企业官网建设流程全解析

1. 为什么要在 FeatureLayer 上做文本标注

做 GIS 前端开发的朋友大概都遇到过这种需求：地图上加载了一个 FeatureLayer，点要素、线要素、面要素都渲染出来了，但业务方跑过来看一眼就说——“这个地块得把名称标上去”“每个点位旁边要显示编号”“这条管线得把管径写出来”。说白了，就是要在要素图层上叠加文本信息。

ArcGIS for JavaScript 里做标注，路子其实不止一条。最直接的是给图层配labelingInfo，走原生标注引擎；另一条路是用TextSymbol配合Graphic手动往GraphicsLayer里塞文本；还有一条是在FeatureLayer的renderer里用visualVariables或者自定义符号做文章。这几条路各有各的适用场景，选错了轻则性能拉胯，重则标注压根不显示，排查半天找不到原因。

这篇内容就是围绕“在 FeatureLayer 上添加文本信息”这个具体场景展开的。我会把几种主流方案的选型逻辑、参数配置、踩坑记录都摊开讲一遍，重点放在原生labelingInfo方案上，因为这是绝大多数业务场景下的正解。适合已经能跑通基础地图加载、对 FeatureLayer 有基本认知、但一配标注就各种不显示或者样式调不对的开发者参考。纯新手也能看，我会把关键概念用生活化的方式解释清楚。

先说清楚一个前提：ArcGIS for JavaScript 目前主流版本是 4.x，API 设计和 3.x 差异很大，网上搜到的不少老代码是 3.x 的写法，直接抄过来大概率跑不通。下面所有内容默认基于 4.x 版本，涉及具体模块导入的地方会标注清楚。

2. 方案选型：三条路怎么挑

2.1 原生 labelingInfo：首选方案

FeatureLayer自带labelingInfo属性，这是官方提供的标注机制。你只需要定义好标注的字段表达式、文本符号样式、放置规则，剩下的渲染、避让、缩放层级控制，引擎全帮你处理了。

选它的理由很实在：标注和要素是绑定的，要素过滤、缩放、平移的时候标注自动跟着走，不用你手动同步；性能有保障，引擎内部对标注做了空间索引和碰撞检测，要素多了也不会卡成幻灯片；配置化程度高，字体、颜色、描边、偏移、优先级都能通过参数调。

代价是灵活性有边界。比如你想让标注带个复杂的背景框、或者标注内容要根据多个字段做很花哨的拼接逻辑，labelingInfo的表达式能力虽然支持 Arcade，但终归不如自己拼 HTML 来得自由。不过对九成以上的业务需求来说，原生方案够用了。

2.2 GraphicsLayer 手动加 TextSymbol：灵活但费劲

思路很简单：遍历 FeatureLayer 的要素，给每个要素创建一个Graphic，几何用要素的几何，符号用TextSymbol，塞进一个独立的GraphicsLayer。

这条路的好处是完全可控，文本内容想怎么拼怎么拼，样式想怎么调怎么调，甚至可以用TextSymbol配合PointSymbol3D做三维标注。坏处也很明显：要素一多，手动创建的 Graphic 数量爆炸，渲染压力全压在你这边；而且要素和标注是两套东西，图层过滤、缩放显隐的时候你得自己写逻辑同步，维护成本高。

我的建议是：要素数量在几百以内、标注样式有特殊要求（比如要带图标、要分多行不同字号）、或者需要做动态交互（点击标注弹窗）的场景，可以考虑这条路。要素上千的，老老实实走原生方案。

2.3 自定义 renderer 符号：偏门但有用

还有一种思路是在renderer里做文章，比如用UniqueValueRenderer配合不同的TextSymbol，或者用visualVariables控制大小颜色。严格说这不算“文本标注”，更像是用符号表达属性。适合的场景是：你不需要每个要素都显示文本，而是用文本符号本身作为分类表达（比如用“A”“B”“C”三个字母区分三类要素）。

这条路用得少，但在某些极简风格的专题图里挺出彩。下面重点讲前两条，尤其是原生方案。

