URLPattern exec 怎样提取命名路由参数

如果只想从浏览器原生 URL 模式中取出 /books/:id 里的 id，关键写法是读取 URLPattern.exec() 返回对象的 pathname.groups。匹配成功时这里保存命名组；匹配失败时整个返回值是 null，不能直接链式访问。

官方资料：https://developer.mozilla.org/en-US/docs/Web/API/URLPattern/exec

先记住三个边界：

• exec() 返回的是匹配结果对象或 null，不是布尔值。
• :id 这样的命名组会出现在对应 URL 部分的 groups.id 中。
• 相对 URL 需要配合 baseURL 才能解析成可匹配的绝对地址。

先看 exec 的返回结构

URLPattern 会把协议、主机、路径、查询和哈希拆成独立结果字段。本文只关心路由最常用的 pathname：它包含实际匹配到的路径文本，以及命名组和值。

const pattern = new URLPattern({ pathname: '/books/:id' });

// exec 匹配成功后返回按 URL 部分组织的对象。
const match = pattern.exec('https://example.com/books/123');

// 命名组 id 的值位于 pathname.groups.id。
console.log(match.pathname.groups.id); // '123'

// 不匹配时返回 null，调用属性前必须先判断。
const missing = pattern.exec('https://example.com/authors/123');
console.log(missing === null); // true

这里的 id 不是从完整字符串上用正则再次截取，而是由 URLPattern 按 pathname 的模式放入结果对象。这样可以把“哪一段 URL 被匹配”和“命名参数是什么”放在同一个返回结构里。

用命名组匹配绝对 URL

实际路由通常不止一个参数。可以在同一个 pathname 模式中声明多个命名组，再从 groups 对象读取它们。命名组名称应保持稳定，后续业务代码只依赖这些名称，不要依赖未命名组的数字下标。

const detailPattern = new URLPattern({
  // 两个冒号开头的片段分别命名为 category 和 id。
  pathname: '/:category/:id',
});

function readRoute(url) {
  // 匹配失败时返回 null，先保存结果再做分支处理。
  const result = detailPattern.exec(url);
  if (!result) return null;

  // 只从 pathname.groups 读取路由参数，避免把 query 当成路径参数。
  return {
    category: result.pathname.groups.category,
    id: result.pathname.groups.id,
  };
}

console.log(readRoute('https://example.com/books/123'));
// { category: 'books', id: '123' }
console.log(readRoute('https://example.com/books'));
// null

如果同一个 URL 还带有查询参数，查询部分会出现在 result.search，不会自动混入 pathname.groups。因此，路径参数、查询参数和哈希值应分别处理。

处理相对 URL 和 baseURL

页面路由代码经常拿到的是 /books/123 这样的相对路径。此时可以把基准站点作为第二个参数传给 exec(url, baseURL)。相对 URL 没有基准地址时，无法完成绝对 URL 解析，结果不会按预期匹配。

const pattern = new URLPattern('/books/:id', 'https://example.com');

// 相对路径和 baseURL 一起使用，可以得到完整匹配结果。
const result = pattern.exec('/books/123', 'https://example.com');
console.log(result?.pathname.groups.id); // '123'

// 绝对 URL 也可以直接传入，不需要额外的 baseURL。
const absolute = pattern.exec('https://example.com/books/456');
console.log(absolute?.pathname.groups.id); // '456'

要注意参数位置：字符串 URL 可以配合 baseURL；如果传入的是包含 pathname 等字段的输入对象，就不应再额外传第二个基准地址。把两种调用形式混用，容易得到 TypeError。

补上未匹配和字段边界

推荐把 exec() 当成“返回数据或空值”的函数，而不是把它当成 test() 那样的布尔判断。需要只判断是否匹配时可以使用 test()；需要读取路由参数时才使用 exec()。

function matchBook(url) {
  // 先处理 null，再访问 pathname，避免未匹配时抛出异常。
  const result = pattern.exec(url);
  if (result === null) {
    return { matched: false };
  }

  // input 是当前 URL 部分的原始匹配文本，groups 才是命名参数集合。
  return {
    matched: true,
    path: result.pathname.input,
    id: result.pathname.groups.id,
  };
}

速查可以这样记：

相关问题

URLPattern.exec 没匹配到时返回什么？返回 null。读取 pathname.groups 前应先判断结果是否为空。

命名参数应该从哪里取？例如模式是 /:id，匹配成功后从 result.pathname.groups.id 读取。

相对 URL 为什么需要 baseURL？相对路径本身缺少协议和主机，baseURL 用来提供解析所需的基准。

什么时候使用 test 而不是 exec？只需要真假判断时用 test()；还要拿路径、命名组或其他 URL 部分时用 exec()。

最终可以把它归纳成一句话：先用 URLPattern 描述 URL 部分，再用 exec() 取得结构化结果，命名路由参数从对应部分的 groups 读取，未匹配和相对地址则分别用 null 判断与 baseURL 处理。