1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
---
title: 内嵌选项
slug: 扩展/内嵌选项
tags:
- inline options
- 内嵌选项
translation_of: Archive/Add-ons/Inline_Options
---
<p>{{ gecko_minversion_header("7.0") }}</p>
<p>Firefox 7 支持新的定义扩展首选项的语法，同时适用于无需启动（<a href="/en-US/docs/Extensions/Bootstrapped_extensions">bootstrapped</a>）扩展和传统扩展。该新语法定义的首选项用户界面会出现在<a href="/zh-CN/docs/Addons/Add-on_Manager" title="/zh-CN/docs/Addons/Add-on_Manager">附加组件管理器</a>的扩展详细视图里。该功能最初出现在 Firefox 移动版，现在已经可以在 Firefox 桌面版使用了。</p>
<h2 id="选项文件">选项文件</h2>
<p>The XUL allowed for the inline options is limited to a <a class="external" href="http://mxr.mozilla.org/mozilla-central/source/toolkit/mozapps/extensions/content/setting.xml">few new tags</a>. Here is an example of an <code>options.xul</code> file:</p>
<pre class="brush: xml"><?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>
</pre>
<p>Note that it's limited to <code><setting></code> tags. The root <code><vbox></code> just acts as a container, it isn't merged into the main window. If you need script support, see the <a href="#Display_notifications">display notifications</a> section.</p>
<h2 id="设置类型">设置类型</h2>
<p>There are several types of <code><setting></code>s, each with a different <code>type</code> attribute:</p>
<table class="standard-table">
<tbody>
<tr>
<td class="header">type attribute</td>
<td class="header">displayed as</td>
<td class="header">preference stored as</td>
</tr>
<tr>
<td><code>bool</code></td>
<td>{{ XULElem("checkbox") }}</td>
<td>boolean</td>
</tr>
<tr>
<td><code>boolint</code></td>
<td>{{ XULElem("checkbox") }}</td>
<td>integer (use the attributes <code>on</code> and <code>off</code> to specify what values to store)</td>
</tr>
<tr>
<td><code>integer</code></td>
<td>{{ XULElem("textbox") }}</td>
<td>integer</td>
</tr>
<tr>
<td><code>string</code></td>
<td>{{ XULElem("textbox") }}</td>
<td>string</td>
</tr>
<tr>
<td><code>color</code></td>
<td>{{ XULElem("colorpicker") }}</td>
<td>string (in the <code>#123456</code> format)</td>
</tr>
<tr>
<td><code>file</code></td>
<td>browse button and label</td>
<td>string</td>
</tr>
<tr>
<td><code>directory</code></td>
<td>browse button and label</td>
<td>string</td>
</tr>
<tr>
<td><code>menulist</code> {{ gecko_minversion_inline("8.0") }}</td>
<td>{{ XULElem("menulist") }}</td>
<td>dependent on the menu item values</td>
</tr>
<tr>
<td><code>radio</code> {{ gecko_minversion_inline("8.0") }}</td>
<td>{{ XULElem("radio") }} buttons</td>
<td>dependent on the radio values</td>
</tr>
<tr>
<td><code>control</code></td>
<td>{{ XULElem("button") }}</td>
<td>no pref stored</td>
</tr>
</tbody>
</table>
<p>The <code>pref</code> attribute should have the full name of the preference to be stored. The <code>title</code> attribute is used as a label for the controls. To set a description, either use the <code>desc</code> attribute, or a text node as a child of the <code><setting></code> tag.</p>
<p>Settings are tied to actual preferences, except the button setting, which is designed more for actions.</p>
<p>Some examples:</p>
<pre class="brush: xml"><!-- 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>
</pre>
<h2 id="显示通知">显示通知</h2>
<p>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 <code>addon-options-displayed</code> notification to initialize your settings. For example:</p>
<pre class="brush: js">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.
</pre>
<p>This code should be in <code>bootstrap.js</code> (within the <code>startup()</code> function) for restartless extensions or in an XPCOM component or a <a href="/en-US/docs/JavaScript_code_modules">JavaScript code module</a> (not an overlay!) for traditional extensions.</p>
<div class="geckoVersionNote" style="">
<p>{{ gecko_callout_heading("13.0") }}</p>
<p>Starting in Gecko 13.0 {{ geckoRelease("13.0") }}, you can also listen for the <code>addon-options-hidden</code> 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.</p>
</div>
<h2 id="Locating_the_options_file">Locating the options file</h2>
<p>There are two ways to let the Add-on Manager find your options file:</p>
<ul>
<li>Name the file <code>options.xul</code> and put it in the extension's root folder (alongside <code>install.rdf</code>).</li>
<li>Use <a href="/en-US/docs/Install_Manifests"><code>install.rdf</code></a> to identify the XUL used for displaying the options. For inline options, you must also specify the <code>optionsType</code> as <code>2</code>:
<pre class="deki-transform"><em:optionsURL><span class="plain">chrome://myaddon/content/options.xul</span></em:optionsURL>
<em:optionsType>2</em:optionsType>
</pre>
You can maintain compatibility with previous versions of Firefox by adding an override to your <a href="/en-US/docs/Chrome_Registration"><code>chrome.manifest</code></a>:
<pre class="deki-transform"><span class="plain">override chrome://myaddon/content/options.xul chrome://myaddon/content/oldOptions.xul application={ec8030f7-c20a-464f-9b0e-13a3a9e97384} appversion<=6.*</span>
</pre>
</li>
</ul>
<h2 id="See_also">See also</h2>
<ul>
<li><a class="link-https" href="https://wiki.mozilla.org/Mobile/Fennec/Extensions/Options">https://wiki.mozilla.org/Mobile/Fennec/Extensions/Options</a></li>
</ul>
|