3. 原生 labelingInfo 的核心配置拆解

3.1 最小可用配置长什么样

先看一段能跑起来的最小代码，基于 4.x 的模块化写法：

import FeatureLayer from "@arcgis/core/layers/FeatureLayer"; const layer = new FeatureLayer({ url: "https://your-server/FeatureServer/0", labelingInfo: [{ labelExpressionInfo: { expression: "$feature.name" }, symbol: { type: "text", color: "white", haloColor: "black", haloSize: 1, font: { size: 12, family: "sans-serif", weight: "bold" } }, labelPlacement: "above-center" }] });

这段配置的意思是：取每个要素的name字段作为标注文本，白色字体带黑色描边，字号 12 加粗，放在要素几何中心的正上方。

几个关键点必须说清楚。labelExpressionInfo.expression里用$feature.字段名引用属性字段，这是 Arcade 表达式的写法。如果你直接写"name"字符串，在某些版本下也能识别为字段名，但为了兼容性和可读性，建议统一用$feature.前缀。symbol的type必须是"text"，这是文本符号的类型标识，漏了或者写错直接不渲染。labelPlacement控制标注相对要素的位置，点要素常用above-center，线要素常用above-along，面要素常用always-horizontal，选错了标注可能跑到要素外面去。

3.2 文本符号的样式参数详解

TextSymbol的样式参数不少，挑最常用的几个讲透。

color是字体颜色，支持十六进制、rgb、rgba 以及颜色数组。这里有个坑：如果你传的是数组形式的颜色（比如[255, 255, 255]），某些版本下透明度通道的处理和字符串形式不一致，建议统一用rgba(255,255,255,1)这种写法，省得排查。

haloColor 和 haloSize是描边，这个强烈建议配上。地图底图颜色复杂的时候，纯色字体很容易和背景糊在一起，加一圈描边能显著提升可读性。haloSize的单位是像素，一般 1 到 2 就够了，太大字会显得糊。

font对象里，size是字号（像素），family是字体族，weight控制粗细（normal/bold），style控制斜体（normal/italic）。字体族建议用系统通用字体，别指定太冷门的字体，否则用户机器上没有会回退成默认字体，排版可能乱。

verticalAlignment 和 horizontalAlignment控制文本在符号锚点上的对齐方式，配合labelPlacement一起用。比如labelPlacement是above-center时，verticalAlignment设成bottom能让文本底部贴着要素顶部，视觉上更紧凑。

3.3 标注放置规则与避让

labelPlacement的取值和要素类型强相关，用错了不报错但效果诡异。整理成表格更直观：

避让这块，引擎默认会做标注之间的碰撞检测，重叠的标注会自动隐藏一部分。控制这个行为的参数是labelingInfo里的deconflictionStrategy，取值"none"表示不避让（所有标注都显示，可能重叠），"static"表示静态避让（默认值，重叠时隐藏优先级低的）。要素密集的场景，建议保持默认的static，再配合minScale和maxScale控制标注的显示层级范围，避免缩得太小时标注糊成一团。

注意：deconflictionStrategy设成"none"在要素密集时会导致标注严重重叠，视觉上非常乱，除非你有明确的业务理由（比如必须保证每个标注都可见），否则别动这个参数。

4. 实操过程：从零配出一个可用的标注图层

4.1 环境准备与图层加载

假设你已经有了一套基于 4.x 的地图应用骨架，Map和MapView都初始化好了。第一步是把 FeatureLayer 加载进来，先不加标注，确认要素能正常渲染。

import Map from "@arcgis/core/Map"; import MapView from "@arcgis/core/MapView"; import FeatureLayer from "@arcgis/core/layers/FeatureLayer"; const map = new Map({ basemap: "gray-vector" }); const view = new MapView({ container: "viewDiv", map: map, center: [116.4, 39.9], zoom: 10 }); const featureLayer = new FeatureLayer({ url: "https://your-server/FeatureServer/0", outFields: ["*"] }); map.add(featureLayer);

