315 lines
10 KiB
Markdown
315 lines
10 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## user rools
|
||
每次开头请叫我哥哥
|
||
|
||
请严格遵守ui设计规范，使用响应式布局设计，不要硬编码
|
||
请使用项目里面封装好的ui组件，如果没有请提醒我
|
||
## Project Overview
|
||
|
||
React Native + Expo mobile application built on **Ignite CLI boilerplate** (v11.4.0). Uses TypeScript, React Navigation 7, and NativeWind (Tailwind CSS).
|
||
|
||
## Common Commands
|
||
|
||
```bash
|
||
pnpm install # Install dependencies
|
||
pnpm run start # Start Expo dev client
|
||
pnpm run android # Run on Android (expo run:android)
|
||
pnpm run ios # Run on iOS (expo run:ios)
|
||
pnpm run compile # TypeScript type check (tsc --noEmit)
|
||
pnpm run lint # ESLint with auto-fix
|
||
pnpm run lint:check # ESLint without fix
|
||
pnpm run test # Run Jest tests
|
||
pnpm run test:watch # Run Jest in watch mode
|
||
|
||
# EAS Builds (requires expo-cli)
|
||
pnpm run build:ios:sim # iOS simulator build
|
||
pnpm run build:android:sim # Android emulator build
|
||
pnpm run prebuild:clean # Regenerate native projects
|
||
```
|
||
|
||
## Architecture
|
||
|
||
### Directory Structure
|
||
|
||
- `app/` - Main application source
|
||
- `components/` - 12个基础 UI 组件（详见下方组件列表）
|
||
- `screens/` - Screen components connected to navigation
|
||
- `screens/DemoShowroomScreen/demos/` - 组件演示页面（展示组件用法，非实际组件）
|
||
- `navigators/` - React Navigation configuration (AppNavigator, DemoNavigator)
|
||
- `context/` - React Context providers (AuthContext, ThemeContext, ToastContext)
|
||
- `services/api/` - API layer using Apisauce (`authApi.ts` for auth, `index.ts` for base API)
|
||
- `theme/` - Design tokens (colors, spacing, typography) and theme system
|
||
- `i18n/` - Internationalization with i18next (8 languages: en, zh, ar, es, fr, hi, ja, ko)
|
||
- `utils/` - Utilities including MMKV storage wrapper
|
||
- `config/` - Environment-based configuration (dev/prod)
|
||
- `devtools/` - Reactotron configuration
|
||
|
||
### Key Patterns
|
||
|
||
**State Management**: React Context + MMKV for persistence. No Redux.
|
||
|
||
**Theming**: Use `useAppTheme()` hook and `ThemedStyle<T>` pattern:
|
||
```typescript
|
||
const $container: ThemedStyle<ViewStyle> = ({ colors, spacing }) => ({
|
||
backgroundColor: colors.background,
|
||
padding: spacing.lg,
|
||
})
|
||
```
|
||
|
||
**Navigation**: Two-layer structure - AppStack (auth/main screens) and DemoNavigator (bottom tabs). Type-safe routes defined in `navigationTypes.ts`. Auth screens: AuthWelcome, Login, Register, ForgotPassword. Main screens: Welcome, Profile, Settings, Security, Theme, Language, About, etc.
|
||
|
||
**API Layer**: Singleton `Api` class in `services/api/index.ts` using Apisauce with typed responses.
|
||
|
||
**Styling**: NativeWind (Tailwind CSS) configured. Use `className` prop for Tailwind styles.
|
||
|
||
**Authentication**: `AuthContext` provides full auth flow with step-based state machines for login, register, and password reset. Supports email/password and Google Sign-In. Uses JWT tokens stored in MMKV.
|
||
|
||
## UI 设计规范
|
||
|
||
### 参考文件
|
||
|
||
| 类型 | 文件路径 | 说明 |
|
||
|------|----------|------|
|
||
| **设计令牌** | `app/theme/colors.ts` | 颜色系统（浅色主题） |
|
||
| | `app/theme/colorsDark.ts` | 颜色系统（深色主题） |
|
||
| | `app/theme/spacing.ts` | 间距系统 |
|
||
| | `app/theme/typography.ts` | 字体排版 |
|
||
| | `app/theme/styles.ts` | 全局样式（$styles.container 等） |
|
||
| **UI 参考页面** | `app/screens/DemoCommunityScreen.tsx` | **最佳参考** - 标准页面结构、ListItem 用法、Section 标题 |
|
||
| | `app/screens/WelcomeScreen.tsx` | useHeader hook 用法 |
|
||
| | `app/screens/ProfileScreen.tsx` | 设置页面、用户卡片 |
|
||
| **组件演示** | `app/screens/DemoShowroomScreen/demos/` | 所有组件的用法示例（类似 Storybook） |
|
||
|
||
### 设计令牌
|
||
|
||
**颜色语义**（定义在 `app/theme/colors.ts`）:
|
||
```typescript
|
||
text: palette.neutral800 // 主要文本
|
||
textDim: palette.neutral600 // 次要文本
|
||
background: palette.neutral200 // 屏幕背景
|
||
border: palette.neutral400 // 边框
|
||
tint: palette.primary500 // 主色调（按钮、链接）
|
||
separator: palette.neutral300 // 分隔线
|
||
error: palette.angry500 // 错误
|
||
```
|
||
|
||
**间距系统**（`app/theme/spacing.ts`）:
|
||
```typescript
|
||
xxxs: 2, xxs: 4, xs: 8, sm: 12, md: 16, lg: 24, xl: 32, xxl: 48, xxxl: 64
|
||
```
|
||
|
||
**字体大小**（`app/components/Text.tsx`）:
|
||
```typescript
|
||
xxl: 36, xl: 24, lg: 20, md: 18, sm: 16(默认), xs: 14, xxs: 12
|
||
```
|
||
|
||
### Header 使用规范
|
||
|
||
**必须使用 `useHeader` hook**，不要直接在 Screen 内部放置 `<Header>` 组件。
|
||
|
||
```typescript
|
||
// ✅ 正确写法
|
||
import { useHeader } from "@/utils/useHeader"
|
||
|
||
useHeader({
|
||
title: translate("screenName:title"),
|
||
leftIcon: "back",
|
||
onLeftPress: () => navigation.goBack(),
|
||
}, [])
|
||
|
||
return (
|
||
<Screen safeAreaEdges={["bottom"]} contentContainerStyle={[$styles.container, themed($container)]}>
|
||
{/* 内容 */}
|
||
</Screen>
|
||
)
|
||
|
||
const $container: ThemedStyle<ViewStyle> = ({ spacing }) => ({
|
||
paddingTop: spacing.lg, // 覆盖 $styles.container 的 56px
|
||
})
|
||
```
|
||
|
||
**原因**: Header 组件默认添加顶部安全区域 padding，直接放在 Screen 内容中会导致 Header 上方出现额外空白。`useHeader` 通过 `navigation.setOptions()` 将 Header 设置为导航层的一部分。
|
||
|
||
### 容器间距规范
|
||
|
||
`$styles.container`（定义在 `app/theme/styles.ts`）:
|
||
```typescript
|
||
container: {
|
||
paddingTop: spacing.lg + spacing.xl, // = 56px（为无 Header 的 Tab 页面设计）
|
||
paddingHorizontal: spacing.lg, // = 24px
|
||
}
|
||
```
|
||
|
||
**使用 useHeader 的页面**需在 `$container` 中覆盖 paddingTop 为 `spacing.lg` (24px)。
|
||
|
||
**不要**在页面内容中再添加额外的 paddingTop 或 marginTop，避免重复间距。
|
||
|
||
### ListItem 使用规范
|
||
|
||
**参考**: `app/screens/DemoCommunityScreen.tsx`
|
||
|
||
**默认无分隔线**，保持简洁风格：
|
||
```typescript
|
||
<ListItem
|
||
tx="setting:option1"
|
||
leftIcon="settings"
|
||
rightIcon="caretRight"
|
||
onPress={handlePress}
|
||
/>
|
||
```
|
||
|
||
只有**连续列表项**需要视觉分隔时，才使用 `bottomSeparator`，且**最后一项不需要**:
|
||
```typescript
|
||
<ListItem text="Item 1" bottomSeparator />
|
||
<ListItem text="Item 2" bottomSeparator />
|
||
<ListItem text="Item 3" />
|
||
```
|
||
|
||
### Section 标题规范
|
||
|
||
**参考**: `app/screens/DemoCommunityScreen.tsx` 的 `$sectionTitle` 样式
|
||
|
||
使用 `preset="subheading"` 作为 section 标题:
|
||
```typescript
|
||
<Text preset="subheading" tx="section:title" style={themed($sectionTitle)} />
|
||
|
||
const $sectionTitle: ThemedStyle<TextStyle> = ({ spacing }) => ({
|
||
marginTop: spacing.xxl, // 48px
|
||
})
|
||
```
|
||
|
||
### 页面结构模板
|
||
|
||
**有 Header 的页面**（如设置、详情页）:
|
||
```typescript
|
||
import { useHeader } from "@/utils/useHeader"
|
||
|
||
export const ExampleScreen: FC<Props> = ({ navigation }) => {
|
||
const { themed } = useAppTheme()
|
||
|
||
useHeader({
|
||
title: translate("exampleScreen:title"),
|
||
leftIcon: "back",
|
||
onLeftPress: () => navigation.goBack(),
|
||
}, [])
|
||
|
||
return (
|
||
<Screen
|
||
preset="scroll"
|
||
safeAreaEdges={["bottom"]}
|
||
contentContainerStyle={[$styles.container, themed($container)]}
|
||
>
|
||
{/* 内容 */}
|
||
</Screen>
|
||
)
|
||
}
|
||
|
||
const $container: ThemedStyle<ViewStyle> = ({ spacing }) => ({
|
||
paddingTop: spacing.lg,
|
||
})
|
||
```
|
||
|
||
**无 Header 的 Tab 页面**（参考 `DemoCommunityScreen.tsx`）:
|
||
```typescript
|
||
export const ExampleTabScreen: FC<Props> = () => {
|
||
const { themed } = useAppTheme()
|
||
|
||
return (
|
||
<Screen preset="scroll" contentContainerStyle={$styles.container}>
|
||
<Text preset="heading" tx="screen:title" style={themed($title)} />
|
||
<Text tx="screen:description" style={themed($description)} />
|
||
|
||
<Text preset="subheading" tx="screen:section1" style={themed($sectionTitle)} />
|
||
<ListItem ... />
|
||
<ListItem ... />
|
||
</Screen>
|
||
)
|
||
}
|
||
|
||
const $title: ThemedStyle<TextStyle> = ({ spacing }) => ({
|
||
marginBottom: spacing.sm,
|
||
})
|
||
|
||
const $description: ThemedStyle<TextStyle> = ({ spacing }) => ({
|
||
marginBottom: spacing.lg,
|
||
})
|
||
|
||
const $sectionTitle: ThemedStyle<TextStyle> = ({ spacing }) => ({
|
||
marginTop: spacing.xxl,
|
||
})
|
||
```
|
||
|
||
### 组件列表 (`app/components/`)
|
||
|
||
| 组件 | 用途 |
|
||
|------|------|
|
||
| `Screen.tsx` | 屏幕容器（SafeArea + 键盘适配 + 滚动） |
|
||
| `Header.tsx` | 页面头部导航栏 |
|
||
| `Card.tsx` | 卡片容器 |
|
||
| `TextField.tsx` | 文本输入框 |
|
||
| `Button.tsx` | 按钮（default/filled/reversed 预设） |
|
||
| `EmptyState.tsx` | 空状态占位 |
|
||
| `ListItem.tsx` | 列表项 |
|
||
| `Icon.tsx` | 图标 |
|
||
| `Text.tsx` | 文本（heading/subheading/bold 等预设） |
|
||
| `AutoImage.tsx` | 自适应图片 |
|
||
| `Toggle/` | 开关/复选框/单选框 |
|
||
| `Avatar.tsx` | 用户头像（使用 expo-image 缓存） |
|
||
| `Modal.tsx` | 模态框（bottom/center 预设） |
|
||
| `Dialog.tsx` | 对话框（确认/提示） |
|
||
|
||
**注意**: `screens/DemoShowroomScreen/demos/` 目录下的 `Demo*.tsx` 文件是组件**演示页面**，用于展示组件的各种用法和变体，类似 Storybook，不是实际组件。
|
||
|
||
### 自适应布局
|
||
|
||
**Screen 组件预设**:
|
||
- `preset="fixed"` - 固定布局，不可滚动
|
||
- `preset="scroll"` - 始终可滚动
|
||
- `preset="auto"` - 智能判断：内容超出屏幕时才启用滚动
|
||
|
||
**安全区域**: 使用 `useSafeAreaInsetsStyle` hook 处理刘海屏
|
||
```typescript
|
||
<Screen safeAreaEdges={["top", "bottom"]}>
|
||
{/* 内容自动避开刘海和底部指示条 */}
|
||
</Screen>
|
||
```
|
||
|
||
**间距系统** (`app/theme/spacing.ts`):
|
||
```typescript
|
||
xxxs: 2, xxs: 4, xs: 8, sm: 12, md: 16, lg: 24, xl: 32, xxl: 48, xxxl: 64
|
||
```
|
||
|
||
**字体大小** (`app/components/Text.tsx`) - 固定像素值，无响应式:
|
||
```typescript
|
||
xxl: 36, xl: 24, lg: 20, md: 18, sm: 16(默认), xs: 14, xxs: 12
|
||
```
|
||
|
||
### Path Aliases
|
||
|
||
- `@/*` → `app/*`
|
||
- `@assets/*` → `assets/*`
|
||
|
||
## Import Restrictions (ESLint enforced)
|
||
|
||
- Use `Text`, `Button`, `TextInput` from `@/components`, not from `react-native`
|
||
- Use `SafeAreaView` from `react-native-safe-area-context`, not from `react-native`
|
||
- Import named exports from `react` (not `import React from 'react'`)
|
||
|
||
## Testing
|
||
|
||
Jest with Testing Library for React Native. Test files use `.test.ts(x)` suffix. Setup in `test/setup.ts`.
|
||
|
||
Run single test:
|
||
```bash
|
||
pnpm run test -- --testPathPattern="storage"
|
||
```
|
||
|
||
## Web Support
|
||
|
||
This app runs on web via Expo. Use `pnpm run start` and press `w` to open web. Note: React Navigation's `headerRight` may not work reliably on web - consider placing header elements directly inside Screen components if targeting web.
|
||
|
||
## Running on Physical Devices
|