axiom-sf-symbols-ref

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SF Symbols — API Reference

SF Symbols — API参考文档

When to Use This Skill

何时使用此技能

Use when:

You need exact API signatures for rendering modes or symbol effects
You need UIKit/AppKit equivalents for SwiftUI symbol APIs
You need to check platform availability for a specific effect
You need configuration options (weight, scale, variable values)
You need to create custom symbols with proper template structure

适用于以下场景：

你需要渲染模式或符号效果的精确API签名
你需要SwiftUI符号API对应的UIKit/AppKit等效实现
你需要检查特定效果的平台兼容性
你需要配置选项（字重、缩放、变量值）
你需要创建具有正确模板结构的自定义符号

Related Skills

Part 1: Symbol Display

第一部分：符号显示

SwiftUI

swift

// Basic display
Image(systemName: "star.fill")

// With Label (icon + text)
Label("Favorites", systemImage: "star.fill")

// Font sizing — symbol scales with text
Image(systemName: "star.fill")
    .font(.title)

// Image scale — relative sizing without changing font
Image(systemName: "star.fill")
    .imageScale(.large) // .small, .medium, .large

// Explicit point size
Image(systemName: "star.fill")
    .font(.system(size: 24))

// Weight — matches SF Pro font weights
Image(systemName: "star.fill")
    .fontWeight(.bold) // .ultraLight through .black

// Symbol variant — programmatic .fill, .circle, .square, .slash
Image(systemName: "person")
    .symbolVariant(.circle.fill) // Renders person.circle.fill

// Variable value — 0.0 to 1.0, controls symbol fill level
Image(systemName: "speaker.wave.3.fill", variableValue: 0.5)

swift

// Basic display
Image(systemName: "star.fill")

// With Label (icon + text)
Label("Favorites", systemImage: "star.fill")

// Font sizing — symbol scales with text
Image(systemName: "star.fill")
    .font(.title)

// Image scale — relative sizing without changing font
Image(systemName: "star.fill")
    .imageScale(.large) // .small, .medium, .large

// Explicit point size
Image(systemName: "star.fill")
    .font(.system(size: 24))

// Weight — matches SF Pro font weights
Image(systemName: "star.fill")
    .fontWeight(.bold) // .ultraLight through .black

// Symbol variant — programmatic .fill, .circle, .square, .slash
Image(systemName: "person")
    .symbolVariant(.circle.fill) // Renders person.circle.fill

// Variable value — 0.0 to 1.0, controls symbol fill level
Image(systemName: "speaker.wave.3.fill", variableValue: 0.5)

UIKit

swift

// Basic display
let image = UIImage(systemName: "star.fill")
imageView.image = image

// Configuration — point size and weight
let config = UIImage.SymbolConfiguration(pointSize: 24, weight: .bold)
let image = UIImage(systemName: "star.fill", withConfiguration: config)

// Configuration — text style (scales with Dynamic Type)
let config = UIImage.SymbolConfiguration(textStyle: .title1)
let image = UIImage(systemName: "star.fill", withConfiguration: config)

// Configuration — scale
let config = UIImage.SymbolConfiguration(scale: .large) // .small, .medium, .large

// Combine configurations
let sizeConfig = UIImage.SymbolConfiguration(pointSize: 24, weight: .bold, scale: .large)

// Variable value
let image = UIImage(systemName: "speaker.wave.3.fill", variableValue: 0.5)

swift

// Basic display
let image = UIImage(systemName: "star.fill")
imageView.image = image

// Configuration — point size and weight
let config = UIImage.SymbolConfiguration(pointSize: 24, weight: .bold)
let image = UIImage(systemName: "star.fill", withConfiguration: config)

// Configuration — text style (scales with Dynamic Type)
let config = UIImage.SymbolConfiguration(textStyle: .title1)
let image = UIImage(systemName: "star.fill", withConfiguration: config)

// Configuration — scale
let config = UIImage.SymbolConfiguration(scale: .large) // .small, .medium, .large

// Combine configurations
let sizeConfig = UIImage.SymbolConfiguration(pointSize: 24, weight: .bold, scale: .large)

// Variable value
let image = UIImage(systemName: "speaker.wave.3.fill", variableValue: 0.5)

AppKit

swift

// Basic display
let image = NSImage(systemSymbolName: "star.fill", accessibilityDescription: "Favorite")

// Configuration
let config = NSImage.SymbolConfiguration(pointSize: 24, weight: .bold)
let configured = image?.withSymbolConfiguration(config)

swift

// Basic display
let image = NSImage(systemSymbolName: "star.fill", accessibilityDescription: "Favorite")

// Configuration
let config = NSImage.SymbolConfiguration(pointSize: 24, weight: .bold)
let configured = image?.withSymbolConfiguration(config)

Part 2: Rendering Modes

第二部分：渲染模式

SwiftUI

swift

// Monochrome (default)
Image(systemName: "cloud.rain.fill")
    .foregroundStyle(.blue)

// Hierarchical — depth from single color
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.hierarchical)
    .foregroundStyle(.blue)

// Palette — explicit color per layer
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.palette)
    .foregroundStyle(.white, .blue)
// For 3-layer symbols:
    .foregroundStyle(.red, .white, .blue)

// Multicolor — Apple's curated colors
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.multicolor)

// Preferred rendering mode — uses symbol's preferred mode
// Falls back gracefully if the symbol doesn't support it
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.monochrome) // explicit monochrome

swift

// Monochrome (default)
Image(systemName: "cloud.rain.fill")
    .foregroundStyle(.blue)

// Hierarchical — depth from single color
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.hierarchical)
    .foregroundStyle(.blue)

// Palette — explicit color per layer
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.palette)
    .foregroundStyle(.white, .blue)
// For 3-layer symbols:
    .foregroundStyle(.red, .white, .blue)

// Multicolor — Apple's curated colors
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.multicolor)

// Preferred rendering mode — uses symbol's preferred mode
// Falls back gracefully if the symbol doesn't support it
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.monochrome) // explicit monochrome

SymbolRenderingMode Enum

SymbolRenderingMode枚举

Value	Description
`.monochrome`	Single color for all layers (default)
`.hierarchical`	Single color with automatic opacity per layer
`.palette`	Explicit color per layer via `.foregroundStyle()`
`.multicolor`	Apple's fixed curated colors

值	描述
`.monochrome`	所有图层使用单一颜色（默认）
`.hierarchical`	单一颜色，各图层自动调整透明度以体现层次
`.palette`	通过 `.foregroundStyle()` 为每个图层指定明确颜色
`.multicolor`	使用Apple预设的专属配色

UIKit

swift

// Hierarchical
let config = UIImage.SymbolConfiguration(hierarchicalColor: .systemBlue)
imageView.preferredSymbolConfiguration = config

// Palette
let config = UIImage.SymbolConfiguration(paletteColors: [.white, .systemBlue])
imageView.preferredSymbolConfiguration = config

// Multicolor
let config = UIImage.SymbolConfiguration.preferringMulticolor()
imageView.preferredSymbolConfiguration = config

// Monochrome — just set tintColor
imageView.tintColor = .systemBlue

swift

// Hierarchical
let config = UIImage.SymbolConfiguration(hierarchicalColor: .systemBlue)
imageView.preferredSymbolConfiguration = config

