docs: 添加项目文档(copilot-instructions、编码规范、各目录 README)
- 新增 .github/copilot-instructions.md:Copilot 指令文件,涵盖构建命令、CI 流水线、项目架构、关键规范 - 新增 .github/CODING_STANDARDS.md:完整的代码编写规范文档(TypeScript、React、样式、错误处理、命名、测试、Hook、i18n、存储等 12 个章节) - 新增 11 个目录的 README.md:components、components/ui、config、entrypoints、i18n、lib、pages、providers、public、src、types、utils - 更新 AGENTS.md:补充页面组件模式说明和 components/ui 目录 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
@@ -47,6 +47,7 @@ config/features.tsx # 功能定义(路由 + 元数据的单一事实来源
|
||||
entrypoints/ # 扩展入口点 (popup/, options/, sidepanel/, background.ts, content.ts)
|
||||
pages/ # 功能页面组件 (懒加载)
|
||||
components/ # 可复用 UI 组件
|
||||
components/ui/ # shadcn/ui 基础组件 (button, dialog, select 等)
|
||||
providers/ # React Context (Router, Theme 等)
|
||||
hooks/ # 自定义 React Hooks
|
||||
utils/ # 工具函数与服务抽象
|
||||
@@ -54,11 +55,26 @@ types/ # TypeScript 类型声明
|
||||
i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json 及各功能独立 JSON)
|
||||
```
|
||||
|
||||
### 页面组件模式
|
||||
|
||||
典型功能页面遵循 **UI + Hook 分离** 模式:
|
||||
|
||||
```
|
||||
pages/FeatureName/
|
||||
├── index.tsx # 页面 UI(纯展示,使用 shadcn/ui 组件)
|
||||
├── useFeatureName.ts # 业务逻辑 Hook(状态管理 + 转换逻辑)
|
||||
└── constants.ts # 常量定义
|
||||
```
|
||||
|
||||
- 页面组件调用 `useLazyTranslation('featureName')` 获取翻译函数
|
||||
- Hook 负责所有状态管理和业务逻辑,通过返回值暴露给页面
|
||||
- 子组件可进一步拆分(如 `LiveClock.tsx`、`ResultView.tsx`)
|
||||
|
||||
## 关键架构决策
|
||||
|
||||
**路由**: 不使用 React Router。通过 `config/features.tsx` 的 `FEATURES` 数组管理,`RouterProvider` 根据 `PageType`
|
||||
渲染对应组件。支持三种渲染模式:popup(弹窗)、sidepanel(侧边栏)和 browser-tab(浏览器新标签页,通过 `open_in_tab` 打开)。
|
||||
每种模式有独立的路由和可见页面配置。
|
||||
每种模式有独立的路由和可见页面配置(`app/popupRoute`、`app/sidepanelRoute`、`app/tabRoute` 等)。
|
||||
|
||||
**存储**: 所有 Chrome Storage 键必须在 `types/storage.d.ts` 的 `StorageSchema` 中定义,键名使用 kebab-case 格式(如 `app/currentRoute`)。
|
||||
使用 `utils/chromeStorage.ts` 及其 Hook。Router 同时使用 `chrome.storage.local` 和 `localStorage` 做快照以消除首屏闪烁。
|
||||
@@ -70,6 +86,8 @@ i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json 及各功
|
||||
|
||||
**浏览器兼容**: 优先使用 `wxt/browser` 导出的 `browser` 对象,而非原生 `chrome` API。
|
||||
|
||||
**代码分割**: `wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组依赖(vendor-react、vendor-i18n、vendor-qr 等),无需手动配置。
|
||||
|
||||
## 测试环境
|
||||
|
||||
- 环境: jsdom
|
||||
@@ -99,8 +117,11 @@ i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json 及各功
|
||||
## 新功能开发清单
|
||||
|
||||
1. 在 `types/storage.d.ts` 添加 `PageType` 联合类型
|
||||
2. 在 `config/features.tsx` 的 `FEATURES` 数组添加配置
|
||||
3. 在 `pages/` 创建页面组件 (懒加载)
|
||||
2. 在 `config/features.tsx` 的 `FEATURES` 数组添加配置(指定 key、翻译键、图标、三种渲染模式的组件)
|
||||
3. 在 `pages/` 创建页面组件 (懒加载):
|
||||
- `index.tsx` — UI 组件,使用 `useLazyTranslation` 获取翻译
|
||||
- `useFeatureName.ts` — 业务逻辑 Hook
|
||||
- `constants.ts` — 常量(可选)
|
||||
4. 在 `i18n/locales/{zh,en}/features.json` 添加翻译(复杂功能可新建独立 JSON)
|
||||
5. 如需新权限,更新 `wxt.config.ts` 的 `manifest.permissions`
|
||||
6. 添加对应的单元测试
|
||||
@@ -115,15 +136,11 @@ i18n/locales/{zh,en}/ # 国际化资源 (common.json, features.json 及各功
|
||||
- 格式: Prettier (`.prettierrc`: 100 字符宽, 单引号, 尾逗号 all, LF 换行)
|
||||
- ESLint 使用 `typescript-eslint` 的 `projectService: true`(无需手动维护 project 路径)
|
||||
|
||||
## 技术栈版本
|
||||
## 关键外部库(非显而易见的)
|
||||
|
||||
- WXT: ^0.20.26
|
||||
- React: ^19.2.6
|
||||
- Tailwind CSS: ^3.4.19
|
||||
- shadcn/ui (基于 Radix UI + class-variance-authority)
|
||||
- TypeScript: ^5.9.3
|
||||
- Vitest: ^4.1.7
|
||||
- i18next: ^26.2.0
|
||||
- @dnd-kit (拖拽排序)
|
||||
- marked (Markdown 解析)
|
||||
- qrious + qr-scanner (二维码生成与解析)
|
||||
- `@webext-core/messaging` — 扩展消息通信
|
||||
- `@dnd-kit` — 拖拽排序(用于页面顺序管理)
|
||||
- `marked` — Markdown 解析
|
||||
- `qrious` + `qr-scanner` — 二维码生成与解析
|
||||
- `dayjs` — 日期处理(时间戳转换)
|
||||
- `sonner` — Toast 通知(替代传统 snackbar)
|
||||
|
||||
Reference in New Issue
Block a user