Firefox/Thunderbird 扩展结构

相关源文件

• src/chrome.manifest
• src/chrome/backgroundscript.js
• src/chrome/contentscript.js
• src/firefox/chrome/content/confirm-prompt.js
• src/firefox/chrome/content/confirm-prompt.xul
• src/firefox/chrome/content/ff-overlay.js
• src/firefox/chrome/content/ff-overlay.xul
• src/firefox/chrome/content/tb-overlay.xul
• src/firefox/chrome/content/zotero-overlay.xul
• src/firefox/chrome/skin/toolbar.css
• src/firefox/defaults/preferences/prefs.js

本页介绍了适用于 Firefox 和 Thunderbird 的 Markdown Here 扩展的结构和实现。它涵盖了该扩展如何使用基于 XUL 的技术与这些 Mozilla 应用程序集成、涉及的关键文件以及它们如何相互作用以提供核心功能。有关 Chrome 扩展结构的信息，请参阅 Chrome 扩展结构。

1. Mozilla XUL 扩展架构概述

Markdown Here 为 Firefox 和 Thunderbird 使用了传统的基于 XUL (XML 用户界面语言) 的扩展结构，这与 Chrome 扩展模型显著不同。在 WebExtensions 成为主流之前，这种架构是 Mozilla 应用程序的标准方法。

来源：src/chrome.manifest src/firefox/chrome/content/ff-overlay.js src/firefox/chrome/content/ff-overlay.xul src/firefox/chrome/content/tb-overlay.xul

2. Chrome Manifest 文件

chrome.manifest 文件是核心配置文件，它决定了扩展如何与浏览器/邮件客户端集成。它定义了

2.1 资源映射

content   markdown_here                 firefox/chrome/content/
skin      markdown_here   classic/1.0   firefox/chrome/skin/
locale    markdown_here   en            firefox/chrome/locale/en/
resource  markdown_here_common          common/

这些映射创建了扩展可以访问的 chrome:// URL。resource 映射尤为重要，因为它允许访问共享代码。

2.2 覆盖声明

# Firefox
overlay chrome://browser/content/browser.xul  chrome://markdown_here/content/ff-overlay.xul application={ec8030f7-c20a-464f-9b0e-13a3a9e97384}

# Thunderbird
overlay chrome://messenger/content/messengercompose/messengercompose.xul chrome://markdown_here/content/tb-overlay.xul application={3550f703-e582-4d05-9a08-453d09bdfdc6}

这些声明告诉浏览器将哪些 XUL 文件覆盖到特定的应用程序窗口上。应用程序 ID 确保覆盖只在适当的应用程序中加载。

来源：src/chrome.manifest1-51

3. 扩展文件结构

Firefox/Thunderbird 扩展使用以下目录结构

此结构遵循 Mozilla 传统的扩展布局，为内容（JavaScript 和 XUL）、皮肤（CSS）和本地化（国际化）设置了单独的目录。

来源：src/chrome.manifest src/firefox/chrome/content/ff-overlay.js

4. XUL 覆盖与 UI 集成

XUL 覆盖是 Markdown Here 与 Firefox 和 Thunderbird 用户界面集成的方式。

4.1 Firefox UI 集成 (ff-overlay.xul)

Firefox 覆盖添加了

• 右键菜单中的上下文菜单项
• URL 栏中的页面操作按钮
• 一个可自定义的工具栏按钮

来源：src/firefox/chrome/content/ff-overlay.xul11-30

4.2 Thunderbird UI 集成 (tb-overlay.xul)

Thunderbird 覆盖添加了

• 撰写窗口中的上下文菜单项
• 撰写窗口中的一个可自定义工具栏按钮
• 格式工具栏中的一个按钮

来源：src/firefox/chrome/content/tb-overlay.xul10-31

5. 核心 JavaScript 实现 (ff-overlay.js)

ff-overlay.js 文件包含了 Firefox 和 Thunderbird 的核心功能。它创建了一个 markdown_here 对象来处理所有扩展操作。

来源：src/firefox/chrome/content/ff-overlay.js15-496

5.1 初始化和脚本加载

扩展加载时，它使用 Mozilla 脚本加载器导入所需的模块

这种机制通过从 chrome.manifest 中映射的 resource://markdown_here_common/ URL 加载，实现了 Chrome、Firefox 和 Thunderbird 扩展之间的代码共享。

来源：src/firefox/chrome/content/ff-overlay.js102-125

5.2 事件处理

该扩展处理各种事件

