地图控件组件

2026年7月20日大约 4 分钟

地图控件组件

一组独立可摆放、可换肤的 2D 地图辅助控件（顶层 widget，不在地图 pieces 内）。与 2D 地图本体自带的四角内置控件相比，它们是画布上的独立画布元素，可自由摆放、单独调样式主题。

通用绑定与样式

关联地图：每个控件都有 target-map（element, types=map-2d，留空 = 关联本页第一个 2D 地图）。
通用样式：accent（主题色）、panel-bg / panel-color / panel-border-color / panel-radius / panel-font-size（面板底色 / 文字 / 边框 / 圆角 / 字号）。

下面每个控件只列其特有功能参数。

在线演示

一个空白 CAD 网格地图 + 三个独立控件（缩放 / 指南针 / 比例尺）摆在画布旁：target-map 全部留空即自动关联本页第一个 2D 地图。点缩放按钮 / 拖动地图，控件读数实时联动。

参数：coord-track（mouse 跟随鼠标 / center 取中心）、coord-digits（小数位数）、coord-layout（column / row）、coord-show-projected（投影 X/Y）、coord-show-lnglat（经纬度）、coord-show-zoom / coord-show-bearing / coord-show-pitch（缩放 / 方位 / 俯仰）。

缩放控件 `map-control-zoom`

放大 / 缩小按钮。默认尺寸 [34, 99]。

参数：zoom-step（每次缩放级数）、zoom-orientation（vertical / horizontal）、zoom-show-level（显示缩放级别）、zoom-show-home（复位按钮）、btn-size / btn-gap / btn-radius（按钮样式）。

指南针 `map-control-compass`

方位盘，点击复位正北。默认尺寸 [64, 64]。

参数：compass-show-pitch（俯仰倾斜）、compass-show-label（显示角度）、compass-reset-on-click（点击复位）、compass-north-color / compass-south-color（指北 / 指南色）。

比例尺 `map-control-scale`

默认尺寸 [120, 32]。

参数：scale-unit（metric / imperial / nautical）、scale-max-width（最大宽度）、scale-tick（两端刻度）、scale-color / scale-text-color / scale-line-width。

导出 `map-control-export`

导出地图为图片 / PDF。默认尺寸 [220, 40]。

参数：show-image / show-pdf（按钮显隐）、image-label / pdf-label（按钮文字）、img-range（view 视野 / data 数据范围 / select 框选）、img-width / img-transparent / img-bg（图片导出）、pdf-preset（A0~A5 / Letter / Tabloid / custom）+ pdf-orientation / pdf-custom-w / pdf-custom-h / pdf-geom-dpi / pdf-color-dpi（PDF 导出）。

视角 + 全屏 `map-control-view`

俯仰 / 旋转 / 正北 / 复位 / 全屏一体控件。默认尺寸 [248, 46]。

参数：view-show-pitch + view-pitch-max（俯仰滑杆）、view-show-rotate（旋转微调）、view-show-north（正北按钮）、view-show-reset（复位全图）、view-show-fullscreen（全屏按钮）、view-layout（排列方向）。

底图切换 `map-control-basemap`

切换互联网底图。默认尺寸 [232, 150]。

参数：basemap-layout（grid / segmented / list / dropdown）、basemap-columns（每行列数）、basemap-allowed（可选底图列表）、basemap-default（默认底图）、basemap-show-title + basemap-title、basemap-xyz-url / basemap-tianditu-token。

CAD 图层 `map-control-cad-layers`

控制 CAD 图纸的图层显隐。默认尺寸 [240, 320]。

参数：cad-title、cad-show-search（搜索框）、cad-show-toolbar（全选 / 反选）、cad-default-all（默认全部可见）、cad-dark（深色底图）。

图层管理 `map-control-layers`

管理数据图层与数据源（显隐 / 层级 / 属性编辑）。默认尺寸 [264, 356]。

参数：layers-title、layers-show-sources（数据源区）、layers-allow-edit（属性编辑）、layers-allow-reorder（调整层级）、props-scope（style / style+data）、props-panel-side / props-panel-width（属性面板位置 / 宽度）、props-search。

鹰眼 `map-control-overview`

缩略概览图 + 视口框。默认尺寸 [220, 160]。

参数：overview-click-nav（拖动回中）、overview-show-cross（中心十字）、overview-allow-zoom（滚轮缩放）、overview-margin（概览缩小级数）、rect-color / rect-fill / overview-line-width（视口框样式）。

测量工具 `map-control-measure`

测距 / 测面。默认尺寸 [232, 132]。

参数：measure-mode（distance 测距 / area 测面）、measure-distance-unit / measure-area-unit（地理单位）、measure-unit-label（CAD 单位名）、measure-compact（精简形态）、measure-line-color / measure-fill-color / measure-point-radius（量算样式）。

数据图例 `map-control-legend`

展示图层配色 / 分级图例。默认尺寸 [196, 176]。

参数：legend-show-title + legend-title、legend-mode（manual 手动 / ramp 分级 / size 气泡大小 / gradient 渐变）、legend-orientation、legend-items（手动项，每行 标签 => 颜色）、legend-shape（square / circle / line）、legend-colors（色带）、legend-min / legend-max / legend-count（分级）、legend-min-radius / legend-max-radius（气泡范围）。

示例

// 独立摆放一个缩放控件，关联本页第一个 2D 地图（target-map 留空）
{ "type": "map-control-zoom", "uid": "w_zoom", "options": {
  "position": [24, 24], "size": [34, 99], "zoom-show-level": true } }

// 关联指定地图
{ "type": "map-control-legend", "uid": "w_legend", "options": {
  "position": [24, 140], "size": [196, 176],
  "target-map": [{ "refType": "element", "targetPath": ["screen_main", "w_map"] }],
  "legend-mode": "manual" } }

延伸阅读：2D 地图子系统（地图本体、图层、内置控件与叠加）· 组件手册总览 · 事件交互（控件驱动地图视角 / 图层动作）。