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

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

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

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

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

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

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

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

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

webPage.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>

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

content-script.js

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

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

Внедрение скриптов

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

Внедрение с помощью статических объявлений

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

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

manifest.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 . По умолчанию — false.
match_origin_as_fallback логический Необязательно. Указывает, следует ли скрипту внедрять скрипт в фреймы, созданные соответствующим источником, но чей URL-адрес или источник могут не соответствовать шаблону напрямую. К ним относятся фреймы с различными схемами, такими как about: data: blob: и filesystem: См. также Внедрение в связанные фреймы .
world ExecutionWorld Необязательный параметр. Область выполнения скрипта на JavaScript. По умолчанию используется ISOLATED . См. также «Работа в изолированных средах» .

На определенном этапе жизненного цикла документа первыми внедряются скрипты содержимого, объявленные статически в манифесте, прежде чем внедряются скрипты содержимого, зарегистрированные любым другим способом. Они внедряются в том порядке, в котором указаны в манифесте.

Внедрение с помощью динамических объявлений

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

Введенные в Chrome 96, динамические объявления похожи на статические , но объект скрипта содержимого регистрируется в Chrome с помощью методов в пространстве имен browser.scripting , а не в manifest.json . API скриптинга также позволяет разработчикам расширений:

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

service-worker.js

browser.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))

service-worker.js

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

service-worker.js

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

service-worker.js

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

Внедрение программным способом

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

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

Ниже представлены различные версии расширения, основанного на функции activeTab.

manifest.json:

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

Скрипты контента можно внедрять в виде файлов.

content-script.js


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

service-worker.js: 

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

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

service-worker.js: 

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

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

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

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

service-worker.js 

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

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

Исключить спички и шарики

Для настройки соответствия указанным страницам включите следующие поля в декларативную регистрацию.

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

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

  • Его 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 .

manifest.json 

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

service-worker.js 

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

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

Например, шаблон 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 :

manifest.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 .

manifest.json 

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

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

manifest.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 для получения информации о других возможных значениях.

manifest.json 

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

service-worker.js 

browser.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, или только в самый верхний фрейм во вкладке:

manifest.json 

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

При программной регистрации скриптов содержимого с помощью browser.scripting.registerContentScripts(...) параметр allFrames можно использовать для указания того, следует ли внедрять скрипт содержимого во все фреймы, соответствующие указанным требованиям URL, или только в самый верхний фрейм во вкладке. Это можно использовать только с tabId и нельзя использовать, если указаны frameIds или documentIds:

service-worker.js 

browser.scripting.registerContentScripts([{
  id: "test",
  matches : [ "https://*.nytimes.com/*" ],
  allFrames : true,
  js : [ "contentScript.js" ],
}]);

Расширения могут захотеть запускать скрипты во фреймах, которые связаны с соответствующим фреймом, но сами не соответствуют ему. Распространенный сценарий в этом случае — это фреймы с 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" в спецификации скрипта содержимого в манифесте.

manifest.json 

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

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

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

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

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

Взаимодействие со страницей встраивания

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

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

content-script.js 

var port = browser.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, отправляет сообщения самой себе. Это сообщение перехватывается и анализируется скриптом содержимого, а затем отправляется в процесс расширения. Таким образом, страница устанавливает канал связи с процессом расширения. Обратный процесс возможен аналогичным образом.

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

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

content-script.js 

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

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

content.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 как доступные через веб-интерфейс :

manifest.json 

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

Политика безопасности контента

Скрипты контента, работающие в изолированных средах, имеют следующую политику безопасности контента (CSP): 

script-src 'self' 'wasm-unsafe-eval' 'inline-speculation-rules' chrome-extension://abcdefghijklmopqrstuvwxyz/; object-src 'self';

Подобно ограничениям, применяемым к другим контекстам расширений, это предотвращает использование функции eval() , а также загрузку внешних скриптов.

Для распакованных расширений CSP также включает localhost: 

script-src 'self' 'wasm-unsafe-eval' 'inline-speculation-rules' http://localhost:* http://127.0.0.1:* chrome-extension://abcdefghijklmopqrstuvwxyz/; object-src 'self';

Когда скрипт контента внедряется в основной контент, применяются правила CSP этой страницы.

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

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

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

Не

content-script.js 

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

content-script.js 

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

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

Делать

content-script.js 

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

content-script.js 

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

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

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

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

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

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

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

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

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

webPage.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>

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

content-script.js

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

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

Внедрение скриптов

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