事件	处理器	目的
上下文菜单点击	onMenuItemCommand()	处理来自上下文菜单的 Markdown 切换
工具栏按钮点击	onToolbarButtonCommand()	处理来自工具栏的 Markdown 切换
上下文菜单显示	contextMenuShowing()	控制上下文菜单项的可见性
焦点变化	focusChange()	根据当前元素更新按钮状态
快捷键按下	动态创建的处理程序	处理键盘快捷键

来源：src/firefox/chrome/content/ff-overlay.js31-79 src/firefox/chrome/content/ff-overlay.js228-357

5.3 渲染过程

markdownRender 函数处理从 Markdown 到 HTML 的实际转换

此函数

1. 从 DOM 中提取文本
2. 获取用户偏好设置
3. 使用共享的 MarkdownRender 模块渲染 Markdown
4. 对 HTML 进行后处理
5. 通过回调传回渲染后的 HTML 和 CSS

来源：src/firefox/chrome/content/ff-overlay.js272-286

6. 平台特定功能

6.1 Thunderbird 特定功能

该扩展包含了针对 Thunderbird 的特殊处理

6.1.1 撰写窗口检测

这段代码检查扩展是否在 Thunderbird 中运行并验证

• 编辑器处于 HTML 模式（而非纯文本）
• 光标在可渲染的撰写框中

来源：src/firefox/chrome/content/ff-overlay.js40-55

6.1.2 忘记渲染检查

此功能检查用户是否正在发送包含未渲染 Markdown 的电子邮件，并提示他们确认或返回渲染。

来源：src/firefox/chrome/content/ff-overlay.js169-224

6.2 工具栏按钮状态管理

该扩展动态管理按钮状态

此函数

1. 更新页面操作按钮的可见性
2. 启用/禁用工具栏按钮
3. 根据当前状态更新工具提示文本

来源：src/firefox/chrome/content/ff-overlay.js295-324

7. CSS 和视觉样式

该扩展使用平台特定的 CSS 文件对 UI 元素应用 CSS 样式，并根据不同操作系统进行条件加载

# Linux
style chrome://markdown_here/content/ff-overlay.xul chrome://markdown_here/skin/toolbar-linux.css os=Linux
style chrome://markdown_here/content/tb-overlay.xul chrome://markdown_here/skin/toolbar-linux.css os=Linux

# OS X
style chrome://markdown_here/content/ff-overlay.xul chrome://markdown_here/skin/toolbar-osx.css os=Darwin
style chrome://markdown_here/content/tb-overlay.xul chrome://markdown_here/skin/toolbar-osx.css os=Darwin

# Windows
style chrome://markdown_here/content/ff-overlay.xul chrome://markdown_here/skin/toolbar-windows.css os=WINNT
style chrome://markdown_here/content/tb-overlay.xul chrome://markdown_here/skin/toolbar-windows.css os=WINNT

toolbar.css 文件为所有 UI 元素提供了详细的样式，包括适用于 Retina 显示器的高 DPI (2dppx) 版本。

来源：src/chrome.manifest40-50 src/firefox/chrome/skin/toolbar.css1-151

8. 扩展加载过程

此图显示了 Firefox 或 Thunderbird 启动时扩展的加载方式

1. 浏览器读取 chrome.manifest
2. 覆盖应用于相应的浏览器 UI
3. 加载 JavaScript 文件并执行 onLoad 处理程序
4. 导入通用模块
5. 注册事件处理程序
6. 初始化按钮状态
7. 设置快捷键和按钮可见性的间隔检查

来源：src/firefox/chrome/content/ff-overlay.js498-507 src/chrome.manifest24-30

9. 与 WebExtension 模型的比较

传统的基于 XUL 的扩展（如 Markdown Here 的 Firefox/Thunderbird 实现）与现代 WebExtension 模型显著不同

功能	XUL 扩展	WebExtension
UI 集成	通过 XUL 覆盖实现深度集成	限于浏览器操作、页面操作和上下文菜单
权限	完全访问浏览器 API	受限于明确的权限
跨浏览器	Mozilla 专用	适用于 Chrome、Firefox、Edge
文件结构	chrome.manifest + XUL 文件	manifest.json + HTML/JS/CSS
脚本加载	scriptLoader.loadSubScript	import/require 或后台脚本
DOM 访问	直接访问浏览器 DOM	内容脚本，访问受限

现代 Firefox 已基本弃用 XUL 扩展，转而支持 WebExtensions，但 Thunderbird 仍支持此模型以实现更深度的集成。

来源：src/firefox/chrome/content/ff-overlay.js15-26 src/chrome/backgroundscript.js11-15