Скрипты контента

Скрипты контента — это файлы, которые запускаются в контексте веб-страниц. Используя стандартную объектную модель документа (DOM), они могут считывать сведения о веб-страницах, которые посещает браузер, вносить в них изменения и передавать информацию своему родительскому расширению.

Понимание возможностей сценария контента

Скрипты контента могут напрямую обращаться к следующим API расширений:

Сценарии контента не могут напрямую обращаться к другим API. Но они могут получить к ним доступ косвенно, обмениваясь сообщениями с другими частями вашего расширения.

Вы также можете получить доступ к другим файлам в вашем расширении из сценария содержимого, используя API, такие как fetch() . Для этого вам необходимо объявить их как ресурсы, доступные через Интернет . Обратите внимание, что при этом ресурсы также становятся доступными для любых собственных или сторонних сценариев, работающих на том же сайте.

Работа в изолированных мирах

Скрипты контента живут в изолированном мире, что позволяет скрипту контента вносить изменения в свою среду JavaScript, не вступая в конфликт со скриптами контента страницы или других расширений.

Расширение может работать на веб-странице с кодом, подобным следующему примеру.

веб-страница.html

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

Это расширение может внедрить следующий сценарий содержимого, используя один из методов, описанных в разделе «Внедрение сценариев» .

контент-script.js

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

Благодаря этому изменению оба оповещения появляются последовательно при нажатии кнопки.

Внедрить скрипты

Сценарии содержимого могут быть объявлены статически , динамически или программно внедрены .

Внедрить статические объявления

Используйте объявления сценариев статического содержимого в файле манифеста.json для сценариев, которые должны автоматически запускаться на хорошо известном наборе страниц.

Статически объявленные скрипты регистрируются в манифесте под ключом "content_scripts" . Они могут включать файлы JavaScript, файлы CSS или и то, и другое. Все сценарии автозапуска содержимого должны указывать шаблоны соответствия .

манифест.json

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["https://*.nytimes.com/*"],
     "css": ["my-styles.css"],
     "js": ["content-script.js"]
   }
 ],
 ...
}
Имя Тип Описание
matches массив строк Необходимый. Указывает, на какие страницы будет внедрен этот скрипт содержимого. Подробную информацию о синтаксисе этих строк см. в разделе «Шаблоны сопоставления», а также «Шаблоны сопоставления и шаблоны» для получения информации о том, как исключить URL-адреса.
css массив строк Необязательный. Список файлов CSS, которые будут вставлены в соответствующие страницы. Они вводятся в том порядке, в котором они появляются в этом массиве, до того, как будет создан или отображен какой-либо DOM для страницы.
js массив строк Необязательный. Список файлов JavaScript, которые будут внедрены на соответствующие страницы. Файлы внедряются в том порядке, в котором они появляются в этом массиве. Каждая строка в этом списке должна содержать относительный путь к ресурсу в корневом каталоге расширения. Ведущие косые черты (`/`) автоматически обрезаются.
run_at RunAt Необязательный. Указывает, когда сценарий следует внедрить на страницу. По умолчанию — document_idle .
match_about_blank логическое значение Необязательный. Должен ли сценарий внедриться в кадр about:blank , где родительский или открывающий кадр соответствует одному из шаблонов, объявленных в matches . По умолчанию ложь.
match_origin_as_fallback логическое значение Необязательный. Должен ли сценарий внедряться в кадры, созданные соответствующим источником, но URL-адрес или источник которых могут не соответствовать шаблону напрямую. К ним относятся кадры с различными схемами, например about: , data: , blob: и filesystem: . См. также Вставка в связанные кадры .
world ИсполнениеМир Необязательный. Мир JavaScript, в котором выполняется скрипт. По умолчанию ISOLATED . См. также Работа в изолированных мирах .

Внедрить динамические объявления

Сценарии динамического содержимого полезны, когда шаблоны совпадений для сценариев содержимого недостаточно известны или когда сценарии содержимого не всегда следует внедрять на известных хостах.

Динамические объявления, представленные в Chrome 96, аналогичны статическим объявлениям , но объект сценария содержимого регистрируется в Chrome с использованием методов в пространстве имен chrome.scripting , а не в манифесте.json . API сценариев также позволяет разработчикам расширений:

