files/ja/extensions/inline_options/index.html


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
170
171
172

---
title: インラインオプション
slug: Extensions/Inline_Options
tags:
  - Add-ons
  - Extensions
  - XUL
translation_of: Archive/Add-ons/Inline_Options
---
<p>{{ gecko_minversion_header("7.0") }}</p>
<p>Firefox 7 以降、拡張機能の設定を定義する新たな構文が使えるようになりました。これは <a href="/ja/docs/Extensions/Bootstrapped_extensions">ブートストラップ型</a> と従来型のいずれでも使用可能です。この新たな構文で定義された設定のユーザインタフェース (UI) は、<a href="/ja/docs/Addons/Add-on_Manager">アドオンマネージャ</a> 内の拡張機能詳細画面に追加されます。この機能は元々 Android 版 Firefox 向けに提供されたもので、後にデスクトップ版 Firefox も対応しました。</p>
<h2 id="オプションファイル">オプションファイル</h2>
<p>インラインオプションに使用可能な XUL は <a class="external" href="http://mxr.mozilla.org/mozilla-central/source/toolkit/mozapps/extensions/content/setting.xml">いくつかの新要素</a> に限られています。以下が <code>options.xul</code> ファイルの例です。</p>
<pre class="brush: xml">&lt;?xml version="1.0"?&gt;

&lt;!DOCTYPE mydialog SYSTEM "chrome://myaddon/locale/mydialog.dtd"&gt;

&lt;vbox xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"&gt;
  &lt;setting type="bool" pref="extensions.myaddon.bool" title="Boolean" desc="真偽値の設定として保存されます" /&gt;
&lt;/vbox&gt;
</pre>
<p>なお、ここで実際に使われるのは <code>&lt;setting&gt;</code> 要素だけです。ルートの <code>&lt;vbox&gt;</code> は単なるコンテナとして機能し、メイン画面には組み込まれません。スクリプトによる処理を追加したい場合は、下記 <a href="#Display_notifications">表示通知</a> の項目を参照してください。</p>
<h2 id="設定の種類">設定の種類</h2>
<p><code>&lt;setting&gt;</code> にはいくつかの種類があり、それぞれ異なる <code>type</code> 属性を持ちます。</p>
<table class="standard-table">
  <tbody>
    <tr>
      <td class="header">type 属性</td>
      <td class="header">表示形式</td>
      <td class="header">設定の保存形式</td>
    </tr>
    <tr>
      <td><code>bool</code></td>
      <td>{{ XULElem("checkbox") }}</td>
      <td>真偽値</td>
    </tr>
    <tr>
      <td><code>boolint</code></td>
      <td>{{ XULElem("checkbox") }}</td>
      <td>整数値 (保存される値を指定するには <code>on</code>/<code>off</code> 属性を使用します)</td>
    </tr>
    <tr>
      <td><code>integer</code></td>
      <td>{{ XULElem("textbox") }}</td>
      <td>整数値</td>
    </tr>
    <tr>
      <td><code>string</code></td>
      <td>{{ XULElem("textbox") }}</td>
      <td>文字列</td>
    </tr>
    <tr>
      <td><code>color</code></td>
      <td>{{ XULElem("colorpicker") }}</td>
      <td>文字列 (<code>#123456</code> の形式)</td>
    </tr>
    <tr>
      <td><code>file</code></td>
      <td>参照ボタンとラベル</td>
      <td>文字列</td>
    </tr>
    <tr>
      <td><code>directory</code></td>
      <td>参照ボタンとラベル</td>
      <td>文字列</td>
    </tr>
    <tr>
      <td><code>menulist</code> {{ gecko_minversion_inline("8.0") }}</td>
      <td>{{ XULElem("menulist") }}</td>
      <td>メニュー項目の値による</td>
    </tr>
    <tr>
      <td><code>radio</code> {{ gecko_minversion_inline("8.0") }}</td>
      <td>{{ XULElem("radio") }} ボタン</td>
      <td>ラジオボタンの値による</td>
    </tr>
    <tr>
      <td><code>control</code></td>
      <td>{{ XULElem("button") }}</td>
      <td>設定は保存されません</td>
    </tr>
  </tbody>
</table>
<p>
<code>pref</code> 属性には保存する設定をフルネームで記述します。
<code>title</code> 属性はコントロールのラベルとして使われます。説明を追加するには、<code>desc</code> 属性を使うか、<code>&lt;setting&gt;</code> の子ノードとしてテキストを記述します。</p>
<p>設定は実際の設定値と紐付けられます。ただし、主にアクションに設計されているボタン形式の設定は除きます。</p>
<p>以下にいくつかの例を挙げます。</p>
<pre class="brush: xml">&lt;!-- 真偽値の例 --&gt;
&lt;setting pref="extensions.myaddon.bool1" type="bool" title="真偽値 1"/&gt;
&lt;setting pref="extensions.myaddon.bool2" type="bool" title="真偽値 2"&gt;
  真偽値 2 の説明
&lt;/setting&gt;

&lt;!-- 整数値として保存される真偽値 --&gt;
&lt;setting pref="extensions.myaddon.boolInt" type="boolint" title="真偽値 3" on="1" off="2"/&gt;

&lt;!-- 整数値の例 --&gt;
&lt;setting pref="extensions.myaddon.int" type="integer" title="整数値"/&gt;

&lt;!-- 文字列の例 --&gt;
&lt;setting pref="extensions.myaddon.text" type="string" title="テキスト"/&gt;
&lt;setting pref="extensions.myaddon.password" type="string" title="パスワード" inputtype="password"/&gt;

&lt;!-- 色の例 --&gt;
&lt;setting pref="extensions.myaddon.color" type="color" title="色"/&gt;

&lt;!-- ファイルとディレクトリの例 --&gt;
&lt;setting pref="extensions.myaddon.file" type="file" title="ファイル"/&gt;
&lt;setting pref="extensions.myaddon.directory" type="directory" title="ディレクトリ"/&gt;

&lt;!-- リストの例 (この例では整数値として保存されます) --&gt;
&lt;setting pref="extensions.myaddon.options1" type="menulist" title="オプション 1"&gt;
  &lt;menulist&gt;
    &lt;menupopup&gt;
      &lt;menuitem value="500" label="小"/&gt;
      &lt;menuitem value="800" label="中"/&gt;
      &lt;menuitem value="1200" label="大"/&gt;
    &lt;/menupopup&gt;
  &lt;/menulist&gt;
&lt;/setting&gt;

&lt;!-- ラジオボタンの例 (この例では真偽値として保存されます) --&gt;
&lt;setting pref="extensions.myaddon.options2" type="radio" title="オプション 2"&gt;
  &lt;radiogroup&gt;
    &lt;radio value="false" label="無効"/&gt;
    &lt;radio value="true" label="有効"/&gt;
  &lt;/radiogroup&gt;
&lt;/setting&gt;

&lt;!-- ボタンの例 - 設定と紐付けられておらず、代わりにコマンドが設定されています --&gt;
&lt;setting title="何かする" type="control"&gt;
  &lt;button id="myaddon-button" label="ここをクリック" oncommand="alert('ありがとう！');"/&gt;
&lt;/setting&gt;
</pre>
<h2 id="表示通知">表示通知</h2>
<p>設定を保存する用途以外にも設定 UI を使いたい場合は、最初に画面へ組み込まれる前に UI を初期化する必要があるでしょう。オプション XUL がアドオンマネージャ画面へ読み込まれるまではそうした処理ができないため、<code>addon-options-displayed</code> 通知を監視し、設定を初期化します。例えば、</p>
<pre class="brush: js">var observer = {
  observe: function(aSubject, aTopic, aData) {
    if (aTopic == "addon-options-displayed" &amp;&amp; aData == "MY_ADDON@MY_DOMAIN") {
      var doc = aSubject;
      var control = doc.getElementById("myaddon-pref-control");
      control.value = "テスト";
    }
  }
};

Services.obs.addObserver(observer, "addon-options-displayed", false);
// アドオンの終了時にオブザーバを削除するのを忘れないでください
</pre>
<p>このコードは、ブートストラップ型拡張機能の場合は <code>bootstrap.js</code> (<code>startup()</code> 関数内) に記述します。従来型拡張機能の場合は (オーバーレイではなく) XPCOM コンポーネントか <a href="/ja/docs/JavaScript_code_modules">JavaScript コードモジュール</a> に記述します。</p>
<div class="geckoVersionNote" style="">
  <p>{{ gecko_callout_heading("13.0") }}</p>
  <p>Gecko 13.0 {{ geckoRelease("13.0") }} 以降、<code>addon-options-hidden</code> 通知も監視できるようになりました。これは上と同じサブジェクトとデータを持ち、UI が削除されようとするタイミングを把握できます。この通知を使って、イベントリスナーなど、削除しないとリークする可能性のある参照を削除しましょう。</p>
</div>
<h2 id="オプションファイルの場所の指定">オプションファイルの場所の指定</h2>
<p>アドオンマネージャがインラインオプションファイルを見つけられるようにする方法は 2 通りあります。</p>
<ul>
  <li>ファイル名を <code>options.xul</code> とし、拡張機能のルートディレクトリに (<code>install.rdf</code> と同列に) 置く</li>
  <li><a href="/ja/docs/Install_Manifests"><code>install.rdf</code></a> を使ってオプションを表示する XUL を指定する。インラインオプションの場合、値を <code>2</code> とした <code>optionsType</code> を追加する必要もあります。
    <pre class="deki-transform">&lt;em:optionsURL&gt;<span class="plain">chrome://myaddon/content/options.xul</span>&lt;/em:optionsURL&gt;
&lt;em:optionsType&gt;2&lt;/em:optionsType&gt;
</pre>
    以下のように <a href="/ja/docs/Chrome_Registration"><code>chrome.manifest</code></a> にオーバーライドを追加することで、Firefox の旧バージョンとの互換性を保つことができます。
    <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&lt;=6.*</span>
</pre>
  </li>
</ul>
<h2 id="参考資料">参考資料</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>