Эта страница переведена с помощью Cloud Translation API.

хром.скриптинг

Описание

Используйте API chrome.scripting для выполнения скриптов в различных контекстах.

Разрешения

scripting

Доступность

Chrome 88+ MV3+

Манифест

Чтобы использовать API chrome.scripting , объявите разрешение "scripting" в манифесте , а также разрешения хоста для страниц, в которые будут внедряться скрипты. Используйте ключ "host_permissions" или разрешение "activeTab" , которое предоставляет временные разрешения хоста. В следующем примере используется разрешение «activeTab».

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

Концепции и использование

API chrome.scripting можно использовать для внедрения JavaScript и CSS на веб-сайты. Это похоже на то, что можно делать со скриптами контента . Однако, используя пространство имён chrome.scripting , расширения могут принимать решения во время выполнения.

Цели инъекций

Вы можете использовать параметр target , чтобы указать цель, в которую следует внедрить JavaScript или CSS.

Единственное обязательное поле — tabId . По умолчанию инъекция будет выполнена в главном фрейме указанной вкладки.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

Для запуска во всех кадрах указанной вкладки можно установить логическое значение allFrames в true .

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected in all frames"));

Вы также можете внедрять контент в определённые фреймы вкладки, указав их идентификаторы. Подробнее об идентификаторах фреймов см. в API chrome.webNavigation .

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

Примечание: невозможно указать одновременно свойства "frameIds" и "allFrames" .

Внедренный код

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

Файлы

Файлы указываются в виде строк, которые являются путями относительно корневого каталога расширения. Следующий код добавит файл script.js в главный фрейм вкладки.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("injected script file"));

Функции времени выполнения

При внедрении JavaScript с помощью scripting.executeScript() вы можете указать функцию, которая будет выполнена вместо файла. Эта функция должна быть функциональной переменной, доступной текущему контексту расширения.

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
    })
    .then(() => console.log("injected a function"));

Эту проблему можно обойти, используя свойство args :

function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
      args : [ getUserColor() ],
    })
    .then(() => console.log("injected a function"));

Строки времени выполнения

При внедрении CSS на страницу вы также можете указать строку для использования в свойстве css . Эта возможность доступна только для scripting.insertCSS() ; выполнить строку с помощью scripting.executeScript() невозможно.

function getTabId() { ... }
const css = "body { background-color: red; }";

chrome.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

Обрабатывайте результаты

Результаты выполнения JavaScript передаются в расширение. Для каждого кадра добавляется один результат. Основной кадр гарантированно является первым индексом в результирующем массиве; все остальные кадры располагаются в неопределённом порядке.

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : getTitle,
    })
    .then(injectionResults => {
      for (const {frameId, result} of injectionResults) {
        console.log(`Frame ${frameId} result:`, result);
      }
    });

scripting.insertCSS() не возвращает никаких результатов.

Обещания

Если результирующее значение выполнения скрипта является обещанием, Chrome дождется завершения обещания и вернет результирующее значение.

function getTabId() { ... }
async function addIframe() {
  const iframe = document.createElement("iframe");
  const loadComplete =
      new Promise(resolve => iframe.addEventListener("load", resolve));
  iframe.src = "https://example.com";
  document.body.appendChild(iframe);
  await loadComplete;
  return iframe.contentWindow.document.title;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : addIframe,
    })
    .then(injectionResults => {
      for (const frameResult of injectionResults) {
        const {frameId, result} = frameResult;
        console.log(`Frame ${frameId} result:`, result);
      }
    });

Примеры

Отменить регистрацию всех скриптов динамического контента

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

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await chrome.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return chrome.scripting.unregisterContentScripts({ ids: scriptIds });
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

Чтобы опробовать API chrome.scripting , установите пример скрипта из репозитория примеров расширений Chrome .

Типы

ContentScriptFilter

Хром 96+

Характеристики

идентификаторы
строка[] необязательная
Если указано, getRegisteredContentScripts вернет только скрипты с идентификатором, указанным в этом списке.

CSSInjection

Характеристики

css
строка необязательная
Строка, содержащая CSS-код для внедрения. Необходимо указать только один из files и css .
файлы
строка[] необязательная
Путь к CSS-файлам для внедрения относительно корневого каталога расширения. Необходимо указать только один из files и css .
источник
StyleOrigin необязательно
Источник стиля для инъекции. По умолчанию — 'AUTHOR' .
цель
InjectionTarget
Подробная информация, указывающая цель, в которую следует вставить CSS.

