firefox附加组件开发者指南（五）——创建一个firefox扩展(上)
本章篇幅较长，分上下两部分发布，本章中的图和清单4在原网站中没有，因此这里也没有，感兴趣的可以去原文补充。下面是译文。
至今为止，各个章节中独立的介绍了相关的技术——XUL、javascript、CSS和XPCOM。本章中，我们讨论如何将它们放到一起来实际的创建一个扩展。
注：那些对诸如netbeans、eclipse等IDE掌握得非常好的开发者的创建Firefox/thunderbird附加组件的更简单方法是使用netbeans(来自sun microsystems)和foxbeans(netbeans的扩展，由TeeSoft开发)。（译注：本人刚开始学做扩展的时候试过，foxbeans并没有随着Firefox和netbeans的更新而升级，虽然很简单的可以开发出一个Firefox的扩展，但是开发出来的扩展在较新版本的Firefox中没有很好的支持）设置开发环境
为了以最方便的方式开发（以及测试）扩展，极力推荐对Firefox做一些变化。下面你将会看到一个如何改变的简洁描述；更详细的描述可以在设置一个扩展开发环境中找到创建开发profile
如果你想将日常使用的Firefox浏览环境与你的开发环境分开，另外设置一个profile进行开发。创建这个dev profile用下面的参数运行Firefox：firefox.exe -no-remote -P dev在刚开始的时候会打开profile管理器，可以在这里创建devprofile并配置其路径。
改变首选项以进行高效开发
在你开始开发扩展之前，可以对Firefox的首选项进行一些改变。这对于扩展开发来说不是必须的，但是我推荐修改一下，这样工作会更有效率。表1：开发扩展可以设置的首选项
| 首选项 |
描述 |
值 |
| nglayout.debug.disable_xul_cache (Firefox 3.5以上的版本不存在) |
通常,Firefox会在读取XUL文档之后进行缓存,要加快后来的XUL文档的显示速度。禁用该缓存可以在每次需要显示的时候强制重新加载XUL文档 |
True |
| browser.dom.window.dump.enabled (Firefox 3.5以上的版本不存在) |
启用用于调试的dump方法。 对应于“JavaScript debugging methods”侧边栏。 |
True |
| javascript.options.showInConsole (Firefox 3.5以上的版本) |
在错误控制台中输出javascript错误 |
True |
| javascript.options.strict (Firefox 3.5以上的版本) |
从javascript中进行强制错误输出 |
True |
安装DOM Inspector
DOM Inspector是一个可以帮助你检查HTML和XUL 的DOM树结构、javascript对象以及CSS属性等的扩展。这个对于开发扩展来说不是必须的，但有的话会更方便。从mozilla Add-ons网站上安装Firefox扩展。可选-安装Firebug和Chromebug
Chromebug是firebug开发团队使用来开发firebug的。你可以使用它来调试Firefox控制也可以来检查学习Firefox的UI(chrome)是如何构成的。你可以在 http://getfirebug.com/wiki/index.php/Chromebug_User_Guide下载并学习更多关于chromebug。你可以发现这个扩展也很有价值：扩展开发者：Extension Developer https://addons.mozilla.org/en-US/firefox/addon/7434
开发扩展：你需要知道些什么
让我们来探究一下chrome，为了开发扩展你需要知道chrome。Chrome
什么是chrome?
“chrome”是用来描述所有在XUL应用程序中的GUI结构的词。比如，在Firefox浏览器窗口中，除了网页之外的显示在内容区的所有事物就是chrome。扩展也可以当做是带有chrome的XUL应用程序。组成chrome的三类程序包
content程序包这个程序包是用来容纳主要的XUL和javascript脚本源文件的。很多扩展由一个单独的content程序包组成。
locale程序包
这个程序包是用来容纳用于翻译的语言数据的。要使一个扩展的GUI支持多语言，则可以包含多个locale程序包，每种语言一个（locale程序包）。
skin程序包
这是用来包含用于可视化GUI元素（包括样式表和图像）的源文件的。大多数扩展只包含一个skin程序包，但是你可以包含多个skin程序包以支持GUI在不同的主题间进行改变。
Chrome URL
使用一个叫做chrome清单的文件来向Firefox注册chrome程序包并使用它们。要注册一个程序包，使用一个特殊的叫做chrome URL的URI结构来表示文件的路径。Chrome URL的结构是：chrome://%package name%/%package type%/%relative path to source file%例如，Firefox浏览器窗口的chrome URL如下：chrome://browser/content/browser.xul
这里程序包名称是browser，文件是browser.XUL，程序包的类型是content。源文件代表以UniversalXPConnect权限通过chrome URL运行。即使它们没有保证“使用XPConnect作为本地文件”的权限，如第四章所讨论的那样，它们将可以使用XPCOM的函数（图1）。
图1：chrome程序包以及chrome的注册
Extension/
Chrome.manifest
Chrome/ #registered in the chrome
content package #Run with privileges
locale package
skin package
跨包叠加
第三章中介绍的”overlay”技术需要在XUL文档中使用xul-overlay指令说明叠加的目标。不在XUL文档中使用xul-overlay指令而强制叠加也是可能的——这叫做“跨包叠加”（图2）。事实上，你需要使用跨包叠加来将按钮或者菜单添加到Firefox浏览器窗口中。使用chrome清单来激活一个跨包叠加。图2：激活一个跨包叠加
Normal overlay: Adding the xul-overlay instruction to the target XUL document overlays it with another XUL document
Cross-package overlay: Adding a cross manifest permits one XUL file to overlay another without any xul-overlay instruction.
结论
这是对chrome一个简单的介绍，可能还遗留了很多未回答的问题。如果你能牢记下述三点，下一节，开发一个简单的扩展，将会帮助你进一步的理解。1. 一个扩展的GUI可以由三种程序包组成：content、locale和skin。
2. 在browser.XUL的顶部使用跨包叠加为Firefox浏览器窗口添加一个按钮或者菜单项。
3. Chrome清单所扮演的两个重要角色是：注册chrome程序包的内容，激活跨包叠加。
开发一个简单的扩展：Hello World
这一节，我们将会编写一个极为简单的仅仅显示时间的”hello world”扩展。第一阶段:测试安装
我们的第一步将会执行一个包含向工具菜单添加新的菜单项的最少代码的测试安装（图3）。源文件结构
首先设置你要用来组织扩展源代码的工作文件夹。这个文件夹可以随便在哪里，本教程假设它在C:\extensions\helloworld。在你的工作文件夹中创建文件夹和文件如图4.第一阶段创建的每个文件的目的在表2中解释。图4：第一阶段使用的文件夹结构
| 文件名 |
角色 |
| install.rdf |
叫做安装清单，这给出了这个扩展的基本信息，并且是Firefox中安装该扩展所必须的 |
| chrome.manifest |
这是前面描述的chrome清单。注册程序包并激活跨包叠加。 |
| content/overlay.xul |
将会叠加到Firefox浏览器窗口的XUL文件,添加按钮，菜单项等. |
| content/clock.xul content/clock.js |
XUL文件在窗口中显示一个钟，javascript文件控制其操作（这些文件会在第二阶段使用）。 |
创建安装清单
用清单1中的内容写到install.rdf中：清单1：install.rdf的内容
[email protected]
2
Hello, World!
0.1
My first extension.
Gomita
http://www.xuldev.org/helloworld/
{ec8030f7-c20a-464f-9b0e-13a3a9e97384}
2.0
4.0.0.*
创建chrome清单
用清单2中的内容填充chrome.manifest文件清单2：chrome.manifest文件的内容
content helloworld content/
overlay chrome://browser/content/browser.xul chrome://helloworld/content/overlay.xul注册content程序包（content指令）
第一行，以content开头，包含了用于注册chrome的content程序包的代码。这里helloworld是一个程序包名称，content/是一个存储源文件的文件夹的相对路径。注册content程序包使得content文件夹中的overlay.xul文件能够使用chrome URL: chrome://helloworld/content/overlay.xul来访问。
XUL跨包叠加（overlay指令）
第二行，以overlay开头，包含了用来激活跨包叠加的代码，在chrome://browser/content/browser.xul中找融合点用chrome://helloworld/content/overlay.xul.叠加到Firefox浏览器窗口。
寻找融合点
下一步是寻找叠加文档将会插入其内容到基础文档中的“融合点”。关于这个有很多的方法来进行，我们使用DOM Inspector（图5）。
选择工具>DOM Inspector菜单项打开DOM Inspector。
输入chrome://browser/content/browser.XUL到顶部的URL输入区，然后点击Inspect按钮。窗口下面部分将会出现一个浏览器面板。
点击图5中标记为1和2的点；这样菜单元素（3）将会被选中。
展开3：这会露出标记为4的地方，有几个menuitem元素。Menupopup元素4包含了你将要添加新的菜单项的融合点，你可以看到它的id是menu_ToolsPopup。
浏览在这个menupopup元素内部的menuitem元素并确定你想要讲你的新元素添加到什么地方。这里，我们将其定位到数字5的地方。
图5：使用DOM Inspector寻找叠加融合点
将overlay放到浏览器窗口
现在你知道了了你的overlay的融合点，你可以创建将要插入到此处的overlay.xul文件（清单3）。在第四行，我们标记融合点为menupopup元素，5-7行，是添加新菜单项的代码，insertbefore属性决定了这个元素添加的位置。
测试安装及操作检查
我们有了最终安装hello world扩展的位置。这里采用常规的XPI类型安装会带来错误，因此我们不使用那种方式。对于开发中的源文件我们采用测试安装。放置指示文件
首先，移动到当前活动的profile的文件夹，打开其中的extensions文件夹。在其中创建一个新的具有你用来作为hello world扩展的ID相同名称的文件[email protected]。将其内容设置为你的扩展源文件的完整路径：C:\extensions\helloworld.
清单3：overlay.xul文件的附加内容
第二阶段:添加一个显示时间的函数
在第二阶段，我们将会实现选择第一阶段中创建的hello world菜单项就显示一个带有时间窗口的功能（图6）。图6：第二阶段创建的时钟窗口
添加事件处理函数
首先，我们为菜单项添加一个打开窗口的事件处理函数（清单4）。清单4：事件处理函数
时钟处理函数
创建显示时钟的窗口（清单5）以及其控制函数（清单6）。我们已经在第三章中描述了dialog元素。这里，我们只想要显示一个OK按钮，因此我们将buttons属性设置为accept。在这个窗口中有一个label元素和一个textbox元素，放在一个hbox元素内部这样它们就会水平的排列。清单5：clock.xul的内容
清单6：clock.js文件的内容
function initClock() {
showCurrentTime();
window.setInterval(showCurrentTime, 1000);
}
function showCurrentTime() {
var textbox = document.getElementById("currentTime");
textbox.value = new Date().toLocaleTimeString();
textbox.select();
}操作检查
进行一次操作检查以确保你对源文件的修改是正确的。这里，正如前面所述禁用XUL缓存非常重要。假设你已经做了那些，你将可以确认overlay.xul和clock.xul中的变化而不需要进行讨厌的重启Firefox或者重新安装扩展。就像overlay.xul要叠加到的目标browser.xul文件再次读取了，变化将会得到反映，你可以通过打开一个新的浏览器窗口来查看变化。文件clock.xul和clock.js将会在每次打开clock窗口时读取，因此只需要再次打开一次clock窗口就可以满足对它们的检查。在开发过程中，将校正源文件和进行对这些变化进行操作检查的步骤最小化是非常重要的。” 修改源文件后的操作检查”一部分讨论了从源文件校正到操作检查的一般进程。如果有什么东西无法正常工作呢？
如果你的扩展运行得与预计中不一样，首先看看错误控制台的错误面板中是否显示了错误。如果你将”设置开发环境”一节中所推荐的设置都进行了设置，XUL和javascript错误就会出现在这里。参见“javascript调试技术”以获取有用的建议。如果Firefox无法响应，你需要从任务管理器中终止Firefox进程。
第三阶段:添加多语言支持
我们在第二阶段创建的clock窗口显示的都是英文的。第三阶段，我们要为其添加多语言支持，那样在一个法语环境中使用的Firefox中看到“Heure actuelle”，而运行在英语环境中看到“Current time”（图7）。图7：第三阶段之后的clock窗口
目录结构
要为本扩展添加多语言支持，我们增加一个locale程序包到chrome中。在helloworld文件中创建一个具有子文件夹和文件的locale文件夹，如图8所示。这些文件的目的在表3中解释。图8：添加了locale程序包之后的目录结构
表3：第三阶段中使用的文件
| 名称 |
目的 |
| locale\en-US\clock.dtd |
定义clock.xul中使用的DTD实体引用(for English). |
| locale\fr-FR\clock.dtd |
定义clock.xul中使用的DTD实体引用(for French). |
添加locale程序包
注册locale程序包（locale指令）以locale开头的行是用来注册chrome的locale程序包的；helloworld是程序包名称，locale/fr-FR/是相对于包含了这个源文件的文件夹的相对路径；en-US和fr-FR说明了那些locale程序包是分别用于英语和法语的。
清单7：chrome.manifest文件中新增的内容
locale helloworld en-US locale/en-US/
locale helloworld fr-FR locale/fr-FR/用实体引用替换XUL中的文本
要让扩展支持多语言，你需要将clock.xul中所有硬编码显示的文本都移动到一个DTD文件中。DTD文件位于locale程序包中，可以自动的使用以匹配用户的语言首选项。编辑clock.xul文件使其与清单8相匹配。添加DOCTYPE声明以引用这个DTD文件，并将“clock”和“current time”用实体引用来代替。清单8：对clock.xul进行修正
创建定义实体引用的DTD文件
现在来创建clock.xul文件中引用到的DTD文件（清单9）。文件clock.dtd应该放在fr-FR文件夹内而且编码必须为UTF-8。清单9：clock.dtd文件的内容
locale\en-US\clock.xul
locale\fr-FR\clock.xul
用properties引用替换javascript文件中的接口消息
可能你的扩展需要为用户线上一些重要的消息，比如警告框。虽然它们嵌在javascript中，但是为了UI的一致性，字符串也应该进行本地化。假设你有字符串嵌入到了一个.js文件中。if ( password == userPassword ) {
oPrefs.setBoolPref("access.authenticated", true);
}
else {
alert ("Invalid password");
......
function clear()
{
sure = confirm("Are you sure?");
首先，你需要在你的locale文件夹内找到或者创建一个myextension.properties文件（注意：总是要以UTF-8方式编码）。然后你可以简单的写入变量名和显示给最终用户的语句或者单词。比如：
wrongPassMessage=Invalid password
areYouSureMessage=Are you sure?
（其中，Invalid password和Are you sure?是将要显示给最终用户的字符串）注意：一个简单的标记就够了
现在回到那个嵌入了这些需要进行本地化的字符串的.js文件中。在这个文件的顶部用要查找字符串的properties文件的地址创建一个string bundle。
var gmyextensionBundle = Components.classes["@mozilla.org/intl/stringbundle;1"].getService(Components.interfaces.nsIStringBundleService);
var _bundle = gmyextensionBundle.createBundle("chrome://myextension/locale/myextension.properties")
现在你可以在.js文件中需要的地方使用你的字符串替代，如下面的例子：
if ( password == userPassword ) {
oPrefs.setBoolPref("access.authenticated", true);
}
else {
alert (_bundle.GetStringFromName("wrongPassMessage"));
function clear() {
sure = confirm(_bundle.GetStringFromName("areYouSureMessage"));}
操作检查
这些需要我们进行操作检查。因为我们改变了chrome清单，我们需要重启一次Firefox，如” 修改源文件后的操作检查”一部分所讨论的那样。重启Firefox并显示clock窗口以确认它能够正常工作。然后，输入about:config到地址栏，将general.useragent.locale的值从en改变为fr，并让clock窗口重新显示以确认它现在显示为法语了。第四阶段:添加一个工具栏按钮
在第四阶段，我们将会使用图像和样式表来创建一个打开这个clock窗口的工具栏按钮（如图9）图9：第四阶段之后的工具栏
目录结构
样式表和图像文件将会放在chrome的skin程序包里面。事实上将这些放在content程序包中该扩展也可以正常工作，但是将它们放到skin程序包中对设计与指定的Firefox主题相匹配的GUI有好处，并且可以让主题开发者为扩展创建特殊的视觉效果。首先，添加skin目录及其所属文件到你的helloworld目录中，如图10所示。这些文件的目的在表4中进行解释。从资源网站上下载文件icon.png和icon-small.png并将它们放到合适的位置。
图10：添加了skin程序包之后的目录结构
添加skin程序包
用清单10中的内容更新chrome.manifest文件。清单10：chrome.manifest文件新增的内容
skin helloworld classic/1.0 skin/classic/
style chrome://browser/content/browser.xul chrome://helloworld/skin/overlay.css
style chrome://global/content/customizeToolbar.xul chrome://helloworld/skin/overlay.css注册skin程序包（skin指令）
以skin开头的第一行用来对skin程序包进行注册；helloworld是程序包名称，skin/classic/是相对于包含该源文件的文件夹的相对路径；classic/1.0说明了这个skin程序包是用于Firefox标准主题的。
样式表跨包叠加（style指令）
在第一阶段，我们使用了overlay指令来激活一个XUL的跨包叠加；要对样式表进行跨包叠加，我们使用style指令。第二三行创建了对浏览器窗口和定制工具栏窗口的叠加。
添加工具栏按钮
要为浏览器窗口添加工具栏按钮，用清单11中的内容更新overlay.xul。为了使用户可以将这个按钮随意改变位置，要添加一个新的toolbarbutton元素，使用特殊的带有id为BrowserToolbarPalette的toolbarpalette元素作为融合点。你也需要添加一个新的command元素，当点击这个工具栏按钮的时候就会以菜单项进行相同的处理。清单11：overlay.xul文件的修改
创建样式表
用清单12中的内容对overlay.css文件进行更新。1-3行定义了完整尺寸的图标要使用的图标图像，4-6行蝶衣了选择小工具栏图标时使用的图标图像。清单12：overlay.css的内容
#helloworldButton {
list-style-image:
url(chrome://helloworld/skin/icon.png);
}
toolbar[iconsize="small"] #helloworldButton {
list-style-image: url(chrome://helloworld/skin/icon-small.png);
}操作检查
由于我们编辑了chrome清单，与第三阶段由于，我们需要重启Firefox。检查以确认当在窗口右上方点击“定制工具栏”的时候新的工具栏按钮出现在弹出的窗口中。将其拖动到工具栏上，并点击以确定其能够正常工作。表4：第四阶段使用的文件
| 名称 |
目的 |
| icon.png |
完整尺寸的工具栏按钮图标文件 |
| icon-small.png |
小工具栏按钮图标文件 |
| overlay.css |
定义工具栏按钮使用的样式表.同时叠加到浏览器窗口和“定制工具栏”窗口。 |
第五阶段: XPI打包
实际上在第四阶段我们已经完成了helloworld扩展，但是在这个状态你无法将源文件发布给其他用户。因此我们需要创建一个xpi格式的安装程序。XPI文件目录结构
XPI基本上就是一个zip结构。但是xpi文件内部的目录结构与你的开发环境目录结构一般是不同的（图11）图11：一个xpi文件内部的目录结构
打包过程
要将你的扩展打包为一个xpi文件而保留在开发过程中使用的源文件的目录结构，可以按照图11进行更改，描述如下：1. 在helloworld目录下创建一个新的chrome目录。
2. 将content、locale和skin目录进行zip压缩，将得到的存档重命名为helloworld.jar，将其放在第一步中创建的chrome目录下。
3. 复制chrome.manifest并重命名为备份chrome.manifest.bak。
4. 改变chrome.manifest文件的内容为清单13中的内容。
5. 将install.rdf、chrome.manifest和chrome文件夹一起以zip方式压缩，并重命名所得的存档为helloworld.xpi。
清单13：更改chrome.manifest文件
content helloworld jar:chrome/helloworld.jar!/content/
overlay chrome://browser/content/browser.xul chrome://helloworld/content/overlay.xul
locale helloworld en-US jar:chrome/helloworld.jar!/locale/en-US/
locale helloworld fr-FR jar:chrome/helloworld.jar!/locale/fr-FR/
skin helloworld classic/1.0 jar:chrome/helloworld.jar!/skin/classic/
style chrome://browser/content/browser.xul chrome://helloworld/skin/overlay.css
style chrome://global/content/customizeToolbar.xul chrome://helloworld/skin/overlay.css这就完成了XPI打包的过程。在第四步中你需要特别注意的一点就是，需要更新chrome.manifest以便它参考的文件具有指向zip结构内部的路径。
为了在你完成对扩展的打包之后回到开发模式，你需要将第四步中编辑了的chrome.manifest进行复原以使其指向第三步中备份的文件。如果你忘了这样做，那么你对源文件做的任何后续的修改都无法在开发中得到反映。你可能想要写一个批处理文件来自动完成这个任务。
有一个更简单的方法来将扩展打包为xpi。创建一个包含install.rdf、chrome.manifest、content、locale以及skin的zip结构。将其命名为helloworld.xpi。
这样避免了创建叫做helloworld.jar的chrome程序包。这种xpi文件可以正常运行，但是会减慢Firefox的启动时间。
XPI操作检查
在你创建了xpi文件之后，要确保其正常工作。由于你已经有了helloworld扩展的开发版本作为测试安装到了你当前的profile，用一个不同的profile重启Firefox。将这个xpi文件拖放到你的浏览器窗口开始安装。这就完成了对如何创建并打包一个简单的hello world扩展的解释。