2D 地图子系统

2026年7月8日大约 13 分钟

2D 地图子系统

2D 地图（map-2d）是一个搭建型（builder）组件：它本身是画布上的一个容器，内部由若干「图元（piece）」叠加而成。基于 vjmap 内核，同时支持 CAD 工程图与地理底图两种坐标系，并覆盖标绘、聚合、动画、GPU 特效、立体、服务瓦片等全类图层。

在线演示（三种底图形态）

预览使用内置公开演示服务（vjmap 官方示例），联网即可出图；拖拽 / 滚轮缩放真实可用。

① 空白 CAD 图（坐标网格）——不加载图纸，按范围建空白图，适合纯标绘场景：

② 互联网底图（geographic + 高德矢量）：

③ CAD 示例图纸（sys_zp，vjmap 公开演示图）：

结构：本体 + 数据源 + 图层

地图组件的 pieces 按三类排列（同一个 pieces 数组）：

地图本体 map-body：单例、不可删、放第一个，决定坐标系与底图。
数据源 map-source-*：把数据归一化供图层引用（可选；不渲染、不参与选中）。
图层 map-*：真正在地图上出图。叠放顺序 = pieces 数组顺序（靠后在上）。

每个 piece 都是同一种节点：{ uid, type, enabled, options }，enabled 写在节点顶层（与 options 平级），false = 隐藏该图层 / 源。

两种坐标系

坐标系由 map-body 的 coordinate-system 决定，数据源与图层的坐标自动跟随本体，无需各自再选。

坐标系	说明
`cad`（默认）	vjmap 工程图（DWG）。编辑器新建地图默认此模式
`geographic`	互联网经纬度底图（高德 / 天地图 / OSM / 自定义 XYZ）

还能互相叠加：把互联网瓦片叠到 CAD 底图，或把 CAD 叠到互联网底图（见下文叠加配方）。

地图本体 map-body

本体是单例、不可删、无数据绑定。中心 / 缩放 / 朝向 / 俯仰会随用户拖动回写到选项（不入历史）。关键选项：

组	关键 option	说明
视角	`map-center` / `map-zoom` / `map-bearing` / `map-pitch`	中心（地理经纬度 / CAD 的 X,Y）、缩放、旋转角、俯仰角（看立体时用）
底图（地理）	`basemap`	`blank` / `tianditu-vec/img` / `gaode-vec/img` / `osm` / `xyz`；`xyz` 配 `basemap-xyz-url`，天地图配 `tianditu-token`
底图（地理）	`glyphs-url`	文字 / 聚合计数需要字体。留空沿用地图服务自带字体（CAD 模式自带）
CAD 服务	`service-url` / `service-token`	vjmap 服务地址与 token，可继承「项目设置 → 地图」
CAD 服务	`cad-map-mode`	`blank`（空白地图，按 `cad-blank-bounds` 建图）/ `uploaded`（展示已上传 DWG，需 `mapid`）
CAD 服务	`map-open-way`	`raster` 栅格（快）/ `vector` 矢量（可无级缩放）/ `memory` 内存（频繁更新）
控件	`control-scale` / `control-zoom` / `control-compass` / `control-fullscreen` / `control-minimap` …	内置控件，默认全关，各带停靠角 `*-position`
视图	`auto-fit-data` / `perspectives`	数据更新后自动缩放到全部要素；`perspectives` 视角预设（`mapFlyTo` 可按名飞到）
特效	`fx-quality`	全图 GPU 特效质量档：`lite` / `standard` / `cinematic`
图像	`map-images`	图标库：每条 `key` + `url`/`builtin`，图层「图标」按 `key` 引用
格网	`grid-display`	仅 CAD：坐标参考网格 + 坐标标签

数据源（map-source-*）

数据源不渲染，只把不同来源的数据归一化成要素 / 记录供图层引用（图层监听源版本，源刷新即重渲）。5 种（每个源的完整配置与可导入示例见地图数据源）：

type	名称	说明
`map-source-geojson`	GeoJSON 源	本地静态数据：粘贴 / 编辑 FeatureCollection 文本，或对话框随机生成
`map-source-query`	CAD 查询源	从 vjmap CAD 图按图层 / 范围 / 属性查询图形要素
`map-source-dynamic`	动态数据	HTTP GET/POST、轮询、处理脚本、引用工程连接——远程 / 接口 / 实时
`map-source-draw`	图形绘制	地图上交互绘制点 / 线 / 面 → GeoJSON
`map-source-mapcad`	CAD 绘制	vjmapext MapCadLayer 自渲染

发布为项目数据源

GeoJSON / 查询 / 动态源可设 source-publish: true，把源字段并入工程数据树，之后能被任意组件按字段绑定（如「列表绑地图源、点击行定位地图」）。

数据源关键配置