ExecutionWorld

Хром 95+

Мир JavaScript для выполнения скрипта.

Перечисление

«ИЗОЛИРОВАННЫЙ»
Указывает изолированный мир, который является средой выполнения, уникальной для этого расширения.

"ОСНОВНОЙ"
Указывает основной мир DOM, который представляет собой среду выполнения, используемую совместно с JavaScript-кодом страницы хоста.

InjectionResult

Характеристики

documentId
нить
Хром 106+
Документ, связанный с инъекцией.
frameId
число
Хром 90+
Кадр, связанный с инъекцией.
результат
любой необязательный
Результат выполнения скрипта.

InjectionTarget

Характеристики

allFrames
логическое необязательное
Должен ли скрипт внедряться во все фреймы вкладки. Значение по умолчанию — false. Значение не должно быть true, если указан параметр frameIds .
идентификаторы документов
строка[] необязательная
Хром 106+
Идентификаторы конкретных documentIds для внедрения. Этот параметр не должен быть задан, если задан frameIds .
frameIds
номер[] необязательно
Идентификаторы конкретных кадров для внедрения.
tabId
число
Идентификатор вкладки, в которую следует выполнить инъекцию.

RegisteredContentScript

Хром 96+

Характеристики

allFrames
логическое необязательное
Если указано значение true, вставка будет выполнена во все фреймы, даже если фрейм не является самым верхним во вкладке. Каждый фрейм проверяется независимо на соответствие требованиям URL; вставка не будет выполнена в дочерние фреймы, если требования URL не выполнены. Значение по умолчанию — false, что означает, что сопоставляется только верхний фрейм.
css
строка[] необязательная
Список CSS-файлов для внедрения на соответствующие страницы. Они внедряются в том порядке, в котором они указаны в этом массиве, до построения или отображения DOM-модели страницы.
исключить совпадения
строка[] необязательная
Исключает страницы, в которые этот скрипт контента в противном случае был бы внедрён. Подробнее о синтаксисе этих строк см. в разделе «Шаблоны соответствия» .
идентификатор
нить
Идентификатор скрипта контента, указанный в вызове API. Не должен начинаться с символа «_», так как он зарезервирован в качестве префикса для генерируемых идентификаторов скриптов.
js
строка[] необязательная
Список файлов JavaScript для внедрения на соответствующие страницы. Они внедряются в том порядке, в котором они указаны в этом массиве.
matchOriginAsFallback
логическое необязательное
Хром 119+
Указывает, можно ли внедрить скрипт во фреймы, URL-адрес которых содержит неподдерживаемую схему, в частности: about:, data:, blob: или filesystem:. В этих случаях проверяется источник URL-адреса, чтобы определить, следует ли внедрять скрипт. Если источник равен null (как в случае URL-адресов data:), то используемым источником будет либо фрейм, создавший текущий фрейм, либо фрейм, инициировавший навигацию к этому фрейму. Обратите внимание, что это может быть не родительский фрейм.
спички
строка[] необязательная
Указывает, на какие страницы будет внедрен этот скрипт контента. Подробнее о синтаксисе этих строк см. в разделе «Шаблоны соответствия» . Необходимо указать для registerContentScripts .
persistAcrossSessions
логическое необязательное
Указывает, будет ли этот скрипт контента сохраняться в будущих сеансах. Значение по умолчанию — true.
runAt
RunAt необязательно
Указывает, когда файлы JavaScript внедряются в веб-страницу. Предпочтительное значение по умолчанию — document_idle .
мир
ExecutionWorld необязательно
Хром 102+
«Мир» JavaScript, в котором будет запускаться скрипт. По умолчанию — ISOLATED .

ScriptInjection

Характеристики