这里有个容易被忽略的点：outFields一定要包含你后面标注要用的字段。如果outFields只写了["objectid"]，标注表达式里引用$feature.name会拿不到值，标注就是空的。最省事的写法是["*"]，但要素字段特别多的时候会影响加载性能，生产环境建议按需列出。

4.2 标注表达式的进阶写法

基础的单字段标注上面已经演示过了。实际业务里，标注内容往往需要拼接、格式化、条件判断，这就得靠 Arcade 表达式。

多字段拼接，用+或者字符串模板：

labelExpressionInfo: { expression: "$feature.name + ' (' + $feature.code + ')'" }

数值格式化，比如面积保留两位小数加单位：

labelExpressionInfo: { expression: "Round($feature.area, 2) + ' 平方米'" }

条件判断，不同类型显示不同内容：

labelExpressionInfo: { expression: ` if ($feature.type == 'residential') { return '住宅: ' + $feature.name; } else if ($feature.type == 'commercial') { return '商业: ' + $feature.name; } return $feature.name; ` }

Arcade 表达式支持多行，用反引号包裹，可读性好很多。这里提醒一句：表达式里的字段名必须和outFields里的一致，大小写敏感，写错了不报错但返回空值，排查起来很隐蔽。

4.3 缩放层级控制与性能调优

要素图层要素多的时候，标注全量显示会拖慢渲染。两个参数控制显示范围：minScale和maxScale。注意 ArcGIS 里 scale 的语义是“比例尺分母”，数值越大表示缩得越小（看得越远）。所以minScale是“最小比例尺”，即缩放到比这个值更小（更远）时标注隐藏；maxScale是“最大比例尺”，即放大到比这个值更大（更近）时标注隐藏。

labelingInfo: [{ minScale: 50000, maxScale: 0, labelExpressionInfo: { expression: "$feature.name" }, symbol: { type: "text", color: "white", haloColor: "black", haloSize: 1 } }]

上面这段的意思是：比例尺小于 50000（即缩得比 1:50000 更远）时标注不显示，放大到 1:50000 以内才显示。maxScale: 0表示放大到极限也不隐藏。这个配置的逻辑是：视野范围大的时候要素密集，标注全显示会糊，缩放到一定层级再显示，既保证可读性又省性能。

实测下来，minScale的取值要根据要素密度来定。要素稀疏的图层，minScale可以设大一点（比如 100000），让标注早点出现；要素密集的，设小一点（比如 20000），避免一缩小就满屏标注。

4.4 标注与弹窗、过滤的联动

标注配好之后，业务方往往还会提新需求：点击要素弹窗显示详情、按条件过滤要素、标注内容随过滤动态变化。这些联动逻辑要提前想清楚。

弹窗用popupTemplate，和标注是独立的配置，互不影响：

featureLayer.popupTemplate = { title: "{name}", content: "编号: {code}<br>类型: {type}" };

要素过滤用definitionExpression，过滤后标注会自动跟着变，因为标注是基于要素渲染的：

featureLayer.definitionExpression = "type = 'residential'";

这里有个实操心得：definitionExpression变化后，标注的重新计算是异步的，如果你在过滤后立刻去读标注相关的状态，可能拿到的是旧值。需要监听layerView的updating事件，等更新完成再操作。

5. 常见问题与排查技巧实录

5.1 标注完全不显示

这是最高频的问题，原因通常出在几个地方，按排查优先级列出来：

我踩过最隐蔽的一个坑是：labelingInfo在图层load之前设置，某些情况下会被服务端返回的默认配置覆盖。稳妥的做法是在featureLayer.load()的then回调里再设置labelingInfo，或者用when()确保加载完成。

5.2 标注显示但内容为空

标注框出来了，但里面没字。八成是表达式取值失败。先用最简单的表达式"$feature.objectid"测试，如果能显示，说明标注机制本身没问题，问题出在字段引用上。然后逐步替换成目标字段，定位到具体是哪个字段取不到值。常见原因是字段名大小写不匹配，或者该字段在部分要素上是 null。

5.3 标注重叠严重