数据源	关键 option
`map-source-geojson`	`geojson-text`（内联 FeatureCollection JSON）
`map-source-query`	`query-condition`（属性条件）/ `query-fields`（返回字段）/ `query-limit`（最多条数）/ `query-include-geom` / `query-bounds` + `query-is-contains`（范围包含）；`service-mode`（`inherit` 继承本体 / `custom` 自填 `service-url` / `service-token` / `mapid`）
`map-source-dynamic`	`req-type`（`GET` / `POST` / `SOURCE` 引用上游源 / `CONNECTION` 引用工程连接）+ `url` / `req-headers` / `req-body`；`from-source-uid` 或 `from-connection-id` + `from-connection-table`；`interval`（轮询秒，0 = 不轮询）；`process-script`（处理脚本）；`use-mock` + `mock-data`
`map-source-draw`	`draw-features`（交互绘制产出的 GeoJSON）
`map-source-mapcad`	`cad-document`（vjmapext MapCadLayer 文档）

发布为项目数据源（GeoJSON / 查询 / 动态源）：source-publish: true + source-publish-name + source-publish-row-limit（默认 500），把源字段并入工程数据树供任意组件绑定。

图层的数据来源

几乎所有标绘 / 特效图层共享一套数据绑定，二选一（data-input）：

bind-fields（默认）：直接绑工程连接三元组。点类绑 marker-lng / marker-lat（各 1）+ marker-name / marker-value（0~1）；线类绑 line-lng / line-lat + line-group（分组连线）/ line-order（组内排序）；飞线绑起讫。
source：引用本图下的某个 map-source-*（data-source-uid），再用 src-* 把源记录字段映射成几何 / 属性（src-lng-field / src-lat-field / src-name-prop / src-value-prop / src-key-field / 线的 src-group/order-field / 飞线的 src-from/to-*）。

所有图层还共享这些通用图层项：

option	说明
`enable-zoom` + `min-zoom` / `max-zoom`	仅在指定缩放区间显示该图层
`feature-panel-uid` + `feature-panel-offset`	点击要素打开一个锚定窗口贴要素显示（窗口内字段用「响应组件筛选」显示该要素数据）
`tooltip-enable` + `tooltip-fields`	悬停命中要素浮层显示字段值
`filter-expr` + `filter-combine`（all/any）	属性过滤 DSL：每行「字段运算符值」，运算符 `== != > >= < <= in !in has !has`
数据驱动样式	任一样式标量（如 `point-color` / `line-width`）可 `-mode` = `const`/`field`/`zoom`，配 `-field` / `*-stops` 按属性或缩放映射

图层目录

各图层的完整样式项以属性面板为准，下表列用途与关键样式；每个图层的用途 / 数据绑定 / 关键参数 / 可导入示例见地图图层。

标绘类（数据 → 几何；点 / 面类可点选，派发 marker-click / region-click）：

type	用途	关键样式
`map-marker`	DOM 标记（灵活，中小数量）	`marker-kind`（pin/dot/自定义 HTML）、`marker-color`、`marker-size`、`marker-label`
`map-circle`	WebGL 圆点（高性能，可聚合）	`point-color`、`point-radius`、`point-stroke-*`、`cluster`
`map-symbol`	WebGL 图标 + 文字（海量点）	`symbol-color`、`symbol-size`(px)、`symbol-label` + `symbol-label-size/-color`、图标引 `map-images`
`map-cluster` / `map-marker-cluster` / `map-symbol-cluster`	圆点 / 标记 / 符号聚合	圆点聚合 `cluster-radius` + `cluster-t1/t2` + `cluster-color-1/2/3`；标记聚合是 `cluster-cell` + `point-`（不是 `marker-`）
`map-polyline` / `map-curve` / `map-arrowline`	折线 / 平滑曲线 / 箭头线	`line-color`、`line-width`、`line-cap/join`、`line-blur`、`line-dasharray`、曲线 `curve-tension` + `curve-segments`、箭头 `arrow-color/-size/-spacing`
`map-flyline`	飞线（起讫 → 弧）	通用 `line-color` / `line-width` / `line-opacity` + `fly-arc`（boolean）
`map-animate-line`	流动线（流光）	`flow-color`、`flow-width`、`flow-dash`、`flow-gap`、`flow-period`(ms)、`base-color`
`map-path-animate`	路径动画（圆点巡游）	`dot-color`、`dot-radius`、`dot-count`、`dot-period`(ms)、`path-color`/`path-width`
`map-symbol-path-animate`	符号沿路径	`arrow-shape`、`arrow-color`、`arrow-size`、`arrow-count`、`move-period`(ms)
`map-polygon` / `map-region` / `map-geojson`	多边形 / 区域填色 / 综合点线面	`fill-color`、`line-color`；区域 `region-color-ramp`、`region-agg`（sum/avg/max/count），数值走 `src-value-prop`
`map-geocircle`	地理圆 / 扇形（真实地理半径）	`geocircle-shape`、`geocircle-radius-mode`(fixed 公里 / value) + `geocircle-radius`/`-radius-factor`、`geocircle-fill-color`/`-fill-opacity`
`map-heatmap`	热力（点密度 + 权重）	`heat-radius`、`heat-intensity`、`heat-color-preset`、`heat-weight-max`
`map-text`	文本标注	`text-content`（name/value/fixed）、`text-size`、`text-color`、`text-halo-*`
`map-fill-extrusion` / `map-bar3d`	立体面 / 三维柱	`extrusion-height-mode` + `extrusion-height`/`-height-factor`、`extrusion-vertical-gradient`；柱 `bar-height-mode` + `bar-height-factor`（需 `map-pitch > 0`）
`map-line-extrusion`	立体线（光墙 / 围栏）	`wall-color`、`wall-height`、`wall-opacity`、`wall-width`（需 `map-pitch > 0`）
`map-animate-fill` / `map-animate-symbol` / `map-fill-extrusion-animate`	呼吸面 / 跳动符号 / 生长立体面	`breath-min/-max/-period`；`bounce-amplitude`/`bounce-period`；`grow-min-height`/`grow-max-height`/`grow-period`
`map-popup` / `map-divoverlay`	信息窗 / DIV 覆盖物	`popup-title-prop`、`overlay-html`（模板 `${字段}`）