Внедрение с помощью статических объявлений

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

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

manifest.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 . По умолчанию — false.
match_origin_as_fallback логический Необязательно. Указывает, следует ли скрипту внедрять скрипт в фреймы, созданные соответствующим источником, но чей URL-адрес или источник могут не соответствовать шаблону напрямую. К ним относятся фреймы с различными схемами, такими как about: data: blob: и filesystem: См. также Внедрение в связанные фреймы .
world ExecutionWorld Необязательный параметр. Область выполнения скрипта на JavaScript. По умолчанию используется ISOLATED . См. также «Работа в изолированных средах» .

На определенном этапе жизненного цикла документа первыми внедряются скрипты содержимого, объявленные статически в манифесте, прежде чем внедряются скрипты содержимого, зарегистрированные любым другим способом. Они внедряются в том порядке, в котором указаны в манифесте.

Внедрение с помощью динамических объявлений

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

Введенные в Chrome 96, динамические объявления похожи на статические , но объект скрипта содержимого регистрируется в Chrome с помощью методов в пространстве имен browser.scripting , а не в manifest.json . API скриптинга также позволяет разработчикам расширений:

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

service-worker.js

browser.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))

service-worker.js

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

service-worker.js

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

service-worker.js

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

Внедрение программным способом

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

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

Ниже представлены различные версии расширения, основанного на функции activeTab.

manifest.json:

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

Скрипты контента можно внедрять в виде файлов.

content-script.js


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

service-worker.js: 

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

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

service-worker.js: 

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

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

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

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

service-worker.js 

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

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

Исключить спички и шарики

Для настройки соответствия указанным страницам включите следующие поля в декларативную регистрацию.

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

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

  • Его 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 .

manifest.json 

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

service-worker.js 

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

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

Например, шаблон 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 :

manifest.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 .

manifest.json 

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

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

manifest.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 для получения информации о других возможных значениях.

manifest.json 

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

service-worker.js 

browser.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, или только в самый верхний фрейм во вкладке:

manifest.json 

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

При программной регистрации скриптов содержимого с помощью browser.scripting.registerContentScripts(...) параметр allFrames можно использовать для указания того, следует ли внедрять скрипт содержимого во все фреймы, соответствующие указанным требованиям URL, или только в самый верхний фрейм во вкладке. Это можно использовать только с tabId и нельзя использовать, если указаны frameIds или documentIds:

service-worker.js 

browser.scripting.registerContentScripts([{
  id: "test",
  matches : [ "https://*.nytimes.com/*" ],
  allFrames : true,
  js : [ "contentScript.js" ],
}]);

Расширения могут захотеть запускать скрипты во фреймах, которые связаны с соответствующим фреймом, но сами не соответствуют ему. Распространенный сценарий в этом случае — это фреймы с 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" в спецификации скрипта содержимого в манифесте.

manifest.json 

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

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

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

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

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

Взаимодействие со страницей встраивания

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

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

content-script.js 

var port = browser.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, отправляет сообщения самой себе. Это сообщение перехватывается и анализируется скриптом содержимого, а затем отправляется в процесс расширения. Таким образом, страница устанавливает канал связи с процессом расширения. Обратный процесс возможен аналогичным образом.

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

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

content-script.js 

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

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

content.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 как доступные через веб-интерфейс :

manifest.json 

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

Политика безопасности контента

Скрипты контента, работающие в изолированных средах, имеют следующую политику безопасности контента (CSP): 

script-src 'self' 'wasm-unsafe-eval' 'inline-speculation-rules' chrome-extension://abcdefghijklmopqrstuvwxyz/; object-src 'self';

Подобно ограничениям, применяемым к другим контекстам расширений, это предотвращает использование функции eval() , а также загрузку внешних скриптов.

Для распакованных расширений CSP также включает localhost: 

script-src 'self' 'wasm-unsafe-eval' 'inline-speculation-rules' http://localhost:* http://127.0.0.1:* chrome-extension://abcdefghijklmopqrstuvwxyz/; object-src 'self';

Когда скрипт контента внедряется в основной контент, применяются правила CSP этой страницы.

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

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

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

Не

content-script.js 

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

content-script.js 

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

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

Делать

content-script.js 

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

content-script.js 

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

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

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

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

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

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

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

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

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

webPage.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>

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

content-script.js

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

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

Внедрение скриптов

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

Внедрение с помощью статических объявлений

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

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

