Шаблоны совпадения в расширении

Шаблоны совпадения - являются способом обозначения необходимых групп URL. Они используются в нескольких местах в WebExtensions API, главным образом для объявления какие веб-страницы должны загружать встраиваемые скрипты и по каким URL необходимо ожидать событий из  webRequest API.

API, которое использует шаблоны совпадения, обычно принимает их списками, и выполняет соответствующие действия, если URL имеет совпадение с одним из шаблонов. Например, взгляните на content_scripts ключ в manifest.json.

Структура шаблона совпадения

Заметьте: Некоторые браузеры не поддерживают определённые схемы.
Смотрите Browser compatibility table для дополнительной информации.

Все шаблоны совпадения объявляются в виде строк. За исключением специального <all_urls> шаблона, шаблоны совпадения состоят из трёх компонентов: схема, хост и путь. Схема и хост разделяются с помощью ://.

<схема>://<хост><путь>

Схема

Компонент схема может принимать один из двух видов:

Вид Совпадение
* Только "http" and "https", так же "ws" и "wss" в некоторых браузерах.
Одно из http, https, ws, wss, ftp, ftps, data или file. Только данная схема.

Хост

Компонент хост может принимать один из трёх видов:

Form Matches
* Любой хост.
*. за которыми следует частичное имя хоста. Данный хост и любые его субдомены.
Полное название хоста без *. Только данный хост.

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

Хост не обязателен, если схема задана, как "file".

Заметьте, что * звёздочка (символ универсального значения) может быть написана только в начале строки.

Путь

Компонент путь должен начинаться с / символа.

Вслед за ним он может иметь любую комбинацию символов и * звёздочек, которые позволено использовать для обозначения URL и строки параметров (начинается после ?). В отличии от хоста, путь может содержать * звёздочку в середине или в конце строки, и * звёздочка может появляться в строке более одного раза.

Значение пути сравнивается со строкой, которая представляет из себя URL и строку параметров. Если строка параметров присутствует в URL, тогда она отделяется от основного URL знаком ?. Если вы хотите иметь соответствие с URL на любом домене, где URL путь кончается на foo.bar, не зависимо от присутствия строки параметров, тогда вам нужно иметь массив шаблонов совпадений, например ['*://*/*foo.bar', '*://*/*foo.bar?*']. В этой ситуации необходимо использовать ?*, а не bar*, для того чтобы обозначить, что * будет применяться к строке параметров, а не к основной части URL пути.

Ни идентификатор якоря, ни предшествующая ему #, не считаются частями пути.

<all_urls>

Специальное значение <all_urls> совпадает со всеми URL, если они используются со следующими схемами: "http", "https", "ws", "wss", "ftp", "data", and "file".

Примеры

Шаблон Пример совпадения Пример несовпадения

<all_urls>

Совпадение со всеми URL.

http://example.org/

https://a.org/some/path/

ws://sockets.somewhere.org/

wss://ws.example.com/stuff/

ftp://files.somewhere.org/

ftps://files.somewhere.org/

resource://a/b/c/
(неподдерживаемая схема)

*://*/*

Совпадение со всеми HTTP, HTTPS и WebSocket URL.

http://example.org/

https://a.org/some/path/

ws://sockets.somewhere.org/

wss://ws.example.com/stuff/

ftp://ftp.example.org/
(несовпадающая схема)

ftps://ftp.example.org/
(несовпадающая схема)

file:///a/
(несовпадающая схема)

*://*.mozilla.org/*

Совпадение со всеми HTTP, HTTPS и WebSocket URL, которые находятся на "mozilla.org" или одном из её субдоменов.

http://mozilla.org/

https://mozilla.org/

http://a.mozilla.org/

http://a.b.mozilla.org/

https://b.mozilla.org/path/

ws://ws.mozilla.org/

wss://secure.mozilla.org/something

ftp://mozilla.org/
(несовпадающая схема)

http://mozilla.com/
(несовпадающий хост)

http://firefox.org/
(несовпадающий хост)

*://mozilla.org/

