文档管理中心

Marquee

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

跑马灯组件,用于滚动展示一段单行文本,支持自定义滚动速度、方向、循环次数等。仅当文本内容宽度大于等于跑马灯组件宽度时滚动,否则不滚动。适用于需要在有限空间内展示较长文本的场景,如新闻标题滚动、通知公告、广告轮播等,可以有效节省界面空间并吸引用户注意。

说明

该组件从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

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

对于Marquee组件动态帧率的场景,可以使用MarqueeDynamicSyncScene接口实现。

在文本宽度小于跑马灯组件宽度时,使用属性动画实现滚动。

子组件

接口

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Marquee(options: MarqueeOptions)

创建跑马灯组件。

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

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

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

参数:

展开
参数名 类型 必填 说明
options MarqueeOptions18+ 配置跑马灯组件的参数。

MarqueeOptions18+对象说明

Phone18+PC/2in118+Tablet18+TV19+Wearable18+

Marquee初始化参数。

说明

为规范匿名对象的定义,API 18版本修改了此处的元素定义。其中,保留了历史匿名对象的起始版本信息,会出现外层元素@since版本号高于内层元素版本号的情况,但这不影响接口的使用。

模型约束: 此接口仅可在Stage模型下使用。

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

展开
名称 类型 只读 可选 说明
start8+ boolean

控制跑马灯是否进入播放状态。

true:播放;false:不播放。

说明:

当loop参数设置为大于0的有限次数且播放完毕后,不可以通过改变start参数重置滚动次数重新开始播放。

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

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

step8+ number

滚动动画的文本步长。

取值范围:[0, 文本宽度],当step大于Marquee的文本宽度时,取默认值。

默认值:6

单位:vp

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

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

loop8+ number

设置重复滚动的次数,小于等于零时无限循环。

默认值:-1

说明:

ArkTS卡片上该参数设置任意值都仅在可见时滚动一次。当设置为大于0的有限次数且播放完毕后,不可以通过改变start参数重置滚动次数重新开始播放。

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

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

fromStart8+ boolean

设置文本的滚动方向。

true:表示文本从头部位置开始正向滚动;false:表示文本反向滚动。

默认值:true

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

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

src8+ string

需要滚动的文本。

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

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

spacing23+ LengthMetrics

两轮跑马灯之间的间距。当LengthMetrics对象的unit属性为LengthUnit.PERCENT时,当前设置不生效,按默认值处理。

默认值:跑马灯组件宽度。

卡片能力: 从API version 23开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 23开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

delay23+ number

设置两轮滚动之间的延迟时间。

默认值:0

取值范围:[0, +∞),设置的值小于0时等价于设置0。

单位:毫秒

卡片能力: 从API version 23开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API version 23开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

属性

除支持通用属性外,还支持以下属性:

fontColor

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontColor(value: ResourceColor)

设置字体颜色。未通过该接口设置时,默认字体颜色为'#e6182431',表示深灰色(不透明度约为90%),Wearable设备上默认字体颜色为'#c5ffffff',表示白色(不透明度约为77%)。

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

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

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

参数:

展开
参数名 类型 必填 说明
value ResourceColor 字体颜色。

fontSize

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontSize(value: Length)

设置字体大小。

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

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

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

参数:

展开
参数名 类型 必填 说明
value Length

字体大小。fontSize为number类型时,使用fp单位。字体默认大小16fp。不支持设置百分比字符串。

Wearable设备上默认值:15fp

说明:

配合allowScale属性使用时,需设置为fp单位。

fontWeight

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontWeight(value: number | FontWeight | string)

设置文本的字体粗细,设置过大可能会在不同字体下有截断。未通过该接口设置时,默认字体粗细为FontWeight.Normal(正常粗细,对应数值400)。

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

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

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

参数:

展开
参数名 类型 必填 说明
value number | FontWeight | string

文本的字体粗细

number类型取值[100, 900],取值间隔为100,默认为400,取值越大,字体越粗。string类型仅支持number类型取值的字符串形式,例如“400”,以及“bold”、“bolder”、“lighter”、“regular”、“medium”,分别对应FontWeight中相应的枚举值。设置过大可能会在不同字体下有截断。

传入超出取值范围的值时取默认值。传入不符合间隔要求的值时,若设置fontWeightConfigs的enableVariableFontWeight为true,使用传入值;若设置为false,使用默认值。

