Описание
Используйте API userScripts
для выполнения пользовательских сценариев в контексте пользовательских сценариев.
Разрешения
userScripts
Чтобы использовать API chrome.userScripts
, добавьте разрешение "userScripts"
в свой файл манифеста.json и "host_permissions"
для сайтов, на которых вы хотите запускать сценарии.
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
Доступность
Концепции и использование
Пользовательский скрипт — это фрагмент кода, внедряемый в веб-страницу для изменения ее внешнего вида или поведения. Сценарии либо создаются пользователями, либо загружаются из репозитория сценариев или расширения пользовательских сценариев.
Режим разработчика для пользователей расширений
Как разработчик расширений, у вас уже включен режим разработчика в вашей установке Chrome. Для расширений пользовательских сценариев вашим пользователям также потребуется включить режим разработчика. Ниже приведены инструкции, которые вы можете скопировать и вставить в свою документацию.
- Перейдите на страницу «Расширения», введя
chrome://extensions
на новой вкладке. (По замыслу URL-адресаchrome://
не могут быть связаны.) Включите режим разработчика, щелкнув тумблер рядом с режимом разработчика .
Страница расширений (chrome://extensions)
Вы можете определить, включен ли режим разработчика, проверив, выдает ли chrome.userScripts
ошибку. Например:
function isUserScriptsAvailable() {
try {
// Property access which throws if developer mode is not enabled.
chrome.userScripts;
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"
, переданную в обратный вызов события.
Пример
Этот пример взят из примера пользовательского сценария в нашем репозитории образцов.
Зарегистрировать скрипт
В следующем примере показан базовый вызов метода register()
. Первый аргумент — это массив объектов, определяющих регистрируемые скрипты. Вариантов больше, чем показано здесь.
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
Типы
ExecutionWorld
Мир JavaScript, в котором выполняется пользовательский скрипт.
Перечисление
"ОСНОВНОЙ" "ПОЛЬЗОВАТЕЛЬ_СКРИПТ"
Указывает среду выполнения DOM, которая является средой выполнения, используемой совместно с JavaScript главной страницы.
Указывает среду выполнения, специфичную для пользовательских сценариев и исключенную из CSP страницы.
RegisteredUserScript
Характеристики
- всекадры
логическое значение необязательно
Если это правда, он будет вставлен во все кадры, даже если этот кадр не является самым верхним кадром на вкладке. Каждый кадр проверяется независимо на соответствие требованиям URL; он не будет внедряться в дочерние фреймы, если требования URL-адреса не соблюдены. По умолчанию установлено значение false, что означает, что сопоставляется только верхний кадр.
- исключить глобусы
строка[] необязательно
Указывает шаблоны подстановочных знаков для страниц, в которые НЕ будет внедрен этот пользовательский скрипт.
- исключить совпадения
строка[] необязательно
Исключает страницы, в которые в противном случае был бы внедрен этот пользовательский скрипт. Дополнительные сведения о синтаксисе этих строк см. в разделе «Шаблоны совпадений» .
- идентификатор
нить
Идентификатор пользовательского скрипта, указанного в вызове API. Это свойство не должно начинаться с символа «_», поскольку оно зарезервировано в качестве префикса для сгенерированных идентификаторов сценариев.
- includeGlobs
строка[] необязательно
Указывает шаблоны подстановочных знаков для страниц, в которые будет внедрен этот пользовательский скрипт.
- js
Список объектов ScriptSource, определяющих источники скриптов, которые будут внедрены в соответствующие страницы.
- спички
строка[] необязательно
Указывает, на какие страницы будет внедрен этот пользовательский скрипт. Дополнительные сведения о синтаксисе этих строк см. в разделе «Шаблоны совпадений» . Это свойство должно быть указано для ${ref:register}.
- запуститьAt
RunAt необязательно
Указывает, когда файлы JavaScript внедряются на веб-страницу. Предпочтительным значением по умолчанию является
document_idle
. - мир
ExecutionWorld необязательно
Среда выполнения JavaScript, в которой будет запускаться сценарий. По умолчанию используется
`USER_SCRIPT`
.
ScriptSource
Характеристики
- код
строка необязательна
Строка, содержащая код JavaScript для внедрения. Должен быть указан ровно один
file
илиcode
. - файл
строка необязательна
Путь к файлу JavaScript для внедрения относительно корневого каталога расширения. Должен быть указан ровно один
file
илиcode
.
UserScriptFilter
Характеристики
- идентификаторы
строка[] необязательно
getScripts
возвращает только сценарии с идентификаторами, указанными в этом списке.
WorldProperties
Характеристики
- csp
строка необязательна
Указывает мировой csp. По умолчанию используется мировой csp
`ISOLATED`
. - обмен сообщениями
логическое значение необязательно
Указывает, доступны ли API обмена сообщениями. По умолчанию установлено значение
false
.
Методы
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
Настраивает среду выполнения `USER_SCRIPT`
.
Параметры
- характеристики
Содержит конфигурацию мира пользовательских сценариев.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
Возвращает все динамически зарегистрированные пользовательские сценарии для этого расширения.
Параметры
- фильтр
UserScriptFilter необязательно
Если указано, этот метод возвращает только те пользовательские сценарии, которые ему соответствуют.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(scripts: RegisteredUserScript[]) => void
- сценарии
Возврат
Обещание < RegisteredUserScript []>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
Регистрирует один или несколько пользовательских сценариев для этого расширения.
Параметры
- сценарии
Содержит список пользовательских сценариев, которые необходимо зарегистрировать.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
Отменяет регистрацию всех динамически зарегистрированных пользовательских сценариев для этого расширения.
Параметры
- фильтр
UserScriptFilter необязательно
Если этот метод указан, этот метод отменяет регистрацию только тех пользовательских сценариев, которые ему соответствуют.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
Обновляет один или несколько пользовательских сценариев для этого расширения.
Параметры
- сценарии
Содержит список пользовательских сценариев, которые необходимо обновить. Свойство обновляется только для существующего скрипта, если оно указано в этом объекте. Если при разборе скрипта/проверке файла возникают ошибки или если указанные идентификаторы не соответствуют полностью зарегистрированному скрипту, скрипты не обновляются.
- перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.