WebBuilder Slot 组件使用操作指南

原创

技术挖掘官

发布于 2026-07-23 17:06:41

1080

一、Slot 组件概述

Slot 是 WebBuilder 平台的多栏联动选择容器组件，内部承载若干 SlotView 视图，常用于多级联动选择、分栏多选、层级数据筛选场景。典型应用：省市区三级联动、分类多级筛选、多维度并列选择。

从示例源码可以看出，Slot 分为两大形态：

普通多选 Slot：内置静态二维数组数据源，支持多选、获取 / 赋值；
联动 Slot：嵌入多个SlotView，视图之间通过事件实现级联加载；

核心层级结构规范

module
└── viewport（根容器 layout:"grid1"）
    └── container
        └── Slot（Wb.Slot）
            ├ SlotView（Wb.SlotView，列表视图载体）

二、核心属性说明

Wb.Slot 外层容器属性

属性	说明
cid	组件唯一标识，用于脚本 app.xxx 获取实例
data	静态二维数组数据源，适用于固定选项场景
height	设置 Slot 整体高度
buttonAlign	内部按钮对齐方式 center/left/right
defaults	统一给内部 SlotView 配置默认参数，示例 autoScroll:"hide" 隐藏滚动条
border	false 去除外边框

Wb.SlotView 内部视图属性

Slot 内部每一列选择列表都为SlotView

属性	说明
url	远程数据源接口地址
textField	展示文本对应的字段名
valueField	选中值对应的字段名
topTitle	当前列标题名称

Slot 常用事件

itemselect：选中条目触发
SlotView.selectionchange：视图选中项变更（多级联动核心事件）

Slot 内置核心方法

// 设置选中值
app.commonSlot.value = ['a2','b2'];
// 获取选中值
let val = app.commonSlot.value;

三、三种典型场景实操教程（基于示例源码）

场景 1：普通静态多选 Slot（固定二维选项）

适合固定分类选项、多栏静态选择，使用 data 配置静态数组。

完整示例代码：

{
  cname: "module",
  cid: "slot_static_demo",
  items: [{
    cname: "viewport",
    cid: "view1",
    layout: "grid1",
    items: [
      {cname: "label", text:"静态多选Slot", cls:"w-title3"},
      {
        cname: "container",
        layout:"grid1",
        frame:true,
        items:[
          {
            cname: "slots",
            cid: "commonSlot",
            data: "[\n  [{ text: 'a1' }, { text: 'a2' }, { text: 'a3' }],\n  [{ text: 'b1' }, { text: 'b2' }, { text: 'b3' }]\n]",
            buttonAlign: "center",
            events: {
              "itemselect": "Wb.tip(Wb.encode(this.value) + ' selected');"
            },
            items: [
              {
                cname: "array",
                cid: "buttons",
                items: [
                  {
                    cname: "button",
                    text:"Set value",
                    events: {
                      click: "app.commonSlot.value = ['a2', 'b2'];"
                    }
                  },
                  {
                    cname: "button",
                    text:"Get value",
                    events: {
                      click: "Wb.tip('选中值：' + Wb.encode(app.commonSlot.value));"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }]
}

操作要点

data 使用二维数组，每一维对应一列选项；
通过 .value 读写选中集合；
itemselect 监听选中变化；

场景 2：自定义 SlotView（单列表远程数据源）

Slot 内部嵌入单个SlotView，通过 url 加载远程接口数据，适合单列选择面板。

{
  cname: "slots",
  cid: "customSlot",
  height: "15em",
  items: [
    {
      cname: "list",
      cls:"Wb.SlotView",
      cid: "slotView1",
      url: "demo-source?xaction=staffDict",
      textField: "full_name",
      valueField: "code",
      topTitle: "Staff list"
    }
  ]
}

要点：

textField：页面显示文字字段；
valueField：最终提交的值字段；
url 配置后端接口动态加载数据。

场景 3：多级联动 Slot（省市区三级联动，核心业务场景）

原理：一级视图选中变更 selectionchange，加载二级视图，二级选中再加载三级视图。

源码核心片段：

{
  cname: "slots",
  cid: "linkedSlot",
  height: "10em",
  defaults: "({ autoScroll: 'hide' })",
  border: false,
  items: [
    {
      cname: "list",
      cls:"Wb.SlotView",
      cid: "continentView",
      url: "demo-source?xaction=listRootArea",
      topTitle: "Continent",
      textField: "area_name",
      events: {
        "selectionchange": "app.countryView.load({ params: { parent_id: this.selection.data.sid } });"
      }
    },
    {
      cname: "list",
      cls:"Wb.SlotView",
      cid: "countryView",
      url: "demo-source?xaction=listArea",
      topTitle: "Country",
      textField: "area_name",
      events: {
        "selectionchange": "app.cityView.load({ params: { parent_id: this.selection?.data.sid } });"
      }
    },
    {
      cname: "list",
      cls:"Wb.SlotView",
      cid: "cityView",
      url: "demo-source?xaction=listArea",
      topTitle: "City",
      textField: "area_name"
    }
  ]
}

联动核心逻辑说明：

this.selection 获取当前选中行数据；
.load({params:{xxx}}) 动态携带参数刷新下级列表；
this.selection?.data.sid 使用可选链，防止未选择时报错；
defaults:"({autoScroll:'hide'})" 统一控制内部所有 SlotView 滚动条策略。

四、常用 API 汇总

// 1. 获取选中值
let selected = app.commonSlot.value;

// 2. 赋值选中
app.commonSlot.value = ["a2","b2"];

// 3. SlotView 重新加载数据（联动场景）
app.countryView.load({params:{parent_id:"xxx"}});

// 4. 获取当前SlotView选中单行数据
let row = app.continentView.selection;
if(row){
  let sid = row.data.sid;
}

五、适用业务场景

行政区划三级联动（省、市、区县）
物料多级分类筛选、产品分类层级选择
档案多级目录选择
多栏并列多选筛选面板
权限树形层级选择简化展示

六、避坑指南

cid 必须唯一：Slot、SlotView 不能重复 cid，否则 app.xxx 获取实例失败；
多级联动务必增加 ?. 可选链，防止未选择任何条目时 selection 为 null 引发脚本报错；
静态data字符串数组格式严格，引号、换行格式错误会导致选项不渲染；
远程接口必须返回数组结构，textField/valueField 和后端返回字段名称大小写保持一致；
多列联动建议统一设置 Slot 高度，避免各列高度不一致造成界面错位；
不要直接修改内部 SlotView 的 items，优先调用.load()方法刷新数据。

七、开发选型建议

固定少量选项 → 使用 Slot + data 静态数组
单一列表远程选择 → Slot + 单个 SlotView
层级级联选择（省市区、分类树）→ Slot + 多个 SlotView + selectionchange 事件联动

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

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

javascript

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

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

javascript

登录后参与评论

0 条评论

热度

WebBuilder Slot 组件使用操作指南

WebBuilder Slot 组件使用操作指南

一、Slot 组件概述

二、核心属性说明

Wb.Slot 外层容器属性

Wb.SlotView 内部视图属性

Slot 常用事件

Slot 内置核心方法

三、三种典型场景实操教程（基于示例源码）

场景 1：普通静态多选 Slot（固定二维选项）

场景 2：自定义 SlotView（单列表远程数据源）

场景 3：多级联动 Slot（省市区三级联动，核心业务场景）

四、常用 API 汇总

五、适用业务场景

六、避坑指南

七、开发选型建议

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