标注

字数统计: 36.9k 字
阅读时长: 约 143 分钟
当前版本: 4.29

标注有助于标识要素，建立要素的视觉层次结构，并将用户的注意力集中在地图上。标注选项和功能（如标注放置和可用字体）因图层类型、几何类型和视图类型（2D 或 3D）而异。

本指南将介绍基于不同属性和字体出现的可能的标注场景。常见问题解答包含有用工作流的信息以及常见问题解答。我们也会探讨相邻标注用例，例如如何使用 symbolUtils.renderPreviewHTML 进行TextSymbol 和 TextSymbol3DLayer 中的文本文本符号预览，以及在打印中它们的注意事项。

2D MapView 标注 ​

在 2D MapViews 中，FeatureLayer、CSVLayer、GeoJSONLayer、StreamLayer、OGCFeatureLayer 和 WFSLayer 均支持标注。labelingInfo 属性被指定为 LabelClass 对象数组，其中包含 labelExpressionInfo、labelPlacement 和 TextSymbol。TextSymbol 类支持更改标注图形的 color、font、halo 和其他属性。点、折线和面均支持标注。

js
    const labelClass = { // autocasts as new LabelClass()
        symbol: {
            type: "text", // autocasts as new TextSymbol()
            color: "white",
            haloColor: "blue",
            haloSize: 1,
            font: { // autocast as new Font()
                family: "Noto Sans",
                size: 14
            }
        },
        labelPlacement: "above-right",
        labelExpressionInfo: {
            expression: "$feature.Team + TextFormatting.NewLine + $feature.Division"
        },
        maxScale: 0,
        minScale: 25000000,
        where: "Conference = 'AFC'"
    };

    const labelLayer = new FeatureLayer({
        portalItem: { // autocasts as new PortalItem()
            id: "7f0bfc7bf67a407d8efebf584f6d956d"
        },
        labelingInfo: [labelClass]
    });

3D SceneView 标注 ​

所有具有 labelingInfo 属性的图层类型 (例如 FeatureLayer 和 SceneLayer) 均支持标注。此属性被指定为 LabelClass 对象数组，其中包含 labelExpressionInfo、labelPlacement 和 TextSymbol3DLayer。TextSymbol3DLayer 类支持更改标注图形的 material、font、halo 和其他属性。

js
    const labelClass = { // autocasts as new LabelClass()
        symbol: {
            type: "label-3d", // autocasts as new LabelSymbol3D()
            symbolLayers: [{
                type: "text", // autocasts as new TextSymbol3DLayer()
                material: {
                    color: "purple"
                },
                font: { // autocasts as new Font()
                    family: "Just Another Hand",
                    weight: bold
                },
                size: 22
            }]
        },
        labelPlacement: "below-center",
        labelExpressionInfo: {
            expression: 'DefaultValue($feature.CITY_NAME, "no data")'
        }
    };

    const labelLayer = new FeatureLayer({
        url: “url”,
        labelingInfo: [labelClass]
    });

已知限制 (SceneView)

字体 ​

通常，我们不需要知道字体文件的存放位置或文件类型。但是，如果使用自定义字体或在断开连接的环境中工作，则需要了解这部分内容。目前提供了多种字体获取方式：

  • 使用 https://doc.geoscene.cn/resources/fonts 的 pbf 文件
  • 使用 https://doc.geoscene.cn/resources/fonts/woff2 的 woff2 文件
  • 从服务器引用 pbf、otf、ttf、woff 或 woff2 格式文件
  • 使用用户计算机和 web 浏览器上的字体

MapImageLayer 字体 ​

MapImageLayer 字体来自 web 浏览器或用户计算机。 通过在 Sublayer 类上设置 labelingInfo 属性，MapImageLayer 可支持标注。labelingInfo 属性被指定为 LabelClass 对象数组，其中包含 labelExpression、labelPlacement 和 TextSymbol。TextSymbol 类支持更改标注图形的 color、font、halo 和其他属性。点、折线和面均支持标注。 MapView 中 MapImageLayers 支持的字体系列取决于发布图层的 GeoScene Server服务器上的字体。2D MapViews 和 3D SceneViews 也是如此。要检查 GeoScene Server 上的可用字体，请运行 Home > services > System > PublishingTools (GPServer) 下的 Available Fonts (需要管理员权限)。如果添加新字体，该字体必须安装在您的计算机上，并可通过 GeoScene Desktop 注册它来访问 GeoScene Server。如果应用程序使用了未安装的字体，则 Font 类将实现一个回退机制，该机制将使用默认字体系列值，即 sans-serif。