// Palette
let config = UIImage.SymbolConfiguration(paletteColors: [.white, .systemBlue])
imageView.preferredSymbolConfiguration = config

// Multicolor
let config = UIImage.SymbolConfiguration.preferringMulticolor()
imageView.preferredSymbolConfiguration = config

// Monochrome — just set tintColor
imageView.tintColor = .systemBlue

Combining Configurations (UIKit)

组合配置（UIKit）

swift

let sizeConfig = UIImage.SymbolConfiguration(pointSize: 24, weight: .bold)
let colorConfig = UIImage.SymbolConfiguration(paletteColors: [.white, .blue, .gray])
let combined = sizeConfig.applying(colorConfig)
imageView.preferredSymbolConfiguration = combined

swift

let sizeConfig = UIImage.SymbolConfiguration(pointSize: 24, weight: .bold)
let colorConfig = UIImage.SymbolConfiguration(paletteColors: [.white, .blue, .gray])
let combined = sizeConfig.applying(colorConfig)
imageView.preferredSymbolConfiguration = combined

Part 3: Symbol Effects — Complete API

第三部分：符号效果——完整API

Effect Protocol Hierarchy

效果协议层级

All symbol effects conform to

SymbolEffect

. Sub-protocols define behavior:

Protocol	Trigger	Modifier	Loop
`DiscreteSymbolEffect`	`value:` (Equatable)	`.symbolEffect(_:options:value:)`	No
`IndefiniteSymbolEffect`	`isActive:` (Bool)	`.symbolEffect(_:options:isActive:)`	Yes
`TransitionSymbolEffect`	View lifecycle	`.transition(.symbolEffect(_:))`	No
`ContentTransitionSymbolEffect`	Symbol change	`.contentTransition(.symbolEffect(_:))`	No

所有符号效果均遵循

SymbolEffect

协议。子协议定义不同行为：

协议	触发方式	修改器	是否循环
`DiscreteSymbolEffect`	`value:` （遵循Equatable）	`.symbolEffect(_:options:value:)`	否
`IndefiniteSymbolEffect`	`isActive:` （Bool类型）	`.symbolEffect(_:options:isActive:)`	是
`TransitionSymbolEffect`	视图生命周期	`.transition(.symbolEffect(_:))`	否
`ContentTransitionSymbolEffect`	符号变更	`.contentTransition(.symbolEffect(_:))`	否

Remove All Effects (SwiftUI)

移除所有效果（SwiftUI）

swift

// Strip all symbol effects from a view hierarchy
Image(systemName: "star.fill")
    .symbolEffectsRemoved() // Removes all effects
    .symbolEffectsRemoved(false) // Re-enables effects

swift

// Strip all symbol effects from a view hierarchy
Image(systemName: "star.fill")
    .symbolEffectsRemoved() // Removes all effects
    .symbolEffectsRemoved(false) // Re-enables effects

SymbolEffectOptions

swift

// Speed multiplier
.symbolEffect(.bounce, options: .speed(2.0), value: count)

// Repeat count
.symbolEffect(.bounce, options: .repeat(3), value: count)

// Continuous repeat
.symbolEffect(.pulse, options: .repeat(.continuous), isActive: true)

// Non-repeating (for indefinite effects, run once then hold)
.symbolEffect(.breathe, options: .nonRepeating, isActive: true)

// Combined
.symbolEffect(.wiggle, options: .repeat(5).speed(1.5), value: count)

swift

// Speed multiplier
.symbolEffect(.bounce, options: .speed(2.0), value: count)

// Repeat count
.symbolEffect(.bounce, options: .repeat(3), value: count)

// Continuous repeat
.symbolEffect(.pulse, options: .repeat(.continuous), isActive: true)

// Non-repeating (for indefinite effects, run once then hold)
.symbolEffect(.breathe, options: .nonRepeating, isActive: true)

// Combined
.symbolEffect(.wiggle, options: .repeat(5).speed(1.5), value: count)

Bounce

弹跳效果（Bounce）

Protocols:

DiscreteSymbolEffect

swift

// Discrete — triggers on value change
Image(systemName: "arrow.down.circle")
    .symbolEffect(.bounce, value: downloadCount)

// Directional
    .symbolEffect(.bounce.up, value: count)
    .symbolEffect(.bounce.down, value: count)

// By Layer — different layers bounce at different times
    .symbolEffect(.bounce.byLayer, value: count)

// Whole Symbol — entire symbol bounces together
    .symbolEffect(.bounce.wholeSymbol, value: count)

UIKit:

swift

imageView.addSymbolEffect(.bounce)
// With options:
imageView.addSymbolEffect(.bounce, options: .repeat(3))

遵循协议：

DiscreteSymbolEffect

swift

// Discrete — triggers on value change
Image(systemName: "arrow.down.circle")
    .symbolEffect(.bounce, value: downloadCount)

// Directional
    .symbolEffect(.bounce.up, value: count)
    .symbolEffect(.bounce.down, value: count)

// By Layer — different layers bounce at different times
    .symbolEffect(.bounce.byLayer, value: count)

// Whole Symbol — entire symbol bounces together
    .symbolEffect(.bounce.wholeSymbol, value: count)

UIKit实现:

swift

imageView.addSymbolEffect(.bounce)
// With options:
imageView.addSymbolEffect(.bounce, options: .repeat(3))

Pulse

脉冲效果（Pulse）

Protocols:

DiscreteSymbolEffect

IndefiniteSymbolEffect

swift

// Indefinite — continuous while active
Image(systemName: "network")
    .symbolEffect(.pulse, isActive: isConnecting)

// Discrete — triggers once on value change
    .symbolEffect(.pulse, value: errorCount)

// By Layer
    .symbolEffect(.pulse.byLayer, isActive: true)

// Whole Symbol
    .symbolEffect(.pulse.wholeSymbol, isActive: true)

UIKit:

swift

imageView.addSymbolEffect(.pulse)
imageView.removeSymbolEffect(ofType: PulseSymbolEffect.self)

遵循协议：

DiscreteSymbolEffect

IndefiniteSymbolEffect

swift

// Indefinite — continuous while active
Image(systemName: "network")
    .symbolEffect(.pulse, isActive: isConnecting)

// Discrete — triggers once on value change
    .symbolEffect(.pulse, value: errorCount)

// By Layer
    .symbolEffect(.pulse.byLayer, isActive: true)

// Whole Symbol
    .symbolEffect(.pulse.wholeSymbol, isActive: true)

UIKit实现:

swift

imageView.addSymbolEffect(.pulse)
imageView.removeSymbolEffect(ofType: PulseSymbolEffect.self)

Variable Color

可变颜色效果（Variable Color）

Protocols:

DiscreteSymbolEffect

IndefiniteSymbolEffect

swift

// Iterative — highlights one layer at a time
Image(systemName: "wifi")
    .symbolEffect(.variableColor.iterative, isActive: isSearching)

// Cumulative — progressively fills layers
    .symbolEffect(.variableColor.cumulative, isActive: true)

// Reversing — cycles back and forth
    .symbolEffect(.variableColor.iterative.reversing, isActive: true)

// Hide inactive layers (dims non-highlighted layers)
    .symbolEffect(.variableColor.iterative.hideInactiveLayers, isActive: true)

