JavaScript API 群

WebExtension 用の JavaScript API は拡張機能のバックグラウンドスクリプトと、その他の拡張機能にバンドルした文書 (ブラウザーアクションページアクションポップアップやサイドバーオプションページ新規タブページを含む) で使用できます。いくつかの API は拡張機能のコンテンツスクリプトからもアクセスできます (コンテンツスクリプトガイドの表を見てください)。

もっと強力な API を使うには、拡張機能の manifest.jsonパーミッションをリクエストする必要があります。

browser 名前空間内で API にアクセスできます:

js
function logTabs(tabs) {
  console.log(tabs);
}

browser.tabs.query({ currentWindow: true }, logTabs);

API の多くは非同期で、 Promise を返します:

js
function logCookie(c) {
  console.log(c);
}

function logError(e) {
  console.error(e);
}

let setCookie = browser.cookies.set({ url: "/" });
setCookie.then(logCookie, logError);

これは Google Chrome の拡張機能システムでは違っていて、browser の代わりに chrome 名前空間を使い、promise や非同期関数の代わりにコールバックを使っているのに注意してください。移植の助けとして、WebExtensions API の Firefox 実装は browser と promise と同様に chrome とコールバックもサポートします。Mozilla は browser と promise を使うコードが Chrome で変更なく動作する polyfill も書いています: https://github.com/mozilla/webextension-polyfill.

Firefox は chrome 名前空間の下でコールバックを使う API も実装しています。これにより Chrome 向けのコードをここに文書化された API を使って、Firefox で大部分変更なしに実行させることができます。

Microsoft Edge は browser 名前空間を使いますが、promise ベースの非同期 API はサポートされていません。Edge では当面、非同期 API はコールバックを使うのが必須です。

すべてのブラウザーがすべての API をサポートしているわけではありません: 詳しくは JavaScript API のブラウザーサポートをご覧ください。

JavaScript API 一覧

下記の JavaScript API の完全な一覧をご覧ください:

alarms

コードが動作するタイミングを予約します。この API は setTimeout()setInterval() と似ていますが、 alarms API はバックグラウンドで動作する点が異なります。

bookmarks

WebExtensions bookmarks API を利用すると、拡張機能からブラウザーのブックマークシステムにアクセスしたり、操作することができます。ページをブックマークしたり、既存のブックマークを取得したり、ブックマークを編集・削除・整理することが可能です。

browserAction

ブラウザーのツールバーにボタンを追加します。

browserSettings

拡張機能にグローバルなブラウザー設定の変更を可能にします。この API の各プロパティは types.BrowserSetting オブジェクトで、これはそれぞれの設定の変更能力を提供します。これはグローバルな設定のため、拡張機能で衝突が起きる可能性があります。衝突の処理方法の詳細は BrowserSetting.set() の文書を見てください。

browsingData

拡張機能がユーザーの閲覧中に蓄積したデータをクリアできるようにします。

clipboard

クリップボード API は、拡張機能がシステムのクリップボードに要素をクリップするのを可能にします。現在この API は画像のコピーだけをサボートしていますが、将来的にはテキストと HTML のコピーをサボートする計画です。

commands

commands manifest.json キーを使って、登録したコマンドをユーザーが実行するのをリッスンします。

contentScripts

この API はコンテントスクリプトを登録するためにお使いいただけます。コンテントスクリプトを登録することで、指定した URL にマッチするページにそのスクリプトを挿入するようブラウザに指定することができます。

contextualIdentities

contextual identities の操作: contextual identities を一覧、作成、削除、更新します。

cookies

拡張機能に cookie の取得と設定と、変更された時の通知を可能にします。

devtools

拡張機能がブラウザーのDeveloper Toolsと対話することを可能にします。この API を使用して、開発者ツールのページを作成したり、検査対象のウィンドウと対話したり、ページのネットワーク使用状況を検査したりすることができます。

downloads