manifest.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 . По умолчанию — false.
match_origin_as_fallback логический Optional. Whether the script should inject in frames that were created by a matching origin, but whose URL or origin may not directly match the pattern. These include frames with different schemes, such as about: , data: , blob: , and filesystem: . See also Injecting in related frames .
world ExecutionWorld Optional. The JavaScript world for a script to execute within. Defaults to ISOLATED . See also Work in isolated worlds .

Within a given stage of the document lifecycle, content scripts declared statically in the manifest are the first to be injected, before content scripts registered in any other way. They are injected in the order in which they are specified in the manifest.

Inject with dynamic declarations

Dynamic content scripts are useful when the match patterns for content scripts are not well known or when content scripts shouldn't always be injected on known hosts.

Introduced in Chrome 96, dynamic declarations are similar to static declarations , but the content script object is registered with Chrome using methods in the browser.scripting namespace rather than in manifest.json . The Scripting API also allows extension developers to:

Like static declarations, dynamic declarations can include JavaScript files, CSS files, or both.

service-worker.js

browser.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))

service-worker.js

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

service-worker.js

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

service-worker.js

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

Inject programmatically

Use programmatic injection for content scripts that need to run in response to events or on specific occasions.

To inject a content script programmatically, your extension needs host permissions for the page it's trying to inject scripts into. Host permissions can either be granted by requesting them as part of your extension's manifest or temporarily using "activeTab" .

The following are different versions of an activeTab-based extension.

manifest.json:

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

Content scripts can be injected as files.

content-script.js


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

service-worker.js: 

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

Or, a function body can be injected and executed as a content script.

service-worker.js: 

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

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

Be aware that the injected function is a copy of the function referenced in the browser.scripting.executeScript() call, not the original function itself. As a result, the function's body must be self contained; references to variables outside of the function will cause the content script to throw a ReferenceError .

When injecting as a function, you can also pass arguments to the function.

service-worker.js 

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

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

Exclude matches and globs

To customize specified page matching, include the following fields in a declarative registration.

Имя Тип Описание
exclude_matches array of strings Optional. Excludes pages that this content script would otherwise be injected into. See Match Patterns for details of the syntax of these strings.
include_globs array of strings Optional. Applied after matches to include only those URLs that also match this glob. This is intended to emulate the @include Greasemonkey keyword.
exclude_globs array of string Optional. Applied after matches to exclude URLs that match this glob. Intended to emulate the @exclude Greasemonkey keyword.

The content script will be injected into a page if both of the following are true:

  • Its URL matches any matches pattern and any include_globs pattern.
  • The URL doesn't also match an exclude_matches or exclude_globs pattern. Because the matches property is required, exclude_matches , include_globs , and exclude_globs can only be used to limit which pages will be affected.

The following extension injects the content script into https://www.nytimes.com/health but not into https://www.nytimes.com/business .

manifest.json 

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

service-worker.js 

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

Glob properties follow a different, more flexible syntax than match patterns . Acceptable glob strings are URLs that may contain "wildcard" asterisks and question marks. The asterisk ( * ) matches any string of any length, including the empty string, while the question mark ( ? ) matches any single character.

For example, the glob https://???.example.com/foo/\* matches any of the following:

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

However, it does not match the following:

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

This extension injects the content script into https://www.nytimes.com/arts/index.html and https://www.nytimes.com/jobs/index.htm* , but not into https://www.nytimes.com/sports/index.html :

manifest.json 

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

This extension injects the content script into https://history.nytimes.com and https://.nytimes.com/history , but not into https://science.nytimes.com or https://www.nytimes.com/science :

manifest.json 

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

One, all, or some of these can be included to achieve the correct scope.

manifest.json 

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

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

The run_at field controls when JavaScript files are injected into the web page. The preferred and default value is "document_idle" . See the RunAt type for other possible values.

manifest.json 

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

service-worker.js 

browser.scripting.registerContentScripts([{
  id : "test",
  matches : [ "https://*.nytimes.com/*" ],
  runAt : "document_idle",
  js : [ "contentScript.js" ],
}]);
Имя Тип Описание
document_idle нить Preferred. Use "document_idle" whenever possible.

The browser chooses a time to inject scripts between "document_end" and immediately after the window.onload event fires. The exact moment of injection depends on how complex the document is and how long it is taking to load, and is optimized for page load speed.

