ресурсы, доступные в веб-среде

Иногда вам нужно упаковать ресурсы (например, изображения, HTML, CSS или JavaScript) со своим расширением и сделать их доступными для веб-страниц и других расширений.

Например, расширение Beastify заменяет веб-страницу изображением зверя, выбранного пользователем. Изображения зверей упакованы с расширением. Чтобы отобразить выбранное изображение, расширение добавляет элементы <img>, у которых атрибут src указывает на изображение зверя. Для возможности загрузки изображений веб-страницей, они должны быть доступны в веб-среде.

С помощью ключа web_accessible_resources вы перечисляете все упакованные ресурсы, которые вы хотите сделать доступными для веб-страниц. Вы указываете их как пути относительно файла manifest.json.

Обратите внимание, что скрипты содержимого не нужно указывать как ресурсы, доступные в веб-среде.

Если расширение хочет использовать webRequest для перенаправления публичного URL-адреса (например, HTTPS) на страницу, упакованную в расширение, то расширение должно указать страницу в ключе web_accessible_resources.

В манифесте V2 ресурсы, доступные в веб-среде, добавляются в виде массива под ключом, как это:

"web_accessible_resources": [
  "images/my-image.png"
]

В манифесте V3 ключ web_accessible_resources представляет собой массив объектов, как это:

{
  // …
  "web_accessible_resources": [
    {
      "resources": [ "test1.png", "test2.png" ],
      "matches": [ "https://web-accessible-resources-1.glitch.me/*" ]
    }, {
      "resources": [ "test3.png", "test4.png" ],
      "matches": [ "https://web-accessible-resources-2.glitch.me/*" ],
      "use_dynamic_url": true
    }
  ],
  // …
}

Каждый объект должен включать свойство "resources" и либо свойство "matches", либо свойство "extension_ids" из следующих свойств:

Предположим, ваше расширение содержит файл изображения по адресу images/my-image.png, как это:

my-extension-files/
    manifest.json
    my-background-script.js
    images/
        my-image.png

Чтобы позволить веб-странице использовать элемент <img>, у которого атрибут src указывает на это изображение, вы бы указали web_accessible_resources следующим образом:

"web_accessible_resources": ["images/my-image.png"]

Файл затем доступен по URL-адресу:

moz-extension://<extension-UUID>/images/my-image.png"

<extension-UUID> — не идентификатор вашего расширения. Этот идентификатор генерируется случайным образом для каждого экземпляра браузера. Это предотвращает определение браузера веб-сайтами путём анализа установленных расширений.

Рекомендуется использовать runtime.getURL для получения URL ресурса, передав путь относительно manifest.json, например:

browser.runtime.getURL("images/my-image.png");
// something like:
// moz-extension://944cfddf-7a95-3c47-bd9a-663b3ce8d699/images/my-image.png

Этот подход предоставляет вам правильный URL-адрес независимо от браузера, на котором запущено ваше расширение.

Записи web_accessible_resources могут содержать подстановочные знаки. Например, следующая запись также будет работать для включения ресурса по адресу "images/my-image.png":

  "web_accessible_resources": ["images/*.png"]

Если вы сделаете страницу доступной в веб-среде, любой веб-сайт может связаться с этой страницей или перенаправить на неё. Страница должна обрабатывать любой ввод (например, данные POST) так, как будто он пришёл из ненадежного источника, точно так же, как и обычная веб-страница.

Ресурсы расширений, доступные в веб-среде, не блокируются средствами CORS или CSP. Из-за этой возможности обхода проверок безопасности расширениям следует избегать использования веб-скриптов, когда это возможно. Веб-скрипт расширения может быть непредсказуемо использован вредоносными веб-сайтами для ослабления безопасности других веб-сайтов. Следуйте рекомендациям по безопасности, избегая вставки moz-extension:-URL-адресов на веб-страницы и гарантируя актуальность сторонних библиотек.

"web_accessible_resources": ["images/my-image.png"]

Сделать файл по адресу "images/my-image.png" доступным в веб-среде.