HS I18n Chrome 扩展

HanSummer_Xiahl
78 阅读8分钟

HS I18n Chrome 扩展 - 项目总结

项目地址

📋 项目概述

HS I18n 是一个功能完整的 Chrome 浏览器扩展，提供网页自动翻译和国际化功能。基于 Manifest V3 标准开发，支持多语言翻译、侧边栏设置、拖拽移动等特性。

🎯 核心功能

1. 自动翻译

  • 集成 translate.js 翻译引擎
  • 支持多种语言互译
  • 自动检测页面语言
  • 实时翻译页面内容

2. 用户界面

  • Popup 弹出窗口：快速操作和状态显示
  • 侧边栏设置：丰富的配置选项和实时状态
  • 选项页面：完整的设置管理

3. 交互功能

  • 可拖拽的语言选择下拉框
  • 固定在页面上的浮动控件
  • 最高层级显示，不被遮挡

4. 配置管理

  • 自动初始化默认配置
  • 配置持久化存储
  • 多设备同步（chrome.storage.sync）

📁 项目结构

hs-i18n/
├── manifest.json              # 扩展清单文件（Manifest V3）
├── background.js              # 后台服务脚本（Service Worker）
├── content.js                 # 内容脚本（注入到网页）
├── popup.html/js/css          # 弹出窗口
├── sidepanel.html/js/css      # 侧边栏设置
├── options.html/js/css        # 选项页面
├── styles.css                 # 注入页面的样式
├── utils/
│   ├── translate.js           # 翻译引擎（第三方库）
│   ├── translate-init.js     # 翻译初始化脚本
│   └── translate-drag.js     # 拖拽功能脚本
├── icons/                     # 扩展图标
│   ├── icon16.png
│   ├── icon48.png
│   └── icon128.png
└── 文档/
    ├── README.md             # 项目说明
    ├── ARCHITECTURE.md       # 架构文档
    ├── API_REFERENCE.md      # API 参考
    ├── DEBUG_GUIDE.md        # 调试指南
    ├── BUILD_GUIDE.md        # 打包指南
    └── PROJECT_SUMMARY.md    # 项目总结（本文档）

🔧 技术架构

运行环境

  1. Extension Service Worker (Background)

    • 文件：background.js
    • 职责：生命周期管理、消息中转、配置初始化
    • 特性：无状态、异步操作

  2. Content Script

    • 文件：content.js
    • 职责：页面交互、脚本注入、DOM 操作
    • 特性：隔离环境、可访问 DOM

  3. Extension UI

    • Popup：popup.html/js/css
    • SidePanel：sidepanel.html/js/css
    • Options：options.html/js/css

消息传递机制

Popup ←→ Background ←→ Content Script
         ↓
    chrome.storage

脚本注入流程

1. Content Script 注入 translate.js 到页面环境
2. Content Script 注入 translate-init.js 初始化
3. Content Script 注入 translate-drag.js 实现拖拽
4. 通过 postMessage 传递配置

⚙️ 配置项

默认配置

{
  enabled: true,              // 插件启用状态
  autoTranslate: true,         // 自动翻译
  defaultLang: 'zh-CN',        // 默认语言（源语言）
  targetLang: 'en',            // 目标语言
  apiKey: '',                  // API 密钥
  showNotifications: false,     // 显示通知
  autoDetectLang: true         // 自动检测语言
}

配置管理

  • 自动初始化：安装时自动设置默认值
  • 智能合并：更新时保留用户配置，只补充缺失项
  • 持久化存储：使用 chrome.storage.sync 同步到所有设备

🎨 UI 组件

1. Popup（弹出窗口）

  • 位置：点击扩展图标显示
  • 功能：快速切换开关、打开侧边栏、打开设置
  • 特点：简洁、快速操作

2. SidePanel（侧边栏）

  • 位置：浏览器右侧固定显示
  • 功能：完整设置、状态显示、快速操作
  • 特点：功能丰富、实时同步

3. Options（选项页面）

  • 位置：独立页面
  • 功能：详细配置管理
  • 特点：完整功能、持久化设置

4. 语言选择下拉框

  • 位置：页面中可拖拽的浮动控件
  • 功能：切换翻译语言
  • 特点：可拖拽、最高层级、美观样式

