当前位置：首页 > web >正文

16.ArkUI Toggle的介绍和使用

web 2025/7/1 12:51:27

ArkUI Toggle 组件详解与使用指南

Toggle 是 ArkUI 中用于表示开关状态的交互组件，适用于启用/禁用、显示/隐藏等二元选择场景。以下是 Toggle 组件的详细介绍和使用方法。

基本介绍

Toggle 组件特点：

提供开关样式的二元选择
支持多种样式（勾选框、开关按钮等）
可自定义选中和未选中状态
支持状态变化事件监听

基本使用

1. 基础 Toggle 使用

@Entry
@Component
struct BasicToggleExample {@State isChecked: boolean = falsebuild() {Column({ space: 20 }) {Toggle({ type: ToggleType.Checkbox, isOn: this.isChecked }).onChange((isOn: boolean) => {this.isCheck = isOn})Text(this.isChecked ? '已开启' : '已关闭').fontSize(16)}.width('100%').height('100%').justifyContent(FlexAlign.Center).alignItems(HorizontalAlign.Center)}
}

2. 不同样式的 Toggle

@Entry
@Component
struct StyleToggleExample {@State checkboxState: boolean = false@State switchState: boolean = true@State buttonState: boolean = falsebuild() {Column({ space: 20 }) {// 复选框样式Row() {Text('复选框:')Toggle({ type: ToggleType.Checkbox, isOn: this.checkboxState }).onChange((isOn: boolean) => {this.checkboxState = isOn})}// 开关样式Row() {Text('开关:')Toggle({ type: ToggleType.Switch, isOn: this.switchState }).size({ width: 50, height: 30 }).onChange((isOn: boolean) => {this.switchState = isOn})}// 按钮样式Toggle({ type: ToggleType.Button, isOn: this.buttonState }).width(120).onChange((isOn: boolean) => {this.buttonState = isOn})}.padding(20)}
}

核心功能

1. Toggle 类型

// 复选框样式
Toggle({ type: ToggleType.Checkbox, isOn: false })// 开关样式
Toggle({ type: ToggleType.Switch, isOn: true })// 按钮样式
Toggle({ type: ToggleType.Button, isOn: false })

2. 状态控制

@State isActive: boolean = falsebuild() {Toggle({ type: ToggleType.Switch, isOn: this.isActive }).enabled(true) // 是否可交互.onChange((isOn: boolean) => {this.isActive = isOn})
}

3. 自定义样式

Toggle({ type: ToggleType.Switch, isOn: this.isOn }).selectedColor('#FF0000') // 选中状态颜色.switchPointColor('#FFFFFF') // 开关按钮颜色.width(60).height(30)

高级功能

1. 自定义 Toggle 内容

@Builder
toggleText(isOn: boolean) {Text(isOn ? 'ON' : 'OFF').fontColor(isOn ? '#FFFFFF' : '#000000')
}build() {Toggle({ type: ToggleType.Button, isOn: this.isOn }).width(100).height(40).selectedColor('#1890FF').backgroundColor('#EEEEEE').builder(this.toggleText)
}

2. 与其它组件联动

@Entry
@Component
struct ToggleLinkExample {@State isDarkMode: boolean = falsebuild() {Column() {Row() {Text('深色模式')Toggle({ type: ToggleType.Switch, isOn: this.isDarkMode }).onChange((isOn: boolean) => {this.isDarkMode = isOn})}// 根据Toggle状态显示不同内容if (this.isDarkMode) {Text('当前为深色模式').fontColor('#FFFFFF').backgroundColor('#333333')} else {Text('当前为浅色模式').fontColor('#000000').backgroundColor('#FFFFFF')}}.width('100%').height('100%').backgroundColor(this.isDarkMode ? '#222222' : '#F5F5F5')}
}

3. 动态 Toggle 列表

@Entry
@Component
struct DynamicToggleExample {@State settings = [{ name: '消息通知', enabled: true },{ name: '夜间模式', enabled: false },{ name: '自动更新', enabled: true }]build() {List() {ForEach(this.settings, (item, index) => {ListItem() {Row() {Text(item.name)Blank()Toggle({ type: ToggleType.Switch, isOn: item.enabled }).onChange((isOn: boolean) => {this.settings[index].enabled = isOn})}}})}}
}

最佳实践

明确标签：为每个 Toggle 提供清晰的文本说明
合理样式：根据场景选择合适的 Toggle 类型
即时反馈：状态变化应产生明显的视觉反馈
无障碍设计：确保足够的颜色对比度和可操作区域
性能优化：避免在 onChange 中执行耗时操作

实际应用示例

1. 设置项开关

@Entry
@Component
struct AppSettings {@State notificationsEnabled: boolean = true@State locationEnabled: boolean = false@State darkModeEnabled: boolean = falsebuild() {List({ space: 10 }) {ListItem() {Row() {Text('消息通知')Blank()Toggle({ type: ToggleType.Switch, isOn: this.notificationsEnabled }).onChange((isOn: boolean) => {this.notificationsEnabled = isOn})}}ListItem() {Row() {Text('位置服务')Blank()Toggle({ type: ToggleType.Switch, isOn: this.locationEnabled }).onChange((isOn: boolean) => {this.locationEnabled = isOn})}}ListItem() {Row() {Text('深色模式')Blank()Toggle({ type: ToggleType.Switch, isOn: this.darkModeEnabled }).onChange((isOn: boolean) => {this.darkModeEnabled = isOn})}}}.width('100%').height('100%')}
}

2. 任务列表

@Entry
@Component
struct TaskList {@State tasks = [{ id: 1, name: '完成项目设计', completed: false },{ id: 2, name: '编写开发文档', completed: true },{ id: 3, name: '测试功能模块', completed: false }]build() {Column() {ForEach(this.tasks, (task, index) => {Row() {Toggle({ type: ToggleType.Checkbox, isOn: task.completed }).onChange((isOn: boolean) => {this.tasks[index].completed = isOn})Text(task.name).fontSize(16).fontColor(task.completed ? '#999999' : '#000000').decoration({ type: task.completed ? TextDecorationType.LineThrough : TextDecorationType.None }).margin({ left: 10 })}.padding(10).borderRadius(5).backgroundColor(task.completed ? '#F5F5F5' : '#FFFFFF')})}.padding(20)}
}