Как и статические объявления, динамические объявления могут включать файлы JavaScript, файлы CSS или и то, и другое.

сервис-worker.js

chrome.scripting
  .registerContentScripts([{
    id: "session-script",
    js: ["content.js"],
    persistAcrossSessions: false,
    matches: ["*://example.com/*"],
    runAt: "document_start",
  }])
  .then(() => console.log("registration complete"))
  .catch((err) => console.warn("unexpected error", err))

сервис-worker.js

chrome.scripting
  .updateContentScripts([{
    id: "session-script",
    excludeMatches: ["*://admin.example.com/*"],
  }])
  .then(() => console.log("registration updated"));

сервис-worker.js

chrome.scripting
  .getRegisteredContentScripts()
  .then(scripts => console.log("registered content scripts", scripts));

сервис-worker.js

chrome.scripting
  .unregisterContentScripts({ ids: ["session-script"] })
  .then(() => console.log("un-registration complete"));

Внедрить программно

Используйте программное внедрение для сценариев контента, которые необходимо запускать в ответ на события или в определенных случаях.

Чтобы программно внедрить сценарий содержимого, вашему расширению необходимы разрешения хоста для страницы, в которую оно пытается внедрить сценарии. Разрешения хоста можно предоставить, запросив их как часть манифеста вашего расширения, или временно используя "activeTab" .

Ниже приведены различные версии расширения на основе activeTab.

манифест.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "activeTab",
    "scripting"
  ],
  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_title": "Action Button"
  }
}

Сценарии содержимого можно внедрить в виде файлов.

контент-script.js


document.body.style.backgroundColor = "orange";

сервис-worker.js:

chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: { tabId: tab.id },
    files: ["content-script.js"]
  });
});

Или тело функции можно внедрить и выполнить как сценарий содержимого.

сервис-worker.js:

function injectedFunction() {
  document.body.style.backgroundColor = "orange";
}

chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target : {tabId : tab.id},
    func : injectedFunction,
  });
});

Имейте в виду, что внедренная функция является копией функции, указанной в вызове chrome.scripting.executeScript() , а не самой исходной функции. В результате тело функции должно быть автономным; ссылки на переменные вне функции приведут к тому, что сценарий содержимого выдаст ошибку ReferenceError .

При внедрении в качестве функции вы также можете передавать ей аргументы.

сервис-worker.js

function injectedFunction(color) {
  document.body.style.backgroundColor = color;
}

chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target : {tabId : tab.id},
    func : injectedFunction,
    args : [ "orange" ],
  });
});

Исключить совпадения и глобусы

Чтобы настроить указанное соответствие страниц, включите следующие поля в декларативную регистрацию.

Имя Тип Описание
exclude_matches массив строк Необязательный. Исключает страницы, в которые в противном случае был бы внедрен этот сценарий содержимого. Подробную информацию о синтаксисе этих строк см. в разделе «Шаблоны совпадений».
include_globs массив строк Необязательный. Применяется после matches , чтобы включать только те URL-адреса, которые также соответствуют этому шаблону. Это предназначено для эмуляции ключевого слова @include Greasemonkey.
exclude_globs массив строк Необязательный. Применяется после matches , чтобы исключить URL-адреса, соответствующие этому шаблону. Предназначен для эмуляции ключевого слова @exclude Greasemonkey.

Сценарий содержимого будет внедрен на страницу, если выполняются оба следующих условия:

  • Его URL-адрес соответствует любому шаблону matches и любому шаблону include_globs .
  • URL-адрес также не соответствует шаблону exclude_matches или exclude_globs . Поскольку свойство matches является обязательным, exclude_matches , include_globs и exclude_globs можно использовать только для ограничения того, какие страницы будут затронуты.

Следующее расширение вводит сценарий содержимого в https://www.nytimes.com/health , но не в https://www.nytimes.com/business .

манифест.json

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

сервис-worker.js

chrome.scripting.registerContentScripts([{
  id : "test",
  matches : [ "https://*.nytimes.com/*" ],
  excludeMatches : [ "*://*/*business*" ],
  js : [ "contentScript.js" ],
}]);

