符号聚合 map-symbol-cluster

2026年7月20日大约 6 分钟

符号聚合 `map-symbol-cluster`

符号聚合。

放在 map-2d 的 pieces 里；enabled 写在节点顶层。数据来源 data-input：bind-fields（绑工程连接）或 source（引用数据源）。

在线演示

预览使用内置公开演示服务 / 互联网底图，联网即可出图；可拖拽缩放。数据来自内联 GeoJSON 演示源。

属性

属性	名称	类型	默认	说明
`enable-zoom`	限制缩放区间	`boolean`	`false`
`min-zoom`	最小级别	`number(min=0,max=24,step=0.1)`	`0`
`max-zoom`	最大级别	`number(min=0,max=24,step=0.1)`	`24`
`symbol-label-color-mode`	文字颜色·取值	`select(radioGroup)`	`const`	可选：`const` / `field` / `zoom`
`symbol-label-color-field`	文字颜色·字段	`string`	—
`symbol-label-color-stops`	文字颜色·映射	`string(textarea,rows=3)`	—
`symbol-placement`	放置方式	`select`	`point`	可选：`point` / `line` / `line-center`
`symbol-spacing`	沿线间距	`number(min=1,unit=px)`	`250`
`symbol-avoid-edges`	避免跨瓦片边	`boolean`	`false`
`symbol-z-order`	层内顺序	`select`	`auto`	可选：`auto` / `viewport-y` / `source`
`symbol-sort-key`	排序键字段	`string`	—
`text-anchor`	锚定位置	`select`	`top`	可选：`center` / `left` / `right` / `top` / `bottom` / `top-left` / `top-right` / `bottom-left` / `bottom-right`
`text-offset`	锚点偏移(字符)	`string`	—
`text-justify`	对齐	`select`	`center`	可选：`auto` / `left` / `center` / `right`
`text-transform`	大小写	`select`	`none`	可选：`none` / `uppercase` / `lowercase`
`text-rotate`	旋转角度	`number(step=1,unit=°)`	`0`
`text-max-width`	换行宽度(em)	`number(min=0,step=1)`	`10`
`text-letter-spacing`	字间距(em)	`number(step=0.01)`	`0`
`text-line-height`	行高(em)	`number(min=0,step=0.1)`	`1.2`
`text-padding`	碰撞内边距	`number(min=0,unit=px)`	`2`
`text-allow-overlap`	允许重叠	`boolean`	`false`
`text-optional`	冲突时可省略	`boolean`	`true`
`text-rotation-alignment`	旋转对齐	`select`	`auto`	可选：`auto` / `map` / `viewport`
`text-pitch-alignment`	倾斜对齐	`select`	`auto`	可选：`auto` / `map` / `viewport`
`text-opacity`	不透明度	`slider(min=0,max=100,step=1,unit=%)`	`100`
`text-halo-color`	光圈颜色	`color`	`#000000`
`text-halo-width`	光圈宽度	`number(min=0,unit=px)`	`1`
`text-halo-blur`	光圈模糊	`number(min=0,unit=px)`	`0`
`text-translate`	平移	`string`	—
`text-translate-anchor`	平移参考	`select`	`map`	可选：`map` / `viewport`
`icon-anchor`	锚定位置	`select`	`center`	可选：`center` / `left` / `right` / `top` / `bottom` / `top-left` / `top-right` / `bottom-left` / `bottom-right`
`icon-offset`	锚点偏移	`string`	—
`icon-allow-overlap`	允许重叠	`boolean`	`true`
`icon-ignore-placement`	忽略碰撞	`boolean`	`true`
`icon-optional`	冲突时可省略	`boolean`	`false`
`icon-rotation-alignment`	旋转对齐	`select`	`auto`	可选：`auto` / `map` / `viewport`
`icon-pitch-alignment`	倾斜对齐	`select`	`auto`	可选：`auto` / `map` / `viewport`
`icon-keep-upright`	防止颠倒	`boolean`	`false`
`icon-padding`	碰撞内边距	`number(min=0,unit=px)`	`2`
`icon-text-fit`	适应文本	`select`	`none`	可选：`none` / `width` / `height` / `both`
`icon-text-fit-padding`	适应文本内边距	`string`	—
`icon-color`	图标颜色(SDF)	`color`	—
`icon-halo-color`	光圈颜色	`color`	—
`icon-halo-width`	光圈宽度	`number(min=0,unit=px)`	`0`
`icon-halo-blur`	光圈模糊	`number(min=0,unit=px)`	`0`
`icon-translate`	平移	`string`	—
`icon-translate-anchor`	平移参考	`select`	`map`	可选：`map` / `viewport`
`symbol-color`	圆点颜色	`color`	`#3aa1ff`
`symbol-size`	圆点大小	`number(unit=px,min=4)`	`8`
`symbol-stroke-color`	描边颜色	`color`	`#ffffff`
`symbol-label`	显示文字	`boolean`	`false`
`symbol-label-size`	文字大小	`number(unit=px,min=8)`	`12`
`symbol-label-color`	文字颜色	`color`	`#ffffff`
`cluster-radius`	聚合半径	`number(unit=px,min=1)`	`60`
`cluster-max-zoom`	聚合最大级	`number(min=0,max=24)`	`14`
`cluster-color`	簇气泡颜色	`color`	`#3aa1ff`
`cluster-opacity`	簇不透明度	`slider(min=0,max=100,step=1,unit=%)`	`85`
`cluster-stroke-color`	簇描边色	`color`	`#ffffff`
`cluster-stroke-width`	簇描边宽	`number(unit=px,min=0,step=0.5)`	`2`
`cluster-count-size`	计数字号	`number(unit=px,min=8)`	`12`
`cluster-count-color`	计数颜色	`color`	`#ffffff`
`symbol-icon`	图标图片	`map-icon`	—
`icon-size`	图标缩放	`number(min=0,step=0.1)`	`1`
`icon-rotate`	旋转角度	`number(step=1,unit=°)`	`0`
`icon-opacity`	不透明度	`slider(min=0,max=100,step=1,unit=%)`	`100`
`row-row-filter-mode-id`	选择数据规则	`select(condition)`	—
`filter-expr`	过滤条件	`string(textarea,rows=4)`	—
`filter-combine`	组合方式	`select(radioGroup)`	`all`	可选：`all` / `any`
`tooltip-enable`	启用悬停提示	`boolean`	`false`
`tooltip-fields`	显示字段	`string`	—
`tooltip-title-field`	标题字段	`string`	—
`feature-panel-uid`	点击弹出画面	`window`	`[]`
`feature-panel-offset`	弹窗偏移(px)	`vector<水平,垂直>`	`[0,0]`
`data-input`	来源方式	`select(radioGroup)`	`bind-fields`	可选：`bind-fields` / `source`
`data-source-uid`	选择数据源	`map-source`	`[]`
`src-lng-field`	经度/X 字段	`string`	—
`src-lat-field`	纬度/Y 字段	`string`	—
`src-name-prop`	名称属性	`string`	—
`src-value-prop`	数值属性	`string`	—
`src-key-field`	唯一键字段	`string`	—
`marker-lng`	经度/横坐标	`field(recommend=number,min=1,max=1)`	—
`marker-lat`	纬度/纵坐标	`field(recommend=number,min=1,max=1)`	—
`marker-name`	名称	`field(min=0,max=1)`	—
`marker-value`	数值	`field(recommend=number,min=0,max=1)`	—
`marker-points`	坐标点	`string`	`0,0;10,0;-10,5;20,-10`

