expo-ui

Expo @expo/ui SwiftUI 最佳实践

@expo/ui/swift-ui 和 @expo/ui/swift-ui/modifiers 的库参考——Expo 原生 UI 桥接在 iOS 上的接口。包含 8 个类别中的 53 条规则，并按级联影响排序，适用于构建在 iOS 26 及更早版本上渲染为原生 SwiftUI 视图的 Expo 应用。

何时应用

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

• 使用 @expo/ui/swift-ui 构建新屏幕——选择合适的容器（Form、List 还是 ScrollView），正确包裹在 Host 中，并应用修饰符
• 将 React Native 基础组件（View、Text、TouchableOpacity）迁移为原生 SwiftUI 组件
• 面向 iOS 26 功能——Liquid Glass 材质、GlassEffectContainer、新的 sheet detent 行为
• 审查从 @expo/ui/swift-ui 或 @expo/ui/swift-ui/modifiers 导入内容的代码
• 调试“SwiftUI 视图未渲染／尺寸错误／忽略样式”——通常是 Host 或修饰符问题
• 根据 HIG 模态规范组合呈现界面——Alert、ConfirmationDialog、BottomSheet、Popover
• 使用 useNativeState 和 worklet 写入来编写受控输入（TextField、Toggle、Picker、Slider）

何时不使用此技能

• Android Jetpack Compose——此技能仅涵盖 iOS SwiftUI。@expo/ui/jetpack-compose 接口有自己的惯例
• 通用（跨平台）组件——@expo/ui 提供的通用组件较少；此技能仅涵盖 iOS 平台专用接口
• 导航路由——对于堆栈／标签路由，请使用 expo-router 和 expo-router/unstable-native-tabs；此技能仅涵盖 UI 组合
• iOS 17 之前版本的回退方案——大多数规则假设最低版本为 iOS 17；Liquid Glass 规则要求 iOS 26

按优先级划分的规则类别

优先级	类别	影响	前缀
1	设置与 Host 边界	CRITICAL	host-
2	iOS 26 HIG 组合规则	CRITICAL	hig-
3	修饰符系统	CRITICAL	mod-
4	布局组件	HIGH	layout-
5	输入与控件	HIGH	input-
6	导航与叠层	HIGH	nav-
7	显示与反馈	MEDIUM-HIGH	display-
8	状态与跨领域模式	MEDIUM	state-

快速参考

1. 设置与 Host 边界（CRITICAL）

• host-wrap-all-swiftui-roots — 将每个 SwiftUI 子树包裹在 Host 中
• host-match-contents — 使用 matchContents 使 Host 尺寸与其 SwiftUI 内容一致
• host-viewport-size-for-form — 对 Form 和 List 使用 useViewportSizeMeasurement
• host-color-scheme-explicit — 覆盖系统设置时传入明确的 colorScheme
• host-ignore-safe-area — 仅对全屏延展的界面使用 ignoreSafeArea

2. iOS 26 HIG 组合规则（CRITICAL）

• hig-glass-effect-container — 将相邻的玻璃效果视图放在 GlassEffectContainer 中
• hig-no-glass-on-glass — 避免在玻璃界面上嵌套使用 glassEffect
• hig-no-stacked-modals — 先关闭一个 sheet，再呈现另一个
• hig-popover-iphone-fallback — 不要在 iPhone 上使用 Popover；请改用 BottomSheet
• hig-sheet-detents-partial — 添加一个部分 detent，以呈现 Liquid Glass 外观
• hig-confirmation-dialog-destructive — 使用 ConfirmationDialog + destructive role
• hig-tint-only-for-brand — tint 仅用于品牌界面，不用于破坏性操作

3. 修饰符系统（关键）