🔑 核心 API 使用

存储 API

// 保存
chrome.storage.sync.set({ key: 'value' });

// 读取
chrome.storage.sync.get(['key'], (result) => {
  console.log(result.key);
});

消息传递

// 发送消息
chrome.runtime.sendMessage({ action: 'do', data: 'value' });

// 接收消息
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.action === 'do') {
    sendResponse({ success: true });
  }
  return true; // 异步响应
});

标签页操作

// 获取当前标签页
chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
  const tab = tabs[0];
});

// 发送消息到 Content Script
chrome.tabs.sendMessage(tabId, { action: 'update' });

🚀 使用流程

安装扩展

  1. 打开 Chrome 浏览器
  2. 访问 chrome://extensions/
  3. 开启"开发者模式"
  4. 点击"加载已解压的扩展程序"
  5. 选择 hs-i18n 文件夹

使用扩展

  1. 打开 Popup：点击扩展图标查看状态
  2. 打开侧边栏：在 Popup 中点击"侧边栏"按钮
  3. 配置设置：在侧边栏或选项页面中配置
  4. 选择语言：使用页面上的语言选择下拉框
  5. 拖拽移动：拖动下拉框到合适位置

📦 打包发布

生成 CRX 文件

  1. 打开 chrome://extensions/
  2. 开启"开发者模式"
  3. 点击"打包扩展程序"
  4. 选择 hs-i18n 文件夹
  5. 私钥文件（首次留空）
  6. 点击"打包扩展程序"

打包后文件

  • hs-i18n.crx - 扩展安装包
  • key.pem - 私钥文件（请妥善保管）

🔒 权限说明

已声明的权限

  • storage - 存储配置数据
  • activeTab - 访问当前活动标签页
  • scripting - 注入脚本到页面
  • sidePanel - 使用侧边栏功能
  • <all_urls> - 访问所有网站（用于翻译功能）

忽略的网站

  • https://www.baidu.com/* - 百度网站（在 manifest.json 中排除）

🎯 特色功能

1. 智能配置管理

  • 自动初始化默认配置
  • 智能合并用户配置
  • 配置版本管理

2. 可拖拽界面

  • 语言选择下拉框支持拖拽
  • 位置自动保存和恢复
  • 边界限制，不会移出屏幕

3. 多环境通信

  • Popup、SidePanel、Options、Content Script 之间实时通信
  • 配置变更自动同步
  • 状态实时更新

4. 完善的调试支持

  • 详细的日志系统
  • 调试模式开关
  • 完整的调试文档

📚 文档资源

核心文档

  • README.md - 项目说明和快速开始
  • ARCHITECTURE.md - 架构原理详解
  • API_REFERENCE.md - 完整 API 参考
  • DEBUG_GUIDE.md - 调试指南
  • BUILD_GUIDE.md - 打包发布指南

快速参考

  • API_QUICK_REF.md - API 快速参考
  • DEBUG_QUICK_REF.md - 调试快速参考
  • FLOWCHART.md - 流程图和时序图
  • CONFIG_GUIDE.md - 配置管理指南
  • SIDEPANEL_GUIDE.md - 侧边栏使用指南
  • TROUBLESHOOTING.md - 问题排查指南

🔄 开发工作流

开发流程

  1. 修改代码 → 编辑相关文件
  2. 重新加载扩展 → chrome://extensions/ → 点击"重新加载"
  3. 测试功能 → 打开目标网页测试
  4. 调试问题 → 使用 DevTools 查看日志
  5. 打包发布 → 使用打包工具生成 CRX

调试流程

  1. Background → chrome://extensions/ → 点击 "service worker"
  2. Content Script → 网页按 F12 → Sources → Content scripts
  3. Popup → 右键点击 Popup → "检查"
  4. SidePanel → SidePanel 页面按 F12

⚠️ 注意事项

