• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 图标小符号 (SymbolGlyph/SymbolSpan)
2<!--Kit: ArkUI-->
3<!--Subsystem: ArkUI-->
4<!--Owner: @hddgzw-->
5<!--Designer: @pssea-->
6<!--Tester: @jiaoaozihao-->
7<!--Adviser: @HelloCrease-->
8
9SymbolGlyph是图标小符号组件，便于使用精美的图标，如渲染多色图标和使用动效图标。SymbolSpan作为Text组件的子组件，可在文本中穿插显示图标小符号。具体用法请参考[SymbolGlyph](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolGlyph.md)和[SymbolSpan](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolSpan.md)组件的文档。
10
11
12## 创建图标
13
14SymbolGlyph通过$r引用Resource资源来创建，目前仅支持系统预置的Symbol资源名。<!--RP1--><!--RP1End-->
15
16  ```ts
17  SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
18    .fontSize(96)
19    .renderingStrategy(SymbolRenderingStrategy.SINGLE)
20    .fontColor([Color.Black, Color.Green, Color.White])
21  ```
22  ![symbol_folder_badge_plus](figures/symbol_ohos_folder_badge_plus.png)
23
24
25## 添加到文本中
26
27[SymbolSpan](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolSpan.md)可作为[Text](../reference/apis-arkui/arkui-ts/ts-basic-components-text.md)的子组件用于显示图标小符号。可以在一个Text组件内添加多个SymbolSpan，从而展示一串连续的图标。
28
29- 创建SymbolSpan。
30
31  SymbolSpan组件需嵌入在Text组件中才能显示，单独使用不会呈现任何内容。
32
33
34  ```ts
35  Text() {
36    SymbolSpan($r('sys.symbol.ohos_trash'))
37      .fontWeight(FontWeight.Normal)
38      .fontSize(96)
39  }
40  ```
41  ![symbol_trash](figures/symbolspan_trash.png)
42
43
44- 通过[fontSize](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolSpan.md#fontsize)属性设置SymbolSpan的大小。
45
46
47  ```ts
48  Row() {
49    Column() {
50      Text("48")
51      Text() {
52        SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
53          .fontSize(48)
54          .renderingStrategy(SymbolRenderingStrategy.SINGLE)
55          .fontColor([Color.Black, Color.Green, Color.White])
56      }
57    }
58
59    Column() {
60      Text("72")
61      Text() {
62        SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
63          .fontSize(72)
64          .renderingStrategy(SymbolRenderingStrategy.SINGLE)
65          .fontColor([Color.Black, Color.Green, Color.White])
66      }
67    }
68
69    Column() {
70      Text("96")
71      Text() {
72        SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
73          .fontSize(96)
74          .renderingStrategy(SymbolRenderingStrategy.SINGLE)
75          .fontColor([Color.Black, Color.Green, Color.White])
76      }
77    }
78  }
79  ```
80  ![symbolSpan_multi_fontSize](figures/symbolspan_multi_fontsize.png)
81
82- 通过[fontWeight](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolSpan.md#fontweight)属性设置SymbolSpan组件的粗细。
83
84  ```ts
85  Row() {
86    Column() {
87      Text("Light")
88      Text() {
89        SymbolSpan($r('sys.symbol.ohos_trash'))
90          .fontWeight(FontWeight.Lighter)
91          .fontSize(96)
92      }
93    }
94
95    Column() {
96      Text("Normal")
97      Text() {
98        SymbolSpan($r('sys.symbol.ohos_trash'))
99          .fontWeight(FontWeight.Normal)
100          .fontSize(96)
101      }
102    }
103
104    Column() {
105      Text("Bold")
106      Text() {
107        SymbolSpan($r('sys.symbol.ohos_trash'))
108          .fontWeight(FontWeight.Bold)
109          .fontSize(96)
110      }
111    }
112  }
113  ```
114  ![symbolSpan_multi_fontWeight_trash](figures/symbol_multi_fontweight_trash.png)
115
116- 通过[fontColor](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolSpan.md#fontcolor)属性设置SymbolSpan的颜色。
117
118  ```ts
119  Row() {
120    Column() {
121      Text("Black")
122      Text() {
123          SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
124            .fontSize(96)
125            .fontColor([Color.Black])
126      }
127    }
128
129    Column() {
130      Text("Green")
131      Text() {
132        SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
133          .fontSize(96)
134          .fontColor([Color.Green])
135      }
136    }
137
138    Column() {
139      Text("Pink")
140      Text() {
141        SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
142          .fontSize(96)
143          .fontColor([Color.Pink])
144      }
145    }
146  }
147  ```
148  ![symbolSpan_multi_fontColor](figures/symbolspan_multi_fontcolor.PNG)
149
150- 通过[renderingStrategy](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolSpan.md#renderingstrategy)属性设置SymbolSpan的渲染策略。
151
152  ```ts
153  Row() {
154    Column() {
155      Text("单色")
156      Text() {
157        SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
158          .fontSize(96)
159          .renderingStrategy(SymbolRenderingStrategy.SINGLE)
160          .fontColor([Color.Black, Color.Green, Color.White])
161      }
162    }
163
164    Column() {
165      Text("多色")
166      Text() {
167        SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
168          .fontSize(96)
169          .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)
170          .fontColor([Color.Black, Color.Green, Color.White])
171      }
172    }
173
174    Column() {
175      Text("分层")
176      Text() {
177        SymbolSpan($r('sys.symbol.ohos_folder_badge_plus'))
178          .fontSize(96)
179          .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_OPACITY)
180          .fontColor([Color.Black, Color.Green, Color.White])
181      }
182    }
183  }
184  ```
185  ![symbolSpan_multi_renderingStrategy](figures/symbolspan_multi_renderingStrategy.png)
186
187- 通过[effectStrategy](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolSpan.md#effectstrategy)属性设置SymbolSpan的动效策略。
188
189  ```ts
190  Row() {
191    Column() {
192      Text("无动效")
193      Text() {
194        SymbolSpan($r('sys.symbol.ohos_wifi'))
195          .fontSize(96)
196          .effectStrategy(SymbolEffectStrategy.NONE)
197      }
198    }
199
200    Column() {
201      Text("整体缩放动效")
202      Text() {
203        SymbolSpan($r('sys.symbol.ohos_wifi'))
204          .fontSize(96)
205          .effectStrategy(SymbolEffectStrategy.SCALE)
206      }
207    }
208
209    Column() {
210      Text("层级动效")
211      Text() {
212        SymbolSpan($r('sys.symbol.ohos_wifi'))
213          .fontSize(96)
214          .effectStrategy(SymbolEffectStrategy.HIERARCHICAL)
215      }
216    }
217  }
218  ```
219  ![symbolSpan_multi_effectStrategy](figures/symbolspan_multi_effectStrategy.gif)
220
221- SymbolSpan不支持通用事件。
222
223## 自定义图标动效
224
225相较于effectStrategy属性在启动时即触发动效，可以通过以下两种方式来控制动效的播放状态，以及选择更多样化的动效策略。
226
227关于effectStrategy属性与symbolEffect属性的多种动态属性使用及生效原则，详情请参阅[SymbolGlyph.symbolEffect](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolGlyph.md#symboleffect12-1)属性的说明。
228
229- 通过设置SymbolEffect属性，可以同时配置SymbolGlyph的动效策略和播放状态。
230
231  ```ts
232  @State isActive: boolean = true;
233  Column() {
234    Text("可变颜色动效")
235    SymbolGlyph($r('sys.symbol.ohos_wifi'))
236      .fontSize(96)
237      .symbolEffect(new HierarchicalSymbolEffect(EffectFillStyle.ITERATIVE), this.isActive)
238    Button(this.isActive ? '关闭' : '播放').onClick(() => {
239      this.isActive = !this.isActive;
240    })
241  }
242  ```
243  ![symbolGlyph_symbolEffect_isActive](figures/symbolGlyph_symbolEffect_isActive.gif)
244
245- 通过设置SymbolEffect属性，可以同时指定SymbolGlyph的动画效果策略及其播放触发条件。
246
247  ```ts
248  @State triggerValueReplace: number = 0;
249  Column() {
250    Text("弹跳动效")
251    SymbolGlyph($r('sys.symbol.ellipsis_message_1'))
252      .fontSize(96)
253      .fontColor([Color.Gray])
254      .symbolEffect(new BounceSymbolEffect(EffectScope.WHOLE, EffectDirection.UP), this.triggerValueReplace)
255    Button('trigger').onClick(() => {
256      this.triggerValueReplace = this.triggerValueReplace + 1;
257    })
258  }
259  ```
260  ![BounceSymbolEffect](figures/symbolGlyph_bounceSymbolEffect_trigger.gif)
261
262- 从API version 20开始，支持通过设置SymbolEffect属性为[ReplaceSymbolEffect](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolGlyph.md#replacesymboleffect12)，设置[ReplaceEffectType](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolGlyph.md#replaceeffecttype20枚举说明)为ReplaceEffectType.SLASH_OVERLAY，可以指定SymbolGlyph的禁用动画效果及其播放触发条件。
263
264  ```ts
265  @State triggerValueReplace: number = 0;
266  @State renderMode: number = 1;
267  replaceFlag: boolean = true;
268
269  Column() {
270    Text("禁用动效")
271    SymbolGlyph(this.replaceFlag ? $r('sys.symbol.eye_slash') : $r('sys.symbol.eye'))
272      .fontSize(96)
273      .renderingStrategy(this.renderMode)
274      .symbolEffect(new ReplaceSymbolEffect(EffectScope.LAYER, ReplaceEffectType.SLASH_OVERLAY), this.triggerValueReplace)
275    Button('trigger').onClick(() => {
276      this.replaceFlag = !this.replaceFlag;
277      this.triggerValueReplace = this.triggerValueReplace + 1;
278    })
279  }
280  ```
281  ![symbolGlyph_symbolEffect_disable](figures/symbolGlyph_symbolEffect_disable.gif)
282
283- 从API version 20开始，支持通过设置SymbolEffect属性为[ReplaceSymbolEffect](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolGlyph.md#replacesymboleffect12)，设置[ReplaceEffectType](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolGlyph.md#replaceeffecttype20枚举说明)为ReplaceEffectType.CROSS_FADE，可以指定SymbolGlyph的快速替换动画效果及其播放触发条件。
284
285  ```ts
286  @State triggerValueReplace: number = 0;
287  replaceFlag: boolean = true;
288
289  Column() {
290    Text("快速替换动效")
291    SymbolGlyph(this.replaceFlag ? $r('sys.symbol.checkmark_circle') : $r('sys.symbol.repeat_1'))
292      .fontSize(96)
293      .symbolEffect(new ReplaceSymbolEffect(EffectScope.WHOLE, ReplaceEffectType.CROSS_FADE), this.triggerValueReplace)
294    Button('trigger').onClick(() => {
295      this.replaceFlag = !this.replaceFlag;
296      this.triggerValueReplace = this.triggerValueReplace + 1;
297    })
298  }
299  ```
300  ![symbolGlyph_symbolEffect_quick_replace](figures/symbolGlyph_symbolEffect_quick_replace.gif)
301
302## 设置阴影和渐变色
303
304- 从API version 20开始，支持通过[symbolShadow](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolGlyph.md#symbolshadow20)接口实现了symbolGlyph组件显示阴影效果。
305
306  ```ts
307  @State isActive: boolean = true;
308
309  options: ShadowOptions = {
310    radius: 10.0,
311    color: Color.Blue,
312    offsetX: 10,
313    offsetY: 10,
314  };
315
316  Column() {
317    Text("阴影能力")
318    SymbolGlyph($r('sys.symbol.ohos_wifi'))
319      .fontSize(96)
320      .symbolEffect(new HierarchicalSymbolEffect(EffectFillStyle.ITERATIVE), !this.isActive)
321      .symbolShadow(this.options)
322    Button(!this.isActive ? '关闭' : '播放').onClick(() => {
323      this.isActive = !this.isActive;
324    })
325  }
326  ```
327  ![SymbolShadowSymbolEffect](figures/symbolGlyph_symbolShadow.gif)
328
329- 从API version 20开始，支持通过[shaderStyle](../reference/apis-arkui/arkui-ts/ts-basic-components-symbolGlyph.md#shaderstyle20)接口实现了symbolGlyph组件显示渐变色效果。
330
331  ```ts
332  radialGradientOptions: RadialGradientOptions = {
333    center: ["50%", "50%"],
334    radius: "20%",
335    colors: [[Color.Red, 0.0], [Color.Blue, 0.3], [Color.Green, 0.5]],
336    repeating: true,
337  };
338
339  Column() {
340    Text('径向渐变')
341      .fontSize(18)
342      .fontColor(0xCCCCCC)
343      .textAlign(TextAlign.Center)
344    SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
345      .fontSize(96)
346      .shaderStyle([new RadialGradientStyle(this.radialGradientOptions)])
347  }
348  ```
349  ![ShaderStyleSymbolEffect](figures/symbolGlyph_shaderStyle.jpg)
350
351## 添加事件
352
353SymbolGlyph组件可以添加通用事件，例如绑定[onClick](../reference/apis-arkui/arkui-ts/ts-universal-events-click.md#onclick)、[onTouch](../reference/apis-arkui/arkui-ts/ts-universal-events-touch.md#ontouch)等事件来响应操作。
354
355```ts
356@State wifiColor: ResourceColor = Color.Black;
357SymbolGlyph($r('sys.symbol.ohos_wifi'))
358  .fontSize(96)
359  .fontColor([this.wifiColor])
360  .onClick(() => {
361    this.wifiColor = Color.Gray;
362  })
363```
364![symbolGlyph_onClick](figures/symbolGlyph_onClick.gif)
365
366## 场景示例
367
368该示例通过symbolEffect、fontSize、fontColor属性展示了播放列表的效果。
369
370```ts
371// xxx.ets
372@Entry
373@Component
374struct Index {
375  @State triggerValueReplace: number = 0;
376  @State symbolSources: Resource[] =
377    [$r('sys.symbol.repeat'), $r('sys.symbol.repeat_1'), $r('sys.symbol.arrow_left_arrow_right')];
378  @State symbolSourcesIndex: number = 0;
379  @State symbolText: string[] = ['顺序播放', '单曲循环', '随机播放'];
380  @State symbolTextIndex: number = 0;
381  @State fontColorValue: ResourceColor = Color.Grey;
382  @State fontColorValue1: ResourceColor = '#E8E8E8';
383
384  build() {
385    Column({ space: 10 }) {
386      Row() {
387        Text() {
388          Span('当前播放列表')
389            .fontSize(20)
390            .fontWeight(FontWeight.Bolder)
391          Span('（101）')
392        }
393      }
394
395      Row() {
396        Row({ space: 5 }) {
397          SymbolGlyph(this.symbolSources[this.symbolSourcesIndex])
398            .symbolEffect(new ReplaceSymbolEffect(EffectScope.WHOLE), this.triggerValueReplace)
399            .fontSize(20)
400            .fontColor([this.fontColorValue])
401          Text(this.symbolText[this.symbolTextIndex])
402            .fontColor(this.fontColorValue)
403        }
404        .onClick(() => {
405          this.symbolTextIndex++;
406          this.symbolSourcesIndex++;
407          this.triggerValueReplace++;
408          if (this.symbolSourcesIndex > (this.symbolSources.length - 1)) {
409            this.symbolSourcesIndex = 0;
410            this.triggerValueReplace = 0;
411          }
412          if (this.symbolTextIndex > (this.symbolText.length - 1)) {
413            this.symbolTextIndex = 0;
414          }
415        })
416        .width('75%')
417
418        Row({ space: 5 }) {
419          Text() {
420            SymbolSpan($r('sys.symbol.arrow_down_circle_badge_vip_circle_filled'))
421              .fontColor([this.fontColorValue])
422              .fontSize(20)
423          }
424
425          Text() {
426            SymbolSpan($r('sys.symbol.heart_badge_plus'))
427              .fontColor([this.fontColorValue])
428              .fontSize(20)
429          }
430
431          Text() {
432            SymbolSpan($r('sys.symbol.ohos_trash'))
433              .fontColor([this.fontColorValue])
434              .fontSize(20)
435          }
436        }
437        .width('25%')
438      }
439
440      Divider().width(5).color(this.fontColorValue1).width('98%')
441      Row() {
442        Row() {
443          Text("歌曲一")
444        }.width('82%')
445
446        Row({ space: 5 }) {
447          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
448            .fontColor([this.fontColorValue])
449            .fontSize(20)
450          SymbolGlyph($r('sys.symbol.trash'))
451            .fontColor([this.fontColorValue])
452            .fontSize(20)
453        }
454      }
455
456      Divider().width(5).color(this.fontColorValue1).width('98%')
457      Row() {
458        Row() {
459          Text("歌曲二")
460        }.width('82%')
461
462        Row({ space: 5 }) {
463          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
464            .fontColor([this.fontColorValue])
465            .fontSize(20)
466          SymbolGlyph($r('sys.symbol.trash'))
467            .fontColor([this.fontColorValue])
468            .fontSize(20)
469        }
470      }
471
472      Divider().width(5).color(this.fontColorValue1).width('98%')
473      Row() {
474        Row() {
475          Text("歌曲三")
476        }.width('82%')
477
478        Row({ space: 5 }) {
479          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
480            .fontColor([this.fontColorValue])
481            .fontSize(20)
482          SymbolGlyph($r('sys.symbol.trash'))
483            .fontColor([this.fontColorValue])
484            .fontSize(20)
485        }
486      }
487
488      Divider().width(5).color(this.fontColorValue1).width('98%')
489      Row() {
490        Row() {
491          Text("歌曲四")
492        }.width('82%')
493
494        Row({ space: 5 }) {
495          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
496            .fontColor([this.fontColorValue])
497            .fontSize(20)
498          SymbolGlyph($r('sys.symbol.trash'))
499            .fontColor([this.fontColorValue])
500            .fontSize(20)
501        }
502      }
503
504      Divider().width(5).color(this.fontColorValue1).width('98%')
505      Row() {
506        Row() {
507          Text("歌曲五")
508        }.width('82%')
509
510        Row({ space: 5 }) {
511          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
512            .fontColor([this.fontColorValue])
513            .fontSize(20)
514          SymbolGlyph($r('sys.symbol.trash'))
515            .fontColor([this.fontColorValue])
516            .fontSize(20)
517        }
518      }
519
520      Divider().width(5).color(this.fontColorValue1).width('98%')
521      Row() {
522        Row() {
523          Text("歌曲六")
524        }.width('82%')
525
526        Row({ space: 5 }) {
527          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
528            .fontColor([this.fontColorValue])
529            .fontSize(20)
530          SymbolGlyph($r('sys.symbol.trash'))
531            .fontColor([this.fontColorValue])
532            .fontSize(20)
533        }
534      }
535
536      Divider().width(5).color(this.fontColorValue1).width('98%')
537      Row() {
538        Row() {
539          Text("歌曲七")
540        }.width('82%')
541
542        Row({ space: 5 }) {
543          SymbolGlyph($r('sys.symbol.play_arrow_triangle_2_circlepath'))
544            .fontColor([this.fontColorValue])
545            .fontSize(20)
546          SymbolGlyph($r('sys.symbol.trash'))
547            .fontColor([this.fontColorValue])
548            .fontSize(20)
549        }
550      }
551
552      Divider().width(5).color(this.fontColorValue1).width('98%')
553      Column() {
554        Text("关闭")
555      }
556      .alignItems(HorizontalAlign.Center)
557      .width('98%')
558    }
559    .alignItems(HorizontalAlign.Start)
560    .width('100%')
561    .height(400)
562    .padding({
563      left: 10,
564      top: 10
565    })
566  }
567}
568```
569![symbol_scene_demo](figures/symbol_music_demo.gif)
570