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+

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

Пользовательский скрипт — это фрагмент кода, внедряемый в веб-страницу для изменения ее внешнего вида или поведения. Сценарии либо создаются пользователями, либо загружаются из репозитория сценариев или расширения пользовательского сценария.

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

Как разработчик расширений, у вас уже включен режим разработчика в вашей установке 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 страницы.

RegisteredUserScript

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

  • всекадры

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

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

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

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

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

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

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

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

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

    нить

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

  • includeGlobs

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

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

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

  • спички

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

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

  • запуститьAt

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

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

  • мир

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

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

ScriptSource

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

  • код

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

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

  • файл

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

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

UserScriptFilter

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

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

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

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

WorldProperties

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

  • csp

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

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

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

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

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

Методы

configureWorld()

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

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

Параметры

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

    WorldProperties

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

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

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

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

    () => void

Возврат

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

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

getScripts()

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

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

Параметры

Возврат

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

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

register()

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

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

Параметры

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

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

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

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

    () => void

Возврат

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

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

unregister()

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

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

Параметры

  • фильтр

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

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

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

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

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

    () => void

Возврат

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

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

update()

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

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

Параметры

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

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

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

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

    () => void

Возврат

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

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