非 MapImageLayer 字体 ​

对 Font.family、Font.style 和 Font.weight 属性的支持基于字体文件。我们在 https://doc.geoscene.cn/resources/fonts 上托管了许多字体，可以方便地访问这些字体以进行标注。 如果 Font 不可用，则将使用默认字体系列 sans-serif。具有粗体或斜体的字体需要在 Font.style 和 Font.weight 属性中设置，而不是在 Font.family 中进行设置。要查看字体所支持的字符类型 (例如 Latin、Cyrillic、CJKV)，可在 Microsoft Typography 中搜索字体名称。

可进行标注的非 MapImageLayer 图层：

CSVLayer、FeatureLayer、GeoJSONLayer、OGCFeatureLayer、StreamLayer、WFSLayer。

当前托管在 https://doc.geoscene.cn/resources/fonts 中的字体列表使用 pbf、woff2、ttf 格式 (目前，Palatino Linotype Regular 仅在 pbf 中可用)：

字体预览代码
Abril Fatface Regular
Alegreya Bold
Alegreya Bold Italic
Alegreya Italic
Alegreya Regular
Alegreya SC Bold
Alegreya SC Italic
Alegreya SC Regular
Alegreya Sans Italic
Amarante Regular
Amatic SC Bold
Arial Bold
Arial Bold Italic
Arial Italic
Arial Regular
Arial Unicode MS Bold
Arial Unicode MS Regular
Atomic Age Regular
Audiowide Regular
Avenir Next LT Pro Bold
Avenir Next LT Pro Bold Italic
Avenir Next LT Pro Demi Italic
Avenir Next LT Pro Italic
Avenir Next LT Pro Light
Avenir Next LT Pro Light Italic
Avenir Next LT Pro Medium Bold
Avenir Next LT Pro Medium Bold Italic
Avenir Next LT Pro Regular
Avenir Next LT Pro Regular Bold
BellTopo Sans Bold
BellTopo Sans Bold Italic
BellTopo Sans Italic
BellTopo Sans Regular
Belleza Regular
Black Ops One Regular
Cabin Sketch Bold
Cabin Sketch Regular
Coming Soon Regular
FGDC GeoAge Regular
Homemade Apple Regular
IM FELL DW Pica PRO Italic
IM FELL DW Pica PRO Regular
Josefin Sans Regular
Josefin Sans Semibold Italic
Josefin Slab Bold
Josefin Slab Bold Italic
Josefin Slab Italic
Josefin Slab Light Italic
Josefin Slab Regular
Josefin Slab Thin Italic
Just Another Hand Regular
Kranky Regular
Life Savers Bold
Loved by the King Regular
Merriweather Bold
Merriweather Bold Italic
Merriweather Italic
Merriweather Regular
Montserrat Bold
Montserrat Italic
Montserrat Medium Italic
Montserrat Regular
Montserrat Semibold Italic
Noto Sans Bold
Noto Sans Bold Italic
Noto Sans Italic
Noto Sans Regular
Noto Serif Bold
Noto Serif Bold Italic
Noto Serif Italic
Noto Serif Regular
Old Standard TT Bold
Old Standard TT Italic
Old Standard TT Regular
Orbitron Bold
Orbitron Regular
Oregano Italic
Oregano Regular
Oswald Bold
Oswald Regular
Pacifico Regular
Palatino Linotype Regular
Playfair Display Black
Playfair Display Bold
Playfair Display Bold Italic
Playfair Display Italic
Playfair Display Regular
Playfair Display SC Bold
Playfair Display SC Regular
Redressed Regular
Risque Regular
Roboto Bold
Roboto Bold Italic
Roboto Condensed Italic
Roboto Condensed Light Italic
Roboto Italic
Roboto Regular
Rye Regular
Special Elite Regular
Syncopate Bold
Syncopate Regular
Tangerine Regular
Ubuntu Bold
Ubuntu Bold Italic
Ubuntu Condensed Regular
Ubuntu Italic
Ubuntu Light
Ubuntu Light Bold
Ubuntu Light Bold Italic
Ubuntu Light Italic
Ubuntu Medium Italic
Ubuntu Mono Bold
Ubuntu Mono Bold Italic
Ubuntu Mono Italic
Ubuntu Mono Regular
Ubuntu Regular
UnifrakturCook Bold
Vast Shadow Regular
Walter Turncoat Regular
方正舒体
方正姚体
微软雅黑
微软雅黑 Bold
微软雅黑 Light
黑体
仿宋
楷体
宋体
华文彩云
华文仿宋
华文琥珀
华文楷体
华文隶书
华文宋体
华文细黑
华文行楷
华文新魏
华文中宋

