# 表格类组件

> `basic-table`（功能最全）/ `basic-scroll-board`（轮播列表）/ `basic-ranking-list`（排名列表）。
> 返回目录：[index.md](index.md)；全量选项字典（最权威）：[widget-schema.generated.json](../widget-schema.generated.json)。

## 4. basic-table —— 数据表格

- **type**: `basic-table`　**默认尺寸**: `[480,320]`　**默认名**: "基础表格"
- 自定义触发器：`itemClicked`、`click-row`、`select-row`、`unselect-row`、`click-operate`。
- 选项极多（220+ 项），下面只列**高频**；全量见 schema。

高频布局/行为 options：

| name | 类型 | 默认 | 说明 |
|---|---|---|---|
| `row-count` | `number(min=1)` | `5` | **每页行数（pageSize）**——仅分页/整页轮播开启时切片，不开分页不裁 DOM 行 |
| `table-row-height` | `number` | `30` | 行高 px |
| `autoWidth` | `boolean` | `false` | 列宽自适应 |
| `pagination-height` | `number` | `0` | **>0 才显示分页条** |
| `page-size` | `number` | `10` | 分页选项里的"每页数据条数"声明；**basic-table 的 pageSize 只读 `row-count`**，调每页行数用 `row-count` |
| `connection-pagination` | `boolean` | `false` | 走后端分页 |
| `order-width` | `number` | `0` | **>0 才显示序号列**；`order-name` 默认"序号" |
| `radio-width` | `number` | `0` | >0 才显示单选列 |
| `operate-width` | `number` | `0` | >0 才显示操作列；`operate-text-list` 操作项 |
| `select-first-row` | `boolean` | `false` | 默认选中首行（选中态在组件响应式状态 selectedIndex/selectedRow/selectedData；vxe 渲染下 DOM 无稳定选中 class，勿靠 class 探测） |
| `header-bg-color` | `color` | `#1087E433` | 表头背景（默认半透明科技蓝，深色画布通用） |

列/行样式以"簇(cluster)"形式存在（数组型重复组）：

- `table-col-body-cluster`：逐内容列样式（`col-width` 默认 100、`col-align`、`col-type` 等）。
- `table-row-body-cluster`：行样式带（默认 2 条形成斑马纹：`row-bg-color`、`row-hover-bg-color`、`row-selected-bg-color`）。
- 簇在 options 里形如 `{"table-col-body-cluster": {"indexes": ["idx-xxx", ...], "idx-xxx": {...}}}`。**手写表格时通常不必写簇**，留空走默认即可，列会按绑定字段自动生成。

**绑定字段**：

| name | 类型 | 默认/约束 | 说明 |
|---|---|---|---|
| `table-data-fields` | `field` | 默认指向私有示例数据 | **表格列**（多个，每个字段一列） |
| `table-key-fields` | `field` | `[]` | 关键字段（唯一标识，联动/重定位用） |
| `cross-filter-key-field` | `field(max=1)` | `[]` | 点击联动用的键字段 |
| `select-sync-fields` | `field` | `[]` | 选中传递字段 |

> 表格默认 `table-data-fields` 绑定到组件**私有示例数据**（`__vp_private__`/`private`/`f_1..3` 姓名年龄性别）。要显示真实数据，把 `table-data-fields` 重绑到你的 `[connUid,tableUid,fieldUid]` 列表。

---

## 4b. basic-scroll-board —— 轮播列表

- **type**: `basic-scroll-board`　**默认尺寸**: `[420,280]`　**默认名**: "轮播列表"
- 用途：表头 + 自动纵向滚动的数据带（告警流/动态榜单）。自定义触发器：`itemClicked`。

| name | 类型 | 默认 | 说明 |
|---|---|---|---|
| `row-num` | `number(1~30)` | `5` | 可视行数 |
| `wait-time` | `number(s)` | `2` | 轮播间隔 |
| `carousel` | `select` | `single` | `single`逐行 / `page`整页 |
| `show-index` + `index-header` | `boolean`+`string` | `true`/`#` | 序号列 |
| `show-header` + `header-height` + `header-text` | — | `true`/35/`` | 表头（`header-text` 逗号分隔覆盖列名，空=用字段别名） |
| `column-width` / `column-align` | `string` | `` | 逗号分隔的列宽(px)/对齐(left/center/right) |
| `header-bg`/`header-color`/`odd-row-bg`/`even-row-bg`/`row-color`/`font-size` | — | — | 颜色与字号（默认蓝青斑马纹） |

**绑定字段**：`board-fields`（多个，每字段一列；默认指向私有示例数据，要重绑真实三元组）。

---

## 4c. basic-ranking-list —— 排名列表

- **type**: `basic-ranking-list`　**默认尺寸**: `[360,280]`　**默认名**: "排名列表"
- 用途：TOP N 榜单（排名徽标 + 名称 + 数值进度条），按数值自动排序、可轮播。自定义触发器：`itemClicked`。

| name | 类型 | 默认 | 说明 |
|---|---|---|---|
| `row-num` | `number(1~20)` | `5` | 可视行数 |
| `sort` | `select` | `desc` | `desc`/`asc`/`none` |
| `show-value` + `unit` | — | `true`/`` | 数值与单位 |
| `rank-color`/`name-color`/`value-color` | `color` | — | 徽标/名称/数值颜色 |
| `bar-start`/`bar-end`/`bar-height` | — | 蓝→青/6 | 进度条渐变与高度 |

**绑定字段**：`category`(名称,string) + `value`(数值,number)（各恰 1）。**无私有兜底数据**——与 basic-table/scroll-board 不同，未绑字段时渲染为空，必须绑真实三元组。