鸿蒙开发中切换按钮（Toggle/Switch）的详细使用

本文同步发表于我的微信公众号，微信搜索 程语新视界 即可关注，每个工作日都有文章更新

以下是鸿蒙开发中切换按钮（Toggle/Switch）的详细使用，结合官方文档和最佳实践，从基础到高级进行全面讲解，并附带代码示例和标注：

一、核心组件对比

组件	Toggle	Switch
功能定位	支持多种样式（按钮/复选框/开关）	仅支持开关样式
API版本	全版本支持	需API 9+
自定义能力	更强（支持子组件和样式扩展）	基础样式修改

二、Toggle组件详解

1. 基础创建

@Entry
@Component
struct ToggleExample {
  @State isChecked: boolean = false

  build() {
    Column() {
      // 开关样式
      Toggle({ type: ToggleType.Switch, isOn: this.isChecked })
      
      // 复选框样式（API 11+默认圆形）
      Toggle({ type: ToggleType.Checkbox, isOn: true })
      
      // 按钮样式（可包含子组件）
      Toggle({ type: ToggleType.Button, isOn: false }) {
        Text('启用功能').fontSize(16)
      }.width(120)
    }
  }
}

关键属性：

• type: 指定样式类型（Switch/Checkbox/Button）
• isOn: 初始化状态 

2. 状态控制与事件

Toggle({ type: ToggleType.Switch, isOn: this.isChecked })
  .onChange((isOn: boolean) => {
    promptAction.showToast({
      message: isOn ? "已开启" : "已关闭"
    })
    this.isChecked = isOn // 同步状态
  })

方法说明：

• onChange: 状态变化回调

3. 样式定制

// 修改选中背景色
Toggle({ type: ToggleType.Switch, isOn: true })
  .selectedColor(Color.Pink)

// 修改滑块颜色（仅Switch类型有效）
  .switchPointColor(Color.Blue)

// 自定义尺寸
  .size({ width: 80, height: 40 })

样式API：

• selectedColor(): 选中状态背景色
• switchPointColor(): 滑块颜色 

三、Switch组件专用功能

1. XML属性配置

<Switch
  ohos:text_state_on="开启"
  ohos:text_state_off="关闭"
  ohos:track_element="#FF87CEFA"
  ohos:thumb_element="#FF1E90FF"
/>

特有属性：

• text_state_on/off: 状态文本
• track_element: 轨道样式
• thumb_element: 滑块样式 

2. 动态样式设置（Java）

// 设置滑块样式
ShapeElement thumbOn = new ShapeElement();
thumbOn.setShape(ShapeElement.OVAL);
thumbOn.setRgbColor(RgbColor.fromArgbInt(0xFF1E90FF));

// 应用状态样式
StateElement trackElement = new StateElement();
trackElement.addState(new int[]{ComponentState.COMPONENT_STATE_CHECKED}, trackOn);
switchComponent.setTrackElement(trackElement);

原理：通过StateElement管理不同状态样式

3. 自定义滑块图标（API 12+）

@Builder
function customThumb(isOn: boolean) {
  Image(isOn ? $r('app.media.thumb_on') : $r('app.media.thumb_off'))
    .width(24)
    .height(24)
}

Toggle({ type: ToggleType.Switch, isOn: this.isOn })
  .thumbBuilder(customThumb) // 自定义滑块

版本兼容性： 

• thumbBuilder需API 12+
• XML属性仅支持Java UI

四、案例

1. 设置项开关控制

@Entry
@Component
struct SettingsPage {
  @State notificationsEnabled: boolean = true

  build() {
    Column() {
      Row() {
        Text("消息通知")
        Toggle({ 
          type: ToggleType.Switch,
          isOn: this.notificationsEnabled 
        }).margin({ left: 20 })
      }
    }
  }
}

2. 多选项组

@Entry
@Component
struct SurveyForm {
  @State selections: boolean[] = [false, false, false]

  build() {
    List() {
      ForEach(this.selections, (item, index) => {
        ListItem() {
          Toggle({ 
            type: ToggleType.Checkbox,
            isOn: item 
          }).onChange((v) => this.selections[index] = v)
          Text(`选项${index+1}`)
        }
      })
    }
  }
}

五、注意事项

1. 版本差异：

   • Checkbox样式在API 11+变为圆形 
   • Switch的thumb_element需API 9+ 

2. 性能优化：

   • 避免在ForEach中频繁更新Toggle状态
   • 复杂样式建议使用StateElement缓存

3. 交互一致性：

   • 同组单选建议使用Radio组件
   • Toggle按钮需明确状态标识（如附加文字）