WebExtention は複数のファイルで構成されており、それらのファイルが配布・インストール用にパッケージ化されたものです。この記事では、WebExtension に含まれるファイルについて簡単に説明します。
1 つの WebExtension には必ず "manifest.json" というファイルが含まれています。この manifest には、下記のファイルに対する参照を含めることができます。
- background pages: 長時間動作するロジックを実装するもの
- content scripts: Web ページとやり取りするもの
- browser action files: ツールバー上のボタンを実装するもの
- page action files: アドレスバーにボタンを追加するもの
- options pages: define a UI for users to view and change your add-on's settings
- web-accessible resources: パッケージ内のファイルから Web ページや content scripts にアクセスできるようにするもの
manifest.json
WebExtension において唯一不可欠なファイルが manifest.json です。このファイルには名前やバージョン、必要とするパーミッションなど、拡張機能に関する基本的なメタデータが含まれます。加えて、アドオンに含まれている他のファイルへの参照も含んでいます。
詳細は manifest.json のリファレンスを参照して下さい。
Background scripts
しばしば WebExtensions は、web ページやブラウザウィンドウと独立したうえで、状態を長く維持したり処理を長時間実行する必要があります。background scripts はそのような場合のためのスクリプトなのです。
background scripts は拡張機能が読み込まれると同時にロードされ、拡張機能が無効にされるかアンインストールされるまでロードされた状態を維持します。あらかじめ要求された必要な パーミッション の限りにおいて、スクリプト中で WebExtention API を使うことができます。
background scripts を定義する
"manifest.json" の中に background キーを用いることで background script をインクルードできます。
// manifest.json
"background": {
"scripts": ["background-script.js"]
}
複数の background scripts を定義することも可能であり、その場合は web ページに複数のスクリプトが読み込まれているのと同様に、スクリプトは同じコンテキストを共有します。
Background script の実行環境
DOM APIs
background scripts は background pages と呼ばれる特殊なページのコンテキストで動作します。このコンテキストでは、グローバルオブジェクト window と付随する標準 DOM API すべてが利用可能です。
自分で background page を用意する必要はなく、background script をインクルードした際に空の background page が作成されます。
とはいえ、別個の HTML ファイルとして background page を自分で用意することも可能です。
// manifest.json
"background": {
"page": "background-page.html"
}
WebExtension APIs
background scripts は、拡張機能が持つ パーミッション の範囲で WebExtension API にアクセスできます。
Cross-origin access
background scripts は、拡張機能が持つ host パーミッション に一致するホストに XHR リクエストを送信できます。
Browser actions
拡張機能で browser action が定義されており、かつ browser action がポップアップを持っていなければ、browserAction の onClicked オブジェクトで browser action ボタンのクリックイベントをリッスンすることができます。
chrome.browserAction.onClicked.addListener(handleClick);Web content
background scripts から web ページに直接アクセスすることができません。しかし、web ページに content scripts を読み込ませれば、message-passing API を使って content scripts と通信することができます。
Content security policy
background scripts は Content Security Policy による制約を受けており、eval() のように危険な処理は実行できません。詳細は Content Security Policy を参照してください。
Content scripts
web ページにアクセスしたり操作するには content scripts が用いられます。content scripts は web ページに読み込まれて実行されます。
content scripts はアドオンが提供するスクリプトであり、web ページのコンテキスト内で動作します。このため、<script> 要素で取得されたものなど、そのページ自身が読み込んだスクリプトとは異なります。
web ページに読み込まれた通常のスクリプトと同様に、content scripts も web ページの DOM へアクセスできます。
通常のスクリプトと異なるのは、content scripts で以下のことが可能な点です。
- クロスドメインの XHR リクエストを作成できる
- WebExtension API の小さなサブセットを利用できる
- background scripts とメッセージの交換ができ、この方法ですべての WebExtension API に間接的にアクセスできる
content scripts から通常のスクリプトに直接アクセスすることはできませんが、標準化されている window.postMessage() API を用いれば、スクリプト間でメッセージを交換することが可能です。
ここでの議論対象である content script とは基本的に JavaScript のことを指していますが、先ほどと同じ方法で Web ページに CSS を差し込むこともできます。
詳しくは content scripts の記事を参照してください。
Browser actions
browser action とは、ツールバー上に加えたボタンのことを指します。ボタンをクリックすることにより、ユーザと拡張機能の間でやり取りすることができます。
ボタンに対応する ポップアップ を HTML / CSS / JavaScript で定義することもできます。
ポップアップを定義していない場合、ユーザがボタンをクリックすると拡張機能に向けてイベントが送出されます。このイベントは browserAction.onClicked で捕捉できます。
chrome.browserAction.onClicked.addListener(handleClick);ただし、ポップアップを定義している場合は click イベントは送出されず、代わりにポップアップが表示されます。ユーザはこの状態でポップアップを操作することができ、またポップアップの外をクリックすると自動で閉じます。
拡張機能はただ一つの browser action しか持つことができないことに注意してください。
browser action を定義する
browser action のプロパティ（アイコン / タイトル / ポップアップ）は manifest.json の browser_action キーで定義します。
"browser_action": {
"default_icon": {
"19": "button/geo-19.png",
"38": "button/geo-38.png"
},
"default_title": "Whereami?",
"default_popup": "popup/geo.html"
}唯一不可欠なキーは default_icon です。なお、上に示されている任意のプロパティは browserAction API を使ったコードからも変更できます。
ポップアップ
通常の Web ページと同じく、ポップアップは HTML ファイルで定義されます（ここに CSS や JavaScript も含めることが可能です）。 ただし、拡張機能が持つ パーミッション の範囲で JavaScript から WebExtension APIs にアクセスできる点で通常のものと異なります。
Firefox 48 以降では、ブラウザの UI と統一感を持たせるスタイルシートをポップアップに組み込めるようになりました。これを利用するには、browser_action キーで "browser_style": true を指定してください。
ポップアップをプログラムから閉じたい場合は、ポップアップ上のスクリプトから window.close() を呼び出してください。Firefox の場合は Firefox 47 からサポートされていることに注意が必要です。
ポップアップにおけるリソースの読み込み元や、eval() のように安全でない処理は Content Security Policy によって制限されます。詳細は Content Security Policy を参照してください。
Page actions
page actions は browser actions とほとんど同じですが、以下の点で異なります。
- browser actions は常に表示され、基本的にいつでも適用可能な動作に使います。
- page actions は特定のページでだけ意味をもつ動作に使われ、特定のタブがアクティブな時のみ表示されます。
page actions が特定のページと密に紐づいていることを示すため、メインツールバーでなくアドレスバーに表示されます。
page actions は manifest.json の page_action キーで定義され、pageAction API を使って操作します。
browser actions と異なり、page action はデフォルトで隠れています。そのため、pageAction.show() または pageAction.hide() を呼び出すことで、特定のタブ上での表示・非表示を制御します。
Options pages
options pages とは、ユーザから変更できるような WebExtension を設定画面を定義するものです。ユーザはアドオンマネージャを通じて、アドオンの option pages にアクセスできます。
このページにユーザがアクセスする方法や、ブラウザ UI との連携についてはブラウザによって異なります。
options page は以下のように作成します。
- opiton page を定義する HTML ファイルを作成します。通常の web ページと同じく、このファイルに CSS と JavaScript を含めることもできます。この option page で動かす JavaScript は、permissions の範囲で利用可能な WebExtension API すべてにアクセスできます。特に、設定を保存するために
storageAPI が利用できます。 - これらのファイルをアドオンの中にパッケージ化します。
- manifest.json に
options_uiキーを追加し、option page への URL を指定します。
この option page は、プログラムから runtime.openOptionsPage() を呼び出して開くこともできます。
option pages におけるリソースの読み込み元や、eval() のように安全でない処理は Content Security Policy によって制限されます。詳細は Content Security Policy を参照してください。
Web accessible resources
Web accessible resources とは、拡張機能にインクルードして content scripts や Web ページのスクリプトからアクセスできるリソースのことであり、代表的なものは画像や HTML / CSS / JavaScript です。web-accessible なリソースは、特殊なURIスキームを介して web ページのスクリプトや content scripts から参照できます。
例えば content script から Web ページ内に画像を挿入したい場合、拡張機能に画像をインクルードして web-accessible とし、画像を src 属性で参照する img タグを content script が作成して web ページに追加する、といったシナリオが考えられます。