1# SymbolGlyph
2
3The **SymbolGlyph** component represents a symbol glyph.
4
5>  **NOTE**
6>
7>  This component is supported since API version 11. Updates will be marked with a superscript to indicate their earliest API version.
8
9## Child Components
10
11Not supported
12
13## APIs
14
15SymbolGlyph(value?: Resource)
16
17**Widget capability**: This API can be used in ArkTS widgets since API version 12.
18
19**Atomic service API**: This API can be used in atomic services since API version 12.
20
21**System capability**: SystemCapability.ArkUI.ArkUI.Full
22
23**Parameters**
24
25| Name| Type| Mandatory| Description|
26| -------- | -------- | -------- | -------- |
27| value | [Resource](ts-types.md#resource)| No| Resource of the **SymbolGlyph** component, for example, **$r('sys.symbol.ohos_wifi')**.|
28
29>  **NOTE**
30>
31>  The resources referenced in **$r('sys.symbol.ohos_wifi')** are preset in the system. The **SymbolGlyph** component supports only the preset symbol resources. If unsupported resources are referenced, an exception occurs.
32
33## Attributes
34
35The [universal attributes](ts-universal-attributes-size.md) are supported. With regard to text attributes, only the following attributes are supported.
36
37### fontColor
38
39fontColor(value: Array<ResourceColor>)
40
41Sets the color of the **SymbolGlyph** component.
42
43**Widget capability**: This API can be used in ArkTS widgets since API version 12.
44
45**Atomic service API**: This API can be used in atomic services since API version 12.
46
47**System capability**: SystemCapability.ArkUI.ArkUI.Full
48
49**Parameters**
50
51| Name| Type| Mandatory| Description |
52| ------ | ---- | ---- | ----- |
53| value  | Array\<[ResourceColor](ts-types.md#resourcecolor)\> | Yes  | Color of the **SymbolGlyph** component.<br> Default value: depending on the rendering strategy|
54
55### fontSize
56
57fontSize(value: number | string | Resource)
58
59Sets the size of the **SymbolGlyph** component.
60
61The display size of the symbol glyph is controlled by the **fontSize** setting. Once **width** or **height** is specified, other universal attributes will only affect the size of the component's placeholder, not the symbol glyph itself.
62
63**Widget capability**: This API can be used in ArkTS widgets since API version 12.
64
65**Atomic service API**: This API can be used in atomic services since API version 12.
66
67**System capability**: SystemCapability.ArkUI.ArkUI.Full
68
69**Parameters**
70
71| Name| Type| Mandatory| Description |
72| ------ | ---- | ---- | ----- |
73| value  | number \| string \| [Resource](ts-types.md#resource) | Yes  | Size of the **SymbolGlyph** component.<br>Default value: system default value|
74
75### fontWeight
76
77fontWeight(value: number | FontWeight | string)
78
79Sets the font weight of the **SymbolGlyph** component. For the number type, the value ranges from 100 to 900, at an interval of 100. A larger value indicates a heavier font weight. The default value is **400**. For the string type, only strings of the number type are supported, for example, **"400"**, **"bold"**, **"bolder"**, **"lighter"**, **"regular"**, and **"medium"**, which correspond to the enumerated values in **FontWeight**.
80
81The **sys.symbol.ohos_lungs** icon does not support font weight setting.
82
83**Widget capability**: This API can be used in ArkTS widgets since API version 12.
84
85**Atomic service API**: This API can be used in atomic services since API version 12.
86
87**System capability**: SystemCapability.ArkUI.ArkUI.Full
88
89**Parameters**
90
91| Name| Type                                                        | Mandatory| Description                                               |
92| ------ | ------------------------------------------------------------ | ---- | --------------------------------------------------- |
93| value  | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | Yes  | Font weight of the **SymbolGlyph** component.<br>Default value: **FontWeight.Normal**|
94
95### renderingStrategy
96
97renderingStrategy(value: SymbolRenderingStrategy)
98
99Sets the rendering strategy of the **SymbolGlyph** component.
100
101**Widget capability**: This API can be used in ArkTS widgets since API version 12.
102
103**Atomic service API**: This API can be used in atomic services since API version 12.
104
105**System capability**: SystemCapability.ArkUI.ArkUI.Full
106
107**Parameters**
108
109| Name| Type| Mandatory| Description |
110| ------ | ---- | ---- | ----- |
111| value  | [SymbolRenderingStrategy](#symbolrenderingstrategy11) | Yes  | Rendering strategy of the **SymbolGlyph** component.<br>Default value: **SymbolRenderingStrategy.SINGLE**|
112
113The figure below shows the effects of different rendering strategies.
114
115![renderingStrategy](figures/renderingStrategy.png)
116
117### effectStrategy
118
119effectStrategy(value: SymbolEffectStrategy)
120
121Sets the effect strategy of the **SymbolGlyph** component.
122
123**Widget capability**: This API can be used in ArkTS widgets since API version 12.
124
125**Atomic service API**: This API can be used in atomic services since API version 12.
126
127**System capability**: SystemCapability.ArkUI.ArkUI.Full
128
129**Parameters**
130
131| Name| Type| Mandatory| Description |
132| ------ | ---- | ---- | ----- |
133| value  | [SymbolEffectStrategy](#symboleffectstrategy11) | Yes  | Effect strategy of the **SymbolGlyph** component.<br>Default value: **SymbolEffectStrategy.NONE**|
134
135### symbolEffect<sup>12+</sup>
136
137symbolEffect(symbolEffect: SymbolEffect, isActive?: boolean)
138
139Sets the symbol effect and effect state for the **SymbolGlyph** component.
140
141**Widget capability**: This API can be used in ArkTS widgets since API version 12.
142
143**Atomic service API**: This API can be used in atomic services since API version 12.
144
145**System capability**: SystemCapability.ArkUI.ArkUI.Full
146
147**Parameters**
148
149| Name| Type| Mandatory| Description |
150| ------ | ---- | ---- | ----- |
151| symbolEffect  | [SymbolEffect](#symboleffect12) | Yes  | Symbol effect of the **SymbolGlyph** component.<br>Default value: [SymbolEffect](#symboleffect12) |
152| isActive  | boolean | No  | Whether the effect is active.<br>Default value: **false**|
153
154### symbolEffect<sup>12+</sup>
155
156symbolEffect(symbolEffect: SymbolEffect, triggerValue?: number)
157
158Sets the symbol effect and effect trigger for the **SymbolGlyph** component.
159
160**Widget capability**: This API can be used in ArkTS widgets since API version 12.
161
162**Atomic service API**: This API can be used in atomic services since API version 12.
163
164**System capability**: SystemCapability.ArkUI.ArkUI.Full
165
166**Parameters**
167
168| Name| Type| Mandatory| Description |
169| ------ | ---- | ---- | ----- |
170| symbolEffect | [SymbolEffect](#symboleffect12) | Yes  | Symbol effect of the **SymbolGlyph** component.<br>Default value: [SymbolEffect](#symboleffect12) |
171| triggerValue | number | No  | Value that, when changed, initiates the animation of the **SymbolGlyph** component.<br>To prevent the motion effect from triggering initially, set it to **-1**.|
172
173>  **NOTE**
174>
175>  When configuring the symbol effect, use the **effectStrategy** attribute or a single **symbolEffect** attribute. Mixing multiple effect attributes is not allowed.
176
177## SymbolEffect<sup>12+</sup>
178
179Defines the **SymbolEffect** class.
180
181**Widget capability**: This API can be used in ArkTS widgets since API version 12.
182
183**Atomic service API**: This API can be used in atomic services since API version 12.
184
185**System capability**: SystemCapability.ArkUI.ArkUI.Full
186
187## ScaleSymbolEffect<sup>12+</sup>
188
189Inherits from **SymbolEffect**.
190
191**Widget capability**: This API can be used in ArkTS widgets since API version 12.
192
193**Atomic service API**: This API can be used in atomic services since API version 12.
194
195**System capability**: SystemCapability.ArkUI.ArkUI.Full
196
197### Attributes
198
199| Name| Type| Mandatory| Description |
200| ---- | ---- | ---- | ---- |
201| scope     | [EffectScope](#effectscope12)  |  No  | Effect scope.<br>Default value: **EffectScope.LAYER**   |
202| direction | [EffectDirection](#effectdirection12) |  No  | Effect direction.<br>Default value: **EffectDirection.DOWN**|
203
204### constructor<sup>12+</sup>
205
206constructor(scope?: EffectScope, direction?: EffectDirection)
207
208A constructor used to create a **ScaleSymbolEffect** instance, which comes with a scaling animation effect.
209
210**Widget capability**: This API can be used in ArkTS widgets since API version 12.
211
212**Atomic service API**: This API can be used in atomic services since API version 12.
213
214**System capability**: SystemCapability.ArkUI.ArkUI.Full
215
216**Parameters**
217
218| Name| Type| Mandatory| Description |
219| ---- | ---- | ---- | ---- |
220| scope     | [EffectScope](#effectscope12)         | No  | Effect scope.<br>Default value: **EffectScope.LAYER**   |
221| direction | [EffectDirection](#effectdirection12) | No  | Effect direction.<br>Default value: **EffectDirection.DOWN**|
222
223## HierarchicalSymbolEffect<sup>12+</sup>
224
225Inherits from **SymbolEffect**.
226
227**Widget capability**: This API can be used in ArkTS widgets since API version 12.
228
229**Atomic service API**: This API can be used in atomic services since API version 12.
230
231**System capability**: SystemCapability.ArkUI.ArkUI.Full
232
233### Attributes
234
235| Name| Type| Mandatory| Description |
236| ---- | ---- | ---- | ---- |
237| fillStyle | [EffectFillStyle](#effectfillstyle12) | No  | Effect fill style.<br>Default value: **EffectFillStyle.CUMULATIVE**|
238
239### constructor<sup>12+</sup>
240
241constructor(fillStyle?: EffectFillStyle)
242
243A constructor used to create a **HierarchicalSymbolEffect** instance, which comes with a hierarchical animation effect.
244
245**Widget capability**: This API can be used in ArkTS widgets since API version 12.
246
247**Atomic service API**: This API can be used in atomic services since API version 12.
248
249**System capability**: SystemCapability.ArkUI.ArkUI.Full
250
251**Parameters**
252
253| Name| Type| Mandatory| Description |
254| ---- | ---- | ---- | ---- |
255| fillStyle | [EffectFillStyle](#effectfillstyle12) | No  | Effect fill style.<br>Default value: **EffectFillStyle.CUMULATIVE**|
256
257## AppearSymbolEffect<sup>12+</sup>
258
259Inherits from **SymbolEffect**.
260
261**Widget capability**: This API can be used in ArkTS widgets since API version 12.
262
263**Atomic service API**: This API can be used in atomic services since API version 12.
264
265**System capability**: SystemCapability.ArkUI.ArkUI.Full
266
267### Attributes
268
269| Name| Type| Mandatory| Description |
270| ---- | ---- | ---- | ---- |
271| scope | [EffectScope](#effectscope12) | No  | Effect scope.<br>Default value: **EffectScope.LAYER**|
272
273### constructor<sup>12+</sup>
274
275constructor(scope?: EffectScope)
276
277A constructor used to create an **AppearSymbolEffect** instance, which comes with an appear animation effect.
278
279**Widget capability**: This API can be used in ArkTS widgets since API version 12.
280
281**Atomic service API**: This API can be used in atomic services since API version 12.
282
283**System capability**: SystemCapability.ArkUI.ArkUI.Full
284
285**Parameters**
286
287| Name| Type| Mandatory| Description |
288| ---- | ---- | ---- | ---- |
289| scope  | [EffectScope](#effectscope12) | No  | Effect scope.<br>Default value: **EffectScope.LAYER**|
290
291## DisappearSymbolEffect<sup>12+</sup>
292
293Inherits from **SymbolEffect**.
294
295**Widget capability**: This API can be used in ArkTS widgets since API version 12.
296
297**Atomic service API**: This API can be used in atomic services since API version 12.
298
299**System capability**: SystemCapability.ArkUI.ArkUI.Full
300
301### Attributes
302
303| Name| Type| Mandatory| Description |
304| ---- | ---- | ---- | ---- |
305| scope | [EffectScope](#effectscope12) | No  | Effect scope.<br>Default value: **EffectScope.LAYER**|
306
307### constructor<sup>12+</sup>
308
309constructor(scope?: EffectScope)
310
311A constructor used to create a **DisappearSymbolEffect** instance, which comes with a disappear animation effect.
312
313**Widget capability**: This API can be used in ArkTS widgets since API version 12.
314
315**Atomic service API**: This API can be used in atomic services since API version 12.
316
317**System capability**: SystemCapability.ArkUI.ArkUI.Full
318
319**Parameters**
320
321| Name| Type| Mandatory| Description |
322| ---- | ---- | ---- | ---- |
323| scope  | [EffectScope](#effectscope12) | No  | Effect scope.<br>Default value: **EffectScope.LAYER**|
324
325## BounceSymbolEffect<sup>12+</sup>
326
327Inherits from **SymbolEffect**.
328
329**Widget capability**: This API can be used in ArkTS widgets since API version 12.
330
331**Atomic service API**: This API can be used in atomic services since API version 12.
332
333**System capability**: SystemCapability.ArkUI.ArkUI.Full
334
335### Attributes
336
337| Name| Type| Mandatory| Description |
338| ---- | ---- | ---- | ---- |
339| scope     | [EffectScope](#effectscope12)         | No  | Effect scope.<br>Default value: **EffectScope.LAYER**   |
340| direction | [EffectDirection](#effectdirection12) | No  | Effect direction.<br>Default value: **EffectDirection.DOWN**|
341
342### constructor<sup>12+</sup>
343
344constructor(scope?: EffectScope, direction?: EffectDirection)
345
346A constructor used to create a **BounceSymbolEffect** instance, which comes with a bounce animation effect.
347
348**Widget capability**: This API can be used in ArkTS widgets since API version 12.
349
350**Atomic service API**: This API can be used in atomic services since API version 12.
351
352**System capability**: SystemCapability.ArkUI.ArkUI.Full
353
354**Parameters**
355
356| Name| Type| Mandatory| Description |
357| ---- | ---- | ---- | ---- |
358| scope     | [EffectScope](#effectscope12)         | No  | Effect scope.<br>Default value: **EffectScope.LAYER**   |
359| direction | [EffectDirection](#effectdirection12) | No  | Effect direction.<br>Default value: **EffectDirection.DOWN**|
360
361## ReplaceSymbolEffect<sup>12+</sup>
362
363Inherits from **SymbolEffect**.
364
365**Widget capability**: This API can be used in ArkTS widgets since API version 12.
366
367**Atomic service API**: This API can be used in atomic services since API version 12.
368
369**System capability**: SystemCapability.ArkUI.ArkUI.Full
370
371### Attributes
372
373| Name| Type| Mandatory| Description |
374| ---- | ---- | ---- | ---- |
375| scope | [EffectScope](#effectscope12) | No  | Effect scope.<br>Default value: **EffectScope.LAYER**|
376
377### constructor<sup>12+</sup>
378
379constructor(scope?: EffectScope)
380
381A constructor used to create a **ReplaceSymbolEffect** instance, which comes with a replace animation effect.
382
383**Widget capability**: This API can be used in ArkTS widgets since API version 12.
384
385**Atomic service API**: This API can be used in atomic services since API version 12.
386
387**System capability**: SystemCapability.ArkUI.ArkUI.Full
388
389**Parameters**
390
391| Name| Type| Mandatory| Description |
392| ---- | ---- | ---- | ---- |
393| scope  | [EffectScope](#effectscope12) | No  | Effect scope.<br>Default value: **EffectScope.LAYER**|
394
395## PulseSymbolEffect<sup>12+</sup>
396
397A constructor used to create a **PulseSymbolEffect** instance, which comes with a pulse animation effect.
398
399**Widget capability**: This API can be used in ArkTS widgets since API version 12.
400
401**Atomic service API**: This API can be used in atomic services since API version 12.
402
403**System capability**: SystemCapability.ArkUI.ArkUI.Full
404
405## EffectDirection<sup>12+</sup>
406
407**Widget capability**: This API can be used in ArkTS widgets since API version 12.
408
409**Atomic service API**: This API can be used in atomic services since API version 12.
410
411**System capability**: SystemCapability.ArkUI.ArkUI.Full
412
413| Name| Value  | Description            |
414| ---- | ---- | ---------------- |
415| DOWN | 0    | The symbol scales down and then returns to its original size.|
416| UP   | 1    | The symbol scales up and then returns to its original size.|
417
418## EffectScope<sup>12+</sup>
419
420**Widget capability**: This API can be used in ArkTS widgets since API version 12.
421
422**Atomic service API**: This API can be used in atomic services since API version 12.
423
424**System capability**: SystemCapability.ArkUI.ArkUI.Full
425
426| Name | Value  | Description      |
427| ----- | ---- | ---------- |
428| LAYER | 0    | Layered mode.|
429| WHOLE | 1    | Whole mode.|
430
431## EffectFillStyle<sup>12+</sup>
432
433**Widget capability**: This API can be used in ArkTS widgets since API version 12.
434
435**Atomic service API**: This API can be used in atomic services since API version 12.
436
437**System capability**: SystemCapability.ArkUI.ArkUI.Full
438
439| Name      | Value  | Description      |
440| ---------- | ---- | ---------- |
441| CUMULATIVE | 0    | Cumulative style.|
442| ITERATIVE  | 1    | Iterative style.|
443
444## SymbolEffectStrategy<sup>11+</sup>
445
446Enumerates symbol effect types. Once applied, the symbol effect becomes active instantly, eliminating the need for triggering.
447
448**Widget capability**: This API can be used in ArkTS widgets since API version 12.
449
450**Atomic service API**: This API can be used in atomic services since API version 12.
451
452**System capability**: SystemCapability.ArkUI.ArkUI.Full
453
454| Name    | Description                         |
455| ------ | ----------------------------- |
456| NONE | No effect (default value).|
457| SCALE | Scale effect as a whole.                |
458|  HIERARCHICAL  | Hierarchical effect. |
459
460## SymbolRenderingStrategy<sup>11+</sup>
461
462Enumerates the rendering modes.
463
464**Widget capability**: This API can be used in ArkTS widgets since API version 12.
465
466**Atomic service API**: This API can be used in atomic services since API version 12.
467
468**System capability**: SystemCapability.ArkUI.ArkUI.Full
469
470| Name    | Description                         |
471| ------ | ----------------------------- |
472| SINGLE  | Single-color mode (default).<br> The default color is black, and one color can be set.<br> If multiple colors are set, only the first color takes effect.|
473| MULTIPLE_COLOR  |  Multi-color mode.<br> A maximum of three colors can be set. If only one color is set, it updates the color of the first layer, leaving other colors at their default values.<br> The sequence of color settings matches the layering order of the symbol; any colors beyond the number of symbol layers will not take effect.<br> Only color values are accepted. Opacity settings do not take effect.|
474|  MULTIPLE_OPACITY   | Layered mode.<br> The default color is black, and one color can be set. If multiple colors are set, only the first color takes effect.<br> Opacity is related to the layer, with the first layer at 100%, the second layer at 50%, and the third layer at 20%. |
475
476## Events
477
478The [universal events](ts-universal-events-click.md) are supported.
479
480## Example
481
482###  Example 1
483
484```ts
485// xxx.ets
486@Entry
487@Component
488struct Index {
489  build() {
490    Column() {
491      Row() {
492        Column() {
493          Text("Light")
494          SymbolGlyph($r('sys.symbol.ohos_trash'))
495            .fontWeight(FontWeight.Lighter)
496            .fontSize(96)
497        }
498
499        Column() {
500          Text("Normal")
501          SymbolGlyph($r('sys.symbol.ohos_trash'))
502            .fontWeight(FontWeight.Normal)
503            .fontSize(96)
504        }
505
506        Column() {
507          Text("Bold")
508          SymbolGlyph($r('sys.symbol.ohos_trash'))
509            .fontWeight(FontWeight.Bold)
510            .fontSize(96)
511        }
512      }
513
514      Row() {
515        Column() {
516          Text("Single-color mode")
517          SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
518            .fontSize(96)
519            .renderingStrategy(SymbolRenderingStrategy.SINGLE)
520            .fontColor([Color.Black, Color.Green, Color.White])
521        }
522
523        Column() {
524          Text("Multi-color mode")
525          SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
526            .fontSize(96)
527            .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)
528            .fontColor([Color.Black, Color.Green, Color.White])
529        }
530
531        Column() {
532          Text("Layered mode")
533          SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
534            .fontSize(96)
535            .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_OPACITY)
536            .fontColor([Color.Black, Color.Green, Color.White])
537        }
538      }
539
540      Row() {
541        Column() {
542          Text("No effect")
543          SymbolGlyph($r('sys.symbol.ohos_wifi'))
544            .fontSize(96)
545            .effectStrategy(SymbolEffectStrategy.NONE)
546        }
547
548        Column() {
549          Text("Overall scale effect")
550          SymbolGlyph($r('sys.symbol.ohos_wifi'))
551            .fontSize(96)
552            .effectStrategy(1)
553        }
554
555        Column() {
556          Text("Hierarchical effect")
557          SymbolGlyph($r('sys.symbol.ohos_wifi'))
558            .fontSize(96)
559            .effectStrategy(2)
560        }
561      }
562    }
563  }
564}
565```
566![symbol](figures/symbolGlyph.gif)
567
568###  Example 2
569
570This example demonstrates the use of the s**ymbolEffec**t attribute in the **SymbolGlyph** component to achieve variable color and replace animation effects.
571
572```ts
573// xxx.ets
574@Entry
575@Component
576struct Index {
577  @State isActive: boolean = true;
578  @State triggerValueReplace: number = 0;
579  replaceFlag: boolean = true;
580
581  build() {
582    Column() {
583      Row() {
584        Column() {
585          Text("Variable Color Animation")
586          SymbolGlyph($r('sys.symbol.ohos_wifi'))
587            .fontSize(96)
588            .symbolEffect(new HierarchicalSymbolEffect(EffectFillStyle.ITERATIVE), this.isActive)
589          Button(this.isActive ? 'Off' : 'Play').onClick(() => {
590            this.isActive = !this.isActive;
591          })
592        }.margin({right:20})
593
594        Column() {
595          Text("Replace Animation")
596          SymbolGlyph(this.replaceFlag ? $r('sys.symbol.checkmark_circle') : $r('sys.symbol.repeat_1'))
597            .fontSize(96)
598            .symbolEffect(new ReplaceSymbolEffect(EffectScope.WHOLE), this.triggerValueReplace)
599          Button('trigger').onClick(() => {
600            this.replaceFlag = !this.replaceFlag;
601            this.triggerValueReplace = this.triggerValueReplace + 1;
602          })
603        }
604      }
605    }.margin({
606      left:30,
607      top:50
608    })
609  }
610}
611```
612![symbol](figures/symbolGlyph_symbolEffect.gif)
613