Skip to main content
Supported Regions:上海

Switch

WdSwitch

Applicable Scenarios​

Used to control true and false (Boolean values).

Basic Capabilities Description​

  1. Bind to a field of the "Boolean value" type. After the form container is bound to the data model, Boolean values in the model will be automatically rendered as switch components to control true/false states. The initial state of the switch (enabled/disabled) and component size (effective on PC, not on mobile) can be configured.

  2. Supports personalized configuration for titles, including title content, alignment, whether to wrap text (when enabled, the title wraps to the next line if it exceeds one line; when disabled, the title is truncated if it exceeds one line), title position, width, and tooltip text.

Image 1f8c441408179cfb9ab45a9ad2ad3e72
  1. Supports personalized configuration for the switch button, including the tooltip below the switch button and whether to display an underline on mobile devices.
Image 38256963553c10683085c56af8d889f7

Note:

  • The size configuration of the switch button is only effective on PC.
  • If a component is within a form container, its size, title alignment, position, line wrapping, and width will default to the property configuration of the form container

To learn more about form component usage scenarios, refer to the Form Common Scenario Practice Guide

Example​

Interactive Preview​

Different Types of Switches​

Different Layouts of Switches​

Switch Disabled State​

Required Indicator, Title Hint, Hint Below, etc.​

Style API Custom Styles​

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

Properties​

External properties received by the component

Property Name
Property Identifier
Type
Description
Display HeadlineslabelVisibleboolean

Default value: true

Title alignmentlabelAlignstring

In the scenario, the form by default follows the title alignment configuration of the form container.

Line break in headinglabelWrapboolean

If the title content is too long when closed, show one line with overflow omitted; when enabled, show with line breaks. In form scenarios, it follows the form container's title line break configuration by default.

Title positionlayoutstring

Set title display position in form component. In the scenario, it follows the title position configuration of the form container by default.

Title widthlabelWidthstring

You can enter a value with units such as px or %, for example: 200px.

In the scenario, the form follows the title width configuration of the form container by default.

Heading NotelabelTipsstring

Take effect on PC/H5

Configure tooltip content for the heading

Prompt.extrastring

Prompt content is displayed below the component after configuration.

Display underscore on mobile terminalborderedH5boolean

After closing, the mobile terminal does not show the bottom underline

Example: true

Requiredrequiredboolean

Enable required for this component, value cannot be empty

Example: false

Required identifierrequiredFlagboolean

Enabled, the component will display a required asterisk tag if mandatory.

Example: true

Required validation noterequiredMsgstring

Enable required, prompting message when component value is empty

Example: "该项为必填项"

Status.statusstring

Example: "edit"

Bound fieldnamestring

The Key of the form field is used to match the field identifier of the data model when submitting data. Ensure uniqueness inline.

Title content.labelstring

Example: "标题"

Enabling statusvalueboolean

Default switch status

Example: false

Component size(PC)sizestring

Switch dimension size, takes effect on PC only

Example: ""

Events​

Events exposed by the component. You can listen to component events to trigger external actions

Event Name
Event Code
Event Output Parameters event.detail
Applicable Scenarios
Description
value changechangeobject
  • value: boolean

    所选开关状态
Compatible with all platforms

-

Properties API​

Through the Property API, you can access the internal state and property values of components. You can access internal values using$w.componentId.propertyName, such as $w.input1.value. For details, please refer to Property API

Read-only Property Name
Property Identifier
Type
Description
Bound fieldnamestring

The Key of the form field is used to match the field identifier of the data model when submitting data. Ensure uniqueness inline.

Title content.labelstring
Enabling statusvalueboolean

Default switch status

Requiredrequiredboolean

Enable required for this component, value cannot be empty

Indicates whether to displayvisibleboolean

Whether to display the component

Whether to disabledisabledboolean

Component Disabled

Specify whether it is read-only or not.readOnlyboolean

