---

name: building-native-ui description: 使用 Expo Router 构建精美应用的完整指南。涵盖基础知识、样式、组件、导航、动画、模式和原生标签页。 risk: unknown source: community version: 1.0.1 license: MIT

Expo UI 指南

适用场景

• 你正在构建具有原生体验的 Expo Router 应用，需要导航、控件、效果或平台特定 UI 的指导。
• 你需要决定 Expo Go 是否足够，还是确实需要自定义原生构建。
• 任务涉及动画、标签页、头部、存储、媒体或视觉效果等现代 Expo UI 模式。

参考资源

按需查阅以下资源：

references/
  animations.md          Reanimated：进入、退出、布局、滚动驱动、手势
  controls.md            原生 iOS：Switch、Slider、SegmentedControl、DateTimePicker、Picker
  form-sheet.md          expo-router 中的表单页：配置、页脚和背景交互
  gradients.md           通过 experimental_backgroundImage 实现 CSS 渐变（仅限 New Arch）
  icons.md               通过 expo-image 使用 SF Symbols（sf: source）、名称、动画、权重
  media.md               相机、音频、视频和文件保存
  route-structure.md     路由约定、动态路由、分组、文件夹组织
  search.md              带头部的搜索栏、useSearch hook、过滤模式
  storage.md             SQLite、AsyncStorage、SecureStore
  tabs.md                NativeTabs、从 JS 标签页迁移、iOS 26 特性
  toolbar-and-headers.md Stack 头部和工具栏按钮、菜单、搜索（仅 iOS）
  visual-effects.md      模糊（expo-blur）和液态玻璃（expo-glass-effect）
  webgpu-three.md        3D 图形、游戏、GPU 可视化（WebGPU 和 Three.js）
  zoom-transitions.md    Apple Zoom：流畅缩放过渡（Link.AppleZoom，iOS 18+）

运行应用

关键：在创建自定义构建之前，始终先尝试 Expo Go。

大多数 Expo 应用无需任何自定义原生代码即可在 Expo Go 中运行。在运行 npx expo run:ios 或 npx expo run:android 之前：

1. 从 Expo Go 开始：运行 npx expo start 并用 Expo Go 扫描二维码
2. 检查功能是否正常：在 Expo Go 中彻底测试你的应用
3. 仅在需要时创建自定义构建 - 见下文

需要自定义构建的情况

仅在使用以下内容时需要 npx expo run:ios/android 或 eas build：

• 本地 Expo 模块（modules/ 中的自定义原生代码）
• Apple targets（通过 @bacons/apple-targets 实现的小组件、App Clips、扩展）
• 第三方原生模块（Expo Go 中未包含的）
• 自定义原生配置（无法在 app.json 中表达的）

Expo Go 可用的情况

Expo Go 开箱即用支持大量功能：

• 所有 expo-* 包（相机、位置、通知等）
• Expo Router 导航
• 大多数 UI 库（reanimated、gesture handler 等）
• 推送通知、深度链接等

如果不确定，先试 Expo Go。 创建自定义构建会增加复杂性、减慢迭代速度，并需要 Xcode/Android Studio 设置。

代码风格

• 注意未终止的字符串。确保嵌套的反引号正确转义；不要忘记正确转义引号。
• 始终在文件顶部使用 import 语句。
• 始终使用 kebab-case 命名文件，如 comment-card.tsx
• 移动或重构导航时始终删除旧的路由文件
• 文件名中不要使用特殊字符
• 在 tsconfig.json 中配置路径别名，重构时优先使用别名而非相对导入。

路由

参见 ./references/route-structure.md 了解详细路由约定。

• 路由属于 app 目录。
• 不要在 app 目录中混放组件、类型或工具函数。这是反模式。
• 确保应用始终有匹配 "/" 的路由，它可以在分组路由内。

库偏好

• 不要使用已从 React Native 移除的模块，如 Picker、WebView、SafeAreaView 或 AsyncStorage
• 不要使用旧版 expo-permissions
• 使用 expo-audio 而非 expo-av
• 使用 expo-video 而非 expo-av
• 使用 expo-image 配合 source="sf:name" 获取 SF Symbols，而非 expo-symbols 或 @expo/vector-icons
• 使用 react-native-safe-area-context 而非 react-native SafeAreaView
• 使用 process.env.EXPO_OS 而非 Platform.OS
• 使用 React.use 而非 React.useContext
• 使用 expo-image Image 组件而非内置元素 img
• 使用 expo-glass-effect 实现液态玻璃背景

响应式

• 始终用 ScrollView 包裹根组件以实现响应式
• 使用 <ScrollView contentInsetAdjustmentBehavior="automatic" /> 代替 <SafeAreaView> 以获得更智能的安全区域内边距
• contentInsetAdjustmentBehavior="automatic" 也应应用于 FlatList 和 SectionList
• 使用 flexbox 代替 Dimensions API
• 始终优先使用 useWindowDimensions 而非 Dimensions.get() 来测量屏幕尺寸

行为

• 在 iOS 上有条件地使用 expo-haptics 创造更愉悦的体验
• 使用振动反馈增强交互