1# Marquee
2
3The **Marquee** component is used to display a scrolling piece of text. The text is scrolled only when its width exceeds the width of the **Marquee** component.
4
5
6>  **NOTE**
7>
8>  This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
9>
10>  To ensure that scrolling frame rates are not affected, it is recommended that the number of **Marquee** components in a scroll container does not exceed four, or alternatively, use the [Text](ts-basic-components-text.md) component's [TextOverflow.MARQUEE](ts-appendix-enums.md#textoverflow) as a substitute.
11
12## Child Components
13
14Not supported
15
16
17## APIs
18
19Marquee(value: { start: boolean, step?: number, loop?: number, fromStart?: boolean, src: string })
20
21**Widget capability**: This API can be used in ArkTS widgets since API version 9.
22
23**Atomic service API**: This API can be used in atomic services since API version 11.
24
25**System capability**: SystemCapability.ArkUI.ArkUI.Full
26
27**Parameters**
28
29| Name| Type| Mandatory| Description|
30| -------- | -------- | -------- | -------- |
31| value | { start: boolean, step?: number, loop?: number, fromStart?: boolean, src: string } | Yes| Parameters of the marquee.<br>**start**: whether to start scrolling.<br>**NOTE**<br>This parameter cannot be used to restart scrolling that has been completed.<br>- **step**: scrolling step. If the step is greater than the text width, the default value is taken.<br>Default value: **6**, in vp<br>- **loop**: number of times the marquee will scroll. If the value is less than or equal to **0**, the marquee will scroll continuously.<br>Default value: **-1**<br>**NOTE**<br>Regardless of the value, the marquee scrolls only once on an ArkTS widget.<br>- **fromStart**: whether the text scrolls from the start.<br>Default value: **true**<br>- **src**: text to scroll.|
32
33## Attributes
34
35In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
36
37### fontColor
38
39fontColor(value: ResourceColor)
40
41Sets the font color.
42
43**Widget capability**: This API can be used in ArkTS widgets since API version 9.
44
45**Atomic service API**: This API can be used in atomic services since API version 11.
46
47**System capability**: SystemCapability.ArkUI.ArkUI.Full
48
49**Parameters**
50
51| Name| Type                                      | Mandatory| Description      |
52| ------ | ------------------------------------------ | ---- | ---------- |
53| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Font color.|
54
55### fontSize
56
57fontSize(value: number | string | Resource)
58
59Sets the text size.
60
61**Widget capability**: This API can be used in ArkTS widgets since API version 9.
62
63**Atomic service API**: This API can be used in atomic services since API version 11.
64
65**System capability**: SystemCapability.ArkUI.ArkUI.Full
66
67**Parameters**
68
69| Name| Type                                                        | Mandatory| Description                                                        |
70| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
71| value  | [Resource](ts-types.md#resource) \| number \| string | Yes  | Font size. If **fontSize** is of the number type, the unit fp is used. The default font size is 16 fp. This parameter cannot be set in percentage.|
72
73### fontWeight
74
75fontWeight(value: number | FontWeight | string)
76
77Sets the font weight. If the value is too large, the text may be clipped depending on the font.
78
79**Widget capability**: This API can be used in ArkTS widgets since API version 9.
80
81**Atomic service API**: This API can be used in atomic services since API version 11.
82
83**System capability**: SystemCapability.ArkUI.ArkUI.Full
84
85**Parameters**
86
87| Name| Type                                                        | Mandatory| Description                                                        |
88| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
89| value  | [FontWeight](ts-appendix-enums.md#fontweight) \| number \| string | Yes  | Font weight. For the number type, the value range is [100, 900], at an interval of 100. The default value is **400**. A larger value indicates a heavier font weight. For the string type, only strings that represent a number, for example, **"400"**, and the following enumerated values of **FontWeight** are supported: **"bold"**, **"bolder"**, **"lighter"**, **"regular"**, and **"medium"**.<br>Default value: **FontWeight.Normal**|
90
91### fontFamily
92
93fontFamily(value: string | Resource)
94
95Sets the font family.
96
97**Widget capability**: This API can be used in ArkTS widgets since API version 9.
98
99**Atomic service API**: This API can be used in atomic services since API version 11.
100
101**System capability**: SystemCapability.ArkUI.ArkUI.Full
102
103**Parameters**
104
105| Name| Type                                                | Mandatory| Description                                                        |
106| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ |
107| value  | [Resource](ts-types.md#resource) \| string | Yes  | Font family. Default font: **'HarmonyOS Sans'**<br>The 'HarmonyOS Sans' font and [registered custom fonts](../js-apis-font.md) are supported for applications.<br>Only the 'HarmonyOS Sans' font is supported for widgets.|
108
109### allowScale
110
111allowScale(value: boolean)
112
113Sets whether to allow text to scale.
114
115**Widget capability**: This API can be used in ArkTS widgets since API version 9.
116
117**Atomic service API**: This API can be used in atomic services since API version 11.
118
119**System capability**: SystemCapability.ArkUI.ArkUI.Full
120
121**Parameters**
122
123| Name| Type   | Mandatory| Description                                |
124| ------ | ------- | ---- | ------------------------------------ |
125| value  | boolean | Yes  | Whether to allow text to scale.<br>Default value: **false**<br>**NOTE**<br>This parameter is effective only when **fontSize** is in fp units.|
126
127### marqueeUpdateStrategy<sup>12+</sup>
128
129marqueeUpdateStrategy(value: MarqueeUpdateStrategy)
130
131Sets the scrolling strategy for the marquee after its attributes are updated. (This attribute takes effect when the marquee is in the playing state and the text content width exceeds the width of the marquee component.)
132
133**Atomic service API**: This API can be used in atomic services since API version 12.
134
135**System capability**: SystemCapability.ArkUI.ArkUI.Full
136
137**Parameters**
138
139| Name| Type   | Mandatory| Description                                |
140| ------ | ------- | ---- | ------------------------------------ |
141| value |[MarqueeUpdateStrategy](ts-appendix-enums.md#marqueeupdatestrategy12)| Yes| Scrolling strategy of the marquee after its attributes are updated.<br>Default value: **MarqueeUpdateStrategy.DEFAULT**|
142
143## Events
144
145### onStart
146
147onStart(event: () =&gt; void)
148
149Called when the marquee text changes or starts scrolling.
150
151**Widget capability**: This API can be used in ArkTS widgets since API version 9.
152
153**Atomic service API**: This API can be used in atomic services since API version 11.
154
155**System capability**: SystemCapability.ArkUI.ArkUI.Full
156
157### onBounce
158
159onBounce(event: () =&gt; void)
160
161Triggered when the marquee has reached the end. This event will be triggered for multiple times if the **loop** attribute is not set to **1**.
162
163**Widget capability**: This API can be used in ArkTS widgets since API version 9.
164
165**Atomic service API**: This API can be used in atomic services since API version 11.
166
167**System capability**: SystemCapability.ArkUI.ArkUI.Full
168
169### onFinish
170
171onFinish(event: () =&gt; void)
172
173Triggered when the marquee has finished the number of scrolling times set by the **loop** attribute.
174
175**Widget capability**: This API can be used in ArkTS widgets since API version 9.
176
177**Atomic service API**: This API can be used in atomic services since API version 11.
178
179**System capability**: SystemCapability.ArkUI.ArkUI.Full
180
181## Example
182
183
184```ts
185// xxx.ets
186@Entry
187@Component
188struct MarqueeExample {
189  @State start: boolean = false
190  @State src: string = ''
191  @State marqueeText: string = 'Running Marquee'
192  private fromStart: boolean = true
193  private step: number = 10
194  private loop: number = Number.POSITIVE_INFINITY
195  controller: TextClockController = new TextClockController()
196  convert2time(value: number): string{
197    let date = new Date(Number(value+'000'));
198    let hours = date.getHours().toString().padStart(2, '0');
199    let minutes = date.getMinutes().toString().padStart(2, '0');
200    let seconds = date.getSeconds().toString().padStart(2, '0');
201    return hours+ ":" + minutes + ":" + seconds;
202  }
203
204  build() {
205    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
206      Marquee({
207        start: this.start,
208        step: this.step,
209        loop: this.loop,
210        fromStart: this.fromStart,
211        src: this.marqueeText + this.src
212      })
213        .marqueeUpdateStrategy(MarqueeUpdateStrategy.PRESERVE_POSITION)
214        .width(300)
215        .height(80)
216        .fontColor('#FFFFFF')
217        .fontSize(48)
218        .fontWeight(700)
219        .backgroundColor('#182431')
220        .margin({ bottom: 40 })
221        .onStart(() => {
222          console.info('Marquee animation complete onStart')
223        })
224        .onBounce(() => {
225          console.info('Marquee animation complete onBounce')
226        })
227        .onFinish(() => {
228          console.info('Marquee animation complete onFinish')
229        })
230      Button('Start')
231        .onClick(() => {
232          this.start = true
233          // Start the text clock.
234          this.controller.start()
235        })
236        .width(120)
237        .height(40)
238        .fontSize(16)
239        .fontWeight(500)
240        .backgroundColor('#007DFF')
241      TextClock({ timeZoneOffset: -8, controller: this.controller })
242        .format('hms')
243        .onDateChange((value: number) => {
244          this.src = this.convert2time(value);
245        })
246        .margin(20)
247        .fontSize(30)
248    }
249    .width('100%')
250    .height('100%')
251  }
252}
253```
254
255![marquee](figures/marquee.gif)
256