Манифест – скрипты содержимого

Ключ "content_scripts" указывает на статически загруженный файл JavaScript или CSS, который будет использоваться каждый раз, когда открывается страница, соответствующая определенному шаблону URL. Расширения также могут внедрять скрипты для содержимого программно. Подробнее о внедрении скриптов…

Манифест

Ниже перечислены поддерживаемые ключи для "content_scripts". Обязательными являются только ключ "matches" и "js" или "css".

manifest.json

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["https://*.example.com/*"],
     "css": ["my-styles.css"],
     "js": ["content-script.js"],
     "exclude_matches": ["*://*/*foo*"],
     "include_globs": ["*example.com/???s/*"],
     "exclude_globs": ["*bar*"],     
     "all_frames": false,
     "match_origin_as_fallback": false,
     "match_about_blank": false,
     "run_at": "document_idle",
     "world": "ISOLATED",
   }
 ],
 ...
}

Файлы

В каждом файле должен быть указан относительный путь к ресурсу в корневом каталоге расширения. Косые черты (/) в начале удаляются автоматически. Ключ "run_at" определяет, когда будет внедрен каждый файл.

"css" – массив
Необязательно. Массив путей к файлам CSS, которые вставляются в указанном порядке до создания DOM или отрисовки страницы.
"js" – массив;
Необязательно. Массив путей к файлам JavaScript, которые внедряются в том порядке, в котором они указаны в массиве, после внедрения файлов CSS. Каждая строка в массиве должна быть относительным путем к ресурсу в корневом каталоге расширения. Косая черта (/) в начале автоматически удаляется.

Сопоставление URL

Обязательным является только свойство "matches". Затем вы можете использовать "exclude_matches", "include_globs" и "exclude_globs", чтобы настроить, в какие URL нужно вставлять код. Ключ "matches" вызовет предупреждение.

"matches" – массив
Обязательный атрибут. Указывает, в какие шаблоны URL нужно внедрить скрипты контента. Синтаксис описан в статье Шаблоны соответствия.
"exclude_matches" – массив
Необязательно. Исключает шаблоны URL, в которые нужно внедрить скрипты контента. Синтаксис описан в статье Шаблоны соответствия.
"include_globs" – массив
Необязательно. Применяется после сопоставления, чтобы включить только те URL, которые также соответствуют этому шаблону. Имитирует ключевое слово @include Greasemonkey.
"exclude_globs" – массив
Необязательно. Применяется после сопоставления, чтобы исключить URL, соответствующие этому шаблону. Имитирует ключевое слово @exclude в Greasemonkey.

URL-адреса Glob – это адреса, содержащие подстановочные знаки * и вопросительные знаки. Подстановочный знак * соответствует любой строке любой длины, включая пустую строку, а знак вопроса ? соответствует любому символу.

Скрипт контента внедряется на страницу, если:

  • URL соответствует шаблонам "matches" и "include_globs".
  • URL не соответствует шаблонам в правилах "exclude_matches" и "exclude_globs".

Примеры сопоставления шаблонов и URL

"include_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["https://???.example.com/foo/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Соответствует
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

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["*example.com/???s/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Соответствует
https://www.example.com/arts/index.html
https://www.example.com/jobs/index.html
Не соответствует
https://www.example.com/sports/index.html
https://www.example.com/music/index.html

"exclude_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Соответствует
https://history.example.com
https://.example.com/music
Не соответствует
https://science.example.com
https://www.example.com/science

Пример расширенной настройки

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*example.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Соответствует
https://www.example.com/arts/index.html
https://.example.com/jobs/index.html
Не соответствует
https://science.example.com
https://www.example.com/jobs/business
https://www.example.com/science

Кадры

Ключ "all_frames" указывает, должен ли скрипт контента внедряться во все фреймы, соответствующие заданным требованиям к URL. Если задано значение false, то код будет внедряться только в верхний фрейм. Его можно использовать вместе с "match_about_blank" для вставки во фрейм about:blank.

Чтобы внедрить код в другие фреймы, например data:, blob: и filesystem:, задайте для свойства "match_origin_as_fallback" значение true. Подробнее о внедрении в связанные фреймы…

"all_frames" логическое значение
Необязательный атрибут. По умолчанию используется значение false, то есть сопоставляется только верхний фрейм. Если задано значение true, скрипт будет внедрен во все фреймы, даже если фрейм не является самым верхним на вкладке. Каждый фрейм проверяется на соответствие требованиям к URL. Если они не соблюдены, скрипт не будет внедрен в дочерние фреймы.
"match_about_blank" – логическое значение;
Необязательный атрибут. Значение по умолчанию – false. Должен ли скрипт внедряться во фрейм about:blank, если родительский URL соответствует одному из шаблонов, объявленных в "matches".
"match_origin_as_fallback" – логическое значение;
Необязательный атрибут. Значение по умолчанию – false. Должен ли скрипт внедряться во фреймы, созданные соответствующим источником, но URL или источник которых могут не совпадать с шаблоном. К ним относятся фреймы с разными схемами, например about:, data:, blob: и filesystem:.

Среда выполнения и время выполнения

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

"run_at" – document_start | document_end | document_idle
Необязательно. Указывает, когда скрипт должен быть добавлен на страницу. Оно соответствует состояниям загрузки Document.readyState:
  • "document_start" – DOM все ещё загружается.
  • "document_end" – ресурсы страницы все ещё загружаются;
  • "document_idle" – загрузка DOM и ресурсов завершена. Это значение используется по умолчанию.
"world" – ISOLATED | MAIN
Необязательно. Среда JavaScript, в которой будет выполняться скрипт. По умолчанию используется "ISOLATED" – среда выполнения, уникальная для скрипта контента. Если выбрать мир "MAIN", скрипт будет использовать ту же среду выполнения, что и JavaScript на хост-странице. Подробнее о работе в изолированных средах…

Пример

Чтобы создать расширение, которое внедряет скрипт контента в манифест, ознакомьтесь с руководством Запуск на каждой странице.