// Dim inactive layers (slightly reduces opacity of non-highlighted)
    .symbolEffect(.variableColor.iterative.dimInactiveLayers, isActive: true)

UIKit:

swift

imageView.addSymbolEffect(.variableColor.iterative)
imageView.removeSymbolEffect(ofType: VariableColorSymbolEffect.self)

遵循协议：

DiscreteSymbolEffect

IndefiniteSymbolEffect

swift

// Iterative — highlights one layer at a time
Image(systemName: "wifi")
    .symbolEffect(.variableColor.iterative, isActive: isSearching)

// Cumulative — progressively fills layers
    .symbolEffect(.variableColor.cumulative, isActive: true)

// Reversing — cycles back and forth
    .symbolEffect(.variableColor.iterative.reversing, isActive: true)

// Hide inactive layers (dims non-highlighted layers)
    .symbolEffect(.variableColor.iterative.hideInactiveLayers, isActive: true)

// Dim inactive layers (slightly reduces opacity of non-highlighted)
    .symbolEffect(.variableColor.iterative.dimInactiveLayers, isActive: true)

UIKit实现:

swift

imageView.addSymbolEffect(.variableColor.iterative)
imageView.removeSymbolEffect(ofType: VariableColorSymbolEffect.self)

Scale

缩放效果（Scale）

Protocols:

IndefiniteSymbolEffect

swift

// Scale up
Image(systemName: "mic.fill")
    .symbolEffect(.scale.up, isActive: isRecording)

// Scale down
    .symbolEffect(.scale.down, isActive: isMuted)

// By Layer
    .symbolEffect(.scale.up.byLayer, isActive: true)

// Whole Symbol
    .symbolEffect(.scale.up.wholeSymbol, isActive: true)

UIKit:

swift

imageView.addSymbolEffect(.scale.up)
imageView.removeSymbolEffect(ofType: ScaleSymbolEffect.self)

遵循协议：

IndefiniteSymbolEffect

swift

// Scale up
Image(systemName: "mic.fill")
    .symbolEffect(.scale.up, isActive: isRecording)

// Scale down
    .symbolEffect(.scale.down, isActive: isMuted)

// By Layer
    .symbolEffect(.scale.up.byLayer, isActive: true)

// Whole Symbol
    .symbolEffect(.scale.up.wholeSymbol, isActive: true)

UIKit实现:

swift

imageView.addSymbolEffect(.scale.up)
imageView.removeSymbolEffect(ofType: ScaleSymbolEffect.self)

Wiggle (iOS 18+)

摇摆效果（Wiggle，iOS 18+）

Protocols:

DiscreteSymbolEffect

IndefiniteSymbolEffect

swift

// Discrete
Image(systemName: "bell.fill")
    .symbolEffect(.wiggle, value: notificationCount)

// Directional
    .symbolEffect(.wiggle.left, value: count)
    .symbolEffect(.wiggle.right, value: count)
    .symbolEffect(.wiggle.forward, value: count)  // RTL-aware
    .symbolEffect(.wiggle.backward, value: count)  // RTL-aware
    .symbolEffect(.wiggle.up, value: count)
    .symbolEffect(.wiggle.down, value: count)
    .symbolEffect(.wiggle.clockwise, value: count)
    .symbolEffect(.wiggle.counterClockwise, value: count)

// Custom angle
    .symbolEffect(.wiggle.custom(angle: .degrees(15)), value: count)

// By Layer
    .symbolEffect(.wiggle.byLayer, value: count)

UIKit:

swift

imageView.addSymbolEffect(.wiggle)

遵循协议：

DiscreteSymbolEffect

IndefiniteSymbolEffect

swift

// Discrete
Image(systemName: "bell.fill")
    .symbolEffect(.wiggle, value: notificationCount)

// Directional
    .symbolEffect(.wiggle.left, value: count)
    .symbolEffect(.wiggle.right, value: count)
    .symbolEffect(.wiggle.forward, value: count)  // 支持RTL布局
    .symbolEffect(.wiggle.backward, value: count)  // 支持RTL布局
    .symbolEffect(.wiggle.up, value: count)
    .symbolEffect(.wiggle.down, value: count)
    .symbolEffect(.wiggle.clockwise, value: count)
    .symbolEffect(.wiggle.counterClockwise, value: count)

// Custom angle
    .symbolEffect(.wiggle.custom(angle: .degrees(15)), value: count)

// By Layer
    .symbolEffect(.wiggle.byLayer, value: count)

UIKit实现:

swift

imageView.addSymbolEffect(.wiggle)

Rotate (iOS 18+)

旋转效果（Rotate，iOS 18+）

Protocols:

DiscreteSymbolEffect

IndefiniteSymbolEffect

swift

// Indefinite rotation
Image(systemName: "gear")
    .symbolEffect(.rotate, isActive: isProcessing)

// Direction
    .symbolEffect(.rotate.clockwise, isActive: true)
    .symbolEffect(.rotate.counterClockwise, isActive: true)

// By Layer — only specific layers rotate (e.g., fan blades)
    .symbolEffect(.rotate.byLayer, isActive: true)

UIKit:

swift

imageView.addSymbolEffect(.rotate)
imageView.removeSymbolEffect(ofType: RotateSymbolEffect.self)

遵循协议：

DiscreteSymbolEffect

IndefiniteSymbolEffect

swift

// Indefinite rotation
Image(systemName: "gear")
    .symbolEffect(.rotate, isActive: isProcessing)

// Direction
    .symbolEffect(.rotate.clockwise, isActive: true)
    .symbolEffect(.rotate.counterClockwise, isActive: true)

// By Layer — only specific layers rotate (e.g., fan blades)
    .symbolEffect(.rotate.byLayer, isActive: true)

UIKit实现:

swift

imageView.addSymbolEffect(.rotate)
imageView.removeSymbolEffect(ofType: RotateSymbolEffect.self)

Breathe (iOS 18+)

呼吸效果（Breathe，iOS 18+）

Protocols:

DiscreteSymbolEffect

IndefiniteSymbolEffect

swift

// Basic breathe
Image(systemName: "heart.fill")
    .symbolEffect(.breathe, isActive: isMonitoring)

// Plain — scale only
    .symbolEffect(.breathe.plain, isActive: true)

// Pulse — scale + opacity variation
    .symbolEffect(.breathe.pulse, isActive: true)

// By Layer
    .symbolEffect(.breathe.byLayer, isActive: true)

UIKit:

swift

imageView.addSymbolEffect(.breathe)
imageView.removeSymbolEffect(ofType: BreatheSymbolEffect.self)

遵循协议：

DiscreteSymbolEffect

IndefiniteSymbolEffect

swift

// Basic breathe
Image(systemName: "heart.fill")
    .symbolEffect(.breathe, isActive: isMonitoring)

// Plain — scale only
    .symbolEffect(.breathe.plain, isActive: true)

// Pulse — scale + opacity variation
    .symbolEffect(.breathe.pulse, isActive: true)

// By Layer
    .symbolEffect(.breathe.byLayer, isActive: true)

UIKit实现:

swift

imageView.addSymbolEffect(.breathe)
imageView.removeSymbolEffect(ofType: BreatheSymbolEffect.self)

Appear and Disappear

出现与消失效果（Appear and Disappear）

Protocols:

