组件提供勾选框样式、状态按钮样式和开关样式，适用于需要快速切换状态或进行单选确认的场景，能够有效提升交互体验与界面的直观性。
子组件
仅当ToggleType设置为Button时，可包含子组件。
接口
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
Toggle(options: ToggleOptions)
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
| options | ToggleOptions | 是 | Toggle组件的配置选项，用于配置开关的样式类型和初始状态。 |
ToggleOptions18+对象说明
Phone18+PC/2in118+Tablet18+TV19+Wearable18+
Toggle组件的配置信息。
说明
为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。
卡片能力： 从API version 18开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 18开始，该接口支持在元服务中使用。
模型约束： 此接口仅可在Stage模型下使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
| type8+ | ToggleType | 否 | 否 | 开关的样式。 默认值：ToggleType.Switch 卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。 元服务API： 从API version 11开始，该接口支持在元服务中使用。 |
| isOn8+ | boolean | 否 | 是 | 开关是否打开。 true：打开；false：关闭。 默认值：false 该属性支持$$双向绑定变量。 该属性支持!!双向绑定变量。 卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。 元服务API： 从API version 11开始，该接口支持在元服务中使用。 |
ToggleType枚举说明
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
Toggle的样式。
说明
Toggle的样式继承对应组件样式的默认值，且不支持设置。例如，如果ToggleType为Button，则该组件样式继承ButtonType的默认值。由于Button.type从API version 18开始，默认类型从胶囊型变更为圆角矩形，胶囊型按钮不支持设置borderRadius，此时使用Toggle组件设置borderRadius也不生效。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
| 名称 | 值 | 说明 |
| Checkbox | 0 | 提供勾选框样式。 说明： API version 11开始，Checkbox默认样式由圆角方形变为圆形。 通用属性margin的默认值为： { top: '14px', right: '14px', bottom: '14px', left: '14px' }。 默认尺寸为： {width:'20vp', height:'20vp'}。 |
| Switch | 1 | 提供开关样式。 说明： 通用属性margin的默认值为： { top: '6px', right: '14px', bottom: '6px', left: '14px' }。 默认尺寸为： {width:'36vp', height:'20vp'}。 |
| Button | 2 | 提供状态按钮样式。如子组件设置文本，文本内容将显示在按钮内。默认高度为28vp，宽度无默认值。 |
selectedColor
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
selectedColor(value: ResourceColor)
设置组件在打开状态下的背景颜色。
说明
设置systemMaterial系统材质时对背景色的影响，请参考组件开篇说明。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
| value | ResourceColor | 是 | 组件打开状态的背景颜色。 默认值： 当ToggleType为Switch时，默认值为$r('sys.color.ohos_id_color_emphasize')。 当ToggleType为Checkbox时，默认值为$r('sys.color.ohos_id_color_emphasize')。 当ToggleType为Button时，默认值为$r('sys.color.ohos_id_color_emphasize')混合$r('sys.float.ohos_id_alpha_highlight_bg')的透明度。 |
switchPointColor
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
switchPointColor(color: ResourceColor)
设置Switch类型的圆形滑块颜色。仅当type为ToggleType.Switch生效。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
| color | ResourceColor | 是 | Switch类型的圆形滑块颜色。 默认值：$r('sys.color.ohos_id_color_foreground_contrary') 说明： 同时设置了systemMaterial系统材质时，滑块会出现默认白色的点光源效果，设置此属性后点光源颜色跟随此属性的设置。 |
switchStyle12+
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
switchStyle(value: SwitchStyle)
设置Switch类型的样式。仅当type为ToggleType.Switch生效。
说明
与systemMaterial系统材质同时设置时，请参考组件开篇说明及通用系统材质属性文档。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
模型约束： 此接口仅可在Stage模型下使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
contentModifier12+
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
contentModifier(modifier: ContentModifier<ToggleConfiguration>)
定制Toggle内容区的方法。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
模型约束： 此接口仅可在Stage模型下使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
SwitchStyle12+对象说明
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
Switch类型的样式。
说明
与systemMaterial系统材质同时设置时，请参考组件开篇说明及通用系统材质属性文档。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
模型约束： 此接口仅可在Stage模型下使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
| pointRadius | number | Resource | 否 | 是 | 设置Switch类型的圆形滑块半径，单位为vp。 说明： 不支持百分比，设定值小于0时按照默认算法设置，设定值大于等于0时按照设定值设置。 未设定此属性时，圆形滑块半径根据默认算法设置。 默认算法：（组件高度（单位：vp） / 2） - （2vp * 组件高度（单位：vp） / 20vp）。 |
| unselectedColor | ResourceColor | 否 | 是 | 设置Switch类型关闭状态的背景颜色。 默认值：深色和浅色模式下均为0x337F7F7F。从API version 20开始，如果开启了优化深浅色模式切换开销能力，浅色模式下默认值为0x19000000，表现效果为10%透明度的黑色；深色模式下默认值为0x19FFFFFF，表现效果为10%透明度的白色。 |
| pointColor | ResourceColor | 否 | 是 | 设置Switch类型的圆形滑块颜色。 默认值：$r('sys.color.ohos_id_color_foreground_contrary') |
| trackBorderRadius | number | Resource | 否 | 是 | 设置Switch类型的滑轨的圆角，单位为vp。 说明： 不支持百分比，设定值小于0时按照默认算法设置，设定值大于组件高度一半时按照组件高度一半设置，其他场合按照设定值设置。 未设定此属性时，滑轨圆角根据默认算法设置。 默认算法：组件高度（单位：vp） / 2。 |
onChange
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
onChange(callback: (isOn: boolean) => void)
开关状态切换时触发该事件。
卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
参数：
| 参数名 | 类型 | 必填 | 说明 |
| isOn | boolean | 是 | 开关的状态。 true：状态从关切换为开；false：状态从开切换为关。 |
ToggleConfiguration12+对象说明
Phone12+PC/2in113+Tablet12+TV19+Wearable18+
开发者需要自定义class实现ContentModifier接口。继承自CommonConfiguration。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
模型约束： 此接口仅可在Stage模型下使用。
系统能力： SystemCapability.ArkUI.ArkUI.Full
| 名称 | 类型 | 只读 | 可选 | 说明 |
| isOn | boolean | 否 | 否 | 开关是否打开。 true：开关打开；false：开关关闭。 默认值：false |
| enabled | boolean | 否 | 否 | 是否可以切换状态。 true：可以切换状态；false：不可以切换状态。 默认值：true |
| triggerChange | Callback<boolean> | 否 | 否 | 用于触发Toggle开关状态变化的回调函数，通常在自定义ContentModifier中通过编程方式改变开关状态。调用此回调并传入true可将开关状态设置为打开，传入false可将开关状态设置为关闭。 |
示例
示例1（设置开关的样式）
该示例通过配置ToggleType设置Toggle的勾选框样式、状态按钮样式及开关样式。
// xxx.ets
@Entry
@Component
struct ToggleExample {
build() {
Column({ space: 10 }) {
Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%')
Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
Toggle({ type: ToggleType.Switch, isOn: false })
.selectedColor('#007DFF')
.switchPointColor('#FFFFFF')
.onChange((isOn: boolean) => {
console.info('Component status:' + isOn);
})
Toggle({ type: ToggleType.Switch, isOn: true })
.selectedColor('#007DFF')
.switchPointColor('#FFFFFF')
.onChange((isOn: boolean) => {
console.info('Component status:' + isOn);
})
}
Text('type: Checkbox').fontSize(12).fontColor(0xcccccc).width('90%')
Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
Toggle({ type: ToggleType.Checkbox, isOn: false })
.size({ width: 20, height: 20 })
.selectedColor('#007DFF')
.onChange((isOn: boolean) => {
console.info('Component status:' + isOn);
})
Toggle({ type: ToggleType.Checkbox, isOn: true })
.size({ width: 20, height: 20 })
.selectedColor('#007DFF')
.onChange((isOn: boolean) => {
console.info('Component status:' + isOn);
})
}
Text('type: Button').fontSize(12).fontColor(0xcccccc).width('90%')
Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
Toggle({ type: ToggleType.Button, isOn: false }) {
Text('status button').fontColor('#182431').fontSize(12)
}.width(106)
.selectedColor('rgba(0,125,255,0.20)')
.onChange((isOn: boolean) => {
console.info('Component status:' + isOn);
})
Toggle({ type: ToggleType.Button, isOn: true }) {
Text('status button').fontColor('#182431').fontSize(12)
}.width(106)
.selectedColor('rgba(0,125,255,0.20)')
.onChange((isOn: boolean) => {
console.info('Component status:' + isOn);
})
}
}.width('100%').padding(24)
}
} 
示例2（自定义开关类型的样式）
该示例实现了自定义设置Toggle组件Switch样式，包括圆形滑块半径、关闭状态的背景颜色、圆形滑块颜色、滑轨的圆角。
// xxx.ets
@Entry
@Component
struct ToggleExample {
build() {
Column({ space: 10 }) {
Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%')
Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
Toggle({ type: ToggleType.Switch, isOn: false })
.selectedColor('#007DFF')
.switchStyle({
pointRadius: 15,
trackBorderRadius: 10,
pointColor: '#D2B48C',
unselectedColor: Color.Pink })
.onChange((isOn: boolean) => {
console.info('Component status:' + isOn);
})
Toggle({ type: ToggleType.Switch, isOn: true })
.selectedColor('#007DFF')
.switchStyle({
pointRadius: 15,
trackBorderRadius: 10,
pointColor: '#D2B48C',
unselectedColor: Color.Pink })
.onChange((isOn: boolean) => {
console.info('Component status:' + isOn);
})
}
}.width('100%').padding(24)
}
} 
示例3（自定义Toggle样式）
该示例实现自定义Toggle样式，通过按钮切换圆形背景颜色：点击蓝圆按钮，背景变蓝色；点击黄圆按钮，背景变黄色。
// xxx.ets
// 自定义Switch样式修改器，实现ContentModifier接口定制Toggle内容区
class MySwitchStyle implements ContentModifier<ToggleConfiguration> {
// 开关打开时的背景颜色
selectedColor: Color = Color.White;
// 用于按钮显示的文本
lamp: string = 'string';
constructor(selectedColor: Color, lamp: string) {
this.selectedColor = selectedColor;
this.lamp = lamp;
}
applyContent(): WrappedBuilder<[ToggleConfiguration]> {
return wrapBuilder(buildSwitch);
}
}
@Builder
function buildSwitch(config: ToggleConfiguration) {
Column({ space: 50 }) {
Circle({ width: 150, height: 150 })
.fill(config.isOn ? (config.contentModifier as MySwitchStyle).selectedColor : Color.Blue)
Row() {
Button('蓝' + JSON.stringify((config.contentModifier as MySwitchStyle).lamp))
.onClick(() => {
config.triggerChange(false);
})
Button('黄' + JSON.stringify((config.contentModifier as MySwitchStyle).lamp))
.onClick(() => {
config.triggerChange(true);
})
}
}
}
@Entry
@Component
struct Index {
build() {
Column({ space: 50 }) {
// 使用自定义样式修改器定制Toggle内容，并通过onChange监听状态变化
Toggle({ type: ToggleType.Switch })
.enabled(true)
.contentModifier(new MySwitchStyle(Color.Yellow, '灯'))
.onChange((isOn: boolean) => {
console.info('Switch Log:' + isOn);
})
}.height('100%').width('100%')
}
} 
示例4（Toggle沉浸光感效果）
该示例展示了Toggle组件Switch类型在开启沉浸光感前后的效果对比，包括不设置系统材质、设置undefined、设置系统材质以及设置系统材质并配合switchPointColor设置点光源颜色的效果。示例使用通用属性systemMaterial接口来实现沉浸光感效果。
组件沉浸光感效果会根据设备算力与用户在系统中设置的沉浸光感效果自适应调整，开发者无需额外适配。
从API版本26.0.0开始，新增systemMaterial属性。
说明
系统材质的实际显示效果与设备的算力档位相关，相同的代码在不同算力档位的设备上显示效果存在差异，低算力设备上会显示简化后的材质效果。算力档位由系统根据设备硬件能力自动划分和管理，应用无需感知，也无需进行额外设置，系统会根据当前设备的算力档位自动适配材质的显示效果。
import { uiMaterial } from '@kit.ArkUI';
// xxx.ets
@Entry
@Component
struct ToggleMaterialTest {
build() {
Column({ space: 10 }) {
// 不设置系统材质接口，无沉浸光感效果
Toggle({ type: ToggleType.Switch, isOn: true })
// systemMaterial设置undefined，恢复为无沉浸光感的效果
Toggle({ type: ToggleType.Switch, isOn: true })
.systemMaterial(undefined)
// 设置系统材质，开启沉浸光感效果（systemMaterial参数任意仅作为系统材质开关，最终使用组件侧固定参数），默认白色点光源（颜色为switchPointColor默认值）
Toggle({ type: ToggleType.Switch, isOn: true })
.systemMaterial(new uiMaterial.Material())
// 设置系统材质，开启沉浸光感效果（systemMaterial参数任意仅作为系统材质开关，最终使用组件侧固定参数），点光源颜色跟随switchPointColor设置
Toggle({ type: ToggleType.Switch, isOn: true })
.systemMaterial(new uiMaterial.Material())
.switchPointColor(Color.Red)
}
.width('100%')
}
} 高算力设备场景示例图：
低算力设备场景示例图：