Content scripts running at "document_idle" don't need to listen for the window.onload event, they are guaranteed to run after the DOM is complete. If a script definitely needs to run after window.onload , the extension can check if onload has already fired by using the document.readyState property.
document_start нить Scripts are injected after any files from css , but before any other DOM is constructed or any other script is run.
document_end нить Scripts are injected immediately after the DOM is complete, but before subresources like images and frames have loaded.

Specify frames

For declarative content scripts specified in the manifest, the "all_frames" field allows the extension to specify if JavaScript and CSS files should be injected into all frames matching the specified URL requirements or only into the topmost frame in a tab:

manifest.json 

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

When programmatically registering content scripts using browser.scripting.registerContentScripts(...) , the allFrames parameter can be used to specify if the content script should be injected into all frames matching the specified URL requirements or only into the topmost frame in a tab. This can only be used with tabId, and cannot be used if frameIds or documentIds are specified:

service-worker.js 

browser.scripting.registerContentScripts([{
  id: "test",
  matches : [ "https://*.nytimes.com/*" ],
  allFrames : true,
  js : [ "contentScript.js" ],
}]);

Extensions may want to run scripts in frames that are related to a matching frame, but don't themselves match. A common scenario when this is the case is for frames with URLs that were created by a matching frame, but whose URLs don't themselves match the script's specified patterns.

This is the case when an extension wants to inject in frames with URLs that have about: , data: , blob: , and filesystem: schemes. In these cases, the URL won't match the content script's pattern (and, in the case of about: and data: , don't even include the parent URL or origin in the URL at all, as in about:blank or data:text/html,<html>Hello, World!</html> ). However, these frames can still be associated with the creating frame.

To inject into these frames, extensions can specify the "match_origin_as_fallback" property on a content script specification in the manifest.

manifest.json 

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

When specified and set to true , Chrome will look at the origin of the initiator of the frame to determine whether the frame matches, rather than at the URL of the frame itself. Note that this might also be different than the target frame's origin (eg, data: URLs have a null origin).

The initiator of the frame is the frame that created or navigated the target frame. While this is commonly the direct parent or opener, it may not be (as in the case of a frame navigating an iframe within an iframe).

Because this compares the origin of the initiator frame, the initiator frame could be on at any path from that origin. To make this implication clear, Chrome requires any content scripts specified with "match_origin_as_fallback" set to true to also specify a path of * .

When both "match_origin_as_fallback" and "match_about_blank" are specified, "match_origin_as_fallback" takes priority.

Communication with the embedding page

Although the execution environments of content scripts and the pages that host them are isolated from each other, they share access to the page's DOM. If the page wishes to communicate with the content script, or with the extension through the content script, it must do so through the shared DOM.

An example can be accomplished using window.postMessage() :

content-script.js 

var port = browser.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);

The non-extension page, example.html, posts messages to itself. This message is intercepted and inspected by the content script and then posted to the extension process. In this way, the page establishes a line of communication to the extension process. The reverse is possible through similar means.

Access extension files

To access an extension file from a content script, you can call browser.runtime.getURL() to get the absolute URL of your extension asset as shown in the following example ( content.js ):

content-script.js 

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

To use fonts or images in a CSS file, you can use @@extension_id to construct a URL as shown in the following example ( content.css ):

content.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');
}

All assets must be declared as web accessible resources in the manifest.json file:

manifest.json 

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

Политика безопасности контента

Content scripts running in isolated worlds have the following Content Security Policy (CSP): 

script-src 'self' 'wasm-unsafe-eval' 'inline-speculation-rules' chrome-extension://abcdefghijklmopqrstuvwxyz/; object-src 'self';

Similar to the restrictions applied to other extension contexts, this prevents the use of eval() as well as loading external scripts.

For unpacked extensions, the CSP also includes localhost: 

script-src 'self' 'wasm-unsafe-eval' 'inline-speculation-rules' http://localhost:* http://127.0.0.1:* chrome-extension://abcdefghijklmopqrstuvwxyz/; object-src 'self';

When a content script is injected into the main world, the CSP of the page applies.

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

While isolated worlds provide a layer of protection, using content scripts can create vulnerabilities in an extension and the web page. If the content script receives content from a separate website, such as by calling fetch() , be careful to filter content against cross-site scripting attacks before injecting it. Only communicate over HTTPS in order to avoid "man-in-the-middle" attacks.

Be sure to filter for malicious web pages. For example, the following patterns are dangerous, and disallowed in Manifest V3:

Не

content-script.js 

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

content-script.js 

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

Instead, prefer safer APIs that don't run scripts:

Делать

content-script.js 

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

content-script.js 

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