HarmonyOS 鸿蒙系统自带的 SymbolGlyph 图标组件详解

还在到处的找图标？先来看看系统带的两千多个是否满足。在 HarmonyOS 的应用开发中，SymbolGlyph 是一个非常实用的组件，用于显示系统预置的小图标符号。它不仅支持手机、平板、手表等多种设备，还兼容 ArkTS 卡片和元服务，从API 11开始就已经被引入，并且在API 12及其之后的版本中增加了更多功能，如颜色控制、动效和高级渲染策略等。

这些特性让开发者无需再为UI设计资源而烦恼，涵盖了常用的icon图标资源。同时也能确保开发出的应用与原生鸿蒙风格保持一致。

官方图标库网站：

• HarmonyOS Symbol 主题图标库：
• https://developer.huawei.com/consumer/cn/design/harmonyos-symbol/

官方文档上介绍了两千多种，但是还是不完整。以下为网友总结的所有图标示例：

开源图标库：

• https://gitee.com/awa_Liny/Linys_Ani_Examples_NEXT
• https://github.com/awaLiny2333/Linys_Ani_Examples_NEXT

1. SymbolGlyph 基本介绍和接口

SymbolGlyph 组件通过构造函数接受一个指定的图标资源，该资源必须是系统预置的 symbol 资源，例如 $r('sys.symbol.ohos_wifi')，而不是自定义资源。如果使用不正确的资源，图标将无法正确显示。此外，SymbolGlyph 不支持子组件，也就是说你不能将其他组件嵌入到 SymbolGlyph 中来。

代码示例：

// 创建一个Wi-Fi图标，默认大小
SymbolGlyph($r('sys.symbol.ohos_wifi'))

// 创建一个文件夹图标，并指定资源名称
SymbolGlyph($r('sys.symbol.ohos_folder'))

2. 颜色控制属性：fontColor

fontColor 属性允许你设置图标的颜色。你可以通过数组的方式指定多个颜色，图标会根据渲染策略选择颜色。从API 12开始，fontColor 属性也支持在卡片和元服务中使用。

代码示例：

// 设置单色：黑色
SymbolGlyph($r('sys.symbol.ohos_trash'))
  .fontColor([Color.Black])

// 设置多色：黑、绿、白（实际显示颜色取决于渲染策略）
SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
  .fontColor([Color.Black, Color.Green, Color.White])

3. 大小控制属性：fontSize

fontSize 属性用于控制图标的大小，单位为 fp（比如 "16fp"）。该属性支持数字、字符串或 Resource 类型作为参数。需要注意的是，不要使用百分比形式的字符串，否则会导致错误。图标实际大小仅由 fontSize 决定，即便设置了 width 或 height，它们只会影响组件所占据的空间大小，而不改变图标本身的大小。

代码示例：

// 设置大小为20fp
SymbolGlyph($r('sys.symbol.ohos_wifi'))
  .fontSize(20)

// 使用字符串形式设置大小
SymbolGlyph($r('sys.symbol.ohos_trash'))
  .fontSize("24fp") // 等价于24

4. 粗细控制属性：fontWeight

fontWeight 属性可以调整图标的线条粗细，取值范围从 100 到 900，间隔为 100，也可以使用字符串形式如 "bold" 或 "lighter"。不过，并非所有的图标都支持 fontWeight 属性，比如 sys.symbol.ohos_lungs 就不支持。从API 12开始，fontWeight 属性同样适用于卡片和元服务。

代码示例：

// 设置正常粗细
SymbolGlyph($r('sys.symbol.ohos_trash'))
  .fontWeight(FontWeight.Normal)

// 设置粗体，使用字符串形式
SymbolGlyph($r('sys.symbol.ohos_wifi'))
  .fontWeight("bold")

5. 渲染策略属性：renderingStrategy

renderingStrategy 属性决定了图标的上色方式，有三种模式：SINGLE（单色）、MULTIPLE_COLOR（多色）、MULTIPLE_OPACITY（分层透明）。默认情况下，renderingStrategy 为 SINGLE，只使用数组中的第一个颜色。MULTIPLE_COLOR 和 MULTIPLE_OPACITY 则分别使用最多三个颜色或自动添加透明度。

代码示例：

// 单色模式：只生效第一个颜色（黑色）
SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
  .renderingStrategy(SymbolRenderingStrategy.SINGLE)
  .fontColor([Color.Black, Color.Green])

// 多色模式：三色生效（黑、绿、白）
SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
  .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)
  .fontColor([Color.Black, Color.Green, Color.White])

6. 动效策略属性：effectStrategy

effectStrategy 属性为图标添加动画效果，支持 NONE（无动效）、SCALE（整体缩放）、HIERARCHICAL（层级动效）。在设置 effectStrategy 属性后，动效会自动生效，无需额外触发。需要注意的是，不要将 effectStrategy 和 symbolEffect 属性混用，否则可能会产生冲突。

代码示例：

// 无动效
SymbolGlyph($r('sys.symbol.ohos_wifi'))
  .effectStrategy(SymbolEffectStrategy.NONE)

// 整体缩放动效
SymbolGlyph($r('sys.symbol.ohos_wifi'))
  .effectStrategy(1) // 等价于SymbolEffectStrategy.SCALE

7. 高级动效属性：symbolEffect

