swiftui-26-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SwiftUI 26 API Reference

SwiftUI 26 API 参考文档

Non-glass SwiftUI APIs introduced at WWDC 2025 targeting iOS 26, macOS 26, visionOS 26. Synthesized from official Apple documentation (via sosumi.ai extractions).
For Liquid Glass APIs (
glassEffect
,
GlassEffectContainer
,
backgroundExtensionEffect
, morph animations), load
apple-liquid-glass-design
skill instead.

WWDC 2025推出的非玻璃效果SwiftUI API,支持iOS 26、macOS 26、visionOS 26。内容源自苹果官方文档(通过sosumi.ai提取整理)。
Liquid Glass API相关内容
glassEffect
GlassEffectContainer
backgroundExtensionEffect
、形态动画),请查看
apple-liquid-glass-design
技能文档。

Quick Reference

快速参考

Animation

动画

1. @Animatable Macro

1. @Animatable 宏

iOS 13+ · macOS 10.15+ (Swift 5.9+ compiler required)
Auto-synthesizes animatableData from the struct's numeric properties. Non-animatable properties must use @AnimatableIgnored.
swift
@Animatable
struct CoolShape: Shape {
    var width: CGFloat
    var angle: Angle
    @AnimatableIgnored var isOpaque: Bool
    // animatableData synthesized from width + angle
}
iOS 13+ · macOS 10.15+(需Swift 5.9+编译器)
自动从结构体的数值属性合成animatableData。非动画属性需使用@AnimatableIgnored标记。
swift
@Animatable
struct CoolShape: Shape {
    var width: CGFloat
    var angle: Angle
    @AnimatableIgnored var isOpaque: Bool
    // animatableData synthesized from width + angle
}

Text Editing

文本编辑

2. AttributedString TextEditor with Selection

2. 支持选中功能的AttributedString TextEditor

iOS 26+ · macOS 26+
Use
TextEditor
with an
AttributedString
binding and
AttributedTextSelection
to track the insertion point or selected range.
swift
struct SuggestionTextEditor: View {
    @State var text: AttributedString = ""
    @State var selection = AttributedTextSelection()

    var body: some View {
        VStack {
            TextEditor(text: $text, selection: $selection)
            SuggestionsView(substrings: getSubstrings(
                text: text, indices: selection.indices(in: text)))
        }
    }
}
iOS 26+ · macOS 26+
结合
AttributedString
绑定与
AttributedTextSelection
使用
TextEditor
,以跟踪插入点或选中范围。
swift
struct SuggestionTextEditor: View {
    @State var text: AttributedString = ""
    @State var selection = AttributedTextSelection()

    var body: some View {
        VStack {
            TextEditor(text: $text, selection: $selection)
            SuggestionsView(substrings: getSubstrings(
                text: text, indices: selection.indices(in: text)))
        }
    }
}

3. Formatting Definition

3. 格式定义

iOS 26+ · macOS 26+
Define an
AttributedTextFormattingDefinition
to restrict which formatting attributes are valid in a
TextEditor
.
swift
struct MyTextFormattingDefinition: AttributedTextFormattingDefinition {
    var body: some AttributedTextFormattingDefinition<
        AttributeScopes.SwiftUIAttributes
    > {
        ValueConstraint(
            for: \.underlineStyle,
            values: [nil, .single],
            default: .single)
        MyAttributedTextValueConstraint()
        ContactsArePurple()
    }
}
iOS 26+ · macOS 26+
定义
AttributedTextFormattingDefinition
以限制
TextEditor
中允许使用的格式属性。
swift
struct MyTextFormattingDefinition: AttributedTextFormattingDefinition {
    var body: some AttributedTextFormattingDefinition<
        AttributeScopes.SwiftUIAttributes
    > {
        ValueConstraint(
            for: \.underlineStyle,
            values: [nil, .single],
            default: .single)
        MyAttributedTextValueConstraint()
        ContactsArePurple()
    }
}

Web Content

网页内容

4. WebView with WebPage Controller

4. 搭配WebPage控制器的WebView

iOS 26+ · macOS 26+ · visionOS 26+ (requires
import WebKit
)
Displays web content in a native SwiftUI view. Connect a WebPage controller for navigation, JavaScript, and title binding.
swift
import WebKit

struct ContentView: View {
    @State private var page = WebPage()

