สคริปต์เนื้อหา

สคริปต์เนื้อหาคือไฟล์ที่ทำงานในบริบทของหน้าเว็บ การใช้ Document Object Model (DOM) มาตรฐานช่วยให้ส่วนขยายอ่านรายละเอียดของหน้าเว็บที่เบราว์เซอร์เข้าชม ทำการเปลี่ยนแปลง และส่งข้อมูลไปยังส่วนขยายหลักได้

ทําความเข้าใจความสามารถของสคริปต์เนื้อหา

สคริปต์เนื้อหาเข้าถึง Chrome API ที่ใช้โดยส่วนขยายหลักได้โดยแลกเปลี่ยนข้อความกับส่วนขยาย นอกจากนี้ ยังเข้าถึง URL ของไฟล์ส่วนขยายได้ด้วย chrome.runtime.getURL() และใช้ผลลัพธ์ได้เช่นเดียวกับ URL อื่นๆ

// 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);

การแจ้งเตือนทั้ง 2 รายการจะปรากฏขึ้นหากมีการกดปุ่ม

โลกที่แยกต่างหากไม่อนุญาตให้สคริปต์เนื้อหา ส่วนขยาย และหน้าเว็บเข้าถึงตัวแปรหรือฟังก์ชันที่สร้างขึ้นโดยผู้อื่น นอกจากนี้ ยังช่วยให้สคริปต์เนื้อหาเปิดใช้ฟังก์ชันการทำงานที่หน้าเว็บไม่ควรเข้าถึงได้

แทรกสคริปต์

คุณสามารถแทรกสคริปต์เนื้อหาแบบเป็นโปรแกรมหรือแบบประกาศได้

แทรกแบบเป็นโปรแกรม

ใช้การแทรกแบบเป็นโปรแกรมสำหรับสคริปต์เนื้อหาที่ต้องทํางานในบางโอกาส

หากต้องการแทรกสคริปต์เนื้อหาแบบเป็นโปรแกรม ให้ระบุสิทธิ์ activeTab ในไฟล์ Manifest ซึ่งจะมอบสิทธิ์เข้าถึงที่ปลอดภัยในโฮสต์ของเว็บไซต์ที่ใช้งานอยู่และสิทธิ์เข้าถึงแท็บชั่วคราว ซึ่งช่วยให้สคริปต์เนื้อหาทำงานในแท็บที่ใช้งานอยู่ในปัจจุบันได้โดยไม่ต้องระบุสิทธิ์ข้ามแหล่งที่มา

{
  "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'
      });
    }
  });

แทรกแบบประกาศ

ใช้การแทรกแบบประกาศสำหรับสคริปต์เนื้อหาที่ควรเรียกใช้โดยอัตโนมัติในหน้าเว็บที่ระบุ