TransitionSymbolEffect

swift

// SwiftUI transition
if showSymbol {
    Image(systemName: "checkmark.circle.fill")
        .transition(.symbolEffect(.appear))
}

if showSymbol {
    Image(systemName: "xmark.circle.fill")
        .transition(.symbolEffect(.disappear))
}

// Directional
    .transition(.symbolEffect(.appear.up))
    .transition(.symbolEffect(.appear.down))
    .transition(.symbolEffect(.disappear.up))
    .transition(.symbolEffect(.disappear.down))

// By Layer
    .transition(.symbolEffect(.appear.byLayer))

// Whole Symbol
    .transition(.symbolEffect(.appear.wholeSymbol))

UIKit (as effect, not transition):

swift

// Make symbol appear
imageView.addSymbolEffect(.appear)

// Make symbol disappear
imageView.addSymbolEffect(.disappear)

// Appear after disappear
imageView.addSymbolEffect(.appear) // re-shows hidden symbol

遵循协议：

TransitionSymbolEffect

swift

// SwiftUI transition
if showSymbol {
    Image(systemName: "checkmark.circle.fill")
        .transition(.symbolEffect(.appear))
}

if showSymbol {
    Image(systemName: "xmark.circle.fill")
        .transition(.symbolEffect(.disappear))
}

// Directional
    .transition(.symbolEffect(.appear.up))
    .transition(.symbolEffect(.appear.down))
    .transition(.symbolEffect(.disappear.up))
    .transition(.symbolEffect(.disappear.down))

// By Layer
    .transition(.symbolEffect(.appear.byLayer))

// Whole Symbol
    .transition(.symbolEffect(.appear.wholeSymbol))

UIKit实现（作为效果，而非转场）:

swift

// Make symbol appear
imageView.addSymbolEffect(.appear)

// Make symbol disappear
imageView.addSymbolEffect(.disappear)

// Appear after disappear
imageView.addSymbolEffect(.appear) // re-shows hidden symbol

Replace

替换效果（Replace）

Protocols:

ContentTransitionSymbolEffect

swift

// SwiftUI content transition
Image(systemName: isFavorite ? "star.fill" : "star")
    .contentTransition(.symbolEffect(.replace))

// Directional variants
    .contentTransition(.symbolEffect(.replace.downUp))
    .contentTransition(.symbolEffect(.replace.upUp))
    .contentTransition(.symbolEffect(.replace.offUp))

// By Layer
    .contentTransition(.symbolEffect(.replace.byLayer))

// Whole Symbol
    .contentTransition(.symbolEffect(.replace.wholeSymbol))

// Magic Replace — default in iOS 18+, morphs shared elements
// Automatic for structurally related pairs: star ↔ star.fill, pause.fill ↔ play.fill
    .contentTransition(.symbolEffect(.replace))

// Explicit Magic Replace with fallback for unrelated symbols
    .contentTransition(.symbolEffect(.replace.magic(fallback: .replace.downUp)))

UIKit:

swift

// Change symbol with Replace transition
let newImage = UIImage(systemName: "star.fill")
imageView.setSymbolImage(newImage!, contentTransition: .replace)

// Directional
imageView.setSymbolImage(newImage!, contentTransition: .replace.downUp)

遵循协议：

ContentTransitionSymbolEffect

swift

// SwiftUI content transition
Image(systemName: isFavorite ? "star.fill" : "star")
    .contentTransition(.symbolEffect(.replace))

// Directional variants
    .contentTransition(.symbolEffect(.replace.downUp))
    .contentTransition(.symbolEffect(.replace.upUp))
    .contentTransition(.symbolEffect(.replace.offUp))

// By Layer
    .contentTransition(.symbolEffect(.replace.byLayer))

// Whole Symbol
    .contentTransition(.symbolEffect(.replace.wholeSymbol))

// Magic Replace — default in iOS 18+, morphs shared elements
// Automatic for structurally related pairs: star ↔ star.fill, pause.fill ↔ play.fill
    .contentTransition(.symbolEffect(.replace))

// Explicit Magic Replace with fallback for unrelated symbols
    .contentTransition(.symbolEffect(.replace.magic(fallback: .replace.downUp)))

UIKit实现:

swift

// Change symbol with Replace transition
let newImage = UIImage(systemName: "star.fill")
imageView.setSymbolImage(newImage!, contentTransition: .replace)

// Directional
imageView.setSymbolImage(newImage!, contentTransition: .replace.downUp)

Part 4: Draw Effects (iOS 26+)

第四部分：绘制效果（Draw Effects，iOS 26+）

Draw On

绘制出现（Draw On）

swift

// Indefinite — draws in while active
Image(systemName: "checkmark.circle")
    .symbolEffect(.drawOn, isActive: isComplete)

// Playback modes
    .symbolEffect(.drawOn.byLayer, isActive: isActive)
    .symbolEffect(.drawOn.wholeSymbol, isActive: isActive)
    .symbolEffect(.drawOn.individually, isActive: isActive)

// With options
    .symbolEffect(.drawOn, options: .speed(2.0), isActive: isActive)
    .symbolEffect(.drawOn, options: .nonRepeating, isActive: isActive)

swift

// Indefinite — draws in while active
Image(systemName: "checkmark.circle")
    .symbolEffect(.drawOn, isActive: isComplete)

// Playback modes
    .symbolEffect(.drawOn.byLayer, isActive: isActive)
    .symbolEffect(.drawOn.wholeSymbol, isActive: isActive)
    .symbolEffect(.drawOn.individually, isActive: isActive)

// With options
    .symbolEffect(.drawOn, options: .speed(2.0), isActive: isActive)
    .symbolEffect(.drawOn, options: .nonRepeating, isActive: isActive)

Draw Off

绘制消失（Draw Off）

swift

// Indefinite — draws out while active
Image(systemName: "star.fill")
    .symbolEffect(.drawOff, isActive: isHidden)

// Playback modes
    .symbolEffect(.drawOff.byLayer, isActive: isActive)
    .symbolEffect(.drawOff.wholeSymbol, isActive: isActive)
    .symbolEffect(.drawOff.individually, isActive: isActive)

// Direction control
    .symbolEffect(.drawOff.nonReversed, isActive: isActive) // follows draw path forward
    .symbolEffect(.drawOff.reversed, isActive: isActive)    // erases in reverse order

swift

// Indefinite — draws out while active
Image(systemName: "star.fill")
    .symbolEffect(.drawOff, isActive: isHidden)

// Playback modes
    .symbolEffect(.drawOff.byLayer, isActive: isActive)
    .symbolEffect(.drawOff.wholeSymbol, isActive: isActive)
    .symbolEffect(.drawOff.individually, isActive: isActive)

// Direction control
    .symbolEffect(.drawOff.nonReversed, isActive: isActive) // 沿绘制路径正向擦除
    .symbolEffect(.drawOff.reversed, isActive: isActive)    // 沿绘制路径反向擦除

UIKit Draw Effects

UIKit绘制效果实现

swift

// Draw On
imageView.addSymbolEffect(.drawOn)

// Draw Off
imageView.addSymbolEffect(.drawOff)

// Remove
imageView.removeSymbolEffect(ofType: DrawOnSymbolEffect.self)

swift

// Draw On
imageView.addSymbolEffect(.drawOn)

