Files

T

LingandRX 8d36f21f1b Refactor and enhance form recognition, mapping, and UI components (#18 )

* 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 配置文件

2026-05-01 18:00:06 +08:00

13 KiB

Raw Blame History

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

项目概述

这是一个基于 WXT 框架的浏览器扩展项目，提供多种测试工具功能，包括时间戳转换、存储管理、URL 管理、二维码生成、表单识别与填充等。

核心命令

开发相关

npm run dev - 启动 Chrome 浏览器的开发模式
npm run dev:firefox - 启动 Firefox 浏览器的开发模式
npm run build - 构建 Chrome 浏览器的生产版本
npm run build:firefox - 构建 Firefox 浏览器的生产版本
npm run zip - 打包 Chrome 扩展
npm run zip:firefox - 打包 Firefox 扩展
npm run compile - TypeScript 类型检查（不生成文件）
npm run lint - 运行 ESLint 检查

测试相关

npm run test - 运行所有测试（单次执行）
npm run test:watch - 运行测试并监听文件变化
npm run test:coverage - 运行测试并生成覆盖率报告

运行单个测试文件：

npx vitest run components/__tests__/CopyButton.test.tsx

测试技术栈：

Vitest v2 - 测试框架
@testing-library/react v16 - React 组件测试
@testing-library/user-event v14 - 用户交互模拟
jsdom v25 - 浏览器环境模拟

依赖与准备

npm install - 安装依赖
postinstall 会自动运行 wxt prepare 准备开发环境
prepare 钩子会初始化 Husky Git 钩子

项目架构

技术栈

框架: WXT v0.20.6 (Web Extension Toolkit) - 浏览器扩展开发框架
前端: React 19 + TypeScript 5
UI 库: Material UI (MUI) v7 + Emotion
状态管理: React Hooks + 自定义 Hooks
路由: 自定义路由系统（支持 popup/sidepanel/detached 三种模式）
测试: Vitest + Testing Library
代码质量: ESLint v9 + Prettier + Husky + lint-staged

目录结构

├── components/                    # 可复用 UI 组件
│   ├── __tests__/                 # 组件测试文件
│   ├── Button.tsx                 # 按钮组件
│   ├── CopyButton.tsx             # 复制按钮组件
│   ├── DashboardCard.tsx          # 仪表盘卡片组件
│   ├── FieldList.tsx              # 字段列表组件
│   ├── GlobalSnackbar.tsx         # 全局提示消息组件
│   ├── PageHeader.tsx             # 页面头部组件
│   ├── QrCodeToUrlSection.tsx     # 二维码解析为 URL 组件
│   ├── QrCodeUploader.tsx         # 二维码上传组件
│   ├── RouterContainer.tsx        # 路由容器组件
│   ├── StorageCleanerConfirm.tsx  # 存储清理确认组件
│   ├── ToolCard.tsx               # 工具卡片组件
│   ├── TopBar.tsx                 # 顶部导航栏组件
│   ├── UrlEntryForm.tsx           # URL 录入表单组件
│   ├── UrlEntryItem.tsx           # URL 条目组件
│   ├── UrlEntryList.tsx           # URL 列表组件
│   └── UrlToQrCodeSection.tsx     # URL 转二维码组件
├── config/                        # 配置文件
│   ├── __tests__/                 # 配置测试文件
│   ├── dashboardCards.tsx         # 仪表盘卡片配置
│   ├── pageTheme.ts               # 页面主题配置
│   ├── routes.ts                  # 路由配置
│   └── theme.ts                   # 全局主题配置
├── entrypoints/                   # 浏览器扩展入口点
│   ├── background.ts              # 后台脚本（主进程）
│   ├── content.ts                 # 内容脚本（注入到页面）
│   ├── content/
│   │   └── messageHandler.ts      # 消息处理器
│   ├── options/                   # 选项页面
│   │   ├── App.tsx                # 选项应用
│   │   ├── index.html             # 选项页面 HTML
│   │   └── main.tsx               # 选项页面入口
│   ├── popup/                     # 扩展弹窗界面
│   │   ├── App.tsx                # 弹窗主应用
│   │   ├── main.tsx               # 弹窗入口
│   │   ├── index.html             # 弹窗 HTML
│   │   ├── pages/                 # 弹窗页面
│   │   │   ├── components/        # 页面级组件
│   │   │   │   ├── AutoRefreshToggle.tsx    # 自动刷新开关
│   │   │   │   ├── CleaningResult.tsx       # 清理结果展示
│   │   │   │   ├── DomainHeader.tsx         # 域名头部
│   │   │   │   ├── ErrorDisplay.tsx         # 错误显示
│   │   │   │   ├── LiveClock.tsx            # 实时时钟
│   │   │   │   ├── OptionItem.tsx           # 选项条目
│   │   │   │   ├── ResultView.tsx           # 结果视图
│   │   │   │   └── StorageOptionsGrid.tsx   # 存储选项网格
│   │   │   ├── hooks/             # 自定义 Hooks
│   │   │   │   ├── useActiveTabDomain.ts    # 当前标签页域名
│   │   │   │   ├── useFormRecognizer.ts     # 表单识别
│   │   │   │   ├── useSidePanelState.ts     # 侧边栏状态
│   │   │   │   └── useTimestampConverter.ts # 时间戳转换
│   │   │   ├── DashboardPage.tsx            # 仪表盘页面
│   │   │   ├── FormFillPage.tsx             # 表单填充页面
│   │   │   ├── FormMappingPage.tsx          # 表单映射页面
│   │   │   ├── FormRecognizerPage.tsx          # 表单识别页面
│   │   │   ├── OpenUrlPage.tsx              # 打开 URL 页面
│   │   │   ├── OpenUrlViewerPage.tsx        # URL 查看页面
│   │   │   ├── QrCodePage.tsx               # 二维码页面
│   │   │   ├── StorageCleanerPage.tsx       # 存储清理页面
│   │   │   ├── TimestampPage.tsx            # 时间戳页面
│   │   │   └── useStorageCleaner.ts         # 存储清理 Hook
│   └── sidepanel/                 # 侧边栏界面
│       ├── App.tsx                # 侧边栏应用
│       ├── index.html             # 侧边栏 HTML
│       └── main.tsx               # 侧边栏入口
├── providers/                     # React Providers
│   └── RouterProvider.tsx         # 路由 Provider
├── utils/                         # 工具函数
│   ├── __tests__/                 # 工具测试文件
│   ├── formMapping/               # 表单映射工具
│   │   ├── highlighter.ts         # 表单高亮器
│   │   ├── scanner.ts             # 表单扫描器
│   │   ├── smartInjector.ts       # 智能注入器
│   │   └── ui.ts                  # UI 工具
│   ├── chromeStorage.ts           # Chrome 存储工具
│   ├── chromeTabs.ts              # Chrome 标签页工具
│   ├── clipboard.ts               # 剪贴板工具
│   ├── dataTemplate.ts            # 数据模板
│   ├── dataValidator.ts           # 数据验证器
│   ├── dayjs.ts                   # 日期处理工具
│   ├── dummyDataGenerator.ts      # 虚拟数据生成器（基于 Faker）
│   ├── messages.ts                # 消息通信工具
│   ├── qrCodeParser.ts            # 二维码解析器
│   ├── storageCleaner.ts          # 存储清理工具
│   ├── useStorageState.ts         # 存储状态 Hook
│   └── useUrlPreferences.ts       # URL 偏好设置 Hook
├── types/                         # 类型定义
│   └── storage.d.ts               # 存储相关类型
├── docs/                          # 文档
│   └── plans/                     # 计划文档
├── public/                        # 静态资源
│   └── icon/                      # 扩展图标
└── .github/                       # GitHub 配置
    └── workflows/                 # CI/CD 工作流
        ├── ci.yml                 # 持续集成
        └── release.yml            # 发布流程

核心功能模块

1. 时间戳转换工具

位置: entrypoints/popup/pages/TimestampPage.tsx
Hook: entrypoints/popup/pages/hooks/useTimestampConverter.ts
依赖: dayjs 库进行日期处理
功能: 支持日期与时间戳的双向转换，支持多种格式，实时时钟显示

2. 存储清理工具

位置: entrypoints/popup/pages/StorageCleanerPage.tsx
Hook: entrypoints/popup/pages/useStorageCleaner.ts
工具: utils/storageCleaner.ts
功能: 清理缓存、Cookies、本地存储，支持按域名筛选，自动刷新功能

3. URL 管理工具

打开 URL: entrypoints/popup/pages/OpenUrlPage.tsx
查看 URL: entrypoints/popup/pages/OpenUrlViewerPage.tsx
组件: components/UrlEntryForm.tsx, components/UrlEntryList.tsx
功能: 批量打开多个 URL，URL 列表管理

4. 二维码工具

位置: entrypoints/popup/pages/QrCodePage.tsx
组件: components/QrCodeUploader.tsx, components/QrCodeToUrlSection.tsx, components/UrlToQrCodeSection.tsx
工具: utils/qrCodeParser.ts
依赖: qrcode, jsqr 库
功能: URL 转二维码生成，二维码图片解析为 URL

5. 表单工具套件

表单识别 (Form Recognizer)

位置: entrypoints/popup/pages/FormRecognizerPage.tsx
Hook: entrypoints/popup/pages/hooks/useFormRecognizer.ts
功能: 智能识别页面表单指纹

表单映射 (Form Mapping)

位置: entrypoints/popup/pages/FormMappingPage.tsx
工具: utils/formMapping/ 目录
- scanner.ts - 表单扫描器
- highlighter.ts - 表单高亮器
- smartInjector.ts - 智能注入器
- ui.ts - UI 工具
功能: 表单指纹识别与自定义映射规则配置

表单填充 (Form Fill)

位置: entrypoints/popup/pages/FormFillPage.tsx
工具: utils/dummyDataGenerator.ts (基于 @faker-js/faker)
功能: 根据表单指纹智能填充表单数据

6. 仪表盘系统

位置: entrypoints/popup/pages/DashboardPage.tsx
配置: config/features.tsx
组件: components/DashboardCard.tsx, components/ToolCard.tsx
功能: 统一工具入口，可自定义显示的工具卡片

7. 多模式显示系统

支持三种显示模式:
- popup - 扩展弹窗（点击图标显示）
- sidepanel - 浏览器侧边栏
- detached - 独立窗口模式
路由配置: config/features.tsx
路由容器: components/RouterContainer.tsx
Provider: providers/RouterProvider.tsx

8. 通信系统

位置: utils/messages.ts
机制: 使用 @webext-core/messaging 库实现
内容脚本消息处理: entrypoints/content/messageHandler.ts
通信通道: 后台脚本 ↔ 内容脚本 ↔ 弹窗/侧边栏

9. 数据存储

Chrome Storage API: utils/chromeStorage.ts
存储状态 Hook: utils/useStorageState.ts
URL 偏好设置: utils/useUrlPreferences.ts
类型定义: types/storage.d.ts

关键配置文件

wxt.config.ts

配置 WXT 框架参数
启用 React 模块
配置浏览器扩展权限（storage, unlimitedStorage, clipboardWrite, activeTab, scripting, tabs, cookies, sidePanel）
Vite 构建配置（使用 Terser 压缩，强制 ASCII 编码）
配置侧边栏和选项页面

manifest 权限

permissions: [
  'storage',           // 存储权限
  'unlimitedStorage',  // 无限制存储
  'clipboardWrite',    // 剪贴板写入
  'activeTab',         // 当前标签页
  'scripting',         // 脚本注入
  'tabs',              // 标签页管理
  'cookies',           // Cookies 管理
  'sidePanel',         // 侧边栏
],
host_permissions:['<all_urls>']  // 访问所有网站

CI/CD 配置

.github/workflows/ci.yml - 持续集成工作流
.github/workflows/release.yml - 发布工作流

开发注意事项

扩展入口点

后台脚本: entrypoints/background.ts - 处理扩展生命周期和后台任务
内容脚本: entrypoints/content.ts - 注入到网页中，处理 DOM 交互
弹窗: entrypoints/popup/main.tsx - 用户点击扩展图标时显示
侧边栏: entrypoints/sidepanel/main.tsx - 浏览器侧边栏界面
选项页面: entrypoints/options/main.tsx - 扩展设置页面

路由系统

使用自定义路由系统，支持多种显示模式
路由配置在 config/features.tsx
通过 getEntryPointType() 判断当前入口点类型
支持页面可见性配置（defaultVisible）

浏览器兼容性

支持 Chrome 和 Firefox 浏览器
使用 WXT 框架抽象浏览器差异
使用 @types/chrome 和 @types/webextension-polyfill 提供类型支持

代码质量

使用 ESLint v9 进行代码检查（基于 typescript-eslint）
Prettier 进行代码格式化
Husky v9 用于 Git 钩子管理
Lint-staged 确保暂存文件符合规范
GitHub Actions CI/CD 自动化测试和构建

测试策略

组件测试: components/__tests__/ 目录
工具函数测试: utils/__tests__/ 目录
配置测试: config/__tests__/ 目录
使用 Vitest 作为测试框架
使用 Testing Library 进行 React 组件测试

13 KiB Raw Blame History Unescape Escape