1# Toggle 2 3组件提供勾选框样式、状态按钮样式及开关样式。 4 5> **说明：** 6> 7> 该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9## 子组件 10 11仅当ToggleType为Button时可包含子组件。 12 13 14## 接口 15 16Toggle(options: ToggleOptions) 17 18**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 19 20**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 21 22**系统能力：** SystemCapability.ArkUI.ArkUI.Full 23 24**参数：** 25 26| 参数名 | 类型 | 必填 | 说明 | 27| ---- | ---------- | -----| -------------- | 28| options | [ToggleOptions](#toggleoptions18对象说明) | 是 | Toggle的信息。 | 29 30## ToggleOptions<sup>18+</sup>对象说明 31 32**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 33 34**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 35 36**系统能力：** SystemCapability.ArkUI.ArkUI.Full 37 38| 名称 | 类型 | 必填 | 说明 | 39| ----------------- | --------------------------------- | ---- | ------------------------------------------------------------ | 40| type<sup>8+</sup> | [ToggleType](#toggletype枚举说明) | 是 | 开关的样式。<br/>默认值：ToggleType.Switch<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 41| isOn<sup>8+</sup> | boolean | 否 | 开关是否打开，true：打开，false：关闭。<br/>默认值：false<br />该参数支持[$$](../../../ui/state-management/arkts-two-way-sync.md)双向绑定变量。<br />该属性支持[!!](../../../ui/state-management/arkts-new-binding.md#系统组件参数双向绑定)双向绑定变量。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 42 43## ToggleType枚举说明 44 45**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 46 47**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 48 49**系统能力：** SystemCapability.ArkUI.ArkUI.Full 50 51| 名称 | 说明 | 52| -------- | ------------------------------------------------------------ | 53| Checkbox | 提供单选框样式。<br>**说明：**<br/>API version 11开始，Checkbox默认样式由圆角方形变为圆形。<br/>[通用属性margin](ts-universal-attributes-size.md#margin)的默认值为：<br>{<br> top: '14px',<br> right: '14px',<br> bottom: '14px',<br> left: '14px'<br> }。<br/>默认尺寸为：<br>{width:'20vp', height:'20vp'}。 | 54| Button | 提供状态按钮样式，如果子组件有文本设置，则相应的文本内容会显示在按钮内部。<br/>默认尺寸为:高为28vp，宽无默认值。 | 55| Switch | 提供开关样式。<br>**说明：**<br/>[通用属性margin](ts-universal-attributes-size.md#margin)默认值为：<br>{<br/> top: '6px',<br/> right: '14px',<br/> bottom: '6px',<br/> left: '14px'<br/> }。<br/>默认尺寸为：<br>{width:'36vp', height:'20vp'}。 | 56 57## 属性 58 59除支持[通用属性](ts-component-general-attributes.md)外，还支持以下属性： 60 61### selectedColor 62 63selectedColor(value: ResourceColor) 64 65设置组件打开状态的背景颜色。 66 67**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 68 69**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 70 71**系统能力：** SystemCapability.ArkUI.ArkUI.Full 72 73**参数：** 74 75| 参数名 | 类型 | 必填 | 说明 | 76| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 77| value | [ResourceColor](ts-types.md#resourcecolor) | 是 | 组件打开状态的背景颜色。<br/>默认值：<br/>当ToggleType为Switch时，默认值为`$r('sys.color.ohos_id_color_component_activated')`<br/>当ToggleType为Checkbox时，默认值为`$r('sys.color.ohos_id_color_component_activated')`<br/>当ToggleType为Button时，默认值为`$r('sys.color.ohos_id_color_component_activated')`混合`$r('sys.color.ohos_id_color_text_highlight_bg')`的透明度。 | 78 79### switchPointColor 80 81switchPointColor(color: ResourceColor) 82 83设置Switch类型的圆形滑块颜色。仅对type为ToggleType.Switch生效。 84 85**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 86 87**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 88 89**系统能力：** SystemCapability.ArkUI.ArkUI.Full 90 91**参数：** 92 93| 参数名 | 类型 | 必填 | 说明 | 94| ------ | ------------------------------------------ | ---- | -------------------------- | 95| color | [ResourceColor](ts-types.md#resourcecolor) | 是 | Switch类型的圆形滑块颜色。<br/>默认值：$r('sys.color.ohos_id_color_foreground_contrary') | 96 97### switchStyle<sup>12+</sup> 98 99switchStyle(value: SwitchStyle) 100 101设置Switch类型的样式。仅对type为ToggleType.Switch生效。 102 103**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 104 105**系统能力：** SystemCapability.ArkUI.ArkUI.Full 106 107**参数：** 108 109| 参数名 | 类型 | 必填 | 说明 | 110| ------ | ------------------------------------- | ---- | ---------------- | 111| value | [SwitchStyle](#switchstyle12对象说明) | 是 | Switch样式风格。 | 112 113### contentModifier<sup>12+</sup> 114 115contentModifier(modifier: ContentModifier\<ToggleConfiguration>) 116 117定制Toggle内容区的方法。 118 119**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 120 121**系统能力：** SystemCapability.ArkUI.ArkUI.Full 122 123**参数：** 124 125| 参数名 | 类型 | 必填 | 说明 | 126| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 127| modifier | [ContentModifier\<ToggleConfiguration>](#toggleconfiguration12对象说明) | 是 | 在Toggle组件上，定制内容区的方法。<br/>modifier：内容修改器，开发者需要自定义class实现ContentModifier接口。 | 128 129## SwitchStyle<sup>12+</sup>对象说明 130 131**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 132 133**系统能力：** SystemCapability.ArkUI.ArkUI.Full 134 135| 名称 | 类型 | 必填 | 说明 | 136| ----------------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 137| pointRadius | number \| [Resource](ts-types.md#resource) | 否 | 设置Switch类型的圆形滑块半径，单位为vp。<br />**说明：**<br/>不支持百分比，设定值小于0时按照默认算法设置，设定值大于等于0时按照设定值设置。<br/>未设定此属性时，圆形滑块半径根据默认算法设置。<br/>默认算法：（组件高度（单位：vp） / 2） - （2vp * 组件高度（单位：vp） / 20vp）。 | 138| unselectedColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置Switch类型关闭状态的背景颜色。<br />默认值：0x337F7F7F。 | 139| pointColor | [ResourceColor](ts-types.md#resourcecolor) | 否 | 设置Switch类型的圆形滑块颜色。<br />默认值：$r('sys.color.ohos_id_color_foreground_contrary') | 140| trackBorderRadius | number \| [Resource](ts-types.md#resource) | 否 | 设置Switch类型的滑轨的圆角，单位为vp。<br />**说明：**<br/>不支持百分比，设定值小于0时按照默认算法设置，设定值大于组件高度一半时按照组件高度一半设置，其他场合按照设定值设置。<br/>未设定此属性时，滑轨圆角根据默认算法设置。<br/>默认算法：组件高度（单位：vp） / 2。 | 141 142## 事件 143 144除支持[通用事件](ts-component-general-events.md)外，还支持以下事件： 145 146### onChange 147 148onChange(callback: (isOn: boolean) => void) 149 150开关状态切换时触发该事件。 151 152**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 153 154**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 155 156**系统能力：** SystemCapability.ArkUI.ArkUI.Full 157 158**参数：** 159 160| 参数名 | 类型 | 必填 | 说明 | 161| ------ | ------- | ---- | ------------------------------------------------------------ | 162| isOn | boolean | 是 | 为true时，代表状态从关切换为开。false时，代表状态从开切换为关。 | 163 164## ToggleConfiguration<sup>12+</sup>对象说明 165 166开发者需要自定义class实现ContentModifier接口。 167 168**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 169 170**系统能力：** SystemCapability.ArkUI.ArkUI.Full 171 172| 名称 | 类型 | 只读 | 可选 | 说明 | 173| ------ | ------ | ------ |-------------------------------- |-------------------------------- | 174| isOn | boolean| 否 | 否 | 开关是否打开。<br/>默认值：false<br/>值为true时，开关打开。值为false时，开关关闭。 | 175| enabled | boolean | 否 | 否 | 是否可以切换状态。<br/>默认值：true<br/>值为true时，可以切换状态。值为false时，不可以切换状态。 | 176| triggerChange |Callback\<boolean>| 否 | 否 |触发switch选中状态变化。<br/>为true时，代表状态从关切换为开。false时，代表状态从开切换为关。 | 177 178 179## 示例 180 181### 示例1（设置开关的样式） 182 183该示例通过配置ToggleType设置Toggle的勾选框样式、状态按钮样式及开关样式。 184 185```ts 186// xxx.ets 187@Entry 188@Component 189struct ToggleExample { 190 build() { 191 Column({ space: 10 }) { 192 Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%') 193 Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) { 194 Toggle({ type: ToggleType.Switch, isOn: false }) 195 .selectedColor('#007DFF') 196 .switchPointColor('#FFFFFF') 197 .onChange((isOn: boolean) => { 198 console.info('Component status:' + isOn); 199 }) 200 201 Toggle({ type: ToggleType.Switch, isOn: true }) 202 .selectedColor('#007DFF') 203 .switchPointColor('#FFFFFF') 204 .onChange((isOn: boolean) => { 205 console.info('Component status:' + isOn); 206 }) 207 } 208 209 Text('type: Checkbox').fontSize(12).fontColor(0xcccccc).width('90%') 210 Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) { 211 Toggle({ type: ToggleType.Checkbox, isOn: false }) 212 .size({ width: 20, height: 20 }) 213 .selectedColor('#007DFF') 214 .onChange((isOn: boolean) => { 215 console.info('Component status:' + isOn); 216 }) 217 218 Toggle({ type: ToggleType.Checkbox, isOn: true }) 219 .size({ width: 20, height: 20 }) 220 .selectedColor('#007DFF') 221 .onChange((isOn: boolean) => { 222 console.info('Component status:' + isOn); 223 }) 224 } 225 226 Text('type: Button').fontSize(12).fontColor(0xcccccc).width('90%') 227 Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) { 228 Toggle({ type: ToggleType.Button, isOn: false }) { 229 Text('status button').fontColor('#182431').fontSize(12) 230 }.width(106) 231 .selectedColor('rgba(0,125,255,0.20)') 232 .onChange((isOn: boolean) => { 233 console.info('Component status:' + isOn); 234 }) 235 236 Toggle({ type: ToggleType.Button, isOn: true }) { 237 Text('status button').fontColor('#182431').fontSize(12) 238 }.width(106) 239 .selectedColor('rgba(0,125,255,0.20)') 240 .onChange((isOn: boolean) => { 241 console.info('Component status:' + isOn); 242 }) 243 } 244 }.width('100%').padding(24) 245 } 246} 247``` 248 249 250 251### 示例2（自定义开关类型的样式） 252 253该示例实现了自定义设置Toggle组件Switch样式的圆形滑块半径、关闭状态的背景颜色、圆形滑块颜色、滑轨的圆角。 254 255```ts 256// xxx.ets 257@Entry 258@Component 259struct ToggleExample { 260 build() { 261 Column({ space: 10 }) { 262 Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%') 263 Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) { 264 Toggle({ type: ToggleType.Switch, isOn: false }) 265 .selectedColor('#007DFF') 266 .switchStyle({ 267 pointRadius: 15, 268 trackBorderRadius: 10, 269 pointColor: '#D2B48C', 270 unselectedColor: Color.Pink }) 271 .onChange((isOn: boolean) => { 272 console.info('Component status:' + isOn); 273 }) 274 275 Toggle({ type: ToggleType.Switch, isOn: true }) 276 .selectedColor('#007DFF') 277 .switchStyle({ 278 pointRadius: 15, 279 trackBorderRadius: 10, 280 pointColor: '#D2B48C', 281 unselectedColor: Color.Pink }) 282 .onChange((isOn: boolean) => { 283 console.info('Component status:' + isOn); 284 }) 285 } 286 }.width('100%').padding(24) 287 } 288} 289``` 290 291 292 293### 示例3（自定义Toggle样式） 294 295该示例实现了自定义Toggle样式的功能。自定义样式实现了通过按钮切换圆形颜色的功能：点击蓝圆按钮，圆形背景变蓝色，点击黄圆按钮，圆形背景变黄色。 296 297```ts 298// xxx.ets 299class MySwitchStyle implements ContentModifier<ToggleConfiguration> { 300 selectedColor: Color = Color.White; 301 lamp: string = 'string'; 302 303 constructor(selectedColor: Color, lamp: string) { 304 this.selectedColor = selectedColor; 305 this.lamp = lamp; 306 } 307 308 applyContent(): WrappedBuilder<[ToggleConfiguration]> { 309 return wrapBuilder(buildSwitch); 310 } 311} 312 313@Builder 314function buildSwitch(config: ToggleConfiguration) { 315 Column({ space: 50 }) { 316 Circle({ width: 150, height: 150 }) 317 .fill(config.isOn ? (config.contentModifier as MySwitchStyle).selectedColor : Color.Blue) 318 Row() { 319 Button('蓝' + JSON.stringify((config.contentModifier as MySwitchStyle).lamp)) 320 .onClick(() => { 321 config.triggerChange(false); 322 }) 323 Button('黄' + JSON.stringify((config.contentModifier as MySwitchStyle).lamp)) 324 .onClick(() => { 325 config.triggerChange(true); 326 }) 327 } 328 } 329} 330 331@Entry 332@Component 333struct Index { 334 build() { 335 Column({ space: 50 }) { 336 Toggle({ type: ToggleType.Switch }) 337 .enabled(true) 338 .contentModifier(new MySwitchStyle(Color.Yellow, '灯')) 339 .onChange((isOn: boolean) => { 340 console.info('Switch Log:' + isOn); 341 }) 342 }.height('100%').width('100%') 343 } 344} 345``` 346 347 348
