扩展结构

相关源文件

• CHANGES.md
• src/chrome.manifest
• src/chrome/background.html
• src/common/CHANGES.md
• src/firefox/chrome/content/ff-overlay.xul
• src/firefox/chrome/content/tb-overlay.xul
• src/firefox/chrome/skin/toolbar.css
• src/install.rdf
• src/manifest.json

本页详细介绍了 Markdown Here 扩展在不同浏览器平台上的结构。内容涵盖了文件组织、浏览器特定的实现以及构成扩展的共享组件。有关渲染管道工作原理的信息，请参阅Markdown 渲染管道；有关用户界面元素的详细信息，请参阅用户界面。

1. 扩展架构概述

Markdown Here 是一个跨浏览器扩展，通过共享的核心代码库支持多个平台。该扩展根据不同的浏览器使用不同的集成方法。

来源：src/manifest.json src/install.rdf src/chrome.manifest src/chrome/background.html

2. 目录结构

该扩展的代码库被组织成几个关键目录

根目录包含项目元数据和构建脚本，而 src 目录包含扩展的所有源代码。源代码进一步分为：

• common/ - 所有浏览器实现共享的代码
• chrome/ - Chrome 特定的实现
• firefox/ - Firefox 和 Thunderbird 实现

来源：src/manifest.json src/chrome.manifest

3. Chrome 扩展结构

Chrome 扩展遵循标准的 Chrome 扩展模型，使用 manifest.json、后台脚本和内容脚本。

3.1 清单文件

Chrome 和其他基于 Chromium 的浏览器的扩展结构在 manifest.json 中定义。

清单文件声明了：

• 清单版本 (v3)
• 扩展元数据（名称、版本、描述）
• 所需权限（contextMenus、storage）
• 后台脚本配置
• 要注入到网页中的内容脚本
• 浏览器操作（工具栏按钮）
• 选项页配置

来源：src/manifest.json1-55

3.2 后台和内容脚本

Chrome 扩展使用后台脚本来处理持久状态和事件，使用内容脚本进行页面交互。

后台脚本（backgroundscript.js）处理：

• 上下文菜单创建
• 工具栏按钮状态
• 扩展组件之间的消息传递
• 选项管理

内容脚本（contentscript.js）处理：

• DOM 交互
• Markdown 检测和渲染
• 页面上下文中的事件监听

来源：src/manifest.json16-33 src/chrome/background.html12-18

4. Firefox/Thunderbird 扩展结构

Firefox 和 Thunderbird 使用基于 Mozilla 扩展模型的不同扩展结构。

4.1 安装清单

Firefox 和 Thunderbird 的扩展结构在 install.rdf 中定义。

install.rdf 文件指定了：

• 扩展元数据（ID、版本）
• 兼容应用程序（Firefox、Thunderbird）
• 版本兼容范围
• 本地化描述
• 选项页配置

来源：src/install.rdf1-159

4.2 Chrome 清单和叠加层

Firefox 和 Thunderbird 扩展使用 chrome.manifest 来定义资源和叠加层。

chrome.manifest 文件：

• 映射内容、皮肤和区域设置目录
• 为不同的应用程序（Firefox、Thunderbird、Zotero、Pale Moon）定义叠加层
• 指定平台特定样式（Linux、OS X、Windows）
• 将资源标识符映射到实际目录

来源：src/chrome.manifest1-51

4.3 XUL 叠加层

Firefox 和 Thunderbird 的 UI 集成通过 XUL 叠加文件实现。

这些叠加文件定义了：

• 上下文菜单项
• 工具栏按钮
• 页面操作
• 用户交互的事件处理器

来源：src/firefox/chrome/content/ff-overlay.xul1-31 src/firefox/chrome/content/tb-overlay.xul1-43 src/firefox/chrome/skin/toolbar.css1-151

5. 常用核心组件

共享的核心功能在 common/ 目录中的 JavaScript 文件中实现。

主要组成部分包括：

• markdown-here.js - 核心切换功能
• markdown-render.js - Markdown 渲染逻辑
• mdh-html-to-text.js - HTML 到 Markdown 转换
• common-logic.js - 共享业务逻辑
• utils.js - 实用函数
• options-store.js - 选项管理

来源：src/chrome/background.html12-18 src/manifest.json24-32

6. 跨浏览器兼容性

Markdown Here 通过不同的实现方法支持多个浏览器平台。

浏览器/平台	集成方法	主配置文件	UI 实现
Chrome/Chromium	WebExtensions API	manifest.json	基于 HTML/JS 的 UI
Firefox（现代版）	WebExtensions API	manifest.json	基于 HTML/JS 的 UI
Firefox（旧版）	基于 XUL	install.rdf + chrome.manifest	XUL 叠加层
Thunderbird	基于 XUL	install.rdf + chrome.manifest	XUL 叠加层
Safari	Safari 扩展	-	基于 HTML/JS 的 UI

该扩展随着时间推移不断发展，以适应不断变化的浏览器扩展模型。

• 旧版 Firefox/Thunderbird 扩展使用 XUL 叠加层。
• 现代 Firefox 扩展使用 WebExtensions API（自 v2.13.1 起）。
• Chrome 使用 WebExtensions API，最近更新到 Manifest V3（自 v2.14.0 起）。

来源：src/common/CHANGES.md50-56 src/common/CHANGES.md26-27

7. 构建系统

构建系统针对不同平台打包扩展，处理扩展格式的差异。

构建过程

1. 为每个平台组装相应的文件
2. 以正确的格式打包它们
3. 处理平台之间的清单差异
4. 包含正确的资源和依赖

来源：src/common/CHANGES.md26-27 src/common/CHANGES.md50-56

总结

Markdown Here 采用混合架构，结合了平台特定实现和共享核心组件。扩展结构旨在最大化代码重用，同时适应受支持浏览器的不同扩展模型。这种方法使得扩展能够在 Chrome、Firefox、Thunderbird 和其他平台提供一致的功能，同时适应平台特定的要求和限制。