WebBuilder 原生 Wb.Select 组件全方位使用指南

原创

技术挖掘官

发布于 2026-07-28 17:13:26

1230

前言

在 WebBuilder 低代码开发体系中，下拉选择框是表单、筛选面板、业务配置页面最高频使用的控件。平台内置Wb.Select原生下拉组件，无需引入 Vue、ElementUI 等第三方前端库，原生支持静态数据、远程接口加载、树形下拉、联动级联、多选、自定义模板、搜索过滤、内置快捷按钮（Trigger）等丰富能力。

一、基础概念与模块加载方式

示例整体承载在Wb.Module模块中，模块initialize事件预先注册全局工具方法，用于给下拉组件附加快捷操作按钮。

Wb.apply(app, {
  /**
   * Add trigger button to fetch value. @priv
   * @param {Wb.Select} select select control.
   */
  addFetchValueButton(select) {
    select.addTrigger({
      icon: 'share', tip: 'Show value', weight: 991, handler() {
        Wb.tip(select.cid + ' value is: ' + select.value);
      }
    });
  }
});

作用：页面内所有下拉组件在ready事件可直接调用app.addFetchValueButton(this)，快速添加取值快捷按钮，实现代码复用。

二、基础静态下拉（本地数据）

适用于选项固定、数据量小，不需要请求后台接口的场景。

1. 简单字符串数组

{
  "_icon": "combo",
  "text": "commonSelect",
  "cls": "Wb.Select",
  "properties": {
    "cid": "commonSelect",
    "text": "Common Select",
    "data": "['item1', 'item2', 'item3']"
  }
}

data：填写字符串数组，展示文本与选中 value 一致；
editable:false：禁止输入，只能下拉选择。

2. 名称 - 值二元数组（业务最常用）

{
  "_icon": "combo",
  "text": "nameValueSelect",
  "cls": "Wb.Select",
  "properties": {
    "cid": "nameValueSelect",
    "text": "Name Value",
    "data": "[['name1', 'value1'], ['name2', 'value2'], ['name3', 'value3']]"
  },
  "events": {
    "ready": "app.addFetchValueButton(this);"
  }
}

格式[显示文本,存储值]，页面展示 name1，后台拿到 value1，满足绝大多数字典选择场景。

3. 带图标、提示、禁用项的复杂静态选项

"data": "[
  { text: 'With icon', _icon: 'user2' },
  { text: 'Disabled Item', _disabled: true }
]"

支持_icon图标、_disabled禁用、_tip悬浮提示、_fixed固定置顶选项。

三、远程数据源下拉（对接后台接口，企业系统主流）

通过url属性调用服务接口，搭配textField展示字段、valueField存储字段。

基础远程下拉

{
  "_icon": "combo",
  "text": "remoteSelect",
  "cls": "Wb.Select",
  "properties": {
    "cid": "remoteSelect",
    "text": "Remote Select No Wrap",
    "url": "demo-source?xaction=staffRows",
    "textField": "full_name",
    "valueField": "code",
    "loadOnce": "true",
    "noWrap": "true"
  }
}

关键属性说明：

url：服务端数据源地址；
textField：下拉展示文本对应的返回字段；
valueField：选中后控件 value 保存的字段；
loadOnce:true：页面首次打开加载一次，下拉不再重复请求；
autoLoad:"all"：自动回显默认值，页面渲染完成自动加载数据；
noWrap：文本不自动换行。

实时搜索远程下拉

{
  "_icon": "combo",
  "text": "liveSearchSelect",
  "cls": "Wb.Select",
  "properties": {
    "cid": "liveSearchSelect",
    "text": "Live Seach",
    "url": "demo-source?xaction=staffSearch",
    "textField": "full_name",
    "valueField": "code"
  }
}

输入关键词自动携带参数访问接口实现后端模糊搜索，适合大数据字典。

请求前置拦截 beforeload 事件

可以在发起请求前修改请求参数、做校验，校验不通过直接终止加载：

"beforeload": "params.foo = 'bar';"

四、自定义下拉选项模板（ItemTpl / ItemTplFn）

原生样式无法满足展示需求时，自定义 DOM 布局，支持多列、图标、多字段同时展示。

静态模板 itemTpl

"itemTpl": "<div class=\"w-row w-align-center\">\n  <div style=\"width: 3em\" class=\"w-cell w-rownum\"></div>\n  <div class=\"w-icon icon-user2\"></div>\n  <div class=\"w-cell w-flex\">{code}</div>\n  <div class=\"w-cell w-flex3\">{full_name}</div>\n</div>"

直接使用{字段名}填充接口返回的数据字段。

函数模板 itemTplFn

支持 JS 表达式动态拼接 HTML，灵活性更高：

"itemTplFn": "return `<div class=\"w-row w-align-center\">\n  <div style=\"width: 3em\" class=\"w-cell w-rownum\"></div>\n  <div class=\"w-icon icon-user2\"></div>\n  <div class=\"w-cell w-flex\">${data.code}</div>\n  <div class=\"w-cell w-flex3\">${data.full_name}</div>\n</div>`;"

