API URLPattern официально стал базовой возможностью и доступен во всех основных браузерах с сентября 2025 года. Однако он может не работать на старых устройствах или в старых браузерах. Узнать больше.

Когда требуется функциональность, реагирующая на изменения URL, часто приходится писать сложные регулярные выражения или подключать сторонние библиотеки для маршрутизации. Теперь, когда URL Pattern API вошел в Baseline, у нас появилось стандартное, мощное и универсальное решение для этой задачи.

API позволяет сопоставлять URL с привычным шаблоном, что значительно упрощает разбор и извлечение данных с помощью методов .exec() и .test().

const pattern = new URLPattern({ pathname: "/products/:id" });
console.log(pattern.test("https://example.com/products/123")); // true

Функциональность URL Pattern API реализована в интерфейсе URLPattern. В этой статье показаномы рассмотрим, как его использование помогает упростить и улучшить код при решении типичных задач.

❯ Базовое сопоставление URL

До появления URL Pattern API для проверки URL приходилось использовать старый интерфейс URL для разбора адреса, а затем применять отдельное — зачастую сложное — регулярное выражение к свойству .pathname, чтобы проверить совпадение:

const url = new URL(location.href);
const pathRegex = /^\/users\/([a-zA-Z0-9]+)\/?$/;
const isMatch = pathRegex.test(url.pathname);

С URLPattern эта задача выполняется проще, а код при этом читается гораздо легче:

const pattern = new URLPattern({ pathname: "/users/:id" });
const isMatch = pattern.test(location.href);

❯ Извлечение динамических параметров

Еще один распространенный сценарий использования URLPattern — извлечение динамических параметров из URL. Раньше для этого часто использовали числовые/порядковые группы захвата (numbered capture groups) в регулярных выражениях, которые были позиционными и анонимными. Параметры приходилось извлекать по индексу массива (result[1], result[2]), и такой подход был ненадежным при изменении порядка групп:

const pathRegex = /^\/books\/([a-z]+)\/(\d+)\/?$/;
const result = pathRegex.exec("/books/classics/12345");

// `result` — это массив:
// ["/books/classics/12345", "classics", "12345"]
const category = result ? result[1] : null;
const bookId = result ? result[2] : null;

URLPattern возвращает структурированный объект групп с именованными параметрами. Имена параметров напрямую соответствуют ключам в объекте, что делает код понятным и надежным:

// Шаблон для сопоставления /books/<category>/<id>
const pattern = new URLPattern({ pathname: "/books/:category/:id" });
const result = pattern.exec("/books/classics/12345");

// `result.pathname.groups` возвращает
// { category: "classics", id: "12345" }
const { category, id: bookId } = result.pathname.groups;

❯ Составление многокомпонентных совпадений

Раньше для проверки нескольких частей URL обычно использовали конструктор URL, чтобы получить отдельные компоненты (hostname, pathname), а затем выполняли отдельные проверки или применяли регулярные выражения к каждой из них:

const url = new URL(req.url);

if (url.hostname.endsWith(".cdn.com") && url.pathname.startsWith("/images/")) {
  // Выполняем нужные действия
}

URLPattern позволяет делать это напрямую, с понятным и предсказуемым управлением:

const pattern = new URLPattern({ hostname: "*.cdn.com", pathname: "/images/*" });

if (pattern.test(req.url)) {
  // Выполняем нужные действия
}

❯ Зависимости проекта

Раньше для надежной обработки URL часто приходилось подключать сторонние библиотеки для реализации логики роутинга.

Теперь, когда URLPattern официально доступен в Baseline, для таких задач можно обойтись без дополнительных зависимостей. Функциональность встроена прямо в браузер, что уменьшает размер сборки, избавляет от необходимости управлять внешними библиотеками и использует потенциально более производительную реализацию, работающую во всех основных движках браузеров.

❯ Подробное руководство по использованию

Преимущество URLPattern заключается в возможности работать как с простыми, так и с более сложными задачами. Можно начать с базового сопоставления путей и по мере необходимости постепенно подключать более продвинутые возможности. Ниже приведены примеры распространенных сценариев.

Сопоставление пути и извлечение параметров

