Checkbox
提供多选框组件,通常用于某选项的打开或关闭。
说明:
API version 11开始,Checkbox默认样式由圆角方形变为圆形。
该组件从API Version 8开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。
子组件
无
接口
Checkbox(options?: CheckboxOptions)
多选框组件。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
options | CheckboxOptions | 否 | 配置复选框的参数。 |
CheckboxOptions对象说明
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
名称 | 类型 | 必填 | 描述 |
---|---|---|---|
name | string | 否 | 用于指定多选框名称。 |
group | string | 否 | 用于指定多选框所属群组的名称(即所属CheckboxGroup的名称)。 说明: 未配合使用CheckboxGroup组件时,此值无用。 |
indicatorBuilder12+ | CustomBuilder | 否 | 配置多选框的选中样式为自定义组件。自定义组件与Checkbox组件为中心点对齐显示。indicatorBuilder设置为undefined/null时,默认为indicatorBuilder未设置状态。 |
属性
除支持通用属性外,还支持以下属性:
select
select(value: boolean)
设置多选框是否选中。
从API version 10开始,该属性支持$$双向绑定变量。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
value | boolean | 是 | 多选框是否选中。 默认值:false |
selectedColor
selectedColor(value: ResourceColor)
设置多选框选中状态颜色。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
value | ResourceColor | 是 | 多选框选中状态颜色。 默认值:$r(‘sys.color.ohos_id_color_text_primary_activated’)。 异常值按照默认值处理。 |
unselectedColor10+
unselectedColor(value: ResourceColor)
设置多选框非选中状态边框颜色。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
value | ResourceColor | 是 | 多选框非选中状态边框颜色。 默认值:‘#33ffffff’。 |
mark10+
mark(value: MarkStyle)
设置多选框内部图标样式。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
value | MarkStyle | 是 | 多选框内部图标样式。 从API version 12开始,设置了indicatorBuilder时,按照indicatorBuilder中的内容显示。 |
shape11+
shape(value: CheckBoxShape)
设置CheckBox组件形状, 包括圆形和圆角方形。
卡片能力: 从API version 11开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
value | CheckBoxShape | 是 | CheckBox组件形状, 包括圆形和圆角方形。 默认值:CheckBoxShape.CIRCLE |
contentModifier12+
contentModifier(modifier: ContentModifier<CheckBoxConfiguration>)
定制CheckBox内容区的方法。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
modifier | ContentModifier<CheckBoxConfiguration> | 是 | 在CheckBox组件上,定制内容区的方法。 modifier: 内容修改器,开发者需要自定义class实现ContentModifier接口。 |
事件
支持通用事件外,还支持以下事件:
onChange
onChange(callback: (value: boolean) => void)
当选中状态发生变化时,触发该回调。
卡片能力: 从API version 9开始,该接口支持在ArkTS卡片中使用。
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
系统能力: SystemCapability.ArkUI.ArkUI.Full
参数:
参数名 | 类型 | 必填 | 描述 |
---|---|---|---|
value | boolean | 是 | 返回true时,表示已选中。返回false时,表示未选中。 |
MarkStyle10+对象说明
原子化服务API: 从API version 11开始,该接口支持在原子化服务中使用。
名称 | 类型 | 必填 | 默认值 | 描述 |
---|---|---|---|---|
strokeColor | ResourceColor | 否 | Color.White | 内部图标颜色。 |
size | Length | 否 | - | 内部图标大小,单位vp。默认大小与多选框组件宽度设置值一致。 不支持百分比形式设置。当设置为非法值时,按照默认值处理。 |
strokeWidth | Length | 否 | 2 | 内部图标粗细,单位vp。不支持百分比形式设置。当设置为非法值时,按照默认值处理。 |
CheckBoxShape11+枚举类型说明
原子化服务API: 从API version 12开始,该接口支持在原子化服务中使用。
名称 | 值 | 说明 |
---|---|---|
CIRCLE | 0 | 圆形 |
ROUNDED_SQUARE | 1 | 圆角方形 |
CheckBoxConfiguration12+对象说明
开发者需要自定义class实现ContentModifier接口。
参数名 | 类型 | 默认值 | 说明 |
---|---|---|---|
name | string | - | 当前多选框名称。 |
selected | boolean | false | 指示多选框是否被选中。 如果select属性没有设置默认值是false。 如果设置select属性,此值与设置select属性的值相同。 |
triggerChange | Callback<boolean> | - | 触发多选框选中状态变化。 |
示例
示例1
// xxx.ets
@Entry
@Component
struct CheckboxExample {
build() {
Flex({ justifyContent: FlexAlign.SpaceAround }) {
Checkbox({ name: 'checkbox1', group: 'checkboxGroup' })
.select(true)
.selectedColor(0xed6f21)
.shape(CheckBoxShape.CIRCLE)
.onChange((value: boolean) => {
console.info('Checkbox1 change is' + value)
})
Checkbox({ name: 'checkbox2', group: 'checkboxGroup' })
.select(false)
.selectedColor(0x39a2db)
.shape(CheckBoxShape.ROUNDED_SQUARE)
.onChange((value: boolean) => {
console.info('Checkbox2 change is' + value)
})
}
}
}
ts
示例2
// xxx.ets
@Entry
@Component
struct Index {
build() {
Row() {
Column() {
Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
Checkbox({ name: 'checkbox1', group: 'checkboxGroup' })
.selectedColor(0x39a2db)
.shape(CheckBoxShape.ROUNDED_SQUARE)
.onChange((value: boolean) => {
console.info('Checkbox1 change is'+ value)
})
.mark({
strokeColor:Color.Black,
size: 50,
strokeWidth: 5
})
.unselectedColor(Color.Red)
.width(30)
.height(30)
Text('Checkbox1').fontSize(20)
}
Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
Checkbox({ name: 'checkbox2', group: 'checkboxGroup' })
.selectedColor(0x39a2db)
.shape(CheckBoxShape.ROUNDED_SQUARE)
.onChange((value: boolean) => {
console.info('Checkbox2 change is' + value)
})
.width(30)
.height(30)
Text('Checkbox2').fontSize(20)
}
}
.width('100%')
}
.height('100%')
}
}
ts
示例3
该示例实现了自定义复选框样式的功能,自定义样式实现了一个五边形复选框,如果选中,内部会出现红色三角图案,标题会显示选中字样,如果取消选中,红色三角图案消失,标题会显示非选中字样。
// xxx.ets
class MyCheckboxStyle implements ContentModifier<CheckBoxConfiguration> {
selectedColor: Color = Color.White
constructor(selectedColor: Color) {
this.selectedColor = selectedColor;
}
applyContent() : WrappedBuilder<[CheckBoxConfiguration]>
{
return wrapBuilder(buildCheckbox)
}
}
@Builder function buildCheckbox(config: CheckBoxConfiguration) {
Column({space:10}) {
Text(config.name + (config.selected ? "( 选中 )" : "( 非选中 )")).margin({right : 70, top : 50})
Text(config.enabled ? "enabled true" : "enabled false").margin({right : 110})
Shape() {
Path().width(100).height(100).commands('M100 0 L0 100 L50 200 L150 200 L200 100 Z').fillOpacity(0).strokeWidth(3).onClick(()=>{
if (config.selected) {
config.triggerChange(false)
} else {
config.triggerChange(true)
}
}).opacity(config.enabled ? 1 : 0.1)
Path().width(10).height(10).commands('M50 0 L100 100 L0 100 Z')
.visibility(config.selected ? Visibility.Visible : Visibility.Hidden)
.fill(config.selected ? (config.contentModifier as MyCheckboxStyle).selectedColor : Color.Black)
.stroke((config.contentModifier as MyCheckboxStyle).selectedColor)
.margin({left:11,top:10})
.opacity(config.enabled ? 1 : 0.1)
}
.width(300)
.height(200)
.viewPort({ x: 0, y: 0, width: 310, height: 310 })
.strokeLineJoin(LineJoinStyle.Miter)
.strokeMiterLimit(5)
.margin({left:50})
}
}
@Entry
@Component
struct Index {
@State checkboxEnabled: boolean = true;
build() {
Column({ space: 100 }) {
Checkbox({ name: '复选框状态', group: 'checkboxGroup' })
.contentModifier(new MyCheckboxStyle(Color.Red))
.onChange((value: boolean) => {
console.info('Checkbox change is' + value)
}).enabled(this.checkboxEnabled)
Row() {
Toggle({ type: ToggleType.Switch, isOn: true }).onChange((value: boolean) => {
if (value) {
this.checkboxEnabled = true
} else {
this.checkboxEnabled = false
}
})
}
}.margin({top : 30})
}
}
ts
示例4
该示例设置选中样式为Text。
// xxx.ets
@Entry
@Component
struct CheckboxExample {
@Builder
indicatorBuilder(value: number) {
Column(){
Text(value > 99 ? '99+': value.toString())
.textAlign(TextAlign.Center)
.fontSize(value > 99 ? '16vp': '20vp')
.fontWeight(FontWeight.Medium)
.fontColor('#ffffffff')
}
}
build() {
Row() {
Column() {
Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center}) {
Checkbox({ name: 'checkbox1', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(9)}})
.shape(CheckBoxShape.CIRCLE)
.onChange((value: boolean) => {
console.info('Checkbox1 change is'+ value)
})
.mark({
strokeColor:Color.Black,
size: 50,
strokeWidth: 5
})
.width(30)
.height(30)
Text('Checkbox1').fontSize(20)
}.padding(15)
Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
Checkbox({ name: 'checkbox2', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(100)}})
.shape(CheckBoxShape.ROUNDED_SQUARE)
.onChange((value: boolean) => {
console.info('Checkbox2 change is' + value)
})
.width(30)
.height(30)
Text('Checkbox2').fontSize(20)
}
}
.width('100%')
}
.height('100%')
}
}
ts