swiftui-iconography-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SF Symbols & Iconography API Reference

SF Symbols 与图标API参考

Lifecycle Position

生命周期定位

Phase 3 API Reference — load during implementation when using SF Symbols or custom icons. Dispatched from

autonomous-ui-workflow

Phase 2 research table.

第三阶段API参考——在使用SF Symbols或自定义图标的实现阶段加载。从

autonomous-ui-workflow

第二阶段研究表调度。

Quick Reference

快速参考

API	Purpose
`Image(systemName:)`	System SF Symbol
`Image(systemName:variableValue:)`	Symbol with 0.0-1.0 value
`.symbolRenderingMode(_:)`	Set rendering mode
`.symbolVariant(_:)`	Add variant (.fill, .circle)
`.symbolEffect(_:)`	Animate symbol
`.foregroundStyle(_:_:)`	Palette colors (implies palette mode)

API	用途
`Image(systemName:)`	系统SF Symbol
`Image(systemName:variableValue:)`	带有0.0-1.0变量值的Symbol
`.symbolRenderingMode(_:)`	设置渲染模式
`.symbolVariant(_:)`	添加变体（.fill、.circle）
`.symbolEffect(_:)`	为Symbol添加动画
`.foregroundStyle(_:_:)`	调色板颜色（隐含调色板模式）

Rendering Modes

渲染模式

Mode	Usage
`.monochrome`	Single color: `.symbolRenderingMode(.monochrome).foregroundStyle(.purple)`
`.hierarchical`	Layered opacity: `.symbolRenderingMode(.hierarchical).foregroundStyle(.purple)`
`.multicolor`	Inherent colors: `.symbolRenderingMode(.multicolor)`
`.palette`	Custom per-layer: `.foregroundStyle(.yellow, .cyan)`

模式	用法
`.monochrome`	单一颜色： `.symbolRenderingMode(.monochrome).foregroundStyle(.purple)`
`.hierarchical`	分层透明度： `.symbolRenderingMode(.hierarchical).foregroundStyle(.purple)`
`.multicolor`	固有颜色： `.symbolRenderingMode(.multicolor)`
`.palette`	自定义分层颜色： `.foregroundStyle(.yellow, .cyan)`

Symbol Effects

符号效果

swift

// Indefinite (repeating)
Image(systemName: "bolt.slash.fill").symbolEffect(.pulse)

// Active/inactive
Image(systemName: "wifi").symbolEffect(.pulse, isActive: isConnecting)

// Value-driven
Image(systemName: "bell").symbolEffect(.bounce, value: count)

// As transition
.transition(.symbolEffect(.appear))

swift

// Indefinite (repeating)
Image(systemName: "bolt.slash.fill").symbolEffect(.pulse)

// Active/inactive
Image(systemName: "wifi").symbolEffect(.pulse, isActive: isConnecting)

// Value-driven
Image(systemName: "bell").symbolEffect(.bounce, value: count)

// As transition
.transition(.symbolEffect(.appear))

Variable Values

变量值

swift

Image(systemName: "chart.bar.fill", variableValue: 0.3)  // partial
Image(systemName: "chart.bar.fill", variableValue: 1.0)  // full

swift

Image(systemName: "chart.bar.fill", variableValue: 0.3)  // partial
Image(systemName: "chart.bar.fill", variableValue: 1.0)  // full

When to Use Which

场景选择指南

Need	Use
Standard system icon	`Image(systemName: "star.fill")`
Icon with accessible label	`Label("Favorites", systemImage: "star.fill")` (preferred in buttons/toolbars)
Icon matching adjacent text weight	`.fontWeight(.semibold)` on Image to match Text
Animated symbol feedback	`.symbolEffect(.bounce, value: trigger)`
Progress/level indicator	`Image(systemName: "wifi", variableValue: 0.5)`
Multi-color system icon	`.symbolRenderingMode(.multicolor)`
Icon tinted to match theme	`.symbolRenderingMode(.palette)` with `foregroundStyle(.red, .blue)`
Custom app icon	Asset catalog → Symbol Image Set → export from SF Symbols app

