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