amis 按钮点选控件 button-group-select用 JSON 配置实现按钮式表单选择器【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis在 amis 低代码框架中button-group-select是一种按钮集合当 select 点选的表单项控件它以按钮组的视觉形态呈现一组选项用户点击按钮即完成选择适合作为性别、状态、类型等少量枚举值的快速选择器。本文基于官方文档 button-group-select 组件文档 与仓库源码完整讲解其基本用法、垂直/平铺布局、按钮主题样式、角标配置、选项与值格式化参数以及change事件与clear/reset/reload/setValue四类特性动作并结合 组件实现文件 与 选项控件 HOC 说明其底层调用链。读完后你可以直接用 JSON Schema 搭建按钮点选表单项并掌握与数据域联动、跨组件控制的完整方案。基本用法在form的body中放置一个type: button-group-select的表单项通过options声明选项集合即可得到一个可点选的按钮组。选中值会写入表单数据域的name字段本例为type随表单提交到api指定的接口{ type: form, api: /api/mock2/form/saveForm, debug: true, body: [ { type: button-group-select, label: 选项, name: type, options: [ {label: Option A, value: a}, {label: Option B, value: b}, {label: Option C, value: c} ] } ] }从源码看该控件的渲染器注册在 ButtonGroupSelect.tsx使用OptionsControl装饰器以type: button-group-select注册并声明了sizeMutable: false尺寸不可被表单联动改变与strictMode: false不启用严格更新模式选项/数据变化时允许重渲染。组件本体继承自OptionsControlProps即所有列表选择类控件Select、Radios、Checkboxes 等共用的父类接口因此它天然获得选项加载、多选、值格式化等一整套能力。垂直模式配置vertical: true后按钮组由横向排列改为纵向排列适合选项文字较长、标签较多、需要逐行点选的场景{ type: form, api: /api/mock2/form/saveForm, body: [ { type: button-group-select, label: 选项, name: type, vertical: true, options: [ {label: Option A, value: a}, {label: Option B, value: b}, {label: Option C, value: c} ] } ] }实现上render方法会把vertical转成根节点样式类ButtonGroup--vertical见 ButtonGroupSelect.tsx 的 render对应样式定义在 amis-ui 按钮组 SCSS 中对应的单元测试 buttonGroupSelect.test.tsx 通过断言.cxd-ButtonGroup.cxd-ButtonGroup--vertical存在来验证该行为。平铺模式配置tiled: true实现平铺模式按钮按网格均匀铺满容器宽度视觉上更接近卡片点选适合移动端或需要大点击热区的场景{ type: form, api: /api/mock2/form/saveForm, body: [ { type: button-group-select, label: 选项, name: type, tiled: true, options: [ {label: Option A, value: a}, {label: Option B, value: b}, {label: Option C, value: c} ] } ] }与垂直模式同理tiled会映射到样式类ButtonGroup--tiledSCSS 中的平铺样式单元测试中同样以.cxd-ButtonGroup--tiled的存在性作为验证依据测试代码。按钮主题样式btnLevel 与 btnActiveLevel配置btnLevel统一设置所有按钮的主题样式配置btnActiveLevel为按钮设置激活态选中态的主题样式。注意buttons或options中每个选项自己的level属性优先级高于btnLevel{ type: form, api: /api/mock2/form/saveForm, debug: true, body: [ { type: button-group-select, label: 选项, name: type, btnLevel: light, btnActiveLevel: warning, options: [ {label: Option A, value: a}, {label: Option B, value: b}, {label: Option C, value: c, level: primary} ] } ] }btnLevel与btnActiveLevel的取值范围为link | primary | secondary | info | success | warning | danger | light | dark | default文档标注的默认值均为default。源码中的优先级逻辑非常直白选中按钮的 level 按激活样式 选项自身样式 整体默认样式计算level 计算表达式level: (active ? btnActiveLevel : ) || option.level || btnLevel即按钮处于选中态时优先使用btnActiveLevel未选中时先取选项自己的level再回退到btnLevel。另外若配置了旧版属性btnClassName/btnActiveClassName源码会通过getLevelFromClassName解析出 level 覆盖btnLevel/btnActiveLevelclassName 解析逻辑这两个旧属性在新版中已被标记为废弃。组件类型定义 中也明确注释了deprecated 建议用btnLevel。单测 btnActiveLevel 用例 精确验证了这套优先级在btnLevel: light、btnActiveLevel: warning的配置下选中项value: a最终呈现cxd-Button--warning未选中但带level: primary的项呈现cxd-Button--primary其余项回退为cxd-Button--light。支持角标按钮可支持角标在options的单个选项中配置badge即可。badge支持mode: text数字/文字角标与mode: ribbon缎带角标等形态完整属性见 badge 组件文档{ type: form, api: /api/mock2/form/saveForm, debug: true, body: [ { type: button-group-select, label: 选项, name: type, options: [ {label: Option A, value: a}, { label: Option B, value: b, badge: {mode: text, text: 15} }, { label: Option C, value: c, badge: {mode: ribbon, text: HOT} } ] } ] }从源码看角标配置还具备控件级兜底 选项级覆盖的合并能力getBadgeConfig 方法如果控件整体配置了badge则每个选项的badge对象会展开覆盖兜底配置字符串/数字会填充到text字段优先生效未配置控件级badge时直接使用选项自身配置。该能力自2.8.1版本引入。属性表当做选择器表单项使用时除了支持 普通表单项属性表 中的配置以外还支持下面一些配置属性名类型默认值说明版本typestringbutton-group-select指定为 button-group-select 渲染器verticalbooleanfalse是否使用垂直模式tiledbooleanfalse是否使用平铺模式btnLevellink \| primary \| secondary \| info \| success \| warning \| danger \| light \| dark \| defaultdefault按钮样式btnActiveLevellink \| primary \| secondary \| info \| success \| warning \| danger \| light \| dark \| defaultdefault选中按钮样式optionsArrayobject或Arraystring静态选项组option.badgeobject角标2.8.1sourcestring或 API动态选项组multiplebooleanfalse多选labelFieldstringlabel选项标签字段valueFieldstringvalue选项值字段joinValuesbooleantrue拼接值extractValuebooleanfalse提取值autoFillobject自动填充补充几点与源码互相印证的细节source支持字符串 URL、API 对象也支持形如${xxx}的纯变量表达式从数据域取选项labelField/valueField用于指定选项中标签和值的字段名源码渲染按钮文本时即为option[labelField || label]见 渲染逻辑。多选模式下的值格式化由joinValues默认true用delimiter把多个值拼成字符串与extractValue默认false开启后值封装为数组共同决定实现位于 OptionsControlBase 的 formatValueArray / toggleValue 中。单选模式下clearable该控件默认false见 defaultProps允许再次点击已选按钮取消选择。若options与buttons均为空控件会渲染占位文本placeholder 分支配合placeholder属性显示提示文案。事件表当前组件会对外派发以下事件可以通过onEvent来监听这些事件并通过actions来配置执行的动作在actions中可以通过${事件参数名}或${event.data.[事件参数名]}来获取事件产生的数据详细请查看 事件动作。[name]表示当前组件绑定的名称即name属性如果没有配置name属性则通过value取值。事件名称事件参数说明change[name]: string组件的值选中值变化时触发从源码调用链看按钮点击触发handleToggle→ 父层 OptionsControlBase.handleToggle 计算新值后先dispatchOptionEvent(change, {value: newValue})派发change事件支持在 actions 中返回prevented阻塞取值未被阻塞才调用onChange写回表单值。也就是说change事件可以在其他组件的联动动作中被拦截。change{ type: form, debug: true, body: [ { type: button-group-select, label: 选项, name: type, options: [ {label: Option A, value: a}, {label: Option B, value: b}, {label: Option C, value: c} ], onEvent: { change: { actions: [ { actionType: toast, args: { msg: ${event.data.value|json} } } ] } } } ] }动作表当前组件对外暴露以下特性动作其他组件可以通过指定actionType: 动作名称、componentId: 该组件id来触发这些动作动作配置可以通过args: {动作配置项名称: xxx}来配置具体的参数详细请查看 事件动作。动作名称动作配置说明clear-清空reset-将值重置为初始值。6.3.0 及以下版本为resetValuereload-重新加载调用source刷新数据域数据刷新重新加载setValuevalue: string更新的值更新数据其中clear与reset的具体实现在 ButtonGroupControl.doAction 中clear直接调用onChange()清空reset则优先取表单初始值formStore.pristine中该name对应的值取不到再回退到resetValue最后兜底为空字符串。clear{ type: form, debug: true, body: [ { type: button-group-select, label: 选项, name: type, id: clear_type, options: [ {label: Option A, value: a}, {label: Option B, value: b}, {label: Option C, value: c} ], value: b }, { type: button, label: 清空, onEvent: { click: { actions: [ { actionType: clear, componentId: clear_type } ] } } } ] }reset如果配置了resetValue则重置时使用resetValue的值否则使用初始值。{ type: form, debug: true, data: { abc: { type: c } }, body: [ { type: button-group-select, label: 选项, name: type, id: reset_type, options: [ {label: Option A, value: a}, {label: Option B, value: b}, {label: Option C, value: c} ], value: b }, { type: button, label: 重置, onEvent: { click: { actions: [ { actionType: reset, componentId: reset_type } ] } } } ] }reload只有选择器模式支持即配置source用于重新加载选择器的数据源。组件侧的reload方法会透传给 HOC 提供的reloadOptionsreload 透传底层 reloadOptions 实现 会区分纯变量表达式 source重新从数据域取值与接口 source重新请求两种路径。{ type: form, debug: true, body: [ { type: button-group-select, label: 选项, name: type, id: reload_type, source: /api/mock2/form/getOptions?waitSeconds1 }, { type: button, label: 重新加载, onEvent: { click: { actions: [ { actionType: reload, componentId: reload_type } ] } } } ] }setValue{ type: form, debug: true, body: [ { type: button-group-select, label: 选项, name: type, id: setvalue_type, options: [ {label: Option A, value: a}, {label: Option B, value: b}, {label: Option C, value: c} ], value: b }, { type: button, label: 赋值, onEvent: { click: { actions: [ { actionType: setValue, componentId: setvalue_type, args: { value: c } } ] } } } ] }可视化编辑与相关资源除 JSON 配置外amis 可视化编辑器也内置了该组件的插件编辑器插件定义 将组件命名为按钮点选默认脚手架即一份带options的button-group-selectSchema编辑面板中可直接维护选项、btnLevel、事件与动作其事件元数据同样声明了change事件的value参数结构。相关可深入阅读的仓库文件渲染器实现packages/amis/src/renderers/Form/ButtonGroupSelect.tsx选项控件通用 HOCsource 加载、多选、值格式化packages/amis-core/src/renderers/Options.tsx按钮组基础类型定义btnLevel/vertical/tiled 等packages/amis/src/renderers/ButtonGroup.tsx单元测试packages/amis/tests/renderers/Form/buttonGroupSelect.test.tsx按钮组样式packages/amis-ui/scss/components/_button-group.scss【免费下载链接】amis前端低代码框架通过 JSON 配置就能生成各种页面。项目地址: https://gitcode.com/GitHub_Trending/am/amis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考