唯杰地图 logo唯杰地图
VJMAP
EN

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

vjvp/references/widgets/controls.md 10.3 KB89 行
原文

basic-button/switch/search/select/pagination/list/progress/iframe 与 group-popup/tabs/buttons。 返回目录：index.md；全量选项字典（最权威）：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,01) + value-field(number,01)。

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,01)——⚠️ 值与 max-value（默认 100）同单位取百分比：推 0.7 显示 1%（0.7% 四舍五入到 label-decimal-places），不是"01 小数即百分比"。要显示 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"}} }] }] } }。