// Draw Off
imageView.addSymbolEffect(.drawOff)

// Remove
imageView.removeSymbolEffect(ofType: DrawOnSymbolEffect.self)

Variable Draw

可变绘制（Variable Draw）

Uses

SymbolVariableValueMode

to control how variable values are rendered.

swift

// Variable Draw — draws stroke proportional to value (iOS 26+)
Image(systemName: "thermometer.high", variableValue: temperature)
    .symbolVariableValueMode(.draw)

// Variable Color — sets layer opacity based on threshold (iOS 17+, default)
Image(systemName: "wifi", variableValue: signalStrength)
    .symbolVariableValueMode(.color)

使用

SymbolVariableValueMode

控制变量值的渲染方式。

swift

// Variable Draw — draws stroke proportional to value (iOS 26+)
Image(systemName: "thermometer.high", variableValue: temperature)
    .symbolVariableValueMode(.draw)

// Variable Color — sets layer opacity based on threshold (iOS 17+, default)
Image(systemName: "wifi", variableValue: signalStrength)
    .symbolVariableValueMode(.color)

SymbolVariableValueMode Enum (iOS 26+)

SymbolVariableValueMode枚举（iOS 26+）

Case	Description
`.color`	Sets opacity of each variable layer on/off based on threshold (existing behavior)
`.draw`	Changes drawn length of each variable layer based on range

Constraint: Some symbols support only one mode. Setting an unsupported mode has no visible effect. A symbol cannot use both Variable Color and Variable Draw simultaneously.

枚举值	描述
`.color`	根据阈值设置每个变量图层的显示/隐藏（现有默认行为）
`.draw`	根据数值范围改变每个变量图层的绘制长度

约束：部分符号仅支持一种模式。设置不支持的模式不会产生可见效果。一个符号无法同时使用可变颜色和可变绘制模式。

Gradient Rendering (iOS 26+)

渐变渲染（Gradient Rendering，iOS 26+）

Uses

SymbolColorRenderingMode

for automatic gradient generation from a single color.

swift

// Gradient fill — system generates axial gradient from source color
Image(systemName: "heart.fill")
    .symbolColorRenderingMode(.gradient)
    .foregroundStyle(.red)

// Works with any rendering mode
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.hierarchical)
    .symbolColorRenderingMode(.gradient)
    .foregroundStyle(.blue)

使用

SymbolColorRenderingMode

从单一颜色自动生成渐变效果。

swift

// Gradient fill — system generates axial gradient from source color
Image(systemName: "heart.fill")
    .symbolColorRenderingMode(.gradient)
    .foregroundStyle(.red)

// Works with any rendering mode
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.hierarchical)
    .symbolColorRenderingMode(.gradient)
    .foregroundStyle(.blue)

SymbolColorRenderingMode Enum (iOS 26+)

SymbolColorRenderingMode枚举（iOS 26+）

Case	Description
`.flat`	Solid color fill (default)
`.gradient`	Axial gradient generated from source color

Gradients are most effective at larger symbol sizes and work across all rendering modes.

枚举值	描述
`.flat`	纯色填充（默认）
`.gradient`	从源颜色生成轴向渐变

渐变效果在较大符号尺寸下表现最佳，且适用于所有渲染模式。

Part 5: Content Transition Patterns

第五部分：内容转场模式

Symbol Swap with Replace

符号切换与替换效果

swift

struct PlayPauseButton: View {
    @State private var isPlaying = false

    var body: some View {
        Button {
            isPlaying.toggle()
        } label: {
            Image(systemName: isPlaying ? "pause.fill" : "play.fill")
                .contentTransition(.symbolEffect(.replace))
        }
        .accessibilityLabel(isPlaying ? "Pause" : "Play")
    }
}

swift

struct PlayPauseButton: View {
    @State private var isPlaying = false

    var body: some View {
        Button {
            isPlaying.toggle()
        } label: {
            Image(systemName: isPlaying ? "pause.fill" : "play.fill")
                .contentTransition(.symbolEffect(.replace))
        }
        .accessibilityLabel(isPlaying ? "Pause" : "Play")
    }
}

Download Progress Pattern

下载进度模式

swift

struct DownloadButton: View {
    @State private var state: DownloadState = .idle

    var symbolName: String {
        switch state {
        case .idle: "arrow.down.circle"
        case .downloading: "stop.circle"
        case .complete: "checkmark.circle.fill"
        }
    }

    var body: some View {
        Button {
            advanceState()
        } label: {
            Image(systemName: symbolName)
                .contentTransition(.symbolEffect(.replace))
                .symbolEffect(.pulse, isActive: state == .downloading)
        }
    }
}

swift

struct DownloadButton: View {
    @State private var state: DownloadState = .idle

    var symbolName: String {
        switch state {
        case .idle: "arrow.down.circle"
        case .downloading: "stop.circle"
        case .complete: "checkmark.circle.fill"
        }
    }

    var body: some View {
        Button {
            advanceState()
        } label: {
            Image(systemName: symbolName)
                .contentTransition(.symbolEffect(.replace))
                .symbolEffect(.pulse, isActive: state == .downloading)
        }
    }
}

Toggle with Effect Feedback

带效果反馈的开关

swift

struct FavoriteButton: View {
    @Binding var isFavorite: Bool
    @State private var bounceValue = 0

    var body: some View {
        Button {
            isFavorite.toggle()
            bounceValue += 1
        } label: {
            Image(systemName: isFavorite ? "star.fill" : "star")
                .contentTransition(.symbolEffect(.replace))
                .symbolEffect(.bounce, value: bounceValue)
                .foregroundStyle(isFavorite ? .yellow : .gray)
        }
    }
}

swift

struct FavoriteButton: View {
    @Binding var isFavorite: Bool
    @State private var bounceValue = 0

    var body: some View {
        Button {
            isFavorite.toggle()
            bounceValue += 1
        } label: {
            Image(systemName: isFavorite ? "star.fill" : "star")
                .contentTransition(.symbolEffect(.replace))
                .symbolEffect(.bounce, value: bounceValue)
                .foregroundStyle(isFavorite ? .yellow : .gray)
        }
    }
}

Part 6: Custom Symbols

第六部分：自定义符号

Template Structure

模板结构

Custom symbols are SVG files with specific layer annotations:

Export from design tool as SVG
Import into SF Symbols app (File > Import)
Set template type: Monochrome, Hierarchical, Multicolor, or Variable Color
Annotate layers for rendering modes:
- Primary layer: Full opacity in Hierarchical
- Secondary layer: Reduced opacity in Hierarchical
- Tertiary layer: Most reduced opacity in Hierarchical
Set Palette colors per layer if supporting Palette mode
Export as
```
.svg
```
template for Xcode

自定义符号是带有特定图层注释的SVG文件：

从设计工具导出为SVG格式
导入到SF Symbols应用（文件 > 导入）
设置模板类型：单色、层次化、多色或可变颜色
为图层添加注释以支持渲染模式：
- Primary图层：在层次化模式下完全不透明
- Secondary图层：在层次化模式下降低透明度
- Tertiary图层：在层次化模式下透明度最低
如果支持调色板模式，为每个图层设置调色板颜色
导出为
```
.svg
```
模板用于Xcode

Draw Annotation (SF Symbols 7)

