# 控件类组件（按钮 / 开关 / 输入 / 列表 / 弹层）

> `basic-button/switch/search/select/pagination/list/progress/iframe` 与 `group-popup/tabs/buttons`。
> 返回目录：[index.md](index.md)；全量选项字典（最权威）：[widget-schema.generated.json](../widget-schema.generated.json)。

## 8. 控件类（按钮 / 输入 / 列表 / 弹层）

### 8.1 basic-button —— 按钮

- **type**: `basic-button`　**默认尺寸**: `[120,40]`　**默认名**: `text` 值或"按钮"
- 用途：触发交互动作（配 `options.interactions` 的 `click` 组）；支持**四态**样式。选项按状态前缀成组：`*-default-*`(常态)、`*-hover-*`(悬停,开关 `show-hover`)、`*-click-*`(点击,开关 `show-click`)、`*-select-*`(选中,开关 `show-select`+`checked` 默认选中)——每态一套 `text-<state>-font`/`background-<state>-color`(支持渐变)/`border-<state>-color/width/radius/style`/`font-<state>-shadow-*`，未开启或未写的态回落常态。
- 其它：`text`、`padding`(`[上,右,下,左]`)、涟漪动画 `animation-hover-show`/`animation-click-show`+`animation-*-time`、选中判定 `relationship-field`/`relationship-value`。
- 常用写法：`{ "text":"查询", "text-default-font":{"size":16,"color":"#fff","bold":true}, "background-default-color":"#2f7bff", "border-default-radius":8, "show-hover":true, "background-hover-color":"#1c64d9" }`。

### 8.2 basic-search —— 搜索框

- **type**: `basic-search`　**默认尺寸**: `[260,36]`　**默认名**: "搜索框"
- 用途：输入关键字 → **联动筛选**其它组件（发起方开 `cross-filter-emit`，接收方开 `cross-filter-receive`（只看接收组件自身开关，页面开关可省；无单独的 `cross-filter-in` 选项））。
- 关键项：`placeholder`、`fuzzy-search`(模糊匹配)、`pinyin-search`(全拼/首字母，如 `gz` 命中广州)、`realtime`(实时搜索)+`realtime-debounce`、`show-button`+`button-text`、`clearable`；盒样式 `input-bg`/`input-text-color`/`input-border-color`/`input-focus-border-color`/`input-radius`、按钮 `button-bg`/`button-text-color`。
- **绑定字段**：`linkage-field`(string,0~1) —— 搜索值与该字段匹配做联动。
- `search` 是专属触发器，payload `{keyword, value, fuzzy}`；程序化入口 `element.search(kw)`。

### 8.3 basic-select —— 基础下拉菜单

- **type**: `basic-select`　**默认尺寸**: `[200,36]`　**默认名**: "基础下拉菜单"
- 用途：下拉选项 → 联动/切换/改参数。选项来源：静态 `static-items`(逗号串) 或绑定 `option-field`(去重后作为选项)。
- 关键项：`multiple`(多选)、`default-type`(`fixed`/`first`/`last`/`index`)+`default-value`/`default-index`、`clearable`/`filterable`/`pinyin-search`(可搜索时全拼/首字母)；盒 `select-bg`/`select-text-color`/`select-border-color`/`select-radius`、面板 `panel-bg`/`option-hover-bg`/`option-selected-bg`/`option-height`。
- **绑定字段**：`option-field`(string,0~1)。
- `default-type:'index'` 的 `default-index` 是 **1 基**（`2` → `selectedIndex=1`）；`itemClicked` payload = `selectedData`（`select(i,data)` 传入的维度行）。

### 8.4 basic-pagination —— 分页器

- **type**: `basic-pagination`　**默认尺寸**: `[400,36]`　**默认名**: "分页器"
- 用途：配合表格/列表分页（页码经 `itemClicked` payload `{页码,每页条数}` 联动）。
- 关键项：`page-size`(10)、`show-size-changer`+`size-options`、`show-total`、静态 `total`(100)；颜色 `text-color`/`active-color`/`item-bg`。
- **绑定字段**：`count-field`(0~1) —— 总条数取该字段首行值。
- `itemClicked` payload `{页码:N, 每页条数:N}` 只在 `changePage(page)` 路径组装（页码 DOM 点击走此路）；裸 `handle.select(i)` 不带此 payload。