没有 animate-speed

animate-speed 只属于三维的 scene3d-line，地图图层里不存在。地图动画各自用 flow-period / dot-period / move-period / breath-period / bounce-period / grow-period（毫秒，越小越快）。

同样不存在的还有 flyline-color/flyline-width（用 line-*）、text-field（用 text-content）、bar-height-field（用 bar-height-mode + src-value-prop）、region-value-prop（用 src-value-prop）、effect-color（用 effect-colors）、symbol-text-field（用 symbol-label）。

设了不存在的 option 不会报错，只是静默不生效——看起来"用法对了但没效果"多半是这个原因。

特效类（vjmapext GPU 渲染，万级不掉帧）：

特效点（11）：map-fx-fire、map-fx-pulse-ring、map-fx-halo、map-fx-radar、map-fx-smoke、map-fx-lightning、map-fx-meteor、map-fx-vortex、map-fx-shield、map-fx-firework、map-fx-crosshair——关键 fx-color / fx-opacity / fx-size。
特效线（5）：map-fx-flowline、map-fx-meteor-line、map-fx-lightning-line、map-fx-arrow-flow、map-fx-dash-flow——关键 fx-line-color / fx-line-width / fx-line-speed。
其它：map-effect-marker（DOM 呼吸光圈）、map-fx-symbol（fx 离屏渲成图标）、map-fx-shadertoy-point / map-fx-shadertoy-line / map-fx-shadertoy-fullscreen（自定义 Shadertoy 着色器：点 / 线 / 全屏）。

服务 / 环境类（多数无业务数据源，直接配 URL / 参数）： map-tile（XYZ 瓦片底图）、map-wms、map-wmts、map-image（四角贴影像）、map-video（四角贴视频）、map-mvt（矢量瓦片）、map-background、map-sky、map-hillshade（山体阴影）、map-canvas、map-svgoverlay。

服务图层与 CAD↔互联网叠加

map-tile 是最简单的 XYZ 底图（tile-url 用 {z}/{x}/{y} 模板）。map-wms / map-wmts 支持两种源：ogc（标准 OGC 服务）与 vjmap（把另一张 vjmap 服务图按坐标系叠加，含 CAD↔互联网互叠）。

代表性配方——把互联网瓦片叠到 CAD 底图（CAD 作底、路网朝上）。三件套：本体 cad-clip-zoom: 8（加深瓦片金字塔）+ 图层 ov-as-base: true（互联网瓦片置于 CAD 线划之下作底）+ 本体 map-bearing（四参数旋转角使路网朝上）：

"pieces": [
  { "type": "map-body", "uid": "map-body", "enabled": true, "options": {
      "coordinate-system": "cad", "cad-map-mode": "uploaded", "mapid": "sys_zp",
      "service-url": "https://vjmap.com/server/api/v1", "service-token": "<token>",
      "cad-clip-zoom": 8, "map-zoom": 8, "map-bearing": -39.39 } },
  { "type": "map-wms", "uid": "layer-wms", "enabled": true, "options": {
      "wms-source-kind": "vjmap", "ov-mode": "param", "ov-as-base": true,
      "ov-maps": { "indexes": ["m0"], "m0": {
        "mapid": "gaode-road", "webtype": "GCJ02",
        "web": "https://webrd0{1-4}.is.autonavi.com/appmaptile?...&x={x}&y={y}&z={z}" } } } }
]

