# 组件参考索引（widget / piece 选项与数据绑定）

按组件家族分文件：先在下表命中家族，**只读对应文档**，不要整目录通读。每个组件条目给出 `type`、用途、关键 `options`（名/类型/默认）与**数据绑定字段**。

- 完整且永不过时的全量选项字典见 [widget-schema.generated.json](../widget-schema.generated.json)（脚本从源码 `defineOptions()` 自动导出）——**选项名拿不准以它为准**，本目录是人读向导，只列高频项。
- 字段绑定值形态：`[[connUid, tableUid, fieldUid], ...]`。约束 `min/max` 指可绑字段个数；`recommend` 指推荐字段类型。
- ⚠️ 同一组件一起取数的绑定字段必须同表（tableUid 一致），混表静默无数据，见 [data.md](../data.md) §3。

## 家族路由表

| 家族 | 文档 | 覆盖 type |
|---|---|---|
| 基类通用选项 + 默认名 | [base-options.md](base-options.md) | 所有组件继承：`position`/`size`/边框背景/联动选中开关/内部布局(`container-layout`)/悬浮弹层(`hover-popup-*`) |
| 数据交互 | [data-interactions.md](data-interactions.md) | `filter` 筛选 / `select-sync`·`cross-filter` 选中联动 / `dynamic-prop-fields` 动态数据项 / `conditionalStyles` 条件样式 / `prop-source` 属性数据源 |
| 文本 | [text.md](text.md) | `basic-text` `basic-markdown` `basic-paragraph` |
| 图表（18 种） | [charts.md](charts.md) | `chart-bar` `chart-line` `chart-area` `chart-biaxial(-stack)` `chart-pie` `chart-scatter` `chart-radar` `chart-funnel` `chart-gauge` `chart-heatmap` `chart-treemap` `chart-sankey` `chart-graph` `chart-liquid` `chart-wordcloud` `chart-capsule` `chart-map` |
| 表格（3 种） | [tables.md](tables.md) | `basic-table` `basic-scroll-board` `basic-ranking-list` |
| 容器与复用 | [containers.md](containers.md) | `group-panel` `data-repeater` `component-instance` `layout-section` `nav-views` `window-instance` |
| 控件（11 种） | [controls.md](controls.md) | `basic-button` `basic-switch` `basic-search` `basic-select` `basic-pagination` `basic-list` `basic-progress` `basic-iframe` `group-popup` `group-tabs` `group-buttons` |
| 媒体（4 种） | [media.md](media.md) | `basic-image` `basic-graphical` `basic-carousel` `basic-video` |
| 时间（5 种） | [time.md](time.md) | `basic-timer` `basic-timing` `basic-calendar` `basic-timeselect` `basic-timescale` |
| 指标与装饰（6 种） | [indicators.md](indicators.md) | `basic-card` `basic-flipper` `basic-icon` `deco-border` `deco-decoration` `deco-pipeline` |
| 布局控件（9 种） | [layouts.md](layouts.md) | `layout-row` `layout-column` `layout-grid` `layout-flow-row` `layout-fixed-panel` `layout-dock` `layout-sidebar` `layout-accordion` `placeholder` |
| 2D 地图 | [map-2d.md](map-2d.md) | `map-2d` + piece：`map-body` / `map-source-*`(5) / 标绘·特效·服务图层 `map-*`；独立控件 `map-control-*`(12) |
| 组态 | [scada-2d.md](scada-2d.md) | `scada-2d` + piece：`scada-node`(159 种形状，含 `image`+`sprite-*`) `scada-link` |
| 三维场景 | [scene-3d.md](scene-3d.md) | `scene-3d` + piece：`scene3d-*`(41 种元素，含固定单例 `scene3d-scene`/`scene3d-camera`) |

## 绑定字段速查（仅组件特有）