Совпадение со всеми HTTP, HTTPS и WebSocket URL, которые находятся исключительно на "mozilla.org/".

http://mozilla.org/

https://mozilla.org/

ws://mozilla.org/

wss://mozilla.org/

ftp://mozilla.org/
(несовпадающая схема)

http://a.mozilla.org/
(несовпадающий хост)

http://mozilla.org/a
(несовпадающий путь)

ftp://mozilla.org/

Совпадение только с "ftp://mozilla.org/".

ftp://mozilla.org

http://mozilla.org/
(несовпадающая схема)

ftp://sub.mozilla.org/
(несовпадающий хост)

ftp://mozilla.org/path
(несовпадающий путь)

https://*/path

Совпадение со всеми HTTPS URL на любом хосте, чей путь точно соответсвует "path".

https://mozilla.org/path

https://a.mozilla.org/path

https://something.com/path

http://mozilla.org/path
(несовпадающая схема)

https://mozilla.org/path/
(несовпадающий путь)

https://mozilla.org/a
(несовпадающий путь)

https://mozilla.org/
(несовпадающий путь)

https://mozilla.org/path?foo=1
(несовпадающий путь из-за строки параметров)

https://*/path/

Совпадение со всеми HTTPS URL на любом хосте, чей путь точно соответсвует "path/" и не имеет строки параметров.

https://mozilla.org/path/

https://a.mozilla.org/path/

https://something.com/path/

http://mozilla.org/path/
(несовпадающая схема)

https://mozilla.org/path
(несовпадающий путь)

https://mozilla.org/a
(несовпадающий путь)

https://mozilla.org/
(несовпадающий путь)

https://mozilla.org/path/?foo=1
(несовпадающий путь из-за строки параметров)

https://mozilla.org/*

Совпадение со всеми HTTPS URL только на домене "mozilla.org", с любым URL путём и строкой параметров.

https://mozilla.org/

https://mozilla.org/path

https://mozilla.org/another

https://mozilla.org/path/to/doc

https://mozilla.org/path/to/doc?foo=1

http://mozilla.org/path
(несовпадающая схема)

https://mozilla.com/path
(несовпадающий хост)

https://mozilla.org/a/b/c/

Совпадение только с данным URL, или данным URL, имеющим идентификатор якоря.

https://mozilla.org/a/b/c/

https://mozilla.org/a/b/c/#section1

Всё остальное.

https://mozilla.org/*/b/*/

Совпадение только с HTTPS URL, которые находятся на "mozilla.org", чей путь имеет сегмент "b" где-то в середине. Совпадёт с URL со строкой параметров, если эта строка параметров заканчивается на /.

https://mozilla.org/a/b/c/

https://mozilla.org/d/b/f/

https://mozilla.org/a/b/c/d/

https://mozilla.org/a/b/c/d/#section1

https://mozilla.org/a/b/c/d/?foo=/

https://mozilla.org/a?foo=21314&bar=/b/&extra=c/

https://mozilla.org/b/*/
(несовпадающий путь)

https://mozilla.org/a/b/
(несовпадающий путь)

https://mozilla.org/a/b/c/d/?foo=bar
(несовпадающий путь из-за строки параметров)

file:///blah/*

Совпадает с любым FILE URL, чей путь начинается с "blah".

file:///blah/

file:///blah/bleh

file:///bleh/
(несовпадающий путь)

Недопустимые шаблоны совпадения

Недопустимый шаблон Причина
resource://path/ Неподдерживаемая схема.
https://mozilla.org Отсутствие пути.
https://mozilla.*.org/ "*" в хосте должна присутствовать только в начале.
https://*zilla.org/ "*" в хосте должен быть единственным символом или сопровождаться  ".".
http*://mozilla.org/ "*" в схеме должен быть единственным символом.
https://mozilla.org:80/ Хост не должен включать в себя номер порта.
*://* Пустой путь: должно быть переписано, как "*://*/*".
file://* Пустой путь: должно быть переписано, как "file:///*".

Browser compatibility

scheme

BCD tables only load in the browser