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

chrome.userScripts

Описание

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

Разрешения

userScripts

Чтобы использовать API пользовательских скриптов ( chrome.userScripts , добавьте разрешение "userScripts" в ваш файл manifest.json и "host_permissions" для сайтов, на которых вы хотите запускать скрипты.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

Доступность

Chrome 120+ MV3+

Понятия и применение

Пользовательский скрипт — это фрагмент кода, внедряемый в веб-страницу для изменения её внешнего вида или поведения. В отличие от других функций расширений, таких как Content Scripts и chrome.scripting API , API пользовательских скриптов позволяет запускать произвольный код. Этот API необходим для расширений, которые запускают скрипты, предоставленные пользователем, и которые не могут быть включены в пакет расширения.

Разрешить использование API пользовательских скриптов

После того, как ваше расширение получит разрешение на использование API userScripts, пользователям необходимо включить определенный переключатель, чтобы разрешить вашему расширению использовать API. Необходимый переключатель и поведение API в отключенном состоянии различаются в зависимости от версии Chrome.

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

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

В следующих разделах описаны различные переключатели и способы их включения.

Версии Chrome до 138 (переключение режима разработчика)

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

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

Перейдите на страницу расширений, введя chrome://extensions в новой вкладке. (По умолчанию URL-адреса с префиксом chrome:// не являются ссылками.)
Включите режим разработчика, нажав на переключатель рядом с пунктом «Режим разработчика» .
Extensions page (chrome://extensions)

Версии Chrome 138 и новее (включите параметр «Разрешить пользовательские скрипты»).

The Allow User Scripts toggle is on each extension's details page (for example, chrome://extensions/?id=YOUR_EXTENSION_ID).

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

Перейдите на страницу расширений, введя chrome://extensions в новой вкладке. (По умолчанию URL-адреса с префиксом chrome:// не являются ссылками.)
Нажмите кнопку «Подробности» на карточке расширения, чтобы просмотреть подробную информацию о расширении.
Нажмите переключатель рядом с пунктом «Разрешить пользовательские скрипты» .

Переключатель «Разрешить пользовательские скрипты» находится на странице сведений о расширении. — Разрешить пользовательские скрипты (chrome://extensions/?id=abc...)

Проверьте доступность API.

Мы рекомендуем следующую проверку, чтобы определить, включен ли API userScripts, поскольку она работает во всех версиях Chrome. Эта проверка пытается вызвать метод chrome.userScripts() , который всегда должен быть успешным, если API доступен. Если этот вызов вызывает ошибку, API недоступен:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    chrome.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

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

Как пользовательские, так и контентные скрипты могут выполняться в изолированной среде или в основной среде. Изолированная среда — это среда выполнения, недоступная для основной страницы или других расширений. Это позволяет пользовательскому скрипту изменять свою среду JavaScript, не затрагивая пользовательские и контентные скрипты основной страницы или других расширений. И наоборот, пользовательские скрипты (и контентные скрипты) не видны основной странице или пользовательским и контентным скриптам других расширений. Скрипты, работающие в основной среде, доступны основным страницам и другим расширениям и видны им. Чтобы выбрать среду, передайте "USER_SCRIPT" или "MAIN" при вызове userScripts.register() .

Для настройки политики безопасности контента для среды USER_SCRIPT вызовите userScripts.configureWorld() :

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

Обмен сообщениями

Подобно скриптам контента и документам, находящимся вне экрана, пользовательские скрипты взаимодействуют с другими частями расширения с помощью обмена сообщениями (это означает, что они могут вызывать runtime.sendMessage() и runtime.connect() так же, как и любая другая часть расширения). Однако они принимаются с помощью специальных обработчиков событий (то есть, они не используют onMessage или onConnect ). Эти обработчики называются runtime.onUserScriptMessage и runtime.onUserScriptConnect . Специальные обработчики упрощают идентификацию сообщений от пользовательских скриптов, которые представляют собой менее надежный контекст.

Перед отправкой сообщения необходимо вызвать configureWorld() , установив аргумент messaging в true . Обратите внимание, что аргументы csp и messaging могут быть переданы одновременно.

chrome.userScripts.configureWorld({
  messaging: true
});

Обновления расширений

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

Пример

Этот пример взят из образца userScript в нашем репозитории примеров.

Зарегистрируйте скрипт

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

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Типы

ExecutionWorld

Область JavaScript, в которой должен выполняться пользовательский скрипт.

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

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

"USER_SCRIPT"
Указывает среду выполнения, специфичную для пользовательских скриптов и не подпадающую под действие политики безопасности страницы (CSP).

InjectionResult

Chrome 135+

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

documentId
нить
Документ, связанный с инъекцией.
ошибка
строка необязательный
Ошибка, если таковая имеется. error и result взаимоисключающие.
frameId
число
Рамка, связанная с инъекцией.
результат
any optional
The result of the script execution.

InjectionTarget

Chrome 135+

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

все кадры
логический необязательный
Указывает, следует ли внедрять скрипт во все фреймы внутри вкладки. По умолчанию — false. Если указан параметр frameIds , это значение не должно быть true.
documentIds
строка[] необязательный
Идентификаторы конкретных documentIds, в которые будет осуществлена инъекция. Этот параметр не должен быть задан, если задан frameIds .
frameIds
number[] optional
Идентификаторы конкретных фреймов, в которые следует внедрить код.
tabId
число
The ID of the tab into which to inject.

RegisteredUserScript

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

все кадры
логический необязательный
Если значение равно true, то внедрение будет происходить во все фреймы, даже если фрейм не является самым верхним фреймом во вкладке. Каждый фрейм проверяется независимо на соответствие требованиям URL; внедрение в дочерние фреймы не будет происходить, если требования URL не соблюдены. По умолчанию значение равно false, что означает, что соответствие устанавливается только для самого верхнего фрейма.
excludeGlobs
строка[] необязательный
Указывает шаблоны с подстановочными знаками для страниц, на которые этот пользовательский скрипт НЕ будет внедрен.
excludeMatches
строка[] необязательный
Исключаются страницы, в которые в противном случае был бы внедрен этот пользовательский скрипт. Дополнительные сведения о синтаксисе этих строк см. в разделе «Шаблоны соответствия» .
идентификатор
нить
Идентификатор пользовательского скрипта, указанного в вызове API. Это свойство не должно начинаться с символа '_', поскольку он зарезервирован в качестве префикса для сгенерированных идентификаторов скриптов.
includeGlobs
строка[] необязательный
Задает шаблоны с подстановочными знаками для страниц, в которые будет внедрен этот пользовательский скрипт.
js
ScriptSource [] необязательный
Список объектов ScriptSource, определяющих источники скриптов, которые будут внедрены в соответствующие страницы. Это свойство необходимо указать для ${ref:register}, и если оно указано, то должно быть непустым массивом.
матчи
строка[] необязательный
Указывает, на какие страницы будет внедрен этот пользовательский скрипт. Дополнительные сведения о синтаксисе этих строк см. в разделе «Шаблоны соответствия» . Это свойство необходимо указать для ${ref:register}.
runAt
RunAt optional
Указывает, когда файлы JavaScript внедряются на веб-страницу. Предпочтительное значение по умолчанию — document_idle .
мир
ExecutionWorld ( необязательно)
Среда выполнения JavaScript для запуска скрипта. По умолчанию используется `USER_SCRIPT` .
worldId
строка необязательный
Chrome 133+
Указывает идентификатор среды выполнения пользовательского скрипта. Если опущено, скрипт будет выполняться в среде выполнения пользовательского скрипта по умолчанию. Действительно только в том случае, если world опущено или имеет значение USER_SCRIPT . Значения с ведущими символами подчеркивания ( _ ) зарезервированы.

ScriptSource

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

код
строка необязательный
Строка, содержащая код JavaScript для внедрения. Необходимо указать ровно один из вариантов: file или code .
файл
строка необязательный
The path of the JavaScript file to inject relative to the extension's root directory. Exactly one of file or code must be specified.

UserScriptFilter

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

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

UserScriptInjection

Chrome 135+

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

injectImmediately
логический необязательный
Следует ли запускать внедрение кода в целевом объекте как можно скорее? Обратите внимание, что это не гарантирует, что внедрение произойдет до загрузки страницы, поскольку страница может уже загрузиться к моменту, когда скрипт достигнет целевого объекта.
js
ScriptSource []
Список объектов ScriptSource, определяющих источники скриптов, которые будут внедрены в целевой объект.
цель
Цель инъекции
Подробности, указывающие на целевой объект, в который следует внедрить скрипт.
мир
ExecutionWorld ( необязательно)
Параметр JavaScript, в котором будет выполняться скрипт. По умолчанию используется переменная USER_SCRIPT .
worldId
строка необязательный
Указывает идентификатор среды выполнения пользовательского скрипта. Если опущено, скрипт будет выполняться в среде выполнения пользовательского скрипта по умолчанию. Действительно только в том случае, если world опущено или имеет значение USER_SCRIPT . Значения с ведущими символами подчеркивания ( _ ) зарезервированы.

WorldProperties

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

csp
строка необязательный
Указывает CSP мира. По умолчанию используется CSP мира `ISOLATED` .
обмен сообщениями
логический необязательный
Указывает, доступны ли API обмена сообщениями. По умолчанию — false .
worldId
строка необязательный
Chrome 133+
Указывает идентификатор конкретного пользовательского скрипта, который необходимо обновить. Если не указан, обновляются свойства скрипта пользователя по умолчанию. Значения с ведущими символами подчеркивания ( _ ) зарезервированы.

Методы

configureWorld()

chrome.userScripts.configureWorld(
  properties: WorldProperties,
): Promise<void>

Настраивает среду выполнения `USER_SCRIPT` .

Параметры

характеристики
WorldProperties
Contains the user script world configuration.

Возвраты

Обещание<пустота>
Обещание, которое выполняется после настройки мира.

execute()

Chrome 135+

chrome.userScripts.execute(
  injection: UserScriptInjection,
): Promise<InjectionResult[]>

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

Параметры

инъекция
Внедрение пользовательского скрипта

Возвраты

Promise< InjectionResult []>

getScripts()

chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>

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

Параметры

фильтр
UserScriptFilter (необязательно)
Если указано иное, этот метод возвращает только те пользовательские скрипты, которые ему соответствуют.

Возвраты

Promise< RegisteredUserScript []>
Обещание, которое разрешается с помощью зарегистрированных скриптов. Обещание будет отклонено в случае возникновения ошибки.

getWorldConfigurations()

Chrome 133+

chrome.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>

Получает все зарегистрированные мировые конфигурации.

Возвраты

Promise< WorldProperties []>
Обещание, которое выполняется в соответствии с зарегистрированными конфигурациями мира.

register()

chrome.userScripts.register(
  scripts: RegisteredUserScript[],
): Promise<void>

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

Параметры

скрипты
Зарегистрированный пользовательский скрипт []
Содержит список пользовательских скриптов, подлежащих регистрации.

Возвраты

Обещание<пустота>
Обещание, которое выполняется после полной регистрации скриптов. Обещание будет отклонено в случае возникновения ошибки.

resetWorldConfiguration()

Chrome 133+

chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
): Promise<void>

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

Параметры

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

Возвраты

Обещание<пустота>
Обещание, которое выполняется при сбросе конфигурации.

unregister()

chrome.userScripts.unregister(
  filter?: UserScriptFilter,
): Promise<void>

Отменяет регистрацию всех динамически зарегистрированных пользовательских скриптов для этого расширения.

Параметры

фильтр
UserScriptFilter (необязательно)
Если указано, этот метод отменяет регистрацию только тех пользовательских скриптов, которые ему соответствуют.

Возвраты

Обещание<пустота>
Промис, который разрешается после полной отмены регистрации скриптов. Промис будет отклонен в случае возникновения ошибки.

update()

chrome.userScripts.update(
  scripts: RegisteredUserScript[],
): Promise<void>

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

Параметры

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

Возвраты

Обещание<пустота>
Обещание, которое выполняется после полного обновления скриптов. Обещание будет отклонено в случае возникновения ошибки.

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

Описание

Разрешения

Доступность

Понятия и применение

Разрешить использование API пользовательских скриптов

Версии Chrome до 138 (переключение режима разработчика)

Версии Chrome 138 и новее (включите параметр «Разрешить пользовательские скрипты»).

Проверьте доступность API.

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

Обмен сообщениями

Обновления расширений

Пример

Зарегистрируйте скрипт

Типы

ExecutionWorld

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

InjectionResult

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

InjectionTarget

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

RegisteredUserScript

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

ScriptSource

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

UserScriptFilter

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

UserScriptInjection

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

WorldProperties

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

Методы

configureWorld()

Параметры

Возвраты

execute()

Параметры

Возвраты

getScripts()

Параметры

Возвраты

getWorldConfigurations()

Возвраты

register()

Параметры

Возвраты

resetWorldConfiguration()

Параметры

Возвраты

unregister()

Параметры

Возвраты

update()

Параметры

Возвраты

chrome.userScripts