內容指令碼

內容指令碼是指在網頁情境中執行的檔案。透過標準的文件物件模型 (DOM)，擴充功能就能讀取瀏覽器造訪的網頁詳細資料、變更這些資料，並將資訊傳遞至上層擴充功能。

瞭解內容指令碼功能

內容指令碼可以透過與擴充功能交換訊息，存取其父項擴充功能使用的 Chrome API。他們也可以使用 chrome.runtime.getURL() 存取擴充功能檔案的網址，並使用與其他網址相同的結果。

// Code for displaying EXTENSION_DIR/images/myimage.png:
var imgURL = chrome.runtime.getURL("images/myimage.png");
document.getElementById("someImage").src = imgURL;

此外，內容腳本可以直接存取下列 Chrome API：

內容指令碼無法直接存取其他 API。

在隔離的世界中工作

內容指令碼會在獨立環境中執行，因此可讓內容指令碼變更其 JavaScript 環境，且不會與網頁或其他內容指令碼發生衝突。

擴充功能可能會在網頁中執行，程式碼類似於以下範例。

<html>
  <button id="mybutton">click me</button>
  <script>
    var greeting = "hello, ";
    var button = document.getElementById("mybutton");
    button.person_name = "Bob";
    button.addEventListener("click", function() {
      alert(greeting + button.person_name + ".");
    }, false);
  </script>
</html>

該擴充功能可能會插入下列內容指令碼。

var greeting = "hola, ";
var button = document.getElementById("mybutton");
button.person_name = "Roberto";
button.addEventListener("click", function() {
  alert(greeting + button.person_name + ".");
}, false);

按下按鈕時，系統會顯示這兩則警示。

在隔離世界中，內容指令碼、擴充功能和網頁無法存取其他項目建立的任何變數或函式。這也讓內容指令碼能夠啟用網頁不應存取的功能。

插入指令碼

您可以以程式輔助或以宣告方式插入內容指令碼。

以程式輔助方式插入

針對需要在特定情況下執行的內容指令碼，使用程式輔助插入功能。

如要插入程式輔助內容指令碼，請在資訊清單中提供 activeTab 權限。這麼做可安全存取目前網站的代管服務器，並暫時存取「分頁」權限，讓內容指令碼能在目前的有效分頁中執行，而無須指定跨來源權限。

{
  "name": "My extension",
  ...
  "permissions": [
    "activeTab"
  ],
  ...
}

內容指令碼可做為程式碼插入。

chrome.runtime.onMessage.addListener(
  function(message, callback) {
    if (message == "changeColor"){
      chrome.tabs.executeScript({
        code: 'document.body.style.backgroundColor="orange"'
      });
    }
  });

或者，也可以注入整個檔案。

chrome.runtime.onMessage.addListener(
  function(message, callback) {
    if (message == "runContentScript"){
      chrome.tabs.executeScript({
        file: 'contentScript.js'
      });
    }
  });

以宣告方式插入

針對應在指定網頁上自動執行的內容指令碼，使用宣告式插入功能。

