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