Описание
Используйте userScripts API, чтобы выполнять пользовательские скрипты в контексте User Scripts.
Разрешения
userScriptsЧтобы использовать User Scripts API, browser.userScripts, добавьте разрешение "userScripts" в файл manifest.json и "host_permissions" для сайтов, на которых вы хотите запускать скрипты.
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
Доступность
Основные понятия и использование
Пользовательский скрипт – это фрагмент кода, который вставляется в веб-страницу, чтобы изменить ее внешний вид или поведение. В отличие от других функций расширений, таких как скрипты контента и browser.scripting API, User Scripts API позволяет выполнять произвольный код. Этот API необходим для расширений, которые запускают скрипты, предоставленные пользователем и не включенные в пакет расширения.
Разрешить использование userScripts API
После того как расширение получит разрешение на использование userScripts API, пользователи должны включить специальный переключатель, чтобы разрешить расширению использовать 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. (chrome://URL не могут быть ссылками.) Включите режим разработчика, нажав на переключатель рядом с надписью Режим разработчика.
Страница расширений (chrome://extensions)
Chrome 138 и более поздних версий (переключатель "Разрешить пользовательские скрипты")
Переключатель Разрешить пользовательские скрипты находится на странице сведений о расширении (например, chrome://extensions/?id=YOUR_EXTENSION_ID).
Вы можете скопировать приведенные ниже инструкции и вставить их в документацию к расширению.
- Откройте новую вкладку и перейдите на страницу расширений, введя
chrome://extensions. (chrome://URL не могут быть ссылками.) - Нажмите кнопку "Сведения" на карточке расширения, чтобы посмотреть подробную информацию о нем.
- Установите переключатель Разрешить пользовательские скрипты в положение "включено".
Проверьте доступность API
Чтобы определить, включен ли API userScripts, рекомендуем выполнить следующую проверку, которая работает во всех версиях Chrome. При этом вызывается метод browser.userScripts(), который всегда должен выполняться успешно, если API доступен. Если этот вызов возвращает ошибку, API недоступен:
function isUserScriptsAvailable() {
try {
// Method call which throws if API permission or toggle is not enabled.
browser.userScripts.getScripts();
return true;
} catch {
// Not available.
return false;
}
}
Работа в изолированных мирах
Как пользовательские, так и контентные скрипты могут выполняться в изолированном или основном мире. Изолированная среда – это среда выполнения, недоступная для хост-страницы и других расширений. Это позволяет пользовательскому скрипту изменять свою среду JavaScript, не влияя на хост-страницу или пользовательские скрипты и скрипты контента других расширений. И наоборот, пользовательские скрипты (и скрипты контента) не видны хост-странице или пользовательским скриптам и скриптам контента других расширений. Скрипты, запущенные в основном мире, доступны для хост-страниц и других расширений и видны им. Чтобы выбрать мир, передайте "USER_SCRIPT" или "MAIN" при вызове userScripts.register().
Чтобы настроить правила безопасности контента для мира USER_SCRIPT, вызовите userScripts.configureWorld():
browser.userScripts.configureWorld({
csp: "script-src 'self'"
});
Сообщения
Как и скрипты контента и закадровые документы, пользовательские скрипты взаимодействуют с другими частями расширения с помощью обмена сообщениями (то есть они могут вызывать runtime.sendMessage() и runtime.connect(), как и любая другая часть расширения). Однако они принимаются с помощью специальных обработчиков событий (то есть не используют onMessage или onConnect). Эти обработчики называются runtime.onUserScriptMessage и runtime.onUserScriptConnect. Специальные обработчики упрощают идентификацию сообщений из пользовательских скриптов, которые являются менее надежным контекстом.
Перед отправкой сообщения необходимо вызвать configureWorld() с аргументом messaging, для которого задано значение true. Обратите внимание, что аргументы csp и messaging можно передавать одновременно.
browser.userScripts.configureWorld({
messaging: true
});
Обновления расширений
Пользовательские скрипты удаляются при обновлении расширения. Вы можете добавить их обратно, запустив код в обработчике событий runtime.onInstalled в сервис-воркере расширения. Реагируйте только на причину "update", переданную в обратный вызов события.
Пример
Этот пример взят из образца userScript в нашем хранилище образцов.
Как зарегистрировать скрипт
Ниже приведен пример простого вызова register(). Первый аргумент – это массив объектов, определяющих скрипты, которые нужно зарегистрировать. Здесь показаны не все варианты.
browser.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
Типы
ExecutionWorld
Мир JavaScript, в котором будет выполняться пользовательский скрипт.
Перечисление
"MAIN"
Указывает на среду выполнения DOM, которая используется совместно с кодом JavaScript на хост-странице.
"USER_SCRIPT"
Указывает среду выполнения, которая относится к пользовательским скриптам и не подпадает под действие CSP страницы.
InjectionResult
Свойства
-
documentId
string
Документ, связанный с инъекцией.
-
ошибка
Строка (необязательно)
Ошибка (если есть).
errorиresultявляются взаимоисключающими. -
frameId
число
Фрейм, связанный с внедрением.
-
Результат
any optional
Результат выполнения скрипта.
InjectionTarget
Свойства
-
allFrames
Логическое значение (необязательно)
Должен ли скрипт внедряться во все фреймы на вкладке. Значение по умолчанию – false. Если указано свойство
frameIds, то это свойство не должно иметь значение true. -
documentIds
string[] необязательно
Идентификаторы documentId, в которые нужно вставить данные. Это значение не должно быть задано, если задано значение
frameIds. -
frameIds
number[] optional
Идентификаторы определенных фреймов, в которые нужно внедрить скрипт.
-
tabId
число
Идентификатор вкладки, в которую нужно внедрить скрипт.
RegisteredUserScript
Свойства
-
allFrames
Логическое значение (необязательно)
Если задано значение true, скрипт будет внедрен во все фреймы, даже если фрейм не является самым верхним на вкладке. Каждый фрейм проверяется на соответствие требованиям к URL. Если фрейм не соответствует требованиям, тег не будет добавлен в дочерние фреймы. Значение по умолчанию – false (сопоставляется только верхний фрейм).
-
excludeGlobs
string[] необязательно
Указывает шаблоны подстановочных знаков для страниц, в которые этот пользовательский скрипт НЕ будет внедрен.
-
excludeMatches
string[] необязательно
Исключает страницы, в которые в противном случае был бы внедрен этот пользовательский скрипт. Подробнее о шаблонах соответствия…
-
id
string
Идентификатор пользовательского скрипта, указанный в вызове API. Это свойство не должно начинаться с символа подчеркивания, поскольку он зарезервирован в качестве префикса для сгенерированных идентификаторов скриптов.
-
includeGlobs
string[] необязательно
Указывает шаблоны подстановочных знаков для страниц, в которые будет внедрен этот пользовательский скрипт.
-
js
ScriptSource[] optional
Список объектов ScriptSource, определяющих источники скриптов, которые нужно внедрить на соответствующие страницы. Это свойство должно быть указано для ${ref:register} и должно быть непустым массивом.
-
соответствует
string[] необязательно
Указывает, на какие страницы будет внедрен этот пользовательский скрипт. Подробнее о шаблонах соответствия… Это свойство обязательно для типа ${ref:register}.
-
runAt
RunAt необязательный
Указывает, когда файлы JavaScript внедряются в веб-страницу. Рекомендуемое значение по умолчанию –
document_idle. -
мир
ExecutionWorld необязательный
Среда выполнения JavaScript, в которой будет запущен скрипт. Значение по умолчанию –
`USER_SCRIPT`. -
worldId
Строка (необязательно)
Chrome 133+ browser.* начиная с Chrome 148Указывает идентификатор среды пользовательского скрипта, в которой он должен выполняться. Если этот параметр опущен, скрипт будет выполняться в мире пользовательских скриптов по умолчанию. Действительно, только если
worldопущено или имеет значениеUSER_SCRIPT. Значения, начинающиеся с символа подчеркивания (_), зарезервированы.
ScriptSource
Свойства
-
код
Строка (необязательно)
Строка, содержащая код JavaScript для внедрения. Необходимо указать только одно значение:
fileилиcode. -
файл
Строка (необязательно)
Путь к файлу JavaScript, который нужно внедрить, относительно корневого каталога расширения. Необходимо указать только одно значение:
fileилиcode.
UserScriptFilter
Свойства
-
ids
string[] необязательно
getScriptsвозвращает только скрипты с идентификаторами, указанными в этом списке.
UserScriptInjection
Свойства
-
injectImmediately
Логическое значение (необязательно)
Должно ли внедрение быть запущено в целевом объекте как можно скорее. Обратите внимание, что это не гарантирует внедрение до загрузки страницы, поскольку страница может быть уже загружена к моменту, когда скрипт достигнет цели.
-
js
Список объектов ScriptSource, определяющих источники скриптов, которые нужно внедрить в целевой объект.
-
target
Сведения о цели, в которую нужно внедрить скрипт.
-
мир
ExecutionWorld необязательный
"Мир" JavaScript, в котором будет выполняться скрипт. Значение по умолчанию –
USER_SCRIPT. -
worldId
Строка (необязательно)
Указывает идентификатор среды пользовательского скрипта, в которой он должен выполняться. Если этот параметр опущен, скрипт будет выполняться в мире пользовательских скриптов по умолчанию. Действительно, только если
worldопущено или имеет значениеUSER_SCRIPT. Значения, начинающиеся с символа подчеркивания (_), зарезервированы.
WorldProperties
Свойства
-
csp
Строка (необязательно)
Указывает CSP мира. По умолчанию используется
`ISOLATED`. -
сообщение
Логическое значение (необязательно)
Указывает, доступны ли API для обмена сообщениями. Значение по умолчанию –
false. -
worldId
Строка (необязательно)
Chrome 133+ browser.* начиная с Chrome 148Указывает идентификатор конкретного мира пользовательских скриптов, который нужно обновить. Если не указано, обновляет свойства мира пользовательских скриптов по умолчанию. Значения, начинающиеся с символа подчеркивания (
_), зарезервированы.
Методы
configureWorld()
browser.userScripts.configureWorld(
properties: WorldProperties,
): Promise<void>
Настраивает среду выполнения `USER_SCRIPT`.
Параметры
-
объекты
Содержит конфигурацию среды пользовательского скрипта.
Возвраты
-
Promise<void>
Объект Promise, который распознается после настройки мира.
execute()
browser.userScripts.execute(
injection: UserScriptInjection,
): Promise<InjectionResult[]>
Добавление скриптов в целевой контекст. По умолчанию скрипт выполняется при событии document_idle или сразу же, если страница уже загружена. Если свойство injectImmediately задано, скрипт будет внедрен без ожидания, даже если страница не загрузилась полностью. Если скрипт возвращает объект Promise, браузер дождется его выполнения и вернет полученное значение.
Параметры
-
инъекция
Возвраты
-
Promise<InjectionResult[]>
getScripts()
browser.userScripts.getScripts(
filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>
Возвращает все динамически зарегистрированные пользовательские скрипты для этого расширения.
Параметры
-
фильтр
UserScriptFilter необязательный
Если указан, метод возвращает только соответствующие ему пользовательские скрипты.
Возвраты
-
Promise<RegisteredUserScript[]>
Promise, который разрешается с зарегистрированными скриптами. Если произойдет ошибка, объект Promise будет отклонен.
getWorldConfigurations()
browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>
Получает все зарегистрированные конфигурации мира.
Возвраты
-
Promise<WorldProperties[]>
Объект Promise, который распознается с зарегистрированными конфигурациями мира.
register()
browser.userScripts.register(
scripts: RegisteredUserScript[],
): Promise<void>
Регистрирует один или несколько пользовательских скриптов для этого расширения.
Параметры
-
скрипты
Содержит список пользовательских скриптов, которые нужно зарегистрировать.
Возвраты
-
Promise<void>
Объект Promise, который разрешается после полной регистрации скриптов. Если произойдет ошибка, объект Promise будет отклонен.
resetWorldConfiguration()
browser.userScripts.resetWorldConfiguration(
worldId?: string,
): Promise<void>
Сбрасывает конфигурацию для мира пользовательских скриптов. Любые скрипты, которые внедряются в мир с указанным идентификатором, будут использовать конфигурацию мира по умолчанию.
Параметры
-
worldId
Строка (необязательно)
Идентификатор среды пользовательского скрипта, которую нужно сбросить. Если не указать, сбрасывает конфигурацию мира по умолчанию.
Возвраты
-
Promise<void>
Объект Promise, который распознается, когда конфигурация сбрасывается.
unregister()
browser.userScripts.unregister(
filter?: UserScriptFilter,
): Promise<void>
Отменяет регистрацию всех динамически зарегистрированных пользовательских скриптов для этого расширения.
Параметры
-
фильтр
UserScriptFilter необязательный
Если указан, этот метод отменяет регистрацию только соответствующих ему пользовательских скриптов.
Возвраты
-
Promise<void>
Объект Promise, который распознается после полной отмены регистрации скриптов. Если произойдет ошибка, объект Promise будет отклонен.
update()
browser.userScripts.update(
scripts: RegisteredUserScript[],
): Promise<void>
Обновляет один или несколько пользовательских скриптов для этого расширения.
Параметры
-
скрипты
Содержит список пользовательских скриптов, которые нужно обновить. Свойство обновляется для существующего скрипта, только если оно указано в этом объекте. Если при синтаксическом анализе скрипта или проверке файла возникнут ошибки или если указанные идентификаторы не соответствуют полностью зарегистрированному скрипту, то скрипты не будут обновлены.
Возвраты
-
Promise<void>
Объект Promise, который разрешается после полного обновления скриптов. Если произойдет ошибка, объект Promise будет отклонен.