反过来（CAD 叠到互联网底图）用 geographic 底图 + map-wms/map-wmts(vjmap 源) 指向 CAD mapid，ov-mode 取 auto（按 EPSG）或 param（公共点四参数）。叠加对话框选项一般由编辑器「选择叠加图」写入。播放态要在叠加图上点选 CAD 实体时，WMS 图层开 ov-click-pick: true（栅格本身点不中，引擎按四参数反算后查询实体）。

地图控件组件

除本体自带的四角内置控件外，还有一组独立可摆放、可换肤的控件组件（顶层 widget，不在地图 pieces 内），用 target-map 绑定地图（留空 = 关联本页第一个 2D 地图）：

map-control-coordinate（坐标位置）、map-control-scale（比例尺）、map-control-zoom（缩放）、map-control-compass（指南针）、map-control-export（导出图片 / PDF）、map-control-view（视角切换）、map-control-basemap（底图切换）、map-control-cad-layers（CAD 图层）、map-control-layers（图层管理）、map-control-overview（鹰眼）、map-control-measure（测量）、map-control-legend（图例）。

事件交互

触发器（写在 map-2d 自身的 options.interactions；要素类触发器运行态按命中图层分流派发，编辑器里可为每个图层单独配动作）：

触发器	名称	payload（公式 `{:字段}` 可取）
`marker-click`	点击标记时	命中点要素的属性行（如 `{:name}`、`{:value}`）
`region-click`	点击区域时	命中面要素的属性行
`map-select` / `map-unselect`	选中 / 取消选中时	选中项数据
`map-hover`	悬停要素时	悬停要素属性行
`map-click` / `map-dblclick`	点击 / 双击地图时	点击处坐标 + 命中信息
`map-blank-click`	点击空白处时	点击处坐标
`map-contextmenu`	右键地图时	右键处坐标
`map-menu-item`	右键菜单时	菜单项 key + 右键处坐标（按菜单项分目标）
`map-ready`	地图就绪时	无
`map-view-change`	视角变化时	当前相机（center / zoom / bearing / pitch）
`map-source-loaded`	数据源加载完成时	源信息
`map-error`	地图出错时	错误信息
`itemClicked`	点击某项	命中要素属性行（通用图表触发器）

运行态自定义菜单需要 contextmenu-enable: true 且 contextmenu-items 非空（可用数组 [{ label }]，triggerTarget 为 '0'/'1'/…；或编辑器簇带 indexes）。只配 items 不开开关时，底图会吞掉浏览器菜单，看起来像右键没反应。

另有基础触发器 click / mouseEnter / mouseLeave / appear / disappear / receiveBehaviorEvent 与所有组件一致。

动作（17 个，目标 = 地图；列表 / 按钮也可跨调地图）：

分类	动作
视角	`mapFlyTo`（飞到视角 / 经纬度）、`mapFitData`（缩放到数据范围）、`mapFitWhole`（全图）、`mapZoom` / `mapSetZoom`、`mapResetNorth`、`mapOrientation`（旋转 + 俯仰）、`mapPanBy`、`mapStop`
图层 / 源	`mapLayerVisible`（显隐图层）、`mapSourceVisible`（显隐源）、`mapSetLayerStyle`（运行态改图层属性）、`mapRefreshData`、`mapSetSourceData`（注入 GeoJSON）
底图	`mapSwitchBasemap`（切互联网底图）、`mapSwitchMap`（切 CAD 图 `mapid`）
选中	`mapClearSelection`

地图也可被通用 changeOption 直改选项（center / zoom / mapid / basemap / 图层 enabled 等都有实时 watcher）。

工程 JSON 速查

{
  "type": "map-2d", "uid": "w_map",
  "options": { "position": [0,0], "size": [1894,1078], "interactions": { /* 触发器→动作 */ } },
  "pieces": [
    { "type": "map-body", "uid": "map-body", "enabled": true, "options": {
        "coordinate-system": "geographic", "basemap": "gaode-vec",
        "map-center": [116.4,39.9], "map-zoom": 10 } },
    { "type": "map-source-geojson", "uid": "src_geo", "enabled": true,
      "options": { "geojson-text": "{...FeatureCollection...}" } },
    { "type": "map-circle", "uid": "ly_pts", "enabled": true, "options": {
        "data-input": "source",
        "data-source-uid": [{ "refType": "element", "targetPath": ["src_geo"] }],
        "point-color": "#38BDF8" } }
  ]
}

延伸阅读：数据系统（图层字段绑定的连接来源）· 事件交互（interactions 结构）· 窗口系统（要素点击 → 信息窗跟随）· 三维场景与组态 SCADA（另两大搭建型子系统）。