expo-ios-hig

Expo iOS HIG 最佳实践

面向 Expo（React Native） 中 iOS 26 应用的设计规则，帮助应用遵循 Apple 人机界面指南，呈现真正原生的体验。包含 8 个类别中的 46 条规则，并根据各项决策对原生体验和 HIG 合规性的影响程度确定优先级。所有示例均为 TSX/Expo——展示的是你在 React Native 和 TypeScript 中作出的决策，而非 Swift。

核心理念：React Native 应用只有在充分利用平台能力时才会有原生感——使用系统导航控制器、系统控件、语义颜色、SF Symbols、真实触感反馈和系统分享菜单，而不是用 JavaScript 重新实现 iOS。这些规则会告诉你，哪些决策能带来原生感，哪些决策会在不知不觉中失去这种体验。

适用场景

在以下情况下，请参考这些指南：

• 在 Expo 应用中构建或审查 iOS 屏幕、导航、列表或表单
• 选择导航方式：Expo Router 原生堆栈或 JS 堆栈、原生标签页、工作表、模态视图、大标题
• 选择控件：何时使用原生 Alert、ActionSheetIOS、日期选择器、Switch、SF Symbols，或改用 @expo/ui
• 针对平台进行样式设计：安全区域、深色模式、语义颜色、iOS 字体排版比例、间距、Liquid Glass
• 让交互更具原生感：触控目标、按压反馈、滑动操作、下拉刷新、手势、触感反馈
• 添加动画、加载／空状态、无障碍支持、权限和启动优化

不适用场景

• @expo/ui 组件 API——有关如何使用 @expo/ui/swift-ui 组件、Host 边界和修饰符，请使用 expo-ui 技能。此技能介绍哪些决策能让应用更具原生感，并在适合切换到 SwiftUI 时指向 @expo/ui；但不会重新介绍该 API。
• 跨平台设计系统本身——有关共享的 Unistyles 主题、设计令牌、由变体驱动的组件 API，以及如何让组件在 Web 和 iOS 上都具有原生感，请使用 expo-design-system 技能。此技能负责 iOS 原生体验；该技能则负责两个前端共用的令牌和组件架构。
• 原生 Swift／SwiftUI——如需在原生 Swift 代码库中应用 HIG，请使用 ios-hig 或 ios-design。此技能的示例全部使用 React Native/TSX。
• Android——这些规则针对 iOS 规范。请使用平台自适应代码，让 Android 遵循 Material 规范；不要在 Android 上套用 iOS 设计惯例。

按优先级划分的规则类别

优先级	类别	影响程度	前缀
1	原生导航架构	严重	nav-
2	原生组件保真度	严重	native-
3	布局与自适应	高	layout-
4	触控、手势与触感反馈	高	touch-
5	视觉系统与 Liquid Glass	高	visual-
6	动画与反馈	中高	motion-
7	无障碍	中高	acc-
8	系统集成与优化	中	system-

快速参考

1. 原生导航架构（严重）

• nav-native-stack — 使用 Expo Router 的原生 Stack 构建屏幕层级
• nav-native-tabs — 在顶层分区采用原生标签页
• nav-large-titles — 在顶层屏幕启用大标题
• nav-sheet-detents — 将次要任务作为带有停靠点的工作表呈现
• nav-push-vs-present — 使用推入导航呈现层级关系，使用模态呈现处理独立任务
• nav-search-in-header — 将搜索放在导航栏中
• nav-system-back — 保留系统返回按钮和向后滑动手势

2. 原生组件保真度（关键）

• native-avoid-material-ui — 在 iOS 上避免使用 Material Design 组件套件
• native-sf-symbols — 使用 SF Symbols 表示图标
• native-system-alert — 使用原生警告框进行确认
• native-action-sheet — 使用操作表供用户选择操作
• native-datetime-picker — 使用原生日期和时间选择器
• native-switch-toggle — 使用平台的 Switch 控件设置布尔选项

3. 布局与适配（高）

• layout-safe-area-insets — 使用 safe-area context 遵循安全区域内边距
• layout-edge-to-edge — 将可滚动内容延伸至半透明栏下方
• layout-keyboard-avoidance — 确保输入框在键盘上方保持可见
• layout-dark-mode-semantic — 根据当前配色方案设置颜色
• layout-content-inset-under-bars — 为列表内容设置内边距，使其避开标签栏和主屏幕指示条
• layout-readable-width-ipad — 限制 iPad 和大屏幕上的阅读宽度

4. 触控、手势与触觉反馈（高）

• touch-hit-target — 将触控目标尺寸设为至少 44pt
• touch-pressable-feedback — 为每个控件提供即时按压反馈
• touch-swipe-actions — 为列表行提供滑动操作
• touch-pull-to-refresh — 使用 RefreshControl 实现下拉刷新
• touch-gesture-handler-thread — 使用 Gesture Handler 驱动交互式手势
• touch-haptics-on-outcome — 在有意义的操作结果出现时配合触觉反馈

5. 视觉系统与 Liquid Glass（高）

• visual-semantic-colors — 使用语义化系统颜色，而非硬编码的十六进制值
• visual-system-font — 使用系统字体显示界面文本
• visual-type-scale — 将文本样式映射到 iOS 字体级别
• visual-spacing-rhythm — 基于单一基础单位设置间距
• visual-liquid-glass-gated — 通过受版本控制的原生视图应用 Liquid Glass
• visual-tint-discipline — 将强调色保留给交互元素

6. 动效与反馈（中高）

• motion-ui-thread-animation — 在 UI 线程上运行动画
• motion-virtualized-lists — 使用虚拟化列表呈现长列表
• motion-loading-states — 加载时显示与内容形状相符的占位符
• motion-empty-states — 设计空状态，引导用户采取下一步操作
• motion-optimistic-updates — 对用户操作应用乐观更新

7. 无障碍功能（中高优先级）

• acc-roles-labels — 为交互控件和仅含图标的控件添加标签，以供 VoiceOver 使用
• acc-dynamic-type — 让文本随 Dynamic Type 缩放
• acc-reduce-motion — 遵循“减少动态效果”设置
• acc-state-and-hint — 向辅助技术公开控件状态
• acc-grouping-focus — 将相关元素分组，形成符合逻辑的焦点顺序

8. 系统集成与完善（中优先级）

• system-permissions-jit — 在恰当时机请求权限，并说明原因
• system-status-bar — 让状态栏样式与其背后的内容相匹配
• system-keyboard-type — 根据内容配置各文本字段
• system-share-sheet — 通过系统分享表单分享内容
• system-app-icon-launch — 配置真正的 App 图标和启动屏幕

使用方法

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

• 章节定义 — 类别结构和影响级别
• 规则模板 — 添加新规则的模板
• 参考文件：references/{prefix}-{slug}.md

每个规则文件都简要说明了它为何有助于营造原生体验，提供一个 Incorrect（非原生）的 TSX 示例、一个与之相比仅有最小差异的 Correct（原生）示例，以及一个权威参考 URL。在适用情况下，规则还会添加“何时不应使用此模式”或“替代方案”章节。

相关技能

• expo-ui — @expo/ui/swift-ui 组件 API 参考。此处的规则建议使用原生 SwiftUI 组件时，请参考它。
• ios-hig / ios-design — 适用于原生 Swift/SwiftUI 代码库的 HIG 和 Apple 设计原则。
• expo — Expo React Native 性能优化，与此处的动效和列表规则互为补充。