This page was translated from English by the community.Learn more and join the MDN Web Docs community.
Шаблоны совпадения в расширении
Шаблоны совпадения - являются способом обозначения необходимых групп 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/pathhttps://a.mozilla.org/pathhttps://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/pathhttps://mozilla.org/anotherhttps://mozilla.org/path/to/dochttps://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/#section1https://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:///*". |