map-2d —— 2D 地图（builder 型，vjmap 内核）

地图本体 / 数据源 / 图层目录 / 服务叠加 / 地图控件组件 / 事件交互 / 示例库。 返回目录：index.md；全量选项字典（最权威）：widget-schema.generated.json。

6. map-2d —— 2D 地图（builder 型，vjmap 内核）

• type: map-2d　默认尺寸: [640,420]　默认名: "2D地图"
• 自定义触发器 14 个 + itemClicked：要素类 marker-click（点）/region-click（面）/map-select/map-unselect；交互类 map-blank-click/map-click/map-dblclick/map-hover/map-contextmenu/map-menu-item(右键菜单项)；生命周期类 map-ready/map-view-change(视角变化)/map-source-loaded/map-error。事件挂在 map-2d 自身的 options.interactions 上（不是图层 piece 上）：运行态从地图 widget 读取并按命中图层分流派发（见 §6.8）。
• 自定义动作 17 个（mapFlyTo/mapFitData/mapLayerVisible/… 见 §6.8）；地图也可被通用 changeOption 直改选项（center/zoom/mapid/basemap/图层 enabled 等都有实时 watcher）。
• 结构：map-2d 节点必须有 pieces，按以下三类排列（同一 pieces 数组）：
  1. 地图本体 map-body——单例、不可删、建议 uid:"map-body"、放第一个（§6.1）。
  2. 数据源 map-source-*——不渲染，把数据归一化供图层引用（§6.2，可选）。
  3. 图层 map-*——真正在地图上出图的图元（标绘/特效/服务，§6.4）。

{
  "type": "map-2d", "uid": "w_map",
  "options": { "position": [0,0], "size": [1894,1078], "interactions": { /* §6.8 */ } },
  "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" } }
  ]
}

• 每个 piece 是同一种节点：{ uid, type, enabled, options, stateOverrides? }。enabled 写在节点顶层（与 options 平级，非 option）：false=该图层/源隐藏（图层树灰显）。
• 图层叠放(z-order) = pieces 数组顺序：靠后的图层在上。例外：服务图层开 ov-as-base:true（见 §6.5/6.6）会被移到 CAD 底图之下作背景。
• 坐标系由 map-body 的 coordinate-system 决定：geographic(互联网经纬度底图) / cad(vjmap 工程图)。编辑器新建地图默认 cad。各数据源/图层的坐标自动跟随本体坐标系，无需各自再选。

6.1 piece: map-body（地图本体 / 场景，单例不可删）

• type: map-body（建议 uid:"map-body"），enabled:true，无数据绑定字段。先定 coordinate-system，再按模式填底图(地理)或 CAD 服务。
• 中心/缩放/朝向/俯仰会随用户拖动回写到选项（不入历史）；改这些选项也会 easeTo 应用。

基础（style.base）：

底图（style.basemap，仅 coordinate-system=geographic）：

CAD 服务（style.cad，仅 coordinate-system=cad，对接 vjmap）：

控件（style.controls，默认全关，各控件独立开关+停靠角 *-position：top-left/top-right/bottom-left/bottom-right）： control-scale(比例尺)、control-zoom(缩放按钮)、control-compass(指南针)、control-fullscreen(全屏)、control-mouseposition(坐标位置，配 -digits/-latlng/-zoom)、control-minimap(缩略图鹰眼)、control-draw(CAD 绘图工具栏，配 -theme/-direction/-corner)。

视图/特效/图像/格网：

6.2 数据源 piece（map-source-*，数据驱动图层的推荐方式）

数据源不渲染，只把不同来源的数据归一化成要素/记录供图层引用（图层 watch 源版本，源刷新即重渲）。5 种：

发布为项目数据源（GeoJSON/查询/动态源有）：source-publish:true + source-publish-name + source-publish-row-limit(默认 500)——把源字段并入工程数据树，可被任意组件（含 marker 嵌入窗口里的组件）按字段绑定。发布后产生一条 type:"map-source" 的连接（connUid 形如 __vp_map_<源piece的uid>，表 uid 固定 records），见 §6.9 图层示例。

6.3 图层的数据来源（data-input：字段绑定 / 引用数据源）

几乎所有标绘/特效图层共享这套数据绑定（点/线/面/起讫各有映射子集）：

• data-input：bind-fields(默认，绑工程连接字段) / source(引用本地图下的 map-source-*)。
• data-source-uid：data-input=source 时必填，element 引用形如 [{ "refType": "element", "targetPath": ["源piece的uid"] }]。

