Описание
Используйте API chrome.scripting для выполнения скриптов в различных контекстах.
Разрешения
scriptingДоступность
Манифест
Для использования 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"));
Внедренный код
Расширения могут указывать код для внедрения либо через внешний файл, либо через переменную времени выполнения.
Файлы
Файлы указываются в виде строк, представляющих собой пути относительно корневого каталога расширения. Следующий код внедрит файл 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
Характеристики
- идентификаторы
строка[] необязательный
Если указано,
getRegisteredContentScriptsвернет только скрипты с идентификатором, указанным в этом списке.
CSSInjection
Характеристики
- css
строка необязательный
Строка, содержащая CSS-код для внедрения. Необходимо указать ровно один из следующих параметров:
filesиcss. - файлы
строка[] необязательный
Путь к CSS-файлам для внедрения, относительно корневого каталога расширения. Необходимо указать ровно один из параметров:
filesиcss. - источник
StyleOrigin (необязательно)
Источник стиля для внедрения. По умолчанию используется значение
'AUTHOR'. - цель
Укажите целевую область, в которую следует вставить CSS-код.
ExecutionWorld
Область JavaScript, в которой будет выполняться скрипт.
Перечисление
"ИЗОЛИРОВАННЫЙ" "ОСНОВНОЙ"
Указывает на изолированный мир, представляющий собой уникальную для данного расширения среду выполнения.
Определяет основную область DOM, которая представляет собой среду выполнения, разделяемую с JavaScript-кодом главной страницы.
InjectionResult
Характеристики
- documentId
нить
Chrome 106+Документ, связанный с инъекцией.
- frameId
число
Chrome 90+Рамка, связанная с инъекцией.
- результат
любой необязательный
Результат выполнения скрипта.
InjectionTarget
Характеристики
- все кадры
логический необязательный
Указывает, следует ли внедрять скрипт во все фреймы внутри вкладки. По умолчанию — false. Если указан параметр
frameIds, это значение не должно быть true. - documentIds
строка[] необязательный
Chrome 106+Идентификаторы конкретных documentIds, в которые будет осуществлена инъекция. Этот параметр не должен быть задан, если задан
frameIds. - frameIds
число[] необязательно
Идентификаторы конкретных фреймов, в которые следует внедрить код.
- tabId
число
Идентификатор вкладки, в которую нужно вставить файл.
RegisteredContentScript
Характеристики
- все кадры
логический необязательный
Если указано значение true, то вставка будет происходить во все фреймы, даже если фрейм не является самым верхним на вкладке. Каждый фрейм проверяется независимо на соответствие требованиям URL; вставка в дочерние фреймы не будет производиться, если требования URL не соблюдены. По умолчанию значение false, что означает соответствие только самому верхнему фрейму.
- css
строка[] необязательный
Список CSS-файлов, которые будут внедрены в соответствующие страницы. Они внедряются в том порядке, в котором они указаны в этом массиве, до того, как будет создан или отображен какой-либо DOM-элемент для страницы.
- excludeMatches
строка[] необязательный
Исключаются страницы, на которые в противном случае был бы внедрен этот скрипт содержимого. Дополнительные сведения о синтаксисе этих строк см. в разделе «Шаблоны соответствия» .
- идентификатор
нить
Идентификатор скрипта контента, указанный в вызове API. Не должен начинаться с символа '_', поскольку он зарезервирован в качестве префикса для генерируемых идентификаторов скриптов.
- js
строка[] необязательный
Список JavaScript-файлов, которые будут внедрены в соответствующие страницы. Они внедряются в том порядке, в котором они указаны в этом массиве.
- matchOriginAsFallback
логический необязательный
Chrome 119+Указывает, можно ли внедрить скрипт в фреймы, URL-адрес которых содержит неподдерживаемую схему; в частности: about:, data:, blob: или filesystem:. В этих случаях проверяется источник URL-адреса, чтобы определить, следует ли внедрять скрипт. Если источник равен
null(как в случае с URL-адресами data:), то используемым источником является либо фрейм, создавший текущий фрейм, либо фрейм, инициировавший переход к этому фрейму. Обратите внимание, что это может быть не родительский фрейм. - матчи
строка[] необязательный
Указывает, на какие страницы будет внедрен этот скрипт содержимого. Дополнительные сведения о синтаксисе этих строк см. в разделе «Шаблоны соответствия» . Необходимо указать для
registerContentScripts. - persistAcrossSessions
логический необязательный
Указывает, будет ли этот скрипт содержимого сохраняться в будущих сессиях. По умолчанию — true.
- runAt
RunAt optional
Указывает, когда файлы JavaScript внедряются на веб-страницу. Предпочтительное значение по умолчанию —
document_idle. - мир
ExecutionWorld ( необязательно)
Chrome 102+Окружение JavaScript, в котором будет выполняться скрипт. По умолчанию используется
ISOLATED.
ScriptInjection
Характеристики
- аргументы
любой[] необязательный
Chrome 92+Аргументы, передаваемые в указанную функцию. Это допустимо только в том случае, если указан параметр
func. Эти аргументы должны быть сериализуемыми в формате JSON. - файлы
строка[] необязательный
Путь к JS или CSS файлам для внедрения, относительно корневого каталога расширения. Необходимо указать ровно один из следующих параметров:
filesилиfunc. - injectImmediately
логический необязательный
Chrome 102+Следует ли запускать внедрение кода в целевом объекте как можно скорее? Обратите внимание, что это не гарантирует, что внедрение произойдет до загрузки страницы, поскольку страница может уже загрузиться к моменту, когда скрипт достигнет целевого объекта.
- цель
Подробности, указывающие на целевой объект, в который следует внедрить скрипт.
- мир
ExecutionWorld ( необязательно)
Chrome 95+Окружение JavaScript, в котором будет выполняться скрипт. По умолчанию используется
ISOLATED. - функция
void optional
Chrome 92+Функция JavaScript для внедрения. Эта функция будет сериализована, а затем десериализована для внедрения. Это означает, что все связанные параметры и контекст выполнения будут потеряны. Необходимо указать ровно один из
filesилиfunc.funcвыглядит следующим образом:() => {...}
StyleOrigin
Истоки изменения стиля. Подробнее см. раздел «Истоки стиля» .
Перечисление
"АВТОР" "ПОЛЬЗОВАТЕЛЬ"
Методы
executeScript()
chrome.scripting.executeScript(
injection: ScriptInjection,
): Promise<InjectionResult[]>
Внедряет скрипт в целевой контекст. По умолчанию скрипт будет запущен в document_idle или немедленно, если страница уже загружена. Если задано свойство injectImmediately , скрипт будет внедрен без ожидания, даже если страница еще не завершила загрузку. Если скрипт возвращает промис, браузер будет ждать завершения выполнения промиса и вернет результирующее значение.
Параметры
- инъекция
Подробности о скрипте, который необходимо внедрить.
Возвраты
Promise< InjectionResult []>
Chrome 90+Возвращает промис, который разрешается после завершения инъекции. Полученный массив содержит результат выполнения для каждого кадра, в котором инъекция прошла успешно.
getRegisteredContentScripts()
chrome.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>
Возвращает все динамически зарегистрированные скрипты контента для этого расширения, соответствующие заданному фильтру.
Параметры
- фильтр
ContentScriptFilter (необязательно)
Объект для фильтрации динамически регистрируемых скриптов расширения.
Возвраты
Promise< RegisteredContentScript []>
insertCSS()
chrome.scripting.insertCSS(
injection: CSSInjection,
): Promise<void>
Вставляет таблицу стилей CSS в целевой контекст. Если указано несколько фреймов, неудачные попытки внедрения игнорируются.
Параметры
- инъекция
Детали стилей, которые необходимо вставить.
Возвраты
Обещание<пустота>
Chrome 90+Возвращает промис, который разрешается по завершении вставки.
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
): Promise<void>
Регистрирует один или несколько скриптов контента для этого расширения.
Параметры
- скрипты
Содержит список скриптов, подлежащих регистрации. Если во время анализа скриптов/проверки файлов возникают ошибки или если указанные идентификаторы уже существуют, то ни один скрипт не регистрируется.
Возвраты
Обещание<пустота>
Возвращает промис, который разрешается после полной регистрации скриптов или отклоняется в случае возникновения ошибки.
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
): Promise<void>
Удаляет CSS-таблицу стилей, ранее добавленную этим расширением, из целевого контекста.
Параметры
- инъекция
Подробности о стилях, которые необходимо удалить. Обратите внимание, что свойства
css,filesиoriginдолжны точно соответствовать таблице стилей, вставленной с помощьюinsertCSS. Попытка удалить несуществующую таблицу стилей не приведет к каким-либо изменениям.
Возвраты
Обещание<пустота>
Возвращает Promise, который разрешается после завершения удаления.
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
): Promise<void>
Отменяет регистрацию скриптов контента для этого расширения.
Параметры
- фильтр
ContentScriptFilter (необязательно)
Если указано иное, отменяется регистрация только тех скриптов динамического контента, которые соответствуют фильтру. В противном случае отменяются все скрипты динамического контента расширения.
Возвраты
Обещание<пустота>
Возвращает промис, который разрешается после отмены регистрации скриптов или отклоняется в случае возникновения ошибки.
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
): Promise<void>
Обновляет один или несколько скриптов контента для этого расширения.
Параметры
- скрипты
Содержит список скриптов, подлежащих обновлению. Свойство обновляется только для существующего скрипта, если оно указано в этом объекте. Если во время анализа скрипта/проверки файла возникают ошибки или если указанные идентификаторы не соответствуют полностью зарегистрированному скрипту, то ни один скрипт не обновляется.
Возвраты
Обещание<пустота>
Возвращает промис, который разрешается после обновления скриптов или отклоняется в случае возникновения ошибки.