数据绑定（bind-fields 档）

字段槽	类型 / 约束	说明
`marker-lng`	`field(recommend=number,min=1,max=1)`	经度/横坐标
`marker-lat`	`field(recommend=number,min=1,max=1)`	纬度/纵坐标
`marker-name`	`field(min=0,max=1)`	名称
`marker-value`	`field(recommend=number,min=0,max=1)`	数值

事件

触发器	名称	配在哪	payload
`marker-click`	点击点要素	`map-2d` 组件的 `options.interactions`（运行态按命中图层分流）	命中要素属性行，公式 `{:name}` / `{:value}` 取值
`region-click`	点击面要素	同上	同上
`map-select` / `map-unselect`	选中 / 取消	同上	选中项数据

事件写在地图组件上而非图层上。图层还支持 feature-panel-uid（点击要素弹锚定窗口）与 tooltip-enable（悬停浮层），见属性表。动作端可用 mapLayerVisible / mapSetLayerStyle / mapRefreshData 等 17 个地图动作，见 2D 地图 · 事件。

示例

{
  "type": "map-symbol-cluster",
  "uid": "ly_x",
  "enabled": true,
  "options": {
    "data-input": "source",
    "data-source-uid": [{ "refType": "element", "targetPath": ["src_x"] }]
  }
}

延伸阅读：2D 地图子系统 · 地图数据源 · 地图图层总览。