五、多选模式 multiSelect

开启multiSelect:"true"支持多选标签展示：

{
  "_icon": "combo",
  "text": "multiSelectWrap",
  "cls": "Wb.Select",
  "properties": {
    "cid": "multiSelectWrap",
    "text": "Multi Select Wrap",
    "url": "demo-source?xaction=staffSearch",
    "textField": "full_name",
    "valueField": "code",
    "noWrap": "true",
    "multiSelect": "true",
    "tagSortable": "true",
    "tagWrap": "true",
    "clearButton": "true"
  }
}

常用配套属性：

tagWrap：标签自动换行；
tagSortable：拖拽调整选中标签顺序；
clearButton：一键清空所有选择；选中值为数组格式，可通过脚本批量赋值：

this.parent.value = [{ code: '10001', full_name: 'Terri Duffy' }];

六、树形下拉 treePicker（机构、区域层级选择）

开启treePicker:true，下拉弹窗展示树形结构，支持单选 / 多选树节点。

{
  "_icon": "combo",
  "text": "treeSelect",
  "cls": "Wb.Select",
  "properties": {
    "cid": "treeSelect",
    "text": "Tree Select",
    "textField": "text",
    "valueField": "sid",
    "gridColumn": "1 / -1",
    "treePicker": "true",
    "data": "[{text:'Asia',sid:'a',items:[{text:'China',sid:'a1',_leaf:true}]}]"
  },
  "events": {
    "beforeselect": "if (!item.leaf) {\n  Wb.tip('Please select a leaf node');\n  return false;\n}"
  }
}

beforeselect事件：拦截选择，可以限制仅允许选择叶子节点，业务区域、组织架构场景高频使用。

七、级联联动下拉（Linked Select 省市区联动范式）

三个 Wb.Select 依次联动：大洲→国家→城市，核心依靠beforeload事件传递上级选中值作为查询参数。

{
  "_icon": "combo",
  "text": "countrySelect",
  "cls": "Wb.Select",
  "properties": {
    "cid": "countrySelect",
    "placeholder": "Country",
    "url": "demo-source?xaction=listArea",
    "textField": "area_name",
    "valueField": "sid"
  },
  "events": {
    "beforeload": "let select = app.continentSelect;\nif (select.verify())\n  params.parent_id = select.value;\nelse {\n  select.focus();\n  return false;\n}"
  }
}

逻辑：加载当前下拉数据前，读取上级下拉选中值放入请求参数；上级未选择则终止加载，并自动聚焦上级控件。

八、重要实用属性详解

forceSelect:"true" 强制必须选择下拉列表内存在的选项，禁止手动输入自定义值；
bindField 绑定页面字段，支持Wb.setValue直接给控件赋值，适合表单回填；
matchMode、selectMode 自定义搜索匹配规则，includesIC不区分大小写包含匹配；
keyName 读取平台内置字典配置，直接引用全局字典，无需手动填写 data；
pickerMinWidth：控制下拉弹窗最小宽度，避免自定义模板展示挤压。

九、常用脚本操作（开发高频代码片段）

1. 获取选中值

// 获取value原始值
let val = app.nameValueSelect.value;
// 完整对象
let fullData = Wb.getValue(app.nameValueSelect);
Wb.tip(Wb.encode(fullData));

2. 赋值

// 单选
app.nameValueSelect.value = "value1";
// 多选
app.multiSelect.value = [{code:"10001",full_name:"Terri Duffy"}];

3. 动态新增 / 删除静态选项

//永久修改数据源
app.localSelect.data.push({ text: 'New Item' });
app.localSelect.data.erase(0);
//临时新增（重新展开下拉会丢失）
app.localSelect.picker.addData({ text: 'New Item' });

4. 主动展开下拉、主动查询远程数据

app.localSelect.expand();
app.remoteSelect1.query();

十、Wb.Select 与外部 ElementUI Select 组件如何选择

优先使用 Wb.Select ✅ 原生控件，与 WebBuilder 表单校验、页面序列化、导入导出完美兼容； ✅ 无需加载 Vue、ElementUI 资源，页面加载更快，不存在跨框架生命周期冲突； ✅ 支持树形下拉、级联联动、多选标签、内置搜索、触发器扩展。
什么时候自定义 ElementUI Select 仅当原生控件 UI 样式、交互逻辑无法满足甲方强视觉要求，需要完全复刻 ElementUI 交互特性时，再采用 Vue 封装方案。

十一、落地最佳实践总结

小型固定字典：使用静态data配置；
大数据字典、后台动态字典：使用远程 url 加载，区分一次性加载loadOnce和实时搜索；
层级结构（组织、区域）：启用treePicker树形下拉；
省市区、分类联动场景：依靠beforeload实现级联；
需要多字段并排展示：使用itemTpl自定义模板；
多选业务场景开启multiSelect，搭配tagWrap自动换行；
统一封装通用工具方法（案例中的 addFetchValueButton），减少页面重复事件代码。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

低代码