symbolEffect 属性提供了更灵活的动效设置方式，支持多种动效类型如缩放、层级、脉冲等，还可以控制播放状态（isActive）或触发器（triggerValue）。从API 12开始支持卡片和元服务。symbolEffect 对象包括 ScaleSymbolEffect（缩放）、HierarchicalSymbolEffect（层级）等，每个对象都有自己的构造参数如 scope（范围）、direction（方向）等，使用 triggerValue 时，图标会在数值变化时触发动效，非常适合交互场景。

代码示例：

// 层级动效，播放状态为true
SymbolGlyph($r('sys.symbol.ohos_wifi'))
  .symbolEffect(new HierarchicalSymbolEffect(EffectFillStyle.ITERATIVE), true)

// 替换动效，由触发器控制
@State triggerValue: number = 0;
SymbolGlyph($r('sys.symbol.checkmark_circle'))
  .symbolEffect(new ReplaceSymbolEffect(), triggerValue)
Button('trigger').onClick(() => {
  this.triggerValue = this.triggerValue + 1;
})

SymbolSpan 和 SymbolGlyph 的异同点

相同点：

1. 都是用于显示图标小符号的组件。
2. 都不支持子组件。
3. 都仅支持系统预置的 symbol 资源名，引用非 symbol 资源将显示异常。

不同点：

1. SymbolSpan 仅支持作为 Text 组件的子组件，而 SymbolGlyph 不能作为 Text 组件的子组件。

示例代码

示例1：设置渲染和动效策略

// xxx.ets
@Entry
@Component
struct Index {
  build() {
    Column() {
      Row() {
        Column() {
          Text("Light")
          SymbolGlyph($r('sys.symbol.ohos_trash'))
            .fontWeight(FontWeight.Lighter)
            .fontSize(96)
        }

        Column() {
          Text("Normal")
          SymbolGlyph($r('sys.symbol.ohos_trash'))
            .fontWeight(FontWeight.Normal)
            .fontSize(96)
        }

        Column() {
          Text("Bold")
          SymbolGlyph($r('sys.symbol.ohos_trash'))
            .fontWeight(FontWeight.Bold)
            .fontSize(96)
        }
      }

      Row() {
        Column() {
          Text("单色")
          SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
            .fontSize(96)
            .renderingStrategy(SymbolRenderingStrategy.SINGLE)
            .fontColor([Color.Black, Color.Green, Color.White])
        }

        Column() {
          Text("多色")
          SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
            .fontSize(96)
            .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_COLOR)
            .fontColor([Color.Black, Color.Green, Color.White])
        }

        Column() {
          Text("分层")
          SymbolGlyph($r('sys.symbol.ohos_folder_badge_plus'))
            .fontSize(96)
            .renderingStrategy(SymbolRenderingStrategy.MULTIPLE_OPACITY)
            .fontColor([Color.Black, Color.Green, Color.White])
        }
      }

      Row() {
        Column() {
          Text("无动效")
          SymbolGlyph($r('sys.symbol.ohos_wifi'))
            .fontSize(96)
            .effectStrategy(SymbolEffectStrategy.NONE)
        }

        Column() {
          Text("整体缩放动效")
          SymbolGlyph($r('sys.symbol.ohos_wifi'))
            .fontSize(96)
            .effectStrategy(1) // 等价于SymbolEffectStrategy.SCALE
        }

        Column() {
          Text("层级动效")
          SymbolGlyph($r('sys.symbol.ohos_wifi'))
            .fontSize(96)
            .effectStrategy(2) // 等价于SymbolEffectStrategy.HIERARCHICAL
        }
      }
    }
  }
}

示例2：设置动效

// xxx.ets
@Entry
@Component
struct Index {
  @State isActive: boolean = true;
  @State triggerValueReplace: number = 0;
  replaceFlag: boolean = true;

  build() {
    Column() {
      Row() {
        Column() {
          Text("可变颜色动效")
          SymbolGlyph($r('sys.symbol.ohos_wifi'))
            .fontSize(96)
            .symbolEffect(new HierarchicalSymbolEffect(EffectFillStyle.ITERATIVE), this.isActive)
          Button(this.isActive ? '关闭' : '播放').onClick(() => {
            this.isActive = !this.isActive;
          })
        }.margin({ right: 20 })

        Column() {
          Text("替换动效")
          SymbolGlyph(this.replaceFlag ? $r('sys.symbol.checkmark_circle') : $r('sys.symbol.repeat_1'))
            .fontSize(96)
            .symbolEffect(new ReplaceSymbolEffect(EffectScope.WHOLE), this.triggerValueReplace)
          Button('trigger').onClick(() => {
            this.replaceFlag = !this.replaceFlag;
            this.triggerValueReplace = this.triggerValueReplace + 1;
          })
        }
      }
    }.margin({
      left: 30,
      top: 50
    })
  }
}

SymbolGlyph 真正是一个宝藏组件！从基础的图标显示到复杂的动效设计，它都能胜任。通过 fontColor、fontSize、renderingStrategy 等属性，你可以轻松定制图标的外观；effectStrategy 和 symbolEffect 则让图标能够动起来，提升用户体验。记住关键点：只使用系统资源、避免属性混用、多利用枚举简化代码。结合事件支持，你能够创建出超交互的界面。希望这篇口语化解析能够帮助你快速上手 SymbolGlyph，所有代码示例都可以直接复制到你的项目中使用。

参考文档：

• SymbolSpan 参考文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V13/ts-basic-components-symbolspan-V13
• SymbolGlyph 参考文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V13/ts-basic-components-symbolglyph-V13

参考链接:

• HarmonyOS Symbol 主题图标库
• Zhihu 技术文章
• Bilibili 视频
• CSDN 文章