一、為什麼需要 “符號”（Symbol）組件？

在 UI 設計裏，經常會碰到這樣的需求：

• 在按鈕或標題前放一個小圖標
• 在某段文本里插入一個圖標（比如 ⭐、❤️、📍）
• 顯示系統預置圖標（比如網絡狀態、箭頭、系統資源圖標）
• 用圖標替代圖片資源實現統一風格

普通做法會用 Image 或者文字字體圖標（unicode），但這樣：

• 不夠語義化
• 有時渲染顏色與樣式難以統一
• 不夠輕量也不利於換膚/主題適配

HarmonyOS ArkTS 就提供了 SymbolGlyph 和 SymbolSpan 兩個組件來解決這個問題。

二、SymbolGlyph 與 SymbolSpan 是什麼？

1.SymbolGlyph

這是一個圖標小符號組件，專門用來顯示系統預置的圖標資源（如 Wi-Fi、文件夾等）。
它通常用來直接顯示一個獨立的圖標，與 Image 不同的是它是矢量圖標，支持動態設色和大小變化。

• 適合：按鈕圖標、狀態提示、列表項左側圖標等
• 不能放子組件（只顯示圖標）

2. SymbolSpan

這是一個可以放在 Text（文本）內部的符號片段，可以讓圖標跟文字“擠在一起”顯示。常見於：

• 文本里穿插圖標
• 圖標+文字組合標籤
• Emoji 之外的 UI 圖標
• 文本提示裏的輔助圖形

內部原理類似 Text 的 Span，但顯示的是符號圖標，而不是文字三、常用 API 屬性（按人讀得懂的方式講）

下面這些屬性是在開發中你最可能用到的，順序按重要程度排序。

fontSize(...) — 控制圖標大小

不管是 SybolGlyph 還是 SymbolSpan，圖標大小主要由 fontSize 決定：

SymbolGlyph($r('sys.symbol.ohos_wifi'))
  .fontSize(20)

它接受數字、字符串、資源引用（不建議用百分比字符串）。這個值直接控制圖標渲染大小

fontColor([...]) — 控制圖標顏色

與 Text 的 fontColor 不同，SymbolGlyph 支持數組式顏色：

• 單色：只傳一個顏色
• 多色：傳多個顏色數組，圖標根據渲染策略分配顏色

例子：

SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
  .fontColor([Color.Black, Color.Green, Color.White])

多色圖標顯示更豐富，但要注意渲染策略（下面講）。

fontWeight(...) — 圖標粗細

可以配置圖標的“線條粗細”，取值範圍是 100~900，也支持常用的字符串：

SymbolGlyph($r('sys.symbol.ohos_trash'))
  .fontWeight(FontWeight.Bold)

注意：部分系統圖標本身可能不支持修改粗細，這時設置也不會生效

renderingStrategy(...) — 渲染策略

決定圖標上色方式：

舉例：

SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
  .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)
  .fontColor([Color.Black, Color.Green])

默認是 SINGLE，只生效數組中的第一個顏色。

effectStrategy(...) — 動效策略

可以給圖標添加動效策略（比如 pulse、fade 等策略，具體支持的效果需要查你的 SDK 版本 API 參考）。如果不設置，它默認無動效。

🔧 四、SymbolGlyph / SymbolSpan 的基本用法

1. 單獨顯示一個系統圖標

SymbolGlyph($r('sys.symbol.ohos_wifi'))
  .fontSize(24)
  .fontColor([Color.Black])

這是最常見的用法，用它替代 Image + ColorTint，方便、輕量。

2. 文本里插入圖標（用 SymbolSpan）

Text() {
  Text('當前狀態：')
  SymbolSpan($r('sys.symbol.ohos_wifi'))
    .fontSize(18)
    .fontColor([Color.Green])
  Text(' 已連接')
}

這種寫法比用多個 Row/Text 組合更乾淨

3. 配合按鈕或 Row 列表使用

如果你有一個帶圖標的按鈕或列表項：

Row({ space: 8, alignItems: ItemAlign.Center }) {
  SymbolGlyph($r('sys.symbol.ohos_folder'))
    .fontSize(20)
    .fontColor([Color.Blue])
  Text('文件夾')
}

這種組合寫法比 Image + Text 更統一，更容易做動態主題/換色處理

五、什麼時候用它最合適

替代靜態圖片圖標

用靜態圖片做圖標會有體積、切圖、縮放、顏色適配的問題，而 SymbolGlyph 是矢量圖標，自動適配尺寸與視網膜屏。

文本 + 圖標混排場景

比如“⭐ 評分 4.8/5”、“ 警告信息”，用 SymbolSpan 能讓你在一段文字裏直接插圖標

UI Icon 統一規範

HarmonyOS 系統圖標預置了大量 sys.symbol.* 資源，你用它可以確保 UI 風格和系統風格一致，無需自己設計圖標庫

六、常見注意事項（實戰總結）

1. 只支持預置資源

SymbolGlyph 和 SymbolSpan 只支持系統預置的 symbol 資源（如 $r('sys.symbol.ohos_wifi')）。引用非 Symbol 資源會導致不可預測的顯示問題。

2. 大小控制要用 fontSize

不要用 width/height 去控制圖標視覺大小，這樣只是改變組件佔位，而不會真正改變圖標尺寸

3. 渲染策略影響顏色

如果你傳了多個顏色數組但渲染策略還是 SINGLE，只會取第一個顏色；如果想多色顯示，一定要配合正確的渲染策略

七、總結（像真實開發者寫的結論）

• SymbolGlyph 是一個輕量矢量圖標組件，用來顯示系統預置符號圖標。
• SymbolSpan 是它在文本里的“內聯”版本，可在 Text 文本流中插入圖標。
• 它們的大小、顏色、粗細和渲染策略可控，並且樣式能很好地和文本/佈局融為一體。
• 在做圖標按鈕、帶圖標的列表項、文本混排等 UI 場景時非常好用。