URLPattern agora está na linha de base. Recentemente disponível | Blogue

👋

Soluções Web

Atualizado em 22 outubro, 2025

Compartilhe

Publicado: 20 de outubro de 2025

Se você já criou um recurso que precisa reagir a alterações de URL, provavelmente já se viu escrevendo expressões regulares complexas ou recorrendo a uma biblioteca de terceiros para roteamento. O API de padrão de URLagora disponível como linha de base recentemente, fornece uma solução padronizada, poderosa e interoperável para esse desafio comum.

Ele permite combinar URLs com uma sintaxe de padrão familiar, tornando muito menos difícil analisar URLs e extrair dados com métodos como .exec() e .test().

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

A funcionalidade da API URL Pattern está disponível no URLPattern interface. Nesta postagem, você verá como usá-lo pode ajudar a melhorar sua base de código ao se deparar com alguns desafios comuns.

Correspondência básica de padrões de URL

Antes da disponibilidade da API de padrão de URL, a correspondência básica de padrões de URL geralmente significava combinar quanto mais velho URL interface para analisar um URL e, em seguida, aplique uma expressão regular separada, muitas vezes complexa, ao .pathname propriedade para testar uma correspondência.

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

Com URLPatternesta tarefa agora requer menos código e é mais fácil de ler:

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

Outro caso de uso comum para URLPattern é quando você precisa extrair parâmetros dinâmicos de um URL. No passado, muitas vezes se confiava em grupos numerados de captura de expressões regulares, que são posicionais e anônimos. Você tinha que acessar os parâmetros pelo índice do array (result(1), result(2)), que é frágil quando a ordem dos grupos de captura muda.

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

// `result` is an array:
// ("/books/classics/12345", "classics", "12345")
const category = result ? result(1) : null;
const bookId = result ? result(2) : null;

URLPattern retorna um objeto de grupos estruturados, apresentando parâmetros nomeados. Os nomes correspondem diretamente às chaves no objeto resultante, levando a um código explícito e robusto.

// Pattern to match /books//
const pattern = new URLPattern({ pathname: "/books/:category/:id" });
const result = pattern.exec("/books/classics/12345");

// `result.pathname.groups` will return:
// { category: "classics", id: "12345" }
const { category, id: bookId } = result.pathname.groups;

Compor correspondências multipartes

A maneira típica de compor correspondências multipartes para um URL no passado seria usar o URL construtor para obter peças individuais (hostname, pathname) e execute verificações separadas ou expressões regulares em cada um.

const url = new URL(req.url);

if (url.hostname.endsWith(".cdn.com") && url.pathname.startsWith("/images/")) {
  // Do something
}

URLPattern suporta isso nativamente, com controles previsíveis:

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

if (pattern.test(req.url)) {
  // Do something
}

Dependências do projeto

Antes de URLPatterno processamento de strings de URL geralmente era delegado a uma biblioteca de terceiros para o pacote de aplicativos para lidar com a lógica de roteamento de maneira robusta.

Agora isso URLPattern é Baseline recentemente disponível, você não terá nenhuma dependência para fazer esse tipo de trabalho. A funcionalidade é integrada ao navegador, reduzindo o tamanho do pacote, eliminando a dependência de gerenciamento e usando uma implementação no navegador com potencial de melhor desempenho que funciona em todos os principais mecanismos de navegador.

Uso detalhado

A utilidade de URLPattern está em sua capacidade de atender casos de uso básicos e avançados. Você pode começar com uma correspondência de caminho mais simples e adicionar recursos mais poderosos conforme necessário. Aqui estão alguns cenários comuns.

Combine um caminho e extraia parâmetros

Um caso de uso comum de correspondência de padrões de URL é o roteamento do lado do cliente. URLPattern deixa muito limpo. Você pode verificar se um URL corresponde a um padrão com .test()e extraia as partes dinâmicas com .exec().

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

// Use .test() for a boolean check
console.log(pattern.test("https://example.com/products/electronics/123")); // → true
console.log(pattern.test("https://example.com/blog")); // → false

// Use .exec() to extract the named groups
const result = pattern.exec("https://example.com/products/electronics/123");

if (result) {
  const { category, id } = result.pathname.groups;
  console.log(`Loading product ${id} from the ${category} category.`); // → "Loading product 123 from the electronics category."
}

Como combinar subdomínios e muito mais

Ao contrário de muitas bibliotecas de roteamento, URLPattern é uma correspondência de URL completa. Isso é perfeito para aplicativos que se comportam de maneira diferente com base no nome do host, como rotear chamadas de API para um subdomínio específico.

Aqui, é criado um padrão que corresponde apenas às solicitações de um api subdomínio e um caminho específico.

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(`Request to the '${subdomain}' subdomain, API version ${version}.`); // → "Request to the 'api' subdomain, API version 2."
}

Curingas e expressões regulares

Quando você precisar de mais flexibilidade do que os grupos nomeados por si só podem oferecer, URLPattern suporta caracteres curinga (*) e incorporando expressões regulares diretamente em seus padrões para melhor controle.

Por exemplo, aqui está um padrão para corresponder a qualquer arquivo de imagem na pasta de ativos de um usuário, ao mesmo tempo que garante que o ID do usuário seja um número.

// :userId(\d+) - Matches a named group 'userId', but only if it contains one or more digits.
// * - A wildcard that matches any character until the next separator (like a '.')
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" (It matches)

const result2 = assetPattern.exec("/users/abc/assets/avatar.png");
console.log(result2); // → null (It fails because 'abc' is not a digit)

Um exemplo prático: roteamento em um service worker

Os prestadores de serviços são um caso de uso perfeito para URLPattern. Você pode interceptar de forma limpa fetch solicitações e aplicar diferentes estratégias de cache sem expressões regulares confusas ou instruções condicionais retransmitidas url.includes().

// Inside your service worker file:

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)) {
    // Apply a cache-first strategy for images
    event.respondWith(cacheFirst(event.request));
  } else if (API_CALLS.test(url)) {
    // Apply a network-first strategy for API calls
    event.respondWith(networkFirst(event.request));
  }
});

Durante anos, o roteamento de URL no navegador significou expressões regulares complexas ou bibliotecas de terceiros. URLPattern muda isso ao oferecer uma solução robusta, adaptável e padronizada integrada diretamente no navegador.

Então, da próxima vez que você escrever uma expressão regular para analisar uma URL, pare e considere URLPattern. Tente refatorar um módulo de roteamento complexo em seu código ou use-o em seu próximo service worker para lidar com solicitações de busca. Você pode simplificar seu código e talvez até remover uma dependência no processo!

A API URL Pattern vem com mais recursos do que podem ser abordados aqui. Para se aprofundar e ver uma referência completa de todos os seus recursos, confira a documentação abrangente em Documentos da Web do MDN.