HarmonyOS 6 Marquee组件使用示例文档

组件基础信息

1. 组件定义

Marquee是HarmonyOS提供的文本跑马灯滚动组件，用于实现单行文本自动横向滚动效果，适用于公告栏、新闻头条、状态提示、动态信息展示等需要文字滚动的场景，支持控制滚动速度、循环次数、起始位置及动态更新内容。

2. 核心能力

• 控制文本滚动启停、速度、循环次数
• 支持文本滚动策略、字体缩放、字体样式自定义
• 提供滚动开始、回弹、结束生命周期回调
• 支持动态修改滚动文本，实时更新效果
• 可与TextClock等组件联动展示动态数据

核心API

1. 组件接口

Marquee(options:MarqueeOptions)

创建跑马灯组件实例，通过MarqueeOptions配置基础参数。

2. MarqueeOptions 配置项

3. 核心属性

4. 生命周期事件

完整代码示例

1. 依赖导入

import{LengthMetrics}from'@kit.ArkUI';

导入基础UI工具类，支持组件尺寸单位相关能力。

2. 组件状态与变量定义

@Entry@Componentstruct MarqueeExample{@Statestart:boolean=false;// 控制跑马灯启停@Statesrc:string='';// 动态拼接的时间文本@StatemarqueeText:string='Running Marquee';// 固定前缀文本privatefromStart:boolean=true;// 从文本开头滚动privatestep:number=10;// 滚动步长（速度）privateloop:number=Number.POSITIVE_INFINITY;// 无限循环controller:TextClockController=newTextClockController();// 时钟控制器

• 使用@State装饰器定义响应式变量，修改后自动刷新UI
• loop设置为无限循环，实现持续滚动效果
• TextClockController用于联动控制时钟启动

3. 时间格式化工具函数

convert2time(value:number):string{letdate=newDate(Number(value+'000'));lethours=date.getHours().toString().padStart(2,'0');letminutes=date.getMinutes().toString().padStart(2,'0');letseconds=date.getSeconds().toString().padStart(2,'0');returnhours+":"+minutes+":"+seconds;}

将时间戳转换为HH:mm:ss格式字符串，用于动态更新跑马灯文本。

4. 页面构建与组件布局

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('300vp').height('80vp').fontColor('#FFFFFF').fontSize('48fp').allowScale(true)// 允许跟随系统字体大小缩放.fontWeight(700).fontFamily('HarmonyOS Sans')// 固定字体，不跟随主题.backgroundColor('#182431').margin({bottom:'40vp'})// 生命周期监听.onStart(()=>{console.info('Succeeded in completing the onStart callback of marquee animation');}).onBounce(()=>{console.info('Succeeded in completing the onBounce callback of marquee animation');}).onFinish(()=>{console.info('Succeeded in completing the onFinish callback of marquee animation');})// 启动按钮Button('Start').onClick(()=>{this.start=true;// 启动跑马灯this.controller.start();// 启动时钟})// 文本时钟组件TextClock({timeZoneOffset:-8,controller:this.controller}).format('hms').onDateChange((value:number)=>{this.src=this.convert2time(value);// 时间变化时更新跑马灯文本})}.width('100%').height('100%')}

运行效果如图：

核心逻辑

1. 跑马灯文本动态更新

   • 固定文本Running Marquee+ 实时时间src拼接展示
   • TextClock时间变化时触发onDateChange，自动更新跑马灯内容

2. 滚动策略

   • marqueeUpdateStrategy(MarqueeUpdateStrategy.PRESERVE_POSITION)：文本更新时保持当前滚动位置，不重置滚动起点

3. 字体适配

   • allowScale(true)：fontSize使用fp单位，跟随系统字体大小缩放
   • fontFamily('HarmonyOS Sans')：固定使用系统默认字体，不随主题切换

4. 双组件联动

   • 点击Start按钮同时启动跑马灯和TextClock
   • 时钟时间实时同步到跑马灯文本，实现动态滚动效果

5. 生命周期日志

   • 滚动开始、边界回弹、滚动完成时输出日志，便于调试

功能效果说明

1. 初始状态：跑马灯静止，显示默认文本Running Marquee
2. 点击启动：
   • 跑马灯开始无限滚动
   • TextClock启动计时，时间实时追加到跑马灯文本后
3. 滚动表现：
   • 文本滚动速度由step=10控制
   • 文本更新不中断滚动位置，平滑展示动态时间
   • 字体支持系统缩放，样式固定清晰
4. 日志输出：滚动生命周期事件触发时打印日志

总结

Marquee组件是HarmonyOS中实现文本滚动的核心组件，支持启停控制、速度调节、动态文本、生命周期监听、字体适配、多组件联动等完整能力。本文档示例代码可直接运行，通过与TextClock联动实现了动态滚动时钟效果，覆盖了跑马灯组件90%以上的常用场景，是HarmonyOS 6开发中的标准实践方案。

如果这篇文章对你有帮助，欢迎点赞、收藏、关注，你的支持是持续创作的动力