iOS Development Rules 是一套面向 iOS 开发的规则集合,共 38 条,目标是帮助开发者写出达到生产质量的 iOS 应用。每条规则都针对大语言模型常见的错误,并给出具体的修正方案。
无障碍(Accessibility)
减少动态效果(Reduce Motion):通过 @Environment(.accessibilityReduceMotion) 读取设置,启用时将 .spring() 替换为 .easeInOut(duration: 0.2),把滑动转场替换为 .opacity,关闭自动播放动画;保留功能性动画(如进度条),移除装饰性动画。
减少透明度(Reduce Transparency):通过 @Environment(.accessibilityReduceTransparency) 读取设置,启用时用不透明背景替代材质/模糊效果。
VoiceOver 标签:所有可交互元素使用 .accessibilityLabel(),非显而易见的操作使用 .accessibilityHint(),装饰性图片使用 .accessibilityHidden(true),信息性图片提供描述性标签,仅图标的按钮必须有 .accessibilityLabel()。
分组与合并:相关内容(图标+标签+数值)使用 .accessibilityElement(children: .combine),自定义阅读顺序用 .ignore 加手动标签。
无障碍特征:区块标题加 .isHeader,播放媒体按钮加 .startsMediaSession,汇总值加 .isSummaryElement,选中项加 .isSelected。
焦点管理:使用 @FocusState 配合字段枚举实现表单导航,用 .submitLabel(.next) 和 .submitLabel(.done),并通过 .onSubmit 串联字段。
动态字体(Dynamic Type):使用系统文字样式自动缩放,绝不用 .font(.system(size:));布局在大字号下破裂时可将 .minimumScaleFactor(0.8) 作为最后手段;用 Xcode Environment Overrides 在最大无障碍字号下测试;用 ScrollView 包裹可能溢出的内容。
颜色与对比度:状态不要仅用颜色表达,应配合图标和文字;正文最低 4.5:1 对比度,大字号最低 3:1;弱化文字用 .foregroundStyle(.secondary)。
无障碍自定义控件:自定义滑块/步进器使用 .accessibilityValue() 和 .accessibilityAdjustableAction(),自定义开关加 .isToggle 特征与开/关值,进度指示器用百分比值。
App Clips:需要单独的 App Clip target(在 plan 的 extensions 数组中 kind 为 "app_clip")。Info.plist 中的 NSAppClip 字典自动配置;关联域与父应用标识符在 project.yml entitlements 中自动配置。App Clip 体验 URL 在 App Store Connect 配置,用户可通过 NFC、二维码、地图等启动。接收 URL 使用 .onContinueUserActivity(NSUserActivityTypeBrowsingWeb)。用 SKOverlay 引导下载完整应用。限制包括:App Clip 二进制必须小于 15 MB,无法访问 HealthKit、CallKit、SiriKit,后台模式受限,使用 @AppStorage 做轻量持久化(不能用 SwiftData)。
App Review(StoreKit):导入 StoreKit 并使用 @Environment(.requestReview),调用 requestReview() 由 Apple 处理弹窗,应在有意义互动后触发(如启动次数 >= 5 或完成关键任务),通过 @AppStorage("launchCount") 跟踪;Apple 每年限制 3 次提示,切勿在首次启动、出错、崩溃或购买后立即请求。
Apple 端上翻译:使用 Translation 框架(iOS 17.4+,端上运行,无需联网,无需 API key)。该框架用于按需翻译用户内容,而非应用本地化(.strings 文件),不要混淆。可用 .translationPresentation 修饰符弹出系统翻译面板,或使用 TranslationSession 以编程方式翻译。可通过 Translation.supportedLanguages 查看设备支持的语言对,部分语言对首次使用需下载模型,无需特殊权限或 Info.plist 键。
生物识别:导入 LocalAuthentication,使用 LAContext().evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics),需要 NSFaceIDUsageDescription 权限;先检查 canEvaluatePolicy,不可用时回退到密码;用 biometryType 区分 Face ID、Touch ID 与无;始终提供手动解锁备选方案。
相机与照片:相册选择用 PhotosPicker(PhotosUI),有限访问无需权限;相机拍摄需 AVCaptureSession + AVCapturePhotoOutput + UIViewControllerRepresentable 封装,需要 NSCameraUsageDescription 权限;完整照片库需要 NSPhotoLibraryUsageDescription。用 @State 的 PhotosPickerItem 配合 .onChange 加载,通过 try await item.loadTransferable(type: Data.self) 获取图像。
Swift Charts:导入 Charts,使用 Chart { } 容器,用 BarMark、LineMark、AreaMark、PointMark、RuleMark 可视化数据,用 .foregroundStyle(by:) 做颜色编码,用 chartXAxis/chartYAxis 自定义坐标轴。将 Chart 抽取为独立计算属性以避免 body 过于复杂,大数据集用 .chartScrollableAxes(.horizontal)。
颜色与对比度:正文(<20pt)最低 4.5:1,大字号(20pt+ 常规或 14pt+ 粗体)最低 3:1,UI 组件最低 3:1,推荐 7:1。语义色使用需规范:红色用于删除/错误/严重警告,绿色用于成功/完成,橙色用于警告,蓝色用于信息/链接/主要操作;绝不把红色用于正面操作或绿色用于破坏性操作。绝不只依赖颜色,状态需颜色+图标+文字,图表需配合图案、形状或标签。系统自适应色 .primary、.secondary、Color(.systemBackground) 可自动适配明暗。深色模式颜色配对:每个自定义颜色必须有明暗两套变体,两套都需独立满足对比度要求,并分别测试。AppTheme 颜色模式:有外观切换时用 Color(light:dark:) 扩展,定义语义 token(如 AppTheme.Colors.primary、.surface、.error、.success),视图中绝不使用原始十六进制字符串。图片/渐变上的文字需加深色遮罩或阴影处理。不透明度:文字避免低于 .opacity(0.6),禁用状态用 .disabled() 自动处理,占位文字用 .foregroundStyle(.secondary)。
组件模式:按钮层级每个屏幕/区块只保留一个主按钮(.borderedProminent,可配合 .controlSize(.large)),次按钮用 .bordered,低强调用 .borderless,破坏性按钮用 .borderedProminent 加 .tint(.red)。始终使用 Button() 而非 .onTapGesture,禁用用 .disabled(condition)。卡片设计给出了包含图标、元数据、标题、描述、圆角与阴影的 VStack 结构示例。输入字段状态覆盖正常、聚焦、错误、禁用,错误时用红色描边并在字段下方显示错误信息。加载状态按场景选择:内联 spinner(ProgressView().controlSize(.small))、全屏加载、下拉刷新(.refreshable)、骨架屏(.redacted(reason: .placeholder))、遮罩。加载时禁用触发按钮防止重复点击,超过 300ms 的操作才显示加载。还包含徽章/标签、开关、选择器(2-4 项用分段样式,5+ 项用菜单或导航链接,日期用 DatePicker)、空状态(始终用 ContentUnavailableView,含图标、标题、描述和操作按钮)、分隔线等模式。
深色模式:系统/浅色/深色三选一是标准模式,用 @AppStorage("appearance") 存储,.preferredColorScheme() 必须放在 @main 应用的最外层容器,而非仅设置视图。自适应主题色无需颜色资源,将 AppTheme 中所有 Color(hex:) 改为带明暗两个十六进制值的 Color(light:dark:),它基于 UIColor(dynamicProvider:) 会自动响应。深色调色板由开发者根据应用调性决定:加深背景(如 #1C1C1E、#2C2C2E),略微提亮强调色,文字用 Color.primary/Color.secondary。
设计系统:每个应用必须使用集中的主题,用嵌套枚举组织 Colors、Fonts、Spacing,不要用扁平的顶层静态属性枚举。资料给出了 AppTheme 示例,包含 accent、textPrimary、textSecondary、background、surface、cardBackground 等颜色,以及 largeTitle、title、headline 等字体。
适用场景:希望在 iOS 项目(尤其是 SwiftUI)中落地高质量编码规范的开发者,或使用大语言模型辅助生成 iOS 代码时用作校验与纠错参考。
限制:以上内容为规则与实现指引,具体项目需自行适配;资料未提供安装命令、收费、价格、平台要求或效果承诺等信息。