JavaScript API 群の利用

WebExtension JavaScript API にアクセスできるのは、アドオンの background scriptsbrowser action 、そしてアドオンを定義する page action popups です。WebExtensions API の中には、アドオンの content scripts から利用できる API もあります(詳細は list in the content script guide を参照してください)。

より強力な API を利用する場合、アドオンの manifest.json で パーミッションを申請 する必要があります。

WebExtensions API には 2 つの名前空間 chrome / browser からアクセスできます。

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

chrome.tabs.query({currentWindow: true}, logTabs);
function logTabs(tabs) {
  console.log(tabs);
}

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

両者はほぼ等価ですが、以下の点でのみ異なります。

  • 名前空間 browser は Google Chrome からアクセスできないため、同じコードを Chrome でも動作させるには chrome の名前空間からアクセスする必要があります。
  • 名前空間 browser を用いると、非同期メソッドにおいてコールバック関数の代わりに Promise を利用できます。詳しくは次項の コールバック関数と Promise で説明します。

JavaScript API 群の一覧 も参照してください。

コールバック関数と Promise

多くの API は非同期的に実行されるため、戻り値はコールバック関数を介して返されます。

これらのメソッドがエラーを報告すると extension.lastError に値がセットされます。lastError がセットされうるメソッドを利用する際は、コールバック関数の中で lastError を確認する必要があります。

例として、あるアドオンが Cookie を設定するパーミッションを取得していなかった場合、cookies.set() メソッドは lastError をセットします。

function logCookie(c) {
  if (browser.extension.lastError) {
    console.error(browser.extension.lastError);
  } else {
    console.log(c);
  }
}

browser.cookies.set(
  {url: "https://developer.mozilla.org/"},
  logCookie
);

名前空間に browser を利用する際は、コールバック関数を省略することが可能です。その場合、メソッドは戻り値として Promise を返します。Promise.then() の第一引数にはコールバック関数に与えられていた引数が渡され、第二引数には lastError が渡されます。

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

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

var setCookie = browser.cookies.set(
  {url: "https://developer.mozilla.org/"}
);
setCookie.then(logCookie, logError);

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

 このページの貢献者: hashedhyphen
 最終更新者: hashedhyphen,