输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
文档管理中心

HarmonyOS 5.0.2(14)

输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
API参考
高级筛选
元服务API集不筛选
您当前浏览的HarmonyOS 5.0.2(API 14)文档归档不再维护，推荐您使用最新版本。详细请参考文档维护策略变更。
API参考应用框架ArkUI（方舟UI框架）ArkTS组件按钮与选择Toggle

Toggle

更新时间: 2025-03-17 00:56
本文导读
展开章节

组件提供勾选框样式、状态按钮样式及开关样式。

说明

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

仅当ToggleType为Button时可包含子组件。

接口

Toggle(options: { type: ToggleType, isOn?: boolean })

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数:

展开
参数名 类型 必填 说明
type ToggleType 是

开关的样式。

默认值：ToggleType.Switch
isOn boolean 否

开关是否打开，true：打开，false：关闭。

默认值：false

从API version 10开始，该参数支持$$双向绑定变量。

ToggleType枚举说明

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 说明
Checkbox

提供单选框样式。

说明：

API version 11开始，Checkbox默认样式由圆角方形变为圆形。

通用属性margin的默认值为：

{

top: '14px',

right: '14px',

bottom: '14px',

left: '14px'

}。

默认尺寸为:

{width:'20vp', height:'20vp'}。
Button

提供状态按钮样式，如果子组件有文本设置，则相应的文本内容会显示在按钮内部。

默认尺寸为:高为28vp，宽无默认值。
Switch

提供开关样式。

说明：

通用属性margin默认值为：

{

top: '6px',

right: '14px',

bottom: '6px',

left: '14px'

}。

默认尺寸为:

{width:'36vp', height:'20vp'}。

属性

除支持通用属性外，还支持以下属性：

selectedColor

selectedColor(value: ResourceColor)

设置组件打开状态的背景颜色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
value ResourceColor 是

组件打开状态的背景颜色。

默认值：

当ToggleType为Switch时，默认值为$r('sys.color.ohos_id_color_component_activated')

当ToggleType为Checkbox时，默认值为$r('sys.color.ohos_id_color_component_activated')

当ToggleType为Button时，默认值为$r('sys.color.ohos_id_color_component_activated')混合$r('sys.color.ohos_id_color_text_highlight_bg')的透明度。

switchPointColor

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')

switchStyle12+

switchStyle(value: SwitchStyle)

设置Switch类型的样式。仅对type为ToggleType.Switch生效。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
value SwitchStyle 是 Switch样式风格。

contentModifier12+

contentModifier(modifier: ContentModifier<ToggleConfiguration>)

定制Toggle内容区的方法。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
modifier ContentModifier<ToggleConfiguration> 是

在Toggle组件上，定制内容区的方法。

modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

SwitchStyle12+对象说明

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 必填 说明
pointRadius number | Resource 否

设置Switch类型的圆形滑块半径。

说明：

不支持百分比，设定值小于0时按照默认算法设置，设定值大于等于0时按照设定值设置。

未设定此属性时，圆形滑块半径根据默认算法设置。

默认算法：（组件高度（单位：vp） / 2） - （2vp * 组件高度（单位：vp） / 20vp）。
unselectedColor ResourceColor 否

设置Switch类型关闭状态的背景颜色。

默认值：0x337F7F7F。
pointColor ResourceColor 否

设置Switch类型的圆形滑块颜色。

默认值：$r('sys.color.ohos_id_color_foreground_contrary')
trackBorderRadius number | Resource 否

设置Switch类型的滑轨的圆角。

说明：

不支持百分比，设定值小于0时按照默认算法设置，设定值大于组件高度一半时按照组件高度一半设置，其他场合按照设定值设置。

未设定此属性时，滑轨圆角根据默认算法设置。

默认算法：组件高度（单位：vp） / 2。

事件

除支持通用事件外，还支持以下事件：

onChange

onChange(callback: (isOn: boolean) => void)

开关状态切换时触发该事件。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

展开
参数名 类型 必填 说明
isOn boolean 是 为true时，代表状态从关切换为开。false时，代表状态从开切换为关。

ToggleConfiguration12+对象说明

开发者需要自定义class实现ContentModifier接口。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

展开
名称 类型 只读 可选 说明
isOn boolean 否 否

开关是否打开。

默认值：false
enabled boolean 否 否 是否可以切换状态。
triggerChange Callback<boolean> 否 否 触发switch选中状态变化。

示例

示例1（设置开关的样式）

