tabs.executeScript()
====================

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

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

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


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


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

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

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

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

構文
--


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

### 引数

`tabId` 省略可

`integer` 型。 スクリプトを実行するタブの ID。省略時のデフォルトは、現在のウィンドウでアクティブなタブ。

`details`

実行するスクリプトに関するオブジェクト。次のプロパティを持ちます。

`allFrames` 省略可

`boolean` 型。`true` である場合は、現在のページが持つ全てのフレームにコードが挿入されます。`true` であり、かつ `frameId` が設定されている場合はエラーが発生するため、frameId と allFrames は互いに排他的です。`false` である場合は、最上位のフレームにのみコードが挿入されます。デフォルトは `false` です。

`code` 省略可

`string` 型。挿入されるコードを文字列として表現したもの。**注意:** このプロパティを使って信頼できないデータを JavaScript に挿入しないでください。セキュリティの問題につながります。

`file` 省略可

`string` 型。挿入されるコードを持つファイルへのパス。Firefox では、拡張機能のルートから始まらない相対 URL は、現在のページの URL からの相対位置として解決されます。Chrome では、そのような URL は拡張機能のベース URL からの相対位置として解決されます。複数のブラウザーで動作させるには、拡張機能のルートから始まる相対 URL として指定します。例えば、`"/path/to/script.js"` のようにします。

`frameId` 省略可

`integer` 型。コードが挿入されるフレーム。デフォルトは `0` (最上位のフレーム) です。

`matchAboutBlank` 省略可

`boolean` 型。`true` である場合、コードはその親ドキュメントへのアクセスをもつときに、組込の "about:blank" や "about:srcdoc" フレームにも挿入されます。コードをトップレベルの about: フレームに挿入することはできません。デフォルトは `false` です。

`runAt` 省略可

`extensionTypes.RunAt` 型。コードがどの時点でタブに挿入されるかを指定します。デフォルトは "document\_idle" です。


### 戻り値

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

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


```js
var foo = "my result";
foo;
```


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

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

使用例
---

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


```js
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" という名前です。そのスクリプトは、現在アクティブなタブで実行されますが、メインのドキュメントだけでなく、全てのサブフレームでも実行されます。


```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 であるタブで実行されます。


```js
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

* beastify
* context-menu-copy-link-with-types
* devtools-panels
* imagify
* menu-demo
* menu-remove-element
ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

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