設定ページを実装する
設定ページは、ユーザーに拡張機能の設定を確認して変える方法を与えます(「プリファレンス」や「オプション」とも呼ばれます)。
WebExtension API では一般に、設定はstorage API で保存されます。設定ページの実装は次の 3 ステップの手順です:
- 設定を表示して、ユーザーがそれを変更できる HTML を書く。
- HTML からインクルードされる、ストレージから設定ページに投入し、ユーザーが変更した時に保存された設定を更新するスクリプトを書く。
- HTML ファイルのパスを manifest.json の
options_uiキーに設定する。これにより、HTML 文書が、拡張機能の名前や説明と共に、文書ブラウザーのアドオンマネージャーに表示される。
メモ:runtime.openOptionsPage() 関数を使ってプログラム的に開くこともできます。
簡単な拡張機能
まずは、ユーザーが訪問するページに青い枠をつける拡張機能を書きます。
"settings" というディレクトリーを作り、そこに "manifest.json" という名前のファイルを作って下記の中身を入れます:
{ "manifest_version": 2, "name": "Settings example", "version": "1.0", "content_scripts": [ { "matches": ["<all_urls>"], "js": ["borderify.js"] } ]}この拡張機能はブラウザーに対し、"borderify.js" というコンテンツスクリプトを、ユーザーが訪問するすべてのウェブページで読み込むよう指示します。
次に、"settings" ディレクトリー内に "borderify.js" というファイルを作り、次の中身を入れます:
document.body.style.border = "10px solid blue";これは単にページに青い枠をつけます。
この拡張機能をインストールしてテストします — お好みのあらゆるウェブページを開きます:
設定を追加する
今度は枠の色をユーザーが設定できるような設定ページを作りましょう。
まずは "manifest.json" を次の中身に更新します:
{ "manifest_version": 2, "name": "Settings example", "version": "1.0", "content_scripts": [ { "matches": ["<all_urls>"], "js": ["borderify.js"] } ], "options_ui": { "page": "options.html" }, "permissions": ["storage"], "applications": { "gecko": { "id": "addon@example.com" } }}新しく次の 3 つのキーを追加しました:
options_ui: これは HTML 文書に、この拡張機能の設定ページ(オプションページともいう)であることを設定しますpermissions:storageAPI を使って設定を保存し、この API を使うパーミッションが必要ですapplications: 同期ストレージに設定を読み書きするには、拡張機能の ID を入れておく必要があります
次に "options.html" を提供する約束をしたので、作成します。"settings" ディレクトリー内にその名前でファイルを作成して、次の中身を与えます:
<!doctype html><html> <head> <meta charset="utf-8" /> </head> <body> <form> <label>Border color<input type="text" /></label> <button type="submit">Save</button> </form> <script src="options.js"></script> </body></html>これは<form> と、そこにラベル付きのテキスト<input> と送信<button> を定義します。また "options.js" というスクリプトも入っています。
もう一度 "options.js"を "settings" ディレクトリーに作り、次の中身を与えます:
function saveOptions(e) { e.preventDefault(); browser.storage.sync.set({ color: document.querySelector("#color").value, });}function restoreOptions() { function setCurrentChoice(result) { document.querySelector("#color").value = result.color || "blue"; } function onError(error) { console.log(`Error: ${error}`); } var getting = browser.storage.sync.get("color"); getting.then(setCurrentChoice, onError);}document.addEventListener("DOMContentLoaded", restoreOptions);document.querySelector("form").addEventListener("submit", saveOptions);これは 2 つのことをします:
- 文書が読み込まれた時、"color" の値を
storage.sync.get()を使ってストレージから取り出します。値が未設定なら、既定の "blue" を用います。これで値をsyncストレージ領域から取得できます。 - ユーザーが "Save" を押して送信した時、テキストボックスの値を
storage.sync.set()を用いて保存します。これで値をsyncストレージ領域に保存できます。
メモ:別々の .js ファイルの指定が必要です。インライン JavaScript は使用できません。
ローカルストレージがふさわしいと感じる場合、代わりにローカルストレージに設定値を保存できます。
メモ:Firefox のstorage.sync の実装はアドオン ID に依存しているのに注意します。storage.sync を使う場合、上記 manifest にあるように、manifest.json のapplications キーに拡張機能の ID をセットしておく必要があります。
最後に、ストレージから枠の色を読むのに "borderify.js" を更新します:
警告:バージョン 52 より前の Firefox のbrowser.storage.local.get() のバグにより、下記のコードは機能しません。バージョン 52 より前の Firefox で動作させるには、onGot() の中で 2 回出てくるitem.color をitem[0].color に変えないといけません。
function onError(error) { console.log(`Error: ${error}`);}function onGot(item) { var color = "blue"; if (item.color) { color = item.color; } document.body.style.border = "10px solid " + color;}var getting = browser.storage.sync.get("color");getting.then(onGot, onError);この時点で、拡張機能はこのようになります:
settings/ borderify.js manifest.json options.html options.js
いま、次を行ってみます:
- 拡張機能を再読み込み
- ウェブページを読み込む
- 設定ページを開いて枠の色を変える
- ウェブページを再読み込みして違いを見る
Firefox で設定ページにアクセスするには about:addons に移動して拡張機能のエントリーの隣の "Preferences" ボタンをクリックします。
詳しく学ぶ
options_uiマニフェストキーのリファレンス文書storageAPI のリファレンス文書- 拡張機能から直接設定ページを開くには
runtime.openOptionsPage()API を使う - 設定ページの例: