Firefox扩展SDK开发人员指南(一)

天涯网友为何怒沉百宝箱？
如果您喜欢这篇文章，请访问盛夏莲花博客以获取最新内容更新及评论，以及更好的阅读体验。

Firefox扩展使得以百万计的Firefox用户能够增强和定制他们的上网体验。实际上，拥有众多扩展，是用户喜爱Firefox的重要原因之一。现在，Firefox推出了Add-on Builder和Add-on SDK，这样就使得创建一个Firefox扩展变得更加容易。

请注意，使用Add-on Builder和Add-on SDK是Firefox当前主推的开发扩展的最新方法。作为一名扩展开发人员，您应该考虑停止使用过去基于XUL的老的开发方法。而在互联网上可见的关于Firefox扩展开发的各类文章和教程，也可能是基于旧的开发方式，这些都已经或者正在成为过去。

本系列教程是基于Developer Guide的一个翻译。如果本教程中有错译的地方，请以原文为准。
第一章 安装SDK

使用ADD-ON SDK进行开发之前，您需要安装它。您将需要：

    Python 2.5 或者 2.6.注意Python 3.0或者3.1不可用。安装完Python后记得要把它加入到系统路径中。
    Firefox 版本4.0及以上。也就是说，如果您需要为老旧的Firefox开发扩展，那么不可以使用这个SDK。

当前最新的SDK的稳定版本是1.2版。您可以通过tarball或者zip file得到它。此外，您也可以从GitHub repository得到它的最新开发版本。
在Mac OS x/ Linux上安装

将下载后的文件解压到任何您选中的位置，从命令提示行浏览至SDK的根目录。例如：

    ~/mozilla >tar -xf addon-sdk-1.2.tar.gz ~/mozilla > cd addon-sdk-1.2 ~/mozilla/addon-sdk-1.2 >

然后运行：

    ~/mozilla/addon-sdk-1.2 > source bin/activate

运行结束后，您的命令提示符现在应该包含了SDK的根目录的名字了：

    (addon-sdk-1.2)~/mozilla/addon-sdk-1.2 >

在windows上安装

将SDK压缩包解压到任何一个地方，在命令行中浏览至SDK包的根目录，例如：

    C:\Users\mozilla\sdk>7z.exe x addon-sdk-1.2.zip C:\Users\mozilla\sdk>cd addon-sdk-1.2 C:\Users\mozilla\sdk\addon-sdk-1.2>

然后运行:

    C:\Users\mozilla\sdk\addon-sdk-1.2>bin\activate

    您可能会看到如下所示的错误提示：

    ERROR: The system was unable to find the specified registry key or value.

    错误：系统无法找到指定的注册表键或者注册表键值。

    这是一个已知错误，记录在<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=574563">bug 574563</a>上。它不会影响到SDK的正确运行。

    现在，您的命令提示应该有了一个新的包含着SDK根目录的前缀：

    (C:\Users\mozilla\sdk\addon-sdk-1.2) C:\Users\Work\sdk\addon-sdk-1.2&gt;

SDK虚拟环境

这个新的提示符表明您已经进入了一个SDK的虚拟开发环境，在这个虚拟开发环境中，您将可以使用到ADD-ON SDK的命令行工具。

任何时候，您可以通过运行下面的命令来退出这个虚拟开发环境：

deactivate

虚拟开发环境使用了上面这个特定的命令提示符。如果您关闭了命令行窗口，虚拟开发环境则被注销，您需要在新的命令行窗口中输入source bin/activate 或者 bin\activate来重新激活它。

您可以安装多份SDK到不同的位置，并在它们之间自由切换。您甚至可以同时激活多个虚拟开发环境。
完整性校验

在命令提示符下输入下面的命令：

    ~/mozilla/addon-sdk-1.2 &gt; cfx

    输出的第一行应该类似于：

    Usage: cfx [options] [command]

    后面再接着许多行别的信息。

    这个就是命令行cfx程序。它是您与ADD-on SDK的主要接口。您使用它来启动Firefox以测试您的扩展，为分发扩展而进行打包，查看文档，以及运行单元测试。

cfx docs

如果您是在线阅读这份文档，现在您可以试着运行cfx docs命令。它将生成一份SDK的文档，并在浏览器中打开它。
有问题？

试试Troubleshooting页面吧。
下一步

接下来，让我们看一看Getting Started教程。 这份教程解释了SDK的基本概念，并且会引导您完整地考察一个简单的示例。