该示例通过配置ToggleType设置Toggle的勾选框样式、状态按钮样式及开关样式。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct ToggleExample {
  5.   build() {
  6.     Column({ space: 10 }) {
  7.       Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%')
  8.       Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
  9.         Toggle({ type: ToggleType.Switch, isOn: false })
  10.           .selectedColor('#007DFF')
  11.           .switchPointColor('#FFFFFF')
  12.           .onChange((isOn: boolean) => {
  13.             console.info('Component status:' + isOn)
  14.           })
  15. 

  16.         Toggle({ type: ToggleType.Switch, isOn: true })
  17.           .selectedColor('#007DFF')
  18.           .switchPointColor('#FFFFFF')
  19.           .onChange((isOn: boolean) => {
  20.             console.info('Component status:' + isOn)
  21.           })
  22.       }
  23. 

  24.       Text('type: Checkbox').fontSize(12).fontColor(0xcccccc).width('90%')
  25.       Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
  26.         Toggle({ type: ToggleType.Checkbox, isOn: false })
  27.           .size({ width: 20, height: 20 })
  28.           .selectedColor('#007DFF')
  29.           .onChange((isOn: boolean) => {
  30.             console.info('Component status:' + isOn)
  31.           })
  32. 

  33.         Toggle({ type: ToggleType.Checkbox, isOn: true })
  34.           .size({ width: 20, height: 20 })
  35.           .selectedColor('#007DFF')
  36.           .onChange((isOn: boolean) => {
  37.             console.info('Component status:' + isOn)
  38.           })
  39.       }
  40. 

  41.       Text('type: Button').fontSize(12).fontColor(0xcccccc).width('90%')
  42.       Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
  43.         Toggle({ type: ToggleType.Button, isOn: false }) {
  44.           Text('status button').fontColor('#182431').fontSize(12)
  45.         }.width(106)
  46.         .selectedColor('rgba(0,125,255,0.20)')
  47.         .onChange((isOn: boolean) => {
  48.           console.info('Component status:' + isOn)
  49.         })
  50. 

  51.         Toggle({ type: ToggleType.Button, isOn: true }) {
  52.           Text('status button').fontColor('#182431').fontSize(12)
  53.         }.width(106)
  54.         .selectedColor('rgba(0,125,255,0.20)')
  55.         .onChange((isOn: boolean) => {
  56.           console.info('Component status:' + isOn)
  57.         })
  58.       }
  59.     }.width('100%').padding(24)
  60.   }
  61. }

示例2（自定义开关类型的样式）

该示例实现了自定义设置Toggle组件Switch样式的圆形滑块半径、关闭状态的背景颜色、圆形滑块颜色、滑轨的圆角。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct ToggleExample {
  5.   build() {
  6.     Column({ space: 10 }) {
  7.       Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%')
  8.       Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
  9.         Toggle({ type: ToggleType.Switch, isOn: false })
  10.           .selectedColor('#007DFF')
  11.           .switchStyle({
  12.             pointRadius: 15,
  13.             trackBorderRadius: 10,
  14.             pointColor: '#D2B48C',
  15.             unselectedColor: Color.Pink })
  16.           .onChange((isOn: boolean) => {
  17.             console.info('Component status:' + isOn)
  18.           })
  19. 

  20.         Toggle({ type: ToggleType.Switch, isOn: true })
  21.           .selectedColor('#007DFF')
  22.           .switchStyle({
  23.             pointRadius: 15,
  24.             trackBorderRadius: 10,
  25.             pointColor: '#D2B48C',
  26.             unselectedColor: Color.Pink })
  27.           .onChange((isOn: boolean) => {
  28.             console.info('Component status:' + isOn)
  29.           })
  30.       }
  31.     }.width('100%').padding(24)
  32.   }
  33. }

示例3（自定义Toggle样式）

该示例实现了自定义Toggle样式的功能。自定义样式实现了通过按钮切换圆形颜色的功能：点击蓝圆按钮，圆形背景变蓝色，点击黄圆按钮，圆形背景变黄色。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. class MySwitchStyle implements ContentModifier<ToggleConfiguration> {
  3.   selectedColor: Color = Color.White
  4.   lamp: string = 'string';
  5.   constructor(selectedColor: Color, lamp: string) {
  6.     this.selectedColor = selectedColor
  7.     this.lamp = lamp;
  8.   }
  9.   applyContent() : WrappedBuilder<[ToggleConfiguration]>
  10.   {
  11.     return wrapBuilder(buildSwitch)
  12.   }
  13. }
  14. @Builder function buildSwitch(config: ToggleConfiguration) {
  15.   Column({ space: 50 }) {
  16.     Circle({ width: 150, height: 150 })
  17.       .fill(config.isOn ? (config.contentModifier as MySwitchStyle).selectedColor : Color.Blue)
  18.     Row() {
  19.       Button('蓝'+ JSON.stringify((config.contentModifier as MySwitchStyle).lamp))
  20.         .onClick(() => {
  21.           config.triggerChange(false);
  22.         })
  23.       Button('黄'+ JSON.stringify((config.contentModifier as MySwitchStyle).lamp))
  24.         .onClick(() => {
  25.           config.triggerChange(true);
  26.         })
  27.     }
  28.   }
  29. }
  30. 

  31. @Entry
  32. @Component
  33. struct Index {
  34.   build() {
  35.     Column({ space: 50 }) {
  36.       Toggle({ type: ToggleType.Switch})
  37.         .enabled(true)
  38.         .contentModifier(new MySwitchStyle(Color.Yellow, '灯'))
  39.         .onChange((isOn: boolean) => {
  40.           console.info('Switch Log:' + isOn)
  41.         })
  42.     }.height('100%').width('100%')
  43.   }
  44. }

Button
Checkbox
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明
在 API参考 中进行搜索
请输入您想要搜索的关键词