SDK 27 升级后 SwiftUI 编译报错与新 API…

当 SwiftUI 代码在升级到 iOS/macOS/watchOS/tvOS/visionOS 27 SDK 后出现编译错误、弃用警告，或需要使用 SDK 27 新增的 SwiftUI API 时使用。

适用场景

解决思路

1. 在编写或修改任何使用 SDK 27 新增或变更 SwiftUI API 的代码前，先阅读对应的 references/*.md 文件；这些 API 常有名称相近但闭包签名或行为不同的重载，凭记忆选错会导致编译失败或运行时行为错误。
2. 遇到 SwiftUI 视图中使用 @State 的编译错误时，必须先查阅 references/state-macro.md 再作答；不要采用「重排 init 赋值顺序」这一看似显然但错误的修复方式，它会带来错误的运行时行为。
3. @State 已从属性包装器迁移为宏，可能引发三类错误：init 中在其他存储属性之前给 @State 赋值导致「variable used before being initialized」；在 @State 上组合属性包装器导致「invalid redeclaration of synthesized property」；扩展中的成员逐一初始化委托导致「extraneous argument label」；按 state-macro.md 中的正确修复方式处理。
4. 使用 references/reorderable.md 为任意容器（List、stacks、grids、自定义布局）实现拖拽重排：在 ForEach 上加 .reorderable() 并配合 .reorderContainer(for:)，涵盖 ReorderDifference 的 apply 实现、section 与多集合、拖放集成（dragContainer/dropDestination），以及通过每个子项的 dropDestination(for:isEnabled:) 重载把一项拖到另一项上合并。iOS/macOS/watchOS/visionOS 27 可用，tvOS 不可用。
5. 使用 references/async-image.md 处理 AsyncImage 加载与缓存：默认应用标准 HTTP 缓存；新的 AsyncImage(request:) 初始化器接收 URLRequest 以设置每请求缓存策略；asyncImageURLSession(_:) 提供自定义 URLSession。iOS/macOS/watchOS/tvOS/visionOS 27 可用。
6. 使用 references/toolbar.md 处理工具栏：用 visibilityPriority 控制空间受限时哪些项保持可见、哪些移入溢出菜单；用 ToolbarOverflowMenu 指定始终溢出的项；用 .topBarPinnedTrailing 固定尾部项使其永不溢出；用 toolbarMinimizeBehavior 在滚动时最小化导航栏或工具栏；用 contentMarginsRemoved 移除内容边距；用 ToolbarPlacement.statusBar 控制状态栏可见性；工具栏构建器中现在支持 ForEach/EmptyView 动态内容。各 API 可用性不同，参见该 reference 的表格。
7. 使用 references/item-binding.md 从可选 item 绑定（sheet(item:) 形式）呈现 confirmationDialog 或 alert：绑定值变为非 nil 时呈现，并把解包后的值传入 actions 与 message 闭包。iOS/macOS/watchOS/tvOS/visionOS 27 可用。
8. 使用 references/swipe-actions.md 为任意可滚动容器（ScrollView 配 LazyVStack、LazyVGrid 或 stack）中的行添加滑动操作（滑动删除等），而不只是 List：在容器上标记 swipeActionsContainer()，并在每一行保留 swipeActions(edge:allowsFullSwipe:content:)，另含新的 onPresentationChanged 重载。iOS/macOS/watchOS/visionOS 27 可用，tvOS 不可用。
9. 使用 references/document-based-apps.md 构建或迁移文档型应用（含只读文档查看器）：新的 ReadableDocument/WritableDocument API（iOS/macOS/visionOS 27），只读查看器可仅用 ReadableDocument 配 DocumentGroup(viewer:makeReadableDocument:)；涵盖直接访问文件 URL、通过 DocumentReader/DocumentWriter 后台读写、快照、FileWrapperDocument{Reader,Writer} 便捷封装、包文档增量写入、Subprogress 进度上报、DocumentGroup 配置与撤销。部署目标为 iOS 27 / macOS 27 / visionOS 27 或更高时，新代码不要推荐 ReferenceFileDocument 或 FileDocument。
10. 使用 references/content-builder.md 处理统一结果构建器 @ContentBuilder 带来的源码不兼容：overlay/background 中 ShapeStyle 重载歧义、模块遮蔽 SwiftUI 类型时的类型引用歧义，以及 Swift Charts 中深度分支内容导致的类型检查性能回退。
11. 使用 references/deprecations.md 处理 SDK 27.0 中硬弃用的 API，例如 visionOS 上的 statusBarHidden（已无效果，应删除该调用）；软弃用 API 由 swiftui-specialist 技能覆盖。
12. 当用户询问「SwiftUI 在 [SDK 名] 27 中有什么新内容」或类似问题时，依据上述 references 进行总结。
13. 遇到构建错误、弃用警告或匹配已知 API 变更的模式时，应用 references 中记录的修复方式；不要臆造 references 中未记录的 API 或参数。

适用边界 · 注意事项

• tvOS 上不适用 reorderable 与 swipe actions 相关 API。
• 不要凭训练记忆选择名称相近的重载，也不要臆造未记录的 API 或参数。
• 不要用「重排 init 赋值顺序」修复 @State 编译错误。
• 部署目标为 iOS 27 / macOS 27 / visionOS 27 或更高时，新代码不要推荐 ReferenceFileDocument 或 FileDocument。