rsgltzyd/testing-tool
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: 同步工程文档与当前架构 (#70)

Browse Source 
* docs(工程文档): 同步当前架构说明
* docs(工程文档): 格式化文档表格
This commit is contained in:
cursor[bot]
2026-06-26 16:59:53 +08:00
committed by GitHub
parent a163297de4
commit 5ae9cf065f
11 changed files with 181 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/CODING_STANDARDS.md
+42 -38
View File
@@ -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` 语言包 |
---
.github/copilot-instructions.md
+11 -12
View File
@@ -1,6 +1,6 @@
# Copilot 指令
基于 WXT 框架的浏览器扩展项目（React 19 + TypeScript），为开发者和测试人员提供效率工具：时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、Markdown 等。
基于 WXT 框架的浏览器扩展项目（React 19 + TypeScript），为开发者和测试人员提供效率工具：时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、测试数据生成器等。
## 核心命令
@@ -74,10 +74,10 @@ pages/FeatureName/
1. 在 `types/storage.d.ts` 的 `PageType` 联合类型中添加新成员
2. 在 `config/features.tsx` 的 `FEATURES` 数组中添加配置（key、翻译键、图标、三种渲染模式组件）
3. 在 `pages/` 目录创建页面组件（懒加载）：
- `index.tsx` — 使用 `useLazyTranslation` 的 UI 组件
- `index.tsx` — 使用 `useI18n` 的 UI 组件
- `useFeatureName.ts` — 业务逻辑 Hook
- `constants.ts` — 常量（可选）
4. 在 `i18n/locales/{zh,en}/features.json` 添加翻译（复杂功能可新建独立 JSON 文件）
4. 在 `public/_locales/zh_CN/messages.json` 添加 Chrome i18n 翻译
5. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
6. 添加对应的单元测试
@@ -102,7 +102,7 @@ pages/FeatureName/
### 代码分割
`wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组 vendor 依赖（vendor-react、vendor-i18n、vendor-qr、vendor-dnd），无需手动配置。
`wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组 vendor 依赖（vendor-react、vendor-qr、vendor-dnd），无需手动配置。
### 代码风格
@@ -118,8 +118,7 @@ pages/FeatureName/
- 全局变量：`vitest/globals`（describe、it、expect 等无需导入）
- Setup 文件：`vitest.setup.ts` 自动 mock 以下内容：
- `chrome.*` / `browser.*` API（storage、tabs、runtime、cookies 等）
- `react-i18next`（返回 key 作为翻译）
- `@/utils/useLazyTranslation`（返回 `ns:key` 格式）
- `@/utils/chromeI18n`（从 `public/_locales/zh_CN/messages.json` 加载真实翻译）
- `window.matchMedia`
- 测试文件命名：`__tests__/*.test.{ts,tsx}` 或 `*.test.{ts,tsx}`
- 使用 `vi.mock()` 进行模块级 mock；避免重复 mock `vitest.setup.ts` 中已有的内容
@@ -127,12 +126,12 @@ pages/FeatureName/
### 国际化（i18n）
- 命名空间：`common`（默认）、`features`
- 翻译键格式：`namespace:key`（如 `features:timestamp.title`）
- 语言：`zh`（默认）、`en`
- 翻译文件：`i18n/locales/{zh,en}/{common,features}.json` + 各功能独立 JSON 文件
- 使用 `useLazyTranslation` Hook 加载功能专属翻译
- 回退策略：缺失的翻译键回退到 `zh`，若仍缺失则返回占位格式 `namespace:key`
- 使用 Chrome 扩展标准 `chrome.i18n`
- 默认语言目录：`public/_locales/zh_CN/messages.json`
- 使用方式：`import { useI18n } from '@/utils/chromeI18n'`
- 翻译键格式：直接 key（如 `timestamp_title`）；兼容 `namespace:key.path` 并转换为下划线
- 回退策略：缺失翻译返回 key 本身，并在开发模式下记录 warning
- 限制：`chrome.i18n` 跟随浏览器语言，不能在运行时动态切换语言
### WXT 生成文件
AGENTS.md
+8 -7
View File
@@ -1,6 +1,6 @@
# AGENTS.md
WXT 浏览器扩展项目 (React 19 + TypeScript)。提供时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、Markdown、测试数据生成器等测试效率工具。
WXT 浏览器扩展项目 (React 19 + TypeScript)。提供时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、测试数据生成器等测试效率工具。
## 核心命令
@@ -98,8 +98,9 @@ src/pages/TestDataGenerator/
src/utils/
├── ruleStorage.ts # 规则持久化存储（localStorage）
├── dataExporter.ts # 数据导出工具（JSON/CSV 转换、下载、剪贴板）
└── generators/ # 内置生成器定义（个人信息、企业、技术、基础类型）
└── dataExporter.ts # 数据导出工具（JSON/CSV 转换、下载、剪贴板）
src/lib/generators/ # 内置生成器定义（个人信息、企业、技术、基础类型）
src/workers/
└── generator.worker.ts # 数据生成 Web Worker
@@ -132,7 +133,7 @@ src/types/
- 全局变量: `vitest/globals` (describe, it, expect 等无需导入)
- Setup 文件: `vitest.setup.ts` 自动 mock:
- `chrome.*` / `browser.*` API (storage, tabs, runtime, cookies 等)
- `@/utils/chromeI18n` (从 `public/_locales/zh/messages.json` 加载真实翻译)
- `@/utils/chromeI18n` (从 `public/_locales/zh_CN/messages.json` 加载真实翻译)
- `window.matchMedia`
- 测试文件命名: `__tests__/*.test.{ts,tsx}` 或 `*.test.{ts,tsx}`
- Mock 模式: 使用 `vi.mock()` 进行模块级 mock，避免在测试文件中重复 mock 代码
@@ -142,8 +143,8 @@ src/types/
项目使用 Chrome 扩展标准的 `chrome.i18n` API 进行本地化，通过 `src/utils/chromeI18n.ts` 提供类型安全的 React Hook 包装。
- **翻译文件**: `public/_locales/{zh,en}/messages.json`（Chrome 扩展标准格式）
- **默认语言**: `zh`（在 `wxt.config.ts` 的 `manifest.default_locale` 中配置）
- **翻译文件**: `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`
@@ -162,7 +163,7 @@ src/types/
- `index.tsx` — UI 组件，使用 `useI18n` 获取翻译
- `useFeatureName.ts` — 业务逻辑 Hook
- `constants.ts` — 常量（可选）
4. 在 `public/_locales/zh/messages.json`（及 `en/messages.json`）添加翻译
4. 在 `public/_locales/zh_CN/messages.json` 添加翻译
5. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
6. 添加对应的单元测试
README.md
+3 -4
View File
@@ -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`: 管理后台定时任务（如清理后自动刷新）.
## 浏览器支持
docs/test-data-generator/README.md
+11 -1
View File
@@ -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)。
public/README.md
+16
View File
@@ -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` 与语言目录名一致
src/config/README.md
+2 -3
View File
@@ -19,7 +19,7 @@
- `defaultVisible`：默认是否可见
- `components`：三种渲染模式的懒加载组件（`popup`、`sidepanel`、`tab`）
## 已注册功能（11 个）
## 已注册功能（10 个）
| key | 图标 | 说明 |
| -------------------- | ----------------- | ----------------- |
@@ -31,9 +31,8 @@
| `jwt` | Key | JWT 解析工具 |
| `jsonDiff` | GitCompareArrows | JSON 差异比较工具 |
| `base64Converter` | ArrowLeftRight | Base64 转换器 |
| `markdownToHtml` | Code | Markdown 转 HTML |
| `htmlToMarkdown` | File | HTML 转 Markdown |
| `rightClickRestorer` | MousePointerClick | 右键菜单恢复工具 |
| `testDataGenerator` | FileSpreadsheet | 测试数据生成器 |
## 导出函数
src/lib/README.md
+32 -2
View File
@@ -4,9 +4,10 @@
## 文件说明
| 文件 | 用途 |
| ---------- | ------------------------------------ |
| 文件/目录 | 用途 |
| ------------- | -------------------------------------- |
| `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` 能展示该分类。
src/pages/README.md
+22 -9
View File
@@ -113,14 +113,6 @@ Base64 编解码工具，支持文本/文件/图片三种模式。
| `TextMode.tsx` | 文本模式 |
| `Base64ConverterSection.tsx` | 文件/图片通用转换区域 |
### MarkdownToHtml/
Markdown 转 HTML 工具，支持分栏/预览/源码三种视图模式。
### HtmlToMarkdown/
HTML 转 Markdown 工具，支持分栏/预览/Markdown 三种视图模式。
### RightClickRestorer/
右键菜单恢复工具，解除网站对右键的限制。
@@ -130,11 +122,32 @@ HTML 转 Markdown 工具，支持分栏/预览/Markdown 三种视图模式。
| `index.tsx` | 页面 UI |
| `useRightClickRestorer.ts` | 业务逻辑 Hook |
### TestDataGenerator/
测试数据生成器，支持可视化字段配置、规则复用、Web Worker 批量生成和 JSON/CSV 导出。
| 文件/目录 | 用途 |
| ---------------------------- | ------------------------------------------------- |
| `index.tsx` | 主页面，管理字段配置、规则标签页和生成结果 |
| `hooks/useGenerator.ts` | Worker 生命周期与消息通信，暴露生成/取消/清理操作 |
| `components/FieldList.tsx` | 字段列表、拖拽排序、虚拟滚动和规则保存入口 |
| `components/FieldEditor.tsx` | 字段名称、生成器、参数、必填/空值率/唯一性配置 |
| `components/RuleManager.tsx` | 规则搜索、加载、编辑、复制、删除、导入和导出 |
| `components/ExportPanel.tsx` | 生成结果复制和 JSON/CSV 下载 |
约束与注意事项：
- 字段数量最多 40 个（`FieldList.MAX_FIELDS`）。
- 生成数量为 1 ~ 100,000，预设值包含 50、100、1,000、5,000、10,000。
- 大批量生成通过 `src/workers/generator.worker.ts` 执行，避免阻塞 UI；Worker 每 1,000 条或结束时回传进度。
- 规则通过 `src/utils/ruleStorage.ts` 存入 `localStorage`，最多保存 20 条规则。
- 内置生成器位于 `src/lib/generators/`，按个人信息、业务数据、技术数据、基础类型分类。
## 新增页面
1. 在 `types/storage.d.ts` 添加 `PageType` 联合类型成员
2. 在 `config/features.tsx` 的 `FEATURES` 数组添加配置
3. 在 `pages/` 创建页面目录（遵循上述结构）
4. 在 `i18n/locales/{zh,en}/features.json` 添加翻译
4. 在 `public/_locales/zh_CN/messages.json` 添加 Chrome i18n 翻译
5. 如需新权限，更新 `wxt.config.ts`
6. 添加对应的单元测试
src/types/README.md
+11 -3
View File
@@ -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` 时，必须：
src/utils/README.md
+6 -5
View File
@@ -5,7 +5,7 @@
## 工具函数
| 文件 | 用途 |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| `chromeStorage.ts` | Chrome Storage API 封装：类型安全的 `StorageUtils` 类，提供 `get/set/remove` 方法 |
| `chromeTabs.ts` | Chrome Tabs API 封装：获取活动标签页、获取域名、在新标签页打开扩展页面 |
| `clipboard.ts` | 剪贴板操作：`copyTextToClipboard`（文本）、`copyImageToClipboard`（图片） |
@@ -16,27 +16,28 @@
| `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 插件，加载中文本地化 |
| `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`