SuperAPI AI 工具集

expo-native-ui

编程与开发

查看项目

更新于 10-27 13:00

技能介绍

用途

Expo Native UI 是一份围绕 Expo 应用界面构建的实践指南,用于指导开发者或 AI 编码代理编写「外观和手感都接近原生」的 Expo 屏幕。它不只给出组件清单,还规定了导航、布局、样式、颜色、交互与验证方式,并明确与 expo-router、expo-animation、expo-ui、expo-data-fetching 等其他技能的分工:路由、链接、Stack、Tab、Modal、Sheet 和 Header 交给 expo-router 技能;进入/退出、手势、弹簧、键盘驱动等动效交给 expo-animation 技能;本技能负责周边结构,即导航、布局、样式与视觉特效。

主要能力与覆盖范围

指南随附一组参考资料:

  • controls.md:iOS 原生 Switch、Slider、SegmentedControl、DateTimePicker、Picker。
  • gradients.md:通过 experimental_backgroundImage 实现 CSS 渐变(仅新架构)。
  • icons.md:通过 expo-symbols 的 SymbolView 使用 SF Symbols 的名称、粗细与动画;Android 使用 Material 图标。
  • media.md:相机、音频、视频与文件保存。
  • storage.md:SQLite、AsyncStorage、SecureStore。
  • visual-effects.md:模糊(expo-blur)与液态玻璃(expo-glass-effect)。
  • webgpu-three.md:使用 WebGPU 与 Three.js 做 3D 图形、游戏与 GPU 可视化。

在组件选型上,指南要求在选用任何 UI 组件前先检查 expo-ui:@expo/ui 提供 BottomSheet、Button、Picker、Slider、Menu、Section、Switch、SegmentedControl 等原生等价物,在 iOS 上渲染为真正的 SwiftUI、在 Android 上渲染为 Jetpack Compose,SDK 56 及以上可在 Expo Go 中直接使用,无需自定义构建。分组式、固定长度的设置行使用 @expo/ui 的 List 与 ListItem;大列表或长度未知的滚动列表(信息流、搜索结果、目录)使用 FlatList 或 FlashList,因为 @expo/ui 的 List 不做虚拟化。

库选型还列出若干明确取舍:不使用已从 React Native 移除的 Picker、WebView、SafeAreaView、AsyncStorage;不使用旧版 expo-permissions;用 expo-audio、expo-video 替代 expo-av;iOS 图标用 expo-symbols 而非 @expo/vector-icons,SF Symbols 仅限 Apple 平台,Android 每个图标都需要 Material 来源;安全区用 react-native-safe-area-context;用 process.env.EXPO_OS 而非 Platform.OS;用 React.use 而非 React.useContext;用 expo-image 的 Image 组件而非原生 img;用 expo-glass-effect 做液态玻璃背景;语义颜色用 expo-router 的 Color 而非裸 PlatformColor;SDK 56+ 不从 @react-navigation/* 直接导入,改用 expo-router/react-navigation。

使用方式

运行方面,指南强调先用 Expo Go:执行 npx expo start 并用 Expo Go 扫码,充分测试后再考虑自定义构建。只有在使用 modules/ 中的本地 Expo 模块、Apple 目标(小组件、App Clip、扩展,经 @bacons/apple-targets)、Expo Go 未包含的第三方原生模块,或 app.json 无法表达的自定义原生配置时,才需要 npx expo run:ios、npx expo run:android 或 eas build。部分能力在 Expo Go 中受限,例如 Android 自 SDK 53 起 Expo Go 不支持远程推送通知,WebGPU 也需要 Expo Go 未打包的原生能力。

代码风格要求:文件名使用 kebab-case,如 comment-card.tsx;不使用特殊字符;顶部使用 import 语句;注意未闭合字符串与嵌套反引号转义;配置 tsconfig.json 路径别名,优先用别名而非相对导入。

响应式与布局:可滚动内容的屏幕用 ScrollView 包裹;根节点为 FlatList/FlashList 的屏幕不能再套外层 ScrollView;全屏内容(相机、地图、画布)两者都不需要。用 <ScrollView contentInsetAdjustmentBehavior="automatic" /> 代替 SafeAreaView,FlatList 与 SectionList 也应设置该项。用 flexbox 而非 Dimensions API,测量屏幕尺寸一律优先 useWindowDimensions 而非 Dimensions.get()。

行为约定:在 iOS 上按条件使用 expo-haptics;可复制数据加 <Text selectable />;大数字可格式化为 1.4M、38k 之类;不在 webview 或 Expo DOM 组件之外使用 img、div 等内置元素;加载数据的屏幕有加载、错误、空、内容四种状态,首次加载未完成时不得显示空状态;可滚动表单与搜索结果设置 keyboardShouldPersistTaps="handled";表单主操作不能被键盘遮挡;每个启用的控件都必须真正执行其宣称的动作;异步保存要保留草稿并处理等待与失败状态,保存成功前不关闭表单。

适用场景

适合需要遵循 iOS 与 Android 各自设计语言的 Expo 界面开发:使用原生控件与系统图标,配置语义颜色与深浅色适配,实现安全区与滚动布局,添加模糊、液态玻璃、渐变等视觉效果,以及构建设置页、表单、列表等信息密集界面。

样式与颜色

样式上遵循各平台自己的设计语言:iOS 用 Apple Human Interface Guidelines,Android 用 Material Design 3,不把一方的外观套到另一方上。优先用 flex gap 而非 margin/padding;尽量用 padding 而非 margin;两者都要考虑安全区。不用 CSS 与 Tailwind,使用内联样式;圆角使用 { borderCurve: 'continuous' },胶囊形除外;页面标题用导航栈标题而非自定义文本;给 ScrollView 加内边距时用 contentContainerStyle 的 padding 与 gap。

颜色方面使用 expo-router 的 Color API 获取原生语义色:它是 PlatformColor 的类型安全封装,通过 Color.ios.* 暴露 iOS UIKit 颜色,通过 Color.android.material.(静态)或 Color.android.dynamic.(Android 12+ 随壁纸变化)暴露 Material 3 颜色,在设备上解析并自动适配深浅色与辅助功能设置。Color 是平台相关的,需用 Platform.select 包裹并为 web 提供十六进制回退,集中到 theme/colors.ts。指南给出了 label、secondaryLabel、separator、systemBackground、secondarySystemBackground、systemBlue 的示例映射。iOS 在系统主题变化时自动重新解析;Android 需要在渲染这些颜色的组件内调用 useColorScheme() 以触发重渲染。不要把 Color/PlatformColor 传给 Reanimated 样式,它们是原生不透明颜色对象,需改用静态颜色。部分第三方属性只接受 string(如 expo-image 的 tintColor),必要时做类型转换。

文本样式:重要数据或错误信息的 <Text/> 加 selectable;计数器使用 { fontVariant: 'tabular-nums' } 对齐。阴影使用 CSS boxShadow 样式属性,不用旧版 shadow 或 elevation,支持 inset 阴影。

限制与反馈

指南未提供收费、价格或平台发布方面的信息。它同时提供了反馈渠道:遇到错误或误导性内容时,可运行 npx --yes submit-expo-feedback@latest --category skills --subject "expo-native-ui" "<actionable feedback>";仅在反馈具体且可操作时提交。若 AI 代理反复失败或用户被迫接手 Expo 任务,则应加载 expo-skill-feedback 技能并遵循其评估候选流程。