天涯网友为何怒沉百宝箱？
如果您喜欢这篇文章，请访问盛夏莲花博客以获取最新内容更新及评论，以及更好的阅读体验。

一个简单的扩展

这一切的教程将带您完整地领略使用SDK实现，运行和打包扩展的整个过程。这个示例扩展将在Firefox上下文菜单里增加一个选项，以使用英文翻译来替换选中的文本。
初始化您的扩展

创建一个名为translator的扩展。这是我们放置扩展文件的地方。

您不必在SDK根目录下创建目录。一旦您通过调用 source bin/activate激活了SDK，cfx则会记住SDK的位置，因此您可以从任何位置来使用SDK。

将您的扩展代码放在SDK以外是一个好的习惯。这使得更新SDK会变得容易，并且您也可以使用版本控制系统来管理代码。

接下来我们使用cfx init来创建一个扩展的框架结构。浏览至translator目录，并且执行cfx init。您将会看到：

    * lib directory created * data directory created * test directory created * doc directory created * README.md written * package.json written * test/test-main.js written * lib/main.js written * doc/main.md written

现在，您已经可以运行这个示例扩展的测试了：

运行cfx test，然后再运行cfx run。享受这一切吧！

下面，我们来解释一下发生了什么。

首先，cfx init创建了如下扩展所需要的目录结构：

    /data目录。 Data目录用来包含诸如图标，HTML文件之类的资源，以及任意数量content scripts。您可以在扩展的代码中，通过使用SDK中的self模块来访问data子目录里的文件内容。
    /doc。包含了您的扩展的文档。
    /lib。包含了用来实现您的扩展的JavaScript模块。
    /test。包含了单元测试代码。

接下来，cfx init在translator的根目录下创建了一个名为package.json的文件。它包含了您的扩展的一些信息：

    { "name":"translator", "fullName":"translator", "description":"This is an example of addon description.", "author":"", "license":"MPL", "version":"0.1" }

最后，cfx init创建了一些示例代码文件在上述这些目录里。我们将用我们的实现来替换这些文件。
添加您的代码

在lib目录里，打开名为main.js的文件，将其内容用下面的代码替换：

    // Import the APIs we need. var contextMenu = require("context-menu"); var request = require("request"); var selection = require("selection"); exports.main = function(options, callbacks) { console.log(options.loadReason); // Create a new context menu item. var menuItem = contextMenu.Item({ label: "Translate Selection", // Show this item when a selection exists. context: contextMenu.SelectionContext(), // When this item is clicked, post a message to the item with the // selected text and current URL. contentScript: 'self.on("click", function () {' + ' var text = window.getSelection().toString();' + ' self.postMessage(text);' + '});', // When we receive the message, call the Google Translate API with the // selected text and replace it with the translation. onMessage: function (text) { if (text.length === 0) { throw ("Text to translate must not be empty"); } console.log("input: " + text); var req = request.Request({ url: "http://ajax.googleapis.com/ajax/services/language/translate", content: { v: "1.0", q: text, langpair: "|en" }, onComplete: function (response) { translated = response.json.responseData.translatedText; console.log("output: " + translated); selection.text = translated; } }); req.get(); } }); }; exports.onUnload = function (reason) { console.log(reason); };

导入模块

最开始的三行代码从扩展包里导入了三个SDK模块：

    context-menu 使得扩展能够向上下文菜单添加菜单项
    request 使得扩展能够执行网络请求
    selection 使得扩展能够获取当前活动窗口中选中的文本。

创建菜单项

接下来，代码构建了一个菜单项，它提供了：

    用以显示的菜单项名字：Translate Selection
    菜单项显示的上下文环境：SelectionContext()。意思是当页面中存在被选中的内容时，就将这个菜单项包含在上下文菜单中。
    当菜单项被单击时要执行的脚本：这个脚本将选中的文本发送给onMessage属性指定的函数。
    onMessage属性：在此指定一个函数，这个函数将在用户单击菜单项时被调用，并且将用户选中的文本也会传递给这个函数。我们在这里使用了Google的基于AJAX的翻译服务来将选中文本翻译成英文。

监听load和unload事件

创建上下文菜单的代码被包装在一个函数中，这个函数又被我们赋值给了全局对象exports的main属性。

如果您的扩展导出一个名为main的函数，这个函数将在扩展被加载时调用。

exports.main = function (options, callbacks) {};

这里的option是一个对象，描述了您的扩展加载时的一些参数。这些参数都是字符串形式，特别地，options.loadReason字符串解释了您的扩展被调用的原因：

