内嵌选项

Firefox 7 支持新的定义扩展首选项的语法,同时适用于无需启动(bootstrapped)扩展和传统扩展。该新语法定义的首选项用户界面会出现在附加组件管理器的扩展详细视图里。该功能最初出现在 Firefox 移动版,现在已经可以在 Firefox 桌面版使用了。

选项文件

The XUL allowed for the inline options is limited to a few new tags. Here is an example of an options.xul file:

<?xml version="1.0"?>

<!DOCTYPE mydialog SYSTEM "chrome://myaddon/locale/mydialog.dtd">

<vbox xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
  <setting type="bool" pref="extensions.myaddon.bool" title="Boolean" desc="Stored as a boolean preference" />
</vbox>

Note that it's limited to <setting> tags. The root <vbox> just acts as a container, it isn't merged into the main window. If you need script support, see the display notifications section.

设置类型

There are several types of <setting>s, each with a different type attribute:

type attribute displayed as preference stored as
bool checkbox boolean
boolint checkbox integer (use the attributes on and off to specify what values to store)
integer textbox integer
string textbox string
color colorpicker string (in the #123456 format)
file browse button and label string
directory browse button and label string
menulist menulist dependent on the menu item values
radio radio buttons dependent on the radio values
control button no pref stored

The pref attribute should have the full name of the preference to be stored. The title attribute is used as a label for the controls. To set a description, either use the desc attribute, or a text node as a child of the <setting> tag.

Settings are tied to actual preferences, except the button setting, which is designed more for actions.

Some examples:

<!-- Boolean examples -->
<setting pref="extensions.myaddon.bool1" type="bool" title="Boolean 1"/>
<setting pref="extensions.myaddon.bool2" type="bool" title="Boolean 2">
  Description of Boolean 2
</setting>

<!-- Boolean stored as an integer -->
<setting pref="extensions.myaddon.boolInt" type="boolint" title="Boolean 3" on="1" off="2"/>

<!-- Integer example -->
<setting pref="extensions.myaddon.int" type="integer" title="Integer"/>

<!-- String examples -->
<setting pref="extensions.myaddon.text" type="string" title="Text"/>
<setting pref="extensions.myaddon.password" type="string" title="Password" inputtype="password"/>

<!-- Color example -->
<setting pref="extensions.myaddon.color" type="color" title="Color"/>

<!-- File and directory examples -->
<setting pref="extensions.myaddon.file" type="file" title="File"/>
<setting pref="extensions.myaddon.directory" type="directory" title="Directory"/>

<!-- List example (this example would be stored as an integer) -->
<setting pref="extensions.myaddon.options1" type="menulist" title="Options 1">
  <menulist>
    <menupopup>
      <menuitem value="500" label="small"/>
      <menuitem value="800" label="medium"/>
      <menuitem value="1200" label="large"/>
    </menupopup>
  </menulist>
</setting>

<!-- Radio Button example (this example would be stored as a boolean) -->
<setting pref="extensions.myaddon.options2" type="radio" title="Options 2">
  <radiogroup>
    <radio value="false" label="disabled"/>
    <radio value="true" label="enabled"/>
  </radiogroup>
</setting>
 
<!-- Button example - not tied to a preference, but attached to a command -->
<setting title="Do Something" type="control">
  <button id="myaddon-button" label="Click Me" oncommand="alert('Thank you!');"/>
</setting>

显示通知

If you want to use the settings UI for anything more than storing preferences, then you will probably need to initialize them when they first appear. You can't do this until your options XUL has been loaded into the Add-on Manager window, so you should listen for the addon-options-displayed notification to initialize your settings. For example:

var observer = {
  observe: function(aSubject, aTopic, aData) {
    if (aTopic == "addon-options-displayed" && aData == "MY_ADDON@MY_DOMAIN") {
      var doc = aSubject;
      var control = doc.getElementById("myaddon-pref-control");
      control.value = "test";
    }
  }
};

Services.obs.addObserver(observer, "addon-options-displayed", false);
// Don't forget to remove your observer when your add-on is shut down.

This code should be in bootstrap.js (within the startup() function) for restartless extensions or in an XPCOM component or a JavaScript code module (not an overlay!) for traditional extensions.

Gecko 13.0 note
(Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10)

Starting in Gecko 13.0 (Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10), you can also listen for the addon-options-hidden notification, which has the same subject and data as above, to find out when the UI is about to be removed. Use this notification to remove event listeners, or any other references that might otherwise be leaked.

Locating the options file

There are two ways to let the Add-on Manager find your options file:

  • Name the file options.xul and put it in the extension's root folder (alongside install.rdf).
  • Use install.rdf to identify the XUL used for displaying the options. For inline options, you must also specify the optionsType as 2:
    <em:optionsURL>chrome://myaddon/content/options.xul</em:optionsURL>
    <em:optionsType>2</em:optionsType>
    
    You can maintain compatibility with previous versions of Firefox by adding an override to your chrome.manifest:
    override chrome://myaddon/content/options.xul chrome://myaddon/content/oldOptions.xul application={ec8030f7-c20a-464f-9b0e-13a3a9e97384} appversion<=6.*
    

See also

Document Tags and Contributors

Contributors to this page: zbinlin
最后编辑者: zbinlin,