аргументы
любой[] необязательный
Хром 92+
Аргументы, передаваемые в указанную функцию. Это допустимо только при указании параметра func . Эти аргументы должны быть сериализуемы в формате JSON.
файлы
строка[] необязательная
Путь к JS- или CSS-файлам для внедрения относительно корневого каталога расширения. Необходимо указать только один из files или func .
вводить немедленно
логическое необязательное
Хром 102+
Следует ли как можно скорее запустить инъекцию в целевой объект. Обратите внимание, что это не гарантирует, что инъекция произойдёт до загрузки страницы, поскольку страница может быть уже загружена к моменту, когда скрипт достигнет целевой страницы.
цель
InjectionTarget
Подробности, указывающие цель, в которую следует внедрить скрипт.
мир
ExecutionWorld необязательно
Хром 95+
«Мир» JavaScript, в котором будет запускаться скрипт. По умолчанию — ISOLATED .
функция
необязательный
Хром 92+
Функция JavaScript для внедрения. Эта функция будет сериализована, а затем десериализована для внедрения. Это означает, что все привязанные параметры и контекст выполнения будут потеряны. Необходимо указать только один из files или func .
Функция func выглядит так:
```
() => {...}
```

StyleOrigin

Источник изменения стиля. Подробнее см. в разделе «Истоки стиля» .

Перечисление

«АВТОР»

"ПОЛЬЗОВАТЕЛЬ"

Методы

executeScript()

chrome.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

Внедряет скрипт в целевой контекст. По умолчанию скрипт запускается в момент document_idle или немедленно, если страница уже загружена. Если установлено свойство injectImmediately , скрипт будет внедрен без ожидания, даже если страница ещё не загрузилась. Если результат скрипта соответствует обещанию, браузер дождётся его завершения и вернёт полученное значение.

Параметры

инъекция
ScriptInjection
Детали скрипта, который необходимо внедрить.

Возврат

Обещание< РезультатИнъекции []>
Хром 90+

getRegisteredContentScripts()

Хром 96+

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

Параметры

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

Возврат

Обещание< RegisteredContentScript []>

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

Вставляет таблицу стилей CSS в целевой контекст. Если указано несколько фреймов, неудачные внедрения игнорируются.

Параметры

инъекция
CSSInjection
Подробная информация о стилях для вставки.

Возврат

Обещание<void>
Хром 90+

registerContentScripts()

Хром 96+

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Регистрирует один или несколько скриптов контента для этого расширения.

Параметры

сценарии
RegisteredContentScript []
Содержит список скриптов для регистрации. Если при разборе скрипта/проверке файла возникли ошибки или указанные идентификаторы уже существуют, скрипты не регистрируются.

Возврат

Обещание<void>

removeCSS()

Хром 90+

chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

Удаляет таблицу стилей CSS, ранее вставленную этим расширением из целевого контекста.

Параметры

инъекция
CSSInjection
Подробная информация об удаляемых стилях. Обратите внимание, что свойства css , files и origin должны точно соответствовать таблице стилей, вставленной с помощью insertCSS . Попытка удалить несуществующую таблицу стилей невозможна.

Возврат

Обещание<void>

unregisterContentScripts()

Хром 96+

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Отменяет регистрацию скриптов содержимого для этого расширения.

Параметры

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

Возврат

Обещание<void>

updateContentScripts()

Хром 96+

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Обновляет один или несколько скриптов контента для этого расширения.

Параметры

сценарии
RegisteredContentScript []
Содержит список скриптов для обновления. Свойство обновляется только для существующего скрипта, если оно указано в этом объекте. Если при разборе скрипта/проверке файла возникают ошибки или если указанные идентификаторы не соответствуют полностью зарегистрированному скрипту, скрипты не обновляются.

Возврат

Обещание<void>

хром.скриптинг Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Описание

Разрешения

Доступность

Манифест

Концепции и использование

Цели инъекций

Внедренный код

Файлы

Функции времени выполнения

Строки времени выполнения

Обрабатывайте результаты

Обещания

Примеры

Отменить регистрацию всех скриптов динамического контента

Типы

ContentScriptFilter

Характеристики

CSSInjection

Характеристики

ExecutionWorld

Перечисление

InjectionResult

Характеристики

InjectionTarget

Характеристики

RegisteredContentScript

Характеристики

ScriptInjection

Характеристики

StyleOrigin

Перечисление

Методы

executeScript()

Параметры

Возврат

getRegisteredContentScripts()

Параметры

Возврат

insertCSS()

Параметры

Возврат

registerContentScripts()

Параметры

Возврат

removeCSS()

Параметры

Возврат

unregisterContentScripts()

Параметры

Возврат

updateContentScripts()

Параметры

Возврат

хром.скриптинг