diff options
Diffstat (limited to 'files/ja/mozilla/add-ons/webextensions/api/tabs/executescript/index.html')
| -rw-r--r-- | files/ja/mozilla/add-ons/webextensions/api/tabs/executescript/index.html | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/files/ja/mozilla/add-ons/webextensions/api/tabs/executescript/index.html b/files/ja/mozilla/add-ons/webextensions/api/tabs/executescript/index.html new file mode 100644 index 0000000000..82e1ee1686 --- /dev/null +++ b/files/ja/mozilla/add-ons/webextensions/api/tabs/executescript/index.html @@ -0,0 +1,176 @@ +--- +title: tabs.executeScript() +slug: Mozilla/Add-ons/WebExtensions/API/tabs/executeScript +tags: + - API + - Add-ons + - Extensions + - Method + - Non-standard + - Reference + - WebExtensions + - executeScript + - tabs +translation_of: Mozilla/Add-ons/WebExtensions/API/tabs/executeScript +--- +<div>{{AddonSidebar()}}</div> + +<p>JavaScript のコードをページに挿入します。</p> + +<p>コードを挿入できるページの URL は、<a href="/ja/docs/Mozilla/Add-ons/WebExtensions/Match_patterns">マッチパターン</a> により指定できます。 つまり、URL の scheme 部は、"http", "https", "file", "ftp" のいずれかでなければなりません。そして、その URL に対する明示的な <a href="https://developer.mozilla.org/ja/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host パーミッション</a>、または <a href="/ja/Add-ons/WebExtensions/manifest.json/permissions#activeTab_permission">activeTab パーミッション</a>が必要です。</p> + +<p>また、自らの拡張機能パッケージに含まれるページに対してであれば、次の方法でコードを挿入することも可能です。</p> + +<pre class="brush: js">browser.tabs.create({url: "/my-page.html"}).then(() => { + browser.tabs.executeScript({ + code: `console.log('location:', window.location.href);` + }); +});</pre> + +<p>この場合、特別なパーミッションは必要ありません。</p> + +<p>ブラウザーの組込ページ、例えば about:debugging、about:addons、新規タブを開いた時のページなどには、コードを挿入することは<em>できません</em>。</p> + +<p>挿入するスクリプトのことを、コンテンツスクリプトと呼びます。詳細は <a href="/ja/docs/Mozilla/Add-ons/WebExtensions/Content_scripts">コンテンツスクリプト</a> で学んでください。</p> + +<p>これは、<code><a href="https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> を返す非同期関数です。</p> + +<h2 id="構文">構文</h2> + +<pre class="syntaxbox brush:js">var executing = browser.tabs.executeScript( + tabId, // optional integer + details // object +) +</pre> + +<h3 id="引数">引数</h3> + +<dl> + <dt><code>tabId</code> {{optional_inline}}</dt> + <dd><code>integer</code> 型。 スクリプトを実行するタブの ID。省略時のデフォルトは、現在のウィンドウでアクティブなタブ。</dd> + <dt><code>details</code></dt> + <dd>実行するスクリプトに関するオブジェクト。次のプロパティを持ちます。</dd> + <dd> + <dl class="reference-values"> + <dt><code>allFrames</code> {{optional_inline}}</dt> + <dd><code>boolean</code> 型。<code>true</code> である場合は、現在のページが持つ全てのフレームにコードが挿入されます。<code>true</code> であり、かつ <code>frameId</code> が設定されている場合はエラーが発生するため、frameId と allFrames は互いに排他的です。<code>false</code> である場合は、最上位のフレームにのみコードが挿入されます。デフォルトは <code>false</code> です。</dd> + <dt><code>code</code> {{optional_inline}}</dt> + <dd><code>string</code> 型。挿入されるコードを文字列として表現したもの。<strong>注意:</strong> このプロパティを使って信頼できないデータを JavaScript に挿入しないでください。セキュリティの問題につながります。</dd> + <dt><code>file</code> {{optional_inline}}</dt> + <dd><code>string</code> 型。挿入されるコードを持つファイルへのパス。Firefox では、拡張機能のルートから始まらない相対 URL は、現在のページの URL からの相対位置として解決されます。Chrome では、そのような URL は拡張機能のベース URL からの相対位置として解決されます。複数のブラウザーで動作させるには、拡張機能のルートから始まる相対 URL として指定します。例えば、<code>"/path/to/script.js"</code> のようにします。</dd> + <dt><code>frameId</code> {{optional_inline}}</dt> + <dd><code>integer</code> 型。コードが挿入されるフレーム。デフォルトは <code>0</code> (最上位のフレーム) です。</dd> + <dt><code>matchAboutBlank</code> {{optional_inline}}</dt> + <dd><code>boolean</code> 型。<code>true</code> である場合、コードはその親ドキュメントへのアクセスをもつときに、組込の "about:blank" や "about:srcdoc" フレームにも挿入されます。コードをトップレベルの about: フレームに挿入することはできません。デフォルトは <code>false</code> です。</dd> + <dt><code>runAt</code> {{optional_inline}}</dt> + <dd>{{WebExtAPIRef('extensionTypes.RunAt')}} 型。コードがどの時点でタブに挿入されるかを指定します。デフォルトは "document_idle" です。</dd> + </dl> + </dd> +</dl> + +<h3 id="戻り値">戻り値</h3> + +<p>オブジェクト配列を使って fulfilled 状態にされる <code><a href="https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> です。それぞれのオブジェクトは、フレームに挿入されたスクリプトの結果を表します。</p> + +<p>スクリプトの結果とは最後に評価された文のことです。これは、<a href="/ja/docs/Tools/Web_Console">Webコンソール</a>で実行されたスクリプトの出力 (結果であって、<code>console.log()</code> の出力のことではありません) に似ています。例えば、次のようなスクリプトを挿入したとします。</p> + +<pre class="brush: js">var foo='my result';foo;</pre> + +<p>この場合、結果配列には、文字列 "<code>my result</code>" が含まれます。結果は、<a href="/ja/docs/Web/API/Web_Workers_API/Structured_clone_algorithm">structured clone</a> が可能でなければなりません。最後の文を <code><a href="https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a></code> にすることもできますが、<a href="https://github.com/mozilla/webextension-polyfill#tabsexecutescript">webextension-polyfill</a> ライブラリではサポートされていません。</p> + +<p>エラーが発生した場合、Promise はエラーメッセージを使って rejected 状態にされます。</p> + +<h2 id="使用例">使用例</h2> + +<p>次の例は、現在アクティブなタブで 1 行のコードスニペットを実行します。</p> + +<pre class="brush: 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);</pre> + +<p>次の例は、ファイルからスクリプトを実行します。このファイルは拡張機能のパッケージに含まれており、"content-script.js" という名前です。そのスクリプトは、現在アクティブなタブで実行されますが、メインのドキュメントだけでなく、全てのサブフレームでも実行されます。</p> + +<pre class="brush: 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);</pre> + +<p>次の例は、ファイルからスクリプトを実行します。このファイルは拡張機能のパッケージに含まれており、"content-script.js" という名前です。そのスクリプトは、ID が 2 であるタブで実行されます。</p> + +<pre class="brush: 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);</pre> + +<p>{{WebExtExamples}}</p> + +<h2 id="ブラウザー実装状況">ブラウザー実装状況</h2> + + + +<p>{{Compat("webextensions.api.tabs.executeScript")}}</p> + +<div class="note"><strong>謝辞</strong> + +<p>この API は Chromium の <a href="https://developer.chrome.com/extensions/tabs#method-executeScript"><code>chrome.tabs</code></a> API に基づいています。このドキュメントは <a href="https://chromium.googlesource.com/chromium/src/+/master/chrome/common/extensions/api/tabs.json"><code>tabs.json</code></a> における Chromium のコードに基づいています。</p> +</div> + +<div class="hidden"> +<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +// +// Redistribution and use in source and binary forms, with or without +// modification, are permitted provided that the following conditions are +// met: +// +// * Redistributions of source code must retain the above copyright +// notice, this list of conditions and the following disclaimer. +// * Redistributions in binary form must reproduce the above +// copyright notice, this list of conditions and the following disclaimer +// in the documentation and/or other materials provided with the +// distribution. +// * Neither the name of Google Inc. nor the names of its +// contributors may be used to endorse or promote products derived from +// this software without specific prior written permission. +// +// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +</pre> +</div> |