数据图例 map-control-legend

2026年7月20日大约 4 分钟

数据图例 `map-control-legend`

数据图例控件。

类型串：map-control-legend　默认尺寸：[196, 176]　分类：地图控件

实时预览

下面渲染的是真实组件（与编辑器 / 运行时同源）。修改右侧「样式参数」，左侧预览实时更新；点击底部「全页面查看」可放大。

示例把图例切到「色带分段」模式（legend-mode: ramp）：legend-colors 给出低→高五段色带、legend-min/max 定义 0~100 的数值范围、legend-count: 5 等分五档、色块放大到 16px，用来解读右侧泵站圆点的负载数值。legend-mode 换成 manual / size / gradient 可分别得到手动项、气泡分级与连续渐变三种形态。

属性

下表为本组件特有的属性；position / size / opacity / background / border / 联动选中 / 筛选等通用参数见组件手册总览。

basic

属性	名称	类型	默认	说明
`target-map`	关联地图	`element(types=map-2d)`	`[]`
`legend-show-title`	显示标题	`boolean`	`true`
`legend-title`	标题	`string`	`图例`
`legend-mode`	图例类型	`select`	`manual`	可选：`manual` / `ramp` / `size` / `gradient`
`legend-orientation`	排列方向	`select(radioGroup)`	`vertical`	可选：`vertical` / `horizontal`

manual

属性	名称	类型	默认	说明
`legend-items`	图例项	`string(textarea,rows=5)`	`正常 => #36e0ff 预警 => #ffd666 告警 => #ff5b6e 离线 => #6b7a90`
`legend-shape`	符号形状	`select`	`square`	可选：`square` / `circle` / `line`

numeric

属性	名称	类型	默认
`legend-colors`	色带	`colors`	`#1d3b53;#2f6fb0;#3aa1ff;#5ce0d8;#ffd666;#ff7875`
`legend-color`	气泡颜色	`color`	`#36e0ff`
`legend-min`	最小值	`number`	`0`
`legend-max`	最大值	`number`	`100`
`legend-count`	分级数	`number(min=1,max=12)`	`5`
`legend-min-radius`	最小气泡(px)	`number(unit=px,min=1)`	`6`
`legend-max-radius`	最大气泡(px)	`number(unit=px,min=1)`	`20`
`legend-min-label`	低端标签	`string`	—
`legend-max-label`	高端标签	`string`	—

appearance

属性	名称	类型	默认
`panel-bg`	面板背景	`color`	`rgba(9,18,34,0.55)`
`panel-color`	文字色	`color`	`#eaf2ff`
`panel-border-color`	边框色	`color`	`rgba(125,205,255,0.24)`
`panel-radius`	圆角	`number(unit=px,min=0)`	`10`
`panel-font-size`	字号	`number(unit=px,min=8)`	`12`
`legend-swatch-size`	色块尺寸	`number(unit=px,min=6)`	`14`
`accent`	主题色	`color`	`#36e0ff`

数据绑定

无组件特有数据绑定字段（纯样式 / 布局 / 装饰）。

事件

触发器

触发器在预览 / 播放态生效（编辑态点击 = 选中组件）。写在本组件 options.interactions 的 groups[].trigger 里。

触发器	名称	触发时机	payload（供动作公式 `{:字段}` 取值）
`click`	点击	点击本组件时触发	无
`mouseEnter`	鼠标移入	指针移入组件时触发	无
`mouseLeave`	鼠标移出	指针移出组件时触发	无
`appear`	入场	组件出现时触发（配合进场动画）	无
`disappear`	离场	组件消失时触发（配合退场动画）	无
`receiveBehaviorEvent`	接收行为事件	收到 `sendBehaviorEvent` 动作或宿主 `ctx.emit` 投递的事件时触发（按 `eventName` 匹配）	发送方携带的 data

动作

触发器命中后执行的动作。本组件既可发起动作（配在自己的交互里），也可作为其它组件动作的目标。

动作	名称	说明
`changeOption`	修改设置	把本组件（或其它组件）的某个属性改为静态值 / 公式动态值
`switchState`	切换状态	切到多状态里的某个状态（`state:""` 回默认态）
`appear / disappear`	进 / 退场动画	对目标 `opacity` 做 0↔100 插值的显隐动画

完整动作清单（switchScreen / switchWindow / openUrl / sendBehaviorEvent / transfer / executeScript / requestApi 等）与持久化写法见事件交互。

示例

{
  "type": "map-control-legend",
  "uid": "w_map_control_legend",
  "options": {
    "position": [40, 40],
    "size": [196, 176]
  }
}

延伸阅读：组件手册总览 · 数据系统 · 事件交互。