Один из частых сценариев использования сопоставления URL — маршрутизация на стороне клиента. URLPattern упрощает этот процесс: с помощью .test() проверяется соответствие URL шаблону, а с помощью .exec() можно извлечь динамические параметры:

const pattern = new URLPattern({ pathname: "/products/:category/:id" });

// Используем .test() для проверки на true/false
console.log(pattern.test("https://example.com/products/electronics/123")); // → true
console.log(pattern.test("https://example.com/blog")); // → false

// Используем .exec() для извлечения именованных групп
const result = pattern.exec("https://example.com/products/electronics/123");

if (result) {
  const { category, id } = result.pathname.groups;
  console.log(`Загружается продукт ${id} из категории ${category}.`); // → "Загружается продукт 123 из категории electronics."
}

Сопоставление поддоменов и других частей URL

В отличие от многих библиотек для роутинга, URLPattern позволяет полностью сопоставлять URL. Это удобно для приложений, которые по-разному обрабатывают запросы в зависимости от хоста, например, для маршрутизации API-запросов на определенный поддомен.

В примере ниже создается шаблон, который соответствует только запросам к поддомену api и к конкретному пути:

const apiPattern = new URLPattern({
  hostname: ":subdomain.myapp.com",
  pathname: "/api/v:version/*"
});

const result = apiPattern.exec("https://api.myapp.com/api/v2/users");

if (result) {
  const { subdomain, version } = result.hostname.groups;
  console.log(`Запрос к поддомену '${subdomain}', версия API - ${version}.`); // → "Запрос к поддомену 'api', версия API - 2."
}

Подстановочные символы и регулярные выражения

Когда требуется большая гибкость, чем могут дать именованные группы, URLPattern поддерживает подстановочные символы (*) и встроенные регулярные выражения прямо в шаблонах для более точного управления.

Например, можно создать шаблон, который будет соответствовать любому изображению в директории пользователя и одновременно проверять, что ID пользователя — это число:

// :userId(\\d+) - совпадает с именованной группой userId, но только если она содержит одну и более цифр.
// * - подстановочный символ, совпадающий с любыми символами до следующего разделителя (например, '.')
const assetPattern = new URLPattern({
  pathname: "/users/:userId(\\d+)/assets/*.(jpg|png|gif)"
});

const result1 = assetPattern.exec("/users/123/assets/profile.jpg");
console.log(result1?.pathname.groups.userId); // → "123" (совпадение найдено)

const result2 = assetPattern.exec("/users/abc/assets/avatar.png");
console.log(result2); // → null (не совпадает, так как "abc" не является числом)

Практический пример: маршрутизация в сервис воркере

Service worker — отличное место для использования URLPattern. С его помощью можно аккуратно перехватывать запросы fetch и применять разные стратегии кэширования без громоздких регулярных выражений или условных проверок с помощью url.includes():

// В файле сервис воркера

const IMAGE_ASSETS = new URLPattern({ pathname: "/images/*" });
const API_CALLS = new URLPattern({ pathname: "/api/*" });

self.addEventListener("fetch", (event) => {
  const url = event.request.url;

  if (IMAGE_ASSETS.test(url)) {
    // Применяем стратегию cache-first для изображений
    event.respondWith(cacheFirst(event.request));
  } else if (API_CALLS.test(url)) {
    // Применяем стратегию network-first для API-запросов
    event.respondWith(networkFirst(event.request));
  }
});

Много лет обработка URL в браузере ассоциировалась со сложными регулярными выражениями или зависимостями от сторонних библиотек. URLPattern меняет это, предлагая надежное, гибкое и стандартизированное решение, встроенное прямо в браузер.

Поэтому в следующий раз, когда у вас появится соблазн написать регулярное выражение для разбора URL, стоит остановиться и обратить внимание на URLPattern. Можно переработать с его помощью сложный модуль роутинга или использовать в сервис воркере для обработки запросов fetch. Это поможет упростить код и, возможно, избавиться от лишней зависимости.

У URL Pattern API гораздо больше возможностей, чем описано здесь. Подробное руководство и полное описание всех возможностей можно найти в документации на MDN Web Docs.

Новости, обзоры продуктов и конкурсы от команды Timeweb.Cloud - в нашем Telegram-канале ↩