สคริปต์ที่แทรกแบบประกาศจะลงทะเบียนในไฟล์ Manifest ในส่วนฟิลด์ "content_scripts" โดยอาจประกอบด้วยไฟล์ JavaScript, ไฟล์ CSS หรือทั้ง 2 ไฟล์ สคริปต์เนื้อหาที่ทำงานอัตโนมัติทั้งหมดต้องระบุรูปแบบการจับคู่

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["http://*.nytimes.com/*"],
     "css": ["myStyles.css"],
     "js": ["contentScript.js"]
   }
 ],
 ...
}
ชื่อ ประเภท คำอธิบาย
matches {: #matches } อาร์เรย์สตริง ต้องระบุ ระบุหน้าที่ระบบจะแทรกสคริปต์เนื้อหานี้ ดูรายละเอียดเพิ่มเติมเกี่ยวกับไวยากรณ์ของสตริงเหล่านี้ได้ที่รูปแบบการจับคู่ และดูข้อมูลเกี่ยวกับวิธียกเว้น URL ได้ที่รูปแบบการจับคู่และนิพจน์ทั่วไป
css {: #css } อาร์เรย์สตริง ไม่บังคับ รายการไฟล์ CSS ที่จะแทรกลงในหน้าที่ตรงกัน รายการเหล่านี้จะแทรกตามลําดับที่ปรากฏในอาร์เรย์นี้ ก่อนที่ DOM จะสร้างขึ้นหรือแสดงสําหรับหน้าเว็บ
js {: #js } อาร์เรย์สตริง ไม่บังคับ รายการไฟล์ JavaScript ที่จะแทรกลงในหน้าเว็บที่ตรงกัน ระบบจะแทรกรายการเหล่านี้ตามลำดับที่ปรากฏในอาร์เรย์นี้
match_about_blank {: #match_about_blank } บูลีน ไม่บังคับ กำหนดว่าสคริปต์ควรแทรกลงในเฟรม about:blank เมื่อเฟรมหลักหรือเฟรมเปิดตรงกับรูปแบบใดรูปแบบหนึ่งที่ประกาศไว้ใน matches หรือไม่ ค่าเริ่มต้นคือ false

ยกเว้นการจับคู่และนิพจน์ทั่วไป

คุณสามารถปรับแต่งการจับคู่หน้าเว็บที่ระบุได้โดยใส่ช่องต่อไปนี้ในไฟล์ Manifest การลงทะเบียน

ชื่อ ประเภท คำอธิบาย
exclude_matches {: #exclude_matches } อาร์เรย์สตริง ไม่บังคับ ยกเว้นหน้าที่สคริปต์เนื้อหานี้จะแทรกเข้าไป ดูรายละเอียดเพิ่มเติมเกี่ยวกับไวยากรณ์ของสตริงเหล่านี้ได้ที่รูปแบบการจับคู่
include_globs {: #include_globs } อาร์เรย์สตริง ไม่บังคับ ใช้หลังจาก matches เพื่อรวมเฉพาะ URL ที่ตรงกับนิพจน์ทั่วไปนี้ด้วย มีไว้เพื่อเลียนแบบคีย์เวิร์ด @include ของ Greasemonkey
exclude_globs {: #exclude_globs } อาร์เรย์สตริง ไม่บังคับ ใช้หลังจาก matches เพื่อยกเว้น URL ที่ตรงกับรูปแบบทั่วไปนี้ มีไว้เพื่อเลียนแบบคีย์เวิร์ด @excludeGreasemonkey

ระบบจะแทรกสคริปต์เนื้อหาลงในหน้าเว็บหาก URL ของหน้าตรงกับรูปแบบ matches และรูปแบบ include_globs ใดก็ได้ ตราบใดที่ URL นั้นไม่ตรงกับรูปแบบ 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 ใช้ไวยากรณ์ที่ยืดหยุ่นกว่ารูปแบบการทำงานของคีย์เวิร์ด สตริงที่ยอมรับคือ URL ที่อาจมีเครื่องหมายดอกจันและเครื่องหมายคําถาม "ไวลด์การ์ด" เครื่องหมายดอกจัน * จะจับคู่กับสตริงที่มีความยาวเท่าใดก็ได้ รวมถึงสตริงว่าง ส่วนเครื่องหมายคําถาม ? จับคู่กับอักขระเดี่ยวตัวใดก็ได้

เช่น นิพจน์ทั่วไป 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 อย่างแน่นอน ส่วนขยายจะตรวจสอบได้ว่า onload เริ่มทํางานแล้วหรือยังโดยใช้พร็อพเพอร์ตี้ document.readyState
document_start {: #document_start } สตริง ระบบจะแทรกสคริปต์หลังจากไฟล์จาก css แต่ก่อนที่ระบบจะสร้าง DOM อื่นๆ หรือเรียกใช้สคริปต์อื่นๆ
document_end {: #document_end } สตริง ระบบจะแทรกสคริปต์ทันทีหลังจากที่ DOM เสร็จสมบูรณ์ แต่ก่อนที่ทรัพยากรย่อย เช่น รูปภาพและเฟรมจะโหลด

ระบุเฟรม

ช่อง "all_frames" ช่วยให้ส่วนขยายระบุได้ว่าควรแทรกไฟล์ JavaScript และ CSS ลงในเฟรมทั้งหมดที่ตรงกับข้อกําหนดของ URL ที่ระบุ หรือแทรกลงในเฟรมบนสุดในแท็บเท่านั้น

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "all_frames": true,
      "js": ["contentScript.js"]
    }
  ],
  ...
}
ชื่อ ประเภท คำอธิบาย
all_frames {: #all_frames } บูลีน ไม่บังคับ ค่าเริ่มต้นคือ false ซึ่งหมายความว่าระบบจะจับคู่เฉพาะเฟรมบนสุด

หากระบุ true ระบบจะแทรกลงในเฟรมทั้งหมด แม้ว่าเฟรมนั้นจะไม่ใช่เฟรมบนสุดในแท็บก็ตาม ระบบจะตรวจสอบเฟรมแต่ละเฟรมแยกกันเพื่อดูข้อกําหนดของ URL และจะไม่แทรกลงในเฟรมย่อยหากไม่เป็นไปตามข้อกําหนดของ URL

การสื่อสารกับหน้าการฝัง

แม้ว่าสภาพแวดล้อมการเรียกใช้สคริปต์เนื้อหาและหน้าเว็บที่โฮสต์สคริปต์จะแยกจากกัน แต่สคริปต์และหน้าเว็บก็แชร์สิทธิ์เข้าถึง 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);