企业官网建设流程全解析

处理软废弃 API

本文件涵盖遇到软废弃的 SwiftUI API 时如何处理。废弃到现代的转换的实际列表，请参阅references/latest-apis.md。

"软废弃"的含义

软废弃的 API 在 SDK 头文件中被标记为废弃，但使用占位符废弃版本号（100000.0）抑制编译器警告。它仍然可以编译并正常工作——只是表明该 API 不应在新代码中使用。示例包括NavigationView（改用NavigationStack/NavigationSplitView）、ActionSheet/Alert（改用.confirmationDialog/.alert修饰符）、MagnificationGesture（重命名为MagnifyGesture）和PresentationMode（改用\.dismiss）。

因为这些仍然有效，将它们视为信息性的，而不是紧急的。

作用域规则——先读这个

所有软废弃指导都限定在你直接修改的代码范围内。如果一个文件包含多个视图而任务只涉及其中一个，其他视图不在范围内。

• 只讨论你实际编辑的视图。
• 不要提及、标记或提议迁移你没有要求改动的代码中的软废弃 API——包括"顺便问一下，要我顺便把OtherView也迁移了吗？"之类的话。
• 这优先于任何要求"观察"或"其他说明"的提示。

在未触碰的代码中提及软废弃 API 会产生噪音、分散任务注意力，并给用户带来无关工作的压力。

生成新代码时

绝不引入软废弃 API 的新用法。如果你不确定某个 API 是否软废弃，在推荐它之前检查references/latest-apis.md——任何在之前版本中有效的 API 此后都可能已被软废弃。

被要求审查、重构、现代化或清理时

指出被审查代码中的软废弃 API，并建议现代替代品。保持信息性语气——这些仍然可以编译和运行，因此将迁移描述为改进，而不是 bug 修复。

被要求添加功能或修复 bug 时

如果你正在编辑的视图已经使用了软废弃 API，在你的改动中保持原样。不要在添加搜索栏的同时静默地将NavigationView换成NavigationStack——那会产生意外的 diff、带来回归风险（状态重置、导航行为变化），并使改动更难审查。交付所请求的改动后，你可以添加一句简短的话，提议将迁移作为单独的步骤。

如果同一文件中的另一个视图使用了软废弃 API，完全忽略它（见作用域规则）。

一般指导

• 绝不在从零编写的代码中引入软废弃 API 的新用法。
• 不要主动扫描代码库寻找软废弃 API——只在它们出现在你为用户请求而直接修改的代码中时注意它们。
• 迁移是真实的行为风险编辑；它们应该属于自己独立的改动，而不是捆绑进无关的工作。