swiftui-26-api
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSwiftUI 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, morph animations), loadbackgroundExtensionEffectskill instead.apple-liquid-glass-design
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 with an binding and to track the insertion point or selected range.
TextEditorAttributedStringAttributedTextSelectionswift
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+
结合绑定与使用,以跟踪插入点或选中范围。
AttributedStringAttributedTextSelectionTextEditorswift
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 to restrict which formatting attributes are valid in a .
AttributedTextFormattingDefinitionTextEditorswift
struct MyTextFormattingDefinition: AttributedTextFormattingDefinition {
var body: some AttributedTextFormattingDefinition<
AttributeScopes.SwiftUIAttributes
> {
ValueConstraint(
for: \.underlineStyle,
values: [nil, .single],
default: .single)
MyAttributedTextValueConstraint()
ContactsArePurple()
}
}iOS 26+ · macOS 26+
定义以限制中允许使用的格式属性。
AttributedTextFormattingDefinitionTextEditorswift
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 WebKitDisplays 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 to activate SwiftUI scenes from a UIKit app.
UIHostingSceneDelegateswift
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+
使用从UIKit应用中激活SwiftUI场景。
UIHostingSceneDelegateswift
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 skill — it contains complete glass adoption paths.
apple-liquid-glass-designB — Building a Rich Text Editor:
→
text-editing.mdfind-context.mdC — Embedding Web Content:
→ (if UIKit host)
webkit.mduikit-scene-bridge.mdD — Migrating an Existing App:
Migration sections are embedded in each reference file: (WKWebView → WebView), (UIHostingController → UIHostingSceneDelegate), (manual animatableData → @Animatable). For glass migration (.material → .glassEffect), see .
webkit.mduikit-scene-bridge.mdanimatable-macro.mdapple-liquid-glass-designE — macOS-Specific Features:
→
macos-drag-and-windows.mdtoolbar-and-slider.mdF — Custom Shape Animation:
→ (if animating glass shapes)
animatable-macro.mdapple-liquid-glass-design针对常见开发目标整理的参考文件序列。
A — 采用Liquid Glass设计:
查看技能文档 — 包含完整的玻璃效果适配路径。
apple-liquid-glass-designB — 构建富文本编辑器:
→
text-editing.mdfind-context.mdC — 嵌入网页内容:
→ (若为UIKit宿主应用)
webkit.mduikit-scene-bridge.mdD — 迁移现有应用:
每个参考文件中都包含迁移章节:(WKWebView → WebView)、(UIHostingController → UIHostingSceneDelegate)、(手动实现animatableData → @Animatable)。玻璃效果迁移(.material → .glassEffect)请查看。
webkit.mduikit-scene-bridge.mdanimatable-macro.mdapple-liquid-glass-designE — macOS专属功能:
→
macos-drag-and-windows.mdtoolbar-and-slider.mdF — 自定义形状动画:
→ (若为玻璃形状动画)
animatable-macro.mdapple-liquid-glass-designCommon Gotchas
常见陷阱
- is
WebPage— all interactions must happen on the main actor@MainActor - One per
WebPage— only oneWebViewcan bind to a singleWebPageat a timeWebView - Drag container APIs are macOS 26 only — and
dragContainerare not available on iOSdraggable(containerItemID:) - availability is broad — the macro works back to iOS 13, but requires Swift 5.9+ compiler
@Animatable - uses environment — access via
FindContext, returns optional@Environment(\.findContext) - selection requires
TextEditor—AttributedStringbinding doesn't work with plainAttributedTextSelectionString
- 为
WebPage— 所有交互必须在主Actor中执行@MainActor - 一个对应一个
WebView— 一个WebPage同一时间只能绑定一个WebViewWebPage - 拖拽容器API仅适用于macOS 26 — 和
dragContainer在iOS上不可用draggable(containerItemID:) - 兼容性广泛 — 该宏可回溯至iOS 13,但需Swift 5.9+编译器支持
@Animatable - 通过环境访问 — 通过
FindContext获取,返回可选值@Environment(\.findContext) - 选中功能需搭配
TextEditor—AttributedString绑定无法与普通AttributedTextSelection配合使用String
Troubleshooting
故障排查
| Symptom | Cause | Fix |
|---|---|---|
| Missing framework import | Add |
| Compiler too old | Requires Swift 5.9+ (Xcode 15+), even though protocol availability is iOS 13+ |
| Applied to wrong container | Only works on |
| Missing scene declaration | Ensure |
| Not accessing via environment | Use |
| Not stored as @State | Declare as |
| Missing resizability setting | Set |
| Selection bound to String | |
| macOS 26 only | Guard with |
| 症状 | 原因 | 解决方法 |
|---|---|---|
找不到 | 缺少框架导入 | 添加 |
| 编译器版本过旧 | 需Swift 5.9+(Xcode 15+),尽管协议兼容性可回溯至iOS 13+ |
| 应用到错误容器 | 仅对 |
| 缺少场景声明 | 确保实现 |
运行时 | 未通过环境访问 | 使用 |
| 未声明为@State | 声明为 |
缩小窗口时 | 缺少可调整性设置 | 在Scene上设置 |
| 选中绑定到String | |
iOS上 | 仅适用于macOS 26 | 使用 |
Reference Files
参考文件
| File | Read when... |
|---|---|
| using |
| building |
| implementing find/replace via |
| embedding web content with |
| bridging UIKit scene lifecycle to SwiftUI via |
| adding |
| configuring |
| adding |
| 文件 | 适用场景 |
|---|---|
| 使用 |
| 构建支持 |
| 通过 |
| 使用 |
| 通过 |
| 添加 |
| 配置 |
| 添加 |
Cross-References
交叉参考
- — All Liquid Glass APIs (glassEffect, GlassEffectContainer, backgroundExtensionEffect, morph animations)
apple-liquid-glass-design - — Pre-iOS 26 TextEditor, text fields, pickers
swiftui-input-api - — Scene phase management, app entry points
swift-app-lifecycle - — Pre-iOS 26 blur, shadow, opacity effects
swiftui-effects-api
- — 所有Liquid Glass API(glassEffect、GlassEffectContainer、backgroundExtensionEffect、形态动画)
apple-liquid-glass-design - — iOS 26之前的TextEditor、文本框、选择器
swiftui-input-api - — 场景阶段管理、应用入口点
swift-app-lifecycle - — iOS 26之前的模糊、阴影、透明度效果
swiftui-effects-api