| 组件/图层 | 字段 option | 约束 |
|---|---|---|
| basic-text / basic-paragraph | `value-field` | string, 0~1 |
| basic-markdown | `value-field` | string, 0~1（首行值作为 Markdown 内容） |
| chart-bar / chart-line / chart-area | `category-field`, `metric-fields` | 类目:1；数值:≥1（每字段一系列） |
| chart-biaxial(-stack) | `category-field`, `metric-fields`(柱·左轴), `line-metric-fields`(线·右轴) | 类目:1；柱线各 ≥0 |
| chart-pie / chart-funnel / chart-capsule | `category`, `value` | 各 1 |
| chart-scatter | `x-field`, `y-field`, `size-field` | x/y 各 1；size 0~1 |
| chart-radar | `indicator-field`, `metric-fields` | 指标:1；数值 1~6 |
| chart-gauge / chart-liquid | `value-field` | number, 0~1（全行求和） |
| chart-heatmap | `x-field`, `y-field`, `value-field` | 各 1 |
| chart-treemap | `name-field`, `value-field`, `group-field` | 名/值各 1；分组 0~1 |
| chart-sankey / chart-graph | `source-field`, `target-field`, `value-field` | 源/去向各 1；值 sankey:1、graph:0~1 |
| chart-wordcloud | `word-field`, `weight-field` | 各 1 |
| chart-map | `region-field`, `value-field` | 各 1（可写简称如湖北，组件映射到 GeoJSON 全称） |
| basic-table | `table-data-fields`, `table-key-fields`, `cross-filter-key-field`, `select-sync-fields` | fields 多；cross-filter-key-field ≤1 |
| basic-scroll-board | `board-fields` | 多（每字段一列） |
| basic-ranking-list | `category`, `value` | 各 1 |
| data-repeater | `item-fields`, `row-key-field` | item-fields ≥1；row-key-field 0~1（模板子组件用普通字段绑定，自动取本行） |
| basic-list | `title-field`, `value-field` | 各 0~1 |
| basic-select / group-tabs / group-buttons | `option-field` / `tab-field` / `menu-field` | string, 0~1（数据驱动选项） |
| basic-search / basic-calendar / basic-timeselect | `linkage-field` | string, 0~1（联动匹配字段） |
| basic-pagination | `count-field` | 0~1（总条数） |
| basic-progress / basic-card / basic-flipper | `value-field` / `value-field` / `value` | number, 0~1 |
| basic-switch | `value-field` | 0~1（首行值回填开关状态，静默不触发 switchChanged） |
| basic-image / basic-carousel / basic-video | `image-field` / `image-field` / `video-field` | string, 0~1（URL） |
| 三态类(image/graphical/icon/card/button) | `relationship-field` + `relationship-value` | 0~1 + 字符串（选中判定） |
| 点图层(marker/circle/symbol…) | `marker-lng`, `marker-lat`, `marker-name`, `marker-value`（bind-fields 档）/ `data-source-uid`+`src-lng-field`/`src-lat-field`/`src-name-prop`（source 档） | lng/lat 各 1；name/value 0~1 |
| 线图层(polyline/curve/arrowline/animate-line…) | `line-lng`, `line-lat`, `line-group`, `line-order` / 源 `src-lng-field`/`src-lat-field`/`src-group-field`/`src-order-field` | lng/lat 各 1；group/order 0~1 |
| 飞线图层(flyline) | `fly-from-lng`, `fly-from-lat`, `fly-to-lng`, `fly-to-lat`, `fly-name` / 源 `src-from-lng-field`/`src-from-lat-field`/`src-to-lng-field`/`src-to-lat-field`/`src-name-prop` | 起止 lng/lat 各 1；name 0~1 |
| 面图层(region) | `region-name`, `region-value` / 源 `src-name-prop`/`src-value-prop` | 各 1 |
| 面图层(polygon/geojson/fill-extrusion…) | 仅数据源档 `data-source-uid`（polygon/fill-extrusion 另有 `src-name-prop`/`src-value-prop`；geojson 用 `geojson-url`/`geojson-text`） | — |
| scada-2d / scene-3d | `point-key-field`, `point-value-field`（测点长表键/值列；元素 `data-key` 是字符串键，非三元组） | 各 0~1 |