Join MDN and developers like you at Mozilla's View Source conference, 12-14 September in Berlin, Germany. Learn more at https://viewsourceconf.org

インラインオプション

Firefox 7 以降、拡張機能の設定を定義する新たな構文が使えるようになりました。これは ブートストラップ型 と従来型のいずれでも使用可能です。この新たな構文で定義された設定のユーザインタフェース (UI) は、アドオンマネージャ 内の拡張機能詳細画面に追加されます。この機能は元々 Android 版 Firefox 向けに提供されたもので、後にデスクトップ版 Firefox も対応しました。

オプションファイル

インラインオプションに使用可能な XUL は いくつかの新要素 に限られています。以下が options.xul ファイルの例です。

<?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="真偽値の設定として保存されます" />
</vbox>

なお、ここで実際に使われるのは <setting> 要素だけです。ルートの <vbox> は単なるコンテナとして機能し、メイン画面には組み込まれません。スクリプトによる処理を追加したい場合は、下記 表示通知 の項目を参照してください。

設定の種類

<setting> にはいくつかの種類があり、それぞれ異なる type 属性を持ちます。

type 属性 表示形式 設定の保存形式
bool checkbox 真偽値
boolint checkbox 整数値 (保存される値を指定するには on/off 属性を使用します)
integer textbox 整数値
string textbox 文字列
color colorpicker 文字列 (#123456 の形式)
file 参照ボタンとラベル 文字列
directory 参照ボタンとラベル 文字列
menulist menulist メニュー項目の値による
radio radio ボタン ラジオボタンの値による
control button 設定は保存されません

pref 属性には保存する設定をフルネームで記述します。 title 属性はコントロールのラベルとして使われます。説明を追加するには、desc 属性を使うか、<setting> の子ノードとしてテキストを記述します。

設定は実際の設定値と紐付けられます。ただし、主にアクションに設計されているボタン形式の設定は除きます。

以下にいくつかの例を挙げます。

<!-- 真偽値の例 -->
<setting pref="extensions.myaddon.bool1" type="bool" title="真偽値 1"/>
<setting pref="extensions.myaddon.bool2" type="bool" title="真偽値 2">
  真偽値 2 の説明
</setting>

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

<!-- 整数値の例 -->
<setting pref="extensions.myaddon.int" type="integer" title="整数値"/>

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

<!-- 色の例 -->
<setting pref="extensions.myaddon.color" type="color" title="色"/>

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

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

<!-- ラジオボタンの例 (この例では真偽値として保存されます) -->
<setting pref="extensions.myaddon.options2" type="radio" title="オプション 2">
  <radiogroup>
    <radio value="false" label="無効"/>
    <radio value="true" label="有効"/>
  </radiogroup>
</setting>
 
<!-- ボタンの例 - 設定と紐付けられておらず、代わりにコマンドが設定されています -->
<setting title="何かする" type="control">
  <button id="myaddon-button" label="ここをクリック" oncommand="alert('ありがとう!');"/>
</setting>

表示通知

設定を保存する用途以外にも設定 UI を使いたい場合は、最初に画面へ組み込まれる前に UI を初期化する必要があるでしょう。オプション XUL がアドオンマネージャ画面へ読み込まれるまではそうした処理ができないため、addon-options-displayed 通知を監視し、設定を初期化します。例えば、

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 = "テスト";
    }
  }
};

Services.obs.addObserver(observer, "addon-options-displayed", false);
// アドオンの終了時にオブザーバを削除するのを忘れないでください

このコードは、ブートストラップ型拡張機能の場合は bootstrap.js (startup() 関数内) に記述します。従来型拡張機能の場合は (オーバーレイではなく) XPCOM コンポーネントか JavaScript コードモジュール に記述します。

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

Gecko 13.0 (Firefox 13.0 / Thunderbird 13.0 / SeaMonkey 2.10) 以降、addon-options-hidden 通知も監視できるようになりました。これは上と同じサブジェクトとデータを持ち、UI が削除されようとするタイミングを把握できます。この通知を使って、イベントリスナーなど、削除しないとリークする可能性のある参照を削除しましょう。

オプションファイルの場所の指定

アドオンマネージャがインラインオプションファイルを見つけられるようにする方法は 2 通りあります。

  • ファイル名を options.xul とし、拡張機能のルートディレクトリに (install.rdf と同列に) 置く
  • install.rdf を使ってオプションを表示する XUL を指定する。インラインオプションの場合、値を 2 とした optionsType を追加する必要もあります。
    <em:optionsURL>chrome://myaddon/content/options.xul</em:optionsURL>
    <em:optionsType>2</em:optionsType>
    
    以下のように chrome.manifest にオーバーライドを追加することで、Firefox の旧バージョンとの互換性を保つことができます。
    override chrome://myaddon/content/options.xul chrome://myaddon/content/oldOptions.xul application={ec8030f7-c20a-464f-9b0e-13a3a9e97384} appversion<=6.*
    

参考資料

ドキュメントのタグと貢献者

タグ: 
 このページの貢献者: kohei.yoshino
 最終更新者: kohei.yoshino,