    var body: some View {
        NavigationStack {
            WebView(page)
                .navigationTitle(page.title)
        }
    }
}
iOS 26+ · macOS 26+ · visionOS 26+(需导入
import WebKit
在原生SwiftUI视图中显示网页内容。连接WebPage控制器以实现导航、JavaScript交互和标题绑定。
swift
import WebKit

struct ContentView: View {
    @State private var page = WebPage()

    var body: some View {
        NavigationStack {
            WebView(page)
                .navigationTitle(page.title)
        }
    }
}

UIKit Bridge

UIKit 桥接

5. UIHostingSceneDelegate

5. UIHostingSceneDelegate

iOS 26+ · iPadOS 26+ · tvOS 26+ · visionOS 26+
Use
UIHostingSceneDelegate
to activate SwiftUI scenes from a UIKit app.
swift
class HostingSceneDelegate: UIHostingSceneDelegate {
    static var rootScene: some Scene {
        WindowGroup(id: "swiftui-window") {
            ContentView()
        }
    }
}

// Activate from UIKit:
if let request = UISceneSessionActivationRequest(
    hostingDelegateClass: HostingSceneDelegate.self,
    id: "swiftui-window"
) {
    UIApplication.shared.activateSceneSession(for: request)
}
iOS 26+ · iPadOS 26+ · tvOS 26+ · visionOS 26+
使用
UIHostingSceneDelegate
从UIKit应用中激活SwiftUI场景。
swift
class HostingSceneDelegate: UIHostingSceneDelegate {
    static var rootScene: some Scene {
        WindowGroup(id: "swiftui-window") {
            ContentView()
        }
    }
}

// Activate from UIKit:
if let request = UISceneSessionActivationRequest(
    hostingDelegateClass: HostingSceneDelegate.self,
    id: "swiftui-window"
) {
    UIApplication.shared.activateSceneSession(for: request)
}

Scroll & Tab Behavior

滚动与标签栏行为

6. Scroll Edge Effect

6. 滚动边缘效果

iOS 26+ · macOS 26+
swift
ScrollView {
    LazyVStack {
        ForEach(data) { item in
            RowView(item)
        }
    }
}
.scrollEdgeEffectStyle(.hard, for: .all)
iOS 26+ · macOS 26+
swift
ScrollView {
    LazyVStack {
        ForEach(data) { item in
            RowView(item)
        }
    }
}
.scrollEdgeEffectStyle(.hard, for: .all)

7. Tab Bar Minimization

7. 标签栏最小化

iOS 26+ · macOS 26+
swift
TabView {
    Tab("Numbers", systemImage: "number") {
        ScrollView {
            ForEach(0 ..< 50) { index in
                Text("\(index)").padding()
            }
        }
    }
}
.tabBarMinimizeBehavior(.onScrollDown)
iOS 26+ · macOS 26+
swift
TabView {
    Tab("Numbers", systemImage: "number") {
        ScrollView {
            ForEach(0 ..< 50) { index in
                Text("\(index)").padding()
            }
        }
    }
}
.tabBarMinimizeBehavior(.onScrollDown)

Toolbar & Layout

工具栏与布局

8. Toolbar Spacer

8. Toolbar Spacer

iOS 26+ · iPadOS 26+ · macOS 26+
swift
ContentView()
    .toolbar(id: "main-toolbar") {
        ToolbarItem(id: "tag") { TagButton() }
        ToolbarItem(id: "share") { ShareButton() }
        ToolbarSpacer(.fixed)
        ToolbarItem(id: "more") { MoreButton() }
    }
iOS 26+ · iPadOS 26+ · macOS 26+
swift
ContentView()
    .toolbar(id: "main-toolbar") {
        ToolbarItem(id: "tag") { TagButton() }
        ToolbarItem(id: "share") { ShareButton() }
        ToolbarSpacer(.fixed)
        ToolbarItem(id: "more") { MoreButton() }
    }

macOS Only

仅适用于macOS

9. Window Resize Anchor — macOS 26

9. 窗口调整锚点 — macOS 26

swift
struct HeightResizingExample: View {
    @State private var height: CGFloat = 300

    var body: some View {
        Color.red
            .overlay { Text("Tap to toggle").foregroundStyle(.white) }
            .onTapGesture {
                withAnimation(.easeInOut) {
                    height = height == 300 ? 700 : 300
                }
            }
            .frame(width: 250, height: height)
            .windowResizeAnchor(.top)
    }
}
swift
struct HeightResizingExample: View {
    @State private var height: CGFloat = 300

    var body: some View {
        Color.red
            .overlay { Text("Tap to toggle").foregroundStyle(.white) }
            .onTapGesture {
                withAnimation(.easeInOut) {
                    height = height == 300 ? 700 : 300
                }
            }
            .frame(width: 250, height: height)
            .windowResizeAnchor(.top)
    }
}

10. Drag Container — macOS 26

10. 拖拽容器 — macOS 26

swift
VStack {
    ForEach(fruits) { fruit in
        FruitView(fruit)
            .draggable(containerItemID: fruit.name)
    }
}
.dragContainer(itemID: \Fruit.name) { ids in
    fruits(with: ids)
}

swift
VStack {
    ForEach(fruits) { fruit in
        FruitView(fruit)
            .draggable(containerItemID: fruit.name)
    }
}
.dragContainer(itemID: \Fruit.name) { ids in
    fruits(with: ids)
}

Reading Paths

阅读路径

Clustered reference file sequences for common goals.
A — Adopting Liquid Glass: Load
apple-liquid-glass-design
skill — it contains complete glass adoption paths.
B — Building a Rich Text Editor:
text-editing.md
find-context.md
C — Embedding Web Content:
webkit.md
uikit-scene-bridge.md
(if UIKit host)
D — Migrating an Existing App: Migration sections are embedded in each reference file:
webkit.md
(WKWebView → WebView),
uikit-scene-bridge.md
(UIHostingController → UIHostingSceneDelegate),
animatable-macro.md
(manual animatableData → @Animatable). For glass migration (.material → .glassEffect), see
apple-liquid-glass-design
.
E — macOS-Specific Features:
macos-drag-and-windows.md
toolbar-and-slider.md
F — Custom Shape Animation:
animatable-macro.md
apple-liquid-glass-design
(if animating glass shapes)

针对常见开发目标整理的参考文件序列。
A — 采用Liquid Glass设计: 查看
apple-liquid-glass-design
技能文档 — 包含完整的玻璃效果适配路径。
B — 构建富文本编辑器:
text-editing.md
find-context.md
C — 嵌入网页内容:
webkit.md
uikit-scene-bridge.md
(若为UIKit宿主应用)
D — 迁移现有应用: 每个参考文件中都包含迁移章节:
webkit.md
(WKWebView → WebView)、
uikit-scene-bridge.md
(UIHostingController → UIHostingSceneDelegate)、
animatable-macro.md
(手动实现animatableData → @Animatable)。玻璃效果迁移(.material → .glassEffect)请查看
apple-liquid-glass-design
E — macOS专属功能:
macos-drag-and-windows.md
toolbar-and-slider.md
F — 自定义形状动画:
animatable-macro.md
apple-liquid-glass-design
(若为玻璃形状动画)

Common Gotchas

常见陷阱

  1. WebPage
    is
    @MainActor
    — all interactions must happen on the main actor
  2. One
    WebPage
    per
    WebView
    — only one
    WebPage
    can bind to a single
    WebView
    at a time
  3. Drag container APIs are macOS 26 only
    dragContainer
    and
    draggable(containerItemID:)
    are not available on iOS
  4. @Animatable
    availability is broad
    — the macro works back to iOS 13, but requires Swift 5.9+ compiler
  5. FindContext
    uses environment
    — access via
    @Environment(\.findContext)
    , returns optional
  6. TextEditor
    selection requires
    AttributedString
    AttributedTextSelection
    binding doesn't work with plain
    String

  1. WebPage
    @MainActor
    — 所有交互必须在主Actor中执行
  2. 一个
    WebView
    对应一个
    WebPage
    — 一个
    WebView
    同一时间只能绑定一个
    WebPage
  3. 拖拽容器API仅适用于macOS 26
    dragContainer
    draggable(containerItemID:)
    在iOS上不可用
  4. @Animatable
    兼容性广泛
    — 该宏可回溯至iOS 13,但需Swift 5.9+编译器支持
  5. FindContext
    通过环境访问
    — 通过
    @Environment(\.findContext)
    获取,返回可选值
  6. TextEditor
    选中功能需搭配
    AttributedString
    AttributedTextSelection
    绑定无法与普通
    String
    配合使用

Troubleshooting

故障排查

SymptomCauseFix
WebView
type not found
Missing framework importAdd
import WebKit
— WebView/WebPage are in WebKit, not SwiftUI
@Animatable
compilation error
Compiler too oldRequires Swift 5.9+ (Xcode 15+), even though protocol availability is iOS 13+
scrollEdgeEffectStyle
has no visible effect
Applied to wrong containerOnly works on
ScrollView
, not
List
UIHostingSceneDelegate
callbacks not firing
Missing scene declarationEnsure
static var rootScene
is implemented and
UISceneConfiguration.delegateClass
is set
FindContext
is nil at runtime
Not accessing via environmentUse
@Environment(\.findContext) var findContext
— returns optional
WebPage.title
is always nil
Not stored as @StateDeclare as
@State private var page = WebPage()
windowResizeAnchor
ignored during shrink
Missing resizability settingSet
.windowResizability(.contentSize)
on the Scene
AttributedTextSelection.indices
returns empty
Selection bound to String
TextEditor
must use
$attributedString
binding, not
$string
dragContainer
compile error on iOS
macOS 26 onlyGuard with
#if os(macOS)

症状原因解决方法
找不到
WebView
类型
缺少框架导入添加
import WebKit
— WebView/WebPage属于WebKit框架,而非SwiftUI
@Animatable
编译错误
编译器版本过旧需Swift 5.9+(Xcode 15+),尽管协议兼容性可回溯至iOS 13+
scrollEdgeEffectStyle
无可见效果
应用到错误容器仅对
ScrollView
生效,对
List
无效
UIHostingSceneDelegate
回调未触发
缺少场景声明确保实现
static var rootScene
并设置
UISceneConfiguration.delegateClass
运行时
FindContext
为nil
未通过环境访问使用
@Environment(\.findContext) var findContext
— 返回可选值
WebPage.title
始终为nil
未声明为@State声明为
@State private var page = WebPage()
缩小窗口时
windowResizeAnchor
被忽略
缺少可调整性设置在Scene上设置
.windowResizability(.contentSize)
AttributedTextSelection.indices
返回空值
选中绑定到String
TextEditor
必须使用
$attributedString
绑定,而非
$string
iOS上
dragContainer
编译错误
仅适用于macOS 26使用
#if os(macOS)
进行条件编译

Reference Files

参考文件

FileRead when...
references/animatable-macro.md
using
@Animatable
macro to synthesize animatableData
references/text-editing.md
building
TextEditor
with
AttributedString
, selection, or formatting definitions
references/find-context.md
implementing find/replace via
FindContext
references/webkit.md
embedding web content with
WebView
or
WebPage
references/uikit-scene-bridge.md
bridging UIKit scene lifecycle to SwiftUI via
UIHostingSceneDelegate
references/macos-drag-and-windows.md
adding
dragContainer
/
draggable
or
windowResizeAnchor
(macOS 26 only)
references/scroll-and-tabs.md
configuring
scrollEdgeEffectStyle
or
tabBarMinimizeBehavior
references/toolbar-and-slider.md
adding
ToolbarSpacer
or
Slider
tick marks
文件适用场景
references/animatable-macro.md
使用
@Animatable
宏合成animatableData时
references/text-editing.md
构建支持
AttributedString
、选中或格式定义的
TextEditor
references/find-context.md
通过
FindContext
实现查找/替换功能时
references/webkit.md
使用
WebView
WebPage
嵌入网页内容时
references/uikit-scene-bridge.md
通过
UIHostingSceneDelegate
将UIKit场景生命周期桥接到SwiftUI时
references/macos-drag-and-windows.md
添加
dragContainer
/
draggable
windowResizeAnchor
(仅macOS 26)时
references/scroll-and-tabs.md
配置
scrollEdgeEffectStyle
tabBarMinimizeBehavior
references/toolbar-and-slider.md
添加
ToolbarSpacer
Slider
刻度时

Cross-References

交叉参考

  • apple-liquid-glass-design
    — All Liquid Glass APIs (glassEffect, GlassEffectContainer, backgroundExtensionEffect, morph animations)
  • swiftui-input-api
    — Pre-iOS 26 TextEditor, text fields, pickers
  • swift-app-lifecycle
    — Scene phase management, app entry points
  • swiftui-effects-api
    — Pre-iOS 26 blur, shadow, opacity effects
  • apple-liquid-glass-design
    — 所有Liquid Glass API(glassEffect、GlassEffectContainer、backgroundExtensionEffect、形态动画)
  • swiftui-input-api
    — iOS 26之前的TextEditor、文本框、选择器
  • swift-app-lifecycle
    — 场景阶段管理、应用入口点
  • swiftui-effects-api
    — iOS 26之前的模糊、阴影、透明度效果