diff --git a/.github/CODING_STANDARDS.md b/.github/CODING_STANDARDS.md index 46c6bee..6cacda1 100644 --- a/.github/CODING_STANDARDS.md +++ b/.github/CODING_STANDARDS.md @@ -762,22 +762,335 @@ const [themeMode, setThemeMode, isInitialized] = useStorageState( --- -## 11. 文件组织 +## 11. 页面开发规范 -### 11.1 页面组件结构 +### 11.1 目录结构(按复杂度分级) + +#### 简单页面(单一功能,无子模式) + +适用于 Timestamp、Jwt、TextStatistics、RightClickRestorer 等: ``` src/pages/FeatureName/ -├── index.tsx # 页面 UI(纯展示,使用 shadcn/ui 组件) -├── useFeatureName.ts # 业务逻辑 Hook(状态管理 + 转换逻辑) -├── constants.ts # 常量定义(可选) -├── LiveClock.tsx # 子组件(可选) -├── ResultView.tsx # 子组件(可选) -└── __tests__/ # 测试文件 - └── index.test.tsx +├── index.tsx # 页面入口组件(default export) +├── useFeatureName.ts # 业务逻辑 Hook(命名导出) +├── constants.ts # 常量定义(可选,命名导出) +├── SubComponent.tsx # 子组件(可选,default export) +└── __tests__/ + └── index.test.tsx # 页面集成测试 ``` -### 11.2 目录职责 +#### 中等页面(含多个子模式/标签页切换) + +适用于 Base64Converter、StorageCleaner 等: + +``` +src/pages/FeatureName/ +├── index.tsx # 页面入口(模式路由 + 顶层布局) +├── useFeatureName.ts # 业务逻辑 Hook(命名导出) +├── SubModeA.tsx # 子模式组件 +├── SubModeB.tsx # 子模式组件 +├── SubComponent.tsx # 可复用子组件 +└── __tests__/ + ├── index.test.tsx + └── SubModeA.test.tsx +``` + +#### 复杂页面(Context + 多组件协作) + +适用于 QrCode、JsonTools 等: + +``` +src/pages/FeatureName/ +├── index.tsx # 页面入口(Provider + 布局) +├── types.ts # 页面专属类型定义 +├── constants.ts # 常量(可选) +├── contexts/ # React Context 定义 +│ └── FeatureContext.ts +├── hooks/ # 页面专属 Hooks +│ └── useFeature.ts +├── components/ # 页面专属子组件 +│ ├── PanelA.tsx +│ └── PanelB.tsx +└── __tests__/ + ├── index.test.tsx + └── useFeature.test.ts +``` + +#### 特殊情况(单个文件即可) + +功能极简的页面(如 Dashboard),仅需 `index.tsx` 一个文件。当 `index.tsx` 超过 **150 行**时,应拆分为 UI + Hook 模式。 + +--- + +### 11.2 页面入口组件(`index.tsx`)规范 + +#### 组件命名 + +- 页面入口组件**统一使用 `Index` 作为函数名**,通过 `export default` 导出 +- 使用 `export default function Index()` 而非匿名默认导出 +- **禁止**混用 `XxxPage` 命名(当前 `RightClickRestorerPage`、`DashboardPage` 不合规范,应统一为 `Index`) + +```typescript +// ✅ 正确 +export default function Index() { ... } + +// ❌ 错误 — 命名不一致 +export default function RightClickRestorerPage() { ... } +export default function DashboardPage() { ... } +``` + +#### 组件职责 + +`index.tsx` 只负责三件事: + +1. **获取翻译函数**(`useI18n`) +2. **调用业务 Hook** 获取状态和操作方法 +3. **渲染 UI 布局**(纯展示,无业务逻辑) + +```typescript +// ✅ 标准页面入口模板 +import { useI18n } from '@/utils/chromeI18n'; +import { useFeatureName } from './useFeatureName'; + +export default function Index() { + const { t } = useI18n('featureName'); + const { state, actions } = useFeatureName(); + + return ( +