跳到内容
CrossFly 是 100% 开源在 GitHub 关注我们
CrossFlyCrossFly
开始使用

本页面由葡萄牙语机器翻译，可能存在错误。葡萄牙语版本为准。

Switch

Switch 是一个开/关切换器，带有圆角轨道和一个“thumb”（滑动按钮），thumb 以动画方式在 off 和 on 状态之间滑动。它接受一个可选的旁置文本标签，以及在过渡时进行淡入淡出交叉的 on/off 图标。它是以 iOS/Material 风格立即启用/禁用某个偏好设置的理想控件。

🟢 · 包： dev.crossfly.ui · 继承： Component（实现 Checkable、AlphaAnimation.Animate） · 样式： SwitchStyle

何时使用

  • 具有即时效果地开/关单个偏好设置（例如“启用通知”）。
  • 用户期待一个可视化 toggle 而非勾选框的场合。

何时不使用

  • 从同时可见的多个选项中选择 → 在 group 内使用 option。
  • 更大的选项列表 → 使用 dropdown。

外观

圆角轨道（trackRadius = trackH/2）加上一个方形 thumb，thumb 从 thumbMinX（off）移动到 thumbMaxX（on）。宽度、轨道高度和 thumb 大小与字体高度成比例（SwitchStyle 的 switchWidth、trackHeight、thumbSizeRatio）。可选的标签位于切换器旁边；当 iconAlignH == END 时 switch 在右、文本在左，否则文本在右。

完整示例（复制、粘贴并运行）

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      // 反映 switch 状态的 Label
      Label saida = new Label("Recurso: desligado");
      add(LAY_AUTO, saida);

      // 带标签的 Switch；onAction 只在状态改变时触发
      Switch toggle = new Switch("Ativar recurso");
      toggle.checked(false);   // 初始状态，无动画
      toggle.onAction(c -> saida.setText("Recurso: " + (toggle.checked ? "ligado" : "desligado")));
      add(LAY_AUTO, toggle);
   }
}

下面的片段只展示核心部分（放入 onShow() 内的内容）。要运行它们，请将它们放入上面的 MainWindow 骨架中。

基本用法

Switch toggle = new Switch("Ativar recurso");
toggle.checked(true);                                  // 初始状态，无动画
toggle.onAction(c -> System.out.println("estado: " + toggle.checked));
container.add(LAY_AUTO, toggle);

构造函数

构造函数 描述
Switch() 未选中，无标签（仅图标模式）。
Switch(String text) 未选中，带旁置标签。

属性与自定义

属性 / 方法 类型 默认值 作用
text(String) Switch（流式） null 设置标签。
checked(boolean) Switch（流式） false 无动画的初始状态（直接调整 progress）；通知分组。
setChecked(boolean) void — 带动画的状态；通知分组。
toggle() void — 切换状态（尊重分组）。
checked boolean（字段） false 当前逻辑状态（只读）。
progress float（字段） 0 thumb 的插值位置：0 = off，1 = on。
.group(Group) Switch（流式） — 关联到一个 group 以实现互斥。

回调与事件

回调 何时触发
onAction(Action) 在 onTouchUp 时，仅当状态（checked）发生变化时。

状态

  • checked / unchecked：由 checked(boolean)（无动画）或 setChecked(boolean)（带动画）控制。checked 字段反映状态。
  • 动画中：progress 通过 AlphaAnimation 从 0 过渡到 1（或反之）（持续时间 = style.animationDuration）。
  • 在分组中：toggle() 不会取消选中一个已选中且属于某分组的 switch（单选行为）。

一个 Group 中多个互斥的 switch（单选）

Group modo = new Group();

Switch claro  = new Switch("Tema claro").group(modo).checked(true);
Switch escuro = new Switch("Tema escuro").group(modo);

container.add(LAY_AUTO, claro);
container.add(LAY_AUTO, escuro);
// 勾选一个会自动取消勾选另一个。

最佳实践

  • 对于初始状态优先使用 checked(boolean)（一次性调整 progress 和分组）；当你想要运行时的动画过渡时使用 setChecked。
  • 在 onAction 内通过 isChecked() 或 checked 字段读取状态。

常见错误

  • 期待 onAction 在每次交互时都触发：它只在 checked 变化时触发。
  • 试图通过点击一个 Group 内已选中的 switch 来“关闭”它：toggle() 会阻止这一点（单选）。

另见

这个页面有帮助吗？