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](#toggleoptions13对象说明) | 是 | Toggle的信息。 | 29 30## ToggleOptions<sup>13+</sup>对象说明 31 32**卡片能力：** 从API version 13开始，该接口支持在ArkTS卡片中使用。 33 34**原子化服务API：** 从API version 13开始，该接口支持在原子化服务中使用。 35 36**系统能力：** SystemCapability.ArkUI.ArkUI.Full 37 38| 名称 | 类型 | 必填 | 说明 | 39| ---- | --------------------------------- | ---- | ------------------------------------------------------------ | 40| type | [ToggleType](#toggletype枚举说明) | 是 | 开关的样式。<br/>默认值：ToggleType.Switch | 41| isOn | boolean | 否 | 开关是否打开，true：打开，false：关闭。<br/>默认值：false<br />该参数支持[$$](../../../quick-start/arkts-two-way-sync.md)双向绑定变量。 | 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-universal-attributes-size.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类型的圆形滑块半径。<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类型的滑轨的圆角。<br />**说明：**<br/>不支持百分比，设定值小于0时按照默认算法设置，设定值大于组件高度一半时按照组件高度一半设置，其他场合按照设定值设置。<br/>未设定此属性时，滑轨圆角根据默认算法设置。<br/>默认算法：组件高度（单位：vp） / 2。 | 141 142## 事件 143 144除支持[通用事件](ts-universal-events-click.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 | 175| enabled | boolean | 否 | 否 | 是否可以切换状态。 | 176| triggerChange |Callback\<boolean>| 否 | 否 |触发switch选中状态变化。 | 177 178 179## 示例 180 181### 示例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### 示例2 250 251该示例实现了自定义设置Toggle组件Switch样式的圆形滑块半径、关闭状态的背景颜色、圆形滑块颜色、滑轨的圆角。 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### 示例3 292 293该示例实现了自定义Toggle样式的功能。自定义样式实现了通过按钮切换圆形颜色的功能：点击蓝圆按钮，圆形背景变蓝色，点击黄圆按钮，圆形背景变黄色。 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('蓝'+ JSON.stringify((config.contentModifier as MySwitchStyle).lamp)) 315 .onClick(() => { 316 config.triggerChange(false); 317 }) 318 Button('黄'+ 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, '灯')) 334 .onChange((isOn: boolean) => { 335 console.info('Switch Log:' + isOn) 336 }) 337 }.height('100%').width('100%') 338 } 339} 340``` 341 342 343