Whether the component is read-only

Method API​

Through the Method API, you can programmatically trigger internal methods of components, such as submitting forms, displaying popups, etc. You can call component methods using $w.componentId.methodName, such as $w.form1.submit()

Method Name
Method Identifier
Parameters
Method Description
set valuesetValueboolean值

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

Show/Hide SettingssetVisibleboolean显示

Set the component to hidden via $w.id1.setVisible(false)

Set DisabledsetDisabledboolean禁用

Set the component to disabled with $w.id1.setDisabled(true)

Clear valueclearValue

Clear the component value with $w.id1.clearValue()

Set as read-onlysetReadOnlyboolean只读

Set the component to read-only via $w.id1.setReadOnly(true)

Trigger validationhandleValidate

Validate the component value via $w.id1.handleValidate()

Clear verificationclearValidate

Clear component validation via $w.id1.clearValidate()

Style API​

Through the Style API, you can override the styles of internal elements in components to achieve customization. For example, in the low-code editor, you can write styles for all button components using #wd-page-root .wd-btn, and control individual component styles with :scope. For detailed instructions, please refer toStyle API

Name
Class Name
Description and Examples
root element.wd-switch-rootOutermost component element
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope.wd-switch-root {
  /* Write CSS styles here */
}
H5 root element.wd-h5-switch-rootSettable root element style for the H5 side
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope.wd-h5-switch-root {
  /* Write CSS styles here */
}
PC-side root element.wd-pc-switch-rootSettable root element style for the PC side
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope.wd-pc-switch-root {
  /* Write CSS styles here */
}
Mini program root element.wd-mp-switch-rootSettable root element style for mini program
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope.wd-mp-switch-root {
  /* Write CSS styles here */
}
Component title style.wd-switch-root .wd-form-item-wrap__labelComponent title element

:scope .wd-form-item-wrap__label {
  font-size: 20px;
  color: gray;
  padding: 0;
  display: flex;
  align-items: center;
}
form control root node style.wd-switch-root .wd-form-item-wrap__controlSet form control root element style

:scope .wd-form-item-wrap__control {
  font-size: 20px;
  color: gray;
  padding: 0;
  display: flex;
  align-items: center;
}
Button style in editing status (selected).wd-switch-root .is-checked .wd-switch__box::beforeButton style in editing status (selected)

      :scope .is-checked .wd-switch__box::before {
        background-color: red;
      }
Editing status - Unselected button style.wd-switch-root .wd-switch__box::beforeEditing status - Unselected button style

      :scope .wd-switch__box::before {
        background-color: gray;
      }
Editing status - Verification information.wd-switch-root .wd-g-text-errorSet component verification information style

:scope .wd-g-text-error {
    font-size: 20px;
    color: gray;
  }
prompt text.wd-switch-root .wd-form-item__help-textSet the text style of the component prompt

:scope .wd-form-item__help-text {
    font-size: 20px;
    color: gray;
  }
Disabled state - Selected button style.wd-switch-root .is-disabled.is-checked .wd-switch__box::beforeDisabled state - Selected button style

      :scope .is-disabled.is-checked .wd-switch__box::before {
        background-color: red;
      }
Disabled state - Unselected button style.wd-switch-root .is-disabled .wd-switch__box::beforeDisabled state - Unselected button style

      :scope .is-disabled .wd-switch__box::before {
        background-color: gray;
      }
read-only status - button select style.wd-switch-root .is-readonly.is-checked .wd-switch__box::beforeread-only status - button select style

      :scope .is-readonly.is-checked .wd-switch__box::before {
        background-color: red;
      }
read-only status - unselected button style.wd-switch-root .is-readonly .wd-switch__box::beforeread-only status - unselected button style

      :scope .is-readonly .wd-switch__box::before {
        background-color: gray;
      }

Learn about Style API

Version Changes​

  • Property Changes
  • Style Changes
  • widget api Changes