在WebBuilder低代码开发中，表单选择类组件是使用率最高、覆盖场景最广的基础核心能力。

其中 Check复选框、Radio单选框、Toggle开关、Slider滑块四大组件，包揽了后台系统95%以上的状态选择、参数配置、数值调节场景。

很多新手刚接触WebBuilder，看不懂组件属性、不会区分使用场景、不懂取值赋值、不会配置高阶样式。

今天这篇保姆级零基础使用教程，基于官方源码实战拆解，从组件作用、核心属性、完整示例、业务场景、AI生成技巧全方位讲解，看完直接精通四大组件开发，项目直接复用！

一、整体认知：四大组件分工与适用场景

先搞懂核心区别，开发不再选错组件：

✅ Check 复选框：支持单多选，适合多选项勾选、权限配置、多标签选择

✅ Radio 单选框：互斥选择，只能选一个，适合状态、类型、性别等唯一选项场景

✅ Toggle 开关：布尔状态切换，UI更轻量化、现代化，适合功能启停、模块开关

✅ Slider 滑块：数值拖拽调节，适合百分比、权重、区间、音量等数值配置

二、Check复选框 & CheckGroup群组 完整使用教程

复选框分为「独立单复选」和「CheckGroup群组复选」两种用法，分别适配单一场景和批量多选场景。

1、独立单复选（基础用法）

用于单个勾选确认，比如协议同意、单独功能启用标记，结构极简、开箱即用。

核心常用属性：

text：组件展示文本 label：左侧标签名称 returnType：返回值类型，支持bool/int，适配数据库0/1存储 showEmptyLabel：空标签占位，优化表单排版 change事件：勾选状态实时监听回调

完整可运行示例：

{ cname: "check6", cid: "intValueCheck", label: "是否公开", text: "公开此数据", returnType: "int", showEmptyLabel: true, events: { change: "Wb.tip('当前选中值：' + value);" } }

特点：勾选返回1、未勾选返回0，完美适配后端数字字段存储，无需手动转换数据类型。

2、CheckGroup群组多选（业务核心）

多个复选框统一管理，实现批量多选、统一取值、表单批量回显，是权限、标签配置的核心组件。

高阶核心属性：

returnAll：返回所有选项（含选中/未选中）完整状态 returnArray：以数组格式返回选中值，后端解析更便捷

实战示例（权限多选）：

{ cname: "checks", cid: "roleCheckGroup", returnArray: true, items: [ {cname: "check6",cid: "add",label: "新增权限"}, {cname: "check6",cid: "edit",label: "编辑权限",value:true}, {cname: "check6",cid: "del",label: "删除权限"} ] }

支持三种赋值回显方式：对象赋值、数组赋值、CID赋值，完美适配编辑页数据回填场景。

三、Radio单选框 & RadioGroup群组 使用教程

单选组件核心解决「唯一选择」场景，通过分组隔离彻底解决传统单选互相干扰、状态错乱的问题。

1、独立Radio分组单选

核心精髓：group分组隔离，不同group的单选框完全独立、互不干扰。

{ cname: "check2", cid: "man", label: "男", group: "userGender" }, { cname: "check2", cid: "woman", label: "女", group: "userGender" }

同一分组自动互斥，页面可同时搭建多组单选，零BUG、无需手写互斥逻辑。

2、RadioGroup群组单选（项目首选）

企业级开发推荐统一使用群组写法，结构更规范、维护更简单，支持多种取值模式。

核心属性：

returnName：开启CID取值，精准定位选项，不受排序影响

完整示例：

{ cname: "radios", cid: "statusRadioGroup", returnName: true, items: [ {cname: "check2",cid: "open",label: "启用",value:true}, {cname: "check2",cid: "close",label: "禁用"} ] }

支持索引赋值、CID赋值，表单编辑回显一键搞定，彻底告别手动匹配判断。

四、Toggle开关组件 详细使用教程

Toggle是轻量化现代化状态开关，替代传统单选框，UI更美观、交互更流畅，适配所有启停、开关场景。

1、基础用法与核心属性

prefix/suffix：开关前后自定义文案 clickToggle：是否允许点击切换，关闭后仅支持拖拽 toggleAlign：对齐方式，支持居左/居右 vertical：开启垂直开关布局 returnType：支持布尔/整型返回，适配数据库

2、实战常用示例

{ cname: "toggle", cid: "msgToggle", text: "消息推送开关", prefix: "关闭", suffix: "开启", returnType: "int", events: { change: "Wb.tip('当前状态值：' + value)" } }

适用于系统设置、功能启停、权限开关等轻量化状态配置场景。

五、Slider滑块组件 高阶使用教程

滑块组件是数值调节神器，支持单值、多区间、横竖布局，适配百分比、权重、范围筛选等场景。

1、基础单值滑块

适用于单一数值调节，如权重、比例、音量。

{ cname: "slider", cid: "weightSlider", text: "权重配置", value: 50, minValue: 0, maxValue: 100, step: 10 }

2、高阶多值区间滑块

支持双节点拖拽，实现数值区间选取，适配价格筛选、分段参数配置。

{ cname: "slider", cid: "rangeSlider", text: "数值区间筛选", value: [20, 80], maxValue: 100 }

3、特色布局滑块

支持 vertical 垂直布局、自定义提示文案、前后缀展示，适配数据大屏、侧边控制面板。

六、四大组件通用取值 & 赋值通用方法（必学）

所有选择类组件，WebBuilder全部原生封装取值、赋值API，无需手写JS：

1、获取组件值：app.组件CID.value 2、动态赋值/表单回显：app.组件CID.setValue(值) 3、状态监听：change事件实时回调数值变化

统一API规范，上手即会，大幅降低开发学习成本。

七、AI一键生成组件 万能指令模板

无需手动写配置，直接复制指令交给AI，一键生成完整可用组件：

复选框AI指令：生成权限多选复选框组，包含新增、编辑、删除，默认选中新增，返回数组格式，带取值按钮

单选框AI指令：生成系统状态单选组件，启用/禁用两项，默认选中启用，支持表单回显

开关AI指令：生成消息推送开关，带前后缀文案，返回整型0/1数值，切换状态实时提示

滑块AI指令：生成权重配置滑块，范围0-100，步进10，默认50，展示数值提示

八、业务场景选型总结（快速对照）

1、单一确认场景 → 独立Check复选框 2、多选项批量勾选 → CheckGroup群组 3、唯一状态选择 → RadioGroup单选群组 4、轻量化功能开关 → Toggle开关 5、数值拖拽、区间配置 → Slider滑块

写在最后

WebBuilder四大表单选择组件，核心优势就是配置化零开发、原生无BUG、AI一键生成。

掌握本文的属性用法、代码示例、场景选型，基本可以覆盖所有企业级表单选择开发场景，彻底告别重复手写JS冗余代码。