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

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

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

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

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

Все шаблоны совпадения объявляются в виде строк. За исключением специального <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:///*".

Совместимость с браузерами

BCD tables only load in the browser