install，enable,startup,upgrade,downgrade.

相反地，如果您的扩展导出一个名为onUnload的函数，则它将在扩展被卸载时调用：

exports.onUnload = function (reason) {};

reason指明了您的扩展被卸载的原因：

uninstall,disable,shutdown,upgrade或者downgrade.

您不是必须使用exports.main或者exports.oonUnload。您的代码，如果是放置在源文件的顶层位置，而不是被包含在函数中的话，它们都会被调用。然而，如果您这样做，就会失去访问options或者callbacks参数的机会。

我们的示例扩展并不特别地需要使用exports.main或者exports.onUnload，我们将它们包含进来，完全是为了演示目的。
日志

请注意这里使用了console.log()。console是一个全局对象，可以在任何模块中访问它，并且您还可以使用它来输出error，warning或者消息。

如果扩展补打包成xpi并安装到firefox，消息会被输出到Firefox的错误控制台。如果您是使用cfx从命令行中启动的Firefox，则这些消息会被发送到命令行控制台。
运行扩展

浏览至translator目录，键入

cfx run

如果您是第一次这么做，您将会看到下面的消息：

    No 'id' in package.json: creating a new ID for you. package.json modified: please re-run 'cfx run'

    在package.json中没有找到id的定义。正在为您创建ID…package.json已经修改，请重新运行cfx run。

    重新运行，一个新的Firefox实例将带着您的扩展一起启动。

    cfx生成的ID是一个惟一的标识符，称作程序标识符。它十分重要。许多工具或者服务都需要通过它来区分不同的扩展。

    关于更多程序标识符的信息，请参阅<a href="https://addons.mozilla.org/en-US/developers/docs/sdk/1.2/dev-guide/addon-development/program-id.html">Program ID</a>文档。

    一旦cfx run启动了firefox，您就可以试一下这个新的扩展。打开一个有非英语文字的页面，比如<a href="http://www.mozilla.org/about/manifesto.fr.html">http://www.mozilla.org/about/manifesto.fr.html</a>，选中一些文字，右键打开上下文菜单，您应该看到一个新的菜单项，叫做"Translate Selection“，

    <a href="http://blog.lotus-scent.com/wp-content/uploads/2011/12/image3.png"><img style="background-image: none; border-right-width: 0px; margin: 0px; padding-left: 0px; padding-right: 0px; display: inline; border-top-width: 0px; border-bottom-width: 0px; border-left-width: 0px; padding-top: 0px" title="image" border="0" alt="image" src="http://blog.lotus-scent.com/wp-content/uploads/2011/12/image_thumb3.png" width="568" height="341"></a>

单这个菜单项，则选中的文字应该会被翻译成英文。

image

同时，您应该在命令行控制台中看到类似下面的输出：

    info: input: Le projet Mozilla est une communauté mondiale de personnes qui pensent que l'ouverture, l'innovation et la saisie des chances qui nous sont offertes sont les clés de la vitalité d'Internet. Nous travaillons ensemble depuis 1998 pour nous assurer qu'Internet se développe d'une manière qui bénéficie à tout le monde. On nous connaît surtout pour la création du navigateur Web Mozilla Firefox. info: output: The Mozilla project is a global community of people who believe that openness, innovation and seizing opportunities offered to us are the keys to the vitality of the Internet. We have been working together since 1998 to ensure that the Internet develops in a way that benefits everyone. We are best known for creating the Mozilla Firefox Web browser.

准备布署

一旦完成了测试，您就可以着手将其包装成xpi文件，就象其它firefox扩展一样。扩展SDK将可以为您生成这个文件，从而简化了这一操作。

要将您的程序包装成xpi，请导航至您的package的根目录，再运行cfx xpi。您应该会看到下面的消息：

    Exporting extension to translator.xpi.

    正在将扩展输出到translator.xpi。

    translator.xpi将可以在您运行命令的那个目录下找到。

安装

在Firefox窗口中按下Ctrl+O（Cmd+O for Mac）键。这将唤起一个文件选择对话框，浏览并选中translator.xpi，打开它并按提示完成安装。
分发

要分发您的程序，您可以将其上传至addons.mozilla.org。最终，这些步骤也会被集成到SDK中来。

在一下节我们将会介绍CommonJS。CommonJS为SDK提供了基础性的架构。

先顶一个再说……

我已经翻译到Firefox扩展SDK开发人员指南(七)了。第(七)章讲得是关于Request对象。请大家前往forum.lotus-scent.com收看