### 8.5 basic-list —— 列表

- **type**: `basic-list`　**默认尺寸**: `[280,320]`　**默认名**: "列表"
- 用途：标题+数值的数据列表（可显序号/数值条/自动轮播）。自定义触发器：`itemClicked`（行点击，带选中传递）。
- 关键项：`static-items`(静态条目)、`show-index`、`row-height`(36)、`show-divider`、`auto-select-first`；轮播 `carousel`+`carousel-type`(`scroll`连续/`page`整页)+`carousel-speed`/`carousel-page-count`/`carousel-dwell`/`carousel-loop`+`show-dots`；数值条 `valueBar`+`value-bar-color`(渐变)/`value-bar-bg`/`value-bar-height`；行色 `row-bg`/`row-alt-bg`/`hover-bg`/`selected-bg`、字色 `title-color`/`value-color`。
- **绑定字段**：`title-field`(string,0~1) + `value-field`(number,0~1)。

### 8.6 basic-progress —— 进度条

- **type**: `basic-progress`　**默认尺寸**: `[200,200]`　**默认名**: "进度条"
- 用途：单值进度（环形/横条/纵条）。无数据显示 `static-value`(60)。
- 关键项：`shape`(`ring`环/`rect`横/`column`纵)、`progress-color`(渐变)/`shape-background`(轨道)、`bar-shape`(`normal`/`burst`分段/`bold`)+`bar-shape_burst-number`/`-interval`、环形 `ring-size`(环宽%)+`data-start-angle`/`data-end-angle`、标签 `label`+`label-position`+`label-text-type`(`percent`/`normal`)+`label-unit`/`label-decimal-places`、`max-value`。
- **绑定字段**：`value-field`(number,0~1)——⚠️ 值与 `max-value`（默认 100）同单位取百分比：推 `0.7` 显示 `1%`（0.7% 四舍五入到 `label-decimal-places`），不是"0~1 小数即百分比"。要显示 70% 应推 `70`。

### 8.7 basic-iframe —— iframe 内嵌网页

- **type**: `basic-iframe`　**默认尺寸**: `[400,300]`　**默认名**: "iframe"
- 关键项：`iframe-link`(地址)、`heavy-load`(显示时重载)、`sandbox`、`zoom`(页面缩放)、`enable-movement-polyfill`(鼠标移动兼容)、`microphone`/`camera`(权限)。无绑定字段。

### 8.8 group-popup —— 弹窗（页面内弹层）

- **type**: `group-popup`　**默认尺寸**: `[400,300]`　**默认名**: "弹窗"
- 用途：页面内轻弹层（内容放 `widgets: []`），由 **`switchPopup` 动作**（`popupUid` 指向本组件，`operate`:`show`/`hide`）开关；区别于工程级窗口（`switchWindow`+`project.windows`）。
- 关键项：`is-popup`(默认显示弹窗，默认 false=初始隐藏)、`popup-bg`、`show-mask`+`background-mask-color`+`close-outside`(点遮罩关闭)、`auto-close`+`close-time`、关闭按钮 `close-btn-show`/`close-btn-color`/`close-btn-size`/`close-show-countdown`、`show-scroll`。无绑定字段。
- `switchPopup` 动作选项键是 `popupUid`（`[{targetPath:[uid]}]`）+ `operate`(`'show'|'hide'`)；`showPopup()`/`hidePopup()` 写的是 **transient 选项层** 的 `is-popup`——读回用 `getOption("is-popup")`，组件上没有 `visible` 字段。播放态 `is-popup=false` 时整个定位盒不可见（`isBoxVisible`）。

### 8.9 group-tabs —— 选项卡

