chrome.userScripts

Описание

Используйте 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/*"
  ]
}

Доступность

Хром 120+ МВ3+

Концепции и использование

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

Режим разработчика для пользователей расширений

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

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

  2. Включите режим разработчика, щелкнув тумблер рядом с режимом разработчика .

    Страница расширений

    Страница расширений (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 страницы.

InjectionResult

Хром 135+

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

  • идентификатор документа

    нить

    Документ, связанный с инъекцией.

  • ошибка

    строка необязательна

    Ошибка, если она есть. error и result являются взаимоисключающими.

  • идентификатор кадра

    число

    Рамка, связанная с инъекцией.

  • результат

    любые дополнительные

    Результат выполнения скрипта.

InjectionTarget

Хром 135+

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

  • всекадры

    логическое значение необязательно

    Должен ли сценарий внедряться во все кадры на вкладке. По умолчанию ложь. Это не должно быть правдой, если указаны frameIds .

  • идентификаторы документов

    строка[] необязательно

    Идентификаторы конкретных идентификаторов документов, в которые необходимо внедрить. Это не должно быть установлено, если установлен frameIds .

  • идентификаторы фреймов

    номер[] необязательно

    Идентификаторы конкретных кадров, в которые необходимо внедрить.

  • идентификатор табуляции

    число

    Идентификатор вкладки, в которую необходимо внедрить.

RegisteredUserScript

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

  • всекадры

    логическое значение необязательно

    Если это правда, он будет вставлен во все кадры, даже если этот кадр не является самым верхним кадром на вкладке. Каждый кадр проверяется независимо на соответствие требованиям URL; он не будет внедряться в дочерние фреймы, если требования URL-адреса не соблюдены. По умолчанию установлено значение false, что означает, что сопоставляется только верхний кадр.

  • исключить глобусы

    строка[] необязательно

    Указывает шаблоны подстановочных знаков для страниц, в которые НЕ будет внедрен этот пользовательский скрипт.

  • исключить совпадения

    строка[] необязательно

    Исключает страницы, в которые в противном случае был бы внедрен этот пользовательский скрипт. Дополнительные сведения о синтаксисе этих строк см. в разделе «Шаблоны совпадений» .

  • идентификатор

    нить

    Идентификатор пользовательского скрипта, указанного в вызове API. Это свойство не должно начинаться с символа «_», поскольку оно зарезервировано в качестве префикса для сгенерированных идентификаторов сценариев.

  • includeGlobs

    строка[] необязательно

    Указывает шаблоны подстановочных знаков для страниц, в которые будет внедрен этот пользовательский скрипт.

  • js

    ScriptSource [] необязательно

    Список объектов ScriptSource, определяющих источники скриптов, которые будут внедрены в соответствующие страницы. Это свойство должно быть указано для ${ref:register}, и если оно указано, оно должно быть непустым массивом.

  • спички

    строка[] необязательно

    Указывает, на какие страницы будет внедрен этот пользовательский скрипт. Дополнительные сведения о синтаксисе этих строк см. в разделе «Шаблоны совпадений» . Это свойство должно быть указано для ${ref:register}.

  • запуститьAt

    RunAt необязательно

    Указывает, когда файлы JavaScript внедряются на веб-страницу. Предпочтительным значением по умолчанию является document_idle .

  • мир

    ExecutionWorld необязательно

    Среда выполнения JavaScript, в которой будет запускаться сценарий. По умолчанию используется `USER_SCRIPT` .

  • worldId

    строка необязательна

    Хром 133+

    Указывает идентификатор мира пользовательских сценариев для выполнения. Если этот параметр опущен, сценарий будет выполняться в мире пользовательских сценариев по умолчанию. Допустимо только в том случае, если world опущен или имеет значение USER_SCRIPT . Значения с начальным подчеркиванием ( _ ) зарезервированы.

ScriptSource

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

  • код

    строка необязательна

    Строка, содержащая код JavaScript для внедрения. Должен быть указан ровно один file или code .

  • файл

    строка необязательна

    Путь к файлу JavaScript для внедрения относительно корневого каталога расширения. Должен быть указан ровно один file или code .

UserScriptFilter

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

  • идентификаторы

    строка[] необязательно

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

UserScriptInjection

Хром 135+

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

  • вводить немедленно

    логическое значение необязательно

    Должна ли инъекция быть запущена в цель как можно скорее. Обратите внимание, что это не является гарантией того, что внедрение произойдет до загрузки страницы, поскольку страница может быть уже загружена к тому времени, когда скрипт достигнет цели.

  • Список объектов ScriptSource, определяющих источники скриптов, которые будут внедрены в цель.

  • Подробности, определяющие цель, в которую нужно внедрить скрипт.

  • мир

    ExecutionWorld необязательно

    «Мир» JavaScript для запуска сценария. Значение по умолчанию — USER_SCRIPT .

  • worldId

    строка необязательна

    Указывает идентификатор мира пользовательских сценариев для выполнения. Если этот параметр опущен, сценарий будет выполняться в мире пользовательских сценариев по умолчанию. Допустимо только в том случае, если world опущен или имеет значение USER_SCRIPT . Значения с начальным подчеркиванием ( _ ) зарезервированы.

WorldProperties

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

  • csp

    строка необязательна

    Указывает мировой csp. По умолчанию используется мировой csp `ISOLATED` .

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

    логическое значение необязательно

    Указывает, доступны ли API обмена сообщениями. По умолчанию установлено значение false .

  • worldId

    строка необязательна

    Хром 133+

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

Методы

configureWorld()

Обещать
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

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

Параметры

  • характеристики

    WorldProperties

    Содержит конфигурацию мира пользовательских сценариев.

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    () => void

Возврат

  • Обещание<void>

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

execute()

Обещание Chrome 135+
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

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

Параметры

Возврат

  • Обещание< InjectionResult []>

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

getScripts()

Обещать
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

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

Параметры

Возврат

  • Обещание < RegisteredUserScript []>

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

getWorldConfigurations()

Обещание Chrome 133+
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

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

Параметры

Возврат

  • Обещание< WorldProperties []>

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

register()

Обещать
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

Параметры

  • Содержит список пользовательских сценариев, которые необходимо зарегистрировать.

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    () => void

Возврат

  • Обещание<void>

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

resetWorldConfiguration()

Обещание Chrome 133+
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

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

Параметры

  • worldId

    строка необязательна

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

  • перезвонить

    функция необязательна

    Параметр 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 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

,

Описание

Используйте 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/*"
  ]
}

Доступность

Хром 120+ МВ3+

Концепции и использование

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

Режим разработчика для пользователей расширений

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

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

  2. Включите режим разработчика, щелкнув тумблер рядом с режимом разработчика .

    Страница расширений

    Страница расширений (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 страницы.

InjectionResult

Хром 135+

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

  • идентификатор документа

    нить

    Документ, связанный с инъекцией.

  • ошибка

    строка необязательна

    Ошибка, если она есть. error и result являются взаимоисключающими.

  • идентификатор кадра

    число

    Рамка, связанная с инъекцией.

  • результат

    любые дополнительные

    Результат выполнения скрипта.

InjectionTarget

Хром 135+

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

  • всекадры

    логическое значение необязательно

    Должен ли сценарий внедряться во все кадры на вкладке. По умолчанию ложь. Это не должно быть правдой, если указаны frameIds .

  • идентификаторы документов

    строка[] необязательно

    Идентификаторы конкретных идентификаторов документов, в которые необходимо внедрить. Это не должно быть установлено, если установлен frameIds .

  • идентификаторы фреймов

    номер[] необязательно

    Идентификаторы конкретных кадров, в которые необходимо внедрить.

  • идентификатор табуляции

    число

    Идентификатор вкладки, в которую необходимо внедрить.

RegisteredUserScript

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

  • всекадры

    логическое значение необязательно

    Если это правда, он будет вставлен во все кадры, даже если этот кадр не является самым верхним кадром на вкладке. Каждый кадр проверяется независимо на соответствие требованиям URL; он не будет внедряться в дочерние фреймы, если требования URL-адреса не соблюдены. По умолчанию установлено значение false, что означает, что сопоставляется только верхний кадр.

  • исключить глобусы

    строка[] необязательно

    Указывает шаблоны подстановочных знаков для страниц, в которые НЕ будет внедрен этот пользовательский скрипт.

  • исключить совпадения

    строка[] необязательно

    Исключает страницы, в которые в противном случае был бы внедрен этот пользовательский скрипт. Дополнительные сведения о синтаксисе этих строк см. в разделе «Шаблоны совпадений» .

  • идентификатор

    нить

    Идентификатор пользовательского скрипта, указанного в вызове API. Это свойство не должно начинаться с символа «_», поскольку оно зарезервировано в качестве префикса для сгенерированных идентификаторов сценариев.

  • includeGlobs

    строка[] необязательно

    Указывает шаблоны подстановочных знаков для страниц, в которые будет внедрен этот пользовательский скрипт.

  • js

    ScriptSource [] необязательно

    Список объектов ScriptSource, определяющих источники скриптов, которые будут внедрены в соответствующие страницы. Это свойство должно быть указано для ${ref:register}, и если оно указано, оно должно быть непустым массивом.

  • спички

    строка[] необязательно

    Указывает, на какие страницы будет внедрен этот пользовательский скрипт. Дополнительные сведения о синтаксисе этих строк см. в разделе «Шаблоны совпадений» . Это свойство должно быть указано для ${ref:register}.

  • запуститьAt

    RunAt необязательно

    Указывает, когда файлы JavaScript внедряются на веб-страницу. Предпочтительным значением по умолчанию является document_idle .

  • мир

    ExecutionWorld необязательно

    Среда выполнения JavaScript, в которой будет запускаться сценарий. По умолчанию используется `USER_SCRIPT` .

  • worldId

    строка необязательна

    Хром 133+

    Указывает идентификатор мира пользовательских сценариев для выполнения. Если этот параметр опущен, сценарий будет выполняться в мире пользовательских сценариев по умолчанию. Допустимо только в том случае, если world опущен или имеет значение USER_SCRIPT . Значения с начальным подчеркиванием ( _ ) зарезервированы.

ScriptSource

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

  • код

    строка необязательна

    Строка, содержащая код JavaScript для внедрения. Должен быть указан ровно один file или code .

  • файл

    строка необязательна

    Путь к файлу JavaScript для внедрения относительно корневого каталога расширения. Должен быть указан ровно один file или code .

UserScriptFilter

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

  • идентификаторы

    строка[] необязательно

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

UserScriptInjection

Хром 135+

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

  • вводить немедленно

    логическое значение необязательно

    Должна ли инъекция быть запущена в цель как можно скорее. Обратите внимание, что это не является гарантией того, что внедрение произойдет до загрузки страницы, поскольку страница может быть уже загружена к тому времени, когда скрипт достигнет цели.

  • Список объектов ScriptSource, определяющих источники скриптов, которые будут внедрены в цель.

  • Подробности, определяющие цель, в которую нужно внедрить скрипт.

  • мир

    ExecutionWorld необязательно

    «Мир» JavaScript для запуска сценария. Значение по умолчанию — USER_SCRIPT .

  • worldId

    строка необязательна

    Указывает идентификатор мира пользовательских сценариев для выполнения. Если этот параметр опущен, сценарий будет выполняться в мире пользовательских сценариев по умолчанию. Допустимо только в том случае, если world опущен или имеет значение USER_SCRIPT . Значения с начальным подчеркиванием ( _ ) зарезервированы.

WorldProperties

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

  • csp

    строка необязательна

    Указывает мировой csp. По умолчанию используется мировой csp `ISOLATED` .

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

    логическое значение необязательно

    Указывает, доступны ли API обмена сообщениями. По умолчанию установлено значение false .

  • worldId

    строка необязательна

    Хром 133+

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

Методы

configureWorld()

Обещать
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

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

Параметры

  • характеристики

    WorldProperties

    Содержит конфигурацию мира пользовательских сценариев.

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    () => void

Возврат

  • Обещание<void>

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

execute()

Обещание Chrome 135+
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

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

Параметры

Возврат

  • Обещание< InjectionResult []>

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

getScripts()

Обещать
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

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

Параметры

Возврат

  • Обещание < RegisteredUserScript []>

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

getWorldConfigurations()

Обещание Chrome 133+
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

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

Параметры

Возврат

  • Обещание< WorldProperties []>

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

register()

Обещать
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

Параметры

  • Содержит список пользовательских сценариев, которые необходимо зарегистрировать.

  • перезвонить

    функция необязательна

    Параметр callback выглядит так: 

    () => void

Возврат

  • Обещание<void>

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

resetWorldConfiguration()

Обещание Chrome 133+
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

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

Параметры

  • worldId

    строка необязательна

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

  • перезвонить

    функция необязательна

    Параметр 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 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

,

Описание

Используйте 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/*"
  ]
}

Доступность

Хром 120+ МВ3+

Концепции и использование

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

Режим разработчика для пользователей расширений

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

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

  2. Включите режим разработчика, щелкнув тумблер рядом с режимом разработчика .

    Страница расширений

    Страница расширений (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 страницы.

InjectionResult

Хром 135+

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

  • идентификатор документа

    нить

    Документ, связанный с инъекцией.

  • ошибка

    строка необязательна

    Ошибка, если она есть. error и result являются взаимоисключающими.

  • идентификатор кадра

    число

    Рамка, связанная с инъекцией.

  • результат

    любые дополнительные

    Результат выполнения скрипта.

InjectionTarget

Хром 135+

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

  • всекадры

    логическое значение необязательно

    Должен ли сценарий внедряться во все кадры на вкладке. По умолчанию ложь. Это не должно быть правдой, если указаны frameIds .

  • идентификаторы документов

    строка[] необязательно

    Идентификаторы конкретных документов для введения. Это не должно быть установлено, если frameIds установлен.

  • Frameids

    номер [] необязательно

    Идентификаторы конкретных кадров в впрыскивание.

  • табид

    число

    Идентификатор вкладки, в которую для инъекции.

RegisteredUserScript

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

  • Allframes

    Логический необязательный

    Если это правда, он будет вводить во все кадры, даже если кадр не является наиболее максимальной кадром на вкладке. Каждый кадр проверяется независимо на требования URL; Он не будет вводить в детские рамки, если требования URL не будут выполнены. По умолчанию ложно, что означает, что только верхний кадр соответствует.

  • ExculideGlobs

    String [] Необязательно

    Определяет схемы подстановочных знаков для страниц. Этот пользовательский скрипт не будет введен.

  • ExcludeMatches

    String [] Необязательно

    Исключает страницы, в которые в противном случае был бы введен этот пользовательский скрипт. Смотрите шаблоны соответствия для более подробной информации о синтаксисе этих строк.

  • идентификатор

    нить

    Идентификатор пользовательского сценария, указанный в вызове API. Это свойство не должно начинаться с «_», поскольку оно зарезервировано в качестве префикса для сгенерированных идентификаторов сценария.

  • Включите Globs

    String [] Необязательно

    Определяет схемы подстановочных знаков для страниц, в этот сценарий будет введен этот пользовательский скрипт.

  • js

    ScriptSource [] Необязательно

    Список объектов ScriptSource, определяющих источники сценариев, которые должны быть введены в соответствующие страницы. Это свойство должно быть указано для $ {ref: Register}, а когда указано, это должно быть непустые массивы.

  • спички

    String [] Необязательно

    Определяет, в какие страницы будут введены этот пользовательский скрипт. Смотрите шаблоны соответствия для более подробной информации о синтаксисе этих строк. Это свойство должно быть указано для $ {ref: Register}.

  • Рунат

    Runat необязательно

    Определяет, когда файлы JavaScript вводят в веб -страницу. Предпочтительным значением по умолчанию является document_idle .

  • мир

    Executionworld необязательно

    Среда выполнения JavaScript для запуска сценария. По умолчанию `USER_SCRIPT` .

  • Всемирный

    Строка необязательно

    Хром 133+

    Определяет идентификатор мира пользователя для выполнения. Если пропущен, скрипт будет выполняться в мире пользовательского скрипта по умолчанию. Только действительный, если world опущен или USER_SCRIPT . Значения с ведущими подчеркиваниями ( _ ) зарезервированы.

ScriptSource

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

  • код

    Строка необязательно

    Строка, содержащая код JavaScript для ввода. Один из file или code должен быть указан.

  • файл

    Строка необязательно

    Путь файла JavaScript к внедрению относительно корневого каталога расширения. Один из file или code должен быть указан.

UserScriptFilter

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

  • идентификаторы

    String [] Необязательно

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

UserScriptInjection

Хром 135+

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

  • сразу же

    Логический необязательный

    Должна ли инъекция быть вызвана в цель как можно скорее. Обратите внимание, что это не является гарантией того, что впрыска произойдет до загрузки страницы, так как страница, возможно, уже загружена к моменту сценария достигнут цели.

  • Список объектов ScriptSource, определяющих источники сценариев, которые должны быть введены в цель.

  • цель

    IncectionTarget

    Подробности, в которой указано цель, в которую вводят сценарий.

  • мир

    Executionworld необязательно

    JavaScript "World" для запуска скрипта. По умолчанию USER_SCRIPT .

  • Всемирный

    Строка необязательно

    Определяет идентификатор мира пользователя для выполнения. Если пропущен, скрипт будет выполняться в мире пользовательского скрипта по умолчанию. Только действительный, если world опущен или USER_SCRIPT . Значения с ведущими подчеркиваниями ( _ ) зарезервированы.

WorldProperties

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

  • csp

    Строка необязательно

    Указывает мир CSP. По умолчанию является `ISOLATED` World CSP.

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

    Логический необязательный

    Определяет, выявляются ли API -интерфейсы обмена сообщениями. По умолчанию false .

  • Всемирный

    Строка необязательно

    Хром 133+

    Определяет идентификатор конкретного мира пользователя для обновления. Если не предоставлено, обновляет свойства мира пользовательских сценариев по умолчанию. Значения с ведущими подчеркиваниями ( _ ) зарезервированы.

Методы

configureWorld()

Обещать
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Конфигурирует среду выполнения `USER_SCRIPT` .

Параметры

  • характеристики

    WorldProperties

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

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    () => void

Возврат

  • Обещание <Void>

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

execute()

Обещай хром 135+
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

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

Параметры

Возврат

  • Обещание < incectionResult []>

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

getScripts()

Обещать
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

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

Параметры

  • фильтр

    USERSCRICTFILTER Необязательно

    Если указано, этот метод возвращает только пользовательские сценарии, которые соответствуют его.

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    (scripts: RegisteredUserScript[]) => void

Возврат

  • Обещание < receledEdUserScript []>

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

getWorldConfigurations()

Обещай хром 133+
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

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

Параметры

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    (worlds: WorldProperties[]) => void

Возврат

  • Обещание < WorldProperties []>

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

register()

Обещать
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

Параметры

  • сценарии

    RecelededUserscript []

    Содержит список пользовательских сценариев, которые будут зарегистрированы.

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    () => void

Возврат

  • Обещание <Void>

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

resetWorldConfiguration()

Обещай хром 133+
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

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

Параметры

  • Всемирный

    Строка необязательно

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

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    () => void

Возврат

  • Обещание <Void>

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

unregister()

Обещать
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

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

Параметры

  • фильтр

    USERSCRICTFILTER Необязательно

    Если указан, этот метод нерегистрирует только пользовательские сценарии, которые соответствуют ему.

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    () => void

Возврат

  • Обещание <Void>

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

update()

Обещать
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

Параметры

  • сценарии

    RecelededUserscript []

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

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    () => void

Возврат

  • Обещание <Void>

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

,

Описание

Используйте 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+ MV3+

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

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

Режим разработчика для пользователей расширения

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

  1. Перейдите на страницу расширений, введя chrome://extensions на новой вкладке. (По дизайну chrome:// url не связаны.)

  2. Включите режим разработчика, нажав переключатель переключателя рядом с режимом разработчика .

    Страница расширений

    Страница расширений (Chrome: // расширения)

Вы можете определить, включен ли режим разработчика, проверив, бросает ли 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

World JavaScript для пользовательского скрипта для выполнения внутри.

Перевозить

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

"User_script"
Определяет среду выполнения, характерную для пользовательских сценариев и освобождается от CSP страницы.

InjectionResult

Хром 135+

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

  • DocumentId

    нить

    Документ, связанный с инъекцией.

  • ошибка

    Строка необязательно

    Ошибка, если таковая имеется. error и result являются взаимоисключающими.

  • FrameID

    число

    Рама, связанная с инъекцией.

  • результат

    Любой необязательный

    Результат выполнения скрипта.

InjectionTarget

Хром 135+

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

  • Allframes

    Логический необязательный

    Должен ли сценарий вводить во все кадры на вкладке. По умолчанию ложь. Это не должно быть правдой, если frameIds указан.

  • документы

    String [] Необязательно

    Идентификаторы конкретных документов для введения. Это не должно быть установлено, если frameIds установлен.

  • Frameids

    номер [] необязательно

    Идентификаторы конкретных кадров в впрыскивание.

  • табид

    число

    Идентификатор вкладки, в которую для инъекции.

RegisteredUserScript

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

  • Allframes

    Логический необязательный

    Если это правда, он будет вводить во все кадры, даже если кадр не является наиболее максимальной кадром на вкладке. Каждый кадр проверяется независимо на требования URL; Он не будет вводить в детские рамки, если требования URL не будут выполнены. По умолчанию ложно, что означает, что только верхний кадр соответствует.

  • ExculideGlobs

    String [] Необязательно

    Определяет схемы подстановочных знаков для страниц. Этот пользовательский скрипт не будет введен.

  • ExcludeMatches

    String [] Необязательно

    Исключает страницы, в которые в противном случае был бы введен этот пользовательский скрипт. Смотрите шаблоны соответствия для более подробной информации о синтаксисе этих строк.

  • идентификатор

    нить

    Идентификатор пользовательского сценария, указанный в вызове API. Это свойство не должно начинаться с «_», поскольку оно зарезервировано в качестве префикса для сгенерированных идентификаторов сценария.

  • Включите Globs

    String [] Необязательно

    Определяет схемы подстановочных знаков для страниц, в этот сценарий будет введен этот пользовательский скрипт.

  • js

    ScriptSource [] Необязательно

    Список объектов ScriptSource, определяющих источники сценариев, которые должны быть введены в соответствующие страницы. Это свойство должно быть указано для $ {ref: Register}, а когда указано, это должно быть непустые массивы.

  • спички

    String [] Необязательно

    Определяет, в какие страницы будут введены этот пользовательский скрипт. Смотрите шаблоны соответствия для более подробной информации о синтаксисе этих строк. Это свойство должно быть указано для $ {ref: Register}.

  • Рунат

    Runat необязательно

    Определяет, когда файлы JavaScript вводят в веб -страницу. Предпочтительным значением по умолчанию является document_idle .

  • мир

    Executionworld необязательно

    Среда выполнения JavaScript для запуска сценария. По умолчанию `USER_SCRIPT` .

  • Всемирный

    Строка необязательно

    Хром 133+

    Определяет идентификатор мира пользователя для выполнения. Если пропущен, скрипт будет выполняться в мире пользовательского скрипта по умолчанию. Только действительный, если world опущен или USER_SCRIPT . Значения с ведущими подчеркиваниями ( _ ) зарезервированы.

ScriptSource

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

  • код

    Строка необязательно

    Строка, содержащая код JavaScript для ввода. Один из file или code должен быть указан.

  • файл

    Строка необязательно

    Путь файла JavaScript к внедрению относительно корневого каталога расширения. Один из file или code должен быть указан.

UserScriptFilter

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

  • идентификаторы

    String [] Необязательно

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

UserScriptInjection

Хром 135+

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

  • сразу же

    Логический необязательный

    Должна ли инъекция быть вызвана в цель как можно скорее. Обратите внимание, что это не является гарантией того, что впрыска произойдет до загрузки страницы, так как страница, возможно, уже загружена к моменту сценария достигнут цели.

  • Список объектов ScriptSource, определяющих источники сценариев, которые должны быть введены в цель.

  • цель

    IncectionTarget

    Подробности, в которой указано цель, в которую вводят сценарий.

  • мир

    Executionworld необязательно

    JavaScript "World" для запуска скрипта. По умолчанию USER_SCRIPT .

  • Всемирный

    Строка необязательно

    Определяет идентификатор мира пользователя для выполнения. Если пропущен, скрипт будет выполняться в мире пользовательского скрипта по умолчанию. Только действительный, если world опущен или USER_SCRIPT . Значения с ведущими подчеркиваниями ( _ ) зарезервированы.

WorldProperties

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

  • csp

    Строка необязательно

    Указывает мир CSP. По умолчанию является `ISOLATED` World CSP.

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

    Логический необязательный

    Определяет, выявляются ли API -интерфейсы обмена сообщениями. По умолчанию false .

  • Всемирный

    Строка необязательно

    Хром 133+

    Определяет идентификатор конкретного мира пользователя для обновления. Если не предоставлено, обновляет свойства мира пользовательских сценариев по умолчанию. Значения с ведущими подчеркиваниями ( _ ) зарезервированы.

Методы

configureWorld()

Обещать
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Конфигурирует среду выполнения `USER_SCRIPT` .

Параметры

  • характеристики

    WorldProperties

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

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    () => void

Возврат

  • Обещание <Void>

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

execute()

Обещай хром 135+
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

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

Параметры

Возврат

  • Обещание < incectionResult []>

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

getScripts()

Обещать
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

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

Параметры

  • фильтр

    USERSCRICTFILTER Необязательно

    Если указано, этот метод возвращает только пользовательские сценарии, которые соответствуют его.

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    (scripts: RegisteredUserScript[]) => void

Возврат

  • Обещание < receledEdUserScript []>

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

getWorldConfigurations()

Обещай хром 133+
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

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

Параметры

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    (worlds: WorldProperties[]) => void

Возврат

  • Обещание < WorldProperties []>

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

register()

Обещать
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

Параметры

  • сценарии

    RecelededUserscript []

    Содержит список пользовательских сценариев, которые будут зарегистрированы.

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    () => void

Возврат

  • Обещание <Void>

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

resetWorldConfiguration()

Обещай хром 133+
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

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

Параметры

  • Всемирный

    Строка необязательно

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

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    () => void

Возврат

  • Обещание <Void>

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

unregister()

Обещать
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

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

Параметры

  • фильтр

    USERSCRICTFILTER Необязательно

    Если указан, этот метод нерегистрирует только пользовательские сценарии, которые соответствуют ему.

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    () => void

Возврат

  • Обещание <Void>

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

update()

Обещать
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

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

Параметры

  • сценарии

    RecelededUserscript []

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

  • перезвонить

    функция необязательно

    Параметр callback выглядит как: 

    () => void

Возврат

  • Обещание <Void>

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