开发注意事项

  1. Service Worker 无状态

    • 不能使用全局变量持久化数据
    • 必须使用 chrome.storage 存储

  2. Content Script 隔离

    • 与页面 JS 环境隔离
    • 不能直接访问页面变量
    • 需要通过消息传递通信

  3. CSP 限制

    • 不能使用内联脚本
    • 必须使用外部脚本文件
    • 通过 web_accessible_resources 声明可访问资源

  4. 权限声明

    • 所有使用的 API 都需要在 manifest.json 中声明
    • 某些功能需要特定权限

发布注意事项

  1. 私钥管理

    • key.pem 文件非常重要
    • 丢失后无法更新已发布的扩展
    • 不要提交到代码仓库

  2. 版本管理

    • 更新时修改 manifest.json 中的版本号
    • 使用语义化版本（如 1.0.0 → 1.0.1）

  3. 测试

    • 打包前充分测试所有功能
    • 检查不同浏览器的兼容性
    • 验证权限是否足够

🛠️ 技术栈

  • Manifest Version: 3（最新标准）
  • JavaScript: ES6+
  • CSS: 现代 CSS（Flexbox、Grid、动画）
  • Chrome APIs:
    • chrome.storage
    • chrome.runtime
    • chrome.tabs
    • chrome.scripting
    • chrome.sidePanel
    • chrome.action

📊 项目统计

文件数量

  • JavaScript 文件：8 个
  • HTML 文件：3 个
  • CSS 文件：4 个
  • 文档文件：10+ 个
  • 配置文件：2 个

代码行数（估算）

  • JavaScript：~1500 行
  • CSS：~500 行
  • HTML：~200 行
  • 文档：~3000 行

🎓 学习要点

Chrome 扩展开发核心概念

  1. 多环境隔离

    • Service Worker、Content Script、Extension UI 运行在不同环境
    • 通过消息传递和存储 API 通信

  2. 消息传递

    • sendMessage / onMessage - 简单消息
    • connect / onConnect - 长连接
    • tabs.sendMessage - 标签页消息

  3. 存储管理

    • chrome.storage.sync - 同步存储
    • chrome.storage.local - 本地存储
    • 监听存储变化

  4. 脚本注入

    • Content Scripts - 自动注入
    • chrome.scripting.executeScript - 动态注入
    • 页面环境 vs 扩展环境

🔮 未来扩展

可能的改进方向

  1. 功能增强

    • 支持更多翻译服务
    • 添加翻译历史记录
    • 支持自定义翻译规则

  2. 用户体验

    • 添加快捷键支持
    • 优化拖拽体验
    • 添加更多主题

  3. 性能优化

    • 优化脚本加载
    • 减少内存占用
    • 提升翻译速度

  4. 国际化

    • 扩展界面多语言支持
    • 更多语言对支持

📝 版本历史

v1.0.0（当前版本）

  • ✅ 基础翻译功能
  • ✅ Popup 弹出窗口
  • ✅ SidePanel 侧边栏
  • ✅ Options 选项页面
  • ✅ 可拖拽语言选择框
  • ✅ 配置管理系统
  • ✅ 完整的文档

🤝 贡献指南

开发环境

  1. 克隆或下载项目
  2. 在 Chrome 中加载扩展
  3. 开启调试模式
  4. 开始开发

代码规范

  • 使用有意义的变量名
  • 添加必要的注释
  • 保持代码简洁
  • 遵循现有代码风格

📞 支持与反馈

获取帮助

  • 查看 DEBUG_GUIDE.md 了解调试方法
  • 查看 TROUBLESHOOTING.md 排查问题
  • 查看 API_REFERENCE.md 了解 API 使用

报告问题

如遇到问题，请提供：

  • Chrome 版本
  • 扩展版本
  • 错误信息
  • 复现步骤

📄 许可证

本项目为示例项目，可根据需要添加许可证信息。

🎉 总结

HS I18n 是一个功能完整、架构清晰的 Chrome 扩展项目，展示了：

  • ✅ Manifest V3 标准开发
  • ✅ 多环境组件通信
  • ✅ 完善的配置管理
  • ✅ 现代化的 UI 设计
  • ✅ 完整的文档体系
  • ✅ 良好的代码组织

适合作为 Chrome 扩展开发的参考和学习项目。

最后更新: 2025年 版本: 1.0.0 状态: 开发完成，可打包发布

avatar
文章
阅读
粉丝