Свойства Glob имеют другой, более гибкий синтаксис, чем шаблоны сопоставления . Допустимыми glob-строками являются URL-адреса, которые могут содержать подстановочные знаки и звездочки. Звездочка ( * ) соответствует любой строке любой длины, включая пустую строку, а знак вопроса ( ? ) соответствует любому одиночному символу.

Например, glob https://???.example.com/foo/\* соответствует любому из следующих значений:

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

Однако он не соответствует следующему:

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

Это расширение вставляет скрипт содержимого в https://www.nytimes.com/arts/index.html и https://www.nytimes.com/jobs/index.htm* , но не в https://www.nytimes.com/sports/index.html :

манифест.json

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

Это расширение внедряет сценарий содержимого в https://history.nytimes.com и https://.nytimes.com/history , но не в https://science.nytimes.com или https://www.nytimes.com/science :

манифест.json

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

Для достижения правильной области действия можно включить один, все или некоторые из них.

манифест.json

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

Время выполнения

Поле run_at определяет, когда файлы JavaScript внедряются на веб-страницу. Предпочтительным значением по умолчанию является "document_idle" . Другие возможные значения см. в типе RunAt .

манифест.json

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.nytimes.com/*"],
      "run_at": "document_idle",
      "js": ["contentScript.js"]
    }
  ],
  ...
}

сервис-worker.js

chrome.scripting.registerContentScripts([{
  id : "test",
  matches : [ "https://*.nytimes.com/*" ],
  runAt : "document_idle",
  js : [ "contentScript.js" ],
}]);
Имя Тип Описание
document_idle нить Предпочтительно. Используйте "document_idle" когда это возможно.

Браузер выбирает время для внедрения скриптов между "document_end" и сразу после срабатывания события window.onload . Точный момент внедрения зависит от того, насколько сложен документ и сколько времени занимает его загрузка, и оптимизирован для скорости загрузки страницы.

Сценариям содержимого, работающим в "document_idle" не нужно прослушивать событие window.onload , они гарантированно запустятся после завершения DOM. Если сценарий обязательно должен быть запущен после window.onload , расширение может проверить, запущена ли уже onload , используя свойство document.readyState .
document_start нить Скрипты вводятся после любых файлов из css , но до создания любого другого DOM или запуска любого другого скрипта.
document_end нить Скрипты внедряются сразу после завершения DOM, но до загрузки подресурсов, таких как изображения и фреймы.

Укажите рамки

Поле "all_frames" позволяет расширению указать, следует ли вставлять файлы JavaScript и CSS во все кадры, соответствующие указанным требованиям URL-адреса, или только в самый верхний кадр на вкладке.

манифест.json

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.nytimes.com/*"],
      "all_frames": true,
      "js": ["contentScript.js"]
    }
  ],
  ...
}

сервис-worker.js

chrome.scripting.registerContentScripts([{
  id: "test",
  matches : [ "https://*.nytimes.com/*" ],
  allFrames : true,
  js : [ "contentScript.js" ],
}]);
Имя Тип Описание
all_frames логическое значение Необязательный. По умолчанию установлено значение false , что означает, что сопоставляется только верхний кадр.

Если указано true , будут вставлены все кадры, даже если этот кадр не является самым верхним кадром на вкладке. Каждый кадр проверяется независимо на соответствие требованиям URL. Он не будет внедряться в дочерние фреймы, если требования URL-адреса не соблюдены.

Расширения могут захотеть запускать сценарии в кадрах, которые связаны с совпадающим кадром, но сами не совпадают. Обычным сценарием в этом случае являются фреймы с URL-адресами, которые были созданы совпадающим фреймом, но чьи URL-адреса сами по себе не соответствуют шаблонам, указанным в сценарии.

Это тот случай, когда расширение хочет внедрить в кадры URL-адреса, имеющие схемы about: , data: , blob: и filesystem: В этих случаях URL-адрес не будет соответствовать шаблону сценария содержимого (а в случае about: и data: вообще не включайте родительский URL-адрес или источник в URL-адрес, как в about:blank или data:text/html,<html>Hello, World!</html> ). Однако эти кадры по-прежнему можно связать с создающим кадром.

Для внедрения в эти кадры расширения могут указать свойство "match_origin_as_fallback" в спецификации сценария содержимого в манифесте.

манифест.json

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["https://*.google.com/*"],
      "match_origin_as_fallback": true,
      "js": ["contentScript.js"]
    }
  ],
  ...
}

Если указано значение true , Chrome будет проверять происхождение инициатора кадра, чтобы определить, соответствует ли кадр, а не URL-адрес самого кадра. Обратите внимание, что это также может отличаться от источника целевого кадра (например, data: URL-адреса имеют нулевое происхождение).

Инициатором кадра является кадр, который создал или перемещался по целевому кадру. Хотя обычно это прямой родительский элемент или средство открытия, это может быть и не так (как в случае с фреймом, перемещающимся по iframe внутри iframe).

Поскольку при этом сравнивается источник кадра-инициатора, кадр-инициатор может находиться на любом пути от этого источника. Чтобы прояснить этот вывод, Chrome требует, чтобы все сценарии содержимого, для которых "match_origin_as_fallback" был установлен в true , также указывали путь * .

Если указаны оба "match_origin_as_fallback" и "match_about_blank" , приоритет имеет "match_origin_as_fallback" .

Связь со страницей встраивания

Хотя среды выполнения сценариев контента и страниц, на которых они размещены, изолированы друг от друга, они имеют общий доступ к DOM страницы. Если страница желает взаимодействовать со сценарием содержимого или с расширением через сценарий содержимого, она должна делать это через общий DOM.

Пример можно реализовать с помощью window.postMessage() :

контент-script.js

var port = chrome.runtime.connect();

window.addEventListener("message", (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);

пример.js

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

Страница без расширения, example.html, отправляет сообщения самому себе. Это сообщение перехватывается и проверяется сценарием содержимого, а затем отправляется в процесс расширения. Таким образом, страница устанавливает канал связи с процессом расширения. Обратное возможно с помощью аналогичных средств.

Доступ к файлам расширений

Чтобы получить доступ к файлу расширения из сценария содержимого, вы можете вызвать chrome.runtime.getURL() чтобы получить абсолютный URL-адрес вашего ресурса расширения, как показано в следующем примере ( content.js ):

контент-script.js

let image = chrome.runtime.getURL("images/my_image.png")

Чтобы использовать шрифты или изображения в файле CSS, вы можете использовать @@extension_id для создания URL-адреса, как показано в следующем примере ( content.css ):

контент.css

body {
 background-image:url('chrome-extension://__MSG_@@extension_id__/background.png');
}

@font-face {
 font-family: 'Stint Ultra Expanded';
 font-style: normal;
 font-weight: 400;
 src: url('chrome-extension://__MSG_@@extension_id__/fonts/Stint Ultra Expanded.woff') format('woff');
}

Все ресурсы должны быть объявлены как доступные через Интернет ресурсы в файле manifest.json :

манифест.json

{
 ...
 "web_accessible_resources": [
   {
     "resources": [ "images/*.png" ],
     "matches": [ "https://example.com/*" ]
   },
   {
     "resources": [ "fonts/*.woff" ],
     "matches": [ "https://example.com/*" ]
   }
 ],
 ...
}

Оставайтесь в безопасности

Хотя изолированные миры обеспечивают уровень защиты, использование сценариев содержимого может создать уязвимости в расширении и веб-странице. Если сценарий контента получает контент с отдельного веб-сайта, например, при вызове fetch() , будьте осторожны, чтобы отфильтровать контент от атак с использованием межсайтовых сценариев перед его внедрением. Общайтесь только через HTTPS, чтобы избежать атак «человек посередине» .

Обязательно отфильтруйте вредоносные веб-страницы. Например, следующие шаблоны опасны и запрещены в Манифесте V3:

Не

контент-script.js

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

контент-script.js

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

Вместо этого отдайте предпочтение более безопасным API, которые не запускают сценарии:

Делать

контент-script.js

const data = document.getElementById("json-data")
// JSON.parse does not evaluate the attacker's scripts.
const parsed = JSON.parse(data);
Делать

контент-script.js

const elmt_id = ...
// The closure form of setTimeout does not evaluate scripts.
window.setTimeout(() => animate(elmt_id), 200);