基础组件
# AlphabetIndexer
可以与容器组件联动用于按逻辑结构快速定位容器显示区域的组件。
该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
无
#### 接口
AlphabetIndexer(value: {arrayValue: Array<string>, selected: number})
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**参数：**
| 参数名 | 参数类型 | 必填 | 参数描述 |
| --- | --- | --- | --- |
| arrayValue | Array<string> | 是 | 字母索引字符串数组，不可设置为空。 |
| selected | number | 是 | 初始选中项索引值，若超出索引值范围，则取默认值0。从API version 10开始，该参数支持[$$](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-two-way-sync-V5)双向绑定变量。 |
#### 属性
[width](zh-cn_topic_0000001945367680.html#ZH-CN_TOPIC_0000001945367680__width)属性设置"auto"时表示自适应宽度，宽度会随索引项最大宽度变化。
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### color
color(value: ResourceColor)
设置文字颜色。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 文字颜色。默认值：0x99182431。 |
#### selectedColor
selectedColor(value: ResourceColor)
设置选中项文字颜色。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 选中项文字颜色。默认值：0xFF007DFF。 |
#### popupColor
popupColor(value: ResourceColor)
设置提示弹窗文字颜色。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 提示弹窗文字颜色。默认值：0xFF007DFF。 |
#### selectedBackgroundColor
selectedBackgroundColor(value: ResourceColor)
设置选中项背景颜色。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 选中项背景颜色。默认值：0x1A007DFF。 |
#### popupBackground
popupBackground(value: ResourceColor)
设置提示弹窗背景色。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 提示弹窗背景色。默认值：API version 11及以前：0xFFFFFFFF。API version 12及以后：#66808080。 |
#### usingPopup
usingPopup(value: boolean)
设置是否使用提示弹窗。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 是否使用提示弹窗。默认值：false。 |
#### selectedFont
selectedFont(value: Font)
设置选中项文字样式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [Font](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__font) | 是 | 选中项文字样式。默认值：API version 11及以前：{size:'12.0fp',style:FontStyle.Normal,weight:FontWeight.Normal,family:'HarmonyOS Sans'}API version 12及以后：{size:'10.0vp',style:FontStyle.Normal,weight:FontWeight.Medium,family:'HarmonyOS Sans'} |
#### popupFont
popupFont(value: Font)
设置提示弹窗字体样式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [Font](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__font) | 是 | 提示弹窗字体样式。默认值：{size:'24.0vp',style:FontStyle.Normal,weight:FontWeight.Normal,family:'HarmonyOS Sans'} |
#### font
font(value: Font)
设置字母索引条默认字体样式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [Font](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__font) | 是 | 字母索引条默认字体样式。默认值：API version 11及以前：{size:'12.0fp',style:FontStyle.Normal,weight:FontWeight.Normal,family:'HarmonyOS Sans'}API version 12及以后：{size:'10.0vp',style:FontStyle.Normal,weight:FontWeight.Medium,family:'HarmonyOS Sans'} |
#### itemSize
itemSize(value: string | number)
设置字母索引条字母区域大小。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | string \\| number | 是 | 字母索引条字母区域大小，字母区域为正方形，即正方形边长。不支持设置为百分比。默认值：16.0单位：vp |
#### alignStyle
alignStyle(value: IndexerAlign, offset?: Length)
设置字母索引条弹框的对齐样式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [IndexerAlign](#ZH-CN_TOPIC_0000001972645913__indexeralign枚举说明) | 是 | 字母索引条弹框的对齐样式，支持弹窗显示在索引条右侧和左侧。默认值: IndexerAlign.END。 |
| offset10+ | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length) | 否 | 提示弹窗与索引条之间间距，大于等于0为有效值，在不设置或设置为小于0的情况下间距与popupPosition.x相同。与popupPosition同时设置时，水平方向上offset生效，竖直方向上popupPosition.y生效。 |
#### selected8+
selected(index: number)
设置选中项索引值。
从API version 10开始，该参数支持[$$](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-two-way-sync-V5)双向绑定变量。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| index | number | 是 | 选中项索引值。默认值：0 |
#### popupPosition8+
popupPosition(value: Position)
设置弹出窗口相对于索引器条上边框中点的位置。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [Position](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__position) | 是 | 弹出窗口相对于索引器条上边框中点的位置。默认值：{x:60.0, y:48.0} |
#### popupSelectedColor10+
popupSelectedColor(value: ResourceColor)
设置提示弹窗非字母部分选中文字色。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 提示弹窗非字母部分选中文字色。默认值：#FF182431 |
#### popupUnselectedColor10+
popupUnselectedColor(value: ResourceColor)
设置提示弹窗非字母部分未选中文字色。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 提示弹窗非字母部分未选中文字色。默认值：#FF182431 |
#### popupItemFont10+
popupItemFont(value: Font)
设置提示弹窗非字母部分字体样式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [Font](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__font) | 是 | 提示弹窗非字母部分字体样式。默认值：{size:24,weight:FontWeight.Medium} |
#### popupItemBackgroundColor10+
popupItemBackgroundColor(value: ResourceColor)
设置提示弹窗非字母部分背景色。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 提示弹窗非字母部分背景色。默认值：API version 11及以前：#FFFFFFFF。API version 12及以后：#00000000。 |
#### autoCollapse11+
autoCollapse(value: boolean)
设置是否使用自适应折叠模式。
如果字符串首字符为“#”，除去首字符。当剩余字符数 $\leq$ 9时，选择全显示模式。当9 < 剩余字符数 $\leq$ 13时，根据索引条高度自适应选择全显示模式或者短折叠模式。当剩余字符数 > 13时，根据索引条高度自适应选择短折叠模式或者长折叠模式。
如果字符串首字符不为“#”。当所有字符数 $\leq$ 9时，选择全显示模式。当9 < 所有字符数 $\leq$ 13时，根据索引条高度自适应选择全显示模式或者短折叠模式。当所有字符数 > 13时，根据索引条高度自适应选择短折叠模式或者长折叠模式。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 是否使用自适应折叠模式。默认值：false |
#### popupItemBorderRadius12+
popupItemBorderRadius(value: number)
设置提示弹窗索引项背板圆角半径。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | number | 是 | 设置提示弹窗索引项背板圆角半径。默认值：24vp。不支持百分比，小于0时按照0设置。提示弹窗背板圆角自适应变化（索引项圆角半径+4vp）。 |
#### itemBorderRadius12+
itemBorderRadius(value: number)
设置索引项背板圆角半径。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | number | 是 | 设置索引项背板圆角半径。默认值：8vp不支持百分比，小于0时按照0设置。索引条背板圆角自适应变化（索引项圆角半径+4vp）。 |
#### popupBackgroundBlurStyle12+
popupBackgroundBlurStyle(value: BlurStyle)
设置提示弹窗的背景模糊材质。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [BlurStyle](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__blurstyle9) | 是 | 设置提示弹窗的背景模糊材质。默认值：COMPONENT_REGULAR。 |
#### popupTitleBackground12+
popupTitleBackground(value: ResourceColor)
设置提示弹窗首个索引项背板颜色。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 设置提示弹窗首个索引项背板颜色。默认值：提示弹窗只有一个索引项：#00FFFFFF。提示弹窗有多个索引项：#0c182431。 |
#### enableHapticFeedback12+
enableHapticFeedback(enable: boolean)
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| enable | boolean | 否 | 支持触控反馈。默认值：true。 |
#### IndexerAlign枚举说明
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 描述 |
| --- | --- |
| Left | 弹框显示在索引条右侧。 |
| Right | 弹框显示在索引条左侧。 |
| START12+ | 在LTR场景下，弹框显示在索引条右侧的位置。在RTL场景下，弹框显示在索引条左侧的位置。 |
| END12+ | 在LTR场景下，弹框显示在索引条左侧的位置。在RTL场景下，弹框显示在索引条右侧的位置。 |
#### 事件
除支持[通用事件](zh-cn_topic_0000001972686089.html)外，还支持以下事件：
#### onSelected(deprecated)
onSelected(callback: (index: number) => void)
索引条选中回调，返回值为当前选中索引。
从API Version 8开始废弃，建议使用[onSelect](#ZH-CN_TOPIC_0000001972645913__onselect8)代替。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| index | number | 是 | 当前选中的索引。 |
#### onSelect8+
onSelect(callback: (index: number) => void)
索引条选中回调，返回值为当前选中索引。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| index | number | 是 | 当前选中的索引。 |
#### onRequestPopupData8+
onRequestPopupData(callback: (index: number) => Array<string>)
选中字母索引后，请求索引提示弹窗显示内容回调。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| index | number | 是 | 当前选中的索引 |
**返回值：**
| 类型 | 说明 |
| --- | --- |
| Array<string> | 索引对应的字符串数组，此字符串数组在弹窗中竖排显示，字符串列表最多显示5个，超出部分可以滑动显示。 |
#### onPopupSelect8+
onPopupSelect(callback: (index: number) => void)
字母索引提示弹窗字符串列表选中回调。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| index | number | 是 | 当前选中的索引。 |
#### 示例
#### 示例1
// xxx.ets
@Entry
@Component
struct AlphabetIndexerSample {
private arrayA: string[] = ['安']
private arrayB: string[] = ['卜', '白', '包', '毕', '丙']
private arrayC: string[] = ['曹', '成', '陈', '催']
private arrayL: string[] = ['刘', '李', '楼', '梁', '雷', '吕', '柳', '卢']
private value: string[] = ['#', 'A', 'B', 'C', 'D', 'E', 'F', 'G',
'H', 'I', 'J', 'K', 'L', 'M', 'N',
'O', 'P', 'Q', 'R', 'S', 'T', 'U',
'V', 'W', 'X', 'Y', 'Z']
build() {
Stack({ alignContent: Alignment.Start }) {
Row() {
List({ space: 20, initialIndex: 0 }) {
ForEach(this.arrayA, (item: string) => {
ListItem() {
Text(item)
.width('80%')
.height('5%')
.fontSize(30)
.textAlign(TextAlign.Center)
}
}, (item: string) => item)
ForEach(this.arrayB, (item: string) => {
ListItem() {
Text(item)
.width('80%')
.height('5%')
.fontSize(30)
.textAlign(TextAlign.Center)
}
}, (item: string) => item)
ForEach(this.arrayC, (item: string) => {
ListItem() {
Text(item)
.width('80%')
.height('5%')
.fontSize(30)
.textAlign(TextAlign.Center)
}
}, (item: string) => item)
ForEach(this.arrayL, (item: string) => {
ListItem() {
Text(item)
.width('80%')
.height('5%')
.fontSize(30)
.textAlign(TextAlign.Center)
}
}, (item: string) => item)
}
.width('50%')
.height('100%')
AlphabetIndexer({ arrayValue: this.value, selected: 0 })
.selectedColor(0xFFFFFF) // 选中项文本颜色
.popupColor(0xFFFAF0) // 弹出框文本颜色
.selectedBackgroundColor(0xCCCCCC) // 选中项背景颜色
.popupBackground(0xD2B48C) // 弹出框背景颜色
.usingPopup(true) // 是否显示弹出框
.selectedFont({ size: 16, weight: FontWeight.Bolder }) // 选中项字体样式
.popupFont({ size: 30, weight: FontWeight.Bolder }) // 弹出框内容的字体样式
.itemSize(28) // 每一项的尺寸大小
.alignStyle(IndexerAlign.Left) // 弹出框在索引条右侧弹出
.popupItemBorderRadius(24) // 设置提示弹窗索引项背板圆角半径
.itemBorderRadius(14) // 设置索引项背板圆角半径
.popupBackgroundBlurStyle(BlurStyle.NONE) // 设置提示弹窗的背景模糊材质
.popupTitleBackground(0xCCCCCC) // 设置提示弹窗首个索引项背板颜色
.popupSelectedColor(0x00FF00)
.popupUnselectedColor(0x0000FF)
.popupItemFont({ size: 30, style: FontStyle.Normal })
.popupItemBackgroundColor(0xCCCCCC)
.onSelect((index: number) => {
console.info(this.value[index] + ' Selected!')
})
.onRequestPopupData((index: number) => {
if (this.value[index] == 'A') {
return this.arrayA // 当选中A时，弹出框里面的提示文本列表显示A对应的列表arrayA，选中B、C、L时也同样
} else if (this.value[index] == 'B') {
return this.arrayB
} else if (this.value[index] == 'C') {
return this.arrayC
} else if (this.value[index] == 'L') {
return this.arrayL
} else {
return [] // 选中其余子母项时，提示文本列表为空
}
})
.onPopupSelect((index: number) => {
console.info('onPopupSelected:' + index)
})
}
.width('100%')
.height('100%')
}
}
}
#### 示例2
// xxx.ets
@Entry
@Component
struct AlphabetIndexerSample {
private arrayA: string[] = ['安']
private arrayB: string[] = ['卜', '白', '包', '毕', '丙']
private arrayC: string[] = ['曹', '成', '陈', '催']
private arrayJ: string[] = ['嘉', '贾']
private value: string[] = ['#', 'A', 'B', 'C', 'D', 'E', 'F', 'G',
'H', 'I', 'J', 'K', 'L', 'M', 'N',
'O', 'P', 'Q', 'R', 'S', 'T', 'U',
'V', 'W', 'X', 'Y', 'Z']
@State isNeedAutoCollapse: boolean = false;
@State indexerHeight: string = '75%';
build() {
Stack({ alignContent: Alignment.Start }) {
Row() {
List({ space: 20, initialIndex: 0 }) {
ForEach(this.arrayA, (item: string) => {
ListItem() {
Text(item)
.width('80%')
.height('5%')
.fontSize(30)
.textAlign(TextAlign.Center)
}
}, (item: string) => item)
ForEach(this.arrayB, (item: string) => {
ListItem() {
Text(item)
.width('80%')
.height('5%')
.fontSize(30)
.textAlign(TextAlign.Center)
}
}, (item: string) => item)
ForEach(this.arrayC, (item: string) => {
ListItem() {
Text(item)
.width('80%')
.height('5%')
.fontSize(30)
.textAlign(TextAlign.Center)
}
}, (item: string) => item)
ForEach(this.arrayJ, (item: string) => {
ListItem() {
Text(item)
.width('80%')
.height('5%')
.fontSize(30)
.textAlign(TextAlign.Center)
}
}, (item: string) => item)
}
.width('50%')
.height('100%')
Column() {
Column() {
AlphabetIndexer({ arrayValue: this.value, selected: 0 })
.autoCollapse(this.isNeedAutoCollapse)
.height(this.indexerHeight)
.selectedColor(0xFFFFFF)// 选中项文本颜色
.popupColor(0xFFFAF0)// 弹出框文本颜色
.selectedBackgroundColor(0xCCCCCC)// 选中项背景颜色
.popupBackground(0xD2B48C)// 弹出框背景颜色
.usingPopup(true)// 是否显示弹出框
.selectedFont({ size: 16, weight: FontWeight.Bolder })// 选中项字体样式
.popupFont({ size: 30, weight: FontWeight.Bolder })// 弹出框内容的字体样式
.itemSize(28)// 每一项的尺寸大小
.alignStyle(IndexerAlign.Right)// 弹出框在索引条左侧弹出
.popupTitleBackground("#D2B48C") // 弹出框首个索引项背板颜色
.popupSelectedColor(0x00FF00)
.popupUnselectedColor(0x0000FF)
.popupItemFont({ size: 30, style: FontStyle.Normal })
.popupItemBackgroundColor(0xCCCCCC)
.onSelect((index: number) => {
console.info(this.value[index] + ' Selected!');
})
.onRequestPopupData((index: number) => {
if (this.value[index] == 'A') {
return this.arrayA;
} else if (this.value[index] == 'B') {
return this.arrayB;
} else if (this.value[index] == 'C') {
return this.arrayC;
} else if (this.value[index] == 'J') {
return this.arrayJ;
} else {
return [];
}
})
.onPopupSelect((index: number) => {
console.info('onPopupSelected:' + index);
})
}
.height('80%')
.justifyContent(FlexAlign.Center)
Column() {
Button('切换成折叠模式')
.margin('5vp')
.onClick(() => {
this.isNeedAutoCollapse = true;
})
Button('切换索引条高度到30%')
.margin('5vp')
.onClick(() => {
this.indexerHeight = '30%';
})
Button('切换索引条高度到70%')
.margin('5vp')
.onClick(() => {
this.indexerHeight = '70%';
})
}.height('20%')
}
.width('50%')
.justifyContent(FlexAlign.Center)
}
.width('100%')
.height('100%')
}
}
}
#### 示例3
// 该示例实现了自定义设置提示弹窗的背景模糊材质
@Entry
@Component
struct AlphabetIndexerSample {
private arrayA: string[] = ['安']
private arrayB: string[] = ['卜', '白', '包', '毕', '丙']
private arrayC: string[] = ['曹', '成', '陈', '催']
private arrayL: string[] = ['刘', '李', '楼', '梁', '雷', '吕', '柳', '卢']
private value: string[] = ['#', 'A', 'B', 'C', 'D', 'E', 'F', 'G',
'H', 'I', 'J', 'K', 'L', 'M', 'N',
'O', 'P', 'Q', 'R', 'S', 'T', 'U',
'V', 'W', 'X', 'Y', 'Z']
@State customBlurStyle: BlurStyle = BlurStyle.NONE;
build() {
Stack({ alignContent: Alignment.Start }) {
Row() {
List({ space: 20, initialIndex: 0 }) {
ForEach(this.arrayA, (item: string) => {
ListItem() {
Text(item)
.width('80%')
.height('5%')
.fontSize(30)
.textAlign(TextAlign.Center)
}
}, (item: string) => item)
ForEach(this.arrayB, (item: string) => {
ListItem() {
Text(item)
.width('80%')
.height('5%')
.fontSize(30)
.textAlign(TextAlign.Center)
}
}, (item: string) => item)
ForEach(this.arrayC, (item: string) => {
ListItem() {
Text(item)
.width('80%')
.height('5%')
.fontSize(30)
.textAlign(TextAlign.Center)
}
}, (item: string) => item)
ForEach(this.arrayL, (item: string) => {
ListItem() {
Text(item)
.width('80%')
.height('5%')
.fontSize(30)
.textAlign(TextAlign.Center)
}
}, (item: string) => item)
}
.width('30%')
.height('100%')
Column(){
Column() {
Text('切换模糊材质: ')
.fontSize(24)
.fontColor(0xcccccc)
.width('100%')
Button('COMPONENT_REGULAR')
.margin('5vp')
.width(200)
.onClick(() => {
this.customBlurStyle = BlurStyle.COMPONENT_REGULAR;
})
Button('BACKGROUND_THIN')
.margin('5vp')
.width(200)
.onClick(() => {
this.customBlurStyle = BlurStyle.BACKGROUND_THIN;
})
}.height('20%')
Column(){
AlphabetIndexer({ arrayValue: this.value, selected: 0 })
.usingPopup(true) // 是否显示弹出框
.alignStyle(IndexerAlign.Left) // 弹出框在索引条右侧弹出
.popupItemBorderRadius(24) // 设置提示弹窗索引项背板圆角半径
.itemBorderRadius(14) // 设置索引项背板圆角半径
.popupBackgroundBlurStyle(this.customBlurStyle) // 设置提示弹窗的背景模糊材质
.popupTitleBackground(0xCCCCCC) // 设置提示弹窗首个索引项背板颜色
.onSelect((index: number) => {
console.info(this.value[index] + ' Selected!')
})
.onRequestPopupData((index: number) => {
if (this.value[index] == 'A') {
return this.arrayA // 当选中A时，弹出框里面的提示文本列表显示A对应的列表arrayA，选中B、C、L时也同样
} else if (this.value[index] == 'B') {
return this.arrayB
} else if (this.value[index] == 'C') {
return this.arrayC
} else if (this.value[index] == 'L') {
return this.arrayL
} else {
return [] // 选中其余子母项时，提示文本列表为空
}
})
.onPopupSelect((index: number) => {
console.info('onPopupSelected:' + index)
})
}
.height('80%')
}
.width('70%')
}
.width('100%')
.height('100%')
.backgroundImage($r("app.media.image"))
}
}
}
# Blank
空白填充组件，在容器主轴方向上，空白填充组件具有自动填充容器空余部分的能力。仅当父组件为Row/Column/Flex时生效。
该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
无
#### 接口
Blank(min?: number | string)
从API version 10开始：
* Blank在父容器Row、Column、Flex主轴方向上未设置大小时会自动拉伸、压缩，设置了大小或容器自适应子节点大小时不会自动拉伸、压缩。
* Blank设置主轴方向大小（size）与min时约束关系为max(min, size)。
* Blank在父容器交叉轴上设置大小时不会撑满父容器交叉轴，交叉轴不设置大小时alignSelf默认值为ItemAlign.Stretch，会撑满容器交叉轴。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用
**参数：**
| 参数名 | 参数类型 | 必填 | 参数描述 |
| --- | --- | --- | --- |
| min | number \\| string | 否 | 空白填充组件在容器主轴上的最小大小。默认值：0**说明：**不支持设置百分比。负值使用默认值。当最小值大于容器可用空间时，使用最小值作为自身大小并超出容器。 |
#### 属性
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### color
color(value: ResourceColor)
设置空白填充的填充颜色。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 空白填充的填充颜色。默认值：Color.Transparent |
#### 事件
支持[通用事件](zh-cn_topic_0000001972686089.html)。
#### 示例
#### 示例1
Blank组件在横竖屏占满空余空间效果。
// xxx.ets
@Entry
@Component
struct BlankExample {
build() {
Column() {
Row() {
Text('Bluetooth').fontSize(18)
Blank()
Toggle({ type: ToggleType.Switch }).margin({ top: 14, bottom: 14, left: 6, right: 6 })
}.width('100%').backgroundColor(0xFFFFFF).borderRadius(15).padding({ left: 12 })
}.backgroundColor(0xEFEFEF).padding(20)
}
}
竖屏状态
横屏状态
#### 示例2
Blank组件的父组件未设置宽度时，min参数的使用效果。
// xxx.ets
@Entry
@Component
struct BlankExample {
build() {
Column({ space: 20 }) {
// blank父组件不设置宽度时，Blank失效，可以通过设置min最小宽度填充固定宽度
Row() {
Text('Bluetooth').fontSize(18)
Blank().color(Color.Yellow)
Toggle({ type: ToggleType.Switch }).margin({ top: 14, bottom: 14, left: 6, right: 6 })
}.backgroundColor(0xFFFFFF).borderRadius(15).padding({ left: 12 })
Row() {
Text('Bluetooth').fontSize(18)
// 设置最小宽度为160
Blank('160').color(Color.Yellow)
Toggle({ type: ToggleType.Switch }).margin({ top: 14, bottom: 14, left: 6, right: 6 })
}.backgroundColor(0xFFFFFF).borderRadius(15).padding({ left: 12 })
}.backgroundColor(0xEFEFEF).padding(20).width('100%')
}
}
Blank父组件未设置宽度时，子组件间无空白填充，使用min参数设置填充尺寸
# Button
按钮组件，可快速创建不同样式的按钮。
该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
可以包含单个子组件。
#### 接口
#### Button
Button(options: ButtonOptions)
创建可以包含单个子组件的按钮。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| options | [ButtonOptions](#ZH-CN_TOPIC_0000001945527068__buttonoptions对象说明) | 是 | 配置按钮的显示样式。 |
#### Button
Button(label: ResourceStr, options?: ButtonOptions)
使用文本内容创建相应的按钮组件，此时Button无法包含子组件。
文本内容默认单行显示。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| label | [ResourceStr](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcestr) | 是 | 按钮文本内容。 |
| options | [ButtonOptions](#ZH-CN_TOPIC_0000001945527068__buttonoptions对象说明) | 否 | 配置按钮的显示样式。 |
#### ButtonOptions对象说明
| 名称 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| type | [ButtonType](#ZH-CN_TOPIC_0000001945527068__buttontype枚举说明) | 否 | 描述按钮显示样式。默认值：ButtonType.Capsule**元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| stateEffect | boolean | 否 | 按钮按下时是否开启按压态显示效果，当设置为false时，按压效果关闭。默认值：true**说明：**当开启按压态显示效果，开发者设置状态样式时，会基于状态样式设置完成后的背景色再进行颜色叠加。**元服务API：** 从API version 11开始，该接口支持在元服务中使用。 |
| buttonStyle11+ | [ButtonStyleMode](#ZH-CN_TOPIC_0000001945527068__buttonstylemode11枚举说明) | 否 | 描述按钮的样式和重要程度。默认值：ButtonStyleMode.EMPHASIZED**说明：**按钮重要程度：强调按钮>普通按钮>文字按钮。**元服务API：** 从API version 12开始，该接口支持在元服务中使用。 |
| controlSize11+ | [ControlSize](#ZH-CN_TOPIC_0000001945527068__controlsize11枚举说明) | 否 | 描述按钮的尺寸。默认值：ControlSize.NORMAL**元服务API：** 从API version 12开始，该接口支持在元服务中使用。 |
| role12+ | [ButtonRole](#ZH-CN_TOPIC_0000001945527068__buttonrole12枚举说明) | 否 | 描述按钮的角色。默认值：ButtonRole.NORMAL |
#### 属性
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### type
type(value: ButtonType)
设置Button样式。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ButtonType](#ZH-CN_TOPIC_0000001945527068__buttontype枚举说明) | 是 | Button样式。默认值：ButtonType.Capsule |
#### fontSize
fontSize(value: Length)
设置文本显示字号。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length) | 是 | 文本显示字号。默认值：若controlSize的值为：controlSize.NORMAL，取'16fp'，若controlSize的值为：controlSize.SMALL，取'12fp' |
#### fontColor
fontColor(value: ResourceColor)
设置文本显示颜色。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 文本显示颜色。默认值：'#ffffff' |
#### fontWeight
fontWeight(value: number | FontWeight | string)
设置文本的字体粗细。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [FontWeight](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__fontweight) \\| number \\| string | 是 | 文本的字体粗细，number类型取值[100, 900]，取值间隔为100，取值越大，字体越粗。默认值：400 |
#### fontStyle
fontStyle(value: FontStyle)
设置文本的字体样式。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [FontStyle](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__fontstyle) | 是 | 文本的字体样式。默认值：FontStyle.Normal。 |
#### stateEffect
stateEffect(value: boolean)
设置是否开启按压态显示效果。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 按钮按下时是否开启按压态显示效果，当设置为false时，按压效果关闭。默认值：true |
#### fontFamily
fontFamily(value: string | Resource)
设置字体列表。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [Resource](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resource) \\| string | 是 | 字体列表。默认字体'HarmonyOS Sans'，当前支持'HarmonyOS Sans'字体和[注册自定义字体](zh-cn_topic_0000001960459825.html)。 |
#### labelStyle10+
labelStyle(value: LabelStyle)
设置Button组件label文本和字体的样式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [LabelStyle](#ZH-CN_TOPIC_0000001945527068__labelstyle10对象说明) | 是 | Button组件label文本和字体的样式。 |
#### buttonStyle11+
buttonStyle(value: ButtonStyleMode)
设置Button组件的样式和重要程度。
**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ButtonStyleMode](#ZH-CN_TOPIC_0000001945527068__buttonstylemode11枚举说明) | 是 | Button组件的样式和重要程度。默认值:ButtonStyleMode.EMPHASIZED |
#### controlSize11+
controlSize(value: ControlSize)
设置Button组件的尺寸。
**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ControlSize](#ZH-CN_TOPIC_0000001945527068__controlsize11枚举说明) | 是 | Button组件的尺寸。默认值:ControlSize.NORMAL |
#### role12+
role(value: ButtonRole)
设置Button组件的角色。
**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ButtonRole](#ZH-CN_TOPIC_0000001945527068__buttonrole12枚举说明) | 是 | 设置Button组件的角色。默认值:ButtonRole.NORMAL |
#### contentModifier12+
contentModifier(modifier: ContentModifier<ButtonConfiguration>)
定制Button内容区的方法。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| modifier | [ContentModifier](#ZH-CN_TOPIC_0000001945527068__buttonconfiguration12对象说明) | 是 | 在Button组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。 |
#### ButtonType枚举说明
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 描述 |
| --- | --- |
| Capsule | 胶囊型按钮（圆角默认为高度的一半）。 |
| Circle | 圆形按钮。 |
| Normal | 普通按钮（默认不带圆角）。 |
* 按钮圆角通过[通用属性borderRadius](zh-cn_topic_0000001945367684.html#ZH-CN_TOPIC_0000001945367684__borderradius)设置（不支持通过border接口设置圆角），且只支持设置参数为[Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length)的圆角。
* 当按钮类型为Capsule时，borderRadius设置不生效，按钮圆角始终为宽、高中较小值的一半。
* 当按钮类型为Circle时，若同时设置了宽和高，则borderRadius不生效，且按钮半径为宽高中较小值的一半；若只设置宽、高中的一个，则borderRadius不生效，且按钮半径为所设宽或所设高值的一半；若不设置宽高，则borderRadius为按钮半径；若borderRadius的值为负，则borderRadius的值按照0处理。
* 按钮文本通过[通用文本样式](zh-cn_topic_0000001972645893.html#ZH-CN_TOPIC_0000001972645893__属性)进行设置。
* 设置[颜色渐变](zh-cn_topic_0000001945367696.html)需先设置[backgroundColor](zh-cn_topic_0000001972686109.html#ZH-CN_TOPIC_0000001972686109__backgroundcolor)为透明色。
#### LabelStyle10+对象说明
**元服务API：** 从API version 11开始，该接口支持在元服务中使用
| 名称 | 参数类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| overflow | [TextOverflow](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__textoverflow) | 否 | 设置label文本超长时的显示方式。文本截断是按字截断。例如，英文以单词为最小单位进行截断，若需要以字母为单位进行截断，可在字母间添加零宽空格。默认值：TextOverflow.Ellipsis |
| maxLines | number | 否 | 设置label文本的最大行数。默认情况下，文本是自动折行的，如果指定此参数，则文本最多不会超过指定的行。如果有多余的文本，可以通过overflow来指定截断方式。默认值：1 |
| minFontSize | number \\| [ResourceStr](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcestr) | 否 | 设置label文本最小显示字号。需配合maxFontSize以及maxLines或布局大小限制使用。**说明：**minFontSize小于或等于0时，自适应字号不生效。 |
| maxFontSize | number \\| [ResourceStr](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcestr) | 否 | 设置label文本最大显示字号。需配合minFontSize以及maxLines或布局大小限制使用。 |
| heightAdaptivePolicy | [TextHeightAdaptivePolicy](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__textheightadaptivepolicy10) | 否 | 设置label文本自适应高度的方式。默认值：TextHeightAdaptivePolicy.MAX_LINES_FIRST。 |
| font | [Font](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__font) | 否 | 设置label文本字体样式。默认值：默认值参考[Font](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__font)。 |
#### ButtonStyleMode11+枚举说明
**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
| 名称 | 描述 |
| --- | --- |
| EMPHASIZED | 强调按钮（用于强调当前操作）。 |
| NORMAL | 普通按钮（一般界面操作）。 |
| TEXTUAL | 文本按钮（纯文本，无背景颜色）。 |
#### ControlSize11+枚举说明
**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
| 名称 | 描述 |
| --- | --- |
| SMALL | 小尺寸按钮。 |
| NORMAL | 正常尺寸按钮。 |
#### ButtonRole12+枚举说明
**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
| 名称 | 描述 |
| --- | --- |
| NORMAL | 正常按钮。 |
| ERROR | 警示按钮。 |
#### ButtonConfiguration12+对象说明
开发者需要自定义class实现ContentModifier接口。
| 参数名 | 类型 | 说明 |
| --- | --- | --- |
| label | string | Button的文本标签。 |
| pressed | boolean | 指示是否按下Button。**说明：**此属性指示的是原本Button是否被按压，而非build出来的新组件。若新build出来的组件超过原本组件的大小，那么超出部分按压不触发。 |
| triggerClick | [ButtonTriggerClickCallback](#ZH-CN_TOPIC_0000001945527068__buttontriggerclickcallback12对象说明) | 使用builder新构建出来组件的点击事件。 |
#### ButtonTriggerClickCallback12+对象说明
定义ButtonConfiguration中使用的回调类型。
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| xPos | number | 是 | 点击位置x的坐标。 |
| yPos | number | 是 | 点击位置y的坐标。 |
#### 事件
支持[通用事件](zh-cn_topic_0000001972686089.html)。
#### 示例
#### 示例1
// xxx.ets
@Entry
@Component
struct ButtonExample {
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
Text('Normal button').fontSize(9).fontColor(0xCCCCCC)
Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
Button('OK', { type: ButtonType.Normal, stateEffect: true })
.borderRadius(8)
.backgroundColor(0x317aff)
.width(90)
.onClick(() => {
console.log('ButtonType.Normal')
})
Button({ type: ButtonType.Normal, stateEffect: true }) {
Row() {
LoadingProgress().width(20).height(20).margin({ left: 12 }).color(0xFFFFFF)
Text('loading').fontSize(12).fontColor(0xffffff).margin({ left: 5, right: 12 })
}.alignItems(VerticalAlign.Center)
}.borderRadius(8).backgroundColor(0x317aff).width(90).height(40)
Button('Disable', { type: ButtonType.Normal, stateEffect: false }).opacity(0.4)
.borderRadius(8).backgroundColor(0x317aff).width(90)
}
Text('Capsule button').fontSize(9).fontColor(0xCCCCCC)
Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
Button('OK', { type: ButtonType.Capsule, stateEffect: true }).backgroundColor(0x317aff).width(90)
Button({ type: ButtonType.Capsule, stateEffect: true }) {
Row() {
LoadingProgress().width(20).height(20).margin({ left: 12 }).color(0xFFFFFF)
Text('loading').fontSize(12).fontColor(0xffffff).margin({ left: 5, right: 12 })
}.alignItems(VerticalAlign.Center).width(90).height(40)
}.backgroundColor(0x317aff)
Button('Disable', { type: ButtonType.Capsule, stateEffect: false }).opacity(0.4)
.backgroundColor(0x317aff).width(90)
}
Text('Circle button').fontSize(9).fontColor(0xCCCCCC)
Flex({ alignItems: ItemAlign.Center, wrap: FlexWrap.Wrap }) {
Button({ type: ButtonType.Circle, stateEffect: true }) {
LoadingProgress().width(20).height(20).color(0xFFFFFF)
}.width(55).height(55).backgroundColor(0x317aff)
Button({ type: ButtonType.Circle, stateEffect: true }) {
LoadingProgress().width(20).height(20).color(0xFFFFFF)
}.width(55).height(55).margin({ left: 20 }).backgroundColor(0xF55A42)
}
}.height(400).padding({ left: 35, right: 35, top: 35 })
}
}
#### 示例2
// xxx.ets
@Entry
@Component
struct SwipeGestureExample {
@State count: number = 0
build() {
Column() {
Text(`${this.count}`)
.fontSize(30)
.onClick(() => {
this.count++
})
if (this.count <= 0) {
Button('count is negative').fontSize(30).height(50)
} else if (this.count % 2 === 0) {
Button('count is even').fontSize(30).height(50)
} else {
Button('count is odd').fontSize(30).height(50)
}
}.height('100%').width('100%').justifyContent(FlexAlign.Center)
}
}
#### 示例3
// xxx.ets
@Entry
@Component
struct buttonTestDemo {
@State txt: string = 'overflowTextOverlengthTextOverflow.Clip';
@State widthShortSize: number = 200;
build() {
Row() {
Column() {
Button(this.txt)
.width(this.widthShortSize)
.height(100)
.labelStyle({ overflow: TextOverflow.Clip,
maxLines: 1,
minFontSize: 20,
maxFontSize: 20,
font: {
size: 20,
weight: FontWeight.Bolder,
family: 'cursive',
style: FontStyle.Italic
}
})
.fontSize(40)
}
.width('100%')
}
.height('100%')
}
}
#### 示例4
// xxx.ets
@Entry
@Component
struct ButtonExample {
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
Text('Normal size button').fontSize(9).fontColor(0xCCCCCC)
Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
Button('Emphasized', { buttonStyle: ButtonStyleMode.EMPHASIZED });
Button('Normal', { buttonStyle: ButtonStyleMode.NORMAL });
Button('Textual', { buttonStyle: ButtonStyleMode.TEXTUAL });
}
Text('Small size button').fontSize(9).fontColor(0xCCCCCC)
Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
Button('Emphasized', { controlSize: ControlSize.SMALL, buttonStyle: ButtonStyleMode.EMPHASIZED });
Button('Normal', { controlSize: ControlSize.SMALL, buttonStyle: ButtonStyleMode.NORMAL });
Button('Textual', { controlSize: ControlSize.SMALL, buttonStyle: ButtonStyleMode.TEXTUAL });
}
Text('Small size button').fontSize(9).fontColor(0xCCCCCC)
Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
Button('Emphasized').controlSize(ControlSize.SMALL).buttonStyle(ButtonStyleMode.EMPHASIZED);
Button('Normal').controlSize(ControlSize.SMALL).buttonStyle(ButtonStyleMode.NORMAL);
Button('Textual').controlSize(ControlSize.SMALL).buttonStyle(ButtonStyleMode.TEXTUAL);
}
}.height(400).padding({ left: 35, right: 35, top: 35 })
}
}
#### 示例5
// xxx.ets
@Entry
@Component
struct ButtonExample {
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start, justifyContent: FlexAlign.SpaceBetween }) {
Text('Role is Normal button').fontSize(9).fontColor(0xCCCCCC)
Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
Button('Emphasized', { buttonStyle: ButtonStyleMode.EMPHASIZED, role: ButtonRole.NORMAL });
Button('Normal', { buttonStyle: ButtonStyleMode.NORMAL, role: ButtonRole.NORMAL });
Button('Textual', { buttonStyle: ButtonStyleMode.TEXTUAL, role: ButtonRole.NORMAL });
}
Text('Role is Error button').fontSize(9).fontColor(0xCCCCCC)
Flex({ alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceBetween }) {
Button('Emphasized', { buttonStyle: ButtonStyleMode.EMPHASIZED, role: ButtonRole.ERROR});
Button('Normal', { buttonStyle: ButtonStyleMode.NORMAL, role: ButtonRole.ERROR });
Button('Textual', { buttonStyle: ButtonStyleMode.TEXTUAL, role: ButtonRole.ERROR });
}
}.height(200).padding({ left: 35, right: 35, top: 35 })
}
}
#### 示例6
该示例实现了自定义样式的功能，自定义样式实现了一个圆圈替换原本的按钮样式。如果按压，圆圈将变成红色，标题会显示按压字样；如果没有按压，圆圈将变成黑色，标题会显示非按压字样。
class MyButtonStyle implements ContentModifier<ButtonConfiguration> {
x: number = 0
y: number = 0
selectedColor:Color = Color.Black
constructor(x : number, y: number,ColorType:Color) {
this.x = x
this.y = y
this.selectedColor = ColorType
}
applyContent() : WrappedBuilder<[ButtonConfiguration]>
{
return wrapBuilder(buildButton1)
}
}
@Builder function buildButton1(config: ButtonConfiguration) {
Column({space:30}) {
Text(config.enabled ? "enabled true" : "enabled false")
Text('圆圈状态' + (config.pressed ? "（ 按压 ）" : "（ 非按压 ）"))
Text('点击位置x坐标：' + (config.enabled ? (config.contentModifier as MyButtonStyle).x : "0"))
Text('点击位置y坐标：' + (config.enabled ? (config.contentModifier as MyButtonStyle).y : "0"))
Circle({ width: 50, height: 50 })
.fill(config.pressed ? (config.contentModifier as MyButtonStyle).selectedColor : Color.Black)
.gesture(
TapGesture({count:1}).onAction((event: GestureEvent)=>{
config.triggerClick(event.fingerList[0].localX,event.fingerList[0].localY)
})).opacity(config.enabled ? 1 : 0.1)
}
}
@Entry
@Component
struct ButtonExample {
@State buttonEnabled: boolean = true;
@State positionX: number = 0
@State positionY: number = 0
@State state : boolean[] = [true,false]
@State index:number = 0
build() {
Column() {
Button('OK')
.contentModifier(new MyButtonStyle(this.positionX,this.positionY,Color.Red))
.onClick((event) => {
console.info('change' + JSON.stringify(event))
this.positionX = event.displayX
this.positionY = event.displayY
}).enabled(this.buttonEnabled)
Row() {
Toggle({ type: ToggleType.Switch, isOn: true }).onChange((value: boolean) => {
if (value) {
this.buttonEnabled = true
} else {
this.buttonEnabled = false
}
}).margin({left:-80})
}
}.height('100%').width('100%').justifyContent(FlexAlign.Center)
}
}
# CalendarPicker
日历选择器组件，提供下拉日历弹窗，可以让用户选择日期。
该组件从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
无
#### 接口
CalendarPicker(options?: CalendarOptions)
日历选择器。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| options | [CalendarOptions](#ZH-CN_TOPIC_0000001945367748__calendaroptions对象说明) | 否 | 配置日历选择器组件的参数。 |
#### 属性
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### edgeAlign
edgeAlign(alignType: CalendarAlign, offset?: Offset)
设置选择器与入口组件的对齐方式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| alignType | [CalendarAlign](#ZH-CN_TOPIC_0000001945367748__calendaralign枚举说明) | 是 | 对齐方式类型。默认值：CalendarAlign .END |
| offset | [Offset](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__offset) | 否 | 按照对齐类型对齐后，选择器相对入口组件的偏移量。默认值：{dx: 0, dy: 0} |
#### textStyle
textStyle(value: PickerTextStyle)
入口区的文本颜色、字号、字体粗细。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [PickerTextStyle](zh-cn_topic_0000001972686177.html#ZH-CN_TOPIC_0000001972686177__pickertextstyle10类型说明) | 是 | 设置入口区的文本颜色、字号、字体粗细。默认值：{color: '#ff182431',font: {size: '16fp',weight: FontWeight.Regular}} |
#### 事件
除支持[通用事件](zh-cn_topic_0000001972686089.html)，还支持以下事件：
#### onChange
onChange(callback: (value: Date) => void)
选择日期时触发该事件。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | Date | 是 | 选中的日期值。 |
#### CalendarOptions对象说明
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| hintRadius | number \\| [Resource](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resource) | 否 | 描述日期选中态底板样式。默认值：底板样式为圆形。**说明：**hintRadius为0，底板样式为直角矩形。hintRadius为0 ~ 16，底板样式为圆角矩形。hintRadius>=16，底板样式为圆形 |
| selected | Date | 否 | 设置选中项的日期。选中的日期未设置或日期格式不符合规范则为默认值。默认值：当前系统日期。 |
#### CalendarAlign枚举说明
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 描述 |
| --- | --- |
| START | 设置选择器与入口组件左对齐的对齐方式。 |
| CENTER | 设置选择器与入口组件居中对齐的对齐方式。 |
| END | 设置选择器与入口组件右对齐的对齐方式。 |
#### 示例
// xxx.ets
@Entry
@Component
struct CalendarPickerExample {
private selectedDate: Date = new Date('2024-03-05')
build() {
Column() {
Text('月历日期选择器').fontSize(30)
Column() {
CalendarPicker({ hintRadius: 10, selected: this.selectedDate })
.edgeAlign(CalendarAlign.END)
.textStyle({ color: "#ff182431", font: { size: 20, weight: FontWeight.Normal } })
.margin(10)
.onChange((value) => {
console.info("CalendarPicker onChange:" + JSON.stringify(value))
})
}.alignItems(HorizontalAlign.End).width("100%")
}.width('100%').margin({ top: 350 })
}
}
# Chekbox
提供多选框组件，通常用于某选项的打开或关闭。
API version 11开始，Checkbox默认样式由圆角方形变为圆形。
该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
无
#### 接口
Checkbox(options?: CheckboxOptions)
多选框组件。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| options | [CheckboxOptions](#ZH-CN_TOPIC_0000001972645917__checkboxoptions对象说明) | 否 | 配置复选框的参数。 |
#### CheckboxOptions对象说明
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| name | string | 否 | 用于指定多选框名称。 |
| group | string | 否 | 用于指定多选框所属群组的名称（即所属CheckboxGroup的名称）。**说明：**未配合使用[CheckboxGroup](zh-cn_topic_0000001972686173.html)组件时，此值无用。 |
| indicatorBuilder12+ | [CustomBuilder](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__custombuilder8) | 否 | 配置多选框的选中样式为自定义组件。自定义组件与Checkbox组件为中心点对齐显示。indicatorBuilder设置为undefined/null时，默认为indicatorBuilder未设置状态。 |
#### 属性
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### select
select(value: boolean)
设置多选框是否选中。
从API version 10开始，该属性支持[$$](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-two-way-sync-V5)双向绑定变量。
**卡片能力：** 从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](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 多选框选中状态颜色。默认值：$r('sys.color.ohos_id_color_text_primary_activated')。异常值按照默认值处理。 |
#### unselectedColor10+
unselectedColor(value: ResourceColor)
设置多选框非选中状态边框颜色。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 多选框非选中状态边框颜色。默认值：'#33ffffff'。 |
#### mark10+
mark(value: MarkStyle)
设置多选框内部图标样式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| value | [MarkStyle](#ZH-CN_TOPIC_0000001972645917__markstyle10对象说明) | 是 | 多选框内部图标样式。 从API version 12开始，设置了indicatorBuilder时，按照indicatorBuilder中的内容显示。 |
#### shape11+
shape(value: CheckBoxShape)
设置CheckBox组件形状, 包括圆形和圆角方形。
**卡片能力：** 从API version 11开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| value | [CheckBoxShape](#ZH-CN_TOPIC_0000001972645917__checkboxshape11枚举类型说明) | 是 | CheckBox组件形状, 包括圆形和圆角方形。默认值：CheckBoxShape.CIRCLE |
#### contentModifier12+
contentModifier(modifier: ContentModifier<CheckBoxConfiguration>)
定制CheckBox内容区的方法。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| modifier | [ContentModifier](#ZH-CN_TOPIC_0000001972645917__checkboxconfiguration12对象说明) | 是 | 在CheckBox组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。 |
#### 事件
支持[通用事件](zh-cn_topic_0000001972686089.html)外，还支持以下事件：
#### 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](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 否 | Color.White | 内部图标颜色。 |
| size | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length) | 否 | - | 内部图标大小，单位vp。默认大小与多选框组件宽度设置值一致。不支持百分比形式设置。当设置为非法值时，按照默认值处理。 |
| strokeWidth | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__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)
})
}
}
}
#### 示例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%')
}
}
#### 示例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})
}
}
#### 示例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%')
}
}
# CheckboxGroup
多选框群组，用于控制多选框全选或者不全选状态。
该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
无
#### 接口
CheckboxGroup(options?: CheckboxGroupOptions)
创建多选框群组，可以控制群组内的Checkbox全选或者不全选，group值相同的Checkbox和CheckboxGroup为同一群组。
在结合带缓存组件使用时(如List)，未被创建的Checkbox选中状态需要应用手动控制。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| options | [CheckboxGroupOptions](#ZH-CN_TOPIC_0000001972686173__checkboxgroupoptions对象说明) | 否 | 配置多选框群组参数。 |
#### CheckboxGroupOptions对象说明
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| group | string | 否 | 群组名称。**说明：**多个相同群组名称的CheckboxGroup，仅第一个CheckboxGroup生效。 |
#### 属性
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### selectAll
selectAll(value: boolean)
设置是否全选。若同组的[Checkbox](zh-cn_topic_0000001972645917.html)显式设置了select属性，则Checkbox的优先级高。
从API version 10开始，该属性支持[$$](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-two-way-sync-V5)双向绑定变量。
**卡片能力：** 从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](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 被选中或部分选中状态的颜色。默认值：$r('sys.color.ohos_id_color_text_primary_activated')异常值按照默认值处理。 |
#### unselectedColor10+
unselectedColor(value: ResourceColor)
设置非选中状态边框颜色。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 非选中状态边框颜色。默认值：'#33ffffff'。 |
#### mark10+
mark(value: MarkStyle)
设置多选框内部图标样式。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [MarkStyle](#ZH-CN_TOPIC_0000001972686173__markstyle10对象说明) | 是 | 多选框内部图标样式。 |
#### checkboxShape12
checkboxShape(value: CheckBoxShape)
设置CheckboxGroup组件形状， 包括圆形和圆角方形。
**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [CheckBoxShape](zh-cn_topic_0000001972645917.html#ZH-CN_TOPIC_0000001972645917__checkboxshape11枚举类型说明) | 是 | 设置CheckboxGroup组件形状， 包括圆形和圆角方形。默认值:CheckBoxShape.CIRCLE。**说明**：CheckboxGroup组件形状按照设置显示。CheckboxGroup内所有没有单独设置shape类型的Checkbox形状和CheckboxGroup的保持一致。CheckboxGroup内有单独设置shape类型的Checkbox形状则优先于CheckboxGroup，按照设置形状显示。 |
#### 事件
除支持[通用事件](zh-cn_topic_0000001972686089.html)外，还支持以下事件：
#### onChange
onChange(callback: (event: CheckboxGroupResult) => void )
CheckboxGroup的选中状态或群组内的Checkbox的选中状态发生变化时，触发回调。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| event | [CheckboxGroupResult](#ZH-CN_TOPIC_0000001972686173__checkboxgroupresult对象说明) | 是 | 多选框群组的信息。 |
#### CheckboxGroupResult对象说明
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 类型 | 描述 |
| --- | --- | --- |
| name | Array<string> | 群组内所有被选中的多选框名称。 |
| status | [SelectStatus](#ZH-CN_TOPIC_0000001972686173__selectstatus枚举说明) | 选中状态。 |
#### SelectStatus枚举说明
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 描述 |
| --- | --- |
| All | 群组多选择框全部选择。 |
| Part | 群组多选择框部分选择。 |
| None | 群组多选择框全部没有选择。 |
#### MarkStyle10+对象说明
| 名称 | 类型 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- | --- |
| strokeColor | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 否 | Color.White | 内部图标颜色。 |
| size | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length) | 否 | - | 内部图标大小，单位vp。默认大小与多选框群组组件宽度设置值一致。不支持百分比形式设置。当设置为非法值时，按照默认值处理。 |
| strokeWidth | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length) | 否 | 2 | 内部图标粗细，单位vp。不支持百分比形式设置。当设置为非法值时，按照默认值处理。 |
#### 示例
#### 示例1
// xxx.ets
@Entry
@Component
struct CheckboxExample {
build() {
Scroll() {
Column() {
// 全选按钮
Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
CheckboxGroup({ group: 'checkboxGroup' })
.checkboxShape(CheckBoxShape.ROUNDED_SQUARE)
.selectedColor('#007DFF')
.onChange((itemName: CheckboxGroupResult) => {
console.info("checkbox group content" + JSON.stringify(itemName))
})
Text('Select All').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500)
}
// 选项1
Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
Checkbox({ name: 'checkbox1', group: 'checkboxGroup' })
.selectedColor('#007DFF')
.shape(CheckBoxShape.ROUNDED_SQUARE)
.onChange((value: boolean) => {
console.info('Checkbox1 change is' + value)
})
Text('Checkbox1').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500)
}.margin({ left: 36 })
// 选项2
Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
Checkbox({ name: 'checkbox2', group: 'checkboxGroup' })
.selectedColor('#007DFF')
.shape(CheckBoxShape.ROUNDED_SQUARE)
.onChange((value: boolean) => {
console.info('Checkbox2 change is' + value)
})
Text('Checkbox2').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500)
}.margin({ left: 36 })
// 选项3
Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
Checkbox({ name: 'checkbox3', group: 'checkboxGroup' })
.selectedColor('#007DFF')
.shape(CheckBoxShape.ROUNDED_SQUARE)
.onChange((value: boolean) => {
console.info('Checkbox3 change is' + value)
})
Text('Checkbox3').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500)
}.margin({ left: 36 })
}
}
}
}
#### 示例2
// xxx.ets
@Entry
@Component
struct Index {
build() {
Row() {
Column() {
Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
CheckboxGroup({ group: 'checkboxGroup' })
.checkboxShape(CheckBoxShape.ROUNDED_SQUARE)
.selectedColor(Color.Orange)
.onChange((itemName: CheckboxGroupResult) => {
console.info("checkbox group content" + JSON.stringify(itemName))
})
.mark({
strokeColor:Color.Black,
size: 40,
strokeWidth: 5
})
.unselectedColor(Color.Red)
.width(30)
.height(30)
Text('Select All').fontSize(20)
}.margin({right:15})
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)
}
Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
Checkbox({ name: 'checkbox3', group: 'checkboxGroup' })
.selectedColor(0x39a2db)
.shape(CheckBoxShape.ROUNDED_SQUARE)
.onChange((value: boolean) => {
console.info('Checkbox3 change is' + value)
})
.width(30)
.height(30)
Text('Checkbox3').fontSize(20)
}
}
.width('100%')
}
.height('100%')
}
}
# Component3D
3D渲染组件，可以加载3D模型资源并做自定义渲染，通常用于3D动效场景。
该组件从API Version 11开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
无
#### 接口
Component3D((sceneOptions?: SceneOptions))
**参数：**
| 参数名 | 参数类型 | 必填 | 参数描述 |
| --- | --- | --- | --- |
| sceneOptions | [SceneOptions](#ZH-CN_TOPIC_0000001945527072__sceneoptions对象说明) | 否 | 3D场景配置选项。**说明：**3D场景配置选项在控件创建后不支持动态修改。 |
#### SceneOptions对象说明
Component3D组件配置选项。
| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| scene | [Resource](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resource)\\|[Scene](zh-cn_topic_0000001933542162.html#ZH-CN_TOPIC_0000001933542162__scene-1)12+ | 否 | 3D模型资源文件或场景对象，默认值为undefined。**说明：**目前仅支持GLTF格式资源。 |
| modelType | [ModelType](#ZH-CN_TOPIC_0000001945527072__modeltype枚举说明) | 否 | 3D场景显示合成方式。默认值：ModelType.SURFACE**说明：**设置为ModelType.TEXTURE时通过GPU合成显示。设置为ModelType.SURFACE时通过专有硬件合成显示。一般开发者可以使用默认值而无需关心此项设置。 |
#### ModelType枚举说明
| 名称 | 描述 |
| --- | --- |
| TEXTURE | 使用GPU合成显示3D场景。 |
| SURFACE | 使用专有硬件显示3D场景。 |
#### 属性
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### environment
environment(uri: Resource)
设置3D环境资源。目前仅支持GLTF格式资源，模型资源在控件创建后不支持动态修改。
**系统能力：** SystemCapability.ArkUi.Graphics3D
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| uri | [Resource](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resource) | 是 | 3D环境资源。 |
#### customRender
customRender(uri: Resource, selfRenderUpdate: boolean)
设置三维场景渲染的渲染管道。管线配置及自渲染属性在控件创建后不支持动态修改。
**系统能力：** SystemCapability.ArkUi.Graphics3D
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| uri | [Resource](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resource) | 是 | 自定义渲染管线的配置文件。 |
| selfRenderUpdate | boolean | 是 | 当设置为true时外部UI没有更新时也能触发动效渲染。当设置为false时只有外部UI更新才能触发渲染。 |
#### shader
shader(uri: Resource)
设置自定义渲染的shader文件资源。自定义渲染的shader文件资源在控件创建后不支持动态修改。
**系统能力：** SystemCapability.ArkUi.Graphics3D
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| uri | [Resource](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resource) | 是 | 自定义渲染的shader文件资源。 |
#### shaderImageTexture
shaderImageTexture(uri: Resource)
设置自定义渲染用到的纹理资源。若自定义渲染用到多个纹理资源则调用多次，绑定点与调用顺序一致，不支持纹理更换。纹理资源在控件创建后不支持动态修改。
**系统能力：** SystemCapability.ArkUi.Graphics3D
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| uri | [Resource](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resource) | 是 | 自定义渲染用到的纹理资源。 |
#### shaderInputBuffer
shaderInputBuffer(buffer: Array<number>)
设置自定义渲染用到的动效参数。
**系统能力：** SystemCapability.ArkUi.Graphics3D
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| buffer | Array<number> | 是 | 自定义渲染用到的动效参数。 |
#### renderWidth
renderWidth(value: Dimension)
设置3D渲染分辨率的宽度。渲染分辨率的长宽可以不同于控件的长宽，若渲染分辨率与控件分辨率长宽不一致时会上采样或下采样到控件长宽。
不调用此属性时默认渲染分辨率。
渲染分辨率在控件创建后不支持动态修改。
**系统能力：** SystemCapability.ArkUi.Graphics3D
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [Dimension](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__dimension10) | 是 | 3D渲染分辨率的宽度。 |
#### renderHeight
renderHeight(value: Dimension)
设置3D渲染分辨率的长度。渲染分辨率的长宽可以不同于控件的长宽，若渲染分辨率与控件分辨率长宽不一致时会上采样或下采样到控件长宽。
不调用此属性时默认渲染分辨率。
渲染分辨率在控件创建后不支持动态修改。
**系统能力：** SystemCapability.ArkUi.Graphics3D
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [Dimension](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__dimension10) | 是 | 3D渲染分辨率的长度。 |
#### 事件
支持[通用事件](zh-cn_topic_0000001972686089.html)。
#### 示例
示例效果请以真机运行为准，当前IDE预览器不支持。
GLTF模型加载示例。
// xxx.ets
@Entry
@Component
struct Index {
scene: SceneOptions = { scene: $rawfile('gltf/DamageHemlt/glTF/DamagedHelmet.gltf'), modelType: ModelType.SURFACE};
build() {
Row() {
Column() {
Text('GLTF Example')
Component3D( this.scene )
.environment($rawfile('gltf/Environment/glTF/Environment.gltf'))
.renderWidth('90%').renderHeight('90%')
}.width('100%')
}
.height('100%')
}
}
自定义渲染示例。
import { Animator as animator, AnimatorResult } from '@kit.ArkUI';
class EngineTime {
totalTimeUs = 0;
deltaTimeUs = 0;
};
let engineTime = new EngineTime();
let frameCount: number = 0;
function TickFrame() {
if (frameCount == 10) {
engineTime.totalTimeUs += 1.0;
engineTime.deltaTimeUs += 1.0;
frameCount = 0;
} else {
frameCount++;
}
}
@Entry
@Component
struct Index {
scene: SceneOptions = { scene: $rawfile('gltf/DamageHemlt/glTF/DamagedHelmet.gltf'), modelType: ModelType.SURFACE};
backAnimator: AnimatorResult = animator.create({
duration: 2000,
easing: "ease",
delay: 0,
fill: "none",
direction: "normal",
iterations: -1,
begin: 100,
end: 200,
});
@State timeDelta: number[] = [1.0, 2.0];
create() {
this.backAnimator.onfinish = () => {
console.log('backAnimator onfinish');
}
this.backAnimator.onframe = value => {
TickFrame();
this.timeDelta[0] = engineTime.deltaTimeUs;
}
}
build() {
Row() {
Column() {
Text('custom rendering')
Component3D()
.shader($rawfile('assets/app/shaders/shader/London.shader'))
.shaderImageTexture($rawfile('assets/London.jpg'))
.shaderInputBuffer(this.timeDelta)
.customRender($rawfile('assets/app/rendernodegraphs/London.rng'), true)
.renderWidth('90%').renderHeight('90%')
.onAppear(() => {
this.create();
this.backAnimator.play();
}).width('50%').height('50%')
}.width('100%')
}
.height('100%')
}
}
# ContainerSpan
[Text](zh-cn_topic_0000001972645953.html)组件的子组件，用于统一管理多个[Span](zh-cn_topic_0000001945367780.html)、[ImageSpan](zh-cn_topic_0000001945527080.html)的背景色及圆角弧度。
该组件从API Version 11开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
可以包含[Span](zh-cn_topic_0000001945367780.html)、[ImageSpan](zh-cn_topic_0000001945527080.html) 子组件。
#### 接口
ContainerSpan()
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
#### 属性
仅支持以下属性:
#### textBackgroundStyle
textBackgroundStyle(style: TextBackgroundStyle)
设置文本背景样式。子组件在不设置该属性时，将继承此属性值。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| style | [TextBackgroundStyle](#ZH-CN_TOPIC_0000001945367752__textbackgroundstyle对象说明) | 是 | 文本背景样式。默认值：{color: Color.Transparent,radius: 0} |
#### TextBackgroundStyle对象说明
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
| 名称 | 参数类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| color | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 否 | 文本背景色。 |
| radius | [Dimension](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__dimension10) \\| [BorderRadiuses](zh-cn_topic_0000001945367684.html#ZH-CN_TOPIC_0000001945367684__borderradiuses9对象说明) | 否 | 文本背景圆角。 |
#### 事件
不支持[通用事件](zh-cn_topic_0000001972686089.html)。
#### 示例
// xxx.ets
@Component
@Entry
struct Index {
build() {
Column() {
Text() {
ContainerSpan() {
ImageSpan($r('app.media.app_icon'))
.width('40vp')
.height('40vp')
.verticalAlign(ImageSpanAlignment.CENTER)
Span(' Hello World ! ').fontSize('16fp').fontColor(Color.White)
}.textBackgroundStyle({color: "#7F007DFF", radius: "12vp"})
}
}.width('100%').alignItems(HorizontalAlign.Center)
}
}
# DataPanel
数据面板组件，用于将多个数据占比情况使用占比图进行展示。
该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
无
#### 接口
DataPanel(options: DataPanelOptions)
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**参数：**
| 参数名 | 参数类型 | 必填 | 参数描述 |
| --- | --- | --- | --- |
| options | [DataPanelOptions](#ZH-CN_TOPIC_0000001972645921__datapaneloptions对象说明) | 是 | 数据面板组件参数。 |
#### DataPanelOptions对象说明
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 参数名 | 参数类型 | 必填 | 参数描述 |
| --- | --- | --- | --- |
| values | number[] | 是 | 数据值列表，最多包含9个数据，大于9个数据则取前9个数据。若数据值小于0则置为0。 |
| max | number | 否 | - max大于0，表示数据的最大值。- max小于等于0，max等于value数组各项的和，按比例显示。默认值：100 |
| type8+ | [DataPanelType](#ZH-CN_TOPIC_0000001972645921__datapaneltype8枚举说明) | 否 | 数据面板的类型（不支持动态修改）。默认值：DataPanelType.Circle |
#### DataPanelType8+枚举说明
从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 描述 |
| --- | --- |
| Line | 线型数据面板。 |
| Circle | 环形数据面板。 |
#### 属性
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### closeEffect
closeEffect(value: boolean)
设置关闭数据占比图表旋转动效和投影效果。若未设置[trackShadow属性](#ZH-CN_TOPIC_0000001972645921__trackshadow10)，则该属性控制投影效果的开关，开启投影的效果为投影的默认效果。若设置trackShadow属性，则由trackShadow属性值控制投影效果的开关。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 关闭数据占比图表旋转动效和投影效果。默认值：false |
#### valueColors10+
valueColors(value: Array<ResourceColor | LinearGradient>)
设置各数据段颜色。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | Array<[ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) \\| [LinearGradient](#ZH-CN_TOPIC_0000001972645921__lineargradient10对象说明)> | 是 | 各数据段颜色，ResourceColor为纯色，LinearGradient为渐变色。 |
#### trackBackgroundColor10+
trackBackgroundColor(value: ResourceColor)
设置底板颜色。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 底板颜色。默认值：'#08182431'，格式为十六进制ARGB值，前俩位代表透明度。 |
#### strokeWidth10+
strokeWidth(value: Length)
设置圆环粗细。数据面板的类型为DataPanelType.Line时该属性不生效。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length) | 是 | 圆环粗细。默认值：24单位：vp**说明：**设置小于0的值时，按默认值显示。 |
#### trackShadow10+
trackShadow(value: DataPanelShadowOptions)
设置投影样式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [DataPanelShadowOptions](#ZH-CN_TOPIC_0000001972645921__datapanelshadowoptions10对象说明) | 是 | 投影样式。**说明：**设置null为不开启投影。 |
#### contentModifier12+
contentModifier(modifier: ContentModifier<DataPanelConfiguration>)
定制DataPanel内容区的方法。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| modifier | [ContentModifier](#ZH-CN_TOPIC_0000001972645921__datapanelconfiguration12对象说明) | 是 | 在DataPanel组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。 |
#### DataPanelShadowOptions10+对象说明
DataPanelShadowOptions继承自[MultiShadowOptions](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__multishadowoptions10)，具有MultiShadowOptions的全部属性。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 参数类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| colors | Array<[ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) \\| [LinearGradient](#ZH-CN_TOPIC_0000001972645921__lineargradient10对象说明)> | 否 | 各数据段投影的颜色。默认值：与valueColors值相同**说明：**若设置的投影颜色的个数少于数据段个数时，则显示的投影颜色的个数和设置的投影颜色个数一致。若设置的投影颜色的个数多于数据段个数时，则显示的投影颜色的个数和数据段个数一致。 |
#### LinearGradient10+对象说明
线性渐变颜色描述。
LinearGradient(colorStops: ColorStop[])
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 参数类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| colorStops | [ColorStop](#ZH-CN_TOPIC_0000001972645921__colorstop10对象说明)[] | 是 | 存储渐变颜色和渐变点。 |
#### ColorStop10+对象说明
颜色断点类型，用于描述渐进色颜色断点。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 参数类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| color | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 颜色值。 |
| offset | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length) | 是 | 渐变色断点（0~1之间的比例值，若数据值小于0则置为0，若数据值大于1则置为1）。**说明：**若传入字符串类型且内容为数字，则转换为对应的数值。例如'10vp'转换为10，'10%'转换为0.1。 |
#### DataPanelConfiguration12+对象说明
开发者需要自定义class实现ContentModifier接口。
| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| values | number[] | - | 当前DataPanel的数据值，最大长度为9。 |
| maxValue | number | 100 | DataPanel显示的最大值。 |
#### 示例
#### 示例1
// xxx.ets
@Entry
@Component
struct DataPanelExample {
public valueArr: number[] = [10, 10, 10, 10, 10, 10, 10, 10, 10]
build() {
Column({ space: 5 }) {
Row() {
Stack() {
DataPanel({ values: [30], max: 100, type: DataPanelType.Circle }).width(168).height(168)
Column() {
Text('30').fontSize(35).fontColor('#182431')
Text('1.0.0').fontSize(9.33).lineHeight(12.83).fontWeight(500).opacity(0.6)
}
Text('%')
.fontSize(9.33)
.lineHeight(12.83)
.fontWeight(500)
.opacity(0.6)
.position({ x: 104.42, y: 78.17 })
}.margin({ right: 44 })
Stack() {
DataPanel({ values: [50, 12, 8, 5], max: 100, type: DataPanelType.Circle }).width(168).height(168)
Column() {
Text('75').fontSize(35).fontColor('#182431')
Text('已使用98GB/128GB').fontSize(8.17).lineHeight(11.08).fontWeight(500).opacity(0.6)
}
Text('%')
.fontSize(9.33)
.lineHeight(12.83)
.fontWeight(500)
.opacity(0.6)
.position({ x: 104.42, y: 78.17 })
}
}.margin({ bottom: 59 })
DataPanel({ values: this.valueArr, max: 100, type: DataPanelType.Line }).width(300).height(20)
}.width('100%').margin({ top: 5 })
}
}
#### 示例2
// xxx.ets
@Entry
@Component
struct LinearGradientDataPanelExample {
public values1: number[] = [20, 20, 20, 20]
public color1: LinearGradient = new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#FFEF629F", offset: 1 }])
public color2: LinearGradient = new LinearGradient([{ color: "#FF67F9D4", offset: 0 }, { color: "#FFFF9554", offset: 1 }])
public colorShadow1: LinearGradient = new LinearGradient([{ color: "#65EEC9A3", offset: 0 }, { color: "#65EF629F", offset: 1 }])
public colorShadow2: LinearGradient = new LinearGradient([{ color: "#65e26709", offset: 0 }, { color: "#65efbd08", offset: 1 }])
public colorShadow3: LinearGradient = new LinearGradient([{ color: "#6572B513", offset: 0 }, { color: "#6508efa6", offset: 1 }])
public colorShadow4: LinearGradient = new LinearGradient([{ color: "#65ed08f5", offset: 0 }, { color: "#65ef0849", offset: 1 }])
@State color3: string = '#00FF00'
@State color4: string = '#20FF0000'
@State bgColor: string = '#08182431'
@State offsetX: number = 15
@State offsetY: number = 15
@State radius: number = 5
@State colorArray: Array<LinearGradient | ResourceColor> = [this.color1, this.color2, this.color3, this.color4]
@State shadowColorArray: Array<LinearGradient | ResourceColor> = [this.colorShadow1, this.colorShadow2, this.colorShadow3, this.colorShadow4]
build() {
Column({ space: 5 }) {
Text('LinearGradient').fontSize(9).fontColor(0xCCCCCC).textAlign(TextAlign.Start).width('100%').margin({ top: 20, left: 20})
DataPanel({ values: this.values1, max: 100, type: DataPanelType.Circle })
.width(300)
.height(300)
.valueColors(this.colorArray)
.trackShadow({
radius: this.radius,
colors: this.shadowColorArray,
offsetX: this.offsetX,
offsetY: this.offsetY
})
.strokeWidth(30)
.trackBackgroundColor(this.bgColor)
}.width('100%').margin({ top: 5 })
}
}
#### 示例3
// xxx.ets
@Builder
function buildDataPanel(config: DataPanelConfiguration) {
Column() {
Column() {
ForEach(config.values, (item: number, index: number) => {
ChildItem({ item: item, index: index, max:config.maxValue})
}, (item: string) => item)
}.padding(10)
Line().width(360).backgroundColor("#ff373737").margin({bottom:5})
Row() {
Text('Length=' + config.values.length + ' ').margin({ left: 10 }).align(Alignment.Start)
Text('Max=' + config.maxValue).margin({ left: 10 }).align(Alignment.Start)
}
}
}
class DataPanelBuilder implements ContentModifier<DataPanelConfiguration> {
constructor() {
}
applyContent () : WrappedBuilder<[DataPanelConfiguration]> {
return wrapBuilder(buildDataPanel)
}
}
@Entry
@Component
struct Index {
build() {
Column() {
Text("Data panel").margin({ top: 12 });
Row() {
DataPanel({ values: [12.3, 21.1, 13.4, 35.2, 26.0, 32.0], max: 140, type: DataPanelType.Circle })
.width(400).height(260)
.padding({ top: 10 })
.contentModifier(new DataPanelBuilder())
}.margin(15).backgroundColor("#fff5f5f5")
}
}
}
@Component
struct ChildItem {
@Prop item: number;
@Prop index: number;
@Prop max: number;
public color1: string = "#65ff00dd"
public color2: string = "#6500ff99"
public color3: string = "#65ffe600"
public color4: string = "#6595ff00"
public color5: string = "#65000dff"
public color6: string = "#650099ff"
public colorArray: Array<string> = [this.color1, this.color2, this.color3, this.color4, this.color5, this.color6]
build() {
RelativeContainer() {
Row() {
Rect().height(25).width(this.item * 600 / this.max).foregroundColor(this.colorArray[this.index]).radius(5)
.align(Alignment.Start)
Text(" "+this.item)
.fontSize(17)
}
}.height(28)
}
}
# DatePicker
日期选择器组件，用于根据指定日期范围创建日期滑动选择器。
该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
无
#### 接口
DatePicker(options?: DatePickerOptions)
根据指定范围的Date创建可以选择日期的滑动选择器。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| options | [DatePickerOptions](#ZH-CN_TOPIC_0000001972686177__datepickeroptions对象说明) | 否 | 配置日期选择器组件的参数。 |
#### DatePickerOptions对象说明
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| start | Date | 否 | 指定选择器的起始日期。默认值：Date('1970-1-1') |
| end | Date | 否 | 指定选择器的结束日期。默认值：Date('2100-12-31') |
| selected | Date | 否 | 设置选中项的日期。默认值：当前系统日期从API version 10开始，该参数支持[$$](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-two-way-sync-V5)双向绑定变量。 |
**异常情形说明:**
| 异常情形 | 对应结果 |
| --- | --- |
| 起始日期晚于结束日期，选中日期未设置 | 起始日期、结束日期和选中日期都为默认值 |
| 起始日期晚于结束日期，选中日期早于起始日期默认值 | 起始日期、结束日期都为默认值，选中日期为起始日期默认值 |
| 起始日期晚于结束日期，选中日期晚于结束日期默认值 | 起始日期、结束日期都为默认值，选中日期为结束日期默认值 |
| 起始日期晚于结束日期，选中日期在起始日期与结束日期默认值范围内 | 起始日期、结束日期都为默认值，选中日期为设置的值 |
| 选中日期早于起始日期 | 选中日期为起始日期 |
| 选中日期晚于结束日期 | 选中日期为结束日期 |
| 起始日期晚于当前系统日期，选中日期未设置 | 选中日期为起始日期 |
| 结束日期早于当前系统日期，选中日期未设置 | 选中日期为结束日期 |
| 日期格式不符合规范，如‘1999-13-32’ | 取默认值 |
| 起始日期或结束日期早于系统有效范围 | 起始日期或结束日期取起始日期默认值 |
| 起始日期或结束日期晚于系统有效范围 | 起始日期或结束日期取结束日期默认值 |
| 起始日期与结束日期同时早于系统有效范围 | 起始日期与结束日期取系统有效范围最早日期 |
| 起始日期与结束日期同时晚于系统有效范围 | 起始日期与结束日期取系统有效范围最晚日期 |
系统日期范围：1900-1-31 ~ 2100-12-31
选中日期会在起始日期与结束日期异常处理完成后再进行异常情形判断处理
#### 属性
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### lunar
lunar(value: boolean)
设置弹窗的日期是否显示农历。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 日期是否显示农历。- true：展示农历。- false：不展示农历。默认值：false |
#### disappearTextStyle10+
disappearTextStyle(value: PickerTextStyle)
设置所有选项中最上和最下两个选项的文本样式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [PickerTextStyle](#ZH-CN_TOPIC_0000001972686177__pickertextstyle10类型说明) | 是 | 所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。默认值：{color: '#ff182431',font: {size: '14fp',weight: FontWeight.Regular}} |
#### textStyle10+
textStyle(value: PickerTextStyle)
设置所有选项中除了最上、最下及选中项以外的文本样式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [PickerTextStyle](#ZH-CN_TOPIC_0000001972686177__pickertextstyle10类型说明) | 是 | 所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。默认值：{color: '#ff182431',font: {size: '16fp',weight: FontWeight.Regular}} |
#### selectedTextStyle10+
selectedTextStyle(value: PickerTextStyle)
设置选中项的文本样式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [PickerTextStyle](#ZH-CN_TOPIC_0000001972686177__pickertextstyle10类型说明) | 是 | 选中项的文本颜色、字号、字体粗细。默认值：{color: '#ff007dff',font: {size: '20vp',weight: FontWeight.Medium}} |
#### PickerTextStyle10+类型说明
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 参数名 | 参数类型 | 必填 | 参数描述 |
| --- | --- | --- | --- |
| color | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 否 | 文本颜色。 |
| font | [Font](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__font) | 否 | 文本样式，picker只支持字号、字体粗细的设置。 |
#### 事件
除支持[通用事件](zh-cn_topic_0000001972686089.html)外，还支持以下事件：
#### onChange(deprecated)
onChange(callback: (value: DatePickerResult) => void)
选择日期时触发该事件。
从API version 8 开始支持，从 API version 10 开始废弃，建议使用[onDateChange](#ZH-CN_TOPIC_0000001972686177__ondatechange10)。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [DatePickerResult](#ZH-CN_TOPIC_0000001972686177__datepickerresult对象说明) | 是 | 返回选中的时间。 |
#### onDateChange10+
onDateChange(callback: (value: Date) => void)
选择日期时触发该事件。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | Date | 是 | 返回选中的时间，年月日为选中的日期，时分取决于当前系统时间的时分，秒恒为00。 |
#### DatePickerResult对象说明
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 参数类型 | 描述 |
| --- | --- | --- |
| year | number | 选中日期的年。 |
| month | number | 选中日期的月(0~11)，0表示1月，11表示12月。 |
| day | number | 选中日期的日。 |
#### 示例
// xxx.ets
@Entry
@Component
struct DatePickerExample {
@State isLunar: boolean = false
private selectedDate: Date = new Date('2021-08-08')
build() {
Column() {
Button('切换公历农历')
.margin({ top: 30, bottom: 30 })
.onClick(() => {
this.isLunar = !this.isLunar
})
DatePicker({
start: new Date('1970-1-1'),
end: new Date('2100-1-1'),
selected: this.selectedDate
})
.disappearTextStyle({color: Color.Gray, font: {size: '16fp', weight: FontWeight.Bold}})
.textStyle({color: '#ff182431', font: {size: '18fp', weight: FontWeight.Normal}})
.selectedTextStyle({color: '#ff0000FF', font: {size: '26fp', weight: FontWeight.Regular}})
.lunar(this.isLunar)
.onDateChange((value: Date) => {
this.selectedDate = value
console.info('select current date is: ' + value.toString())
})
}.width('100%')
}
}
# Divider
提供分隔器组件，分隔不同内容块/内容元素。
该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
无
#### 接口
Divider()
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
#### 属性
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### vertical
vertical(value: boolean)
设置分割线的方向。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 使用水平分割线还是垂直分割线。false：水平分割线；true：垂直分割线。默认值：false |
#### color
color(value: ResourceColor)
设置分割线的颜色。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 分割线颜色。默认值：'#33182431' |
#### strokeWidth
strokeWidth(value: number | string)
设置分割线的宽度。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | number \\| string | 是 | 分割线宽度。默认值：1px单位：vp**说明：**分割线的宽度不支持百分比设置。优先级低于[通用属性height](zh-cn_topic_0000001945367680.html#ZH-CN_TOPIC_0000001945367680__height)，超过通用属性设置大小时，按照通用属性进行裁切。 |
#### lineCap
lineCap(value: LineCapStyle)
设置分割线的端点样式。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [LineCapStyle](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__linecapstyle) | 是 | 分割线的端点样式。默认值：LineCapStyle.Butt |
#### 示例
// xxx.ets
@Entry
@Component
struct DividerExample {
build() {
Column() {
// 使用横向分割线场景
Text('Horizontal divider').fontSize(9).fontColor(0xCCCCCC)
List() {
ForEach([1, 2, 3], (item: number) => {
ListItem() {
Text('list' + item).width('100%').fontSize(14).fontColor('#182431').textAlign(TextAlign.Start)
}.width(244).height(48)
}, (item: number) => item.toString())
}.padding({ left: 24, bottom: 8 })
Divider().strokeWidth(8).color('#F1F3F5')
List() {
ForEach([4, 5], (item: number) => {
ListItem() {
Text('list' + item).width('100%').fontSize(14).fontColor('#182431').textAlign(TextAlign.Start)
}.width(244).height(48)
}, (item: number) => item.toString())
}.padding({ left: 24, top: 8 })
// 使用纵向分割线场景
Text('Vertical divider').fontSize(9).fontColor(0xCCCCCC)
Column() {
Column() {
Row().width(288).height(64).backgroundColor('#30C9F0').opacity(0.3)
Row() {
Button('Button')
.width(136)
.height(22)
.fontSize(16)
.fontColor('#007DFF')
.fontWeight(500)
.backgroundColor(Color.Transparent)
Divider().vertical(true).height(22).color('#182431').opacity(0.6).margin({ left: 8, right: 8 })
Button('Button')
.width(136)
.height(22)
.fontSize(16)
.fontColor('#007DFF')
.fontWeight(500)
.backgroundColor(Color.Transparent)
}.margin({ top: 17 })
}
.width(336)
.height(152)
.backgroundColor('#FFFFFF')
.borderRadius(24)
.padding(24)
}
.width('100%')
.height(168)
.backgroundColor('#F1F3F5')
.justifyContent(FlexAlign.Center)
.margin({ top: 8 })
}.width('100%').padding({ top: 24 })
}
}
# Gauge
数据量规图表组件，用于将数据展示为环形图表。
该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
可以包含单个子组件。
建议使用文本组件构建当前数值文本和辅助文本。
若子组件宽高为百分比形式，则基准范围为以外圆环做为内切圆的矩形。
#### 接口
Gauge(options:{value: number, min?: number, max?: number})
创建数据量规图表组件。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | number | 是 | 量规图的当前数据值，即图中指针指向位置。用于组件创建时量规图初始值的预置。**说明：**value不在min和max范围内时使用min作为默认值。 |
| min | number | 否 | 当前数据段最小值。默认值：0 |
| max | number | 否 | 当前数据段最大值。默认值：100**说明：**max小于min时使用默认值0和100。max和min支持负数。 |
#### 属性
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### value
value(value: number)
设置量规图的数据值。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | number | 是 | 量规图的数据值，可用于动态修改量规图的数据值。默认值：0 |
#### startAngle
startAngle(angle: number)
设置起始角度位置。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| angle | number | 是 | 起始角度位置，时钟0点为0度，顺时针方向为正角度。默认值：0 |
#### endAngle
endAngle(angle: number)
设置终止角度位置。起始角度位置和终止角度位置差过小时，会绘制出异常图像，请取合理的起始角度位置和终止角度位置。建议使用单色环改变Gauge的value参数实现数据值的调节，可通过定时器setTimeout进行数值的延迟加载。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| angle | number | 是 | 终止角度位置，时钟0点为0度，顺时针方向为正角度。默认值：360 |
#### colors
colors(colors: ResourceColor | LinearGradient | Array<[ResourceColor | LinearGradient | number]>)
设置量规图的颜色。
从API version 11开始，该接口使用以下规则：
参数类型为ResourceColor，则圆环类型为单色环。
参数类型为LinearGradient，则圆环类型为渐变环。
参数类型为数组，则圆环类型为分段渐变环，第一个参数为颜色值，若设置为非颜色类型，则置为"0xFFE84026"。第二个参数为颜色所占比重，若设置为负数或是非数值类型，则将比重置为0。
分段渐变环最大显示段数为9段，若多于9段，则多于部分不显示。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| colors | [ResourceColor11+](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) \\| [LinearGradient11+](zh-cn_topic_0000001972645921.html#ZH-CN_TOPIC_0000001972645921__lineargradient10对象说明) \\| Array<[[ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) \\| [LinearGradient11+](zh-cn_topic_0000001972645921.html#ZH-CN_TOPIC_0000001972645921__lineargradient10对象说明) \\| number]> | 是 | 量规图的颜色，支持分段颜色设置。API version 9 默认值：Color.BlackAPI version 11默认值：若不传颜色，或者数组为空，无法确定圆环类型及颜色，则圆环颜色为"0xFF64BB5C"、"0xFFF7CE00"、"0xFFE84026"的渐变环。若传入颜色，但颜色值有误，则该颜色为"0xFFE84026"。 |
#### strokeWidth
strokeWidth(length: Length)
设置环形量规图的环形厚度。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| length | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length) | 是 | 环形量规图的环形厚度。默认值：4单位：vp**说明：**设置小于0的值时，按默认值显示。不支持百分比。 |
#### description11+
description(value: CustomBuilder)
设置说明内容。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [CustomBuilder](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__custombuilder8) | 是 | 说明内容。**说明：**@Builder中的内容由开发者自定义，建议使用文本或者图片。若自定义部分的宽高为百分比形式，则基准范围为圆环直径的44.4%*25.4%的矩形（图片为28.6%*28.6%），距离圆环底部0vp，左右居中。设置null则不显示内容。不设置则依赖是否设置数据最大最小值。若设置最大最小值或者只设置其中一个，则显示最大最小值。若未设置最大最小值，则不显示内容。最大最小值显示在圆环底部，位置不可移动，若圆环开口角度设置不恰当，存在圆环遮挡文字的情况。 |
#### trackShadow11+
trackShadow(value: GaugeShadowOptions)
设置阴影样式。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [GaugeShadowOptions](#ZH-CN_TOPIC_0000001945367756__gaugeshadowoptions11对象说明) | 是 | 阴影样式。**说明：**阴影颜色与圆环颜色一致。设置null为不开启投影。 |
#### indicator11+
indicator(value: GaugeIndicatorOptions)
设置指针样式。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [GaugeIndicatorOptions](#ZH-CN_TOPIC_0000001945367756__gaugeindicatoroptions11对象说明) | 是 | 指针样式。**说明：**设置null则不显示指针。 |
#### privacySensitive12+
privacySensitive(isPrivacySensitiveMode: Optional<boolean>)
设置隐私敏感。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| isPrivacySensitiveMode | [Optional<boolean>] | 是 | 设置隐私敏感，隐私模式下Gauge指针指向0位置，最大值最小值文本将被遮罩，量程显示灰色或者底色。**说明：**设置null则不敏感。[需要卡片框架支持。](zh-cn_topic_0000001945367724.html) |
#### contentModifier12+
contentModifier(modifier: ContentModifier<GaugeConfiguration>)
定制Slider内容区的方法。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| modifier | [ContentModifier](#ZH-CN_TOPIC_0000001945367756__gaugeconfiguration12对象说明) | 是 | 在Gauge组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。 |
#### GaugeShadowOptions11+对象说明
GaugeShadowOptions继承自[MultiShadowOptions](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__multishadowoptions10)，具有MultiShadowOptions的全部属性。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
#### GaugeIndicatorOptions11+对象说明
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
| 名称 | 参数类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| icon | [Resource](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resource) | 否 | 图标资源路径。**说明：**不配置则使用默认的三角形样式指针。支持使用svg格式的图标，若使用其他格式，则使用默认的三角形样式指针。 |
| space | [Dimension](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__dimension10) | 否 | 指针距离圆环外边的间距。(不支持百分比)默认值：8单位：vp**说明：**对于默认的三角形样式指针，间距为黑色三角形到圆环外边的间距。若设置值小于0，则使用默认值。若设置值大于圆环半径，则使用默认值。 |
#### GaugeConfiguration12+对象说明
开发者需要自定义class实现ContentModifier接口。
| 参数名 | 类型 | 说明 |
| --- | --- | --- |
| value | number | 当前数据值。 |
| min | number | 当前数据段最小值。 |
| max | number | 当前数据段最大值。 |
#### 示例
#### 示例1
示例使用当前数值、说明文本、辅助文本。
@Entry
@Component
struct Gauge1 {
@Builder descriptionBuilder() {
Text('说明文本')
.maxFontSize('30sp')
.minFontSize("10.0vp")
.fontColor("#fffa2a2d")
.fontWeight(FontWeight.Medium)
.width('100%')
.height("100%")
.textAlign(TextAlign.Center)
}
build() {
Column() {
Gauge({ value: 50, min: 1, max: 100 }) {
Column() {
Text('50')
.fontWeight(FontWeight.Medium)
.width('62%')
.fontColor("#ff182431")
.maxFontSize("60.0vp")
.minFontSize("30.0vp")
.textAlign(TextAlign.Center)
.margin({ top: '35%' })
.textOverflow({ overflow: TextOverflow.Ellipsis })
.maxLines(1)
Text('辅助文本')
.maxFontSize("16.0fp")
.minFontSize("10.0vp")
.fontColor($r('sys.color.ohos_id_color_text_secondary'))
.fontColor($r('sys.color.ohos_id_color_text_secondary'))
.fontWeight(FontWeight.Regular)
.width('67.4%')
.height('9.5%')
.textAlign(TextAlign.Center)
}.width('100%').height('100%')
}
.value(50)
.startAngle(210)
.endAngle(150)
.colors([[new LinearGradient([{ color: "#deb6fb", offset: 0 }, { color: "#ac49f5", offset: 1 }]), 9],
[new LinearGradient([{ color: "#bbb7fc", offset: 0 }, { color: "#564af7", offset: 1 }]), 8],
[new LinearGradient([{ color: "#f5b5c2", offset: 0 }, { color: "#e64566", offset: 1 }]), 7],
[new LinearGradient([{ color: "#f8c5a6", offset: 0 }, { color: "#ed6f21", offset: 1 }]), 6],
[new LinearGradient([{ color: "#fceb99", offset: 0 }, { color: "#f7ce00", offset: 1 }]), 5],
[new LinearGradient([{ color: "#dbefa5", offset: 0 }, { color: "#a5d61d", offset: 1 }]), 4],
[new LinearGradient([{ color: "#c1e4be", offset: 0 }, { color: "#64bb5c", offset: 1 }]), 3],
[new LinearGradient([{ color: "#c0ece5", offset: 0 }, { color: "#61cfbe", offset: 1 }]), 2],
[new LinearGradient([{ color: "#b5e0f4", offset: 0 }, { color: "#46b1e3", offset: 1 }]), 1]])
.width('80%')
.height('80%')
.strokeWidth(18)
.trackShadow({ radius: 7, offsetX: 7, offsetY: 7 })
.description(this.descriptionBuilder)
.padding(18)
}.margin({ top: 40 }).width('100%').height('100%')
}
}
#### 示例2
示例使用当前数值、图标。
@Entry
@Component
struct Gauge2 {
@Builder descriptionBuilderImage() {
Image($r('sys.media.ohos_ic_public_clock')).width(72).height(72)
}
build() {
Column() {
Gauge({ value: 50, min: 1, max: 100 }) {
Column() {
Text('50')
.fontWeight(FontWeight.Medium)
.width('62%')
.fontColor("#ff182431")
.maxFontSize("60.0vp")
.minFontSize("30.0vp")
.textAlign(TextAlign.Center)
.margin({ top: '35%' })
.textOverflow({ overflow: TextOverflow.Ellipsis })
.maxLines(1)
}.width('100%').height('100%')
}
.startAngle(210)
.endAngle(150)
.colors('#cca5d61d')
.width('80%')
.height('80%')
.strokeWidth(18)
.description(this.descriptionBuilderImage)
.padding(18)
}.margin({ top: 40 }).width('100%').height('100%')
}
}
#### 示例3
示例使用当前数值、说明文本。
@Entry
@Component
struct Gauge3 {
@Builder descriptionBuilder() {
Text('说明文本')
.maxFontSize('30sp')
.minFontSize("10.0vp")
.fontColor("#fffa2a2d")
.fontWeight(FontWeight.Medium)
.width('100%')
.height("100%")
.textAlign(TextAlign.Center)
}
build() {
Column() {
Column() {
Gauge({ value: 50, min: 1, max: 100 }) {
Column() {
Text('50')
.fontWeight(FontWeight.Medium)
.width('62%')
.fontColor("#ff182431")
.maxFontSize("60.0vp")
.minFontSize("30.0vp")
.textAlign(TextAlign.Center)
.margin({ top: '35%' })
.textOverflow({ overflow: TextOverflow.Ellipsis })
.maxLines(1)
}.width('100%').height('100%')
}
.startAngle(210)
.endAngle(150)
.colors([[new LinearGradient([{ color: "#deb6fb", offset: 0 }, { color: "#ac49f5", offset: 1 }]), 9],
[new LinearGradient([{ color: "#bbb7fc", offset: 0 }, { color: "#564af7", offset: 1 }]), 8],
[new LinearGradient([{ color: "#f5b5c2", offset: 0 }, { color: "#e64566", offset: 1 }]), 7],
[new LinearGradient([{ color: "#f8c5a6", offset: 0 }, { color: "#ed6f21", offset: 1 }]), 6],
[new LinearGradient([{ color: "#fceb99", offset: 0 }, { color: "#f7ce00", offset: 1 }]), 5],
[new LinearGradient([{ color: "#dbefa5", offset: 0 }, { color: "#a5d61d", offset: 1 }]), 4],
[new LinearGradient([{ color: "#c1e4be", offset: 0 }, { color: "#64bb5c", offset: 1 }]), 3],
[new LinearGradient([{ color: "#c0ece5", offset: 0 }, { color: "#61cfbe", offset: 1 }]), 2],
[new LinearGradient([{ color: "#b5e0f4", offset: 0 }, { color: "#46b1e3", offset: 1 }]), 1]])
.width('80%')
.height('80%')
.strokeWidth(18)
.description(this.descriptionBuilder)
.trackShadow({ radius: 7, offsetX: 7, offsetY: 7 })
.padding(18)
}.margin({ top: 40 }).width('100%').height('100%')
}
}
}
#### 示例4
示例使用当前数值、辅助文本。
@Entry
@Component
struct Gauge4 {
build() {
Column() {
Gauge({ value: 50, min: 1, max: 100 }) {
Column() {
Text('50')
.maxFontSize("72.0vp")
.minFontSize("10.0vp")
.fontColor("#ff182431")
.width('40%')
.textAlign(TextAlign.Center)
.margin({ top: '35%' })
.textOverflow({ overflow: TextOverflow.Ellipsis })
.maxLines(1)
Text('辅助文本')
.maxFontSize("30.0vp")
.minFontSize("18.0vp")
.fontWeight(FontWeight.Medium)
.fontColor($r('sys.color.ohos_id_color_text_secondary'))
.width('62%')
.height('15.9%')
.textAlign(TextAlign.Center)
}.width('100%').height('100%')
}
.startAngle(210)
.endAngle(150)
.colors([[new LinearGradient([{ color: "#deb6fb", offset: 0 }, { color: "#ac49f5", offset: 1 }]), 9],
[new LinearGradient([{ color: "#bbb7fc", offset: 0 }, { color: "#564af7", offset: 1 }]), 8],
[new LinearGradient([{ color: "#f5b5c2", offset: 0 }, { color: "#e64566", offset: 1 }]), 7],
[new LinearGradient([{ color: "#f8c5a6", offset: 0 }, { color: "#ed6f21", offset: 1 }]), 6],
[new LinearGradient([{ color: "#fceb99", offset: 0 }, { color: "#f7ce00", offset: 1 }]), 5],
[new LinearGradient([{ color: "#dbefa5", offset: 0 }, { color: "#a5d61d", offset: 1 }]), 4],
[new LinearGradient([{ color: "#c1e4be", offset: 0 }, { color: "#64bb5c", offset: 1 }]), 3],
[new LinearGradient([{ color: "#c0ece5", offset: 0 }, { color: "#61cfbe", offset: 1 }]), 2],
[new LinearGradient([{ color: "#b5e0f4", offset: 0 }, { color: "#46b1e3", offset: 1 }]), 1]])
.width('80%')
.height('80%')
.strokeWidth(18)
.description(null)
.trackShadow({ radius: 7, offsetX: 7, offsetY: 7 })
.padding(18)
}.margin({ top: 40 }).width('100%').height('100%')
}
}
#### 示例5
示例使用当前数值、最大最小数值。
@Entry
@Component
struct Gauge5 {
build() {
Column() {
Gauge({ value: 50, min: 1, max: 100 }) {
Column() {
Text('50')
.maxFontSize("80sp")
.minFontSize("60.0vp")
.fontWeight(FontWeight.Medium)
.fontColor("#ff182431")
.width('40%')
.height('30%')
.textAlign(TextAlign.Center)
.margin({ top: '22.2%' })
.textOverflow({ overflow: TextOverflow.Ellipsis })
.maxLines(1)
}.width('100%').height('100%')
}
.startAngle(225)
.endAngle(135)
.colors(new LinearGradient([{ color: "#e84026", offset: 0 },
{ color: "#f7ce00", offset: 0.6 },
{ color: "#64bb5c", offset: 1 }]))
.width('80%')
.height('80%')
.strokeWidth(18)
.trackShadow({ radius: 7, offsetX: 7, offsetY: 7 })
.padding(18)
}.margin({ top: 40 }).width('100%').height('100%')
}
}
#### 示例6
示例使用当前数值、最大最小数值、辅助文本。
@Entry
@Component
struct Gauge6 {
build() {
Column() {
Gauge({ value: 50, min: 1, max: 100 }) {
Column() {
Text('50')
.maxFontSize('60sp')
.minFontSize('30.0vp')
.fontWeight(FontWeight.Medium)
.fontColor("#ff182431")
.width('62%')
.textAlign(TextAlign.Center)
.margin({ top: '35%' })
.textOverflow({ overflow: TextOverflow.Ellipsis })
.maxLines(1)
Text('辅助文本')
.maxFontSize('16sp')
.minFontSize("10.0vp")
.fontColor($r('sys.color.ohos_id_color_text_secondary'))
.fontWeight(FontWeight.Regular)
.width('67.4%')
.height('9.5%')
.textAlign(TextAlign.Center)
}.width('100%').height('100%')
}
.startAngle(225)
.endAngle(135)
.colors(Color.Red)
.width('80%')
.height('80%')
.indicator(null)
.strokeWidth(18)
.trackShadow({ radius: 7, offsetX: 7, offsetY: 7 })
.padding(18)
}.margin({ top: 40 }).width('100%').height('100%')
}
}
#### 示例7
示例使用当前数值、最大最小数值。
@Entry
@Component
struct Gauge7 {
build() {
Column() {
Gauge({ value: 50, min: 1, max: 100 }) {
Column() {
Text('50')
.maxFontSize('60sp')
.minFontSize('30.0vp')
.fontWeight(FontWeight.Medium)
.fontColor("#ff182431")
.width('62%')
.textAlign(TextAlign.Center)
.margin({ top: '35%' })
.textOverflow({ overflow: TextOverflow.Ellipsis })
.maxLines(1)
}.width('100%').height('100%')
}
.startAngle(225)
.endAngle(135)
.colors(Color.Red)
.width('80%')
.height('80%')
.indicator(null)
.strokeWidth(18)
.trackShadow({ radius: 7, offsetX: 7, offsetY: 7 })
.padding(18)
}.margin({ top: 40 }).width('100%').height('100%')
}
}
#### 示例8
// xxx.ets
//该示例实现了Gauge组件使用Builder定制内容区，使用了环形图表组件，按钮和文本框。点击增加按钮，环形图表指针位置会向右偏移，反之点减少按钮环形图表指针位置会向左偏移。
@Builder
function buildGauge(config: GaugeConfiguration) {
Column({ space: 30 }) {
Row() {
Text('【ContentModifier】 value：' + JSON.stringify((config.contentModifier as MyGaugeStyle).value) +
' min：' + JSON.stringify((config.contentModifier as MyGaugeStyle).min) +
' max：' + JSON.stringify((config.contentModifier as MyGaugeStyle).max))
.fontSize(12)
}
Text('【Config】value：' + config.value + ' min：' + config.min + ' max：' + config.max).fontSize(12)
Gauge({
value: config.value,
min: config.min,
max: config.max
}).width("50%")
}
.width("100%")
.padding(20)
.margin({ top: 5 })
.alignItems(HorizontalAlign.Center)
}
class MyGaugeStyle implements ContentModifier<GaugeConfiguration> {
value: number = 0
min: number = 0
max: number = 0
constructor(value: number, min: number, max: number) {
this.value = value
this.min = min
this.max = max
}
applyContent(): WrappedBuilder<[GaugeConfiguration]> {
return wrapBuilder(buildGauge)
}
}
@Entry
@Component
struct refreshExample {
@State gaugeValue: number = 20
@State gaugeMin: number = 0
@State gaugeMax: number = 100
build() {
Column({ space: 20 }) {
Gauge({
value: this.gaugeValue,
min: this.gaugeMin,
max: this.gaugeMax
})
.contentModifier(new MyGaugeStyle(30, 10, 100))
Column({ space: 20 }) {
Row({ space: 20 }) {
Button('增加').onClick(() => {
if (this.gaugeValue < this.gaugeMax) {
this.gaugeValue += 1
}
})
Button('减少').onClick(() => {
if (this.gaugeValue > this.gaugeMin) {
this.gaugeValue -= 1
}
})
}
}.width('100%')
}.width('100%').margin({ top: 5 })
}
}
#### 示例9
该示例展示了如何配置隐私隐藏，效果展示需要卡片框架支持
@Entry
@Component
struct GaugeExample {
build() {
Scroll() {
Column({ space: 15 }) {
Row() {
Gauge({ value: 50, min: 1, max: 100 }) {
Column() {
Text('60')
.maxFontSize("180sp")
.minFontSize("160.0vp")
.fontWeight(FontWeight.Medium)
.fontColor("#ff182431")
.width('40%')
.height('30%')
.textAlign(TextAlign.Center)
.margin({ top: '22.2%' })
.textOverflow({ overflow: TextOverflow.Ellipsis })
.maxLines(1)
}.width('100%').height('100%')
}
.startAngle(225)
.endAngle(135)
.colors(Color.Red)
.width('80%')
.height('80%')
.strokeWidth(18)
.trackShadow({ radius: 7, offsetX: 7, offsetY: 7 })
.padding(18)
.privacySensitive(true)
}
}
}
}
}
# Image
Image为图片组件，常用于在应用中显示图片。Image支持加载[PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7)、[ResourceStr](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcestr)和[DrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__drawabledescriptor)类型的数据源，支持png、jpg、jpeg、bmp、svg、webp、gif和heif类型的图片格式。
该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
使用快捷组合键对Image组件复制时，Image组件必须处于[获焦状态](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-common-events-focus-event-V5#ZH-CN_TOPIC_0000001933380206__设置组件是否可获焦)。Image组件默认不获焦，需将[focusable](zh-cn_topic_0000001945527020.html#ZH-CN_TOPIC_0000001945527020__focusable)属性设置为true，即可使用TAB键将焦点切换到组件上，再将[focusOnTouch](zh-cn_topic_0000001945527020.html#ZH-CN_TOPIC_0000001945527020__focusontouch9)属性设置为true，即可实现点击获焦。
图片设置为svg图源时，当前支持的标签是svg、rect、circle、ellipse、path、line、polyline、polygon、feFlood、feBlend、feColorMatrix、feGaussianBlur、feComposite、filter、mask和use。
#### 需要权限
使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考[声明权限](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/declare-permissions-V5)。
#### 子组件
无
#### 接口
#### Image
Image(src: PixelMap | ResourceStr | DrawableDescriptor)
通过图片数据源获取图片，用于后续渲染展示。
Image组件加载图片失败或图片尺寸为0时，图片组件大小自动为0，不跟随父组件的布局约束。
Image组件默认按照居中裁剪，例如组件宽高设置相同，原图长宽不等，此时按照中间区域进行裁剪。
Image加载成功且组件不设置宽高时，其显示大小自适应父组件。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 参数类型 | 必填 | 参数描述 |
| --- | --- | --- | --- |
| src | [PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7) \\| [ResourceStr](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcestr)\\| [DrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__drawabledescriptor) | 是 | 图片的数据源，支持本地图片和网络图片，引用方式请参考[加载图片资源](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-graphics-display-V5#ZH-CN_TOPIC_0000001933539530__加载图片资源)。1. PixelMap格式为像素图，常用于图片编辑的场景。2. ResourceStr包含Resource和string格式。string格式可用于加载网络图片和本地图片，常用于加载网络图片。当使用相对路径引用本地图片时，例如Image("common/test.jpg")，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。- 支持Base64字符串。格式data:image/[png\\|jpeg\\|bmp\\|webp\\|heif];base64,[base64 data], 其中[base64 data]为Base64字符串数据。- 支持file://路径前缀的字符串，[应用沙箱URI](zh-cn_topic_0000001960580593.html#ZH-CN_TOPIC_0000001960580593__constructor10)：file://<bundleName>/<sandboxPath>。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。3. 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。传入[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)类型可播放PixelMap数组动画。**说明：**- ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。- ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。- ArkTS卡片上不支持 [PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7)类型。- 加载本地图片过程中，如果对图片进行修改或者替换，可能会引起应用崩溃。因此需要覆盖图片文件时，应该先删除该文件再重新创建一个同名文件。- 网络图片必须支持RFC 9113标准，否则会导致加载失败。- 如果下载的网络图片大于10MB或一次下载的网络图片数量较多，建议使用[HTTP](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/http-request-V5)工具提前预下载，提高图片加载性能，方便应用侧管理数据。- 如果SVG图片没有原生大小，需要给Image组件设置宽高，否则不显示。- 如果SVG图片通过image标签引用本地其他图片，被引用的图片不支持svg格式和gif格式。 |
#### Image12+
Image(src: PixelMap | ResourceStr | DrawableDescriptor, imageAIOptions: ImageAIOptions)
通过图片数据源获取图片，用于后续渲染展示。
Image组件加载图片失败或图片尺寸为0时，图片组件大小自动为0，不跟随父组件的布局约束。
Image组件默认按照居中裁剪，例如组件宽高设置相同，原图长宽不等，此时按照中间区域进行裁剪。
Image加载成功且组件不设置宽高时，其显示大小自适应父组件。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 参数类型 | 必填 | 参数描述 |
| --- | --- | --- | --- |
| src | [PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7) \\| [ResourceStr](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcestr)\\| [DrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__drawabledescriptor) | 是 | 图片的数据源，支持本地图片和网络图片，引用方式请参考[加载图片资源](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-graphics-display-V5#ZH-CN_TOPIC_0000001933539530__加载图片资源)。1. PixelMap格式为像素图，常用于图片编辑的场景。2. ResourceStr包含Resource和string格式。string格式可用于加载网络图片和本地图片，常用于加载网络图片。当使用相对路径引用本地图片时，例如Image("common/test.jpg")，不支持跨包/跨模块调用该Image组件，建议使用Resource格式来管理需全局使用的图片资源。- 支持Base64字符串。格式data:image/[png\\|jpeg\\|bmp\\|webp\\|heif];base64,[base64 data], 其中[base64 data]为Base64字符串数据。- 支持file://路径前缀的字符串，[应用沙箱URI](zh-cn_topic_0000001960580593.html#ZH-CN_TOPIC_0000001960580593__constructor10)：file://<bundleName>/<sandboxPath>。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。3. 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。传入[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)类型可播放PixelMap数组动画。**说明：**- ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。- ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。- ArkTS卡片上不支持 [PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7)类型。- 加载本地图片过程中，如果对图片进行修改或者替换，可能会引起应用崩溃。因此需要覆盖图片文件时，应该先删除该文件再重新创建一个同名文件。- 网络图片必须支持RFC 9113标准，否则会导致加载失败。- 如果下载的网络图片大于10MB或一次下载的网络图片数量较多，建议使用[HTTP](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/http-request-V5)工具提前预下载，提高图片加载性能，方便应用侧管理数据。- 如果SVG图片没有原生大小，需要给Image组件设置宽高，否则不显示。- 如果SVG图片通过image标签引用本地其他图片，被引用的图片不支持svg格式和gif格式。 |
| imageAIOptions | [ImageAIOptions](zh-cn_topic_0000001945367908.html#ZH-CN_TOPIC_0000001945367908__imageaioptions) | 是 | 给组件设置一个AI分析选项，通过此项可配置分析类型或绑定一个分析控制器。 |
#### 属性
属性的详细使用指导请参考[添加属性](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-graphics-display-V5#ZH-CN_TOPIC_0000001933539530__添加属性)。除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### alt
alt(value: string | Resource | PixelMap)
设置图片加载时显示的占位图。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | string \\| [Resource](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resource) \\| [PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7)12+ | 是 | 加载时显示的占位图，支持本地图片（png、jpg、bmp、svg、gif和heif类型）,支持[PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7)类型图片，不支持网络图片。默认值：null |
#### objectFit
objectFit(value: ImageFit)
设置图片的填充效果。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ImageFit](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__imagefit) | 是 | 图片的填充效果。默认值：ImageFit.Cover |
#### objectRepeat
objectRepeat(value: ImageRepeat)
设置图片的重复样式，从中心点向两边重复，剩余空间不足放下一张图片时会截断。svg类型图源不支持该属性。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ImageRepeat](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__imagerepeat) | 是 | 图片的重复样式。默认值：ImageRepeat.NoRepeat |
#### interpolation
interpolation(value: ImageInterpolation)
设置图片的插值效果，即缓解图片在缩放时的锯齿问题。svg类型图源不支持该属性。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ImageInterpolation](#ZH-CN_TOPIC_0000001972645925__imageinterpolation) | 是 | 图片的插值效果。默认值：ImageInterpolation.Low |
#### renderMode
renderMode(value: ImageRenderMode)
设置图片的渲染模式。svg类型图源不支持该属性。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ImageRenderMode](#ZH-CN_TOPIC_0000001972645925__imagerendermode) | 是 | 图片的渲染模式为原色或黑白。默认值：ImageRenderMode.Original |
#### sourceSize
sourceSize(value: { width: number; height: number })
设置图片解码尺寸。仅在目标尺寸小于图源尺寸时生效。svg类型图源和PixelMap资源不支持该属性。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | {width: number,height: number} | 是 | 图片解码尺寸，降低图片的分辨率，常用于需要让图片显示尺寸比组件尺寸更小的场景。和ImageFit.None配合使用时可在组件内显示小图。单位：vp |
#### matchTextDirection
matchTextDirection(value: boolean)
设置图片是否跟随系统语言方向，在RTL语言环境下显示镜像翻转显示效果。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 图片是否跟随系统语言方向。默认值：false |
#### fitOriginalSize
fitOriginalSize(value: boolean)
设置图片的显示尺寸是否跟随图源尺寸。图片组件尺寸未设置时，其显示尺寸是否跟随图源尺寸。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 图片的显示尺寸是否跟随图源尺寸默认值：false |
#### fillColor
fillColor(value: ResourceColor)
设置填充颜色，设置后填充颜色会覆盖在图片上。仅对svg图源生效，设置后会替换svg图片的填充颜色。如需对png图片进行修改颜色，可以使用[colorFilter](#ZH-CN_TOPIC_0000001972645925__colorfilter9)。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 设置填充颜色。 |
#### autoResize
autoResize(value: boolean)
设置图片解码过程中是否对图源自动缩放。降采样解码时图片的部分信息丢失，因此可能会导致图片质量的下降（如：出现锯齿），这时可以选择把autoResize设为false，按原图尺寸解码，提升显示效果，但会增加内存占用。
原图尺寸和显示尺寸不匹配时，图片都会出现些许的失真、模糊。最佳清晰度配置建议：
图片缩小显示时：.autoResize(false) + .interpolation(.Medium)
图片放大显示时：.interpolation(.High)
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 图片解码过程中是否对图源自动缩放。设置为true时，组件会根据显示区域的尺寸决定用于绘制的图源尺寸，有利于减少内存占用。如原图大小为1920x1080，而显示区域大小为200x200，则图片会降采样解码到200x200的尺寸，大幅度节省图片占用的内存。默认值：false |
#### syncLoad8+
syncLoad(value: boolean)
设置是否同步加载图片。建议加载尺寸较小的本地图片时将syncLoad设为true，因为耗时较短，在主线程上执行即可。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 是否同步加载图片，默认是异步加载。同步加载时阻塞UI线程，不会显示占位图。默认值：false |
#### copyOption9+
copyOption(value: CopyOptions)
设置图片是否可复制。当copyOption设置为非CopyOptions.None时，支持使用长按、鼠标右击、快捷组合键'CTRL+C'等方式进行复制。svg图片不支持复制。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [CopyOptions](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__copyoptions9) | 是 | 图片是否可复制。默认值：CopyOptions.None |
#### colorFilter9+
colorFilter(value: ColorFilter | DrawingColorFilter)
为图像设置颜色滤镜效果。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ColorFilter](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__colorfilter9) \\| [DrawingColorFilter](zh-cn_topic_0000001960461213.html#ZH-CN_TOPIC_0000001960461213__colorfilter)12+ | 是 | 1. 给图像设置颜色滤镜效果，入参为一个的4x5的RGBA转换矩阵。矩阵第一行表示R（红色）的向量值，第二行表示G（绿色）的向量值，第三行表示B（蓝色）的向量值，第四行表示A（透明度）的向量值，4行分别代表不同的RGBA的向量值。当矩阵对角线值为1，其余值为0时，保持图片原有色彩。**计算规则：**如果输入的滤镜矩阵为：像素点为[R, G, B, A]则过滤后的颜色为 [R’, G’, B’, A’]2. 从API Version12开始支持@ohos.graphics.drawing的ColorFilter类型作为入参。**说明：**API Version 11及之前，svg类型图源不支持该属性。从API version 12开始，该接口中的DrawingColorfilter类型支持在元服务中使用。其中，svg类型的图源需具有stroke属性。 |
#### draggable9+
draggable(value: boolean)
设置组件默认拖拽效果。不能和[onDragStart](zh-cn_topic_0000001972645837.html#ZH-CN_TOPIC_0000001972645837__ondragstart)事件同时使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 组件默认拖拽效果，设置为true时，组件可拖拽。API version 9及之前，默认值为false。API version 10及之后，默认值为true。 |
#### enableAnalyzer11+
enableAnalyzer(enable: boolean)
设置组件支持AI分析。不能和[overlay](zh-cn_topic_0000001972686113.html)属性同时使用，两者同时设置时overlay中CustomBuilder属性将失效。该特性依赖设备能力。
分析图像要求是静态非矢量图，即svg、gif等图像类型不支持分析，支持传入[PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7)进行分析，目前仅支持[RGBA_8888](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmapformat7)类型，使用方式见[示例](#ZH-CN_TOPIC_0000001972645925__使用pixelmap开启图像分析)。
alt占位图不支持分析，objectRepeat属性仅在ImageRepeat.NoRepeat下支持分析，隐私遮罩属性[obscured](zh-cn_topic_0000001945367724.html)打开时不支持分析。
基于完整原始图像进行分析，设置clip、margin、borderRadius、position和objectFit属性导致图像显示不完整，或使用renderMode设置蒙层，仍基于完整原始图像进行分析。 copyOption属性不影响AI分析功能。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| enable | boolean | 是 | 组件支持AI分析，设置为true时，组件可进行AI分析。默认值：false |
#### resizable11+
resizable(value: ResizableOptions)
设置图像拉伸时可调整大小的图像选项。拉伸对拖拽缩略图以及占位图有效。
设置合法的 [ResizableOptions](#ZH-CN_TOPIC_0000001972645925__resizableoptions11) 时，objectRepeat 属性设置不生效。
当设置 top +bottom 大于原图的高或者 left + right 大于原图的宽时 [ResizableOptions](#ZH-CN_TOPIC_0000001972645925__resizableoptions11) 属性设置不生效。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时设置该属性不生效。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResizableOptions](#ZH-CN_TOPIC_0000001972645925__resizableoptions11) | 是 | 图像拉伸时可调整大小的图像选项。 |
#### privacySensitive12+
privacySensitive(supported: boolean)
设置是否支持卡片敏感隐私信息。
**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| supported | boolean | 是 | 是否支持卡片敏感隐私信息。默认值为false，当设置为true时，隐私模式下图片将显示为半透明底板样式。**说明：**设置null则不敏感。进入隐私模式需要[卡片框架支持](zh-cn_topic_0000001945367724.html)。 |
#### dynamicRangeMode12+
dynamicRangeMode(value: DynamicRangeMode)
设置期望展示的图像动态范围。
该属性仅在手机设备上生效。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [DynamicRangeMode](#ZH-CN_TOPIC_0000001972645925__dynamicrangemode12-1) | 是 | 图像显示的动态范围。默认值：dynamicRangeMode.Standard |
#### ImageInterpolation
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 描述 |
| --- | --- |
| None | 最近邻插值。 |
| High | Cubic插值，插值质量最高，可能会影响图片渲染的速度。 |
| Medium | MipMap插值。 |
| Low | 双线性插值。 |
#### ImageRenderMode
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 描述 |
| --- | --- |
| Original | 原色渲染模式。 |
| Template | 黑白渲染模式。 |
#### ResizableOptions11+
图像拉伸时可调整大小的图像选项。
**元服务API：** 从API version 12开始，该接口支持在元服务中使用。
| 参数名 | 类型 | 说明 |
| --- | --- | --- |
| slice | [EdgeWidths](#ZH-CN_TOPIC_0000001972645925__edgewidths参数说明) | 边框宽度类型，用于描述组件边框不同方向的宽度。**说明：**只有当bottom和right同时大于0时，该属性生效。 |
#### EdgeWidths参数说明
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| top | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length) | 否 | 图片顶部拉伸时保持不变距离。默认值：0单位：vp |
| right | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length) | 否 | 图片右部拉伸时保持不变距离。默认值：0单位：vp |
| bottom | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length) | 否 | 图片底部拉伸时保持不变距离。默认值：0单位：vp |
| left | [Length](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__length) | 否 | 图片左部拉伸时保持不变距离。默认值：0单位：vp |
#### DynamicRangeMode12+
期望展示的图像动态范围。
| 名称 | 描述 |
| --- | --- |
| High | 不受限动态范围，最大限度进行图片提亮。 |
| Constraint | 受限动态范围，受限进行图片提亮。 |
| Standard | 标准动态范围，不进行图片提亮。 |
#### 事件
除支持[通用事件](zh-cn_topic_0000001972686089.html)外，还支持以下事件：
#### onComplete
onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number,contentWidth: number, contentHeight: number, contentOffsetX: number, contentOffsetY: number }) => void)
图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时该事件不触发。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| width | number | 是 | 图片的宽。单位：像素 |
| height | number | 是 | 图片的高。单位：像素 |
| componentWidth | number | 是 | 组件的宽。单位：像素 |
| componentHeight | number | 是 | 组件的高。单位：像素 |
| loadingStatus | number | 是 | 图片加载成功的状态值。**说明：**返回的状态值为0时，表示图片数据加载成功。返回的状态值为1时，表示图片解码成功。 |
| contentWidth10+ | number | 是 | 图片实际绘制的宽度。单位：像素**说明：**仅在loadingStatus返回1时有效。 |
| contentHeight10+ | number | 是 | 图片实际绘制的高度。单位：像素**说明：**仅在loadingStatus返回1时有效。 |
| contentOffsetX10+ | number | 是 | 实际绘制内容相对于组件自身的x轴偏移。单位：像素**说明：**仅在loadingStatus返回1时有效。 |
| contentOffsetY10+ | number | 是 | 实际绘制内容相对于组件自身的y轴偏移。单位：像素**说明：**仅在loadingStatus返回1时有效。 |
#### onError9+
onError(callback: ImageErrorCallback)
图片加载异常时触发该回调。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时该事件不触发。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | [ImageErrorCallback](#ZH-CN_TOPIC_0000001972645925__imageerrorcallback9) | 是 | 图片加载异常时触发的回调。 |
#### onFinish
onFinish(event: () => void)
当加载的源文件为带动效的svg格式图片时，svg动效播放完成时会触发这个回调。如果动效为无限循环动效，则不会触发这个回调。
仅支持svg格式的图片。当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时该事件不触发。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
#### ImageErrorCallback9+
type ImageErrorCallback = (error: ImageError) => void
图片加载异常时触发的回调。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时该事件不触发。
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| error | [ImageError](#ZH-CN_TOPIC_0000001972645925__imageerror9) | 是 | 图片加载异常时触发回调的返回对象。 |
#### ImageError9+
图片加载异常时触发回调的返回对象。
当组件的参数类型为[AnimatedDrawableDescriptor](zh-cn_topic_0000001933381306.html#ZH-CN_TOPIC_0000001933381306__animateddrawabledescriptor12)时该事件不触发。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| componentWidth | number | 是 | 组件的宽。单位：像素 |
| componentHeight | number | 是 | 组件的高。单位：像素 |
| message | string | 是 | 报错信息。 |
#### 示例
#### 示例1
加载基本类型图片
@Entry
@Component
struct ImageExample1 {
build() {
Column() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) {
Row() {
// 加载png格式图片
Image($r('app.media.ic_camera_master_ai_leaf'))
.width(110).height(110).margin(15)
.overlay('png', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
// 加载gif格式图片
Image($r('app.media.loading'))
.width(110).height(110).margin(15)
.overlay('gif', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
}
Row() {
// 加载svg格式图片
Image($r('app.media.ic_camera_master_ai_clouded'))
.width(110).height(110).margin(15)
.overlay('svg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
// 加载jpg格式图片
Image($r('app.media.ic_public_favor_filled'))
.width(110).height(110).margin(15)
.overlay('jpg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
}
}
}.height(320).width(360).padding({ right: 10, top: 10 })
}
}
#### 示例2
加载网络图片时，默认网络超时是5分钟，建议使用alt配置加载时的占位图。如果需要更灵活的网络配置，可以使用[HTTP](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/http-request-V5)工具包发送网络请求，接着将返回的数据解码为Image组件中的PixelMap，图片开发可参考[图片处理](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/image-overview-V5)。
使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考[声明权限](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/declare-permissions-V5)。
@Entry
@Component
struct ImageExample2 {
build() {
Column({ space: 10 }) {
Image("https://www.example.com/xxx.png")// 直接加载网络地址，请填写一个具体的网络图片地址
.alt($r('app.media.LoadingProgress'))// 使用alt，在网络图片加载成功前使用占位图
.width(375)
.height(300)
}
}
}
#### 示例3
为图片添加事件
@Entry
@Component
struct ImageExample3 {
private imageOne: Resource = $r('app.media.earth');
private imageTwo: Resource = $r('app.media.star');
private imageThree: Resource = $r('app.media.moveStar');
@State src: Resource = this.imageOne
@State src2: Resource = this.imageThree
build(){
Column(){
// 为图片添加点击事件，点击完成后加载特定图片
Image(this.src)
.width(100)
.height(100)
.onClick(() => {
this.src = this.imageTwo
})
// 当加载图片为SVG格式时
Image(this.src2)
.width(100)
.height(100)
.onClick(() => {
// SVG动效播放完成时加载另一张图片
this.src2 = this.imageOne
})
}.width('100%').height('100%')
}
}
#### 示例4
使用PixelMap开启图像分析
import { image } from '@kit.ImageKit'
@Entry
@Component
struct ImageExample4 {
@State imagePixelMap: image.PixelMap | undefined = undefined
private aiController: ImageAnalyzerController = new ImageAnalyzerController()
private options: ImageAIOptions = {
types: [ImageAnalyzerType.SUBJECT, ImageAnalyzerType.TEXT],
aiController: this.aiController
}
async aboutToAppear() {
this.imagePixelMap = await this.getPixmapFromMedia($r('app.media.app_icon'))
}
build() {
Column() {
Image(this.imagePixelMap, this.options)
.enableAnalyzer(true)
.width(200)
.height(200)
Button('getTypes')
.width(80)
.height(80)
.onClick(() => {
this.aiController.getImageAnalyzerSupportTypes()
})
}
}
private async getPixmapFromMedia(resource: Resource) {
let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({
bundleName: resource.bundleName,
moduleName: resource.moduleName,
id: resource.id
})
let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength))
let createPixelMap: image.PixelMap = await imageSource.createPixelMap({
desiredPixelFormat: image.PixelMapFormat.RGBA_8888
})
await imageSource.release()
return createPixelMap
}
}
#### 示例5
调整不同方向对图片进行拉伸
@Entry
@Component
struct Index {
@State top: number = 40
@State bottom: number = 5
@State left: number = 40
@State right: number = 10
build() {
Column({ space: 5 }) {
// 原图效果
Image($r("app.media.sky"))
.width(200).height(200)
.border({ width: 2, color: Color.Pink })
.objectFit(ImageFit.Contain)
// 图像拉伸效果，设置resizable属性，对图片不同方向进行拉伸
Image($r("app.media.sky"))
.resizable({
slice: {
left: this.left,
right: this.right,
top: this.top,
bottom: this.bottom
}
})
.width(200)
.height(200)
.border({ width: 2, color: Color.Pink })
.objectFit(ImageFit.Contain)
Row() {
Button("add top to " + this.top).fontSize(10)
.onClick(() => {
this.top += 2
})
Button("add bottom to " + this.bottom).fontSize(10)
.onClick(() => {
this.bottom += 2
})
}
Row() {
Button("add left to " + this.left).fontSize(10)
.onClick(() => {
this.left += 2
})
Button("add right to " + this.right).fontSize(10)
.onClick(() => {
this.right += 2
})
}
}
.justifyContent(FlexAlign.Start).width('100%').height('100%')
}
}
#### 示例6
播放PixelMap数组动画
import {AnimationOptions, AnimatedDrawableDescriptor} from '@kit.ArkUI'
import { image } from '@kit.ImageKit'
@Entry
@Component
struct ImageExample {
pixelmaps: Array<PixelMap> = [];
options: AnimationOptions = {duration:2000, iterations:1};
@State animated: AnimatedDrawableDescriptor | undefined = undefined;
async aboutToAppear() {
this.pixelmaps = await this.getPixelMaps();
this.animated = new AnimatedDrawableDescriptor(this.pixelmaps, this.options);
}
build() {
Column() {
Row() {
Image(this.animated)
.width('500px').height('500px')
.onFinish(() => {
console.info("finish")
})
}.height('50%')
Row() {
Button('once').width(100).padding(5).onClick(() => {
this.options = {duration:2000, iterations:1};
this.animated = new AnimatedDrawableDescriptor(this.pixelmaps, this.options);
}).margin(5)
Button('infinite').width(100).padding(5).onClick(() => {
this.options = {duration:2000, iterations:-1};
this.animated = new AnimatedDrawableDescriptor(this.pixelmaps, this.options);
}).margin(5)
}
}.width('50%')
}
private async getPixmapListFromMedia(resource: Resource) {
let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({
bundleName: resource.bundleName,
moduleName: resource.moduleName,
id: resource.id
})
let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength))
let createPixelMap: Array<image.PixelMap> = await imageSource.createPixelMapList({
desiredPixelFormat: image.PixelMapFormat.RGBA_8888
})
await imageSource.release()
return createPixelMap
}
private async getPixmapFromMedia(resource: Resource) {
let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({
bundleName: resource.bundleName,
moduleName: resource.moduleName,
id: resource.id
})
let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength))
let createPixelMap: image.PixelMap = await imageSource.createPixelMap({
desiredPixelFormat: image.PixelMapFormat.RGBA_8888
})
await imageSource.release()
return createPixelMap
}
private async getPixelMaps() {
let Mypixelmaps:Array<PixelMap> = await this.getPixmapListFromMedia($r('app.media.view'))//gif图, 生成多张PixelMap
Mypixelmaps.push(await this.getPixmapFromMedia($r('app.media.icon'))) //添加一张图片
return Mypixelmaps;
}
}
#### 示例7
该示例实现了给图像设置颜色滤镜效果
import { drawing, common2D } from '@kit.ArkGraphics2D';
@Entry
@Component
struct ImageExample3 {
private imageOne: Resource = $r('app.media.1');
private imageTwo: Resource = $r('app.media.2');
@State src: Resource = this.imageOne
@State src2: Resource = this.imageTwo
private ColorFilterMatrix: number[] = [1, 0, 1, 0, 1, 0, 0, 0, 1, 0, 1, 0, 1, 0, 0, 0, 1, 0, 1, 0]
private color: common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 };
@State DrawingColorFilterFirst: ColorFilter | undefined = undefined
@State DrawingColorFilterSecond: ColorFilter | undefined = undefined
@State DrawingColorFilterThird: ColorFilter | undefined = undefined
build() {
Column() {
Image(this.src)
.width(100)
.height(100)
.colorFilter(this.DrawingColorFilterFirst)
.onClick(()=>{
this.DrawingColorFilterFirst = drawing.ColorFilter.createBlendModeColorFilter(this.color, drawing.BlendMode.SRC_IN);
})
Image(this.src2)
.width(100)
.height(100)
.colorFilter(this.DrawingColorFilterSecond)
.onClick(()=>{
this.DrawingColorFilterSecond = new ColorFilter(this.ColorFilterMatrix);
})
//当加载图片为SVG格式时
Image($r('app.media.test_self'))
.width(110).height(110).margin(15)
.colorFilter(this.DrawingColorFilterThird)
.onClick(()=>{
this.DrawingColorFilterThird = drawing.ColorFilter.createBlendModeColorFilter(this.color, drawing.BlendMode.SRC_IN);
})
}
}
}
# ImageAnimator
提供帧动画组件来实现逐帧播放图片的能力，可以配置需要播放的图片列表，每张图片可以配置时长。
该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
无
#### 接口
ImageAnimator()
**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
#### 属性
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### images
images(value: Array<ImageFrameInfo>)
设置图片帧信息集合。不支持动态更新。
**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | Array<[ImageFrameInfo](#ZH-CN_TOPIC_0000001972686181__imageframeinfo对象说明)> | 是 | 设置图片帧信息集合。每一帧的帧信息(ImageFrameInfo)包含图片路径、图片大小、图片位置和图片播放时长信息，详见ImageFrameInfo属性说明。默认值：[] |
#### state
state(value: AnimationStatus)
控制播放状态。
**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [AnimationStatus](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__animationstatus) | 是 | 默认为初始状态，用于控制播放状态。默认值：AnimationStatus.Initial |
#### duration
duration(value: number)
设置播放时长。当Images中任意一帧图片设置了单独的duration后，该属性设置无效。
**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | number | 是 | 播放时长。value为0时，不播放图片。value的改变只会在下一次循环开始时生效。单位：毫秒默认值：1000ms |
#### reverse
reverse(value: boolean)
设置播放方向。
**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 播放方向。false表示从第1张图片播放到最后1张图片，true表示从最后1张图片播放到第1张图片。默认值：false |
#### fixedSize
fixedSize(value: boolean)
设置图片大小是否固定为组件大小。
**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 设置图片大小是否固定为组件大小。 true表示图片大小与组件大小一致，此时设置图片的width 、height 、top 和left属性是无效的。false表示每一张图片的width 、height 、top和left属性都要单独设置。默认值：true |
#### preDecode(deprecated)
preDecode(value: number)
设置预解码的图片数量。
从API version 9开始废弃。
**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | number | 是 | 预解码的图片数量。例如该值设为2，则播放当前页时会提前加载后面两张图片至缓存以提升性能。默认值：0 |
#### fillMode
fillMode(value: FillMode)
设置当前播放方向下，动画开始前和结束后的状态。动画结束后的状态由fillMode和reverse属性共同决定。例如，fillMode为Forwards表示停止时维持动画最后一个关键帧的状态，若reverse为false则维持正播的最后一帧，即最后一张图，若reverse为true则维持逆播的最后一帧，即第一张图。
**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [FillMode](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__fillmode) | 是 | 当前播放方向下，动画开始前和结束后的状态。默认值：FillMode.Forwards |
#### iterations
iterations(value: number)
设置播放次数。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | number | 是 | 默认播放一次，设置为-1时表示无限次播放。默认值：1 |
#### ImageFrameInfo对象说明
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 参数名称 | 参数类型 | 必填 | 参数描述 |
| --- | --- | --- | --- |
| src | string \\| [Resource](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resource)9+ \\| [PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7)12+ | 是 | 图片路径，图片格式为svg，png和jpg，从API Version9开始支持[Resource](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resource)类型的路径，从API version 12开始支持[PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7)类型。**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。 |
| width | number \\| string | 否 | 图片宽度。默认值：0从API version 10开始，该接口支持在ArkTS卡片中使用 |
| height | number \\| string | 否 | 图片高度。默认值：0从API version 10开始，该接口支持在ArkTS卡片中使用 |
| top | number \\| string | 否 | 图片相对于组件左上角的纵向坐标。默认值：0从API version 10开始，该接口支持在ArkTS卡片中使用 |
| left | number \\| string | 否 | 图片相对于组件左上角的横向坐标。默认值：0从API version 10开始，该接口支持在ArkTS卡片中使用 |
| duration | number | 否 | 每一帧图片的播放时长，单位毫秒。默认值：0 |
#### 事件
除支持[通用事件](zh-cn_topic_0000001972686089.html)外，还支持以下事件：
#### onStart
onStart(event: () => void)
状态回调，动画开始播放时触发。
**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
#### onPause
onPause(event: () => void)
状态回调，动画暂停播放时触发。
**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
#### onRepeat
onRepeat(event: () => void)
状态回调，动画重复播放时触发。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
#### onCancel
onCancel(event: () => void)
状态回调，动画返回最初状态时触发。
**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
#### onFinish
onFinish(event: () => void)
状态回调，动画播放完成时或者停止播放时触发。
**卡片能力：** 从API version 10开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
#### 示例
#### 播放Resource动画
// xxx.ets
@Entry
@Component
struct ImageAnimatorExample {
@State state: AnimationStatus = AnimationStatus.Initial
@State reverse: boolean = false
@State iterations: number = 1
build() {
Column({ space: 10 }) {
ImageAnimator()
.images([
{
src: $r('app.media.img1')
},
{
src: $r('app.media.img2')
},
{
src: $r('app.media.img3')
},
{
src: $r('app.media.img4')
}
])
.duration(2000)
.state(this.state).reverse(this.reverse)
.fillMode(FillMode.None).iterations(this.iterations).width(340).height(240)
.margin({ top: 100 })
.onStart(() => {
console.info('Start')
})
.onPause(() => {
console.info('Pause')
})
.onRepeat(() => {
console.info('Repeat')
})
.onCancel(() => {
console.info('Cancel')
})
.onFinish(() => {
console.info('Finish')
this.state = AnimationStatus.Stopped
})
Row() {
Button('start').width(100).padding(5).onClick(() => {
this.state = AnimationStatus.Running
}).margin(5)
Button('pause').width(100).padding(5).onClick(() => {
this.state = AnimationStatus.Paused // 显示当前帧图片
}).margin(5)
Button('stop').width(100).padding(5).onClick(() => {
this.state = AnimationStatus.Stopped // 显示动画的起始帧图片
}).margin(5)
}
Row() {
Button('reverse').width(100).padding(5).onClick(() => {
this.reverse = !this.reverse
}).margin(5)
Button('once').width(100).padding(5).onClick(() => {
this.iterations = 1
}).margin(5)
Button('infinite').width(100).padding(5).onClick(() => {
this.iterations = -1 // 无限循环播放
}).margin(5)
}
}.width('100%').height('100%')
}
}
#### 播放PixelMap动画
import { image } from '@kit.ImageKit'
@Entry
@Component
struct ImageAnimatorExample {
imagePixelMap: Array<PixelMap> = []
@State state: AnimationStatus = AnimationStatus.Initial
@State reverse: boolean = false
@State iterations: number = 1
@State images:Array<ImageFrameInfo> = []
async aboutToAppear() {
this.imagePixelMap.push(await this.getPixmapFromMedia($r('app.media.icon')))
this.images.push({src:this.imagePixelMap[0]})
}
build() {
Column({ space: 10 }) {
ImageAnimator()
.images(this.images)
.duration(2000)
.state(this.state).reverse(this.reverse)
.fillMode(FillMode.None).iterations(this.iterations).width(340).height(240)
.margin({ top: 100 })
.onStart(() => {
console.info('Start')
})
.onPause(() => {
console.info('Pause')
})
.onRepeat(() => {
console.info('Repeat')
})
.onCancel(() => {
console.info('Cancel')
})
.onFinish(() => {
console.info('Finish')
this.state = AnimationStatus.Stopped
})
Row() {
Button('start').width(100).padding(5).onClick(() => {
this.state = AnimationStatus.Running
}).margin(5)
Button('pause').width(100).padding(5).onClick(() => {
this.state = AnimationStatus.Paused // 显示当前帧图片
}).margin(5)
Button('stop').width(100).padding(5).onClick(() => {
this.state = AnimationStatus.Stopped // 显示动画的起始帧图片
}).margin(5)
}
Row() {
Button('reverse').width(100).padding(5).onClick(() => {
this.reverse = !this.reverse
}).margin(5)
Button('once').width(100).padding(5).onClick(() => {
this.iterations = 1
}).margin(5)
Button('infinite').width(100).padding(5).onClick(() => {
this.iterations = -1 // 无限循环播放
}).margin(5)
}
}.width('100%').height('100%')
}
private async getPixmapFromMedia(resource: Resource) {
let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({
bundleName: resource.bundleName,
moduleName: resource.moduleName,
id: resource.id
})
let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength))
let createPixelMap: image.PixelMap = await imageSource.createPixelMap({
desiredPixelFormat: image.PixelMapFormat.RGBA_8888
})
await imageSource.release()
return createPixelMap
}
}
# ImageSpan
[Text](zh-cn_topic_0000001972645953.html)、[ContainerSpan](zh-cn_topic_0000001945367752.html)组件的子组件，用于显示行内图片。
该组件从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
无
#### 接口
ImageSpan(value: ResourceStr | PixelMap)
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 参数类型 | 必填 | 参数描述 |
| --- | --- | --- | --- |
| value | [ResourceStr](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcestr) \\| [PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7) | 是 | 图片的数据源，支持本地图片和网络图片。当使用相对路径引用图片资源时，例如ImageSpan("common/test.jpg")，不支持跨包/跨模块调用该ImageSpan组件，建议使用$r方式来管理需全局使用的图片资源。- 支持的图片格式包括png、jpg、bmp、svg、gif和heif。- 支持Base64字符串。格式data:image/[png\\|jpeg\\|bmp\\|webp\\|heif];base64,[base64 data], 其中[base64 data]为Base64字符串数据。- 支持file:///data/storage路径前缀的字符串，用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。 |
#### 属性
属性继承自[BaseSpan](zh-cn_topic_0000001945367780.html#ZH-CN_TOPIC_0000001945367780__basespan)，通用属性方法支持[尺寸设置](zh-cn_topic_0000001945367680.html#ZH-CN_TOPIC_0000001945367680__尺寸设置)、[背景设置](zh-cn_topic_0000001972686109.html#ZH-CN_TOPIC_0000001972686109__背景设置)、[边框设置](zh-cn_topic_0000001945367684.html#ZH-CN_TOPIC_0000001945367684__边框设置)
#### alt12+
alt(value: PixelMap)
设置图片加载时显示的占位图。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7) | 是 | 加载时显示的占位图，支持[PixelMap](zh-cn_topic_0000001933382582.html#ZH-CN_TOPIC_0000001933382582__pixelmap7)类型。默认值：null |
#### verticalAlign
verticalAlign(value: ImageSpanAlignment)
设置图片基于文本的对齐方式。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ImageSpanAlignment](#ZH-CN_TOPIC_0000001945527080__imagespanalignment) | 是 | 图片基于文本的对齐方式。默认值：ImageSpanAlignment.BOTTOM |
#### objectFit
objectFit(value: ImageFit)
设置图片的缩放类型。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ImageFit](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__imagefit) | 是 | 图片的缩放类型。默认值：ImageFit.Cover |
#### ImageSpanAlignment
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
| 名称 | 描述 |
| --- | --- |
| TOP | 图片上边沿与行上边沿对齐。 |
| CENTER | 图片中间与行中间对齐。 |
| BOTTOM | 图片下边沿与行下边沿对齐。 |
| BASELINE | 图片下边沿与文本BaseLine对齐。 |
#### 事件
通用事件仅支持[点击事件](zh-cn_topic_0000001945527244.html)。还支持以下事件：
#### onComplete12+
onComplete(callback: ImageCompleteCallback)
图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | [ImageCompleteCallback](#ZH-CN_TOPIC_0000001945527080__imagecompletecallback12) | 是 | 图片数据加载成功和解码成功时触发的回调。 |
#### onError12+
onError(callback: ImageErrorCallback)
图片加载异常时触发该回调。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| callback | [ImageErrorCallback](zh-cn_topic_0000001972645925.html#ZH-CN_TOPIC_0000001972645925__imageerrorcallback9) | 是 | 图片加载异常时触发的回调。 |
#### ImageCompleteCallback12+
type ImageCompleteCallback = (result: ImageLoadResult) => void
图片加载异常时触发的回调。
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| result | [ImageLoadResult](#ZH-CN_TOPIC_0000001945527080__imageloadresult12) | 是 | 图片数据加载成功和解码成功触发回调时返回的对象。 |
#### ImageLoadResult12+
图片数据加载成功和解码成功触发回调时返回的对象。
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| width | number | 是 | 图片的宽。单位：像素 |
| height | number | 是 | 图片的高。单位：像素 |
| componentWidth | number | 是 | 组件的宽。单位：像素 |
| componentHeight | number | 是 | 组件的高。单位：像素 |
| loadingStatus | number | 是 | 图片加载成功的状态值。**说明：**返回的状态值为0时，表示图片数据加载成功。返回的状态值为1时，表示图片解码成功。 |
| contentWidth | number | 是 | 图片实际绘制的宽度。单位：像素**说明：**仅在loadingStatus返回1时有效。 |
| contentHeight | number | 是 | 图片实际绘制的高度。单位：像素**说明：**仅在loadingStatus返回1时有效。 |
| contentOffsetX | number | 是 | 实际绘制内容相对于组件自身的x轴偏移。单位：像素**说明：**仅在loadingStatus返回1时有效。 |
| contentOffsetY | number | 是 | 实际绘制内容相对于组件自身的y轴偏移。单位：像素**说明：**仅在loadingStatus返回1时有效。 |
#### 示例
#### 示例1
该示例实现了设置ImageSpan的基本属性和图片基于文本的对齐方式。
// xxx.ets
@Entry
@Component
struct SpanExample {
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Text() {
Span('This is the Span and ImageSpan component').fontSize(25).textCase(TextCase.Normal)
.decoration({ type: TextDecorationType.None, color: Color.Pink })
}.width('100%').textAlign(TextAlign.Center)
Text() {
ImageSpan($r('app.media.icon'))
.width('200px')
.height('200px')
.objectFit(ImageFit.Fill)
.verticalAlign(ImageSpanAlignment.CENTER)
Span('I am LineThrough-span')
.decoration({ type: TextDecorationType.LineThrough, color: Color.Red }).fontSize(25)
ImageSpan($r('app.media.icon'))
.width('50px')
.height('50px')
.verticalAlign(ImageSpanAlignment.TOP)
Span('I am Underline-span')
.decoration({ type: TextDecorationType.Underline, color: Color.Red }).fontSize(25)
ImageSpan($r('app.media.icon'))
.size({ width: '100px', height: '100px' })
.verticalAlign(ImageSpanAlignment.BASELINE)
Span('I am Underline-span')
.decoration({ type: TextDecorationType.Underline, color: Color.Red }).fontSize(25)
ImageSpan($r('app.media.icon'))
.width('70px')
.height('70px')
.verticalAlign(ImageSpanAlignment.BOTTOM)
Span('I am Underline-span')
.decoration({ type: TextDecorationType.Underline, color: Color.Red }).fontSize(50)
}
.width('100%')
.textIndent(50)
}.width('100%').height('100%').padding({ left: 0, right: 0, top: 0 })
}
}
#### 示例2
该示例实现了如何设置ImageSpan图片的背景样式。
// xxx.ets
@Component
@Entry
struct Index {
build() {
Column() {
Text() {
ImageSpan($r('app.media.app_icon'))
.width('60vp')
.height('60vp')
.verticalAlign(ImageSpanAlignment.CENTER)
.textBackgroundStyle({color: Color.Green, radius: "5vp"})
}
}.width('100%').alignItems(HorizontalAlign.Center)
}
}
#### 示例3
ImageSpan设置图片成功加载解码和图片加载异常事件回调。
// xxx.ets
@Entry
@Component
struct Index {
@State src: ResourceStr = $r('app.media.icon');
build(){
Column(){
Text(){
ImageSpan(this.src)
.width(100).height(100)
.onError((err)=>{
console.log("onError:" + err.message)
})
.onComplete((event)=>{
console.log("onComplete: " + event.loadingStatus)
})
}
}.width('100%').height('100%')
}
}
# LoadingProgress
用于显示加载动效的组件。
该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
#### 子组件
无
#### 接口
LoadingProgress()
创建加载进展组件。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
#### 属性
除支持[通用属性](zh-cn_topic_0000001945367680.html)外，还支持以下属性：
#### color
color(value: ResourceColor)
设置加载进度条前景色。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [ResourceColor](zh-cn_topic_0000001945527232.html#ZH-CN_TOPIC_0000001945527232__resourcecolor) | 是 | 加载进度条的前景色。默认值：API version 10及以下：'#99666666'API version 11及以上：'#ff666666' |
#### enableLoading10+
enableLoading(value: boolean)
设置LoadingProgress动画显示或者不显示。LoadingProgress动画不显示时，该组件依旧占位。通用属性[Visibility.Hidden](zh-cn_topic_0000001945367688.html#ZH-CN_TOPIC_0000001945367688__visibility)隐藏的是包括[border](zh-cn_topic_0000001945367684.html#ZH-CN_TOPIC_0000001945367684__border)、[padding](zh-cn_topic_0000001945367680.html#ZH-CN_TOPIC_0000001945367680__padding)等整个组件范围，而enableLoading=false只隐藏LoadingProgress本身动画内容，不包括border等。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | LoadingProgress动画是否显示。默认值：true |
#### contentModifier12+
contentModifier(modifier: ContentModifier<LoadingProgressConfiguration>)
定制LoadingProgress内容区的方法。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| modifier | [ContentModifier](#ZH-CN_TOPIC_0000001945367760__loadingprogressconfiguration12对象说明) | 是 | 在LoadingProgress组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。 |
#### 事件
支持[通用事件](zh-cn_topic_0000001972686089.html)。
#### LoadingProgressConfiguration12+对象说明
开发者需要自定义class实现ContentModifier接口。
| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| enableloading | boolean | true | LoadingProgress动画是否显示。默认值：true。 |
#### 示例
#### 示例1
// xxx.ets
@Entry
@Component
struct LoadingProgressExample {
build() {
Column({ space: 5 }) {
Text('Orbital LoadingProgress ').fontSize(9).fontColor(0xCCCCCC).width('90%')
LoadingProgress()
.color(Color.Blue)
.layoutWeight(1)
}.width('100%').margin({ top: 5 })
}
}
#### 示例2
//该示例实现了自定义LoadingProgress的功能，实现了通过按钮切换是否显示LoadingProgress。点击按钮，config.enableLoading切换为false, 不显示LoadingProgress。。
// xxx.ets
import { hilog } from '@kit.PerformanceAnalysisKit'
import { promptAction } from '@kit.ArkUI'
class MyLoadingProgressStyle implements ContentModifier<LoadingProgressConfiguration> {
enableLoading: boolean = false
constructor(enableLoading: boolean) {
this.enableLoading = enableLoading
}
applyContent(): WrappedBuilder<[LoadingProgressConfiguration]> {
return wrapBuilder(buildLoadingProgress)
}
}
let arr1: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19"]
let arr2: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9"]
@Builder
function buildLoadingProgress(config: LoadingProgressConfiguration) {
Column({ space: 8 }) {
Row() {
Column() {
Circle({
width: ((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? 100 : 80,
height: ((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? 100 : 80
})
.fill(((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? Color.Grey : 0x2577e3)
}.width('50%')
Column() {
Button('' + ((config.contentModifier as MyLoadingProgressStyle).enableLoading))
.onClick((event: ClickEvent) => {
promptAction.showToast({
message: ((config.contentModifier as MyLoadingProgressStyle).enableLoading) + ''
})
})
.fontColor(Color.White)
.backgroundColor(((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? Color.Grey : 0x2577e3)
}.width('50%')
}
Row() {
Column() {
Gauge({
value: (config.contentModifier as MyLoadingProgressStyle).enableLoading?50:30, min: 11, max: 100
}) {
Column() {
Text('60')
.maxFontSize("180sp")
.minFontSize("160.0vp")
.fontWeight(FontWeight.Medium)
.fontColor("#ff182431")
.width('40%')
.height('30%')
.textAlign(TextAlign.Center)
.margin({ top: '22.2%' })
.textOverflow({ overflow: TextOverflow.Ellipsis })
.maxLines(1)
}.width('100%').height('100%')
}
.colors(((config.contentModifier as MyLoadingProgressStyle).enableLoading) ? Color.Grey : 0x2577e3)
.width(200)
.strokeWidth(18)
.padding(5)
.trackShadow({ radius: 7, offsetX: 7, offsetY: 7 })
.height(200)
}.width('100%')
}
Column() {
List({ space: 20, initialIndex: 0 }) {
ForEach(arr2, (item: string) => {
ListItem() {
Text((config.contentModifier as MyLoadingProgressStyle).enableLoading ? '' + item : Number(item) * 2 + '')
.width('100%')
.height('100%')
.fontColor((config.contentModifier as MyLoadingProgressStyle).enableLoading ? Color.White : Color.Orange)
.fontSize((config.contentModifier as MyLoadingProgressStyle).enableLoading ? 16 : 20)
.textAlign(TextAlign.Center)
.backgroundColor((config.contentModifier as MyLoadingProgressStyle).enableLoading ? Color.Grey : 0x2577e3)
}
.height(110)
.border({
width: 2,
color: Color.White
})
}, (item: string) => item)
}
.height(200)
.width('100%')
.friction(0.6)
.lanes({ minLength: (config.contentModifier as MyLoadingProgressStyle).enableLoading?40:80, maxLength: (config.contentModifier as MyLoadingProgressStyle).enableLoading?40:80 })
.scrollBar(BarState.Off)
}
}.width("100%").padding(10)
}
@Entry
@Component
struct LoadingProgressDemoExample {
@State loadingProgressList: (boolean | undefined | null)[] = [undefined, true, null, false]
@State widthList: (number | string)[] = ['110%', 220, '40%', 80]
@State loadingProgressIndex: number = 0
@State clickFlag: number = 0
scroller: Scroller = new Scroller()
build() {
Column() {
Scroll(this.scroller) {
Column({ space: 5 }) {
Column() {
LoadingProgress()
.color('#106836')
.size({ width: '100%' })
.contentModifier(new MyLoadingProgressStyle(this.loadingProgressList[this.loadingProgressIndex]))
}.width('100%').backgroundColor(0xdcdcdc)
}.width('100%').margin({ top: 5 })
}.height('85%')
Button('点击切换config.enableloading').onClick(() => {
this.clickFlag++
this.loadingProgressIndex = (this.loadingProgressIndex + 1) % this.loadingProgressList.length
console.log('enableLoading:' + this.loadingProgressList[this.loadingProgressIndex])
}).margin(20)
}
}
}
# Marquee
跑马灯组件，用于滚动展示一段单行文本。仅当文本内容宽度超过跑马灯组件宽度时滚动，不超过时不滚动。
该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
为了不影响滚动帧率，建议在滚动类组件中Marquee的个数不超过4个，或者使用[Text](zh-cn_topic_0000001972645953.html)组件的[TextOverflow.MARQUEE](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__textoverflow)替代。
#### 子组件
无
#### 接口
Marquee(value: { start: boolean, step?: number, loop?: number, fromStart?: boolean, src: string })
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**参数：**
| 参数名 | 参数类型 | 必填 | 参数描述 |
| --- | --- | --- | --- |
| value | { start: boolean, step?: number, loop?: number, fromStart?: boolean, src: string } | 是 | 配置跑马灯组件的参数。- start：控制跑马灯是否进入播放状态。**说明：**有限的滚动次数播放完毕后，不可以通过改变start重置滚动次数重新开始播放。- step：滚动动画文本滚动步长，当step大于Marquee的文本宽度时，取默认值。默认值：6，单位vp- loop：设置重复滚动的次数，小于等于零时无限循环。默认值：-1**说明：**ArkTS卡片上该参数设置任意值都仅在可见时滚动一次。- fromStart：设置文本从头开始滚动或反向滚动。默认值：true- src：需要滚动的文本。 |
#### 属性
除支持文本通用属性：[fontColor](zh-cn_topic_0000001972645893.html#ZH-CN_TOPIC_0000001972645893__fontcolor)、[fontSize](zh-cn_topic_0000001972645893.html#ZH-CN_TOPIC_0000001972645893__fontsize)、[fontWeight](zh-cn_topic_0000001972645893.html#ZH-CN_TOPIC_0000001972645893__fontweight)、[fontFamily](zh-cn_topic_0000001972645893.html#ZH-CN_TOPIC_0000001972645893__fontfamily)外，还支持以下属性：
#### allowScale
allowScale(value: boolean)
设置是否允许文本缩放。
暂不支持该接口。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | boolean | 是 | 是否允许文本缩放。默认值：false |
#### marqueeUpdateStrategy12+
marqueeUpdateStrategy(value: MarqueeUpdateStrategy)
跑马灯组件属性更新后，跑马灯的滚动策略。(当跑马灯为播放状态，且文本内容宽度超过跑马灯组件宽度时，该属性生效。)
**卡片能力：** 从API version 12开始，该接口支持在ArkTS卡片中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| value | [MarqueeUpdateStrategy](zh-cn_topic_0000001945367912.html#ZH-CN_TOPIC_0000001945367912__marqueeupdatestrategy12枚举说明) | 是 | 跑马灯组件属性更新后，跑马灯的滚动策略。默认值: MarqueeUpdateStrategy.DEFAULT |
#### 事件
#### onStart
onStart(event: () => void)
开始滚动时触发回调。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
#### onBounce
onBounce(event: () => void)
完成一次滚动时触发，若循环次数不为1，则该事件会多次触发。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
#### onFinish
onFinish(event: () => void)
滚动全部循环次数完成时触发回调。
**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
**元服务API：** 从API version 11开始，该接口支持在元服务中使用。
**系统能力：** SystemCapability.ArkUI.ArkUI.Full
#### 示例
// xxx.ets
@Entry
@Component
struct MarqueeExample {
@State start: boolean = false
@State src: string = ''
@State marqueeText: string = 'Running Marquee'
private fromStart: boolean = true
private step: number = 10
private loop: number = Number.POSITIVE_INFINITY
controller: TextClockController = new TextClockController()
convert2time(value: number): string{
let date = new Date(Number(value+'000'));
let hours = date.getHours().toString().padStart(2, '0');
let minutes = date.getMinutes().toString().padStart(2, '0');
let seconds = date.getSeconds().toString().padStart(2, '0');
return hours+ ":" + minutes + ":" + seconds;
}
build() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
Marquee({
start: this.start,
step: this.step,
loop: this.loop,
fromStart: this.fromStart,
src: this.marqueeText + this.src
})
.marqueeUpdateStrategy(MarqueeUpdateStrategy.PRESERVE_POSITION)
.width(300)
.height(80)
.fontColor('#FFFFFF')
.fontSize(48)
.fontWeight(700)
.backgroundColor('#182431')
.margin({ bottom: 40 })
.onStart(() => {
console.info('Marquee animation complete onStart')
})
.onBounce(() => {
console.info('Marquee animation complete onBounce')
})
.onFinish(() => {
console.info('Marquee animation complete onFinish')
})
Button('Start')
.onClick(() => {
this.start = true
//启动文本时钟
this.controller.start()
})
.width(120)
.height(40)
.fontSize(16)
.fontWeight(500)
.backgroundColor('#007DFF')
TextClock({ timeZoneOffset: -8, controller: this.controller })
.format('hms')
.onDateChange((value: number) => {
this.src = this.convert2time(value);
})
.margin(20)
.fontSize(30)
}
.width('100%')
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
