Compare commits
3 Commits
edd4cf266c
...
0545910b16
| Author | SHA1 | Date | |
|---|---|---|---|
 Cursor Agent
|
0545910b16 | ||
|
cursor[bot]
|
1948ba67a7 | ||
 rsgltzyd
|
1041b3ece1 |
+42
-38
@@ -285,8 +285,7 @@ import { useThemeMode } from '@/providers/ThemeModeProvider';
|
||||
import { FeatureConfig, FEATURES } from '@/config/features';
|
||||
import { storageUtil } from '@/utils/chromeStorage';
|
||||
// 5. i18n
|
||||
import { useTranslation } from 'react-i18next';
|
||||
import { normalizeLanguage, SUPPORTED_LANGUAGES } from '@/i18n';
|
||||
import { useI18n } from '@/utils/chromeI18n';
|
||||
// 6. 本地组件
|
||||
import TextMode from './TextMode';
|
||||
import { ZONES } from './constants';
|
||||
@@ -295,7 +294,7 @@ import SwitchButtonGroup from '@/components/SwitchButtonGroup';
|
||||
import { Button } from '@/components/ui/button';
|
||||
// 8. 工具函数 / Hook
|
||||
import { cn } from '@/lib/utils';
|
||||
import { useLazyTranslation } from '@/utils/useLazyTranslation';
|
||||
import { useStorageState } from '@/utils/useStorageState';
|
||||
// 9. 类型
|
||||
import type { PageType, StorageSchema } from '@/types/storage';
|
||||
```
|
||||
@@ -401,22 +400,22 @@ className={cn(
|
||||
|
||||
## 5. 错误处理
|
||||
|
||||
### 5.1 工具函数：结果对象模式
|
||||
### 5.1 工具函数：可恢复错误返回可判断结果
|
||||
|
||||
工具函数**不抛异常**，返回包含 `hasError` 和 `error` 字段的结果对象：
|
||||
可恢复的解析/校验错误应返回可判断的结果，避免工具层直接弹 Toast。确需保留底层异常的函数
|
||||
（如 `formatJson` / `minifyJson`）必须在页面 Hook 或 UI 层捕获并转换为用户提示：
|
||||
|
||||
```typescript
|
||||
// ✅ 结果对象模式
|
||||
export function markdownToHtml(markdown: string): MarkdownToHtmlResult {
|
||||
// ✅ 可恢复校验返回错误消息，调用方据此展示 UI
|
||||
export function validateJson(text: string): string | null {
|
||||
if (!text.trim()) {
|
||||
return null;
|
||||
}
|
||||
try {
|
||||
...
|
||||
return { html, originalLength, htmlLength, hasError: false };
|
||||
} catch (error) {
|
||||
return {
|
||||
html: '', ...
|
||||
hasError: true,
|
||||
error: error instanceof Error ? error.message : 'Markdown 解析失败',
|
||||
};
|
||||
JSON.parse(text.trim());
|
||||
return null;
|
||||
} catch (e) {
|
||||
return e instanceof SyntaxError ? e.message : 'Invalid JSON';
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -658,7 +657,7 @@ export function useTimestampConverter(): UseTimestampConverterReturn { ... }
|
||||
|
||||
```
|
||||
src/utils/useStorageState.ts — Chrome Storage 状态持久化
|
||||
src/utils/useLazyTranslation.ts — i18n 懒加载
|
||||
src/utils/chromeI18n.ts — chrome.i18n wrapper 与 useI18n
|
||||
src/utils/useContextMenuData.ts — 右键菜单数据
|
||||
src/utils/useDebounce.ts — 防抖
|
||||
src/pages/Timestamp/useTimestampConverter.ts — 页面级 Hook
|
||||
@@ -671,43 +670,48 @@ src/pages/StorageCleaner/useStorageCleaner.ts — 页面级 Hook
|
||||
|
||||
### 9.1 翻译键格式
|
||||
|
||||
- 命名空间：`common`（默认）、`features`
|
||||
- 翻译键格式：`namespace:key`（如 `features:timestamp.title`）
|
||||
- 语言：`zh`（默认）、`en`
|
||||
- 使用 Chrome 扩展标准的 `chrome.i18n`，通过 `src/utils/chromeI18n.ts` 暴露 `useI18n`
|
||||
- 翻译 key 存放在 `public/_locales/zh_CN/messages.json`
|
||||
- 直接 key：`t('dashboard_title')` → 查找 `dashboard_title`
|
||||
- 命名空间兼容写法：`t('common:buttons.search')` → 查找 `common_buttons_search`
|
||||
- 命名空间参数：`useI18n(['common', 'features'])` 会尝试 `common_key`、`features_key`
|
||||
|
||||
### 9.2 翻译文件结构
|
||||
|
||||
```
|
||||
i18n/locales/{zh,en}/common.json — 全局通用翻译
|
||||
i18n/locales/{zh,en}/features.json — 功能模块标题和描述
|
||||
i18n/locales/{zh,en}/{功能名}.json — 各功能独立翻译
|
||||
public/_locales/zh_CN/messages.json — Chrome 扩展默认语言包
|
||||
wxt.config.ts — manifest.default_locale = 'zh_CN'
|
||||
```
|
||||
|
||||
### 9.3 使用方式
|
||||
|
||||
```typescript
|
||||
// ✅ 页面组件 — 使用 useLazyTranslation
|
||||
import { useLazyTranslation } from '@/utils/useLazyTranslation';
|
||||
// ✅ 页面组件 / 子组件 — 使用 useI18n
|
||||
import { useI18n } from '@/utils/chromeI18n';
|
||||
|
||||
export default function Index() {
|
||||
const { t } = useLazyTranslation('timestamp');
|
||||
return <h1>{t('timestamp:title')}</h1>;
|
||||
const { t } = useI18n('timestamp');
|
||||
return <h1>{t('timestamp_title')}</h1>;
|
||||
}
|
||||
|
||||
// ✅ 全局组件 — 使用 useTranslation
|
||||
import { useTranslation } from 'react-i18next';
|
||||
|
||||
export function TopBar() {
|
||||
const { t } = useTranslation(['common', 'features']);
|
||||
return <span>{t('common:settings')}</span>;
|
||||
// ✅ 带占位符
|
||||
export function NotFoundMessage() {
|
||||
const { t } = useI18n('router');
|
||||
return <p>{t('router_notFoundDescription', { entryPointType: 'popup' })}</p>;
|
||||
}
|
||||
```
|
||||
|
||||
### 9.4 添加新翻译
|
||||
|
||||
1. 在 `i18n/locales/{zh,en}/features.json` 添加功能标题和描述
|
||||
2. 创建 `i18n/locales/{zh,en}/{功能名}.json` 添加功能专属翻译
|
||||
3. 在 `utils/useLazyTranslation.ts` 的 `localeModules` 中注册新命名空间
|
||||
1. 在 `public/_locales/zh_CN/messages.json` 添加 Chrome 扩展格式的消息：
|
||||
```json
|
||||
{
|
||||
"feature_title": { "message": "功能标题" },
|
||||
"feature_description": { "message": "功能描述" }
|
||||
}
|
||||
```
|
||||
2. key 使用下划线分隔，避免点号；`useI18n` 会把 `namespace:key.path` 兼容转换为下划线
|
||||
3. `chrome.i18n` 不支持运行时动态切换语言，浏览器语言变化后需要刷新扩展页面
|
||||
|
||||
---
|
||||
|
||||
@@ -1083,7 +1087,7 @@ export default function Index() {
|
||||
4. ✅ 业务逻辑提取到 `useXxx.ts` Hook（index.tsx 不超过 150 行）
|
||||
5. ✅ 需要持久化的 UI 状态使用 `useStorageState`
|
||||
6. ✅ 常量 ≥3 个时提取到 `constants.ts`
|
||||
7. ✅ 在 `i18n/locales/{zh,en}/` 添加翻译
|
||||
7. ✅ 在 `public/_locales/zh_CN/messages.json` 添加翻译
|
||||
8. ✅ 创建 `__tests__/index.test.tsx` 测试文件
|
||||
9. ✅ 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
|
||||
10. ✅ 运行 `npm run lint && npm run typecheck && npm run test` 全部通过
|
||||
@@ -1103,8 +1107,8 @@ export default function Index() {
|
||||
| `src/hooks/` | 自定义 React Hooks |
|
||||
| `src/utils/` | 工具函数与服务抽象 |
|
||||
| `src/types/` | TypeScript 类型声明 |
|
||||
| `src/lib/` | 通用工具函数（cn、utils） |
|
||||
| `public/` | 静态资源 |
|
||||
| `src/lib/` | 通用工具函数与生成器库（cn、utils、generators） |
|
||||
| `public/` | 静态资源与 Chrome `_locales` 语言包 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,141 +0,0 @@
|
||||
# Copilot 指令
|
||||
|
||||
基于 WXT 框架的浏览器扩展项目（React 19 + TypeScript），为开发者和测试人员提供效率工具：时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、Markdown 等。
|
||||
|
||||
## 核心命令
|
||||
|
||||
```bash
|
||||
npm run dev # Chrome 开发模式（支持 HMR）
|
||||
npm run dev:firefox # Firefox 开发模式
|
||||
npm run build # Chrome 生产构建
|
||||
npm run build:firefox # Firefox 生产构建
|
||||
npm run zip # 打包 Chrome 扩展（.output/*.zip）
|
||||
npm run zip:firefox # 打包 Firefox 扩展
|
||||
npm run lint # ESLint 检查（--max-warnings=0）
|
||||
npm run typecheck # TypeScript 类型检查（tsc --noEmit）
|
||||
npm run test # 运行全部单元测试（vitest run）
|
||||
npm run test:watch # Vitest 监视模式
|
||||
npm run test:coverage # 带覆盖率的测试
|
||||
```
|
||||
|
||||
运行单个测试文件：`npx vitest run path/to/file.test.ts`
|
||||
|
||||
修改 `package.json` 后需运行 `npm install`（会自动触发 `postinstall` → `wxt prepare` 重新生成 `.wxt/` 类型声明）。
|
||||
|
||||
## CI 流水线（GitHub Actions）
|
||||
|
||||
严格顺序门控，任一步骤失败则终止：
|
||||
|
||||
1. **setup** — 安装依赖，缓存 `node_modules`
|
||||
2. **lint**、**typecheck**、**test** — 三者并行运行，全部通过才继续
|
||||
3. **build** — Chrome + Firefox 矩阵构建（仅当步骤 2 全部通过时执行）
|
||||
|
||||
Pre-commit 钩子（`.husky/pre-commit` → `lint-staged`）：
|
||||
|
||||
1. 代码文件（`*.{ts,tsx,js,jsx,mjs}`）：运行 `eslint --fix --max-warnings=0`
|
||||
2. 同一代码文件：运行 `prettier --write`
|
||||
3. 其他文件（`*.{json,css,scss,md}`）：运行 `prettier --write`
|
||||
|
||||
## 项目架构
|
||||
|
||||
### 路由（不使用 React Router）
|
||||
|
||||
路由完全通过 `config/features.tsx` 中的 `FEATURES` 数组管理。每个功能定义一个 `key`（类型为 `types/storage.d.ts` 中的 `PageType`）和三个懒加载组件，分别对应 `popup`、`sidepanel`、`tab` 三种渲染模式。`providers/RouterProvider.tsx` 中的 `RouterProvider` 根据存储状态渲染当前页面。
|
||||
|
||||
存在三套独立的路由作用域：`app/popupRoute`、`app/sidepanelRoute`、`app/tabRoute`，各自维护独立的可见页面列表和页面排序。
|
||||
|
||||
### 存储
|
||||
|
||||
所有 Chrome Storage 键必须在 `types/storage.d.ts` 的 `StorageSchema` 中声明，键名使用 kebab-case 格式（如 `app/currentRoute`）。使用 `utils/chromeStorage.ts` 中的类型安全封装（`storageUtil.get/set/remove`）。
|
||||
|
||||
Router 同时使用 `chrome.storage.local` 持久化和 `localStorage` 快照来消除首屏闪烁。
|
||||
|
||||
### 扩展通信
|
||||
|
||||
使用 `@webext-core/messaging`。通信协议在 `utils/messages.ts` 中通过 `ProtocolMap` 定义。使用该模块导出的 `sendMessage` / `onMessage`，不要直接使用原生 `chrome.runtime.sendMessage`。
|
||||
|
||||
### 页面组件模式
|
||||
|
||||
功能页面遵循 **UI + Hook 分离** 模式，详见 [CODING_STANDARDS.md § 11](./CODING_STANDARDS.md#11-页面开发规范)：
|
||||
|
||||
```
|
||||
pages/FeatureName/
|
||||
├── index.tsx # UI 组件（纯展示，使用 shadcn/ui 组件）
|
||||
├── useFeatureName.ts # 业务逻辑 Hook（状态管理 + 转换逻辑）
|
||||
└── constants.ts # 常量定义（可选）
|
||||
```
|
||||
|
||||
- 页面组件调用 `useI18n('featureName')` 获取翻译函数
|
||||
- Hook 负责所有状态管理，通过返回值暴露给页面
|
||||
- 子组件可进一步拆分（如 `LiveClock.tsx`、`ResultView.tsx`）
|
||||
|
||||
### 新功能开发清单
|
||||
|
||||
1. 在 `types/storage.d.ts` 的 `PageType` 联合类型中添加新成员
|
||||
2. 在 `config/features.tsx` 的 `FEATURES` 数组中添加配置（key、翻译键、图标、三种渲染模式组件）
|
||||
3. 在 `pages/` 目录创建页面组件（懒加载）：
|
||||
- `index.tsx` — 使用 `useLazyTranslation` 的 UI 组件
|
||||
- `useFeatureName.ts` — 业务逻辑 Hook
|
||||
- `constants.ts` — 常量（可选）
|
||||
4. 在 `i18n/locales/{zh,en}/features.json` 添加翻译（复杂功能可新建独立 JSON 文件）
|
||||
5. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
|
||||
6. 添加对应的单元测试
|
||||
|
||||
## 关键规范
|
||||
|
||||
> 完整的代码编写规范详见 [CODING_STANDARDS.md](./CODING_STANDARDS.md)。
|
||||
|
||||
### 浏览器 API
|
||||
|
||||
始终使用 `wxt/browser` 导出的 `browser` 对象，而非原生 `chrome` API，以确保跨浏览器兼容性。
|
||||
|
||||
### 路径别名
|
||||
|
||||
`@/` 映射到项目根目录（已在 tsconfig 和 vitest.config 中配置）。跨目录导入使用 `@/` 绝对别名，同目录导入使用 `./` 相对路径。
|
||||
|
||||
### UI 组件
|
||||
|
||||
- 使用 `components/ui/` 下的 shadcn/ui 组件（button、dialog、select、input 等）
|
||||
- 图标：`lucide-react`
|
||||
- 样式：Tailwind CSS + `@/lib/utils` 中的 `cn()` 工具函数（clsx + tailwind-merge）
|
||||
- 主题：使用 shadcn/ui 语义化 token（`bg-background`、`text-foreground`、`border-border` 等），禁止硬编码颜色
|
||||
|
||||
### 代码分割
|
||||
|
||||
`wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组 vendor 依赖（vendor-react、vendor-i18n、vendor-qr、vendor-dnd），无需手动配置。
|
||||
|
||||
### 代码风格
|
||||
|
||||
- 禁止使用 `any`（测试文件除外）
|
||||
- 未使用的变量/参数：使用 `_` 前缀（如 `_unused`）
|
||||
- Prettier：100 字符宽、单引号、尾逗号 all、LF 换行
|
||||
- ESLint 使用 `typescript-eslint` 的 `projectService: true`
|
||||
- 导出模式：页面组件 default export，工具函数/Hook 命名导出，UI 组件 forwardRef + 命名导出
|
||||
|
||||
### 测试
|
||||
|
||||
- 环境：jsdom
|
||||
- 全局变量：`vitest/globals`（describe、it、expect 等无需导入）
|
||||
- Setup 文件：`vitest.setup.ts` 自动 mock 以下内容：
|
||||
- `chrome.*` / `browser.*` API（storage、tabs、runtime、cookies 等）
|
||||
- `react-i18next`（返回 key 作为翻译）
|
||||
- `@/utils/useLazyTranslation`（返回 `ns:key` 格式）
|
||||
- `window.matchMedia`
|
||||
- 测试文件命名：`__tests__/*.test.{ts,tsx}` 或 `*.test.{ts,tsx}`
|
||||
- 使用 `vi.mock()` 进行模块级 mock；避免重复 mock `vitest.setup.ts` 中已有的内容
|
||||
- 测试工具：`@testing-library/react` + `@testing-library/user-event`
|
||||
|
||||
### 国际化（i18n）
|
||||
|
||||
- 命名空间：`common`（默认）、`features`
|
||||
- 翻译键格式：`namespace:key`（如 `features:timestamp.title`）
|
||||
- 语言：`zh`（默认）、`en`
|
||||
- 翻译文件：`i18n/locales/{zh,en}/{common,features}.json` + 各功能独立 JSON 文件
|
||||
- 使用 `useLazyTranslation` Hook 加载功能专属翻译
|
||||
- 回退策略：缺失的翻译键回退到 `zh`，若仍缺失则返回占位格式 `namespace:key`
|
||||
|
||||
### WXT 生成文件
|
||||
|
||||
- `.wxt/` 目录由 `postinstall`（`wxt prepare`）自动生成，包含 TypeScript 类型声明和扩展 tsconfig
|
||||
- 生产构建输出到 `.output/` 目录
|
||||
- `tsconfig.json` 继承自 `./.wxt/tsconfig.json`
|
||||
@@ -1,6 +1,6 @@
|
||||
# AGENTS.md
|
||||
|
||||
WXT 浏览器扩展项目 (React 19 + TypeScript)。提供时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、Markdown、测试数据生成器等测试效率工具。
|
||||
WXT 浏览器扩展项目 (React 19 + TypeScript)。提供时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、测试数据生成器等测试效率工具。
|
||||
|
||||
## 核心命令
|
||||
|
||||
@@ -16,30 +16,64 @@ npm run typecheck # tsc --noEmit
|
||||
npm run test # vitest run (单次执行)
|
||||
npm run test:watch # vitest 监视模式
|
||||
npm run test:coverage # 带覆盖率的测试
|
||||
npx vitest run path/to/file.test.ts # 运行单个测试文件
|
||||
npx wxt prepare # 重新生成 .wxt/ 类型声明（npm install 时 postinstall 会自动执行）
|
||||
```
|
||||
|
||||
修改 `package.json` 或首次克隆仓库后需执行 `npm install`，会自动触发 `postinstall` → `wxt prepare`。
|
||||
|
||||
## 验证流程
|
||||
|
||||
详见 [CI 配置](./.github/CI.md)
|
||||
详见 [CI 配置](./.github/CI.md)。本地与 CI 的检查层次如下。
|
||||
|
||||
### Pre-commit（`.husky/pre-commit`）
|
||||
|
||||
1. 后台运行 `tsc --noEmit`（不阻塞提交，结果输出到 stderr）
|
||||
2. 前台运行 `lint-staged`：
|
||||
- 代码文件 (`*.{ts,tsx,js,jsx,mjs}`)：`eslint --fix --max-warnings=0`，再 `prettier --write`
|
||||
- 其他文件 (`*.{json,css,scss,md}`)：`prettier --write`
|
||||
|
||||
### Pre-push（`.husky/pre-push`）
|
||||
|
||||
1. 全项目 `tsc --noEmit`（阻塞推送）
|
||||
2. 对本次推送相对 upstream（或 `origin/main`）变更的 `*.{ts,tsx,js,jsx,mjs}` 文件运行 `eslint --max-warnings=0`
|
||||
|
||||
### CI（GitHub Actions）
|
||||
|
||||
1. `setup` — 安装依赖
|
||||
2. 并行 `lint`、`typecheck`（含 `wxt prepare`）、`test`
|
||||
3. `build` — Chrome + Firefox 矩阵构建（仅当步骤 2 全部通过）
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
src/ # 源代码根目录
|
||||
config/features.tsx # 功能定义（路由 + 元数据的单一事实来源）
|
||||
entrypoints/ # 扩展入口点 (popup/, sidepanel/, background.ts, content.ts)
|
||||
pages/ # 功能页面组件 (懒加载)
|
||||
components/ # 可复用 UI 组件
|
||||
components/ui/ # shadcn/ui 基础组件 (button, dialog, select 等)
|
||||
providers/ # React Context (Router, Theme 等)
|
||||
hooks/ # 自定义 React Hooks
|
||||
utils/ # 工具函数与服务抽象
|
||||
types/ # TypeScript 类型声明
|
||||
lib/ # 通用工具函数（cn、utils）
|
||||
workers/ # Web Worker（数据生成等耗时任务）
|
||||
public/ # 静态资源（图标、_locales 等）
|
||||
src/ # 源代码根目录
|
||||
config/features.tsx # 功能定义（路由 + 元数据的单一事实来源）
|
||||
entrypoints/ # 扩展入口点 (popup/, sidepanel/, background.ts, content.ts)
|
||||
layout/ # 应用壳层布局（TopBar 导航、搜索、主题切换）
|
||||
pages/ # 功能页面组件 (懒加载)
|
||||
components/ # 可复用 UI 组件
|
||||
components/ui/ # shadcn/ui 基础组件 (button, dialog, select 等)
|
||||
providers/ # React Context (Router, Theme 等)
|
||||
hooks/ # 自定义 React Hooks
|
||||
utils/ # 工具函数与服务抽象
|
||||
types/ # TypeScript 类型声明
|
||||
lib/ # 通用工具函数（cn、utils）及数据生成器定义
|
||||
workers/ # Web Worker（数据生成等耗时任务）
|
||||
spec/ # 功能规格、修复方案与验收标准（见 spec/README.md）
|
||||
public/ # 静态资源（图标、_locales 等）
|
||||
.wxt/ # wxt prepare 自动生成，含类型声明与扩展 tsconfig（勿手动编辑）
|
||||
.output/ # 生产构建输出目录
|
||||
```
|
||||
|
||||
### layout/
|
||||
|
||||
应用壳层，与 popup / sidepanel / tab 入口绑定。当前含 `TopBar/`（搜索、主题切换、返回导航、「在标签页打开」），遵循与 `pages/` 相同的 UI + Hook 模式。详见 [layout/README.md](./src/layout/README.md)。
|
||||
|
||||
### spec/
|
||||
|
||||
功能规格与验收标准文档，重大改动前优先查阅。索引见 [spec/README.md](./spec/README.md)。
|
||||
|
||||
### 页面组件模式
|
||||
|
||||
典型功能页面遵循 **UI + Hook 分离** 模式。详见 [CODING_STANDARDS.md § 11](./.github/CODING_STANDARDS.md#11-页面开发规范)。
|
||||
@@ -59,10 +93,42 @@ src/pages/FeatureName/
|
||||
- 当 `index.tsx` 超过 150 行时，必须拆分为 UI + Hook 模式
|
||||
- 复杂页面可增加 `contexts/`、`hooks/`、`components/` 子目录
|
||||
|
||||
### 测试数据生成器模块
|
||||
|
||||
```
|
||||
src/pages/TestDataGenerator/
|
||||
├── index.tsx # 主页面（字段配置 + 标签页切换）
|
||||
├── hooks/useGenerator.ts # Web Worker 管理 Hook（创建、复用、通信、销毁）
|
||||
└── components/
|
||||
├── FieldList.tsx # 字段列表（虚拟滚动 + @dnd-kit 拖拽排序 + 规则保存）
|
||||
├── FieldItem.tsx # 字段卡片展示
|
||||
├── FieldEditor.tsx # 字段编辑器（名称校验、生成器选择、参数配置）
|
||||
├── GeneratorSelector.tsx # 生成器选择器（分类 + 搜索）
|
||||
├── GeneratorConfig.tsx # 生成器参数表单（动态渲染 string/number/boolean/select/array）
|
||||
├── GenerateOptions.tsx # 生成选项（数量、格式）
|
||||
├── GenerateButton.tsx # 生成按钮 + 进度条
|
||||
├── DataPreview.tsx # 示例数据预览（JSON 语法高亮）
|
||||
├── ResultPanel.tsx # 生成结果状态面板
|
||||
├── ExportPanel.tsx # 导出面板（复制/下载 JSON/CSV）
|
||||
└── RuleManager.tsx # 规则管理（CRUD、搜索、导入/导出）
|
||||
|
||||
src/utils/
|
||||
├── ruleStorage.ts # 规则持久化存储（localStorage）
|
||||
└── dataExporter.ts # 数据导出工具（JSON/CSV 转换、下载、剪贴板）
|
||||
|
||||
src/lib/generators/ # 内置生成器定义（个人信息、企业、技术、基础类型）
|
||||
|
||||
src/workers/
|
||||
└── generator.worker.ts # 数据生成 Web Worker
|
||||
|
||||
src/types/
|
||||
└── testDataGenerator.ts # 类型定义（FieldConfig, DataRule, GeneratorDefinition 等）
|
||||
```
|
||||
|
||||
## 关键架构决策
|
||||
|
||||
**路由**: 不使用 React Router。通过 `src/config/features.tsx` 的 `FEATURES` 数组管理，`RouterProvider` 根据 `PageType`
|
||||
渲染对应组件。支持三种渲染模式：popup（弹窗）、sidepanel（侧边栏）和 browser-tab（浏览器新标签页，通过 `open_in_tab` 打开）。
|
||||
渲染对应组件。支持三种渲染模式：popup（弹窗）、sidepanel（侧边栏）和 tab（浏览器新标签页，TopBar「在标签页打开」调用 `openExtensionPage('popup.html', { mode: 'tab' })`，由 `getEntryPointType()` 根据 URL 参数 `mode=tab` 识别）。
|
||||
每种模式有独立的路由和可见页面配置（`app/popupRoute`、`app/sidepanelRoute`、`app/tabRoute` 等）。
|
||||
|
||||
**存储**: 所有 Chrome Storage 键必须在 `src/types/storage.d.ts` 的 `StorageSchema` 中定义，键名使用 kebab-case 格式（如 `app/currentRoute`）。
|
||||
@@ -70,33 +136,49 @@ src/pages/FeatureName/
|
||||
|
||||
**通信**: 使用 `@webext-core/messaging`，协议定义在 `src/utils/messages.ts`。
|
||||
|
||||
**路径别名**: `@/` 映射到项目根目录 (已在 tsconfig 和 vitest.config 中配置)。
|
||||
**路径别名**: `@/` 映射到 `src/` 目录（已在 `.wxt/tsconfig.json` 和 `vitest.config.ts` 中配置）。项目根目录使用 `@@/`。
|
||||
|
||||
**浏览器兼容**: 优先使用 `wxt/browser` 导出的 `browser` 对象，而非原生 `chrome` API。
|
||||
|
||||
**代码分割**: `wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组依赖（vendor-react、vendor-qr、vendor-dnd 等），无需手动配置。
|
||||
|
||||
## 测试环境
|
||||
|
||||
- 环境: jsdom
|
||||
- 全局变量: `vitest/globals` (describe, it, expect 等无需导入)
|
||||
- Setup 文件: `vitest.setup.ts` 自动 mock:
|
||||
- `chrome.*` / `browser.*` API (storage, tabs, runtime, cookies 等)
|
||||
- `@/utils/chromeI18n` (从 `public/_locales/zh_CN/messages.json` 加载真实翻译)
|
||||
- `window.matchMedia`
|
||||
- 测试文件命名: `__tests__/*.test.{ts,tsx}` 或 `*.test.{ts,tsx}`
|
||||
- Mock 模式: 使用 `vi.mock()` 进行模块级 mock，避免在测试文件中重复 mock 代码
|
||||
- 测试工具: `@testing-library/react` + `@testing-library/user-event` 进行组件测试
|
||||
|
||||
## i18n (chrome.i18n)
|
||||
|
||||
项目使用 Chrome 扩展标准的 `chrome.i18n` API 进行本地化，通过 `src/utils/chromeI18n.ts` 提供类型安全的 React Hook 包装。
|
||||
|
||||
- **翻译文件**: `public/_locales/zh_CN/messages.json`（Chrome 扩展标准格式）
|
||||
- **默认语言**: `zh_CN`（在 `wxt.config.ts` 的 `manifest.default_locale` 中配置）
|
||||
- **使用方式**: `import { useI18n } from '@/utils/chromeI18n'`
|
||||
- **翻译键格式**:
|
||||
- 直接 key: `t('dashboard_title')` → 查找 `dashboard_title`
|
||||
- 命名空间格式（兼容旧用法）: `t('common:buttons.search')` → 查找 `common_buttons_search`
|
||||
- 带命名空间参数: `useI18n(['common', 'features'])`，会自动尝试 `common_key`、`features_key`
|
||||
- **占位符支持**: `t('router_notFoundDescription', { entryPointType: 'popup' })`
|
||||
- **Hook 返回值**: `{ t, i18n: { language, changeLanguage }, isLoaded }`
|
||||
- **回退策略**: 当翻译 key 未命中时，返回 key 本身（开发模式下在控制台记录 warning）
|
||||
- **限制**: `chrome.i18n` 无法动态切换语言，语言跟随浏览器设置，切换后需刷新页面
|
||||
|
||||
## 新功能开发清单
|
||||
|
||||
1. 在 `src/types/storage.d.ts` 添加 `PageType` 联合类型
|
||||
2. 在 `src/config/features.tsx` 的 `FEATURES` 数组添加配置（指定 key、翻译键、图标、三种渲染模式的组件）
|
||||
3. 在 `src/pages/` 创建页面组件 (懒加载)：
|
||||
- `index.tsx` — UI 组件
|
||||
- `use{FeatureName}.ts` — 业务逻辑 Hook
|
||||
- `index.tsx` — UI 组件，使用 `useI18n` 获取翻译
|
||||
- `useFeatureName.ts` — 业务逻辑 Hook
|
||||
- `constants.ts` — 常量（可选）
|
||||
4. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`；如有不使用的权限，需移除
|
||||
5. 添加对应的单元测试
|
||||
4. 在 `public/_locales/zh_CN/messages.json` 添加翻译
|
||||
5. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
|
||||
6. 添加对应的单元测试
|
||||
|
||||
## 代码规范
|
||||
|
||||
@@ -105,10 +187,9 @@ src/pages/FeatureName/
|
||||
- 样式: 使用 Tailwind CSS + shadcn/ui (通过 `className` 和 `cn()` 工具)
|
||||
- UI 组件: 优先使用 `src/components/ui/` 下的 shadcn/ui 组件 (button, dialog, select 等)
|
||||
- 图标: 使用 `lucide-react` 图标库
|
||||
- 格式: Prettier (`.prettierrc`: 100 字符宽, 单引号, 尾逗号 all, LF 换行)
|
||||
- ESLint 使用 `typescript-eslint` 的 `projectService: true`（无需手动维护 project 路径）
|
||||
- **Git Commit**: 必须使用中文描述，遵循 Conventional Commits 规范（如 `fix(组件名): 描述`、`feat(功能名): 描述`）
|
||||
- **测试维护**: 新增/编辑已有功能/组件时，需要针对相关的测试进行更新
|
||||
- 格式: Prettier [配置](./.prettierrc)
|
||||
- ESLint 使用 `typescript-eslint` 的 `projectService: true`
|
||||
- Git Commit: 使用中文描述，遵循 [Conventional Commits 规范](https://www.conventionalcommits.org/zh-hans/v1.0.0/)
|
||||
|
||||
## 关键外部库（非显而易见的）
|
||||
|
||||
@@ -116,4 +197,4 @@ src/pages/FeatureName/
|
||||
- `@dnd-kit` — 拖拽排序（用于页面顺序管理和字段列表排序）
|
||||
- `qrious` + `qr-scanner` — 二维码生成与解析
|
||||
- `dayjs` — 日期处理（时间戳转换）
|
||||
- `sonner` — Toast 通知（替代传统 snackbar）
|
||||
- `sonner` — Toast 通知
|
||||
|
||||
@@ -81,7 +81,7 @@
|
||||
- **UI 组件**: shadcn/ui (基于 Radix UI 的无头组件库)
|
||||
- **样式**: Tailwind CSS + class-variance-authority + cn() 工具函数
|
||||
- **日期处理**: dayjs (集成 UTC 和 Timezone 插件)
|
||||
- **国际化**: i18next + react-i18next
|
||||
- **国际化**: Chrome `chrome.i18n` + `public/_locales/zh_CN/messages.json`
|
||||
- **通信**: @webext-core/messaging
|
||||
- **存储**: Chrome Storage API (类型安全封装)
|
||||
- **解析引擎**: qr-scanner (二维码解析), qrious (二维码生成)
|
||||
@@ -107,8 +107,8 @@
|
||||
│ ├── hooks/ # 自定义 React Hooks
|
||||
│ ├── utils/ # 工具函数与服务抽象
|
||||
│ ├── types/ # TypeScript 类型声明
|
||||
│ └── lib/ # 通用工具函数 (cn, utils 等)
|
||||
├── public/ # 静态资源 (图标、manifest 资源等)
|
||||
│ └── lib/ # 通用工具函数与生成器库 (cn, utils, generators 等)
|
||||
├── public/ # 静态资源 (图标、_locales 本地化资源等)
|
||||
├── wxt.config.ts # WXT 框架核心配置
|
||||
└── package.json # 项目元数据与依赖管理
|
||||
```
|
||||
@@ -155,7 +155,6 @@
|
||||
- `sidePanel`: 支持在浏览器侧边栏中运行.
|
||||
- `clipboardWrite`: 提供一键复制功能.
|
||||
- `contextMenus`: 注册右键菜单，支持快捷操作.
|
||||
- `alarms`: 管理后台定时任务（如清理后自动刷新）.
|
||||
|
||||
## 浏览器支持
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> 版本: v1.0
|
||||
> 创建时间: 2024-01-20
|
||||
> 状态: 待 Review
|
||||
> 状态: 已实现（见 `src/pages/TestDataGenerator/`、`src/lib/generators/`、`src/workers/generator.worker.ts`）
|
||||
|
||||
## 产品定位
|
||||
|
||||
@@ -19,3 +19,13 @@
|
||||
- [规则管理](./rule-management.md)
|
||||
- [界面设计](./ui-design.md)
|
||||
- [技术实现](./technical-implementation.md)
|
||||
|
||||
## 当前实现入口
|
||||
|
||||
- 页面入口：`src/pages/TestDataGenerator/index.tsx`
|
||||
- Worker：`src/workers/generator.worker.ts`
|
||||
- 生成器库：`src/lib/generators/`
|
||||
- 规则存储：`src/utils/ruleStorage.ts`
|
||||
- 导出工具：`src/utils/dataExporter.ts`
|
||||
|
||||
实现约束与任务完成状态记录在 [TASKS.md](./TASKS.md)。
|
||||
|
||||
@@ -12,8 +12,24 @@
|
||||
| `icon/48.png` | 48×48 图标（扩展管理页） |
|
||||
| `icon/96.png` | 96×96 图标 |
|
||||
| `icon/128.png` | 128×128 图标（Chrome Web Store） |
|
||||
| `_locales/` | Chrome 扩展本地化资源 |
|
||||
|
||||
## 本地化资源
|
||||
|
||||
项目使用 Chrome 扩展标准 `chrome.i18n`，默认语言在 `wxt.config.ts` 中配置为 `zh_CN`。
|
||||
|
||||
| 文件/目录 | 用途 |
|
||||
| ------------------------------ | -------------------------------------------------- |
|
||||
| `_locales/zh_CN/messages.json` | 默认中文语言包，包含功能名、描述、按钮、提示等翻译 |
|
||||
|
||||
添加或修改文案时：
|
||||
|
||||
- 使用 Chrome 扩展消息格式：`"key": { "message": "文本" }`
|
||||
- key 使用下划线分隔，例如 `testDataGenerator_title`
|
||||
- 代码中通过 `useI18n` 或 `getMessage` 读取，不要新增 `i18n/locales` 目录
|
||||
|
||||
## 注意事项
|
||||
|
||||
- 修改图标后需同步更新 `wxt.config.ts` 中的 manifest 配置
|
||||
- 图标格式推荐使用 PNG，确保透明背景
|
||||
- 修改 `_locales` 后需确认 `manifest.default_locale` 与语言目录名一致
|
||||
|
||||
@@ -1,51 +0,0 @@
|
||||
# entrypoints/
|
||||
|
||||
WXT 框架要求的扩展生命周期入口点，对应 Chrome Extension 的各个上下文。
|
||||
|
||||
## 入口文件
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ------------------------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `background.ts` | Service Worker 入口：注册右键菜单、监听菜单点击、处理消息通信、管理侧边栏状态、注入主环境脚本 |
|
||||
| `content.ts` | Content Script 入口：注入所有页面（`<all_urls>`），在 `document_end` 时初始化消息处理器 |
|
||||
| `rightClickRestorer.content.ts` | 专用 Content Script：处理右键菜单恢复功能，注入浮动状态徽章 |
|
||||
|
||||
## 子目录
|
||||
|
||||
### popup/
|
||||
|
||||
Popup 弹窗页面（点击扩展图标弹出）。
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ------------ | ------------------------------------------------------------------------------------- |
|
||||
| `index.html` | HTML 入口 |
|
||||
| `main.tsx` | React 挂载点 |
|
||||
| `App.tsx` | 根组件，组装 `RouterProvider` + `layout/TopBar` + `ErrorBoundary` + `RouterContainer` |
|
||||
|
||||
### sidepanel/
|
||||
|
||||
侧边栏页面，结构与 popup 类似，额外通知 background 侧边栏开启/关闭状态。
|
||||
|
||||
### options/
|
||||
|
||||
设置页面，支持：
|
||||
|
||||
- 拖拽排序功能顺序（`@dnd-kit`）
|
||||
- 功能可见性管理（显示/隐藏）
|
||||
- Popup/Sidepanel/Tab 三种模式独立配置
|
||||
|
||||
### content/
|
||||
|
||||
Content Script 内部分模块：
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ----------------------- | ------------------------------------------------------------------- |
|
||||
| `messageHandler.ts` | 消息处理器初始化入口 |
|
||||
| `contextMenuHandler.ts` | 右键菜单点击事件处理，执行时间戳转换/文本统计并通过 UI Popover 展示 |
|
||||
| `uiPopover.ts` | 在页面中注入浮层 Popover UI，展示右键菜单操作结果 |
|
||||
|
||||
## 架构说明
|
||||
|
||||
- `background.ts` 是扩展的核心协调者，处理跨上下文通信
|
||||
- `content.ts` 注入到所有页面，负责接收和处理来自 background 的消息
|
||||
- `popup/`、`sidepanel/`、`options/` 共享同一套页面组件（来自 `pages/`），通过 `RouterProvider` 的不同配置实现独立路由
|
||||
+33
-3
@@ -4,9 +4,10 @@
|
||||
|
||||
## 文件说明
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ---------- | ------------------------------------ |
|
||||
| `utils.ts` | `cn()` 函数 — shadcn/ui 标准工具函数 |
|
||||
| 文件/目录 | 用途 |
|
||||
| ------------- | -------------------------------------- |
|
||||
| `utils.ts` | `cn()` 函数 — shadcn/ui 标准工具函数 |
|
||||
| `generators/` | 测试数据生成器内置生成器库和分类注册表 |
|
||||
|
||||
## cn()
|
||||
|
||||
@@ -24,3 +25,32 @@ import { cn } from '@/lib/utils';
|
||||
```
|
||||
|
||||
所有需要动态合并 Tailwind 类名的场景都应使用 `cn()`，而非手动拼接字符串。
|
||||
|
||||
## generators/
|
||||
|
||||
测试数据生成器的核心生成器库，供 `src/workers/generator.worker.ts` 在后台线程中按字段配置生成数据。
|
||||
|
||||
| 文件 | 用途 |
|
||||
| -------------- | ---------------------------------------------- |
|
||||
| `index.ts` | 聚合所有生成器，导出分类、查找和搜索函数 |
|
||||
| `personal.ts` | 个人信息生成器（姓名、邮箱、手机号、身份证等） |
|
||||
| `business.ts` | 业务数据生成器（订单号、价格、日期、状态等） |
|
||||
| `technical.ts` | 技术数据生成器（UUID、IPv4、URL） |
|
||||
| `basic.ts` | 基础类型生成器（整数、浮点数、布尔值、字符串） |
|
||||
| `types.ts` | 生成器库内部类型与通用选项 |
|
||||
|
||||
使用示例：
|
||||
|
||||
```typescript
|
||||
import { getGeneratorById, searchGenerators } from '@/lib/generators';
|
||||
|
||||
const generator = getGeneratorById('chineseName');
|
||||
const value = generator?.generate({});
|
||||
const matched = searchGenerators('uuid');
|
||||
```
|
||||
|
||||
约束：
|
||||
|
||||
- 新增生成器必须实现 `GeneratorDefinition`，并加入所属分类文件的导出列表。
|
||||
- 需要唯一值或大批量稳定输出时，优先实现 `generateAtIndex(params, index)`。
|
||||
- 新增分类时同步更新 `generatorCategories`，并确保 `GeneratorSelector` 能展示该分类。
|
||||
|
||||
@@ -1,139 +0,0 @@
|
||||
# pages/
|
||||
|
||||
功能页面组件目录，每个子目录对应一个工具页面。
|
||||
|
||||
## 目录结构约定
|
||||
|
||||
典型页面遵循 **UI + Hook 分离** 模式：
|
||||
|
||||
```
|
||||
pages/FeatureName/
|
||||
├── index.tsx # 页面 UI（纯展示，使用 shadcn/ui 组件）
|
||||
├── useFeatureName.ts # 业务逻辑 Hook（状态管理 + 转换逻辑）
|
||||
├── constants.ts # 常量定义（可选）
|
||||
├── SubComponent.tsx # 子组件（可选）
|
||||
└── __tests__/ # 测试文件
|
||||
└── index.test.tsx
|
||||
```
|
||||
|
||||
## 页面列表
|
||||
|
||||
### Dashboard/
|
||||
|
||||
仪表盘首页，以卡片网格展示所有可见工具，支持点击导航。
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ----------- | -------------------------- |
|
||||
| `index.tsx` | 页面组件，渲染工具卡片网格 |
|
||||
|
||||
### Timestamp/
|
||||
|
||||
时间戳转换工具，支持秒/毫秒级互转、多时区选择、实时时钟。
|
||||
|
||||
| 文件 | 用途 |
|
||||
| -------------------------- | ----------------------------------------------------------------- |
|
||||
| `index.tsx` | 页面 UI |
|
||||
| `useTimestampConverter.ts` | 业务逻辑 Hook，包含转换模式、输入、单位、时区状态和响应式计算管线 |
|
||||
| `LiveClock.tsx` | 实时时钟子组件，`React.memo` 优化 |
|
||||
| `ResultView.tsx` | 转换结果展示子组件 |
|
||||
| `constants.ts` | 时区列表等常量 |
|
||||
|
||||
### StorageCleaner/
|
||||
|
||||
浏览器存储清理工具，支持 Cookie/LocalStorage/SessionStorage/IndexedDB/Cache/SW 清理。
|
||||
|
||||
| 文件 | 用途 |
|
||||
| --------------------------- | -------------- |
|
||||
| `index.tsx` | 页面 UI |
|
||||
| `useStorageCleaner.ts` | 业务逻辑 Hook |
|
||||
| `StorageOptionsGrid.tsx` | 清理选项网格 |
|
||||
| `StorageCleanerConfirm.tsx` | 清理确认对话框 |
|
||||
| `AutoRefreshToggle.tsx` | 自动刷新开关 |
|
||||
| `ErrorDisplay.tsx` | 错误展示组件 |
|
||||
| `CleaningResult.tsx` | 清理结果展示 |
|
||||
| `OptionItem.tsx` | 单个选项组件 |
|
||||
|
||||
### QrCode/
|
||||
|
||||
二维码工具，支持生成（URL→QR）和解析（QR→URL）。
|
||||
|
||||
| 文件/目录 | 用途 |
|
||||
| ------------- | ---------------- |
|
||||
| `index.tsx` | 页面 UI |
|
||||
| `types.ts` | 类型定义 |
|
||||
| `contexts/` | Context Provider |
|
||||
| `hooks/` | 业务逻辑 Hooks |
|
||||
| `components/` | 子组件 |
|
||||
|
||||
### TextStatistics/
|
||||
|
||||
文本统计工具，实时计算字符数、单词数、行数、字节大小。
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ----------- | --------------------------------------------- |
|
||||
| `index.tsx` | 页面组件，集成 `TextInputArea` 和统计结果展示 |
|
||||
|
||||
### Jwt/
|
||||
|
||||
JWT 解析工具，解码 Header/Payload/Signature。
|
||||
|
||||
| 文件/目录 | 用途 |
|
||||
| ------------- | ---------------- |
|
||||
| `index.tsx` | 页面 UI |
|
||||
| `types.ts` | 类型定义 |
|
||||
| `contexts/` | Context Provider |
|
||||
| `hooks/` | 业务逻辑 Hooks |
|
||||
| `components/` | 子组件 |
|
||||
|
||||
### JsonTools/
|
||||
|
||||
JSON 工具集：差异比较、格式化、YAML/TOML/Minify 转换。
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ------------------------ | ---------------------------- |
|
||||
| `index.tsx` | 页面入口，子模式切换 |
|
||||
| `types.ts` | 类型定义 |
|
||||
| `diffEngine.ts` | 差异比较引擎 |
|
||||
| `JsonDiffInput.tsx` | JSON 输入组件 |
|
||||
| `DiffResult.tsx` | 差异结果展示 |
|
||||
| `DiffNavigator.tsx` | 差异导航器 |
|
||||
| `JsonFormatSection.tsx` | 格式化区域 |
|
||||
| `JsonConvertSection.tsx` | 转换区域（YAML/TOML/Minify） |
|
||||
| `JsonTree.tsx` | JSON 树形展示 |
|
||||
|
||||
### Base64Converter/
|
||||
|
||||
Base64 编解码工具，支持文本/文件/图片三种模式。
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ---------------------------- | --------------------- |
|
||||
| `index.tsx` | 页面入口，子模式切换 |
|
||||
| `useBase64Converter.ts` | 业务逻辑 Hook |
|
||||
| `TextMode.tsx` | 文本模式 |
|
||||
| `Base64ConverterSection.tsx` | 文件/图片通用转换区域 |
|
||||
|
||||
### MarkdownToHtml/
|
||||
|
||||
Markdown 转 HTML 工具，支持分栏/预览/源码三种视图模式。
|
||||
|
||||
### HtmlToMarkdown/
|
||||
|
||||
HTML 转 Markdown 工具，支持分栏/预览/Markdown 三种视图模式。
|
||||
|
||||
### RightClickRestorer/
|
||||
|
||||
右键菜单恢复工具，解除网站对右键的限制。
|
||||
|
||||
| 文件 | 用途 |
|
||||
| -------------------------- | ------------- |
|
||||
| `index.tsx` | 页面 UI |
|
||||
| `useRightClickRestorer.ts` | 业务逻辑 Hook |
|
||||
|
||||
## 新增页面
|
||||
|
||||
1. 在 `types/storage.d.ts` 添加 `PageType` 联合类型成员
|
||||
2. 在 `config/features.tsx` 的 `FEATURES` 数组添加配置
|
||||
3. 在 `pages/` 创建页面目录（遵循上述结构）
|
||||
4. 在 `i18n/locales/{zh,en}/features.json` 添加翻译
|
||||
5. 如需新权限，更新 `wxt.config.ts`
|
||||
6. 添加对应的单元测试
|
||||
@@ -103,4 +103,31 @@ describe('StorageCleaner 页面', () => {
|
||||
expect(screen.getByRole('button', { name: /立即清理/ })).not.toBeDisabled();
|
||||
});
|
||||
});
|
||||
|
||||
it('展示的数据与当前标签页不一致时不应执行清理', async () => {
|
||||
let currentTabId = 1;
|
||||
vi.mocked(getCurrentTab).mockImplementation(
|
||||
async () =>
|
||||
({
|
||||
id: currentTabId,
|
||||
url: currentTabId === 1 ? 'https://a.example.com' : 'https://b.example.com',
|
||||
}) as any,
|
||||
);
|
||||
|
||||
render(<Index />);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByRole('button', { name: /立即清理/ })).not.toBeDisabled();
|
||||
});
|
||||
|
||||
currentTabId = 2;
|
||||
|
||||
fireEvent.click(screen.getByRole('button', { name: /立即清理/ }));
|
||||
fireEvent.click(screen.getByRole('button', { name: /确认清理/ }));
|
||||
|
||||
await waitFor(() => {
|
||||
expect(clearStorage).not.toHaveBeenCalled();
|
||||
expect(toast.warning).toHaveBeenCalledWith('当前标签页已切换，请等待数据刷新后再清理');
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -15,6 +15,7 @@ export default function Index() {
|
||||
sizes,
|
||||
reloadAfterClean,
|
||||
loading,
|
||||
isRefreshingSizes,
|
||||
result,
|
||||
showConfirm,
|
||||
setShowConfirm,
|
||||
@@ -26,7 +27,7 @@ export default function Index() {
|
||||
handleClean,
|
||||
} = useStorageCleaner();
|
||||
|
||||
const isButtonDisabled = !(someSelected || allSelected) || loading;
|
||||
const isButtonDisabled = !(someSelected || allSelected) || loading || isRefreshingSizes;
|
||||
|
||||
if (isInitializing) {
|
||||
return (
|
||||
|
||||
@@ -75,6 +75,7 @@ export interface UseStorageCleanerReturn {
|
||||
sizes: Record<string, StorageSizeInfo>;
|
||||
reloadAfterClean: boolean;
|
||||
loading: boolean;
|
||||
isRefreshingSizes: boolean;
|
||||
result: CleaningResult | null;
|
||||
showConfirm: boolean;
|
||||
setShowConfirm: (show: boolean) => void;
|
||||
@@ -95,10 +96,12 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
|
||||
const [sizes, setSizes] = useState<Record<string, StorageSizeInfo>>({});
|
||||
const [reloadAfterClean, setReloadAfterClean] = useState<boolean>(true);
|
||||
const [loading, setLoading] = useState<boolean>(false);
|
||||
const [isRefreshingSizes, setIsRefreshingSizes] = useState<boolean>(false);
|
||||
const [result, setResult] = useState<CleaningResult | null>(null);
|
||||
const [showConfirm, setShowConfirm] = useState<boolean>(false);
|
||||
|
||||
const requestIdRef = useRef<number>(0);
|
||||
const boundTabRef = useRef<{ id: number; url: string } | null>(null);
|
||||
const debounceTimerRef = useRef<NodeJS.Timeout | null>(null);
|
||||
const storageTimerRef = useRef<NodeJS.Timeout | null>(null);
|
||||
const loadingRef = useRef(loading);
|
||||
@@ -117,6 +120,7 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
|
||||
// 核心数据拉取链条
|
||||
const loadInfo = useCallback(async () => {
|
||||
const currentRequestId = ++requestIdRef.current;
|
||||
setIsRefreshingSizes(true);
|
||||
try {
|
||||
const tab = await getCurrentTab();
|
||||
if (currentRequestId !== requestIdRef.current) return;
|
||||
@@ -159,6 +163,7 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
|
||||
cacheStorage: { value: cacheCount, displayType: 'count' },
|
||||
serviceWorkers: { value: swCount, displayType: 'count' },
|
||||
});
|
||||
boundTabRef.current = { id: tabId, url };
|
||||
} catch (err) {
|
||||
console.error('Failed to load storage cleaner info:', err);
|
||||
if (currentRequestId === requestIdRef.current) {
|
||||
@@ -167,6 +172,7 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
|
||||
} finally {
|
||||
if (currentRequestId === requestIdRef.current) {
|
||||
setIsInitializing(false);
|
||||
setIsRefreshingSizes(false);
|
||||
}
|
||||
}
|
||||
}, []);
|
||||
@@ -256,6 +262,13 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
|
||||
return;
|
||||
}
|
||||
|
||||
const boundTab = boundTabRef.current;
|
||||
if (!boundTab || boundTab.id !== tab.id) {
|
||||
toast.warning('当前标签页已切换，请等待数据刷新后再清理');
|
||||
setShowConfirm(false);
|
||||
return;
|
||||
}
|
||||
|
||||
setLoading(true);
|
||||
setShowConfirm(false);
|
||||
try {
|
||||
@@ -297,6 +310,7 @@ export function useStorageCleaner(): UseStorageCleanerReturn {
|
||||
sizes,
|
||||
reloadAfterClean,
|
||||
loading,
|
||||
isRefreshingSizes,
|
||||
result,
|
||||
showConfirm,
|
||||
setShowConfirm,
|
||||
|
||||
@@ -105,6 +105,8 @@ export function RouterProvider({
|
||||
);
|
||||
|
||||
const [isLoaded, setIsLoaded] = useState(false);
|
||||
const hasUserNavigatedRef = useRef(false);
|
||||
const canPersistRef = useRef(false);
|
||||
|
||||
/**
|
||||
* 从异步存储中安全溯源初始数据
|
||||
@@ -119,7 +121,7 @@ export function RouterProvider({
|
||||
const savedPageOrder = await storageUtil.get(pageOrderKey, getDefaultPageOrder());
|
||||
const savedRecentTools = await storageUtil.get('app/recentlyUsedTools', []);
|
||||
|
||||
if (isValidPage(savedRoute) && syncRoute) {
|
||||
if (isValidPage(savedRoute) && syncRoute && !hasUserNavigatedRef.current) {
|
||||
setCurrentPage(savedRoute);
|
||||
}
|
||||
if (isValidPageList(savedVisiblePages)) {
|
||||
@@ -131,9 +133,11 @@ export function RouterProvider({
|
||||
if (isValidPageList(savedRecentTools)) {
|
||||
setRecentlyUsedTools(savedRecentTools);
|
||||
}
|
||||
setIsLoaded(true);
|
||||
canPersistRef.current = true;
|
||||
} catch (error) {
|
||||
console.error('[Router Init Error] Core data fetch failed:', error);
|
||||
} finally {
|
||||
setIsLoaded(true);
|
||||
}
|
||||
}, [defaultRoute, syncKey, syncRoute, visiblePagesKey, pageOrderKey]);
|
||||
|
||||
@@ -187,7 +191,7 @@ export function RouterProvider({
|
||||
}, [loadInitialData]);
|
||||
|
||||
useEffect(() => {
|
||||
if (isLoaded && syncRoute) {
|
||||
if (isLoaded && canPersistRef.current && syncRoute) {
|
||||
void storageUtil.set(syncKey, currentPage as PageType).catch(console.error);
|
||||
try {
|
||||
localStorage.setItem(`snapshot/${syncKey}`, JSON.stringify(currentPage));
|
||||
@@ -198,7 +202,7 @@ export function RouterProvider({
|
||||
}, [currentPage, isLoaded, syncRoute, syncKey]);
|
||||
|
||||
useEffect(() => {
|
||||
if (isLoaded) {
|
||||
if (isLoaded && canPersistRef.current) {
|
||||
void storageUtil.set(visiblePagesKey, visiblePages).catch(console.error);
|
||||
try {
|
||||
localStorage.setItem(`snapshot/${visiblePagesKey}`, JSON.stringify(visiblePages));
|
||||
@@ -209,7 +213,7 @@ export function RouterProvider({
|
||||
}, [visiblePages, isLoaded, visiblePagesKey]);
|
||||
|
||||
useEffect(() => {
|
||||
if (isLoaded) {
|
||||
if (isLoaded && canPersistRef.current) {
|
||||
void storageUtil.set(pageOrderKey, pageOrder).catch(console.error);
|
||||
try {
|
||||
localStorage.setItem(`snapshot/${pageOrderKey}`, JSON.stringify(pageOrder));
|
||||
@@ -220,7 +224,7 @@ export function RouterProvider({
|
||||
}, [pageOrder, isLoaded, pageOrderKey]);
|
||||
|
||||
useEffect(() => {
|
||||
if (isLoaded) {
|
||||
if (isLoaded && canPersistRef.current) {
|
||||
void storageUtil.set('app/recentlyUsedTools', recentlyUsedTools).catch(console.error);
|
||||
try {
|
||||
localStorage.setItem('snapshot/app/recentlyUsedTools', JSON.stringify(recentlyUsedTools));
|
||||
@@ -283,6 +287,8 @@ export function RouterProvider({
|
||||
}, [syncRoute, syncKey, visiblePagesKey, pageOrderKey]);
|
||||
|
||||
const navigateTo = (page: PageType) => {
|
||||
hasUserNavigatedRef.current = true;
|
||||
canPersistRef.current = true;
|
||||
setCurrentPage(page);
|
||||
setRecentlyUsedTools((prev) => {
|
||||
const filtered = prev.filter((p) => p !== page);
|
||||
@@ -291,6 +297,8 @@ export function RouterProvider({
|
||||
};
|
||||
|
||||
const goHome = () => {
|
||||
hasUserNavigatedRef.current = true;
|
||||
canPersistRef.current = true;
|
||||
setCurrentPage('dashboard');
|
||||
};
|
||||
|
||||
|
||||
@@ -323,6 +323,51 @@ describe('RouterProvider', () => {
|
||||
});
|
||||
});
|
||||
|
||||
it('初始化失败时仍应解除加载状态以便渲染页面', async () => {
|
||||
(storageUtil.get as any).mockRejectedValue(new Error('Storage unavailable'));
|
||||
|
||||
render(
|
||||
<RouterProvider>
|
||||
<TestComponent />
|
||||
</RouterProvider>,
|
||||
);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(screen.getByTestId('current-page')).toHaveTextContent('dashboard');
|
||||
});
|
||||
expect(storageUtil.set).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it('用户在 loadInitialData 完成前导航时不应被存储路由覆盖', async () => {
|
||||
let resolveGet: () => void;
|
||||
const getBlocked = new Promise<void>((resolve) => {
|
||||
resolveGet = resolve;
|
||||
});
|
||||
|
||||
(storageUtil.get as any).mockImplementation(async (key: string, defaultValue: unknown) => {
|
||||
await getBlocked;
|
||||
if (key === 'app/currentRoute') return 'dashboard';
|
||||
return defaultValue;
|
||||
});
|
||||
|
||||
render(
|
||||
<RouterProvider>
|
||||
<TestComponent />
|
||||
</RouterProvider>,
|
||||
);
|
||||
|
||||
await act(async () => {
|
||||
fireEvent.click(screen.getByTestId('navigate-btn'));
|
||||
});
|
||||
expect(screen.getByTestId('current-page')).toHaveTextContent('timestamp');
|
||||
|
||||
resolveGet!();
|
||||
await waitFor(() => {
|
||||
expect(screen.getByTestId('current-page')).toHaveTextContent('timestamp');
|
||||
expect(storageUtil.set).toHaveBeenCalledWith('app/currentRoute', 'timestamp');
|
||||
});
|
||||
});
|
||||
|
||||
it('组件卸载时不应设置 isLoaded 状态（竞态条件防护）', async () => {
|
||||
let resolveStorage: (value: unknown) => void;
|
||||
const storagePromise = new Promise((resolve) => {
|
||||
|
||||
+11
-3
@@ -10,12 +10,10 @@
|
||||
|
||||
**页面类型：**
|
||||
|
||||
- `PageType` — 所有页面类型的联合类型（`dashboard` | `timestamp` | `storageCleaner` | ...）
|
||||
- `PageType` — 所有页面类型的联合类型（含 `dashboard`、`timestamp`、`storageCleaner`、`testDataGenerator` 等）
|
||||
- `JsonToolsPageMode` — JSON 工具子模式（`diff` | `format` | `yaml` | `toml` | `minify`）
|
||||
- `Base64ConverterPageMode` — Base64 子模式（`text` | `file` | `image`）
|
||||
- `Base64ConvertDirection` — 编解码方向（`encode` | `decode`）
|
||||
- `MarkdownToHtmlPreviewMode` — Markdown 预览模式（`split` | `preview` | `html`）
|
||||
- `HtmlToMarkdownPreviewMode` — HTML 预览模式（`split` | `preview` | `markdown`）
|
||||
|
||||
**存储 Schema：**
|
||||
|
||||
@@ -34,6 +32,16 @@
|
||||
|
||||
`qrious` 库的类型声明，定义 QR 码生成选项和 `QRious` 类。
|
||||
|
||||
### testDataGenerator.ts
|
||||
|
||||
测试数据生成器共享类型，包含：
|
||||
|
||||
- `FieldConfig` — 字段配置（字段名、生成器、参数、必填、空值率、唯一性）
|
||||
- `DataRule` — 可保存/导入/导出的字段规则
|
||||
- `GeneratorDefinition` / `GeneratorParam` — 内置生成器定义和参数 Schema
|
||||
- `GenerateResult` / `GenerateProgress` / `WorkerMessage` — Worker 生成结果、进度和消息协议
|
||||
- `ExportFile` — JSON/CSV 导出文件描述
|
||||
|
||||
## 修改 StorageSchema 的注意事项
|
||||
|
||||
修改 `StorageSchema` 时，必须：
|
||||
|
||||
+22
-21
@@ -4,39 +4,40 @@
|
||||
|
||||
## 工具函数
|
||||
|
||||
| 文件 | 用途 |
|
||||
| -------------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `chromeStorage.ts` | Chrome Storage API 封装：类型安全的 `StorageUtils` 类，提供 `get/set/remove` 方法 |
|
||||
| `chromeTabs.ts` | Chrome Tabs API 封装：获取活动标签页、获取域名、在新标签页打开扩展页面 |
|
||||
| `clipboard.ts` | 剪贴板操作：`copyTextToClipboard`（文本）、`copyImageToClipboard`（图片） |
|
||||
| `messages.ts` | 扩展消息通信：基于 `@webext-core/messaging`，定义 `MessageAction` 枚举和 `ProtocolMap` 类型安全映射 |
|
||||
| `contextMenu.ts` | 右键菜单配置与操作：定义菜单项、创建菜单、解析点击事件、ID→PageType 映射 |
|
||||
| `base64Converter.ts` | Base64 编解码：文本↔Base64、文件↔Base64、图片预览，定义文件大小限制和图像 MIME 类型 |
|
||||
| `jwt.ts` | JWT 解析：Base64URL 解码、解析 Header/Payload/Signature、JSON 格式化输出 |
|
||||
| `jsonFormatter.ts` | JSON 格式化/压缩：支持缩进、按键排序、minify |
|
||||
| `jsonToYaml.ts` | JSON→YAML 转换 |
|
||||
| `jsonToToml.ts` | JSON→TOML 转换 |
|
||||
| `markdownToHtml.ts` | Markdown→HTML 转换：基于 `marked` 库，支持 GFM 和换行转换 |
|
||||
| `htmlToMarkdown.ts` | HTML→Markdown 转换：基于 DOMParser 解析 |
|
||||
| `qrCodeParser.ts` | 二维码解析：基于 `qr-scanner` 库从文件中解析二维码 |
|
||||
| `storageCleaner.ts` | 存储清理：获取当前标签页、检测受限 URL、计算 Cookie/Storage 大小、清理操作 |
|
||||
| `textStatistics.ts` | 文本统计：使用 `Intl.Segmenter` 计算字符数/单词数/行数/字节大小 |
|
||||
| `format.ts` | 通用格式化：`formatBytes` 将字节转为可读字符串（B/KB/MB/GB/TB） |
|
||||
| `dayjs.ts` | Day.js 初始化：扩展 UTC、Timezone、RelativeTime 插件，加载中文本地化 |
|
||||
| 文件 | 用途 |
|
||||
| ------------------------ | --------------------------------------------------------------------------------------------------- |
|
||||
| `chromeStorage.ts` | Chrome Storage API 封装：类型安全的 `StorageUtils` 类，提供 `get/set/remove` 方法 |
|
||||
| `chromeTabs.ts` | Chrome Tabs API 封装：获取活动标签页、获取域名、在新标签页打开扩展页面 |
|
||||
| `clipboard.ts` | 剪贴板操作：`copyTextToClipboard`（文本）、`copyImageToClipboard`（图片） |
|
||||
| `messages.ts` | 扩展消息通信：基于 `@webext-core/messaging`，定义 `MessageAction` 枚举和 `ProtocolMap` 类型安全映射 |
|
||||
| `contextMenu.ts` | 右键菜单配置与操作：定义菜单项、创建菜单、解析点击事件、ID→PageType 映射 |
|
||||
| `base64Converter.ts` | Base64 编解码：文本↔Base64、文件↔Base64、图片预览，定义文件大小限制和图像 MIME 类型 |
|
||||
| `jwt.ts` | JWT 解析：Base64URL 解码、解析 Header/Payload/Signature、JSON 格式化输出 |
|
||||
| `jsonFormatter.ts` | JSON 格式化/压缩：支持缩进、按键排序、minify |
|
||||
| `jsonToYaml.ts` | JSON→YAML 转换 |
|
||||
| `jsonToToml.ts` | JSON→TOML 转换 |
|
||||
| `qrCodeParser.ts` | 二维码解析：基于 `qr-scanner` 库从文件中解析二维码 |
|
||||
| `storageCleaner.ts` | 存储清理：获取当前标签页、检测受限 URL、计算 Cookie/Storage 大小、清理操作 |
|
||||
| `textStatistics.ts` | 文本统计：使用 `Intl.Segmenter` 计算字符数/单词数/行数/字节大小 |
|
||||
| `format.ts` | 通用格式化：`formatBytes` 将字节转为可读字符串（B/KB/MB/GB/TB） |
|
||||
| `dayjs.ts` | Day.js 初始化：扩展 UTC、Timezone、RelativeTime 插件，加载中文本地化 |
|
||||
| `chromeI18n.ts` | Chrome `chrome.i18n` 包装：提供 `getMessage` 和兼容 React 使用的 `useI18n` Hook |
|
||||
| `ruleStorage.ts` | 测试数据生成器规则存储：基于 `localStorage` 的 CRUD、搜索、导入/导出和数量限制 |
|
||||
| `dataExporter.ts` | 测试数据导出：JSON/CSV 转换、文件下载和复制到剪贴板 |
|
||||
| `rightClickInjection.ts` | 右键恢复注入脚本：在页面上下文恢复 contextmenu/copy/paste 等事件默认行为 |
|
||||
|
||||
## 自定义 Hooks
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
|
||||
| `useStorageState.ts` | Chrome Storage 状态 Hook：类似 `useState`，值自动同步到 `chrome.storage`，使用 `localStorage` 快照消除首屏闪烁 |
|
||||
| `useLazyTranslation.ts` | 懒加载翻译 Hook：按需动态导入 i18n 命名空间，支持预加载和缓存 |
|
||||
| `useContextMenuData.ts` | 右键菜单数据 Hook：从 storage 读取待处理数据，匹配 featureKey 后消费并触发回调 |
|
||||
| `useDebounce.ts` | 防抖 Hook：对值进行延迟更新，避免频繁触发 |
|
||||
|
||||
## 使用约定
|
||||
|
||||
- 工具函数使用**命名导出**（`export function xxx()`）
|
||||
- 工具函数**不抛异常**，返回包含 `hasError` 和 `error` 字段的结果对象
|
||||
- 工具层不直接展示 Toast；可恢复错误返回可判断结果，需要抛出的解析/转换错误由页面 Hook 或 UI 层捕获
|
||||
- Hook 使用 `use` 前缀命名，定义返回值接口类型
|
||||
- 存储操作使用 `chromeStorage.ts` 的 `storageUtil` 封装，不要直接调用 `chrome.storage`
|
||||
- 消息通信使用 `messages.ts` 的 `sendMessage`/`onMessage`，不要使用原生 `chrome.runtime.sendMessage`
|
||||
|
||||
@@ -166,4 +166,18 @@ describe('useStorageState', () => {
|
||||
|
||||
expect(result.current[2]).toBe(false);
|
||||
});
|
||||
|
||||
it('加载失败时不应把快照默认值写回 Chrome Storage', async () => {
|
||||
localStorage.setItem('snapshot/app/searchHistory', JSON.stringify([]));
|
||||
|
||||
(storageUtil.get as any).mockRejectedValue(new Error('Storage read failed'));
|
||||
|
||||
renderHook(() =>
|
||||
useStorageState('app/searchHistory', [], (val): val is string[] => Array.isArray(val)),
|
||||
);
|
||||
|
||||
await waitFor(() => {
|
||||
expect(storageUtil.set).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,4 +1,11 @@
|
||||
import { useEffect, useRef, useState } from 'react';
|
||||
import {
|
||||
useCallback,
|
||||
useEffect,
|
||||
useRef,
|
||||
useState,
|
||||
type Dispatch,
|
||||
type SetStateAction,
|
||||
} from 'react';
|
||||
import { storageUtil } from '@/utils/chromeStorage';
|
||||
import { getSyncSnapshot } from '@/utils/syncSnapshot';
|
||||
import type { StorageSchema } from '@/types/storage';
|
||||
@@ -8,11 +15,18 @@ export const useStorageState = <K extends keyof StorageSchema>(
|
||||
defaultValue: StorageSchema[K],
|
||||
validator?: (val: unknown) => val is StorageSchema[K],
|
||||
) => {
|
||||
const [value, setValue] = useState<StorageSchema[K]>(() =>
|
||||
const [value, setValueInternal] = useState<StorageSchema[K]>(() =>
|
||||
getSyncSnapshot(key as string, defaultValue, validator),
|
||||
);
|
||||
const [isInitialized, setIsInitialized] = useState(false);
|
||||
const hasLoadedFromStorage = useRef(false);
|
||||
const loadSucceededRef = useRef(false);
|
||||
const userModifiedRef = useRef(false);
|
||||
|
||||
const setValue = useCallback<Dispatch<SetStateAction<StorageSchema[K]>>>((next) => {
|
||||
userModifiedRef.current = true;
|
||||
setValueInternal(next);
|
||||
}, []);
|
||||
|
||||
// Only load from storage once on mount
|
||||
useEffect(() => {
|
||||
@@ -24,15 +38,17 @@ export const useStorageState = <K extends keyof StorageSchema>(
|
||||
try {
|
||||
const savedValue = await storageUtil.get(key, defaultValue);
|
||||
if (cancelled) return;
|
||||
loadSucceededRef.current = true;
|
||||
if (savedValue !== undefined) {
|
||||
if (validator) {
|
||||
setValue(validator(savedValue) ? savedValue : defaultValue);
|
||||
setValueInternal(validator(savedValue) ? savedValue : defaultValue);
|
||||
} else {
|
||||
setValue(savedValue);
|
||||
setValueInternal(savedValue);
|
||||
}
|
||||
}
|
||||
} catch (error) {
|
||||
console.error(`加载状态失败 (${key}):`, error);
|
||||
loadSucceededRef.current = false;
|
||||
} finally {
|
||||
if (!cancelled) {
|
||||
setIsInitialized(true);
|
||||
@@ -51,6 +67,7 @@ export const useStorageState = <K extends keyof StorageSchema>(
|
||||
// Save to storage and localStorage snapshot when value changes (after initial load)
|
||||
useEffect(() => {
|
||||
if (!isInitialized) return;
|
||||
if (!loadSucceededRef.current && !userModifiedRef.current) return;
|
||||
|
||||
const saveState = async () => {
|
||||
try {
|
||||
|
||||
Reference in New Issue
Block a user