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