expo-react-native-coder

Expo React Native 编码最佳实践

Expo React Native 应用的全面功能开发指南。包含 10 个类别中的 50 条规则，涵盖从项目设置到测试的方方面面。还提供常见功能的生产就绪代码模板。

适用场景

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

• 使用 TypeScript 设置新的 Expo 项目
• 使用 Expo Router 构建导航（标签页、堆栈、抽屉、模态框）
• 创建屏幕（列表、详情、表单、设置）
• 使用受保护路由实现身份验证流程
• 配置深层链接和通用链接

按优先级划分的规则类别

优先级	类别	影响	前缀
1	项目设置与配置	CRITICAL	setup-
2	路由与导航	CRITICAL	route-
3	屏幕模式与布局	HIGH	screen-
4	数据获取与状态	HIGH	data-
5	身份验证与安全	HIGH	auth-
6	深层链接与通用链接	HIGH	link-
7	原生 UX 模式	MEDIUM-HIGH	ux-
8	表单与用户输入	MEDIUM	form-
9	资源与主题	MEDIUM	asset-
10	错误处理与测试	MEDIUM	test-

快速参考

1. 项目设置与配置（CRITICAL）

• setup-typescript-config - 使用严格模式配置 TypeScript
• setup-app-config-typescript - 使用类型化的 app.config.ts
• setup-environment-variables - 客户端变量使用 EXPO_PUBLIC_ 前缀
• setup-eas-build-profiles - 为各环境配置 EAS 构建配置文件
• setup-development-build - 开发构建与 Expo Go

2. 路由与导航（CRITICAL）

• route-file-based-routing - 使用 Expo Router 进行基于文件的路由
• route-tab-navigator - 使用路由组的标签页导航器
• route-dynamic-segments - 动态路由段 [param]
• route-stack-within-tabs - 标签页中的嵌套堆栈
• route-modal-presentation - 模态屏幕呈现方式
• route-typed-routes - 启用类型化路由
• route-drawer-navigator - 设置抽屉导航器

3. 屏幕模式与布局（HIGH）

• screen-list-flashlist - 大型列表使用 FlashList
• screen-detail-params - 通过参数传递最少量的数据
• screen-loading-state - 加载和错误状态
• screen-pull-to-refresh - 下拉刷新模式
• screen-header-options - 配置屏幕标题栏
• screen-settings-list - 使用 SectionList 的设置屏幕

4. 数据获取与状态（HIGH）

• data-api-routes - 服务端 API 路由
• data-secure-store - 使用 SecureStore 存储敏感数据
• data-sqlite-local - 使用 SQLite 存储复杂的本地数据
• data-fetch-on-focus - 屏幕获得焦点时重新获取数据
• data-async-storage-simple - 使用 AsyncStorage 存储偏好设置
• data-abort-controller - 卸载时取消 fetch 操作

5. 身份验证与安全（高）

• auth-protected-routes - Stack.Protected 守卫
• auth-context-provider - 带会话的身份验证上下文
• auth-oauth-flow - 使用 AuthSession 的 OAuth
• auth-login-form - 带验证的登录表单
• auth-splash-loading - 身份验证检查期间显示的启动屏幕

6. 深度链接与通用链接（高）

• link-deep-linking-scheme - 自定义 URL 方案
• link-universal-links-ios - iOS 通用链接
• link-android-app-links - Android 应用链接
• link-handle-incoming - 处理传入的 URL

7. 原生 UX 模式（中高）

• ux-safe-area-insets - 用于适配刘海屏的 SafeAreaView
• ux-status-bar - 状态栏样式
• ux-haptic-feedback - 操作时提供触觉反馈
• ux-gesture-handler - 用于滑动操作的手势处理器
• ux-keyboard-avoiding - KeyboardAvoidingView

8. 表单与用户输入（中）

• form-text-input-config - TextInput 键盘类型
• form-controlled-inputs - 使用 useState 控制输入
• form-submit-button-state - 提交期间禁用按钮
• form-dismiss-keyboard - 点击外部区域时收起键盘

9. 资源与主题（中）

• asset-image-optimization - 使用 expo-image 缓存
• asset-font-loading - 使用 useFonts 加载字体
• asset-vector-icons - @expo/vector-icons
• asset-splash-screen - 启动屏幕配置

10. 错误处理与测试（中）

• test-jest-setup - 使用 jest-expo 预设的 Jest
• test-component-testing - 使用 Testing Library 测试组件
• test-error-boundary - 错误边界
• test-e2e-maestro - Maestro E2E 测试

代码模板

assets/templates/ 中提供了可用于生产环境的模板：

模板	描述
layouts/tab-layout.tsx	带图标的底部标签导航器
layouts/auth-layout.tsx	带受保护路由的根布局
screens/list-screen.tsx	带 FlashList、刷新和状态的列表
screens/detail-screen.tsx	带参数处理的详情屏幕
screens/form-screen.tsx	带验证和键盘处理的表单
hooks/use-auth.tsx	使用 SecureStore 的身份验证上下文
components/error-boundary.tsx	错误边界组件

使用方法

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

• 章节定义 - 类别结构和影响级别
• 规则模板 - 添加新规则的模板

完整编译文档

如需包含所有规则的完整综合文档，请参阅 AGENTS.md。

参考文件

文件	描述
AGENTS.md	包含所有规则的完整编译指南
references/_sections.md	类别定义和排序
assets/templates/	可用于生产环境的代码模板
metadata.json	版本和参考信息