ios-storyboard

iOS Storyboard 最佳实践

针对诊所项目中仍在使用的、以 Storyboard 为主的代码提供旧版互操作指南。不适用于新的 SwiftUI 诊所功能开发。

全面介绍 Xcode Storyboard 和 Interface Builder 的 UI 设计与架构指南，重点讲解如何构建易于维护、适配性强且无障碍的 iOS 界面。包含 8 个类别中的 45 条规则，按影响程度排序，为自动重构和代码生成提供指导。

诊所架构约定（iOS 26 / Swift 6.2）

本技能中的所有指南均基于诊所模块化 MVVM-C 架构：

• 功能模块仅导入 Domain + DesignSystem（绝不导入 Data，也不导入同级功能模块）
• App target 是汇合点，负责管理 DependencyContainer、具体协调器和 Route Shell 连接
• Domain 保持纯 Swift，定义模型以及 repository、*Coordinating、ErrorRouting 和 AppError 契约
• Data 负责 SwiftData／网络／同步／重试／后台 I/O，并实现 Domain 协议
• 读写流程默认采用先返回陈旧数据、再重新验证的读取方式，以及乐观排队写入
• ViewModel 直接调用 repository 协议（不设默认的 use-case／interactor 层）

适用场景

以下情况可参考这些指南：

• 在 Xcode Interface Builder 中创建或修改 Storyboard 场景
• 为适配性布局设置 Auto Layout 约束
• 使用 segue 和 storyboard 引用设计导航流程
• 为通用应用配置 size class 和 trait 变体
• 审查 storyboard XML 差异并解决合并冲突

按优先级划分的规则类别

优先级	类别	影响程度	前缀
1	Storyboard 架构	严重	arch-
2	Auto Layout 约束	严重	layout-
3	导航与 Segue	高	nav-
4	适配性布局与 Size Class	高	adapt-
5	视图层级与 Stack View	中高	view-
6	无障碍与 VoiceOver	中	ally-
7	版本控制与协作	中	vcs-
8	调试与检查	中低	debug-

快速参考

1. Storyboard 架构（严重）

• arch-split-storyboards - 将单体 Storyboard 拆分到各功能模块
• arch-storyboard-references - 使用 Storyboard 引用实现跨模块导航
• arch-one-scene-per-flow - 每个 Storyboard 限定为单个用户流程
• arch-initial-view-controller - 在每个 Storyboard 中显式设置初始视图控制器
• arch-avoid-hardcoded-identifiers - 避免硬编码 Storyboard 和 Cell 标识符
• arch-scene-naming - 在 Document Outline 中使用描述性场景标签
• arch-modular-xibs - 将可复用视图提取到独立的 XIB 文件中

2. 自动布局约束（关键）

• layout-avoid-fixed-dimensions - 避免固定宽度和高度约束
• layout-leading-trailing - 使用 Leading 和 Trailing，而不是 Left 和 Right
• layout-safe-area - 将视图约束到安全区域参考线
• layout-content-hugging - 设置内容拥抱和压缩阻力优先级
• layout-constraint-nearest-neighbor - 将视图约束到最近的相邻视图
• layout-avoid-constant-offsets - 使用布局边距，而不是固定偏移量
• layout-inequality-constraints - 使用不等式约束设置灵活的最小值和最大值
• layout-constraint-priorities - 为可选约束分配不同的优先级

3. 导航与 Segue（高）

• nav-prepare-for-segue - 通过 prepare(for:sender:) 传递数据，而不是直接访问属性
• nav-unwind-segues - 使用 Unwind Segue 向后导航
• nav-avoid-mixed-navigation - 避免混用 Segue 和编程式导航
• nav-adaptive-segues - 使用 Show 和 Show Detail，而不是 Push 和 Modal
• nav-perform-segue-validation - 使用 shouldPerformSegue 验证 Segue 条件
• nav-container-view-controllers - 使用容器视图嵌入子视图控制器

4. 自适应布局与尺寸类别（高）

• adapt-size-classes - 使用 Vary for Traits 按尺寸类别配置约束
• adapt-trait-variations - 使用 Trait Variations 调整字体和间距
• adapt-safe-area-all-devices - 在所有设备尺寸类别上测试自适应布局
• adapt-readable-content-guide - 在大屏幕上使用可读内容参考线显示文本
• adapt-dynamic-type - 为所有文本标签支持动态字体

5. 视图层级与堆栈视图（中高）

• view-prefer-stack-views - 对于线性布局，使用堆栈视图，而不是手动设置约束
• view-avoid-deep-nesting - 避免堆栈视图嵌套超过两层
• view-intrinsic-content-size - 使用标准 UIKit 控件的固有内容尺寸
• view-placeholder-intrinsic-size - 在 Storyboard 中为自定义视图使用占位符固有尺寸
• view-clip-to-bounds - 为带圆角的视图启用 Clip to Bounds
• view-content-mode - 在 Storyboard 中为 UIImageView 设置正确的内容模式

6. 无障碍与 VoiceOver（中）

• ally-labels - 为所有交互元素设置无障碍标签
• ally-traits - 在 Interface Builder 中分配正确的无障碍特征
• ally-grouping - 对相关元素分组，以便通过 VoiceOver 导航
• ally-identifiers - 为 UI 测试设置无障碍标识符
• ally-dynamic-labels - 更新动态内容的无障碍标签

7. 版本控制与协作（中）

• vcs-one-scene-per-developer - 为每位开发者分配 Storyboard 场景
• vcs-open-as-source - 提交前以源代码形式审查 Storyboard 差异
• vcs-lock-storyboard-files - 使用 Git 文件锁定来处理正在编辑的 Storyboard
• vcs-gitattributes-merge - 配置 .gitattributes，为 Storyboard 使用并集合并

8. 调试与检查（低至中）

• debug-view-hierarchy - 使用 Debug View Hierarchy 检查布局问题
• debug-ambiguous-layout - 使用 hasAmbiguousLayout 在运行时检测约束问题
• debug-constraint-identifier - 为约束分配标识符，以便查看易读的日志
• debug-stale-outlets - 移除过期的 Outlet 连接，避免崩溃

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息