鸿蒙开发：如何实现文本跑马灯效果

原创

程序员一鸣

发布于 2025-03-28 10:42:10

750

文章被收录于专栏：HarmonyOS点石成金HarmonyOS点石成金

前言

本文基于Api13

跑马灯的场景非常常见，在日常的开发中常见于消息、广告及公告通知，内容从左到右或者从右到左进行滚动播出，在鸿蒙开发中，实现起来可以说是非常简单，一个属性便可以搞定。

比如给定一段内容，让它从右往左进行滚动播出，效果如下：

鸿蒙当中，直接给文本组件，设置textOverflow属性，让overflow的值为TextOverflow.MARQUEE即可：

Text(this.message)
        .textOverflow({ overflow: TextOverflow.MARQUEE })
        .border({ width: 1, color: Color.Gray })
        .padding({ top: 10, bottom: 10 })
        .margin({ left: 10, right: 10 })

虽然说，TextOverflow.MARQUEE实现了一个跑马灯效果，但是仍然存在一些问题，比如，我想控制一下播放的速度，或者我想暂停滚动，再或者，我想从左往右滚动等等，有很多阻碍性问题存在。

为了解决这些问题，鸿蒙给我们提供了一个，专门用于跑马灯的组件Marquee，解决Text跑马灯的痛点。

Marquee

Marquee是一个专门的跑马灯组件，用于滚动展示一段单行文本，自身有五个属性可供使用。

属性	类型	概述
start	boolean	控制跑马灯是否进入播放状态。
step	number	滚动动画文本滚动步长，可用于控制速度。
loop	number	设置重复滚动的次数，小于等于零时无限循环
fromStart	boolean	设置文本从头开始滚动或反向滚动
src	string	需要滚动的文本

除此之外，我们也可以通过文本属性也更改内容的样式。

属性	类型	概述
fontColor	ResourceColor	设置字体颜色
fontSize	Length	设置字体大小
fontWeight	number /FontWeight /string	设置文本的字体粗细，设置过大可能会在不同字体下有截断
fontFamily	string/Resource	设置字体列表
allowScale	boolean	设置是否允许文本缩放
marqueeUpdateStrategy	MarqueeUpdateStrategy	跑马灯组件属性更新后，跑马灯的滚动策略。(当跑马灯为播放状态，且文本内容宽度超过跑马灯组件宽度时，该属性生效。)

简单案例

@Entry
@Component
struct DemoPage {
  @State message: string = "我是一段比较长的内容，主要用于测试跑马灯的效果，看看如何进行滚动"
  @State start: boolean = true
  @State fromStart: boolean = true

  build() {
    Column() {
      Marquee({
        start: this.start,
        fromStart: this.fromStart,
        step: 2,
        src: this.message
      })

      Row() {
        Button("开始")
          .onClick(() => {
            this.start = true
          })
        Button("暂停")
          .onClick(() => {
            this.start = false
          })
        Button("切换方向")
          .onClick(() => {
            this.fromStart = !this.fromStart
          })
      }.margin({ top: 10 })
    }
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center)
  }
}

Marquee除了可以实现跑马灯的功能，还有一些事件的监听，比如当滚动的文本内容变化或者开始滚动时触发onStart，完成一次滚动时触发，若循环次数不为1，则该事件会多次触发的监听onBounce，以及滚动全部循环次数完成时触发回调监听onFinish。