1# Marquee
2
3跑马灯组件，用于滚动展示一段单行文本。仅当文本内容宽度超过跑马灯组件宽度时滚动，不超过时不滚动。
4
5
6>  **说明：**
7>
8>  该组件从API Version 8开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
9>
10>  为了不影响滚动帧率，建议在滚动类组件中Marquee的个数不超过4个，或者使用[Text](ts-basic-components-text.md)组件的[TextOverflow.MARQUEE](ts-appendix-enums.md#textoverflow)替代。
11
12## 子组件
13
14无
15
16
17## 接口
18
19Marquee(value: { start: boolean, step?: number, loop?: number, fromStart?: boolean, src: string })
20
21**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
22
23**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
24
25**系统能力：** SystemCapability.ArkUI.ArkUI.Full
26
27**参数：**
28
29| 参数名 | 类型 | 必填 | 说明 |
30| -------- | -------- | -------- | -------- |
31| value | { start: boolean, step?: number, loop?: number, fromStart?: boolean, src: string } | 是 | 配置跑马灯组件的参数。<br/>-&nbsp;start：控制跑马灯是否进入播放状态。<br/>**说明：**<br/>有限的滚动次数播放完毕后，不可以通过改变start重置滚动次数重新开始播放。<br/>-&nbsp;step：滚动动画文本滚动步长，当step大于Marquee的文本宽度时，取默认值。<br/>默认值：6，单位vp<br/>-&nbsp;loop：设置重复滚动的次数，小于等于零时无限循环。<br/>默认值：-1<br/>**说明：**<br/>ArkTS卡片上该参数设置任意值都仅在可见时滚动一次。<br/>-&nbsp;fromStart：设置文本从头开始滚动或反向滚动。<br/>默认值：true<br/>-&nbsp;src：需要滚动的文本。 |
32
33## 属性
34
35除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性：
36
37### fontColor
38
39fontColor(value: ResourceColor)
40
41设置字体颜色。
42
43**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
44
45**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
46
47**系统能力：** SystemCapability.ArkUI.ArkUI.Full
48
49**参数：**
50
51| 参数名 | 类型                                       | 必填 | 说明       |
52| ------ | ------------------------------------------ | ---- | ---------- |
53| value  | [ResourceColor](ts-types.md#resourcecolor) | 是   | 字体颜色。 |
54
55### fontSize
56
57fontSize(value: Length)
58
59设置字体大小。
60
61**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
62
63**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
64
65**系统能力：** SystemCapability.ArkUI.ArkUI.Full
66
67**参数：**
68
69| 参数名 | 类型                         | 必填 | 说明                                                         |
70| ------ | ---------------------------- | ---- | ------------------------------------------------------------ |
71| value  | [Length](ts-types.md#length) | 是   | 字体大小。fontSize为number类型时，使用fp单位。字体默认大小16fp。不支持设置百分比字符串。 |
72
73### fontWeight
74
75fontWeight(value: number | FontWeight | string)
76
77设置文本的字体粗细，设置过大可能会在不同字体下有截断。
78
79**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
80
81**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
82
83**系统能力：** SystemCapability.ArkUI.ArkUI.Full
84
85**参数：**
86
87| 参数名 | 类型                                                         | 必填 | 说明                                                         |
88| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
89| value  | number&nbsp;\|&nbsp;[FontWeight](ts-appendix-enums.md#fontweight)&nbsp;\|&nbsp;string | 是   | 文本的字体粗细，number类型取值[100,&nbsp;900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如"400"，以及"bold"、"bolder"、"lighter"、"regular"、"medium"，分别对应FontWeight中相应的枚举值。<br/>默认值：FontWeight.Normal |
90
91### fontFamily
92
93fontFamily(value: string | Resource)
94
95设置字体列表。
96
97**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
98
99**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
100
101**系统能力：** SystemCapability.ArkUI.ArkUI.Full
102
103**参数：**
104
105| 参数名 | 类型                                                 | 必填 | 说明                                                         |
106| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
107| value  | string&nbsp;\|&nbsp;[Resource](ts-types.md#resource) | 是   | 字体列表。默认字体'HarmonyOS Sans'。<br>应用当前支持'HarmonyOS Sans'字体和[注册自定义字体](../js-apis-font.md)。<br>卡片当前仅支持'HarmonyOS Sans'字体。 |
108
109### allowScale
110
111allowScale(value: boolean)
112
113设置是否允许文本缩放。
114
115**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
116
117**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
118
119**系统能力：** SystemCapability.ArkUI.ArkUI.Full
120
121**参数：**
122
123| 参数名 | 类型    | 必填 | 说明                                 |
124| ------ | ------- | ---- | ------------------------------------ |
125| value  | boolean | 是   | 是否允许文本缩放。<br/>默认值：false<br/>**说明：**<br/>仅当fontSize为fp单位时生效。 |
126
127### marqueeUpdateStrategy<sup>12+</sup>
128
129marqueeUpdateStrategy(value: MarqueeUpdateStrategy)
130
131跑马灯组件属性更新后，跑马灯的滚动策略。(当跑马灯为播放状态，且文本内容宽度超过跑马灯组件宽度时，该属性生效。)
132
133**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
134
135**系统能力：** SystemCapability.ArkUI.ArkUI.Full
136
137**参数：**
138
139| 参数名 | 类型    | 必填 | 说明                                 |
140| ------ | ------- | ---- | ------------------------------------ |
141| value |[MarqueeUpdateStrategy](ts-appendix-enums.md#marqueeupdatestrategy12) | 是 | 跑马灯组件属性更新后，跑马灯的滚动策略。<br/>默认值: MarqueeUpdateStrategy.DEFAULT |
142
143## 事件
144
145### onStart
146
147onStart(event:&nbsp;()&nbsp;=&gt;&nbsp;void)
148
149当滚动的文本内容变化或者开始滚动时触发回调。
150
151**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
152
153**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
154
155**系统能力：** SystemCapability.ArkUI.ArkUI.Full
156
157### onBounce
158
159onBounce(event:&nbsp;()&nbsp;=&gt;&nbsp;void)
160
161完成一次滚动时触发，若循环次数不为1，则该事件会多次触发。
162
163**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
164
165**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
166
167**系统能力：** SystemCapability.ArkUI.ArkUI.Full
168
169### onFinish
170
171onFinish(event:&nbsp;()&nbsp;=&gt;&nbsp;void)
172
173滚动全部循环次数完成时触发回调。
174
175**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。
176
177**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
178
179**系统能力：** SystemCapability.ArkUI.ArkUI.Full
180
181## 示例
182
183该示例通过设置start、step、loop、fromStart、src、marqueeUpdateStrategy展示了跑马灯内容动态更新时运行的效果。
184
185```ts
186// xxx.ets
187@Entry
188@Component
189struct MarqueeExample {
190  @State start: boolean = false
191  @State src: string = ''
192  @State marqueeText: string = 'Running Marquee'
193  private fromStart: boolean = true
194  private step: number = 10
195  private loop: number = Number.POSITIVE_INFINITY
196  controller: TextClockController = new TextClockController()
197  convert2time(value: number): string{
198    let date = new Date(Number(value+'000'));
199    let hours = date.getHours().toString().padStart(2, '0');
200    let minutes = date.getMinutes().toString().padStart(2, '0');
201    let seconds = date.getSeconds().toString().padStart(2, '0');
202    return hours+ ":" + minutes + ":" + seconds;
203  }
204
205  build() {
206    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
207      Marquee({
208        start: this.start,
209        step: this.step,
210        loop: this.loop,
211        fromStart: this.fromStart,
212        src: this.marqueeText + this.src
213      })
214        .marqueeUpdateStrategy(MarqueeUpdateStrategy.PRESERVE_POSITION)
215        .width('300vp')
216        .height('80vp')
217        .fontColor('#FFFFFF')
218        .fontSize('48fp')
219        .fontWeight(700)
220        .backgroundColor('#182431')
221        .margin({ bottom: '40vp' })
222        .onStart(() => {
223          console.info('Succeeded in completing the onStart callback of marquee animation')
224        })
225        .onBounce(() => {
226          console.info('Succeeded in completing the onBounce callback of marquee animation')
227        })
228        .onFinish(() => {
229          console.info('Succeeded in completing the onFinish callback of marquee animation')
230        })
231      Button('Start')
232        .onClick(() => {
233          this.start = true
234          // 启动文本时钟
235          this.controller.start()
236        })
237        .width('120vp')
238        .height('40vp')
239        .fontSize('16fp')
240        .fontWeight(500)
241        .backgroundColor('#007DFF')
242      TextClock({ timeZoneOffset: -8, controller: this.controller })
243        .format('hms')
244        .onDateChange((value: number) => {
245          this.src = this.convert2time(value);
246        })
247        .margin('20vp')
248        .fontSize('30fp')
249    }
250    .width('100%')
251    .height('100%')
252  }
253}
254```
255
256![marquee](figures/marquee.gif)