A) 字段绑定档（bind-fields）——直接绑工程连接三元组：

未绑定字段时点类回退 marker-points("lng,lat;lng,lat")、线类回退 line-points（演示占位，不参与「数据自适应」）。

B) 数据源档（source）——src-* 把源记录字段映射成几何/属性（源自带几何时坐标字段可留空）：

C) 图层级通用 option（写在图层 options 里；覆盖面按类分组，以 schema 为准）：

DOM 标记 map-marker 的颜色同样支持这套写法（marker-color-mode/marker-color-field/marker-color-stops），但只有 const/field 两档（逐要素建 DOM，无法按缩放实时重算）。marker-kind:'default' 时改的是 vjmap 内置标记那段 SVG 的填充色，pin/dot 改自绘图形色；icon 与自定义 HTML 不吃颜色。

6.4 图层目录（按类别；样式项详见 widget-schema.generated.json）

标绘类（数据 → 几何，支持上面 §6.3 的数据来源与通用项；点/面类可点选、派发 marker-click/region-click）：

特效类（vjmapext fx，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、fx-size-units。
• 特效线(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、fx-line-dash。
• 其它：map-effect-marker(DOM 呼吸光圈等，effect-type/effect-colors(复数，多色用 ; 分隔)/effect-width/effect-height/effect-text+effect-text-field)、map-fx-symbol(fx 离屏渲成 symbol 图标，fx-symbol-preset 取 radarSweep 等 11 种)。

没有 animate-speed 这个 option（它只属于 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）。 写之前对 reference/widget-schema.generated.json 核一遍：设了不存在的路径不会报错，只是静默不生效。

• 着色器图层（自定义 Shadertoy mainImage 片元）：map-fx-shadertoy-point(点)、map-fx-shadertoy-line(线，fx-line-width+st-frag)、map-fx-shadertoy-fullscreen(全屏叠加，默认 fx-bucket:"topmost")——共用 st-frag(GLSL 源)、st-alpha-mode(premul/opaque/additive/luma亮度抠图/colorKey)、st-res(虚拟分辨率)、fx-bucket(绘制层级 above/below/topmost)。

服务/环境类（多数无业务数据源，直接配 URL/参数；详见 §6.5）： map-tile(XYZ 瓦片底图)、map-wms、map-wmts、map-image(四角贴静态影像)、map-video(四角贴视频)、map-mvt(矢量瓦片)、map-background(背景色)、map-sky(天空)、map-hillshade(山体阴影)、map-canvas(自定义 Canvas)、map-svgoverlay(经纬度贴 SVG)。

6.5 服务图层详解：map-tile / map-wms / map-wmts

• map-tile XYZ 栅格底图：tile-url({z}/{x}/{y} 模板)、tile-size(256)、tile-opacity。
• map-wms —— wms-source-kind 二选一（默认 vjmap）：
  • ogc：标准 OGC WMS。wms-url(基址)、wms-layers(LAYERS,逗号分隔)、wms-version(1.3.0/1.1.1)、wms-format(image/png)、wms-transparent。仅地理(Web 墨卡托)底图对齐。
  • vjmap：把另一张 vjmap 服务图按坐标系叠加到当前底图（含把互联网瓦片叠到 CAD）。叠加由对话框「选择叠加图」统一管理并写入隐藏簇 ov-maps（每图：mapid/version/crs/ox/oy/scale/rotate/pts(公共点)/webtype+web(互联网瓦片)）；ov-mode=none/direct(同坐标系)/auto(EPSG+偏移)/param(公共点四参数)/arrange(排列组合·网格平铺，配 ov-arrange-cols)；ov-as-base:true=置于 CAD 底图之下作背景。ov-click-pick:true=播放态点击叠加 CAD 栅格，按与瓦片同一套四参数反算后 pointQueryFeature 高亮实体并触发地图 map-select（对照 vjmap 06wmsselentity；互联网底图需 param 公共点）。
  • 共用显示/影像调节：wms-opacity、wms-tile-size、wms-saturation/wms-hue/wms-brightness/wms-contrast/wms-resampling(linear/nearest)/wms-fade-duration。
• map-wmts —— wmts-source-kind 二选一（默认 vjmap）：
  • ogc：标准 OGC WMTS。wmts-url、wmts-layer、wmts-matrix-set(如 w)、wmts-style(default)、wmts-format、wmts-version(1.0.0)。
  • vjmap：CAD 多图叠加——把多张 vjmap 图(wmts-maps：mapid/version/layernames)各渲成栅格瓦片叠到 CAD 底图。写法二选一：编辑器数组簇 { indexes:["m0"], m0:{ mapid, version, layernames } }，或工程 JSON / playground 数组 [{ mapid, version, layernames }]（运行时都认）。wmts-clip-mode=base(底图投影范围,非侵入；先有底图且坐标不变时本体需 cad-clip-zoom:3，对照 28wmtsztMultimap)/union(叠加图合并范围,会重渲底图并对齐取景)/custom(wmts-clip-bounds)；wmts-vj-dark(深色背景)。
  • 共用显示/影像调节同 WMS（前缀 wmts-）。
• 叠加图的对话框选项（ov-*/wmts-* 隐藏簇）一般由编辑器「选择叠加图」对话框写入，手写时照搬 §6.6 示例结构即可。叠加示例库见 data/地图/叠加/（01~15：WMS/WMTS 排列组合、坐标系自动变化、CAD↔互联网互叠、叠加图上点选 CAD 实体）。

6.6 互联网地图 ↔ CAD 叠加（headline 配方）

把互联网瓦片（高德路网等）叠到 CAD 底图（CAD 作底）：map-body 用 CAD 模式 + 一个 map-wms(vjmap 源) 图层。核心三件套：本体 cad-clip-zoom:8（加深瓦片金字塔）+ 图层 ov-as-base:true（互联网瓦片置于 CAD 线划之下作底）+ 本体 map-bearing（取四参数旋转角使路网朝上）。对照 vjmap demo 05fourparamrotatecad.js：

"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-transparent": 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}",
        "pts": "[{\"x1\":...,\"y1\":...,\"x2\":116.48,\"y2\":39.96}, ...4 点...]" } } } }
]