绘制注释（SF Symbols 7）

To enable Draw animations on custom symbols:

Select a path in SF Symbols 7 app
Open the Draw annotation panel
Place guide points on the path:

Point Type	Visual	Purpose
Start	Open circle	Where drawing begins
End	Closed circle	Where drawing ends
Corner	Diamond	Sharp direction change
Bidirectional	Double arrow	Center-outward drawing
Attachment	Link icon	Non-drawing decorative connection

Minimum: 2 guide points per path (start + end)
Option-drag for precise placement
Test in Preview panel across all weights

要为自定义符号启用绘制动画：

在SF Symbols 7应用中选择路径
打开绘制注释面板
在路径上放置引导点：

点类型	视觉标识	用途
Start	空心圆	绘制起始位置
End	实心圆	绘制结束位置
Corner	菱形	尖锐方向变化点
Bidirectional	双箭头	从中心向外绘制
Attachment	链接图标	非绘制装饰性连接

最低要求：每条路径至少2个引导点（起点+终点）
按住Option键拖动可精确放置
在预览面板中测试所有字重下的效果

Weight Interpolation

字重插值

Custom symbols should include designs for at least 3 weight variants:

Ultralight (thinnest)
Regular (middle)
Black (thickest)

The system interpolates between these for intermediate weights (Thin, Light, Medium, Semibold, Bold, Heavy).

自定义符号应至少包含3种字重变体设计：

Ultralight（最细）
Regular（中等）
Black（最粗）

系统会在这些变体之间插值生成中间字重（Thin、Light、Medium、Semibold、Bold、Heavy）。

Importing to Xcode

导入到Xcode

In Xcode, open Asset Catalog
Click + > Symbol Image Set
Drag exported
```
.svg
```
from SF Symbols app

Asset catalog symbols:

Image("custom.symbol.name")

. For symbols loaded from a bundle:

Image(systemName: "custom.symbol.name", bundle: .module)

在Xcode中打开资源目录
点击**+** > Symbol Image Set
将从SF Symbols应用导出的
```
.svg
```
文件拖入

资源目录中的符号使用方式：

Image("custom.symbol.name")

。从bundle加载的符号：

Image(systemName: "custom.symbol.name", bundle: .module)

Part 7: Platform Availability Matrix

第七部分：平台兼容性矩阵

Rendering Modes

渲染模式

Feature	iOS	macOS	watchOS	tvOS	visionOS
Monochrome	13+	11+	6+	13+	1+
Hierarchical	15+	12+	8+	15+	1+
Palette	15+	12+	8+	15+	1+
Multicolor	15+	12+	8+	15+	1+
Variable Value	16+	13+	9+	16+	1+

功能	iOS	macOS	watchOS	tvOS	visionOS
单色	13+	11+	6+	13+	1+
层次化	15+	12+	8+	15+	1+
调色板	15+	12+	8+	15+	1+
多色	15+	12+	8+	15+	1+
变量值	16+	13+	9+	16+	1+

Symbol Effects

符号效果

Effect	Category	iOS	macOS	watchOS	tvOS	visionOS
Bounce	Discrete	17+	14+	10+	17+	1+
Pulse	Discrete/Indefinite	17+	14+	10+	17+	1+
Variable Color	Discrete/Indefinite	17+	14+	10+	17+	1+
Scale	Indefinite	17+	14+	10+	17+	1+
Appear	Transition	17+	14+	10+	17+	1+
Disappear	Transition	17+	14+	10+	17+	1+
Replace	Content Transition	17+	14+	10+	17+	1+
Wiggle	Discrete/Indefinite	18+	15+	11+	18+	2+
Rotate	Discrete/Indefinite	18+	15+	11+	18+	2+
Breathe	Discrete/Indefinite	18+	15+	11+	18+	2+
Draw On	Indefinite	26+	Tahoe+	26+	26+	26+
Draw Off	Indefinite	26+	Tahoe+	26+	26+	26+
Variable Draw	Value-based	26+	Tahoe+	26+	26+	26+
Gradient Fill	Rendering	26+	Tahoe+	26+	26+	26+

效果	分类	iOS	macOS	watchOS	tvOS	visionOS
弹跳	离散型	17+	14+	10+	17+	1+
脉冲	离散型/无限循环	17+	14+	10+	17+	1+
可变颜色	离散型/无限循环	17+	14+	10+	17+	1+
缩放	无限循环	17+	14+	10+	17+	1+
出现	转场型	17+	14+	10+	17+	1+
消失	转场型	17+	14+	10+	17+	1+
替换	内容转场	17+	14+	10+	17+	1+
摇摆	离散型/无限循环	18+	15+	11+	18+	2+
旋转	离散型/无限循环	18+	15+	11+	18+	2+
呼吸	离散型/无限循环	18+	15+	11+	18+	2+
绘制出现	无限循环	26+	Tahoe+	26+	26+	26+
绘制消失	无限循环	26+	Tahoe+	26+	26+	26+
可变绘制	基于值	26+	Tahoe+	26+	26+	26+
渐变填充	渲染	26+	Tahoe+	26+	26+	26+

Effect Behavior Categories

效果行为分类

Category	What It Does	How to Trigger
Discrete	One-shot animation, returns to rest	`.symbolEffect(_:value:)` — fires when value changes
Indefinite	Loops while active	`.symbolEffect(_:isActive:)` — loops while `true`
Transition	Plays on view insert/remove	`.transition(.symbolEffect(_:))`
Content Transition	Plays when symbol changes	`.contentTransition(.symbolEffect(_:))`

分类	功能	触发方式
离散型	一次性动画，结束后回到初始状态	`.symbolEffect(_:value:)` — 值变化时触发
无限循环型	激活时持续循环	`.symbolEffect(_:isActive:)` — 当值为 `true` 时循环
转场型	在视图插入/移除时播放	`.transition(.symbolEffect(_:))`
内容转场型	在符号变更时播放	`.contentTransition(.symbolEffect(_:))`

Part 8: UIKit Complete Reference

第八部分：UIKit完整参考

Adding Effects

添加效果

swift

// Add indefinite effect
imageView.addSymbolEffect(.pulse)
imageView.addSymbolEffect(.breathe)
imageView.addSymbolEffect(.rotate)
imageView.addSymbolEffect(.variableColor.iterative)
imageView.addSymbolEffect(.scale.up)

// Add with options
imageView.addSymbolEffect(.bounce, options: .repeat(3))
imageView.addSymbolEffect(.pulse, options: .speed(2.0))

// Add with completion handler
imageView.addSymbolEffect(.bounce, options: .default) { context in
    // Called when effect finishes
    print("Bounce complete")
}

swift

// Add indefinite effect
imageView.addSymbolEffect(.pulse)
imageView.addSymbolEffect(.breathe)
imageView.addSymbolEffect(.rotate)
imageView.addSymbolEffect(.variableColor.iterative)
imageView.addSymbolEffect(.scale.up)

// Add with options
imageView.addSymbolEffect(.bounce, options: .repeat(3))
imageView.addSymbolEffect(.pulse, options: .speed(2.0))

// Add with completion handler
imageView.addSymbolEffect(.bounce, options: .default) { context in
    // Called when effect finishes
    print("Bounce complete")
}

Removing Effects

移除效果

swift

