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