反过来（CAD 叠到互联网底图）：map-body 用 geographic + 互联网底图，叠加 map-wms/map-wmts(vjmap 源) 指向 CAD mapid，ov-mode:auto(按 EPSG) 或 param(公共点)。完整可导入示例：data/地图/叠加/11-互联网地图旋转叠加至CAD图、12-CAD图旋转叠加至互联网地图、13-多个CAD图旋转叠加、10-互联网地图叠加多张CAD图。

6.7 地图控件组件（map-control-*，独立放置、关联地图）

独立顶层 widget（不在地图 pieces 内），共 12 个；都用 target-map(element，types=map-2d，留空=关联本页第一个 2D 地图) 绑定。外观项按控件形态分两套：面板类控件（coordinate/basemap/cad-layers/layers/overview/measure/legend/view）共享 panel-bg/panel-border-color/panel-radius + 多数带 panel-color/panel-font-size + accent 主题色；按钮/刻度/罗盘类（scale/zoom/compass/export）用自有键（scale-*/btn-*/compass-*，export 用 btn-accent 而非 accent）：

与 map-body 自带的 control-*(内置控件，停靠地图四角) 区别：控件组件是独立可摆放/可换肤的画布元素。示例 data/地图/图层与源/60~64。

6.8 地图事件交互（触发器 → 动作）