要素密集时标注互相压盖，可读性极差。除了前面说的deconflictionStrategy和缩放层级控制，还有几个手段：调整labelPlacement让标注错开（比如交替用above-center和below-center，但这需要多个labelingInfo配置配合where条件）；用labelExpressionInfo里的 Arcade 做内容精简（长文本截断）；或者干脆在低缩放层级只显示关键要素的标注，用definitionExpression配合minScale做分层显示。

5.4 标注样式在移动端显示异常

桌面端调好的字号，到移动端可能显得过大或过小。原因是TextSymbol的size单位是像素，而移动端屏幕像素密度高，同样的像素值视觉大小不同。解决办法是用view.resolution或者view.scale动态计算字号，或者针对移动端单独配一套labelingInfo。实测下来，移动端字号建议比桌面端小 2 到 4 像素，描边haloSize也相应减小。

提示：动态调整标注样式时，直接修改labelingInfo数组里的 symbol 对象后，需要重新赋值layer.labelingInfo = [...]才能触发重绘，原地修改对象属性不一定生效。

5.5 标注性能问题

要素上万、标注全开的时候，地图拖动明显卡顿。除了缩放层级控制，还可以考虑：关闭不必要的描边（haloSize设 0 能省一点渲染开销）；用labelingInfo的where条件只给关键要素加标注；或者用FeatureLayer的labelingInfo配合featureReduction（聚合）减少同时渲染的要素数量。聚合之后标注会显示在聚合点上，需要单独配置聚合的标注表达式。

6. 几个容易被忽略的细节

6.1 标注的 z 轴层级

标注默认渲染在要素之上，但如果你的地图里还有别的 GraphicsLayer 或者弹出窗口，标注可能被遮挡。控制层级用layer.elevationInfo或者调整图层的添加顺序。标注本身没有独立的 z-index 配置，它跟随所属图层的层级。

6.2 多语言与特殊字符

标注内容包含中文、日文等非拉丁字符时，字体族要选支持这些字符的，比如"Microsoft YaHei", "PingFang SC", sans-serif。只写sans-serif在某些系统上可能回退到不支持中文的字体，显示成方块。另外，Arcade 表达式里拼接字符串时，特殊字符（如引号）需要转义，否则表达式解析失败。

6.3 标注与打印、截图

用Print组件或者view.takeScreenshot()导出地图时，标注是否包含取决于导出配置。takeScreenshot默认包含当前视图的所有渲染内容，包括标注；Print组件需要确保labelingInfo在打印服务的支持范围内，某些老版本打印服务对 Arcade 表达式的支持有限，复杂表达式可能打印不出来。这个在项目验收前一定要实测。

6.4 版本差异带来的坑

4.x 的不同小版本之间，labelingInfo的某些参数行为有变化。比如早期版本labelPlacement的取值集合和后期不完全一致，deconflictionStrategy的默认值也调整过。升级 API 版本后，原本正常的标注可能表现异常，建议在package.json里锁定版本号，升级时做回归测试。

7. 我个人的实操体会

配标注这件事，看起来是配置几个参数的小活，实际做下来坑不少。我最大的体会是：先用最小配置跑通，再逐步加复杂度。很多人一上来就把样式、表达式、缩放控制全配齐，结果标注不显示，根本不知道是哪一项出的问题。正确的做法是先配一个最简单的$feature.objectid标注，确认能显示，再换字段、再加样式、再加条件，每改一步看一眼效果，出问题立刻能定位到具体改动。

另一个体会是关于性能的：标注的性能瓶颈往往不在标注本身，而在要素数量。与其在标注配置上抠细节，不如先把要素过滤做好，用definitionExpression和缩放层级把同时渲染的要素数量控制住，标注性能自然就上来了。这个思路在要素上万的业务图层里尤其管用。

最后分享一个小技巧：调试标注表达式的时候，可以临时把symbol.color设成醒目的红色、haloSize设大，这样标注有没有渲染出来一眼就能看到，比盯着地图找白字快得多。调通了再改回正常样式。这个笨办法帮我省了不少排查时间。