LingandRX
8d36f21f1b
* docs: 添加组件文档注释和类型导入 refactor: 统一使用 SnackbarOptions 类型 style: 优化导入语句顺序和格式 * refactor: 简化假数据生成器中的faker导入和使用 Co-authored-by: Copilot <copilot@github.com> * feat(form-recognizer): 增强表单识别功能并优化UI交互 - 新增字段类型偏好设置功能，支持按域名保存字段类型 - 重构FieldList组件，改进字段选择和类型修改体验 - 添加字段定位闪烁功能，便于在页面上快速找到对应字段 - 优化表单填充逻辑，支持单个字段覆盖默认填充模式 - 移除独立的侧边栏页面，统一使用主页面组件 - 改进useStorageState钩子，增加加载状态管理和防抖处理 * refactor: 移除未使用的组件文件 * refactor(页面头部): 提取通用 PageHeader 组件并替换各页面头部实现 重构各页面头部为统一的 PageHeader 组件，提高代码复用性和维护性 * style(组件): 调整自动刷新开关和存储选项网格的样式 优化自动刷新开关的文本内边距，重构存储选项网格的布局结构，调整间距和边框样式 * style(ui): 调整时间戳页面和结果视图的样式 - 为时区选择器添加圆角 - 优化结果视图的布局和对齐方式 - 调整结果项的内边距和文本样式 * ci(workflow): 移除Firefox测试以简化CI流程 仅保留Chrome浏览器的构建步骤，减少CI运行时间和资源消耗 * refactor(qrcode): 重构二维码解析功能并提取为独立模块 * style(页面样式): 统一页面头部图标颜色并优化表单样式 更新各页面头部组件的图标颜色配置，移除冗余的表单标签属性，优化输入框样式和按钮悬停效果 * feat(formMapping): 添加表单映射功能 - 创建 FormMappingPage 页面组件 - 实现表单扫描器 scanner.ts - 实现高亮器 highlighter.ts - 更新路由配置 routes.ts - 更新内容脚本 content.ts - 更新类型定义 storage.d.ts - 添加 formMappingPageStyles 样式配置 * feat(表单映射): 添加配置导出功能及状态提示 添加配置导出为JSON文件的功能，包含导出按钮和错误处理。新增Snackbar组件用于显示导出成功和错误状态。优化页面布局结构，将状态提示移至全局容器外。 * feat(表单填充): 新增智能表单填充功能 添加智能表单填充功能，包括： 1. 新增表单填充页面和路由配置 2. 实现模糊匹配引擎和智能注入引擎 3. 添加Mock数据生成器和视觉反馈渲染器 4. 扩展消息接口支持填充操作 * ci: 精简触发CI的工作流分支 移除对develop分支及其变体的触发，仅保留main分支的触发 * test: 更新路由测试以匹配新增的路由数量 * test: 将测试文件中的描述和断言翻译为中文 * test(PageHeader): 添加组件测试用例验证渲染逻辑和样式 * refactor(theme): 重构主题样式并优化仪表盘卡片组件 将页面样式配置集中管理，移除各页面中硬编码的背景色 新增 DashboardCard 组件封装通用卡片逻辑 添加 dashboardCards 配置文件统一管理卡片数据 * refactor(Button): 统一按钮样式并移除重复样式定义 将按钮样式统一封装到 Button 组件中，移除各页面重复的样式定义 更新组件文档说明，提供更清晰的用法示例 * docs: 更新 README 文件中的目录结构说明 添加新组件和配置文件的说明，保持文档与代码同步 * refactor: 优化代码类型声明和UI布局 修复类型声明从any改为never以提高类型安全性 调整TimestampPage页面布局间距 移除DashboardPage中不必要的实时时钟状态 更新ESLint配置以使用推荐配置 添加选项页面打开的错误处理 * refactor(消息通信): 使用 @webext-core/messaging 重构消息处理逻辑 将原有的 chrome.runtime.onMessage 和 chrome.tabs.sendMessage 替换为类型安全的 @webext-core/messaging 实现 添加 ProtocolMap 类型定义确保消息类型安全 更新相关页面和后台脚本使用新的消息通信方式 * fix: 修复依赖项缺失导致的潜在问题 修复 useStorageState 中缺少 defaultValue 依赖的问题 重构 RouterProvider 的初始化逻辑，使用 useCallback 优化性能 * refactor: 重构表单识别和消息处理逻辑 将表单映射UI逻辑提取到独立文件 将消息处理器提取到独立文件 将表单识别页面逻辑提取到自定义hook 优化代码结构和可维护性 * feat(侧边栏): 添加侧边栏状态变化通知功能 - 在消息类型中新增侧边栏状态变化枚举和字段 - 侧边栏打开和关闭时发送状态通知 - 替换轮询检查方式为消息监听机制 * refactor: 优化高亮组件渲染逻辑并添加防抖处理 重构高亮组件渲染逻辑，使用 requestAnimationFrame 进行节流优化 在 useStorageCleaner 中添加防抖处理以避免频繁加载 * refactor: 统一组件导出方式为默认导出 * refactor: 重构样式系统并迁移至 MUI 主题 删除冗余的 CSS 文件，统一使用 MUI 主题管理样式 新增 useActiveTabDomain 和 useSidePanelState 自定义 Hook 优化各入口点的主题集成和布局处理 * docs: 更新项目文档以反映新增功能和技术栈细节 更新 AGENTS.md 文档，详细描述新增的功能模块（存储管理、URL 管理、二维码生成、表单工具套件等）和更新的技术栈信息 * feat: 添加错误边界组件以捕获子组件错误 在 popup、sidepanel 和 options 入口点添加 ErrorBoundary 组件，用于捕获并处理子组件中的 JavaScript 错误。当错误发生时，显示友好的错误界面并提供刷新功能。 * refactor(ui): 使用全局 snackbar 替换本地通知组件 重构表单页面中的通知系统，移除本地 Snackbar 和 Alert 组件，改用全局 GlobalSnackbar 组件统一管理通知 标准化主题配置中的 CSS 属性命名，移除带前缀的样式属性 * refactor(snackbar): 重构全局消息提示为 SnackbarProvider 组件 将原本分散在各页面的 GlobalSnackbar 组件重构为集中管理的 SnackbarProvider，通过 Context 提供统一的消息提示功能。主要变更包括： 1. 创建新的 SnackbarProvider 组件作为全局消息提示容器 2. 提供 useSnackbar hook 供子组件调用 3. 移除各页面中独立的 GlobalSnackbar 实例 4. 在 App 根组件中统一集成 SnackbarProvider 5. 优化消息提示样式和交互行为 * refactor(Snackbar): 重构消息提示组件并优化样式 重构 Snackbar 组件，将状态管理逻辑提取到 GlobalSnackbar 中复用 优化消息提示样式，调整阴影效果和最小尺寸 统一各页面使用 Snackbar 的方式，移除冗余配置 * refactor: 重构路由和功能配置系统 - 将路由配置和仪表盘卡片配置合并为统一的 features 配置 - 重构 RouterProvider 增加数据校验和本地快照功能 - 优化表单字段识别和填充逻辑，提取公共方法 - 更新相关组件和文档以适配新的配置系统 - 删除废弃的 dashboardCards 和 routes 配置文件
259 lines
6.9 KiB
Markdown
259 lines
6.9 KiB
Markdown
# Testing Tools Browser Extension
|
||
|
||
这是一个基于 WXT 框架的浏览器扩展项目，提供实用的测试工具功能。
|
||
|
||
## 项目概述
|
||
|
||
Testing Tools 是一个轻量级的浏览器扩展，提供多种实用的测试工具功能。项目采用现代化的技术栈，包括 React 19、TypeScript 和 Material UI，并利用 WXT 框架简化浏览器扩展的开发流程。
|
||
|
||
## 功能特性
|
||
|
||
### Dashboard 首页
|
||
|
||
- 卡片式工具展示
|
||
- 支持自定义工具排序和可见性
|
||
- 实时数据预览（时间戳等）
|
||
|
||
### 时间戳转换工具
|
||
|
||
- 实时显示当前时间戳（毫秒/秒可切换）
|
||
- 日期与时间戳之间的双向转换
|
||
- 支持多个时区（亚洲/上海、美洲/纽约、欧洲/伦敦）
|
||
- 一键复制转换结果
|
||
- 输入验证和错误提示
|
||
|
||
### 存储清理工具
|
||
|
||
- 自动读取当前域名
|
||
- 支持清理多种存储类型：
|
||
- localStorage
|
||
- sessionStorage
|
||
- IndexedDB
|
||
- Cookies
|
||
- Cache Storage
|
||
- Service Workers
|
||
- 可选择的清理类型（默认全选）
|
||
- 确认对话框防止误操作
|
||
- 清理结果统计
|
||
- 自动刷新页面选项
|
||
|
||
### URL 工具
|
||
|
||
- 保存常用 URL 列表
|
||
- 快速打开保存的 URL
|
||
- 支持 URL 验证和安全检查
|
||
- 内置 URL 查看器（iframe 沙箱模式）
|
||
|
||
### 二维码工具
|
||
|
||
- URL 转二维码（生成器）
|
||
- 二维码转 URL（解析器）
|
||
- 支持上传二维码图片解析
|
||
- 生成的二维码可下载
|
||
- 一键复制转换结果
|
||
- 卡片式布局，节省空间
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: WXT (Web Extension Toolkit)
|
||
- **前端**: React 19 + TypeScript
|
||
- **UI 库**: Material UI
|
||
- **日期处理**: dayjs (含 UTC 和时区插件)
|
||
- **通信**: @webext-core/messaging
|
||
- **存储**: Chrome Storage API (类型安全封装)
|
||
- **二维码**: qrcode (生成) + jsqr (解析)
|
||
- **测试**: Vitest + Testing Library
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── components/ # 可复用 UI 组件
|
||
│ ├── Button.tsx
|
||
│ ├── CopyButton.tsx
|
||
│ ├── DashboardCard.tsx # 仪表盘卡片组件（React.memo 优化）
|
||
│ ├── GlobalSnackbar.tsx
|
||
│ ├── PageHeader.tsx # 页面标题栏组件
|
||
│ ├── RouterContainer.tsx
|
||
│ ├── StorageCleanerConfirm.tsx
|
||
│ ├── ToolCard.tsx
|
||
│ └── TopBar.tsx
|
||
├── config/ # 配置文件
|
||
│ ├── dashboardCards.tsx # 仪表盘卡片配置数据
|
||
│ └── routes.ts # 页面路由定义
|
||
├── entrypoints/ # 浏览器扩展入口点
|
||
│ ├── popup/ # 扩展弹窗界面
|
||
│ │ ├── App.tsx
|
||
│ │ ├── main.tsx
|
||
│ │ └── pages/ # 页面组件
|
||
│ │ ├── DashboardPage.tsx
|
||
│ │ ├── OpenUrlPage.tsx
|
||
│ │ ├── OpenUrlViewerPage.tsx
|
||
│ │ ├── QrCodePage.tsx
|
||
│ │ ├── StorageCleanerPage.tsx
|
||
│ │ └── TimestampPage.tsx
|
||
│ ├── options/ # 选项页面
|
||
│ ├── sidepanel/ # 侧边栏
|
||
│ ├── background.ts # 后台脚本
|
||
│ └── content.ts # 内容脚本
|
||
├── providers/ # React Context providers
|
||
│ └── RouterProvider.tsx # 路由状态管理
|
||
├── types/ # TypeScript 类型定义
|
||
│ └── storage.d.ts
|
||
├── utils/ # 工具函数
|
||
│ ├── chromeStorage.ts
|
||
│ ├── clipboard.ts
|
||
│ ├── dayjs.ts
|
||
│ ├── messages.tsx
|
||
│ └── storageCleaner.ts
|
||
├── public/ # 静态资源
|
||
├── wxt.config.ts # WXT 配置文件
|
||
├── package.json
|
||
└── README.md
|
||
```
|
||
|
||
## 路由系统
|
||
|
||
项目实现了灵活的路由系统，支持：
|
||
|
||
- **页面导航**: 在不同工具页面之间切换
|
||
- **路由同步**: 通过 Chrome Storage 同步路由状态
|
||
- **可见性控制**: 可配置显示哪些页面
|
||
- **页面排序**: 自定义工具卡片的显示顺序
|
||
|
||
### 页面类型 (PageType)
|
||
|
||
| 页面 | 说明 | 默认可见 |
|
||
| ---------------- | ---------- | -------- |
|
||
| `dashboard` | 首页 | ✓ |
|
||
| `timestamp` | 时间戳转换 | ✓ |
|
||
| `storageCleaner` | 存储清理 | ✓ |
|
||
| `openUrl` | URL 工具 | ✓ |
|
||
| `qrCode` | 二维码工具 | ✓ |
|
||
| `openUrlViewer` | URL 查看器 | ✗ |
|
||
|
||
## 扩展入口点
|
||
|
||
| 入口点 | 说明 |
|
||
| -------------- | ------------------------ |
|
||
| **popup** | 点击扩展图标弹出的界面 |
|
||
| **options** | 扩展选项页面 |
|
||
| **sidepanel** | 浏览器侧边栏 |
|
||
| **background** | 后台脚本（生命周期管理） |
|
||
| **content** | 内容脚本（注入到网页） |
|
||
|
||
## 开发环境要求
|
||
|
||
- Node.js >= 18
|
||
- npm 或 yarn
|
||
|
||
## 安装与运行
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 2. 开发模式
|
||
|
||
```bash
|
||
# Chrome 浏览器
|
||
npm run dev
|
||
|
||
# Firefox 浏览器
|
||
npm run dev:firefox
|
||
```
|
||
|
||
### 3. 构建生产版本
|
||
|
||
```bash
|
||
# Chrome 浏览器
|
||
npm run build
|
||
|
||
# Firefox 浏览器
|
||
npm run build:firefox
|
||
```
|
||
|
||
### 4. 打包分发
|
||
|
||
```bash
|
||
# Chrome 浏览器
|
||
npm run zip
|
||
|
||
# Firefox 浏览器
|
||
npm run zip:firefox
|
||
```
|
||
|
||
### 5. 代码质量
|
||
|
||
```bash
|
||
npm run compile # TypeScript 类型检查
|
||
npm run lint # ESLint 代码检查
|
||
```
|
||
|
||
### 6. 测试
|
||
|
||
```bash
|
||
npm run test # 运行所有测试
|
||
npm run test:watch # 运行测试并监听文件变化
|
||
npm run test:coverage # 运行测试并生成覆盖率报告
|
||
```
|
||
|
||
## 持续集成与发布
|
||
|
||
项目使用 GitHub Actions 实现自动化 CI/CD，无需手动操作。
|
||
|
||
### CI — 持续集成
|
||
|
||
在以下场景自动触发：
|
||
|
||
- push 到 `main` / `develop` / `develop-*` 分支
|
||
- 所有 PR（合并到 `main` 或 `develop`）
|
||
|
||
自动执行：ESLint 检查 → TypeScript 类型检查 → 单元测试 → Chrome & Firefox 构建验证。
|
||
|
||
### 发布版本
|
||
|
||
只需推送符合 `v*` 格式的 Git tag，即可自动完成全量 CI 检查、打包并发布到 GitHub Release：
|
||
|
||
```bash
|
||
git tag v1.0.0
|
||
git push origin v1.0.0
|
||
```
|
||
|
||
> 含 `-` 的 tag（如 `v1.0.0-beta.1`）会自动标记为预发布版本（prerelease）。
|
||
|
||
工作流文件位于 `.github/workflows/`：
|
||
|
||
- `ci.yml` — 持续集成
|
||
- `release.yml` — 自动发布
|
||
|
||
## 权限说明
|
||
|
||
扩展请求以下权限：
|
||
|
||
- `storage` 和 `unlimitedStorage` - 本地数据存储
|
||
- `clipboardWrite` - 剪贴板写入（复制功能）
|
||
- `activeTab`, `scripting`, `tabs` - 当前标签页控制和脚本注入
|
||
- `cookies` - Cookie 访问
|
||
- `sidePanel` - 侧边栏支持
|
||
- `<all_urls>` - 访问所有网站内容（内容脚本注入）
|
||
|
||
## 主要依赖
|
||
|
||
- `react`, `react-dom` - 前端框架
|
||
- `@mui/material` - UI 组件库
|
||
- `dayjs` - 日期处理
|
||
- `@webext-core/messaging` - 扩展消息通信
|
||
- `vitest` - 测试框架
|
||
- `@testing-library/react` - React 组件测试
|
||
|
||
## 浏览器兼容性
|
||
|
||
- Chrome (推荐)
|
||
- Firefox
|
||
|
||
## 许可证
|
||
|
||
此项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。
|