• 触发器 14 个（写在 map-2d.options.interactions.groups，按命中图层分流）：要素 marker-click/region-click/map-select/map-unselect；交互 map-blank-click/map-click/map-dblclick/map-hover/map-contextmenu/map-menu-item；生命周期 map-ready/map-view-change/map-source-loaded/map-error；另有通用 itemClicked。要素类 payload 为命中要素的属性行，公式 {:字段} 取值（如 {:name}、{:value}）。
• 动作（17 个，目标元素=地图；列表/按钮等也可跨调地图）：mapFlyTo(飞到视角/经纬度)、mapFitData(缩放到数据范围)、mapFitWhole(缩放到全图)、mapZoom(放大/缩小)、mapSetZoom、mapResetNorth(复位方向)、mapOrientation(旋转+俯仰)、mapPanBy(像素平移)、mapStop(停止动画)、mapLayerVisible(显隐图层,选 layer+mode)、mapSourceVisible(显隐数据源)、mapSwitchBasemap(切互联网底图)、mapSwitchMap(切 CAD 图 mapid)、mapClearSelection(清除选中)、mapRefreshData(刷新数据源)、mapSetLayerStyle(运行态改某图层某属性)、mapSetSourceData(向数据源注入 GeoJSON/触发数据)。
• 运行态右键菜单：contextmenu-enable: true + contextmenu-items（数组 [{ label }] 或编辑器簇 { indexes, [key]: { label } }）+ 触发器 map-menu-item 按项 triggerTarget 分流。只写 items 不开 enable 时，底图会吞掉浏览器菜单、自定义菜单也不弹。
• ⚠️ 交互写成 { version: 2, groups: [...] } 数组、按 trigger 内容匹配（无需键/哈希）。完整写法见 interactions.md。
• ⚠️ mapFlyTo 的 zoom 单给是 no-op：执行顺序为 view(视角名)→use-row-coords 触发行 bbox（fitGeoBBox，zoom 只作 maxZoom）→lng+lat 都解析到才 flyTo。三个定位源都没有时静默 return——只想变 zoom 请用 mapSetZoom/mapZoom。map-ready→mapZoom(mode:'in') zoom 5→6 生效；mapFlyTo({zoom:9}) zoom 停在 5。
• 运行态动作注册表不可达：project/viewer 上都无 actionRegistry/actions 公共入口，动作名只能靠文档核对。
• map-click/map-view-change 程序化可派发：raw.map.fire('click', {lngLat,point})（vjmap 事件系统合成）可派发 map-click 链；flyTo() 程序化移图可派发 map-view-change；容器 DOM dispatchEvent(click) 也走通（经 map 内部 click→地图事件）。要素级 marker-click 仍需真实命中检测，合成事件到不了。
• map-control-* 控件类 piece（map-control-legend/map-control-view 等）不进 listLayers() 且不回显在 raw.pieces——它们由地图内部控件槽位托管，别用 piece 数组回读校验控件存在性。map-* 图层 / 数据源 / 特效类 piece 则会正常回显。
• 二次开发交互绘制（不是交互动作，是 SDK 句柄能力）：ctx.getMap(uid).startDraw({ mode:'polygon', toolbar:['polygon','trash'] }) 开一个 vjmap Draw 会话，在图上画点/线/面并拖顶点编辑，onChange 拿变化后的 GeoJSON。 想让用户「在地图上选坐标 / 画分区边界」时用它，别自己接 map-click 逐点拼几何。详见 platform/sdk.md §4。

6.9 地图示例库（data/地图/图层与源/，全部可导入对照）

• 数据源/图层基础：11 GeoJSON静态源一源驱动点线面、15 五类数据源总览、04 CAD一源三层、05 API-GeoJSON源、08/09 地图源发布、16/17 列表绑地图源点击行定位。
• 单图层全集：19~58 每种图层一个示例（数据源与事件·百分比），13 标绘图层全集、59 特效预设墙。
• 服务/叠加：14 服务瓦片影像图层组、50~57 服务图层、叠加示例/01~15（WMS/WMTS/CAD↔互联网互叠）。
• 控件/样式：60~64 控件组件与内置控件、65/66 数据驱动样式（按属性/按缩放）。
• 生成器：scripts/generate-map-layer-examples.mjs 批量产出单图层示例（CAD 空白 + GeoJSON 源驱动 + 点击事件 + 缩放/显隐/清除按钮，百分比自适应）。

6.10 VP-TSX 写法

pieces 是节点顶层 prop（不是 children）；模块顶层构造时标注 VpMap2dPiece[] 获得编译期选项键/枚举校验（映射总规则见 vptsx.md）：

import { defineProject, h, type VpMap2dPiece } from '<...>/runtime'

const mapPieces: VpMap2dPiece[] = [
  { uid: 'map-body', type: 'map-body', enabled: true, options: { 'coordinate-system': 'geographic', basemap: 'gaode-vec', 'map-center': [116.4, 39.9], 'map-zoom': 10 } },
  { uid: 'src_geo', type: 'map-source-geojson', enabled: true, options: { 'geojson-text': '{...FeatureCollection...}' } },
  { uid: 'ly_pts', type: 'map-circle', enabled: true, options: { 'data-input': 'source', 'data-source-uid': [{ refType: 'element', targetPath: ['src_geo'] }], 'point-color': '#38BDF8' } },
]
// <map-2d uid="w_map" position={[0, 0]} size={[1894, 1078]} pieces={mapPieces}
//   interactions={interactions(on('marker-click', act('mapFlyTo', { … })))} />