鸿蒙5.0版开发：ArkTS组件-基础组件（Marquee）

往期鸿蒙全套实战文章必看：

• 鸿蒙开发核心知识点，看这篇文章就够了

• 最新版！鸿蒙HarmonyOS Next应用开发实战学习路线

• 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南

• 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）

---

Marquee

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

说明：

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

子组件

无

接口

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

示例

// 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%')
  }
}
ts

看完三件事❤️

• 如果你觉得这篇内容对你还蛮有帮助，我想邀请你帮我三个小忙：
• 点赞，转发，有你们的 『点赞和评论』，才是我创造的动力。
• 关注作者，不定期分享原创知识。
• 同时可以期待后续文章ing🚀。