Marquee

跑马灯组件，用于滚动展示一段单行文本。仅当文本内容宽度超过跑马灯组件宽度时滚动，不超过时不滚动。

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

为了不影响滚动帧率，建议在滚动类组件中Marquee的个数不超过4个，或者使用Text组件的TextOverflow.MARQUEE替代。

子组件

无

接口

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、fontSize、fontWeight、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	是	跑马灯组件属性更新后，跑马灯的滚动策略。默认值: 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

示例

ts 复制代码

复制代码// 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%')
    .height('100%')
  }
}

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说明：不支持设置百分比。负值使用默认值。当最小值大于容器可用空间时，使用最小值作为自身大小并超出容器。

属性

除支持通用属性外，还支持以下属性：

color

color(value: ResourceColor)

设置空白填充的填充颜色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ResourceColor	是	空白填充的填充颜色。默认值：Color.Transparent

事件

支持通用事件。

示例

示例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参数的使用效果。

ts 复制代码

// 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

Button(options: ButtonOptions)

创建可以包含单个子组件的按钮。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
options	[ButtonOptions](#参数名类型必填说明 options ButtonOptions 是配置按钮的显示样式。)	是	配置按钮的显示样式。

Button

Button(label: ResourceStr, options?: ButtonOptions)

使用文本内容创建相应的按钮组件，此时Button无法包含子组件。

文本内容默认单行显示。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
label	ResourceStr	是	按钮文本内容。
options	[ButtonOptions](#参数名类型必填说明 label ResourceStr 是按钮文本内容。 options ButtonOptions 否配置按钮的显示样式。)	否	配置按钮的显示样式。

ButtonOptions对象说明

名称	类型	必填	描述
type	[ButtonType](#名称类型必填描述 type ButtonType 否描述按钮显示样式。默认值：ButtonType.Capsule元服务API：从API version 11开始，该接口支持在元服务中使用。 stateEffect boolean 否按钮按下时是否开启按压态显示效果，当设置为false时，按压效果关闭。默认值：true说明：当开启按压态显示效果，开发者设置状态样式时，会基于状态样式设置完成后的背景色再进行颜色叠加。元服务API：从API version 11开始，该接口支持在元服务中使用。 buttonStyle11+ ButtonStyleMode 否描述按钮的样式和重要程度。默认值：ButtonStyleMode.EMPHASIZED说明：按钮重要程度：强调按钮>普通按钮>文字按钮。元服务API：从API version 12开始，该接口支持在元服务中使用。 controlSize11+ ControlSize 否描述按钮的尺寸。默认值：ControlSize.NORMAL元服务API：从API version 12开始，该接口支持在元服务中使用。 role12+ ButtonRole 否描述按钮的角色。默认值：ButtonRole.NORMAL)	否	描述按钮显示样式。默认值：ButtonType.Capsule元服务API：从API version 11开始，该接口支持在元服务中使用。
stateEffect	boolean	否	按钮按下时是否开启按压态显示效果，当设置为false时，按压效果关闭。默认值：true说明：当开启按压态显示效果，开发者设置状态样式时，会基于状态样式设置完成后的背景色再进行颜色叠加。元服务API：从API version 11开始，该接口支持在元服务中使用。
buttonStyle11+	[ButtonStyleMode](#名称类型必填描述 type ButtonType 否描述按钮显示样式。默认值：ButtonType.Capsule元服务API：从API version 11开始，该接口支持在元服务中使用。 stateEffect boolean 否按钮按下时是否开启按压态显示效果，当设置为false时，按压效果关闭。默认值：true说明：当开启按压态显示效果，开发者设置状态样式时，会基于状态样式设置完成后的背景色再进行颜色叠加。元服务API：从API version 11开始，该接口支持在元服务中使用。 buttonStyle11+ ButtonStyleMode 否描述按钮的样式和重要程度。默认值：ButtonStyleMode.EMPHASIZED说明：按钮重要程度：强调按钮>普通按钮>文字按钮。元服务API：从API version 12开始，该接口支持在元服务中使用。 controlSize11+ ControlSize 否描述按钮的尺寸。默认值：ControlSize.NORMAL元服务API：从API version 12开始，该接口支持在元服务中使用。 role12+ ButtonRole 否描述按钮的角色。默认值：ButtonRole.NORMAL)	否	描述按钮的样式和重要程度。默认值：ButtonStyleMode.EMPHASIZED说明：按钮重要程度：强调按钮>普通按钮>文字按钮。元服务API：从API version 12开始，该接口支持在元服务中使用。
controlSize11+	[ControlSize](#名称类型必填描述 type ButtonType 否描述按钮显示样式。默认值：ButtonType.Capsule元服务API：从API version 11开始，该接口支持在元服务中使用。 stateEffect boolean 否按钮按下时是否开启按压态显示效果，当设置为false时，按压效果关闭。默认值：true说明：当开启按压态显示效果，开发者设置状态样式时，会基于状态样式设置完成后的背景色再进行颜色叠加。元服务API：从API version 11开始，该接口支持在元服务中使用。 buttonStyle11+ ButtonStyleMode 否描述按钮的样式和重要程度。默认值：ButtonStyleMode.EMPHASIZED说明：按钮重要程度：强调按钮>普通按钮>文字按钮。元服务API：从API version 12开始，该接口支持在元服务中使用。 controlSize11+ ControlSize 否描述按钮的尺寸。默认值：ControlSize.NORMAL元服务API：从API version 12开始，该接口支持在元服务中使用。 role12+ ButtonRole 否描述按钮的角色。默认值：ButtonRole.NORMAL)	否	描述按钮的尺寸。默认值：ControlSize.NORMAL元服务API：从API version 12开始，该接口支持在元服务中使用。
role12+	[ButtonRole](#名称类型必填描述 type ButtonType 否描述按钮显示样式。默认值：ButtonType.Capsule元服务API：从API version 11开始，该接口支持在元服务中使用。 stateEffect boolean 否按钮按下时是否开启按压态显示效果，当设置为false时，按压效果关闭。默认值：true说明：当开启按压态显示效果，开发者设置状态样式时，会基于状态样式设置完成后的背景色再进行颜色叠加。元服务API：从API version 11开始，该接口支持在元服务中使用。 buttonStyle11+ ButtonStyleMode 否描述按钮的样式和重要程度。默认值：ButtonStyleMode.EMPHASIZED说明：按钮重要程度：强调按钮>普通按钮>文字按钮。元服务API：从API version 12开始，该接口支持在元服务中使用。 controlSize11+ ControlSize 否描述按钮的尺寸。默认值：ControlSize.NORMAL元服务API：从API version 12开始，该接口支持在元服务中使用。 role12+ ButtonRole 否描述按钮的角色。默认值：ButtonRole.NORMAL)	否	描述按钮的角色。默认值：ButtonRole.NORMAL

属性

除支持通用属性外，还支持以下属性：

type

type(value: ButtonType)

设置Button样式。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[ButtonType](#参数名类型必填说明 value ButtonType 是 Button样式。默认值：ButtonType.Capsule)	是	Button样式。默认值：ButtonType.Capsule

参数名	类型	必填	说明
value	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	是	文本显示颜色。默认值：'#ffffff'

fontWeight

fontWeight(value: number | FontWeight | string)

设置文本的字体粗细。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	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	是	文本的字体样式。默认值：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 \| string	是	字体列表。默认字体'HarmonyOS Sans'，当前支持'HarmonyOS Sans'字体和注册自定义字体。

labelStyle10+

labelStyle(value: LabelStyle)

设置Button组件label文本和字体的样式。

元服务API： 从API version 11开始，该接口支持在元服务中使用

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[LabelStyle](#参数名类型必填说明 value LabelStyle 是 Button组件label文本和字体的样式。)	是	Button组件label文本和字体的样式。

buttonStyle11+

buttonStyle(value: ButtonStyleMode)

设置Button组件的样式和重要程度。

卡片能力： 从API version 11开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[ButtonStyleMode](#参数名类型必填说明 value ButtonStyleMode 是 Button组件的样式和重要程度。默认值:ButtonStyleMode.EMPHASIZED)	是	Button组件的样式和重要程度。默认值:ButtonStyleMode.EMPHASIZED

controlSize11+

controlSize(value: ControlSize)

设置Button组件的尺寸。

卡片能力： 从API version 11开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[ControlSize](#参数名类型必填说明 value ControlSize 是 Button组件的尺寸。默认值:ControlSize.NORMAL)	是	Button组件的尺寸。默认值:ControlSize.NORMAL

role12+

role(value: ButtonRole)

设置Button组件的角色。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[ButtonRole](#参数名类型必填说明 value ButtonRole 是设置Button组件的角色。默认值:ButtonRole.NORMAL)	是	设置Button组件的角色。默认值:ButtonRole.NORMAL

contentModifier12+

contentModifier(modifier: ContentModifier)

定制Button内容区的方法。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
modifier	[ContentModifier](#参数名类型必填说明 modifier ContentModifier 是在Button组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。)	是	在Button组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

ButtonType枚举说明

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	描述
Capsule	胶囊型按钮（圆角默认为高度的一半）。
Circle	圆形按钮。
Normal	普通按钮（默认不带圆角）。

按钮圆角通过通用属性borderRadius设置（不支持通过border接口设置圆角），且只支持设置参数为Length的圆角。
当按钮类型为Capsule时，borderRadius设置不生效，按钮圆角始终为宽、高中较小值的一半。
当按钮类型为Circle时，若同时设置了宽和高，则borderRadius不生效，且按钮半径为宽高中较小值的一半；若只设置宽、高中的一个，则borderRadius不生效，且按钮半径为所设宽或所设高值的一半；若不设置宽高，则borderRadius为按钮半径；若borderRadius的值为负，则borderRadius的值按照0处理。
按钮文本通过通用文本样式进行设置。
设置颜色渐变需先设置backgroundColor为透明色。

LabelStyle10+对象说明

元服务API： 从API version 11开始，该接口支持在元服务中使用

名称	参数类型	必填	描述
overflow	TextOverflow	否	设置label文本超长时的显示方式。文本截断是按字截断。例如，英文以单词为最小单位进行截断，若需要以字母为单位进行截断，可在字母间添加零宽空格。默认值：TextOverflow.Ellipsis
maxLines	number	否	设置label文本的最大行数。默认情况下，文本是自动折行的，如果指定此参数，则文本最多不会超过指定的行。如果有多余的文本，可以通过overflow来指定截断方式。默认值：1
minFontSize	number \| ResourceStr	否	设置label文本最小显示字号。需配合maxFontSize以及maxLines或布局大小限制使用。说明：minFontSize小于或等于0时，自适应字号不生效。
maxFontSize	number \| ResourceStr	否	设置label文本最大显示字号。需配合minFontSize以及maxLines或布局大小限制使用。
heightAdaptivePolicy	TextHeightAdaptivePolicy	否	设置label文本自适应高度的方式。默认值：TextHeightAdaptivePolicy.MAX_LINES_FIRST。
font	Font	否	设置label文本字体样式。默认值：默认值参考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](#参数名类型说明 label string Button的文本标签。 pressed boolean 指示是否按下Button。说明：此属性指示的是原本Button是否被按压，而非build出来的新组件。若新build出来的组件超过原本组件的大小，那么超出部分按压不触发。 triggerClick ButtonTriggerClickCallback 使用builder新构建出来组件的点击事件。)	使用builder新构建出来组件的点击事件。

ButtonTriggerClickCallback12+对象说明

定义ButtonConfiguration中使用的回调类型。

参数名	类型	必填	说明
xPos	number	是	点击位置x的坐标。
yPos	number	是	点击位置y的坐标。

事件

支持通用事件。

示例

示例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](#参数名类型必填描述 options CalendarOptions 否配置日历选择器组件的参数。)	否	配置日历选择器组件的参数。

属性

除支持通用属性外，还支持以下属性：

edgeAlign

edgeAlign(alignType: CalendarAlign, offset?: Offset)

设置选择器与入口组件的对齐方式。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
alignType	[CalendarAlign](#参数名类型必填说明 alignType CalendarAlign 是对齐方式类型。默认值：CalendarAlign .END offset Offset 否按照对齐类型对齐后，选择器相对入口组件的偏移量。默认值：{dx: 0, dy: 0})	是	对齐方式类型。默认值：CalendarAlign .END
offset	Offset	否	按照对齐类型对齐后，选择器相对入口组件的偏移量。默认值：{dx: 0, dy: 0}

textStyle

textStyle(value: PickerTextStyle)

入口区的文本颜色、字号、字体粗细。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	PickerTextStyle	是	设置入口区的文本颜色、字号、字体粗细。默认值：{color: '#ff182431',font: {size: '16fp',weight: FontWeight.Regular}}

事件

除支持通用事件，还支持以下事件：

onChange

onChange(callback: (value: Date) => void)

选择日期时触发该事件。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	Date	是	选中的日期值。

CalendarOptions对象说明

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	类型	必填	说明
hintRadius	number \| Resource	否	描述日期选中态底板样式。默认值：底板样式为圆形。说明：hintRadius为0，底板样式为直角矩形。hintRadius为0 ~ 16，底板样式为圆角矩形。hintRadius>=16，底板样式为圆形
selected	Date	否	设置选中项的日期。选中的日期未设置或日期格式不符合规范则为默认值。默认值：当前系统日期。

CalendarAlign枚举说明

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	描述
START	设置选择器与入口组件左对齐的对齐方式。
CENTER	设置选择器与入口组件居中对齐的对齐方式。
END	设置选择器与入口组件右对齐的对齐方式。

示例

ts 复制代码

// 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 })
  }
}

Checkbox

提供多选框组件，通常用于某选项的打开或关闭。

API version 11开始，Checkbox默认样式由圆角方形变为圆形。

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

无

接口

Checkbox(options?: CheckboxOptions)

多选框组件。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	描述
options	[CheckboxOptions](#参数名类型必填描述 options CheckboxOptions 否配置复选框的参数。)	否	配置复选框的参数。

CheckboxOptions对象说明

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	类型	必填	描述
name	string	否	用于指定多选框名称。
group	string	否	用于指定多选框所属群组的名称（即所属CheckboxGroup的名称）。说明：未配合使用CheckboxGroup组件时，此值无用。
indicatorBuilder12+	CustomBuilder	否	配置多选框的选中样式为自定义组件。自定义组件与Checkbox组件为中心点对齐显示。indicatorBuilder设置为undefined/null时，默认为indicatorBuilder未设置状态。

属性

除支持通用属性外，还支持以下属性：

select

select(value: boolean)

设置多选框是否选中。

从API version 10开始，该属性支持$$双向绑定变量。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	描述
value	boolean	是	多选框是否选中。默认值：false

selectedColor

selectedColor(value: ResourceColor)

设置多选框选中状态颜色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	描述
value	ResourceColor	是	多选框选中状态颜色。默认值：$r('sys.color.ohos_id_color_text_primary_activated')。异常值按照默认值处理。

unselectedColor10+

unselectedColor(value: ResourceColor)

设置多选框非选中状态边框颜色。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	描述
value	ResourceColor	是	多选框非选中状态边框颜色。默认值：'#33ffffff'。

mark10+

mark(value: MarkStyle)

设置多选框内部图标样式。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	描述
value	[MarkStyle](#参数名类型必填描述 value MarkStyle 是多选框内部图标样式。从API version 12开始，设置了indicatorBuilder时，按照indicatorBuilder中的内容显示。)	是	多选框内部图标样式。从API version 12开始，设置了indicatorBuilder时，按照indicatorBuilder中的内容显示。

shape11+

shape(value: CheckBoxShape)

设置CheckBox组件形状, 包括圆形和圆角方形。

卡片能力： 从API version 11开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	描述
value	[CheckBoxShape](#参数名类型必填描述 value CheckBoxShape 是 CheckBox组件形状, 包括圆形和圆角方形。默认值：CheckBoxShape.CIRCLE)	是	CheckBox组件形状, 包括圆形和圆角方形。默认值：CheckBoxShape.CIRCLE

contentModifier12+

contentModifier(modifier: ContentModifier)

定制CheckBox内容区的方法。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
modifier	[ContentModifier](#参数名类型必填说明 modifier ContentModifier 是在CheckBox组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。)	是	在CheckBox组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

事件

支持通用事件外，还支持以下事件：

onChange

onChange(callback: (value: boolean) => void)

当选中状态发生变化时，触发该回调。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	描述
value	boolean	是	返回true时，表示已选中。返回false时，表示未选中。

MarkStyle10+对象说明

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	类型	必填	默认值	描述
strokeColor	ResourceColor	否	Color.White	内部图标颜色。
size	Length	否	-	内部图标大小，单位vp。默认大小与多选框组件宽度设置值一致。不支持百分比形式设置。当设置为非法值时，按照默认值处理。
strokeWidth	Length	否	2	内部图标粗细，单位vp。不支持百分比形式设置。当设置为非法值时，按照默认值处理。

CheckBoxShape11+枚举类型说明

元服务API： 从API version 12开始，该接口支持在元服务中使用。

名称	值	说明
CIRCLE	0	圆形
ROUNDED_SQUARE	1	圆角方形

CheckBoxConfiguration12+对象说明

开发者需要自定义class实现ContentModifier接口。

参数名	类型	默认值	说明
name	string	-	当前多选框名称。
selected	boolean	false	指示多选框是否被选中。如果select属性没有设置默认值是false。如果设置select属性，此值与设置select属性的值相同。
triggerChange	Callback	-	触发多选框选中状态变化。

示例

示例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。

ts 复制代码

复制代码// 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](#参数名类型必填描述 options CheckboxGroupOptions 否配置多选框群组参数。)	否	配置多选框群组参数。

CheckboxGroupOptions对象说明

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	类型	必填	说明
group	string	否	群组名称。说明：多个相同群组名称的CheckboxGroup，仅第一个CheckboxGroup生效。

属性

除支持通用属性外，还支持以下属性：

selectAll

selectAll(value: boolean)

设置是否全选。若同组的Checkbox显式设置了select属性，则Checkbox的优先级高。

从API version 10开始，该属性支持$$双向绑定变量。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	boolean	是	是否全选。默认值：false

selectedColor

selectedColor(value: ResourceColor)

设置被选中或部分选中状态的颜色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ResourceColor	是	被选中或部分选中状态的颜色。默认值：$r('sys.color.ohos_id_color_text_primary_activated')异常值按照默认值处理。

unselectedColor10+

unselectedColor(value: ResourceColor)

设置非选中状态边框颜色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ResourceColor	是	非选中状态边框颜色。默认值：'#33ffffff'。

mark10+

mark(value: MarkStyle)

设置多选框内部图标样式。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[MarkStyle](#参数名类型必填说明 value MarkStyle 是多选框内部图标样式。)	是	多选框内部图标样式。

checkboxShape12

checkboxShape(value: CheckBoxShape)

设置CheckboxGroup组件形状，包括圆形和圆角方形。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	CheckBoxShape	是	设置CheckboxGroup组件形状，包括圆形和圆角方形。默认值:CheckBoxShape.CIRCLE。说明：CheckboxGroup组件形状按照设置显示。CheckboxGroup内所有没有单独设置shape类型的Checkbox形状和CheckboxGroup的保持一致。CheckboxGroup内有单独设置shape类型的Checkbox形状则优先于CheckboxGroup，按照设置形状显示。

事件

除支持通用事件外，还支持以下事件：

onChange

onChange(callback: (event: CheckboxGroupResult) => void )

CheckboxGroup的选中状态或群组内的Checkbox的选中状态发生变化时，触发回调。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
event	[CheckboxGroupResult](#参数名类型必填说明 event CheckboxGroupResult 是多选框群组的信息。)	是	多选框群组的信息。

CheckboxGroupResult对象说明

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	类型	描述
name	Array	群组内所有被选中的多选框名称。
status	[SelectStatus](#名称类型描述 name Array 群组内所有被选中的多选框名称。 status SelectStatus 选中状态。)	选中状态。

SelectStatus枚举说明

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	描述
All	群组多选择框全部选择。
Part	群组多选择框部分选择。
None	群组多选择框全部没有选择。

MarkStyle10+对象说明

名称	类型	必填	默认值	描述
strokeColor	ResourceColor	否	Color.White	内部图标颜色。
size	Length	否	-	内部图标大小，单位vp。默认大小与多选框群组组件宽度设置值一致。不支持百分比形式设置。当设置为非法值时，按照默认值处理。
strokeWidth	Length	否	2	内部图标粗细，单位vp。不支持百分比形式设置。当设置为非法值时，按照默认值处理。

ContainerSpan

Text组件的子组件，用于统一管理多个Span、ImageSpan的背景色及圆角弧度。

该组件从API Version 11开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

可以包含Span、ImageSpan 子组件。

接口

ContainerSpan()

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

属性

仅支持以下属性:

textBackgroundStyle

textBackgroundStyle(style: TextBackgroundStyle)

设置文本背景样式。子组件在不设置该属性时，将继承此属性值。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
style	[TextBackgroundStyle](#参数名类型必填说明 style TextBackgroundStyle 是文本背景样式。默认值：{color: Color.Transparent,radius: 0})	是	文本背景样式。默认值：{color: Color.Transparent,radius: 0}

TextBackgroundStyle对象说明

元服务API： 从API version 12开始，该接口支持在元服务中使用。

名称	参数类型	必填	描述
color	ResourceColor	否	文本背景色。
radius	Dimension \| BorderRadiuses	否	文本背景圆角。

事件

不支持通用事件。

示例

ts 复制代码

// 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](#参数名参数类型必填参数描述 options DataPanelOptions 是数据面板组件参数。)	是	数据面板组件参数。

DataPanelOptions对象说明

元服务API： 从API version 11开始，该接口支持在元服务中使用。

参数名	参数类型	必填	参数描述
values	number[]	是	数据值列表，最多包含9个数据，大于9个数据则取前9个数据。若数据值小于0则置为0。
max	number	否	- max大于0，表示数据的最大值。- max小于等于0，max等于value数组各项的和，按比例显示。默认值：100
type8+	[DataPanelType](#参数名参数类型必填参数描述 values number[] 是数据值列表，最多包含9个数据，大于9个数据则取前9个数据。若数据值小于0则置为0。 max number 否 - max大于0，表示数据的最大值。- max小于等于0，max等于value数组各项的和，按比例显示。默认值：100 type8+ DataPanelType 否数据面板的类型（不支持动态修改）。默认值：DataPanelType.Circle)	否	数据面板的类型（不支持动态修改）。默认值：DataPanelType.Circle

DataPanelType8+枚举说明

从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	描述
Line	线型数据面板。
Circle	环形数据面板。

属性

除支持通用属性外，还支持以下属性：

closeEffect

closeEffect(value: boolean)

设置关闭数据占比图表旋转动效和投影效果。若未设置trackShadow属性，则该属性控制投影效果的开关，开启投影的效果为投影的默认效果。若设置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 \| [LinearGradient](#参数名类型必填说明 value Array<ResourceColor	LinearGradient> 是各数据段颜色，ResourceColor为纯色，LinearGradient为渐变色。)>	是

trackBackgroundColor10+

trackBackgroundColor(value: ResourceColor)

设置底板颜色。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ResourceColor	是	底板颜色。默认值：'#08182431'，格式为十六进制ARGB值，前俩位代表透明度。

strokeWidth10+

strokeWidth(value: Length)

设置圆环粗细。数据面板的类型为DataPanelType.Line时该属性不生效。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	Length	是	圆环粗细。默认值：24单位：vp说明：设置小于0的值时，按默认值显示。

trackShadow10+

trackShadow(value: DataPanelShadowOptions)

设置投影样式。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[DataPanelShadowOptions](#参数名类型必填说明 value DataPanelShadowOptions 是投影样式。说明：设置null为不开启投影。)	是	投影样式。说明：设置null为不开启投影。

contentModifier12+

contentModifier(modifier: ContentModifier)

定制DataPanel内容区的方法。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
modifier	[ContentModifier](#参数名类型必填说明 modifier ContentModifier 是在DataPanel组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。)	是	在DataPanel组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

DataPanelShadowOptions10+对象说明

DataPanelShadowOptions继承自MultiShadowOptions，具有MultiShadowOptions的全部属性。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	参数类型	必填	描述
colors	Array<ResourceColor \| [LinearGradient](#名称参数类型必填描述 colors Array<ResourceColor	LinearGradient> 否各数据段投影的颜色。默认值：与valueColors值相同说明：若设置的投影颜色的个数少于数据段个数时，则显示的投影颜色的个数和设置的投影颜色个数一致。若设置的投影颜色的个数多于数据段个数时，则显示的投影颜色的个数和数据段个数一致。)>	否

LinearGradient10+对象说明

线性渐变颜色描述。

LinearGradient(colorStops: ColorStop[])

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	参数类型	必填	描述
colorStops	[ColorStop](#名称参数类型必填描述 colorStops ColorStop[] 是存储渐变颜色和渐变点。)[]	是	存储渐变颜色和渐变点。

ColorStop10+对象说明

颜色断点类型，用于描述渐进色颜色断点。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	参数类型	必填	描述
color	ResourceColor	是	颜色值。
offset	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

ts 复制代码

// 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 })
  }
}

DatePicker

日期选择器组件，用于根据指定日期范围创建日期滑动选择器。

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

无

接口

DatePicker(options?: DatePickerOptions)

根据指定范围的Date创建可以选择日期的滑动选择器。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	描述
options	[DatePickerOptions](#参数名类型必填描述 options DatePickerOptions 否配置日期选择器组件的参数。)	否	配置日期选择器组件的参数。

DatePickerOptions对象说明

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	类型	必填	说明
start	Date	否	指定选择器的起始日期。默认值：Date('1970-1-1')
end	Date	否	指定选择器的结束日期。默认值：Date('2100-12-31')
selected	Date	否	设置选中项的日期。默认值：当前系统日期从API version 10开始，该参数支持$$双向绑定变量。

异常情形说明:

异常情形	对应结果
起始日期晚于结束日期，选中日期未设置	起始日期、结束日期和选中日期都为默认值
起始日期晚于结束日期，选中日期早于起始日期默认值	起始日期、结束日期都为默认值，选中日期为起始日期默认值
起始日期晚于结束日期，选中日期晚于结束日期默认值	起始日期、结束日期都为默认值，选中日期为结束日期默认值
起始日期晚于结束日期，选中日期在起始日期与结束日期默认值范围内	起始日期、结束日期都为默认值，选中日期为设置的值
选中日期早于起始日期	选中日期为起始日期
选中日期晚于结束日期	选中日期为结束日期
起始日期晚于当前系统日期，选中日期未设置	选中日期为起始日期
结束日期早于当前系统日期，选中日期未设置	选中日期为结束日期
日期格式不符合规范，如'1999-13-32'	取默认值
起始日期或结束日期早于系统有效范围	起始日期或结束日期取起始日期默认值
起始日期或结束日期晚于系统有效范围	起始日期或结束日期取结束日期默认值
起始日期与结束日期同时早于系统有效范围	起始日期与结束日期取系统有效范围最早日期
起始日期与结束日期同时晚于系统有效范围	起始日期与结束日期取系统有效范围最晚日期

系统日期范围：1900-1-31 ~ 2100-12-31

选中日期会在起始日期与结束日期异常处理完成后再进行异常情形判断处理

属性

除支持通用属性外，还支持以下属性：

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](#ff182431’,font: {size: ‘14fp’,weight: FontWeight.Regular}})	是	所有选项中最上和最下两个选项的文本颜色、字号、字体粗细。默认值：{color: '#ff182431',font: {size: '14fp',weight: FontWeight.Regular}}

textStyle10+

textStyle(value: PickerTextStyle)

设置所有选项中除了最上、最下及选中项以外的文本样式。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[PickerTextStyle](#ff182431’,font: {size: ‘16fp’,weight: FontWeight.Regular}})	是	所有选项中除了最上、最下及选中项以外的文本颜色、字号、字体粗细。默认值：{color: '#ff182431',font: {size: '16fp',weight: FontWeight.Regular}}

selectedTextStyle10+

selectedTextStyle(value: PickerTextStyle)

设置选中项的文本样式。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[PickerTextStyle](#ff007dff’,font: {size: ‘20vp’,weight: FontWeight.Medium}})	是	选中项的文本颜色、字号、字体粗细。默认值：{color: '#ff007dff',font: {size: '20vp',weight: FontWeight.Medium}}

PickerTextStyle10+类型说明

元服务API： 从API version 11开始，该接口支持在元服务中使用。

参数名	参数类型	必填	参数描述
color	ResourceColor	否	文本颜色。
font	Font	否	文本样式，picker只支持字号、字体粗细的设置。

事件

除支持通用事件外，还支持以下事件：

onChange(deprecated)

onChange(callback: (value: DatePickerResult) => void)

选择日期时触发该事件。

从API version 8 开始支持，从 API version 10 开始废弃，建议使用onDateChange。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[DatePickerResult](#参数名类型必填说明 value 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	选中日期的日。

示例

ts 复制代码

复制代码// 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

属性

除支持通用属性外，还支持以下属性：

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	是	分割线颜色。默认值：'#33182431'

strokeWidth

strokeWidth(value: number | string)

设置分割线的宽度。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	number \| string	是	分割线宽度。默认值：1px单位：vp说明：分割线的宽度不支持百分比设置。优先级低于通用属性height，超过通用属性设置大小时，按照通用属性进行裁切。

lineCap

lineCap(value: LineCapStyle)

设置分割线的端点样式。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	LineCapStyle	是	分割线的端点样式。默认值：LineCapStyle.Butt

示例

ts 复制代码

// 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支持负数。

属性

除支持通用属性外，还支持以下属性：

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+ \| LinearGradient11+ \| Array<[ResourceColor \| LinearGradient11+ \| 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	是	环形量规图的环形厚度。默认值：4单位：vp说明：设置小于0的值时，按默认值显示。不支持百分比。

description11+

description(value: CustomBuilder)

设置说明内容。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	CustomBuilder	是	说明内容。说明：@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](#参数名类型必填说明 value GaugeShadowOptions 是阴影样式。说明：阴影颜色与圆环颜色一致。设置null为不开启投影。)	是	阴影样式。说明：阴影颜色与圆环颜色一致。设置null为不开启投影。

indicator11+

indicator(value: GaugeIndicatorOptions)

设置指针样式。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[GaugeIndicatorOptions](#参数名类型必填说明 value GaugeIndicatorOptions 是指针样式。说明：设置null则不显示指针。)	是	指针样式。说明：设置null则不显示指针。

privacySensitive12+

privacySensitive(isPrivacySensitiveMode: Optional)

设置隐私敏感。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
isPrivacySensitiveMode	[Optional]	是	设置隐私敏感，隐私模式下Gauge指针指向0位置，最大值最小值文本将被遮罩，量程显示灰色或者底色。说明：设置null则不敏感。需要卡片框架支持。

contentModifier12+

contentModifier(modifier: ContentModifier)

定制Slider内容区的方法。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
modifier	[ContentModifier](#参数名类型必填说明 modifier ContentModifier 是在Gauge组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。)	是	在Gauge组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

GaugeShadowOptions11+对象说明

GaugeShadowOptions继承自MultiShadowOptions，具有MultiShadowOptions的全部属性。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

GaugeIndicatorOptions11+对象说明

元服务API： 从API version 12开始，该接口支持在元服务中使用。

名称	参数类型	必填	描述
icon	Resource	否	图标资源路径。说明：不配置则使用默认的三角形样式指针。支持使用svg格式的图标，若使用其他格式，则使用默认的三角形样式指针。
space	Dimension	否	指针距离圆环外边的间距。(不支持百分比)默认值：8单位：vp说明：对于默认的三角形样式指针，间距为黑色三角形到圆环外边的间距。若设置值小于0，则使用默认值。若设置值大于圆环半径，则使用默认值。

GaugeConfiguration12+对象说明

开发者需要自定义class实现ContentModifier接口。

参数名	类型	说明
value	number	当前数据值。
min	number	当前数据段最小值。
max	number	当前数据段最大值。

Image

Image为图片组件，常用于在应用中显示图片。Image支持加载PixelMap、ResourceStr和DrawableDescriptor类型的数据源，支持png、jpg、jpeg、bmp、svg、webp、gif和heif类型的图片格式。

该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

使用快捷组合键对Image组件复制时，Image组件必须处于获焦状态。Image组件默认不获焦，需将focusable属性设置为true，即可使用TAB键将焦点切换到组件上，再将focusOnTouch属性设置为true，即可实现点击获焦。

图片设置为svg图源时，当前支持的标签是svg、rect、circle、ellipse、path、line、polyline、polygon、feFlood、feBlend、feColorMatrix、feGaussianBlur、feComposite、filter、mask和use。

需要权限

使用网络图片时，需要申请权限ohos.permission.INTERNET。具体申请方式请参考声明权限。

子组件

无

接口

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 \| ResourceStr\| DrawableDescriptor	是	图片的数据源，支持本地图片和网络图片，引用方式请参考加载图片资源。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：file:///。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。3. 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。传入AnimatedDrawableDescriptor类型可播放PixelMap数组动画。说明： - ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。- ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。- ArkTS卡片上不支持 PixelMap类型。- 加载本地图片过程中，如果对图片进行修改或者替换，可能会引起应用崩溃。因此需要覆盖图片文件时，应该先删除该文件再重新创建一个同名文件。- 网络图片必须支持RFC 9113标准，否则会导致加载失败。- 如果下载的网络图片大于10MB或一次下载的网络图片数量较多，建议使用HTTP工具提前预下载，提高图片加载性能，方便应用侧管理数据。- 如果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 \| ResourceStr\| DrawableDescriptor	是	图片的数据源，支持本地图片和网络图片，引用方式请参考加载图片资源。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：file:///。用于读取本应用安装目录下files文件夹下的图片资源。需要保证目录包路径下的文件有可读权限。Resource格式可以跨包/跨模块访问资源文件，是访问本地图片的推荐方式。3. 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。传入AnimatedDrawableDescriptor类型可播放PixelMap数组动画。说明： - ArkTS卡片上支持gif图片格式动效，但仅在显示时播放一次。- ArkTS卡片上不支持http://等网络相关路径前缀和file://路径前缀的字符串。- ArkTS卡片上不支持 PixelMap类型。- 加载本地图片过程中，如果对图片进行修改或者替换，可能会引起应用崩溃。因此需要覆盖图片文件时，应该先删除该文件再重新创建一个同名文件。- 网络图片必须支持RFC 9113标准，否则会导致加载失败。- 如果下载的网络图片大于10MB或一次下载的网络图片数量较多，建议使用HTTP工具提前预下载，提高图片加载性能，方便应用侧管理数据。- 如果SVG图片没有原生大小，需要给Image组件设置宽高，否则不显示。- 如果SVG图片通过image标签引用本地其他图片，被引用的图片不支持svg格式和gif格式。
imageAIOptions	ImageAIOptions	是	给组件设置一个AI分析选项，通过此项可配置分析类型或绑定一个分析控制器。

属性

属性的详细使用指导请参考添加属性。除支持通用属性外，还支持以下属性：

alt

alt(value: string | Resource | PixelMap)

设置图片加载时显示的占位图。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	string \| Resource \| PixelMap12+	是	加载时显示的占位图，支持本地图片（png、jpg、bmp、svg、gif和heif类型）,支持PixelMap类型图片，不支持网络图片。默认值：null

objectFit

objectFit(value: ImageFit)

设置图片的填充效果。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ImageFit	是	图片的填充效果。默认值：ImageFit.Cover

objectRepeat

objectRepeat(value: ImageRepeat)

设置图片的重复样式，从中心点向两边重复，剩余空间不足放下一张图片时会截断。svg类型图源不支持该属性。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ImageRepeat	是	图片的重复样式。默认值：ImageRepeat.NoRepeat

interpolation

interpolation(value: ImageInterpolation)

设置图片的插值效果，即缓解图片在缩放时的锯齿问题。svg类型图源不支持该属性。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[ImageInterpolation](#参数名类型必填说明 value ImageInterpolation 是图片的插值效果。默认值：ImageInterpolation.Low)	是	图片的插值效果。默认值：ImageInterpolation.Low

renderMode

renderMode(value: ImageRenderMode)

设置图片的渲染模式。svg类型图源不支持该属性。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[ImageRenderMode](#参数名类型必填说明 value ImageRenderMode 是图片的渲染模式为原色或黑白。默认值：ImageRenderMode.Original)	是	图片的渲染模式为原色或黑白。默认值：ImageRenderMode.Original

sourceSize

sourceSize(value: { width: number; height: number })

设置图片解码尺寸。仅在目标尺寸小于图源尺寸时生效。svg类型图源和PixelMap资源不支持该属性。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力： 从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时设置该属性不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	boolean	是	图片是否跟随系统语言方向。默认值：false

fitOriginalSize

fitOriginalSize(value: boolean)

设置图片的显示尺寸是否跟随图源尺寸。图片组件尺寸未设置时，其显示尺寸是否跟随图源尺寸。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	boolean	是	图片的显示尺寸是否跟随图源尺寸默认值：false

fillColor

fillColor(value: ResourceColor)

设置填充颜色，设置后填充颜色会覆盖在图片上。仅对svg图源生效，设置后会替换svg图片的填充颜色。如需对png图片进行修改颜色，可以使用colorFilter。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ResourceColor	是	设置填充颜色。

autoResize

autoResize(value: boolean)

设置图片解码过程中是否对图源自动缩放。降采样解码时图片的部分信息丢失，因此可能会导致图片质量的下降（如：出现锯齿），这时可以选择把autoResize设为false，按原图尺寸解码，提升显示效果，但会增加内存占用。

原图尺寸和显示尺寸不匹配时，图片都会出现些许的失真、模糊。最佳清晰度配置建议：

图片缩小显示时：.autoResize(false) + .interpolation(.Medium)

图片放大显示时：.interpolation(.High)

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

卡片能力： 从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时设置该属性不生效。

卡片能力： 从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时设置该属性不生效。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	CopyOptions	是	图片是否可复制。默认值：CopyOptions.None

colorFilter9+

colorFilter(value: ColorFilter | DrawingColorFilter)

为图像设置颜色滤镜效果。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ColorFilter \| DrawingColorFilter12+	是	1. 给图像设置颜色滤镜效果，入参为一个的4x5的RGBA转换矩阵。矩阵第一行表示R（红色）的向量值，第二行表示G（绿色）的向量值，第三行表示B（蓝色）的向量值，第四行表示A（透明度）的向量值，4行分别代表不同的RGBA的向量值。当矩阵对角线值为1，其余值为0时，保持图片原有色彩。计算规则：如果输入的滤镜矩阵为：

draggable9+

draggable(value: boolean)

设置组件默认拖拽效果。不能和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属性同时使用，两者同时设置时overlay中CustomBuilder属性将失效。该特性依赖设备能力。

分析图像要求是静态非矢量图，即svg、gif等图像类型不支持分析，支持传入PixelMap进行分析，目前仅支持RGBA_8888类型，使用方式见示例。

alt占位图不支持分析，objectRepeat属性仅在ImageRepeat.NoRepeat下支持分析，隐私遮罩属性obscured打开时不支持分析。

基于完整原始图像进行分析，设置clip、margin、borderRadius、position和objectFit属性导致图像显示不完整，或使用renderMode设置蒙层，仍基于完整原始图像进行分析。 copyOption属性不影响AI分析功能。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
enable	boolean	是	组件支持AI分析，设置为true时，组件可进行AI分析。默认值：false

resizable11+

resizable(value: ResizableOptions)

设置图像拉伸时可调整大小的图像选项。拉伸对拖拽缩略图以及占位图有效。

设置合法的 ResizableOptions 时，objectRepeat 属性设置不生效。

当设置 top +bottom 大于原图的高或者 left + right 大于原图的宽时 ResizableOptions 属性设置不生效。

当组件的参数类型为AnimatedDrawableDescriptor时设置该属性不生效。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[ResizableOptions](#参数名类型必填说明 value ResizableOptions 是图像拉伸时可调整大小的图像选项。)	是	图像拉伸时可调整大小的图像选项。

privacySensitive12+

privacySensitive(supported: boolean)

设置是否支持卡片敏感隐私信息。

卡片能力： 从API version 12开始，该接口支持在ArkTS卡片中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
supported	boolean	是	是否支持卡片敏感隐私信息。默认值为false，当设置为true时，隐私模式下图片将显示为半透明底板样式。说明：设置null则不敏感。进入隐私模式需要卡片框架支持。

dynamicRangeMode12+

dynamicRangeMode(value: DynamicRangeMode)

设置期望展示的图像动态范围。

该属性仅在手机设备上生效。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[DynamicRangeMode](#参数名类型必填说明 value DynamicRangeMode 是图像显示的动态范围。默认值：dynamicRangeMode.Standard)	是	图像显示的动态范围。默认值：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](#参数名类型说明 slice EdgeWidths 边框宽度类型，用于描述组件边框不同方向的宽度。说明：只有当bottom和right同时大于0时，该属性生效。)	边框宽度类型，用于描述组件边框不同方向的宽度。说明：只有当bottom和right同时大于0时，该属性生效。

EdgeWidths参数说明

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	类型	必填	说明
top	Length	否	图片顶部拉伸时保持不变距离。默认值：0单位：vp
right	Length	否	图片右部拉伸时保持不变距离。默认值：0单位：vp
bottom	Length	否	图片底部拉伸时保持不变距离。默认值：0单位：vp
left	Length	否	图片左部拉伸时保持不变距离。默认值：0单位：vp

DynamicRangeMode12+

期望展示的图像动态范围。

名称	描述
High	不受限动态范围，最大限度进行图片提亮。
Constraint	受限动态范围，受限进行图片提亮。
Standard	标准动态范围，不进行图片提亮。

事件

除支持通用事件外，还支持以下事件：

onComplete

onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number,contentWidth: number, contentHeight: number, contentOffsetX: number, contentOffsetY: number }) => void)

图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。

当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

卡片能力： 从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时该事件不触发。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
callback	[ImageErrorCallback](#参数名类型必填说明 callback ImageErrorCallback 是图片加载异常时触发的回调。)	是	图片加载异常时触发的回调。

onFinish

onFinish(event: () => void)

当加载的源文件为带动效的svg格式图片时，svg动效播放完成时会触发这个回调。如果动效为无限循环动效，则不会触发这个回调。

仅支持svg格式的图片。当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

ImageErrorCallback9+

type ImageErrorCallback = (error: ImageError) => void

图片加载异常时触发的回调。

当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

参数名	类型	必填	说明
error	[ImageError](#参数名类型必填说明 error ImageError 是图片加载异常时触发回调的返回对象。)	是	图片加载异常时触发回调的返回对象。

ImageError9+

图片加载异常时触发回调的返回对象。

当组件的参数类型为AnimatedDrawableDescriptor时该事件不触发。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

参数名	类型	必填	说明
componentWidth	number	是	组件的宽。单位：像素
componentHeight	number	是	组件的高。单位：像素
message	string	是	报错信息。

ImageAnimator

提供帧动画组件来实现逐帧播放图片的能力，可以配置需要播放的图片列表，每张图片可以配置时长。

该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

无

接口

ImageAnimator()

卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

属性

除支持通用属性外，还支持以下属性：

images

images(value: Array)

设置图片帧信息集合。不支持动态更新。

卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	Array<[ImageFrameInfo](#参数名类型必填说明 value Array<ImageFrameInfo> 是设置图片帧信息集合。每一帧的帧信息(ImageFrameInfo)包含图片路径、图片大小、图片位置和图片播放时长信息，详见ImageFrameInfo属性说明。默认值：[])>	是	设置图片帧信息集合。每一帧的帧信息(ImageFrameInfo)包含图片路径、图片大小、图片位置和图片播放时长信息，详见ImageFrameInfo属性说明。默认值：[]

state

state(value: AnimationStatus)

控制播放状态。

卡片能力： 从API version 10开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	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	是	当前播放方向下，动画开始前和结束后的状态。默认值：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 \| Resource9+ \| PixelMap12+	是	图片路径，图片格式为svg，png和jpg，从API Version9开始支持Resource类型的路径，从API version 12开始支持PixelMap类型。卡片能力：从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

事件

除支持通用事件外，还支持以下事件：

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

ImageSpan

Text、ContainerSpan组件的子组件，用于显示行内图片。

该组件从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

无

接口

ImageSpan(value: ResourceStr | PixelMap)

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	参数类型	必填	参数描述
value	ResourceStr \| PixelMap	是	图片的数据源，支持本地图片和网络图片。当使用相对路径引用图片资源时，例如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，通用属性方法支持尺寸设置、背景设置、边框设置

alt12+

alt(value: PixelMap)

设置图片加载时显示的占位图。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	PixelMap	是	加载时显示的占位图，支持PixelMap类型。默认值：null

verticalAlign

verticalAlign(value: ImageSpanAlignment)

设置图片基于文本的对齐方式。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	[ImageSpanAlignment](#参数名类型必填说明 value ImageSpanAlignment 是图片基于文本的对齐方式。默认值：ImageSpanAlignment.BOTTOM)	是	图片基于文本的对齐方式。默认值：ImageSpanAlignment.BOTTOM

objectFit

objectFit(value: ImageFit)

设置图片的缩放类型。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ImageFit	是	图片的缩放类型。默认值：ImageFit.Cover

ImageSpanAlignment

元服务API： 从API version 11开始，该接口支持在元服务中使用。

名称	描述
TOP	图片上边沿与行上边沿对齐。
CENTER	图片中间与行中间对齐。
BOTTOM	图片下边沿与行下边沿对齐。
BASELINE	图片下边沿与文本BaseLine对齐。

事件

通用事件仅支持点击事件。还支持以下事件：

onComplete12+

onComplete(callback: ImageCompleteCallback)

图片数据加载成功和解码成功时均触发该回调，返回成功加载的图片尺寸。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
callback	[ImageCompleteCallback](#参数名类型必填说明 callback ImageCompleteCallback 是图片数据加载成功和解码成功时触发的回调。)	是	图片数据加载成功和解码成功时触发的回调。

onError12+

onError(callback: ImageErrorCallback)

图片加载异常时触发该回调。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
callback	ImageErrorCallback	是	图片加载异常时触发的回调。

ImageCompleteCallback12+

type ImageCompleteCallback = (result: ImageLoadResult) => void

图片加载异常时触发的回调。

参数名	类型	必填	说明
result	[ImageLoadResult](#参数名类型必填说明 result ImageLoadResult 是图片数据加载成功和解码成功触发回调时返回的对象。)	是	图片数据加载成功和解码成功触发回调时返回的对象。

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时有效。

LoadingProgress

用于显示加载动效的组件。

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

子组件

无

接口

LoadingProgress()

创建加载进展组件。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

属性

除支持通用属性外，还支持以下属性：

color

color(value: ResourceColor)

设置加载进度条前景色。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	ResourceColor	是	加载进度条的前景色。默认值：API version 10及以下：'#99666666'API version 11及以上：'#ff666666'

enableLoading10+

enableLoading(value: boolean)

设置LoadingProgress动画显示或者不显示。LoadingProgress动画不显示时，该组件依旧占位。通用属性Visibility.Hidden隐藏的是包括border、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)

定制LoadingProgress内容区的方法。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
modifier	[ContentModifier](#参数名类型必填说明 modifier ContentModifier 是在LoadingProgress组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。)	是	在LoadingProgress组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

事件

支持通用事件。

LoadingProgressConfiguration12+对象说明

开发者需要自定义class实现ContentModifier接口。

参数名	类型	默认值	说明
enableloading	boolean	true	LoadingProgress动画是否显示。默认值：true。

Marquee

跑马灯组件，用于滚动展示一段单行文本。仅当文本内容宽度超过跑马灯组件宽度时滚动，不超过时不滚动。

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

为了不影响滚动帧率，建议在滚动类组件中Marquee的个数不超过4个，或者使用Text组件的TextOverflow.MARQUEE替代。

子组件

无

接口

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、fontSize、fontWeight、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	是	跑马灯组件属性更新后，跑马灯的滚动策略。默认值: 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开始，该接口支持在元服务中使用。

UI.ArkUI.Full

参数：

参数名	类型	必填	说明
modifier	[ContentModifier](#参数名类型必填说明 modifier ContentModifier 是在LoadingProgress组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。)	是	在LoadingProgress组件上，定制内容区的方法。modifier: 内容修改器，开发者需要自定义class实现ContentModifier接口。

事件

支持通用事件。

LoadingProgressConfiguration12+对象说明

开发者需要自定义class实现ContentModifier接口。

参数名	类型	默认值	说明
enableloading	boolean	true	LoadingProgress动画是否显示。默认值：true。

Marquee

跑马灯组件，用于滚动展示一段单行文本。仅当文本内容宽度超过跑马灯组件宽度时滚动，不超过时不滚动。

[外链图片转存中...(img-RJlRRmcz-1734520393323)]

该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

为了不影响滚动帧率，建议在滚动类组件中Marquee的个数不超过4个，或者使用Text组件的TextOverflow.MARQUEE替代。

子组件

无

接口

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、fontSize、fontWeight、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	是	跑马灯组件属性更新后，跑马灯的滚动策略。默认值: 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