ArkUI Toggle：一个开关讲清楚，页面少一半误会

这篇我们写 Toggle。开关控件看起来很小，但它很容易被用乱：有的地方明明是确认项，却做成开关；有的地方是普通按钮，却伪装成 Toggle。

所以这个案例不写设置保存，也不讲状态同步。我们先把 Toggle 自己的三种形态看清楚：Switch、Checkbox、Button。

参考文档：

• https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkui
• https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-ui-development

Switch 适合持续开关

Switch 最适合“打开后持续生效”的设置，比如消息提醒、自动同步、深色模式。

Toggle({ type: ToggleType.Switch, isOn: true })
  .selectedColor('#0F766E')
  .switchPointColor('#FFFFFF')

type 决定它是哪种 Toggle。isOn 决定初始开关状态。

selectedColor 是选中颜色，switchPointColor 是滑块颜色。这个组合放在设置项里，会比只丢一个默认开关更有页面一致性。

但 Switch 旁边的文案一定要说清楚。比如“消息提醒”下面写“打开后接收评论、点赞和系统通知”，用户就知道开了会发生什么。

Checkbox 形态适合确认项

ToggleType.Checkbox 看起来像勾选框，语义也更接近“我选择了这个选项”。

Toggle({ type: ToggleType.Checkbox, isOn: true })
  .selectedColor('#7C3AED')

像“我已阅读并理解说明”“同时发送一份到邮箱”，用勾选框就比较自然。

这类内容不建议用 Switch。因为它不是一个长期持续的开关，只是用户当前这次操作里的一个确认或附加选择。

Button 形态不是普通按钮

ToggleType.Button 很容易被误用。它看起来像按钮，但本质还是 Toggle：有开和关两种状态。

Toggle({ type: ToggleType.Button, isOn: true })
  .height(40)
  .width(96)
  .selectedColor('#C2410C')
  .borderRadius(20)

案例里放了两个按钮形态，一个打开，一个关闭。它适合“专注模式”“公开展示”这种模式切换。

它不适合“保存”“提交”“删除”。这些是动作按钮，应该交给 Button，不要为了视觉新鲜感硬塞进 Toggle。

禁用态别只变灰

开关不能操作时，禁用态要让用户一眼看懂，还要顺手解释原因。

Toggle({ type: ToggleType.Switch, isOn: true })
  .selectedColor('#64748B')
  .switchPointColor('#FFFFFF')
  .enabled(false)

案例里的文案是“当前由管理员统一配置，个人账号暂时不能修改”。这比只把开关变灰更友好。

如果不解释，用户会以为页面坏了，或者以为自己没点准。

看案例时盯这几处

打开案例页后，可以顺着这几个点看：

• Switch 是否用在持续开关场景。
• Checkbox 是否更像确认项，而不是长期设置。
• Button 形态是否仍然表达“开/关”，没有冒充普通按钮。
• 禁用态是否明显不能操作，并且文案解释了原因。

这篇不跑 hvigor。你在 DevEco Studio 里打开案例页，看三种形态的差别就够了。

如果你项目里有设置页，可以先挑一项判断：它到底是持续开关、一次确认，还是普通动作？你们最容易混的是哪一种，通知开关、协议勾选，还是“看起来像按钮”的模式切换？

完整示例代码

文件位置：entry/src/main/ets/pages/arkUI/basic/ArkUIToggleDemo.ets

@Entry
@Component
struct ArkUIToggleDemo {
  @Builder
  sectionTitle(title: string, desc: string) {
    Column({ space: 4 }) {
      Text(title)
        .width('100%')
        .fontSize(16)
        .fontWeight(700)
        .fontColor('#0F172A')

      Text(desc)
        .width('100%')
        .fontSize(13)
        .fontColor('#64748B')
        .lineHeight(20)
    }
    .width('100%')
    .alignItems(HorizontalAlign.Start)
  }

  @Builder
  settingText(title: string, desc: string) {
    Column({ space: 4 }) {
      Text(title)
        .width('100%')
        .fontSize(15)
        .fontWeight(700)
        .fontColor('#0F172A')

      Text(desc)
        .width('100%')
        .fontSize(12)
        .fontColor('#64748B')
        .lineHeight(18)
    }
    .alignItems(HorizontalAlign.Start)
    .layoutWeight(1)
  }