SceneView 字体 ​

3D SceneViews 支持的字体系列取决于 (按优先级顺序)：安装在用户计算机和 Web 浏览器上的字体，然后是 https://doc.geoscene.cn/resources/fonts/woff2 中的字体或从服务器引用的字体。如果应用程序使用了未安装在用户计算机和 web 浏览器上的字体，则应用程序将搜索托管字体。如果字体不可用，则 Font 类将实现一个回退机制，该机制将使用默认字体系列值，即 sans-serif。有关如何在 Windows 或 Mac 上安装新字体的说明，请参阅这些参考资料。

注意，这些字体也适用于 TextSymbol3DLayer，无论是将其用作 3D SceneView 中的图形还是用作标注。

本地未安装的字体也可通过在 css 文件中定义 @font-face 来从 url 加载。

js
    @font-face {
        font-family: "MyFont";
        font-style: normal;
        font-weight: 400;
        font-display: auto;
        src: url("./my-font.ttf") format("truetype");
    }

并从符号图层的 Font.family 属性中引用它：

js
    const labelSymbol = {
        type: "label-3d", // autocasts as new LabelSymbol3D
        symbolLayers: [
            {
                type: "text", // autocasts as new TextSymbol3DLayer()
                material: {
                    color: [0, 0, 0, 0.8]
                },
                font: {
                    size: 30,
                    family: "MyFont"
                }
            }
        ]
    }

默认情况下，字体也可从 https://doc.geoscene.cn/resources/fonts/woff2 进行引用：

js
    const labelClass = { // autocasts as new LabelClass()
        symbol: {
            type: "label-3d", // autocasts as new LabelSymbol3D()
            symbolLayers: [{
                type: "text", // autocasts as new TextSymbol3DLayer()
                material: {
                    color: "black"
                },
                halo: {
                    color: [255, 255, 255, 0.7],
                    size: 2
                },
                font: {
                    family: "Noto Sans"
                },
                size: 10
            }]
        },
        labelPlacement: "above-right",
        labelExpressionInfo: {
            expression: `$feature.NAME + TextFormatting.NewLine + Text($feature.HOEHE, "#,### m")`
        }
    };

    const labelLayer = new FeatureLayer({
        url: "url",
        elevationInfo: {
            mode: "relative-to-ground"
        },
        labelingInfo: [labelClass]
    });

自定义字体和断开连接的环境 ​

在 2D MapViews 中，对于所有非 MapImageLayer 图层和 TextSymbol，使用的字体文件为 pbf，对于 renderPreviewHTML，使用的是 woff2。 在 3D SceneViews 中，对于所有非 MapImageLayer 图层和 TextSymbol3DLayer，使用的字体文件为 ttf、otf、woff 或 woff2 格式，对于 renderPreviewHTML，使用的是 woff2。此外，对于 3D SceneViews，字体文件来自 https://doc.geoscene.cn/resources/fonts，且仅使用 woff2 格式。 默认情况下，可用字体大多与 GeoScene 矢量底图使用的字体相同。 这些字体可通过 https://doc.geoscene.cn/resources/fonts 获得。应用程序需要访问该 URL 才能渲染标注。如果此 URL 不可访问 (例如，断开网络连接或在离线环境中)，或者使用的字体未托管在其中，则可通过设置 geosceneConfig.fontsUrl 属性将 fontsUrl 配置为指向您自己的字体文件。这些字体文件必须是正确的文件类型才能显示。请参考下表，查看所需的字体文件类型，具体取决于所使用的类以及是在 2D 还是 3D 环境中工作。