fontFamily

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

fontFamily(value: string | Resource)

设置字体列表。

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

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

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

参数:

展开
参数名 类型 必填 说明
value string | Resource

字体列表。默认字体'HarmonyOS Sans'。

应用当前支持'HarmonyOS Sans'字体和注册自定义字体loadFontSync

卡片当前仅支持'HarmonyOS Sans'字体。

allowScale

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

allowScale(value: boolean)

设置是否允许文本缩放。未通过该接口设置时,默认不允许文本缩放。

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

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

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

参数:

展开
参数名 类型 必填 说明
value boolean

是否允许文本缩放。

true:允许文本缩放;false:不允许文本缩放。

说明:

仅当fontSize为fp单位时生效。

marqueeUpdateStrategy12+

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

marqueeUpdateStrategy(value: MarqueeUpdateStrategy)

跑马灯组件属性更新后,跑马灯的滚动策略。(当跑马灯为播放状态,且文本内容宽度大于等于跑马灯组件宽度时,该属性生效。)未通过该接口设置时,默认使用MarqueeUpdateStrategy.DEFAULT。

使用场景:

  • MarqueeUpdateStrategy.DEFAULT:适用于内容更新后希望以默认策略重新开始滚动展示的场景。
  • MarqueeUpdateStrategy.PRESERVE_POSITION:适用于内容动态更新时希望保持当前滚动位置继续滚动的场景,如实时时钟、股价等动态内容展示。

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

模型约束: 此接口仅可在Stage模型下使用。

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

参数:

展开
参数名 类型 必填 说明
value MarqueeUpdateStrategy 跑马灯组件属性更新后,跑马灯的滚动策略。

事件

onStart

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onStart(event: () => void)

当滚动的文本内容变化或者开始滚动时触发回调。

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

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

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

参数:

展开
参数名 类型 必填 说明
event () => void 当滚动的文本内容变化或者开始滚动时的回调。

onBounce

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onBounce(event: () => void)

完成一次完整滚动时触发,若循环次数不为1,则该事件会多次触发。

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

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

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

参数:

展开
参数名 类型 必填 说明
event () => void 完成一次完整滚动时触发的回调。

onFinish

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

onFinish(event: () => void)

滚动全部循环次数完成时触发回调。

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

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

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

参数:

展开
参数名 类型 必填 说明
event () => void 滚动全部循环次数完成时的回调。

onStop

Phone26.0.0+PC/2in126.0.0+Tablet26.0.0+TV26.0.0+Wearable26.0.0+

onStop(event: Callback<void>| undefined)

跑马灯滚动结束或停止时触发回调。

跑马灯停止表示跑马灯将从开始位置,重新开始循环,不包含暂停场景,暂停不会触发该回调。

起始版本: 26.0.0

卡片能力: 从API版本26.0.0开始,该接口支持在ArkTS卡片中使用。

元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。

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

模型约束: 此接口仅可在Stage模型下使用。

参数:

展开
参数名 类型 必填 说明
event Callback<void>| undefined

跑马灯滚动结束或停止时触发回调。

设置为undefined时不会执行回调。

示例

示例1(跑马灯内容动态更新)

该示例展示了跑马灯内容动态更新时的运行效果,主要涉及start、step、loop、fromStart、src等属性以及marqueeUpdateStrategy属性的设置。

从API version 23开始,MarqueeOptions新增spacing、delay属性。

