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+

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

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

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

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

• js

  Источник сценария []

  Список объектов 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 установлено, скрипт внедрит данные без ожидания, даже если страница еще не завершила загрузку. Если сценарий вычисляет обещание, браузер будет ждать, пока обещание будет выполнено, и вернет полученное значение.

Параметры

• инъекция

  Юзерскриптинъекция

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

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

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

  (result: InjectionResult[]) => void

  • результат

    Результат инъекции []

Возврат

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

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

getScripts()

Обещать

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

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

Параметры

• фильтр

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

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

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

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

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

  (scripts: RegisteredUserScript[]) => void

  • сценарии

    ЗарегистрированныйПользовательСкрипт []

Возврат

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

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

getWorldConfigurations()

Обещание Chrome 133+

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

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

Параметры

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

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

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

  (worlds: WorldProperties[]) => void

  • миры

    Мировые свойства []

Возврат

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