- **type**: `group-tabs`　**默认尺寸**: `[400,300]`　**默认名**: "选项卡"
- 用途：多标签页容器——每个标签对应一个**子面板**（`widgets[]` 里第 N 个 `group-panel`＝第 N 个标签的内容，同视图容器的结构约定）。自定义触发器：`itemClicked`(payload 含标签序号/文本)。
- 关键项：`tab-items`(标签列表,逗号/换行分隔)、`orientation`(`horizontal`选项卡/`vertical`菜单)+`bar-position`(`start`/`end`)、`default-active`、`bar-size`(Tab 条厚度)、`auto-switch`+`switch-interval`、`tab-align`、`tab-type`(`tag`标签/`mark`标示)+`tag-shape`/`mark-shape`/`mark-size`；三态文字 `tab-color`/`tab-active-color`/`tab-hover-color`(+`tab-hover-show`)、背景 `tab-bg`/`tab-active-bg`/`tab-hover-bg`、指示条 `show-indicator`+`indicator-color`。
- **绑定字段**：`tab-field`(string,0~1) —— 数据驱动标签列表。
- `default-active` 是 0 基序号（`1` → `activeIndex=1`）；`setActive(i)` 切标签并派发 `itemClicked`，payload `{label, index}`。

### 8.10 group-buttons —— 按钮组菜单

- **type**: `group-buttons`　**默认尺寸**: `[480,48]`　**默认名**: "按钮组菜单"
- 用途：一组互斥选中的按钮（时间粒度/图层切换等），选中值经 `itemClicked`/选中传递联动。
- 关键项：`menu-items`(静态选项)、`default-type`(`first`/`fixed`/`last`/`index`/`none`)+`default-value`/`default-index`、`allow-unselected`；布局 `orientation`+`auto-layout`(自适应)或 `rows`/`cols`+`gap`；单钮样式 `item-font-size`/`text-color`/`item-bg`(渐变)/`selected-text-color`/`selected-bg`/`selected-border-color`/`hover-*`。
- **绑定字段**：`menu-field`(string,0~1) —— 数据驱动选项。
- `default-type:'first'` 初始化即自动选中 `selectedIndex=0`（无需点击）。

### 8.11 basic-switch —— 开关

- **type**: `basic-switch`　**默认尺寸**: `[76,36]`　**默认名**: "开关"
- 用途：工业 HMI 启停开关（胶囊轨道+滑块）。播放态点击切换并派发 **`switchChanged` 触发器**（payload `{checked,value}`），配组态 `scadaWritePoint` 动作（「payload 字段」填 `value`）即可点开关写测点驱动泵启停、管道流停。
- 关键项：`checked`(默认开启)、`disabled`(禁用点击)、`on-value`/`off-value`(切换派发的值，默认 `1`/`0`，数字串自动转数字、true/false 转布尔)；外观 `on-color`/`off-color`(支持渐变)/`knob-color`、轨道内短文本 `on-text`/`off-text`+`state-font`。
- 自定义动作（目标=本开关）：`switchOn`/`switchOff`/`switchToggle`（置开/置关/切换，均派发 `switchChanged`）。⚠️ `switchToggle` 缺 `elapsed>0` 守卫，经交互链调用双帧执行=净零不变（`switchOn`/`switchOff` 幂等正常）；要切换用条件分路或 `raw.toggle()`。
- **绑定字段**：`value-field`(0~1) —— 首行值回填开关状态：等于「开启值/关闭值」按其判定，否则按宽松表兜底——开：`1/true/on/run/open/yes`，关：`0/false/off/stop/close/closed/no/空`（静默同步，不触发 `switchChanged`，避免数据回流形成写测点回声）。
- 常用写法：`{ "checked":true, "on-color":"#22c55e", "off-color":"#41506b", "interactions":{ "version":2, "groups":[{ "trigger":{"name":"switchChanged","options":{}}, "interactions":[{ "enable":true, "trigger":{"name":"switchChanged","options":{}}, "action":{"name":"scadaWritePoint","options":{"element":[{"targetPath":["screen_x","w_scada"],"refType":"element"}],"key":"PUMP1_RUN","payload-field":"value"}} }] }] } }`。