  @Builder
  switchRow(title: string, desc: string, isOn: boolean, enabled: boolean, color: string) {
    Row({ space: 12 }) {
      this.settingText(title, desc)

      Toggle({ type: ToggleType.Switch, isOn: isOn })
        .selectedColor(color)
        .switchPointColor('#FFFFFF')
        .enabled(enabled)
    }
    .width('100%')
    .height(64)
    .padding({ left: 14, right: 14, top: 12, bottom: 12 })
    .backgroundColor(enabled ? '#FFFFFF' : '#E2E8F0')
    .border({ width: 1, color: enabled ? '#E2E8F0' : '#CBD5E1' })
    .borderRadius(8)
  }

  build() {
    Scroll() {
      Column({ space: 18 }) {
        Text('ArkUI Toggle')
          .width('100%')
          .fontSize(24)
          .fontWeight(700)
          .fontColor('#0F172A')

        Text('一个开关讲清楚，页面少一半误会')
          .width('100%')
          .fontSize(22)
          .fontWeight(700)
          .fontColor('#111827')

        Text('这一页只看 Toggle 自己：开关、勾选、按钮三种形态怎么摆，什么时候别滥用，以及禁用态怎么让用户一眼看懂。')
          .width('100%')
          .fontSize(14)
          .fontColor('#64748B')
          .lineHeight(22)

        Column({ space: 12 }) {
          this.sectionTitle('Switch 适合明确的开和关', '像通知、自动同步、深色模式这种二选一设置，用 Switch 最顺手。文案要说清打开之后会发生什么。')

          this.switchRow('消息提醒', '打开后接收评论、点赞和系统通知。', true, true, '#0F766E')
          this.switchRow('夜间自动切换', '到指定时间后自动切到深色主题。', false, true, '#2563EB')
        }
        .width('100%')
        .padding(16)
        .backgroundColor('#F0FDFA')
        .borderRadius(8)

        Column({ space: 12 }) {
          this.sectionTitle('Checkbox 形态适合确认项', '它看起来像勾选框，更适合“我已阅读”“同时发送副本”这种确认语义。')

          Row({ space: 12 }) {
            Toggle({ type: ToggleType.Checkbox, isOn: true })
              .selectedColor('#7C3AED')

            this.settingText('我已阅读并理解说明', '这类文案不建议用 Switch，因为它不是持续开关，而是一次确认。')
          }
          .width('100%')
          .height(64)
          .padding({ left: 14, right: 14, top: 12, bottom: 12 })
          .backgroundColor('#FFFFFF')
          .border({ width: 1, color: '#E9D5FF' })
          .borderRadius(8)

          Row({ space: 12 }) {
            Toggle({ type: ToggleType.Checkbox, isOn: false })
              .selectedColor('#7C3AED')

            this.settingText('同时发送一份到邮箱', '这个选择是附加动作，用勾选比用开关更轻。')
          }
          .width('100%')
          .height(64)
          .padding({ left: 14, right: 14, top: 12, bottom: 12 })
          .backgroundColor('#FFFFFF')
          .border({ width: 1, color: '#E9D5FF' })
          .borderRadius(8)
        }
        .width('100%')
        .padding(16)
        .backgroundColor('#F5F3FF')
        .borderRadius(8)

        Column({ space: 12 }) {
          this.sectionTitle('Button 形态别拿来装普通按钮', 'ToggleType.Button 还是开关，只是看起来像按钮。适合“开/关某个模式”，不适合提交、保存、删除。')

          Row({ space: 10 }) {
            Toggle({ type: ToggleType.Button, isOn: true })
              .height(40)
              .width(96)
              .selectedColor('#C2410C')
              .borderRadius(20)

            Toggle({ type: ToggleType.Button, isOn: false })
              .height(40)
              .width(96)
              .selectedColor('#C2410C')
              .borderRadius(20)
          }
          .width('100%')

          Text('左边是打开的按钮形态，右边是关闭的按钮形态。它们还是 Toggle，不是普通 Button。')
            .width('100%')
            .fontSize(13)
            .fontColor('#64748B')
            .lineHeight(20)
        }
        .width('100%')
        .padding(16)
        .backgroundColor('#FFF7ED')
        .borderRadius(8)

        Column({ space: 12 }) {
          this.sectionTitle('禁用态要解释为什么不能改', '开关不能操作时，旁边文案最好顺手说明原因，别只把控件变灰。')

          this.switchRow('企业策略控制', '当前由管理员统一配置，个人账号暂时不能修改。', true, false, '#64748B')
        }
        .width('100%')
        .padding(16)
        .backgroundColor('#F8FAFC')
        .borderRadius(8)
      }
      .width('100%')
      .padding(20)
      .alignItems(HorizontalAlign.Start)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#FFFFFF')
  }
}