Эта страница переведена с помощью 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/*"
  ]
}

Доступность

Хром 120+ МВ3+

Понятия и использование

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

Включить использование API userScripts

После того, как ваше расширение получит разрешение на использование 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 (переключение режима разработчика)

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

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

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

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

Переключатель «Разрешить пользовательские скрипты» находится на странице сведений о каждом расширении (например, 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 в расширении service worker. Отвечайте только на причину "update" переданную в обратный вызов события.

Пример

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

Зарегистрировать скрипт

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

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

Типы

ExecutionWorld

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

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

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

"USER_SCRIPT"
Указывает среду выполнения, которая относится только к пользовательским скриптам и не подпадает под действие CSP страницы.

InjectionResult

Хром 135+

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

documentId
нить
Документ, связанный с инъекцией.
ошибка
строка необязательная
Ошибка, если таковая имеется. error и result являются взаимоисключающими.
frameId
число
Кадр, связанный с инъекцией.
результат
любой необязательный
Результат выполнения скрипта.

InjectionTarget

Хром 135+

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

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

RegisteredUserScript

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

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

ScriptSource

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

код
строка необязательная
Строка, содержащая код JavaScript для внедрения. Необходимо указать только один file или code .
файл
строка необязательная
Путь к файлу JavaScript для внедрения относительно корневого каталога расширения. Необходимо указать только один file или code .

UserScriptFilter

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

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

UserScriptInjection

Хром 135+

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

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

WorldProperties

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

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

Методы

configureWorld()

Обещать

chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

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

Параметры

характеристики
WorldProperties
Содержит конфигурацию мира пользовательских сценариев.
перезвонить
функция необязательная
Параметр callback выглядит так:
```
() => void
```

Возвраты

Обещание<недействительно>
Обещания поддерживаются в Manifest V3 и более поздних версиях, но обратные вызовы предоставляются для обратной совместимости. Вы не можете использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передается обратному вызову.

execute()

Обещание Chrome 135+

chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

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

Параметры

инъекция
UserScriptInjection
перезвонить
функция необязательная
Параметр callback выглядит так:
```
(result: InjectionResult[]) => void
```
- результат
  РезультатИнъекции []

Возвраты

Обещание< РезультатИнъекции []>
Обещания поддерживаются в Manifest V3 и более поздних версиях, но обратные вызовы предоставляются для обратной совместимости. Вы не можете использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передается обратному вызову.

getScripts()

Обещать

chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

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

Параметры

фильтр
UserScriptFilter необязательно
Если указан, этот метод возвращает только соответствующие ему пользовательские скрипты.
перезвонить
функция необязательная
Параметр callback выглядит так:
```
(scripts: RegisteredUserScript[]) => void
```
- скрипты
  ЗарегистрированныйUserScript []

Возвраты

Обещание< RegisteredUserScript []>
Обещания поддерживаются в Manifest V3 и более поздних версиях, но обратные вызовы предоставляются для обратной совместимости. Вы не можете использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передается обратному вызову.

getWorldConfigurations()

Обещание Chrome 133+

chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

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

Параметры

перезвонить
функция необязательная
Параметр callback выглядит так:
```
(worlds: WorldProperties[]) => void
```
- миры
  WorldProperties []

Возвраты

Обещание< WorldProperties []>
Обещания поддерживаются в Manifest V3 и более поздних версиях, но обратные вызовы предоставляются для обратной совместимости. Вы не можете использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передается обратному вызову.

register()

Обещать

chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

Параметры

скрипты
ЗарегистрированныйUserScript []
Содержит список пользовательских скриптов, которые необходимо зарегистрировать.
перезвонить
функция необязательная
Параметр callback выглядит так:
```
() => void
```

Возвраты

Обещание<недействительно>
Обещания поддерживаются в Manifest V3 и более поздних версиях, но обратные вызовы предоставляются для обратной совместимости. Вы не можете использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передается обратному вызову.

resetWorldConfiguration()

Обещание Chrome 133+

chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

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

Параметры

worldId
строка необязательная
Идентификатор мира пользовательского скрипта для сброса. Если не указан, сбрасывает конфигурацию мира по умолчанию.
перезвонить
функция необязательная
Параметр callback выглядит так:
```
() => void
```

Возвраты

Обещание<недействительно>
Обещания поддерживаются в Manifest V3 и более поздних версиях, но обратные вызовы предоставляются для обратной совместимости. Вы не можете использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передается обратному вызову.

unregister()

Обещать

chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

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

Параметры

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

Возвраты

Обещание<недействительно>
Обещания поддерживаются в Manifest V3 и более поздних версиях, но обратные вызовы предоставляются для обратной совместимости. Вы не можете использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передается обратному вызову.

update()

Обещать

chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

Параметры

скрипты
ЗарегистрированныйUserScript []
Содержит список пользовательских скриптов для обновления. Свойство обновляется только для существующего скрипта, если оно указано в этом объекте. Если при разборе скрипта/проверке файла возникают ошибки или если указанные идентификаторы не соответствуют полностью зарегистрированному скрипту, то скрипты не обновляются.
перезвонить
функция необязательная
Параметр callback выглядит так:
```
() => void
```

Возвраты

Обещание<недействительно>
Обещания поддерживаются в Manifest V3 и более поздних версиях, но обратные вызовы предоставляются для обратной совместимости. Вы не можете использовать оба в одном вызове функции. Обещание разрешается с тем же типом, который передается обратному вызову.