一个专为油猴(Tampermonkey)插件开发设计的可扩展框架，基于 TypeScript 和事件驱动架构，旨在简化事件监听和插件交互的开发流程。
本项目是一个油猴(Tampermonkey)插件开发框架，为开发者提供了一个可横向扩展的插件开发平台。框架专注于简化事件监听和插件交互的开发流程，让开发者能够快速构建功能丰富的用户脚本。
- 🔧 开发效率提升：提供标准化的插件开发模板和工具链
- 🎯 事件驱动架构：基于高性能事件总线，支持复杂的事件处理逻辑
- 🔌 模块化设计：插件间松耦合，支持独立开发和部署
- 📦 一键构建：自动生成符合 Tampermonkey 规范的用户脚本
- 💾 数据持久化：内置 IndexedDB 支持，数据安全可靠
框架提供了完整的事件总线系统，包含以下四大核心检测功能：
- 基于 MutationObserver：高性能的 DOM 变化监听
- 精确变更追踪：支持节点增删、属性修改、文本变化等
- 选择器过滤：可指定监听特定元素的变化
- 批量处理：优化性能，避免频繁触发
- 全局键盘监听：捕获所有键盘事件
- 快捷键绑定：支持组合键和自定义快捷键
- 按键状态管理：实时跟踪修饰键状态
- 事件优先级：支持事件拦截和短路机制
- 完整鼠标事件：点击、移动、滚轮等全覆盖
- 精确坐标追踪：提供详细的位置信息
- 按钮状态检测：区分左键、右键、中键操作
- 拖拽支持：内置拖拽事件处理
- 请求拦截：支持 fetch 和 XMLHttpRequest 拦截
- 响应解析：自动解析 JSON 响应内容
- 性能统计：记录请求时间和状态信息
- 错误处理：完善的网络错误捕获机制
开发者可以通过简单的 API 便捷订阅所需的事件类型：
// 订阅DOM变化事件
on(EventType.DOM_MUTATION, (eventData) => {
console.log("DOM发生变化:", eventData);
});
// 订阅键盘事件
on(EventType.KEYDOWN, (eventData) => {
console.log("按键按下:", eventData);
});
// 订阅网络请求事件
on(EventType.NETWORK_RESPONSE, (eventData) => {
console.log("网络响应:", eventData);
});plugin 目录包含四个演示插件，分别展示不同事件总线的调用方式，可作为开发参考模板：
- 功能特性：监听 DOM 变化并提供 DOM 操作工具
- 应用场景：页面元素监控、动态内容检测、UI 自动化
- 核心功能：
- DOM 变更统计和记录
- 元素追踪和管理
- 变化类型分析
- 功能特性：监听键盘事件并管理快捷键
- 应用场景：快捷键绑定、输入监控、游戏辅助
- 核心功能：
- 按键统计和历史记录
- 快捷键组合检测
- 修饰键状态管理
- 功能特性：监听鼠标左键按下事件
- 应用场景：点击统计、用户行为分析、交互优化
- 核心功能：
- 鼠标点击计数
- 点击位置记录
- 点击时间统计
- 功能特性：网络响应体监听器，演示如何获取网络响应的 JSON 内容
- 应用场景：API 调试、数据抓取、网络监控
- 核心功能：
- 网络请求拦截和分析
- JSON 响应自动解析
- 用户数据提取和缓存
- 网络性能统计
- Node.js >= 16.0.0
- npm 或 pnpm 包管理器
- 现代浏览器支持（Chrome 88+, Firefox 78+, Safari 14+）
# 使用 npm
npm install
# 或使用 pnpm（推荐）
pnpm install# 启动监听模式，文件变化时自动重新构建
npm run watch# 构建生产版本
npm run build
# 构建并生成油猴脚本
npm run postbuild构建完成后，在 dist/ 目录下会生成：
bundle.js- 标准 JavaScript 模块bundle.user.js- 油猴脚本版本（包含用户脚本头信息）
pluginFramework/
├── src/ # 源代码目录
│ ├── index.ts # 框架入口文件
│ ├── pluginEntry.ts # 插件入口管理
│ │
│ ├── plugin/ # 插件实现目录
│ │ ├── SampleDomPlugin.ts # DOM变化监听插件
│ │ ├── SampleKeyboardPlugin.ts # 键盘事件处理插件
│ │ ├── SampleMousePlugin.ts # 鼠标事件处理插件
│ │ └── SampleNetworkPlugin.ts # 网络监听示例插件
│ │
│ ├── composable/ # 插件类型定义目录
│ │ ├── SampleDomPlugin/ # DOM插件类型定义
│ │ ├── SampleKeyboardPlugin/ # 键盘插件类型定义
│ │ ├── SampleMousePlugin/ # 鼠标插件类型定义
│ │ └── SampleNetworkPlugin/ # 网络插件类型定义
│ │
│ └── util/ # 核心工具类目录
│ ├── EventBus.ts # 事件总线核心实现
│ ├── EventEmitter.ts # 事件发射器
│ ├── EventTypes.ts # 事件类型定义
│ ├── EventDomObserver.ts # DOM变化观察者
│ ├── EventKeyboardListener.ts # 键盘事件监听器
│ ├── EventMouseListener.ts # 鼠标事件监听器
│ ├── EventNetworkListener.ts # 网络请求监听器
│ ├── PluginBase.ts # 插件基类定义
│ ├── installedPlugins.ts # 插件实例管理
│ ├── db.ts # IndexedDB数据库操作
│ └── logger.ts # 日志系统
│
├── dist/ # 构建输出目录
├── package.json # 项目配置文件
├── tsconfig.json # TypeScript配置
├── rollup.config.js # Rollup构建配置
├── postBuildConfig.mjs # 油猴脚本配置
└── postbuild.mjs # 构建后处理脚本
┌─────────────────────────────────────────────────────────────┐
│ Tampermonkey Plugin Framework │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ 插件层 │ │ 事件总线 │ │ 监听器层 │ │
│ │ │◄──►│ │◄──►│ │ │
│ │ PluginBase │ │ EventBus │ │ EventEmitter │ │
│ │ 子类 │ │ │ │ 各种监听器 │ │
│ └─────────────┘ └──────────────┘ └─────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ │
│ │ 数据持久化 │ │ 日志系统 │ │ 构建系统 │ │
│ │ │ │ │ │ │ │
│ │ IndexedDB │ │ Logger │ │ Rollup │ │
│ │ 存储 │ │ │ │ + PostBuild │ │
│ └─────────────┘ └──────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
详细的 API 文档请参考项目中的注释说明。每个核心模块都包含完整的 TypeScript 类型定义和 JSDoc 注释：
- 事件总线 API：
- 插件基类 API：
- 事件类型定义：
- 数据库操作 API：
请遵循现有代码风格进行开发：
- 使用 TypeScript 进行开发，确保类型安全
- 遵循 驼峰命名法 和现有的命名约定
- 为新功能添加适当的 类型定义 和 JSDoc 注释
- 使用框架提供的 日志系统 进行调试和错误记录
- 插件开发请继承 PluginBase 基类
- 事件监听请使用 EventBus 提供的 API
- 创建插件文件：在
src/plugin/目录下创建新的插件文件 - 继承基类：继承
PluginBase并实现必要的方法 - 定义类型：在
src/composable/目录下创建对应的类型定义 - 注册插件：在插件入口文件中注册新插件
油猴脚本的配置信息在 文件中定义，包括：
- 脚本名称、版本、描述
- 页面匹配规则
- 权限设置
- 外部依赖配置
我们欢迎所有形式的贡献！贡献指南详见 CONTRIBUTING.md（注：该文件需要创建）。
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
- 使用 TypeScript 进行开发
- 遵循现有的代码风格和命名约定
- 为新功能添加适当的类型定义
- 在插件中添加函数级注释
- 确保代码通过 TypeScript 编译检查
如果您在使用过程中遇到问题或有改进建议，请：
- 查看 Issues 页面寻找相似问题
- 创建新的 Issue 详细描述问题或建议
- 参与讨论帮助改进框架
Q: 如何调试插件？ A: 使用浏览器开发者工具，框架会在控制台输出详细的调试信息。
Q: 插件数据丢失怎么办？
A: 检查 IndexedDB 存储，确保调用了 saveData() 方法保存数据。
Q: 如何优化事件监听器性能？ A: 合理设置优先级，及时清理不需要的监听器，避免在高频事件中执行重计算。
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
Happy Coding! 🎉
基于事件驱动架构，构建下一代油猴插件应用