switch 开关

switch 可以切换布尔类型的开关。

XML 元素

switch

Java 类

Switch

基本用法

在线示例

switch 与 checkbox 组件类似，但可以更加直观地展示二进制状态。开关适合用于

  • 在两个相互排斥的选项（例如on/off）之间切换。

  • 提供即时的视觉反馈。

  • 启用或禁用立即生效的设置。

而 checkbox 和 checkboxGroup 组件更适合下面的场景：

  • 从列表中选择一个或多个选项。

  • 允许多个非排他性选择。

  • 选择后不会立即生效的场景。

switch 的基本示例：

<switch id="carField" label="I have a car"/>

数据感知的 switch

在线示例

使用 dataContainer 和 property 属性将 switch 与实体的 Boolean 属性绑定。数据容器提供实体实例，property 表示需要使用该组件编辑的属性。

下面的示例生成了一个数据感知的 switch。实体属性必须为 Boolean 类型。

XML
<data>
    <instance id="customerDc"
              class="io.jmix.uisamples.entity.Customer"
              fetchPlan="_local"/>
</data>
<layout>
    <switch id="activeSwitch"
              label="Switch connected to a container"
              dataContainer="customerDc"
              property="active"/>
    <hbox>
        <span text="Value in the container:"/>
        <span id="spanValue"/>
    </hbox>
</layout>
Java
@ViewComponent
private InstanceContainer<Customer> customerDc;
@ViewComponent
private Span spanValue;

@Autowired
private Metadata metadata;

@Subscribe
public void onInit(InitEvent event) {
    Customer customer = metadata.create(Customer.class);
    customer.setActive(true);
    customerDc.setItem(customer);
}

@Subscribe("activeSwitch")
private void onActiveSwitchValueChange(ComponentValueChangeEvent<Switch, Boolean> changeEvent) {
    spanValue.setText(customerDc.getItem().isActive().toString());
}

状态

switch 有以下几种状态，不同的状态具有不同的外观和功能。

启用

  • 禁用：switch 处于非激活状态，无法与用户交互。通常显示为灰色，表示已禁用。

  • 启用：switch 可进行交互并响应用户的输入。用户可以通过点击改变组件的状态。

<switch label="Enable Dark Mode"
        value="true"
        enabled="false"/>
<switch label="Enable Dark Mode"
        value="true"
        enabled="true"/>

只读

readOnly 属性控制用户是否可以更改组件的状态。如果设置为 true，则 checkbox 为只读状态，用户无法更改状态。

<switch label="Enable Dark Mode"
        value="true"
        readOnly="false"/>
<switch label="Enable Dark Mode"
        value="true"
        readOnly="true"/>

必填

switch 也可以通过 required 配置或绑定一个带 @NotNull 验证的必需属性设置为必填项。

当该组件标记为必填时，组件标签附近会显示一个指示器，提示用户必须选择。如果 switch 默认开启（已选择），然后被关闭（取消选择），则该组件会标记为无效，直至满足必填条件。

与输入字段类似，只有当 switch 非空（即勾选）时才能通过 @NotNull 验证。该行为的默认值可以通过 jmix.ui.component.checkbox-required-state-initialization-enabled 属性修改，以支持非选择状态为 false。

XML 属性

下面是 switch 的特殊属性：

名称 描述 默认值

enabled

设置组件启用或禁用。参阅 启用状态。

true

readOnly

设置 switch 为只读模式。参阅 只读状态。

false

required

设置 switch 的必填状态。参阅 必填状态。

false

value

设置组件值。

—

下面是 switch 支持的其他通用属性：

id - alignSelf - ariaLabel - ariaLabelledBy - autofocus - classNames - clickShortcut - colspan - css - dataContainer - errorMessage - focusShortcut - height - helperText - label - maxHeight - maxWidth - minHeight - minWidth - property - requiredMessage - tabIndex - visible - width

事件和处理器

下面是 switch 的特殊事件和处理器：

名称 描述

ClickEvent

当用户点击组件是触发。

下面是 switch 支持的其他通用事件：

AttachEvent - BlurEvent - ComponentValueChangeEvent - DetachEvent - FocusEvent

XML 内部元素

一个 switch 可以包含 tooltip 作为其内部元素。