// Remove specific effect type
imageView.removeSymbolEffect(ofType: PulseSymbolEffect.self)
imageView.removeSymbolEffect(ofType: ScaleSymbolEffect.self)
imageView.removeSymbolEffect(ofType: RotateSymbolEffect.self)

// Remove all effects
imageView.removeAllSymbolEffects()

// Remove with options
imageView.removeSymbolEffect(ofType: PulseSymbolEffect.self, options: .default)

// Remove with completion
imageView.removeSymbolEffect(ofType: PulseSymbolEffect.self) { context in
    print("Pulse removed")
}

swift

// Remove specific effect type
imageView.removeSymbolEffect(ofType: PulseSymbolEffect.self)
imageView.removeSymbolEffect(ofType: ScaleSymbolEffect.self)
imageView.removeSymbolEffect(ofType: RotateSymbolEffect.self)

// Remove all effects
imageView.removeAllSymbolEffects()

// Remove with options
imageView.removeSymbolEffect(ofType: PulseSymbolEffect.self, options: .default)

// Remove with completion
imageView.removeSymbolEffect(ofType: PulseSymbolEffect.self) { context in
    print("Pulse removed")
}

Setting Symbol Images with Transitions

带转场设置符号图片

swift

// Replace with content transition
let newImage = UIImage(systemName: "pause.fill")!
imageView.setSymbolImage(newImage, contentTransition: .replace)

// Directional replace
imageView.setSymbolImage(newImage, contentTransition: .replace.downUp)
imageView.setSymbolImage(newImage, contentTransition: .replace.upUp)
imageView.setSymbolImage(newImage, contentTransition: .replace.offUp)

// With options
imageView.setSymbolImage(newImage, contentTransition: .replace, options: .speed(2.0))

swift

// Replace with content transition
let newImage = UIImage(systemName: "pause.fill")!
imageView.setSymbolImage(newImage, contentTransition: .replace)

// Directional replace
imageView.setSymbolImage(newImage, contentTransition: .replace.downUp)
imageView.setSymbolImage(newImage, contentTransition: .replace.upUp)
imageView.setSymbolImage(newImage, contentTransition: .replace.offUp)

// With options
imageView.setSymbolImage(newImage, contentTransition: .replace, options: .speed(2.0))

UIBarButtonItem Effects

UIBarButtonItem效果

swift

// Effects also work on UIBarButtonItem
barButtonItem.addSymbolEffect(.bounce)
barButtonItem.addSymbolEffect(.pulse, isActive: isLoading)
barButtonItem.removeSymbolEffect(ofType: PulseSymbolEffect.self)

swift

// Effects also work on UIBarButtonItem
barButtonItem.addSymbolEffect(.bounce)
barButtonItem.addSymbolEffect(.pulse, isActive: isLoading)
barButtonItem.removeSymbolEffect(ofType: PulseSymbolEffect.self)

Part 9: Accessibility

第九部分：无障碍访问

Labels

// SwiftUI
Image(systemName: "star.fill")
    .accessibilityLabel("Favorite")

// UIKit
let image = UIImage(systemName: "star.fill")
imageView.accessibilityLabel = "Favorite"
imageView.isAccessibilityElement = true

// Label automatically provides accessibility
Label("Settings", systemImage: "gear")
// VoiceOver reads: "Settings"

swift

// SwiftUI
Image(systemName: "star.fill")
    .accessibilityLabel("Favorite")

// UIKit
let image = UIImage(systemName: "star.fill")
imageView.accessibilityLabel = "Favorite"
imageView.isAccessibilityElement = true

// Label automatically provides accessibility
Label("Settings", systemImage: "gear")
// VoiceOver reads: "Settings"

Reduce Motion

减少动态效果

Symbol effects automatically respect

UIAccessibility.isReduceMotionEnabled

. When Reduce Motion is on:

Most effects are simplified or suppressed
Replace transitions use crossfade instead of directional movement
Indefinite effects may be simplified to static appearance changes

Do not attempt to override or check this yourself for effects. The system handles it. Only intervene if effects carry semantic meaning:

swift

// If the pulsing conveys connection status, provide a text label
Image(systemName: "wifi")
    .symbolEffect(.pulse, isActive: isConnecting)
    .accessibilityLabel(isConnecting ? "Connecting to WiFi" : "WiFi connected")

符号效果会自动遵循

UIAccessibility.isReduceMotionEnabled

设置。当开启减少动态效果时：

大多数效果会被简化或禁用
替换转场会使用淡入淡出而非方向移动
无限循环效果可能会简化为静态外观变化

请勿尝试自行覆盖或检查此设置。系统会自动处理。仅当效果承载语义信息时才需要干预：

swift

// 如果脉冲效果表示连接状态，请提供文本标签
Image(systemName: "wifi")
    .symbolEffect(.pulse, isActive: isConnecting)
    .accessibilityLabel(isConnecting ? "Connecting to WiFi" : "WiFi connected")

Bold Text

粗体文本

SF Symbols automatically adapt when Bold Text is enabled in Accessibility settings. Custom symbols need weight variants to support this properly.

当无障碍设置中启用粗体文本时，SF Symbols会自动适配。自定义符号需要提供多种字重变体才能正确支持此功能。

Dynamic Type

动态类型

Symbols sized with

.font()

scale automatically with Dynamic Type. Symbols sized with explicit point sizes (

.font(.system(size: 24))

) do not scale.

swift

// ✅ Scales with Dynamic Type
Image(systemName: "star.fill")
    .font(.title)

// ❌ Fixed size, does not scale
Image(systemName: "star.fill")
    .font(.system(size: 24))

使用

.font()

设置尺寸的符号会随动态类型自动缩放。使用明确点尺寸（

.font(.system(size: 24))

）的符号不会缩放。

swift

// ✅ 随动态类型缩放
Image(systemName: "star.fill")
    .font(.title)

// ❌ 固定尺寸，不缩放
Image(systemName: "star.fill")
    .font(.system(size: 24))

Part 10: Common Patterns

第十部分：常见模式

Notification Badge with Effect

带效果的通知徽章

swift

struct NotificationBell: View {
    let count: Int

    var body: some View {
        Image(systemName: count > 0 ? "bell.badge.fill" : "bell.fill")
            .contentTransition(.symbolEffect(.replace))
            .symbolEffect(.wiggle, value: count)
            .symbolRenderingMode(.palette)
            .foregroundStyle(count > 0 ? .red : .primary, .primary)
    }
}

swift

struct NotificationBell: View {
    let count: Int

    var body: some View {
        Image(systemName: count > 0 ? "bell.badge.fill" : "bell.fill")
            .contentTransition(.symbolEffect(.replace))
            .symbolEffect(.wiggle, value: count)
            .symbolRenderingMode(.palette)
            .foregroundStyle(count > 0 ? .red : .primary, .primary)
    }
}

WiFi Strength Indicator

WiFi强度指示器

swift

struct WiFiIndicator: View {
    let strength: Double // 0.0 to 1.0
    let isSearching: Bool

    var body: some View {
        Image(systemName: "wifi", variableValue: strength)
            .symbolEffect(.variableColor.iterative, isActive: isSearching)
            .symbolRenderingMode(.hierarchical)
            .accessibilityLabel(
                isSearching ? "Searching for WiFi" :
                "WiFi strength: \(Int(strength * 100))%"
            )
    }
}