需求	对应方案
标准系统图标	`Image(systemName: "star.fill")`
带无障碍标签的图标	`Label("收藏", systemImage: "star.fill")` （按钮/工具栏中优先使用）
图标权重与相邻文本匹配	为Image设置 `.fontWeight(.semibold)` 以匹配文本
带动画反馈的符号	`.symbolEffect(.bounce, value: trigger)`
进度/等级指示器	`Image(systemName: "wifi", variableValue: 0.5)`
多色系统图标	`.symbolRenderingMode(.multicolor)`
匹配主题色调的图标	使用 `.symbolRenderingMode(.palette)` 搭配 `foregroundStyle(.red, .blue)`
自定义应用图标	资源目录 → Symbol Image Set → 从SF Symbols应用导出

Common Mistakes

常见错误

```
Image(systemName:)
```
without
```
Label
```
in buttons — no accessibility text for VoiceOver
Mismatched symbol weight with adjacent text — icons look too thin/thick next to text. Match with
```
.fontWeight()
```
or
```
.imageScale()
```
Using
```
.resizable().frame()
```
for sizing instead of
```
.font()
```
— breaks alignment with text. Use
```
.font(.title)
```
to match text size
Missing
```
.symbolRenderingMode()
```
— defaults to monochrome which may not match design intent
Hardcoded symbol names without checking SF Symbols availability — some symbols require iOS 16+ or 17+

Before (incorrect):

swift

Button(action: addFavorite) {
    Image(systemName: "star.fill")  // no label — VoiceOver reads nothing useful
}

After (correct):

swift

Button(action: addFavorite) {
    Label("Add to Favorites", systemImage: "star.fill")
}

Before (incorrect):

swift

Image(systemName: "heart.fill")
    .resizable()
    .frame(width: 24, height: 24)  // disrupts text baseline alignment

After (correct):

swift

Image(systemName: "heart.fill")
    .font(.title2)  // scales with Dynamic Type and aligns with text

按钮中使用
```
Image(systemName:)
```
而非
```
Label
```
——VoiceOver无法读取有用的无障碍文本
图标权重与相邻文本不匹配——图标在文本旁显得过细或过粗。使用
```
.fontWeight()
```
或
```
.imageScale()
```
匹配
使用
```
.resizable().frame()
```
调整尺寸而非
```
.font()
```
——破坏与文本的基线对齐。使用
```
.font(.title)
```
匹配文本尺寸
未设置
```
.symbolRenderingMode()
```
——默认单色模式可能不符合设计意图
硬编码符号名称而未检查SF Symbols的可用性——部分符号需要iOS 16+或17+

错误写法：

swift

Button(action: addFavorite) {
    Image(systemName: "star.fill")  // no label — VoiceOver reads nothing useful
}

正确写法：

swift

Button(action: addFavorite) {
    Label("添加到收藏", systemImage: "star.fill")
}

错误写法：

swift

Image(systemName: "heart.fill")
    .resizable()
    .frame(width: 24, height: 24)  // disrupts text baseline alignment

正确写法：

swift

Image(systemName: "heart.fill")
    .font(.title2)  // scales with Dynamic Type and aligns with text

Checklist

检查清单

Buttons and toolbar items use
```
Label("text", systemImage:)
```
not bare
```
Image
```
Icon weight matches adjacent text weight

Icon sizing uses

.font()

.imageScale()

not

.resizable().frame()

Rendering mode explicitly set when multicolor or palette needed
Symbol availability checked for newer symbols (
```
@available
```
)

按钮和工具栏项使用
```
Label("文本", systemImage:)
```
而非单独的
```
Image
```
图标权重与相邻文本权重匹配

图标尺寸使用

.font()

或

.imageScale()

而非

.resizable().frame()

当需要多色或调色板模式时，显式设置渲染模式
检查新版符号的可用性（使用
```
@available
```
）

Cross-References

交叉引用

```
swiftui-colors-api
```
—
```
foregroundStyle()
```
for symbol tinting
```
swiftui-ui-patterns
```
— review checklist includes accessibility label checks
```
macos-app-design
```
— macOS toolbar icon conventions

```
swiftui-colors-api
```
— 用于符号着色的
```
foregroundStyle()
```
```
swiftui-ui-patterns
```
— 检查清单包含无障碍标签检查
```
macos-app-design
```
— macOS工具栏图标规范