此文章解释如何使用 overlays 为工具包（firefox，Thunderbird 或 Kompozer) 添加工具栏按钮（就是浏览器右上方一系列按钮，home，下载之类的）。适用用户是拥有 XUL 和 CSS 基础知识的 扩展 开发人员。
我们假设您已经会创建基础的火狐插件，并且已经成功创建了 Hello World extension ，另外，还有一份更加完全的初学者示例指南，请查看 自定义工具栏按钮。
创建一个 overlay
The first step is to create an overlay for the document containing the toolbar you wish to enhance. Explaining overlays is beyond the scope of this tutorial -- you can read about them in the XUL Tutorial.
To overlay a document, you need to know its URI. You can find a list of URIs for the most commonly overlaid documents at the bottom of this page.
chrome://messenger/content/mailWindowOverlay.xul. That should cause the button to appear on all windows that mailWindowOverlay.xul is applied to (i.e. Main window and View Message window). This needs to be looked into.在工具栏添加按钮
Toolkit applications have customizable toolbars; therefore, it‘s common practice for extensions to add their toolbar buttons to the toolbar palette, rather than adding them directly to the toolbar. The latter is possible but is not recommended and is harder to implement.
Adding a button to the toolbar palette is very easy. Just add code like this to your overlay:
<toolbarpalette id="BrowserToolbarPalette">
<toolbarbutton id="myextension-button" class="toolbarbutton-1"
label="&toolbarbutton.label;" tooltiptext="&toolbarbutton.tooltip;"
oncommand="MyExtension.onToolbarButtonCommand(event);"/>
</toolbarpalette>注意:
- The
idof the palette (BrowserToolbarPalettein the example) depends on the window whose toolbar you wish to insert a button into. See below for the list of common palette IDs. class="toolbarbutton-1"makes the toolbar button appear correctly in Icons and Text mode; it also adjusts padding.- If you need to handle middle-click, add this line after the oncommand line.
onclick="checkForMiddleClick(this, event)"- you can also handle middle-lick and right-click using
onclickhandler and checkevent.buttonin it. like this:
<toolbarpalette id="BrowserToolbarPalette">
<toolbarbutton id="myextension-button" class="toolbarbutton-1"
label="&toolbarbutton.label;" tooltiptext="&toolbarbutton.tooltip;"
onclick="MyExtension.onclick(event);"/>
</toolbarpalette>onclick: function(event) {
switch(event.button) {
case 0:
// Left click
break;
case 1:
// Middle click
break;
case 2:
// Right click
break;
}
}To add more buttons, put more <toolbarbutton> elements inside the <toolbarpalette> element. Wrap elements other than <toolbarbutton> in<toolbaritem>.
为按键应用风格
Most toolbar buttons have an icon. To attach an image to the button we use standard Mozilla skinning facilities. If you‘re unfamiliar with how that works, read the skinning section of Jonah Bishop‘s excellent Toolbar Tutorial. Although the article covers creating an entire toolbar, rather than just a button, it has a great explanation of the techniques we‘ll use here.
图标大小
Toolbar buttons can have two different sizes -- big and small. This means you‘ll need to provide two icons for each of your toolbar buttons. The dimensions of the icons in various applications for both modes are summarized in the following table (feel free to add information about other applications):
| Application (Theme name) | Big icon size | Small icon size |
|---|---|---|
| Firefox 1.0 (Winstripe) | 24x24 | 16x16 |
| Thunderbird 1.0 (Qute) | 24x24 | 16x16 |
CSS 样式表
To set the image for your toolbar button, use the following CSS rules:
/* skin/toolbar-button.css */
#myextension-button {
list-style-image: url("chrome://myextension/skin/btn_large.png");
}
toolbar[iconsize="small"] #myextension-button {
list-style-image: url("chrome://myextension/skin/btn_small.png");
}应用样式表
Remember to attach the stylesheet you created to both the overlay file and the Customize Toolbar window. To attach it to the overlay, put this processing instruction (PI) at the top of the overlay file:
<?xml-stylesheet href="chrome://myextension/skin/toolbar-button.css" type="text/css"?>chrome.manifest file. This is very important because the toolbar customization dialog won‘t work correctly without this.To include the style on your chrome.manifest file:
style chrome://global/content/customizeToolbar.xul chrome://myextension/skin/toolbar-button.cssIf you are developing for Firefox 1.0, attach it to the Customize Toolbar window (chrome://global/content/customizeToolbar.xul) usingskin/contents.rdf. The code looks like this:
<?xml version="1.0"?>
<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:chrome="http://www.mozilla.org/rdf/chrome#">
<Seq about="urn:mozilla:skin:root">
<li resource="urn:mozilla:skin:classic/1.0"/>
</Seq>
<Description about="urn:mozilla:skin:classic/1.0">
<chrome:packages>
<Seq about="urn:mozilla:skin:classic/1.0:packages">
<li resource="urn:mozilla:skin:classic/1.0:myextension"/>
</Seq>
</chrome:packages>
</Description>
<Seq about="urn:mozilla:stylesheets">
<li resource="chrome://global/content/customizeToolbar.xul"/>
</Seq>
<Seq about="chrome://global/content/customizeToolbar.xul">
<li>chrome://myextension/skin/toolbar-button.css</li>
</Seq>
</RDF>The skin/contents.rdf file is denigrated in developing for later releases of Firefox. Extensions for Firefox/Thunderbird 1.5 and above should instead use something like this in their chrome.manifest:
skin myextension classic/1.0 chrome/skin/
style chrome://global/content/customizeToolbar.xul chrome://myextension/skin/toolbar-button.css
iaTake note of the Packaging section in this article; you may need to include .jar references if you are delivering your extension as a .xpi file.
常见错误
This is a list of the most common mistakes made by extension authors, including both symptoms and solutions.
Problem: The whole set of default buttons is painted on the toolbar or in the Customize Toolbars window, instead of your own icon.
Caused by: Malformed or not applied stylesheet.
Solution: Check to be sure your stylesheet is correct, make sure your contents.rdf (or chrome.manifest) is correct, and be sure you didn‘t forget to apply the stylesheet to customizeToolbar.xul.
常见工具栏的 overlayed windows
| URL | Application and affected window(s) | Palette id |
|---|---|---|
| chrome://browser/content/browser.xul | Firefox - Main window | BrowserToolbarPalette |
| chrome://navigator/content/navigator.xul | SeaMonkey 2.0 - Browser window | BrowserToolbarPalette |
| chrome://messenger/content/messenger.xul | Thunderbird - Main window | MailToolbarPalette |
| chrome://messenger/content/messenger...gercompose.xul | Thunderbird - Compose window | MsgComposeToolbarPalette |
| chrome://messenger/content/addressbo...ddressbook.xul | Thunderbird - Address book | AddressBookToolbarPalette |
| chrome://editor/content/editor.xul | Kompozer - Main window | NvuToolbarPalette |
| chrome://calendar/content/calendar.xul | Sunbird - Main window | calendarToolbarPalette |
更多信息
- XulPlanet.com references:
<toolbarbutton>,<toolbaritem>. - How to adjust toolbarbutton‘s label position
- A forum thread about adding an item to the toolbar (instead of just adding it to palette) right after an extension is installed. Note that doing this is not recommended.
- There is another page on mdc with information about adding buttons to various windows in SeaMonkey. Includes useful information about overlays for ChatZilla.