1# Toggle 2 3The **Toggle** component provides a clickable element in the check box, button, or switch type. 4 5> **NOTE** 6> 7> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 8 9## Child Components 10 11This component can contain child components only when **ToggleType** is set to **Button**. 12 13 14## APIs 15 16Toggle(options: ToggleOptions) 17 18**Widget capability**: This API can be used in ArkTS widgets since API version 9. 19 20**Atomic service API**: This API can be used in atomic services since API version 11. 21 22**System capability**: SystemCapability.ArkUI.ArkUI.Full 23 24**Parameters** 25 26| Name| Type| Mandatory | Description | 27| ---- | ---------- | -----| -------------- | 28| options | [ToggleOptions](#toggleoptions13) | Yes | Options of the toggle.| 29 30## ToggleOptions<sup>13+</sup> 31 32**Widget capability**: This API can be used in ArkTS widgets since API version 13. 33 34**Atomic service API**: This API can be used in atomic services since API version 13. 35 36**System capability**: SystemCapability.ArkUI.ArkUI.Full 37 38| Name| Type | Mandatory| Description | 39| ---- | --------------------------------- | ---- | ------------------------------------------------------------ | 40| type | [ToggleType](#toggletype) | Yes | Type of the toggle.<br>Default value: **ToggleType.Switch** | 41| isOn | boolean | No | Whether the toggle is turned on. The value **true** means that the toggle is turned on, and **false** means the opposite.<br>Default value: **false**<br>This parameter supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md).| 42 43## ToggleType 44 45**Widget capability**: This API can be used in ArkTS widgets since API version 9. 46 47**Atomic service API**: This API can be used in atomic services since API version 11. 48 49**System capability**: SystemCapability.ArkUI.ArkUI.Full 50 51| Name | Description | 52| -------- | ---------------- | 53| Checkbox | Check box type.<br>**NOTE**<br>Since API version 11, the default style of the **Checkbox** component is changed from rounded square to circle.<br>The default value of the universal attribute [margin](ts-universal-attributes-size.md#margin) is as follows:<br>{<br> top: '14px',<br> right: '14px',<br> bottom: '14px',<br> left: '14px'<br> }.<br>Default size:<br>{width:'20vp', height:'20vp'}| 54| Button | Button type. The set string, if any, will be displayed inside the button.<br>The default height is 28 vp, and there is no default width. | 55| Switch | Switch type.<br>**NOTE**<br>The default value of the universal attribute [margin](ts-universal-attributes-size.md) is as follows:<br>{<br> top: '6px',<br> right: '14px',<br> bottom: '6px',<br> left: '14px'<br> }.<br>Default size:<br>{width:'36vp', height:'20vp'}| 56 57## Attributes 58 59In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 60 61### selectedColor 62 63selectedColor(value: ResourceColor) 64 65Sets the background color of the component when it is turned on. 66 67**Widget capability**: This API can be used in ArkTS widgets since API version 9. 68 69**Atomic service API**: This API can be used in atomic services since API version 11. 70 71**System capability**: SystemCapability.ArkUI.ArkUI.Full 72 73**Parameters** 74 75| Name| Type | Mandatory| Description | 76| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 77| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Background color of the component when it is turned on.<br>Default value:<br>When **ToggleType** is set to **Switch**, the default value is **$r('sys.color.ohos_id_color_component_activated')**.<br>When **ToggleType** is set to **Checkbox**, the default value is **$r('sys.color.ohos_id_color_component_activated')**.<br>When **ToggleType** is set to **Button**, the default value is **$r('sys.color.ohos_id_color_component_activated')** with the opacity of **$r('sys.color.ohos_id_color_text_highlight_bg')**.| 78 79### switchPointColor 80 81switchPointColor(color: ResourceColor) 82 83Sets the color of the circular slider when the component is of the **Switch** type. This attribute is valid only when **type** is set to **ToggleType.Switch**. 84 85**Widget capability**: This API can be used in ArkTS widgets since API version 9. 86 87**Atomic service API**: This API can be used in atomic services since API version 11. 88 89**System capability**: SystemCapability.ArkUI.ArkUI.Full 90 91**Parameters** 92 93| Name| Type | Mandatory| Description | 94| ------ | ------------------------------------------ | ---- | -------------------------- | 95| color | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the circular slider when the component is of the **Switch** type.<br>Default value: **$r('sys.color.ohos_id_color_foreground_contrary')**| 96 97### switchStyle<sup>12+</sup> 98 99switchStyle(value: SwitchStyle) 100 101Sets the style for the component of the **Switch** type. This attribute is valid only when **type** is set to **ToggleType.Switch**. 102 103**Atomic service API**: This API can be used in atomic services since API version 12. 104 105**System capability**: SystemCapability.ArkUI.ArkUI.Full 106 107**Parameters** 108 109| Name| Type | Mandatory| Description | 110| ------ | ------------------------------------- | ---- | ---------------- | 111| value | [SwitchStyle](#switchstyle12) | Yes | Style of the component of the **Switch** type.| 112 113### contentModifier<sup>12+</sup> 114 115contentModifier(modifier: ContentModifier\<ToggleConfiguration>) 116 117Creates a content modifier. 118 119**Atomic service API**: This API can be used in atomic services since API version 12. 120 121**System capability**: SystemCapability.ArkUI.ArkUI.Full 122 123**Parameters** 124 125| Name| Type | Mandatory| Description | 126| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 127| modifier | [ContentModifier\<ToggleConfiguration>](#toggleconfiguration12) | Yes | Content modifier to apply to the current component.<br>**modifier**: content modifier. You need a custom class to implement the **ContentModifier** API.| 128 129## SwitchStyle<sup>12+</sup> 130 131**Atomic service API**: This API can be used in atomic services since API version 12. 132 133**System capability**: SystemCapability.ArkUI.ArkUI.Full 134 135| Name | Type | Mandatory| Description | 136| ----------------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 137| pointRadius | number \| [Resource](ts-types.md#resource) | No | Radius of the circular slider when the component is of the **Switch** type.<br>**NOTE**<br>This parameter cannot be set in percentage. The value specified is used only when it is greater than or equal to 0.<br>If the value is not specified or the specified one is less than 0, the radius is set using the following formula:<br>(Component height (in vp)/2) - (2 vp x Component height (in vp)/20 vp)| 138| unselectedColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the component when it is of the **Switch** type and is disabled.<br>Default value: **0x337F7F7F**| 139| pointColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the circular slider when the component is of the **Switch** type.<br>Default value: **$r('sys.color.ohos_id_color_foreground_contrary')**| 140| trackBorderRadius | number \| [Resource](ts-types.md#resource) | No | Radius of the slider track border corners when the component is of the **Switch** type.<br>**NOTE**<br>This parameter cannot be set in percentage. If the value specified is less than 0, the radius is set using the default value formula. If the value specified is greater than half of the component height, the latter is used. In other cases, the value specified is used.<br>If the value is not specified or the specified one is less than 0, the radius is set using the default value formula.<br>Default value formula: Component height (in vp)/2| 141 142## Events 143 144In addition to the [universal events](ts-universal-events-click.md), the following events are supported. 145 146### onChange 147 148onChange(callback: (isOn: boolean) => void) 149 150Triggered when the toggle status changes. 151 152**Widget capability**: This API can be used in ArkTS widgets since API version 9. 153 154**Atomic service API**: This API can be used in atomic services since API version 11. 155 156**System capability**: SystemCapability.ArkUI.ArkUI.Full 157 158**Parameters** 159 160| Name| Type | Mandatory| Description | 161| ------ | ------- | ---- | ------------------------------------------------------------ | 162| isOn | boolean | Yes | Whether the toggle is on.<br>**true**: The toggle is on. **false**: The toggle is off.| 163 164## ToggleConfiguration<sup>12+</sup> 165 166You need a custom class to implement the **ContentModifier** API. 167 168**Atomic service API**: This API can be used in atomic services since API version 12. 169 170**System capability**: SystemCapability.ArkUI.ArkUI.Full 171 172| Name | Type | Read-Only | Optional | Description | 173| ------ | ------ | ------ |-------------------------------- |-------------------------------- | 174| isOn | boolean| No | No| Whether the toggle is on.<br>Default value: **false**| 175| enabled | boolean | No| No| Whether the toggle is enabled.| 176| triggerChange |Callback\<boolean>| No| No|Triggers toggle status changes.| 177 178 179## Example 180 181### Example 1 182 183```ts 184// xxx.ets 185@Entry 186@Component 187struct ToggleExample { 188 build() { 189 Column({ space: 10 }) { 190 Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%') 191 Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) { 192 Toggle({ type: ToggleType.Switch, isOn: false }) 193 .selectedColor('#007DFF') 194 .switchPointColor('#FFFFFF') 195 .onChange((isOn: boolean) => { 196 console.info('Component status:' + isOn) 197 }) 198 199 Toggle({ type: ToggleType.Switch, isOn: true }) 200 .selectedColor('#007DFF') 201 .switchPointColor('#FFFFFF') 202 .onChange((isOn: boolean) => { 203 console.info('Component status:' + isOn) 204 }) 205 } 206 207 Text('type: Checkbox').fontSize(12).fontColor(0xcccccc).width('90%') 208 Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) { 209 Toggle({ type: ToggleType.Checkbox, isOn: false }) 210 .size({ width: 20, height: 20 }) 211 .selectedColor('#007DFF') 212 .onChange((isOn: boolean) => { 213 console.info('Component status:' + isOn) 214 }) 215 216 Toggle({ type: ToggleType.Checkbox, isOn: true }) 217 .size({ width: 20, height: 20 }) 218 .selectedColor('#007DFF') 219 .onChange((isOn: boolean) => { 220 console.info('Component status:' + isOn) 221 }) 222 } 223 224 Text('type: Button').fontSize(12).fontColor(0xcccccc).width('90%') 225 Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) { 226 Toggle({ type: ToggleType.Button, isOn: false }) { 227 Text('status button').fontColor('#182431').fontSize(12) 228 }.width(106) 229 .selectedColor('rgba(0,125,255,0.20)') 230 .onChange((isOn: boolean) => { 231 console.info('Component status:' + isOn) 232 }) 233 234 Toggle({ type: ToggleType.Button, isOn: true }) { 235 Text('status button').fontColor('#182431').fontSize(12) 236 }.width(106) 237 .selectedColor('rgba(0,125,255,0.20)') 238 .onChange((isOn: boolean) => { 239 console.info('Component status:' + isOn) 240 }) 241 } 242 }.width('100%').padding(24) 243 } 244} 245``` 246 247 248 249### Example 2 250 251This example implements a toggle of the **Switch** type with custom settings, including the radius and color of the circular slider, background color in the off state, and radius of the slider track border corners. 252 253```ts 254// xxx.ets 255@Entry 256@Component 257struct ToggleExample { 258 build() { 259 Column({ space: 10 }) { 260 Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%') 261 Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) { 262 Toggle({ type: ToggleType.Switch, isOn: false }) 263 .selectedColor('#007DFF') 264 .switchStyle({ 265 pointRadius: 15, 266 trackBorderRadius: 10, 267 pointColor: '#D2B48C', 268 unselectedColor: Color.Pink }) 269 .onChange((isOn: boolean) => { 270 console.info('Component status:' + isOn) 271 }) 272 273 Toggle({ type: ToggleType.Switch, isOn: true }) 274 .selectedColor('#007DFF') 275 .switchStyle({ 276 pointRadius: 15, 277 trackBorderRadius: 10, 278 pointColor: '#D2B48C', 279 unselectedColor: Color.Pink }) 280 .onChange((isOn: boolean) => { 281 console.info('Component status:' + isOn) 282 }) 283 } 284 }.width('100%').padding(24) 285 } 286} 287``` 288 289 290 291### Example 3 292 293This example implements a toggle in a custom style. When you click the **Blue** button, the circle background turns blue. When you click the **Yellow** button, the circle background turns yellow. 294 295```ts 296// xxx.ets 297class MySwitchStyle implements ContentModifier<ToggleConfiguration> { 298 selectedColor: Color = Color.White 299 lamp: string = 'string'; 300 constructor(selectedColor: Color, lamp: string) { 301 this.selectedColor = selectedColor 302 this.lamp = lamp; 303 } 304 applyContent() : WrappedBuilder<[ToggleConfiguration]> 305 { 306 return wrapBuilder(buildSwitch) 307 } 308} 309@Builder function buildSwitch(config: ToggleConfiguration) { 310 Column({ space: 50 }) { 311 Circle({ width: 150, height: 150 }) 312 .fill(config.isOn ? (config.contentModifier as MySwitchStyle).selectedColor : Color.Blue) 313 Row() { 314 Button('Blue '+ JSON.stringify((config.contentModifier as MySwitchStyle).lamp)) 315 .onClick(() => { 316 config.triggerChange(false); 317 }) 318 Button('Yellow '+ JSON.stringify((config.contentModifier as MySwitchStyle).lamp)) 319 .onClick(() => { 320 config.triggerChange(true); 321 }) 322 } 323 } 324} 325 326@Entry 327@Component 328struct Index { 329 build() { 330 Column({ space: 50 }) { 331 Toggle({ type: ToggleType.Switch}) 332 .enabled(true) 333 .contentModifier(new MySwitchStyle(Color.Yellow, 'light')) 334 .onChange((isOn: boolean) => { 335 console.info('Switch Log:' + isOn) 336 }) 337 }.height('100%').width('100%') 338 } 339} 340``` 341 342 343
