tabs.executeScript()

JavaScript のコードをページに挿入します。

コードを挿入できるページの URL は、マッチパターン により指定できます。 つまり、URL の scheme 部は、"http", "https", "file", "ftp" のいずれかでなければなりません。そして、その URL に対する明示的な host パーミッション、または activeTab パーミッションが必要です。

また、自らの拡張機能パッケージに含まれるページに対してであれば、次の方法でコードを挿入することも可能です。

browser.tabs.create({url: "/my-page.html"}).then(() => {
  browser.tabs.executeScript({
    code: `console.log('location:', window.location.href);`
  });
});

この場合、特別なパーミッションは必要ありません。

ブラウザーの組込ページ、例えば about:debugging、about:addons、新規タブを開いた時のページなどには、コードを挿入することはできません

挿入するスクリプトのことを、コンテンツスクリプトと呼びます。詳細は コンテンツスクリプト で学んでください。

これは、Promise を返す非同期関数です。

構文

var executing = browser.tabs.executeScript(
  tabId,                 // optional integer
  details                // object
)

引数

tabId Optional
integer 型。 スクリプトを実行するタブの ID。省略時のデフォルトは、現在のウィンドウでアクティブなタブ。
details
実行するスクリプトに関するオブジェクト。次のプロパティを持ちます。
allFrames Optional
boolean 型。true である場合は、現在のページが持つ全てのフレームにコードが挿入されます。true であり、かつ frameId が設定されている場合はエラーが発生するため、frameId と allFrames は互いに排他的です。false である場合は、最上位のフレームにのみコードが挿入されます。デフォルトは false です。
code Optional
string 型。挿入されるコードを文字列として表現したもの。注意: このプロパティを使って信頼できないデータを JavaScript に挿入しないでください。セキュリティの問題につながります。
file Optional
string 型。挿入されるコードを持つファイルへのパス。Firefox では、拡張機能のルートから始まらない相対 URL は、現在のページの URL からの相対位置として解決されます。Chrome では、そのような URL は拡張機能のベース URL からの相対位置として解決されます。複数のブラウザーで動作させるには、拡張機能のルートから始まる相対 URL として指定します。例えば、"/path/to/script.js" のようにします。
frameId Optional
integer 型。コードが挿入されるフレーム。デフォルトは 0 (最上位のフレーム) です。
matchAboutBlank Optional
boolean 型。true である場合、コードはその親ドキュメントへのアクセスをもつときに、組込の "about:blank" や "about:srcdoc" フレームにも挿入されます。コードをトップレベルの about: フレームに挿入することはできません。デフォルトは false です。
runAt Optional
extensionTypes.RunAt 型。コードがどの時点でタブに挿入されるかを指定します。デフォルトは "document_idle" です。

戻り値

オブジェクト配列を使って fulfilled 状態にされる Promise です。それぞれのオブジェクトは、フレームに挿入されたスクリプトの結果を表します。

スクリプトの結果とは最後に評価された文のことです。これは、Webコンソールで実行されたスクリプトの出力 (結果であって、console.log() の出力のことではありません) に似ています。例えば、次のようなスクリプトを挿入したとします。

var foo='my result';foo;

この場合、結果配列には、文字列 "my result" が含まれます。結果は、structured clone が可能でなければなりません。最後の文を Promise にすることもできますが、webextension-polyfill ライブラリではサポートされていません。

エラーが発生した場合、Promise はエラーメッセージを使って rejected 状態にされます。

使用例

次の例は、現在アクティブなタブで 1 行のコードスニペットを実行します。

function onExecuted(result) {
  console.log(`グリーンにしました`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

var makeItGreen = 'document.body.style.border = "5px solid green"';

var executing = browser.tabs.executeScript({
  code: makeItGreen
});
executing.then(onExecuted, onError);

次の例は、ファイルからスクリプトを実行します。このファイルは拡張機能のパッケージに含まれており、"content-script.js" という名前です。そのスクリプトは、現在アクティブなタブで実行されますが、メインのドキュメントだけでなく、全てのサブフレームでも実行されます。

function onExecuted(result) {
  console.log(`全てのサブフレームで実行しました`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

var executing = browser.tabs.executeScript({
  file: "/content-script.js",
  allFrames: true
});
executing.then(onExecuted, onError);

次の例は、ファイルからスクリプトを実行します。このファイルは拡張機能のパッケージに含まれており、"content-script.js" という名前です。そのスクリプトは、ID が 2 であるタブで実行されます。

function onExecuted(result) {
  console.log(`タブ 2 で実行しました`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

var executing = browser.tabs.executeScript(
  2, {
    file: "/content-script.js"
});
executing.then(onExecuted, onError);

Example extensions

ブラウザー実装状況

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxOperaAndroid 版 Firefox
executeScriptChrome 完全対応 あり
補足
完全対応 あり
補足
補足 Extensions can't inject scripts into their own pages using this API.
Edge 完全対応 14Firefox 完全対応 43
補足
完全対応 43
補足
補足 Before version 50, Firefox would pass a single result value into its callback rather than an array, unless 'allFrames' had been set.
Opera 完全対応 あり
補足
完全対応 あり
補足
補足 Extensions can't inject scripts into their own pages using this API.
Firefox Android 完全対応 54
frameIdChrome 完全対応 39Edge 完全対応 79Firefox 完全対応 43
補足
完全対応 43
補足
補足 'allFrames' and 'frameId' can't both be set at the same time.
Opera 完全対応 26Firefox Android 完全対応 54
補足
完全対応 54
補足
補足 'allFrames' and 'frameId' can't both be set at the same time.
matchAboutBlankChrome 完全対応 39Edge 完全対応 14Firefox 完全対応 53Opera 完全対応 26Firefox Android 完全対応 54
runAtChrome 完全対応 20Edge 完全対応 79Firefox 完全対応 43Opera 完全対応 15Firefox Android 完全対応 54

凡例

完全対応  
完全対応
実装ノートを参照してください。
実装ノートを参照してください。
謝辞

この API は Chromium の chrome.tabs API に基づいています。このドキュメントは tabs.json における Chromium のコードに基づいています。