拡張機能にブラウザーのダウンロードマネージャーとのやりとりを可能にします。この API モジュールを、ファイルマネージャーでのファイルのダウンロード、キャンセル、停止、ダウンロードの再開、ダウンロード済みのファイルの表示に使用できます。

events

イベントをディスパッチする API から使われる共通の型です。

extension

拡張機能に関連するユーティリティ。拡張機能のリソースパッケージの URL を取得したり、拡張機能のページの Window オブジェクトを取得したり、いろいろな設定の値を取得したりします。注意として、このモジュールのメッセージ APIs は非推奨で、 runtime モジュールの同様な API が好まれます。

extensionTypes

その他の WebExtension API で使われる共通な型

find

ウェブページのテキストを検索し、マッチしたものをハイライトします。

history

ブラウザー履歴とやりとりする history API を使用します。

i18n

拡張機能を国際化する関数です。これらの API は、拡張機能に同梱したロケールファイルからローカライズ文字列を取得したり、ブラウザーの現在の言語や、その Accept-Language ヘッダー を調べるために使用します。

identity

identity API を使って OAuth2 の認証コードやアクセストークンを取得し、拡張機能が OAuth2 での認証(Google や Facebook アカウントなど)をサポートするサービスからユーザーデータを取得できるようにします。

idle

ユーザーのシステムがアイドル状態、ロックされた状態、アクティブな状態であるのを発見します。

management

インストール済みのアドオンの管理情報を取得します。

ブラウザーのメニューシステムに項目を追加します。

notifications

OS の通知メカニズムを使って、ユーザーへの通知を表示します。この API は OS の通知メカニズムを使うため、OS とユーザー設定によって通知の現れ方やふるまいは変わってきます。

omnibox

拡張機能に、ユーザーがアドレスバーに入力した時のカスタマイズされた振る舞いを有効にします。

permissions

拡張機能のインストール後、実行時に特別なパーミッションの要求を可能にする。

pkcs11

pkcs11 API は拡張機能にセキュリティモジュール PKCS #11 の列挙を可能とし、キーの元と証明書としてブラウザーからアクセスできるようにします。

privacy

さまざまなプライバシー関連のブラウザー設定にアクセスや変更を行います。

proxy

拡張された Proxy Auto-Configuration (PAC) file (これはウェブのリクエストをプロキシ化するポリシーを実装します) を実装するのにプロキシ API を使います。この実装は標準の PAC 設計といくつかそれていて、なぜなら PAC ファイルのデファクト仕様は 1995 年頃の初期実装から変えられてないためです。仕様を維持している標準化団体はありません。

runtime

このモジュールは拡張機能と実行環境の情報を提供します。

sessions

セッション API を使ってブラウザーが動作している間に閉じたタブやウィンドウを一覧、復帰します。

sidebarAction

拡張機能のサイドバーのプロパティを取得、設定します。

storage

拡張機能にデータの保存、取得と、保存項目の変更をリッスンできるようにします。

tabs

ブラウザーのタブシステムとやりとりします。

theme

ブラウザー拡張機能がブラウザーのテーマを更新できるようにします。

topSites

topSites API を使うと、ユーザーがよく訪れるページをを含む配列を取得できます。

types

ブラウザー設定を表すのに使われる BrowserSetting 型を定義します。

webNavigation

ナビゲーションのいろいろな段階でイベントリスナーを追加します。ナビゲーションにはある URL から他に移動するブラウザーフレームにより成り立っていて、それは(いつもではなく)通常はリンクのクリックやロケーションバーへの URL 入力といったユーザー操作の応答として発生します。

webRequest

websocket が ws:// and wss:// としてリクエストするものも含めた、HTTP リクエスト作成のいろいろなステージでイベントリスナーを追加します。イベントリスナーはリクエストの詳細情報を受け取ったり、リクエストを編集、修正したりします。

windows

ブラウザーウィンドウと相互作用します。この API を使って開いているウィンドウの情報を取得したり、ウィンドウを開き、修正し、閉じることができます。ウィンドウのオープン、クローズ、アクティベートのイベントをリッスンすることもできます。