收起
自动换行
深色代码主题
复制
  1. import { LengthMetrics } from '@kit.ArkUI';
  2. // xxx.ets
  3. @Entry
  4. @Component
  5. struct MarqueeExample {
  6. @State start: boolean = false;
  7. @State src: string = '';
  8. @State marqueeText: string = 'Running Marquee';
  9. private fromStart: boolean = true;
  10. private step: number = 10;
  11. private loop: number = Number.POSITIVE_INFINITY;
  12. controller: TextClockController = new TextClockController();
  13. convertToTime(value: number): string {
  14. let date = new Date(Number(value + '000'));
  15. let hours = date.getHours().toString().padStart(2, '0');
  16. let minutes = date.getMinutes().toString().padStart(2, '0');
  17. let seconds = date.getSeconds().toString().padStart(2, '0');
  18. return hours + ':' + minutes + ':' + seconds;
  19. }
  20. build() {
  21. Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
  22. Marquee({
  23. start: this.start,
  24. step: this.step,
  25. loop: this.loop,
  26. fromStart: this.fromStart,
  27. src: this.marqueeText + this.src,
  28. spacing: LengthMetrics.vp(300), // 从API version 23开始,新增spacing属性
  29. delay: 0, // 从API version 23开始,新增delay属性
  30. })
  31. .marqueeUpdateStrategy(MarqueeUpdateStrategy.PRESERVE_POSITION)
  32. .width('300vp')
  33. .height('80vp')
  34. .fontColor('#FFFFFF')
  35. .fontSize('48fp')
  36. .allowScale(true) // 当fontSize为‘fp’单位且想要Marquee组件文本跟随系统字体大小缩放,可以设置该属性为true
  37. .fontWeight(700)
  38. .fontFamily('HarmonyOS Sans') // 不想跟随主题字体可设置该属性为默认字体'HarmonyOS Sans'
  39. .backgroundColor('#182431')
  40. .margin({ bottom: '40vp' })
  41. .onStart(() => {
  42. console.info('Succeeded in completing the onStart callback of marquee animation');
  43. })
  44. .onBounce(() => {
  45. console.info('Succeeded in completing the onBounce callback of marquee animation');
  46. })
  47. .onFinish(() => {
  48. console.info('Succeeded in completing the onFinish callback of marquee animation');
  49. })
  50. Button('Start')
  51. .onClick(() => {
  52. this.start = true;
  53. // 启动文本时钟
  54. this.controller.start();
  55. })
  56. .width('120vp')
  57. .height('40vp')
  58. .fontSize('16fp')
  59. .fontWeight(500)
  60. .backgroundColor('#007DFF')
  61. TextClock({ timeZoneOffset: -8, controller: this.controller })
  62. .format('hms')
  63. .onDateChange((value: number) => {
  64. this.src = this.convertToTime(value);
  65. })
  66. .margin('20vp')
  67. .fontSize('30fp')
  68. }
  69. .width('100%')
  70. .height('100%')
  71. }
  72. }

示例2(设置跑马灯停止回调)

该示例通过变更跑马灯状态来触发onStop回调,回调触发后使停止计数器numberStop的值加1。

从API版本26.0.0开始,新增onStop接口。

收起
自动换行
深色代码主题
复制
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct MarqueeStop4 {
  5. @State change: boolean = true;
  6. @State scrollDirection: string = '正向滚动';
  7. @State marqueeText: string =
  8. 'This is the text with the text overflow set marquee This is the text with the text overflow set marquee This is the text with the text overflow set marquee';
  9. @State numberStart: number = 0;
  10. @State numberBounce: number = 0;
  11. @State numberStop: number = 0;
  12. build() {
  13. Scroll() {
  14. Column() {
  15. Row() {
  16. Column() {
  17. Text('Start')
  18. Text(this.numberStart.toString())
  19. }.margin(10)
  20. Column() {
  21. Text('Bounce')
  22. Text(this.numberBounce.toString())
  23. }.margin(10)
  24. Column() {
  25. Text('Stop')
  26. Text(this.numberStop.toString())
  27. }.margin(10)
  28. }.margin(20)
  29. Marquee({
  30. start: true,
  31. step: 6,
  32. loop: 1,
  33. fromStart: this.change,
  34. src: this.marqueeText
  35. })
  36. .marqueeUpdateStrategy(MarqueeUpdateStrategy.DEFAULT)
  37. .margin(20)
  38. .onStart(() => {
  39. // '收到状态: START';
  40. this.numberStart++;
  41. })
  42. .onBounce(() => {
  43. // '收到状态: BOUNCE';
  44. this.numberBounce++;
  45. })
  46. .onStop(() => {
  47. // '收到状态: STOP';
  48. this.numberStop++;
  49. })
  50. Button(this.scrollDirection.toString()).onClick(() => {
  51. if (this.change) {
  52. this.change = false;
  53. this.scrollDirection = '反向滚动';
  54. } else {
  55. this.change = true;
  56. this.scrollDirection = '正向滚动';
  57. }
  58. }).margin(20)
  59. }.height(600).width('100%').padding({ left: 35, right: 35, top: 35 })
  60. }
  61. }
  62. }

在 API参考 中进行搜索
请输入您想要搜索的关键词