宣告式插入的腳本會在資訊清單的 "content_scripts" 欄位下註冊。可包含 JavaScript 檔案、CSS 檔案或兩者皆有。所有自動執行內容指令碼都必須指定比對模式。

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["http://*.nytimes.com/*"],
     "css": ["myStyles.css"],
     "js": ["contentScript.js"]
   }
 ],
 ...
}
名稱 類型 說明
matches {: #matches } 字串陣列 必填。指定要將這個內容指令碼插入哪些網頁。如要進一步瞭解這些字串的語法，請參閱「比對模式」一文；如要瞭解如何排除網址，請參閱「比對模式和 glob」一文。
css {: #css } 字串陣列 選填。要插入相符網頁的 CSS 檔案清單。這些項目會按照陣列中的顯示順序注入，在任何 DOM 為網頁建構或顯示之前。
js {: #js } 字串陣列 選填。要插入相符網頁的 JavaScript 檔案清單。這些值會依照陣列中的顯示順序注入。
match_about_blank {: #match_about_blank } 布林值 選填。是否應將指令碼插入 about:blank 框架，其中父項或開啟者框架與 matches 中宣告的任一模式相符。預設為 false。

排除相符項目和 glob

如要自訂指定的網頁比對，請在資訊清單註冊中加入下列欄位。

名稱 類型 說明
exclude_matches {: #exclude_matches } 字串陣列 選填。排除這項內容指令碼會注入的網頁。如要進一步瞭解這些字串的語法，請參閱「比對模式」。
include_globs {: #include_globs } 字串陣列 選填。在 matches 之後套用，只納入與此 glob 相符的網址。旨在模擬 @include Greasemonkey 關鍵字。
exclude_globs {: #exclude_globs } 字串陣列 選填。會在 matches 之後套用，用於排除與此 glob 相符的網址。旨在模擬 @exclude Greasemonkey 關鍵字。

如果網址符合任何 matches 模式和任何 include_globs 模式，且不符合 exclude_matches 或 exclude_globs 模式，系統就會將內容指令碼插入網頁。

由於 matches 屬性為必要屬性，exclude_matches、include_globs 和 exclude_globs 只能用於限制受影響的網頁。

下列擴充功能會將內容指令碼插入 http://www.nytimes.com/ health，但不會插入 http://www.nytimes.com/ business。

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

Glob 屬性採用與比對模式不同的語法，且更具彈性。可接受的 glob 字串是可能包含「萬用字元」星號和問號的網址。星號 * 可比對任何長度的字串，包括空白字串，而問號 ?與任何單一字元比對。

舉例來說，glob http:// ??? .example.com/foo/ * 會比對下列任一項目：

  • http:// www .example.com/foo /bar
  • http:// the .example.com/foo /

但不符合下列條件：

  • http:// my .example.com/foo/bar
  • http:// example .com/foo/
  • http://www.example.com/foo

這個擴充功能會將內容指令碼插入 http:/www.nytimes.com/ arts /index.html 和 http://www.nytimes.com/ jobs /index.html，但不會插入 http://www.nytimes.com/ sports/index.html。

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "include_globs": ["*nytimes.com/???s/*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

這個擴充功能會將內容指令碼插入 http:// history .nytimes.com 和 http://.nytimes.com/ history，但不會插入 http:// science .nytimes.com 或 http://www.nytimes.com/ science。

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "exclude_globs": ["*science*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

您可以加入其中一個、全部或部分，以便取得正確的範圍。

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*nytimes.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

執行時間

run_at 欄位會控制 JavaScript 檔案何時插入網頁。預設欄位為 "document_idle"，但如有需要，也可以指定為 "document_start" 或 "document_end"。

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "run_at": "document_idle",
      "js": ["contentScript.js"]
    }
  ],
  ...
}
名稱 類型 說明
document_idle {: #document_idle } 字串 建議使用。盡可能使用 "document_idle"。

瀏覽器會在 "document_end" 和 windowonload 事件觸發後立即選擇時間，以便插入指令碼。具體的插入時機取決於文件的複雜程度和載入時間，並針對頁面載入速度進行最佳化。

在 "document_idle" 執行的內容指令碼不需要監聽 window.onload 事件，因為系統會保證在 DOM 完成後執行這些指令碼。如果指令碼確實需要在 window.onload 後執行，擴充功能可以使用 document.readyState 屬性，檢查 onload 是否已觸發。
document_start {: #document_start } 字串 指令碼會在 css 的任何檔案之後，但在任何其他 DOM 建構或任何其他指令碼執行之前插入。
document_end {: #document_end } 字串 系統會在 DOM 完成後立即插入指令碼，但在圖片和框架等子資源載入之前。

指定影格

"all_frames" 欄位可讓擴充功能指定 JavaScript 和 CSS 檔案應插入符合指定網址需求的所有框架，還是只插入分頁中位於最上方的框架。

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "all_frames": true,
      "js": ["contentScript.js"]
    }
  ],
  ...
}
名稱 類型 說明
all_frames {: #all_frames } 布林值 選填。預設為 false，表示只會比對頂層影格。

如果指定 true，系統會將其插入所有影格，即使該影格不是分頁中頂層影格也一樣。系統會個別檢查每個影格是否符合網址規定，如果不符合規定，就不會將影格插入子影格。

與嵌入頁面的通訊

雖然內容指令碼的執行環境與代管這些指令碼的網頁彼此隔離，但兩者都會共用網頁的 DOM 存取權。如果網頁想要與內容指令碼通訊，或透過內容指令碼與擴充功能通訊，則必須透過共用 DOM 進行。

您可以使用 window.postMessage 完成以下範例：

var port = chrome.runtime.connect();

window.addEventListener("message", function(event) {
  // We only accept messages from ourselves
  if (event.source != window)
    return;

  if (event.data.type && (event.data.type == "FROM_PAGE")) {
    console.log("Content script received: " + event.data.text);
    port.postMessage(event.data.text);
  }
}, false);

document.getElementById("theButton").addEventListener("click",
    function() {
  window.postMessage({ type: "FROM_PAGE", text: "Hello from the webpage!" }, "*");
}, false);

非擴充功能的網頁 example.html 會將訊息發布至自身。這個訊息會遭到內容指令碼攔截及檢查，然後發布至擴充功能程序。如此一來，頁面就能與擴充程序建立通訊管道。反向操作可透過類似方式進行。

保障安全

雖然隔離世界可提供一層保護，但使用內容指令碼可能會在擴充功能和網頁中造成安全漏洞。如果內容指令碼從其他網站接收內容 (例如建立 XMLHttpRequest)，請務必先篩選內容跨網站指令碼攻擊，再將內容插入。請僅透過 HTTPS 進行通訊，以免遭受"man-in-the-middle"攻擊。

請務必篩除惡意網頁。舉例來說，下列模式都很危險：

var data = document.getElementById("json-data")
// WARNING! Might be evaluating an evil script!
var parsed = eval("(" + data + ")")

var elmt_id = ...
// WARNING! elmt_id might be "); ... evil script ... //"!
window.setTimeout("animate(" + elmt_id + ")", 200);

請改用不執行指令碼的更安全 API：

var data = document.getElementById("json-data")
// JSON.parse does not evaluate the attacker's scripts.
var parsed = JSON.parse(data);

var elmt_id = ...
// The closure form of setTimeout does not evaluate scripts.
window.setTimeout(function() {
  animate(elmt_id);
}, 200);