跳到主要内容

开关

WdSwitch

适用场景

用于控制是和否(布尔值)。

基础能力说明

1、绑定「布尔值」类型字段,表单容器绑定数据模型后,模型中的布尔值会自动渲染为开关组件,实现是和否的控制。可配置开关的初始状态(开启/关闭)、组件尺寸(PC 端生效,在移动端不生效)。

2、支持标题的个性化配置,包含标题的内容、对齐方式、是否换行(开启时,标题字数超过一行时换行展示;关闭时,标题字数超过一行时省略展示)、标题位置、宽度、和标题的提示语。

3、支持开关按钮的个性化配置,包含开关按钮的下方提示、移动端是否展示下划线。

注:

  • 开关按钮的尺寸配置仅针对 PC 端生效;
  • 如果组件在表单容器中,组件尺寸,标题对齐、位置、换行、宽度默认会跟随表单容器的属性配置

了解更多的表单组件使用场景,可查阅 表单常见场景实践指南

示例

交互式预览

不同类型的开关

不同排版的开关

开关禁用效果

开关必填图标、标题提示、下方提示等

样式 API 自定义样式

#wd-page-root .wd-form-item .wd-switch.is-checked .wd-switch__box {
background-color: green;
}

属性

组件接收的外部传入的属性

属性名
属性标识
类型
说明
显示标题labelVisibleboolean

默认值:true

标题对齐labelAlignstring

表单场景下默认会跟随表单容器的标题对齐配置

标题换行labelWrapboolean

如果标题内容过长关闭时只显示一行、溢出省略;开启时换行展示。表单场景下默认会跟随表单容器的标题换行配置

标题位置layoutstring

设置标题在表单组件的展示位置,表单场景下默认会跟随表单容器的标题的位置配置

标题宽度labelWidthstring

您可以输入数值 + px、%等单位,示例:200px

表单场景下默认会跟随表单容器的标题宽度配置

标题提示labelTipsstring

PC/H5端生效

配置标题的工具提示内容

下方提示extrastring

配置后提示内容常显在组件下方

移动端显示下划线borderedH5boolean

关闭后移动端不显示底部下划线

示例:true

必填requiredboolean

启用后该组件强制必填,值不可为空

示例:false

必填标识requiredFlagboolean

启用后,组件若要求必填,则会显示必填星号标记

示例:true

必填校验提示requiredMsgstring

启用必填,但组件值为空时的提示信息

示例:"该项为必填项"

状态statusstring

示例:"edit"

绑定字段namestring

表单字段的Key值,用于提交数据时,匹配数据模型字段标识。页面内需保证唯一。

标题内容labelstring

示例:"标题"

开关状态valueboolean

默认开关状态

示例:false

组件尺寸(PC端)sizestring

开关的尺寸大小,仅在PC端生效

示例:""

事件

组件暴露的事件,可以监听组件的事件来触发一些外部的动作

事件名
事件code
事件出参 event.detail
适用情况
说明
值改变changeobject
  • value: boolean

    所选开关状态

兼容三端

-

属性 API

通过属性 API,可以获取组件内部的状态和属性值,可以通过$w.componentId.propertyName 来访问组件内部的值,如 $w.input1.value ,详请请参考 属性 API

只读属性名
属性标识
类型
说明
绑定字段namestring

表单字段的Key值,用于提交数据时,匹配数据模型字段标识。页面内需保证唯一。

标题内容labelstring
开关状态valueboolean

默认开关状态

必填requiredboolean

启用后该组件强制必填,值不可为空

是否展示visibleboolean

组件是否展示

是否禁用disabledboolean

组件是否禁用

是否只读readOnlyboolean

组件是否只读

方法 API

通过方法 API,可以通过程序触发组件内部的方法,比如提交表单,显示弹窗等, 可以通过$w.componentId.methodName来调用组件方法,如 $w.form1.submit()

方法名
方法标识
参数
方法说明
设置值setValueboolean

通过 $w.id1.setValue("weda") 设置组件值

设置显隐setVisibleboolean显示

通过 $w.id1.setVisible(false) 设置组件为隐藏

设置禁用setDisabledboolean禁用

通过 $w.id1.setDisabled(true) 设置组件为禁用

清空值clearValue

通过 $w.id1.clearValue() 清空组件值

设置只读setReadOnlyboolean只读

通过 $w.id1.setReadOnly(true) 设置组件为只读

触发校验handleValidate

通过 $w.id1.handleValidate() 校验组件值

清除校验clearValidate

通过 $w.id1.clearValidate() 清除组件校验

样式 API

通过样式 API,可以覆盖组件中内部元素的样式来实现自定义,例如在低代码编辑器中中通过 #wd-page-root .wd-btn 即可为所有的按钮组件编写样式,详请请参考样式 API

名称
类名
说明
根元素.wd-switch-root组件最外层元素
H5 端根元素.wd-h5-switch-root可设定 H5 端的根元素样式
PC 端根元素.wd-pc-switch-root可设定 PC 端的根元素样式
小程序端根元素.wd-mp-switch-root可设定小程序端的根元素样式
无边框状态.wd-switch-root.is-borderless设置组件无边框状态样式
必填状态.wd-switch-root.is-required设置组件必填状态样式
标题.wd-switch__label组件标题元素
标题禁用状态.wd-switch__label.is-disabled设置组件标题禁用状态样式
标题不换行.wd-switch__label.is-nowrap设置组件标题不换行时状态样式
提示文字.wd-switch__help设置组件提示文字样式
校验信息.wd-switch__error设置组件校验信息样式
组件本身.wd-switch组件本身元素
禁用状态.wd-switch.is-disabled组件禁用状态
只读状态.wd-switch.is-disabled组件只读状态
勾选状态.wd-switch.is-checked勾选状态
小尺寸.wd-switch.size-sm小尺寸样式(仅PC端有效)
默认尺寸.wd-switch.size-md默认、中尺寸样式(仅PC端有效)
大尺寸.wd-switch.size-lg大尺寸样式
开关背景.wd-switch__box开关内部背景元素
开关按钮.wd-switch__box::before开关内部按钮元素

了解样式 API

版本变化

  • 属性变化
  • 样式变化
  • widget api 变化