docs(工程文档): 同步当前架构说明
Co-authored-by: LingandRX <LingandRX@users.noreply.github.com>
This commit is contained in:
Cursor Agent
@@ -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 | 测试数据生成器 |
|
||||
|
||||
## 导出函数
|
||||
|
||||
|
||||
+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` 能展示该分类。
|
||||
|
||||
+22
-9
@@ -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. 添加对应的单元测试
|
||||
|
||||
+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` 时，必须：
|
||||
|
||||
+5
-4
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user