• mod-prop-not-style — 修饰符通过 modifiers 属性传递，而不是 RN 样式
• mod-composition-order — 修饰符的顺序很重要：每个修饰符都会包裹前一个
• mod-import-from-modifiers-subpath — 从 @expo/ui/swift-ui/modifiers 导入
• mod-frame-vs-fixedsize — frame 提议尺寸，fixedSize 则退出弹性布局
• mod-padding-vs-frame — padding 用于内部留白，frame 用于外部边界
• mod-presentation-on-sheet-content — 展示修饰符附加到工作表内容上
• mod-disabled-prop — 使用 disabled 修饰符，不要有条件地渲染
• mod-animation-wraps-trigger — withAnimation 包裹由状态驱动的属性变更

4. 布局组件（高优先级）

• layout-hstack-vs-vstack — 根据内容流向选择堆栈方向
• layout-lazy-stack-for-long-lists — 长列表应在 ScrollView 中使用 LazyVStack
• layout-form-for-settings — Form 会自动采用 iOS 分组样式
• layout-section-with-header-footer — 使用 Section 的页眉和页脚插槽
• layout-scrollview-axes — 水平或二维滚动时明确设置坐标轴
• layout-grid-vs-stack — 列对齐的内容使用 Grid

5. 输入与控件（高优先级）

• input-button-role-for-destructive — 删除按钮设置 role='destructive'
• input-button-systemimage — 按钮图标使用系统 systemImage SF Symbol
• input-textfield-observable-state — TextField 使用 useNativeState，而不是 React 状态
• input-securefield-for-passwords — 密码使用 SecureField，而不是 TextField
• input-toggle-on-async — 即时切换使用 SyncToggle，异步切换使用 Toggle
• input-picker-style-via-modifier — 使用 pickerStyle 修饰符选择外观
• input-date-picker-range — 使用范围限制可选日期
• input-stepper-bounded — 为 Stepper 提供最小值和最大值

6. 导航与覆盖层（高优先级）

• nav-alert-for-critical-only — Alert 仅用于阻塞性通知
• nav-context-menu-vs-swipe — 每行使用 ContextMenu 或 SwipeActions，不要同时使用
• nav-bottom-sheet-via-group — 使用 Group 包裹 BottomSheet 内容
• nav-share-link-system — 使用 ShareLink 打开系统分享面板
• nav-tabview-style-modifier — 使用 tabViewStyle 修饰符选择外观
• nav-disclosure-group-collapsible — 使用 DisclosureGroup 创建可折叠部分
• nav-link-not-button-for-urls — URL 使用 Link，应用内操作使用 Button
• nav-menu-primary-action — onPrimaryAction 用于区分轻点和长按

7. 显示与反馈（中高）

• display-text-markdown — 启用 markdownEnabled，以支持内联富文本
• display-image-system-name — 优先使用 systemName SF Symbols，而非 uiImage
• display-chart-data-points — ChartDataPoint 数组驱动原生坐标轴
• display-gauge-current-value-label — 提供 currentValueLabel，以支持无障碍功能
• display-progress-indeterminate — 未定义的值 → 加载指示器，0 → 冻结的进度条
• display-label-icon-vs-title — SF Symbols 使用 systemImage，自定义图标使用 icon 插槽

8. 状态与跨领域模式（中）

• state-use-native-state-for-fields — 对每个桥接输入使用 useNativeState
• state-worklet-writes — 从 worklet 更新 ObservableState
• state-controlled-via-selection-prop — 使用 selection 或 defaultSelection，不能同时使用
• state-platform-check-pre-26 — 使用版本检查，为仅适用于 iOS 26 的功能添加保护
• state-textfield-ref-imperative — 使用 TextFieldRef 控制焦点和选择

使用方法

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

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

每个规则文件都包含：

• 简要说明规则对 SwiftUI 桥接的重要性
• 基于真实领域场景的错误代码示例
• 与错误示例仅有最小差异的正确代码示例
• 适用时：替代方案、不适用场景、警告提示、权威参考 URL

注意事项

参见 gotchas.md — 在实际使用中发现故障点时，追加条目。

相关技能

• 对于 Android Jetpack Compose 组件，对应的技能应以 @expo/ui/jetpack-compose 为目标
• 对于导航路由（堆栈、标签页），直接使用 expo-router
• 对于表单验证库，请参见 react-hook-form 技能