swift

struct WiFiIndicator: View {
    let strength: Double // 0.0 to 1.0
    let isSearching: Bool

    var body: some View {
        Image(systemName: "wifi", variableValue: strength)
            .symbolEffect(.variableColor.iterative, isActive: isSearching)
            .symbolRenderingMode(.hierarchical)
            .accessibilityLabel(
                isSearching ? "Searching for WiFi" :
                "WiFi strength: \(Int(strength * 100))%"
            )
    }
}

Animated Toggle

动画开关

swift

struct RecordButton: View {
    @State private var isRecording = false

    var body: some View {
        Button {
            isRecording.toggle()
        } label: {
            Image(systemName: isRecording ? "stop.circle.fill" : "record.circle")
                .contentTransition(.symbolEffect(.replace))
                .symbolEffect(.breathe.pulse, isActive: isRecording)
                .font(.largeTitle)
                .foregroundStyle(isRecording ? .red : .primary)
        }
        .accessibilityLabel(isRecording ? "Stop recording" : "Start recording")
    }
}

swift

struct RecordButton: View {
    @State private var isRecording = false

    var body: some View {
        Button {
            isRecording.toggle()
        } label: {
            Image(systemName: isRecording ? "stop.circle.fill" : "record.circle")
                .contentTransition(.symbolEffect(.replace))
                .symbolEffect(.breathe.pulse, isActive: isRecording)
                .font(.largeTitle)
                .foregroundStyle(isRecording ? .red : .primary)
        }
        .accessibilityLabel(isRecording ? "Stop recording" : "Start recording")
    }
}

Multi-State Symbol with Draw (iOS 26+)

多状态符号与绘制效果（iOS 26+）

swift

struct TaskCheckbox: View {
    @State private var isComplete = false

    var body: some View {
        Button {
            isComplete.toggle()
        } label: {
            Image(systemName: isComplete ? "checkmark.circle.fill" : "circle")
                .contentTransition(.symbolEffect(.replace))
                .symbolEffect(.drawOn, isActive: isComplete)
                .font(.title2)
                .foregroundStyle(isComplete ? .green : .secondary)
        }
        .accessibilityLabel(isComplete ? "Completed" : "Not completed")
    }
}

swift

struct TaskCheckbox: View {
    @State private var isComplete = false

    var body: some View {
        Button {
            isComplete.toggle()
        } label: {
            Image(systemName: isComplete ? "checkmark.circle.fill" : "circle")
                .contentTransition(.symbolEffect(.replace))
                .symbolEffect(.drawOn, isActive: isComplete)
                .font(.title2)
                .foregroundStyle(isComplete ? .green : .secondary)
        }
        .accessibilityLabel(isComplete ? "Completed" : "Not completed")
    }
}

Resources

资源

WWDC: 2023-10257, 2023-10258, 2024-10188, 2025-337

Docs: /symbols, /symbols/symboleffect, /symbols/bouncesymboleffect, /symbols/pulsesymboleffect, /symbols/variablecolorsymboleffect, /symbols/scalesymboleffect, /symbols/wigglesymboleffect, /symbols/rotatesymboleffect, /symbols/breathesymboleffect, /symbols/appearsymboleffect, /symbols/disappearsymboleffect, /symbols/replacesymboleffect, /symbols/drawonsymboleffect, /symbols/drawoffsymboleffect, /swiftui/image/symbolrenderingmode(_:), /uikit/uiimage/symbolconfiguration

Skills: axiom-sf-symbols, axiom-hig-ref, axiom-swiftui-animation-ref

Last Updated Based on WWDC 2023/10257-10258, WWDC 2024/10188, WWDC 2025/337 Version iOS 13+ (display), iOS 15+ (rendering modes), iOS 17+ (effects), iOS 18+ (Wiggle/Rotate/Breathe), iOS 26+ (Draw, Gradients)

WWDC：2023-10257, 2023-10258, 2024-10188, 2025-337

文档：/symbols, /symbols/symboleffect, /symbols/bouncesymboleffect, /symbols/pulsesymboleffect, /symbols/variablecolorsymboleffect, /symbols/scalesymboleffect, /symbols/wigglesymboleffect, /symbols/rotatesymboleffect, /symbols/breathesymboleffect, /symbols/appearsymboleffect, /symbols/disappearsymboleffect, /symbols/replacesymboleffect, /symbols/drawonsymboleffect, /symbols/drawoffsymboleffect, /swiftui/image/symbolrenderingmode(_:), /uikit/uiimage/symbolconfiguration

技能：axiom-sf-symbols, axiom-hig-ref, axiom-swiftui-animation-ref

最后更新 基于WWDC 2023/10257-10258, WWDC 2024/10188, WWDC 2025/337 版本 iOS 13+（显示）, iOS 15+（渲染模式）, iOS 17+（效果）, iOS 18+（摇摆/旋转/呼吸）, iOS 26+（绘制、渐变）

axiom-sf-symbols-ref

Original

Translation

SF Symbols — API Reference

SF Symbols — API参考文档

When to Use This Skill

何时使用此技能

Related Skills

相关技能

Part 1: Symbol Display

第一部分：符号显示

SwiftUI

SwiftUI

UIKit

UIKit

AppKit

AppKit

Part 2: Rendering Modes

第二部分：渲染模式

SwiftUI

SwiftUI

SymbolRenderingMode Enum

SymbolRenderingMode枚举

UIKit

UIKit

Combining Configurations (UIKit)

组合配置（UIKit）

Part 3: Symbol Effects — Complete API

第三部分：符号效果——完整API

Effect Protocol Hierarchy

效果协议层级

Remove All Effects (SwiftUI)

移除所有效果（SwiftUI）

SymbolEffectOptions

SymbolEffectOptions

Bounce

弹跳效果（Bounce）

Pulse

脉冲效果（Pulse）

Variable Color

可变颜色效果（Variable Color）

Scale

缩放效果（Scale）

Wiggle (iOS 18+)

摇摆效果（Wiggle，iOS 18+）

Rotate (iOS 18+)

旋转效果（Rotate，iOS 18+）

Breathe (iOS 18+)

呼吸效果（Breathe，iOS 18+）

Appear and Disappear

出现与消失效果（Appear and Disappear）

Replace

替换效果（Replace）

Part 4: Draw Effects (iOS 26+)

第四部分：绘制效果（Draw Effects，iOS 26+）

Draw On

绘制出现（Draw On）

Draw Off

绘制消失（Draw Off）

UIKit Draw Effects

UIKit绘制效果实现

Variable Draw

可变绘制（Variable Draw）

SymbolVariableValueMode Enum (iOS 26+)

SymbolVariableValueMode枚举（iOS 26+）

Gradient Rendering (iOS 26+)

渐变渲染（Gradient Rendering，iOS 26+）

SymbolColorRenderingMode Enum (iOS 26+)

SymbolColorRenderingMode枚举（iOS 26+）

Part 5: Content Transition Patterns

第五部分：内容转场模式

Symbol Swap with Replace

符号切换与替换效果

Download Progress Pattern

下载进度模式

Toggle with Effect Feedback

带效果反馈的开关

Part 6: Custom Symbols

第六部分：自定义符号

Template Structure