视图应用于字体源
2D & 3DMapImageLayer用户的计算机和 web 浏览器 (ttf、otf、woff 或 woff2 格式)
2D & 3DrenderPreviewHTMLhttps://doc.geoscene.cn/resources/fonts/woff2 (woff2 格式) 托管在服务器上 (woff2 格式)
2D MapView非 MapImageLayerhttps://doc.geoscene.cn/resources/fonts (pbf 格式) 托管在服务器上 (pbf 格式)
3D SceneView非 MapImageLayer用户的计算机和 web 浏览器 https://doc.geoscene.cn/resources/fonts/woff2 (woff2 格式) 引用自服务器 (ttf、otf、woff 或 woff2 格式)
js
    geosceneConfig.fontsUrl = "https://myserver.com/fonts"; // reference fonts from a server in `pbf`

    const labelClass = { // autocasts as new LabelClass()
        symbol: {
            type: "text", // autocasts as new TextSymbol()
            color: "white",
            haloColor: "blue",
            haloSize: 1,
            font: { // autocast as new Font()
                family: "Wes Welker",
                size: 83
            }
        },
        labelPlacement: "above-right",
        labelExpressionInfo: {
            expression: "$feature.Team + TextFormatting.NewLine + $feature.Division"
        },
        maxScale: 0,
        minScale: 25000000,
        where: "Conference = 'AFC'"
    };

    const labelLayer = new FeatureLayer({
        portalItem: { // autocasts as new PortalItem()
            id: "7f0bfc7bf67a407d8efebf584f6d956d"
        },
        labelingInfo: [labelClass]
    });

备选标注方案 ​

此外，本指南页面将探讨相邻标注用例。标注工作流不会以标注图层结束。还有其他标注要素的方法，以及这些标注要素的其他应用程序注意事项。

TextSymbol 和 TextSymbol3DLayer ​

TextSymbol 和 TextSymbol3DLayer 都是典型标注工作流的一部分，也可用于其他标注体验。这些符号本身可以用作单独的标注，标注的字体和文本表示可视化。 以下是使用格式化文本将 TextSymbol 添加到 2D MapView 的示例：

js
    const textSymbol = {
        type: "text", // autocasts as new TextSymbol()
        color: "blue",
        haloColor: "red",
        haloSize: "1px",
        text: "Wish you were here",
        xoffset: 3,
        yoffset: 3,
        font: { // autocasts as new Font()
            size: 12,
            family: "Orbitron",
            weight: "bold"
        }
    };

    const point = {
        type: "point", // autocasts as new Point()
        longitude: -71.26,
        latitude: 42.09
    };

    const pointGraphic = new Graphic({
        geometry: point,
        symbol: textSymbol
    });

    view.graphics.add(pointGraphic);

以下是使用格式化文本将 TextSymbol3DLayer 添加到 3D SceneView 的示例：

js
    const textSymbol3D = {
        type: "point-3d", // autocasts as new PointSymbol3D()
        symbolLayers: [{
            type: "text", // autocasts as new TextSymbol3DLayer()
            font: { // autocasts as new Font()
                size: 12,
                family: "Just Another Hand"
            },
            text: "Wish I was here",
            material: {
                color: "green"
            },
            size: 12
        }]
    };

    const point = {
        type: "point", // autocasts as new Point()
        longitude: -71.26,
        latitude: 42.09
    };

    const pointGraphic3D = new Graphic({
        geometry: point,
        symbol: threeDpoint
    });

    view.graphics.add(pointGraphic3D);

renderPreviewHTML ​

symbolUtils 类用于生成符号的较小预览图像。当工作流需要显示符号 (用于表示图层中要素) 的较小预览时，此实用程序非常有用。renderPreviewHTML() 方法可生成给定符号的预览图像，该图像可以显示在自定义微件或其他 DOM 元素中，包括标注。此标注的字体文件 (woff2 格式) 来自我们的托管字体文件，或者托管在服务器上 (如果通过 geosceneConfig.fontsUrl 使用不同的源)。

打印 ​

打印带有标注的地图时，需要注意以下几点 (当前仅 2D MapViews 中支持打印)。当前不支持在旋转地图时打印旋转标注。 打印服务必须能够访问字体文件的源，标注才能显示在打印的地图中，因此，如果文件托管在专用服务器上，则打印服务也必须能够访问该专用服务器。

常见问题解答 ​

此常见问题解答包含有关有用工作流的信息以及常见问题的答案！

如何在标注中创建新行？ ​

可以使用模板文字 将标注分隔为多行。此处，MARKER_ACTIVITY 将在第一行上，RECAREANAM 将在新的行上。示例：

js
    // template literal
    "$feature.MARKER_ACTIVITY + '\\n' + $feature.RECAREANAM"

    // TextFormatting.NewLine
    "$feature.MARKER_ACTIVITY + TextFormatting.NewLine + $feature.RECAREANAM"