URLPattern: exec() 方法

语法

exec(input)
exec(url)
exec(url, baseURL)

参数

input

一个提供各个 URL 部分的对象。对象成员可以是 protocol、username、password、hostname、port、pathname、search、hash 或 baseURL 中的任何一个。

url

一个定义绝对或相对 URL 的字符串。如果为相对 URL，则还必须提供 baseURL，并且两者结合起来必须解析为一个绝对 URL。如果输入无法解析，或提供了没有 base URL 的相对 URL，则该方法将返回 false。

baseURL 可选

一个字符串，表示在 url 是相对 URL 时要使用的基础 URL。如果未指定，则默认为 undefined。如果提供了基础 URL 但无法解析，则该方法将返回 false。

在某些情况下，未在 url/input 中指定的 URL 部分可以 从基础 URL 继承。省略的部分被视为空字符串。

返回值

一个 object，定义了匹配的元素和组，或者如果传入的输入不匹配模式，则返回 null。

该对象具有以下属性

inputs

一个数组，包含传递给 exec() 函数的输入。它将包含传入的 input 对象、一个绝对 url 字符串，或一个相对 url 和一个 baseURL。

protocol、username、password、hostname、port、pathname、search 和 hash

每个 URL 部分的命名属性。每个属性包含一个对象，该对象具有以下属性：

input

与当前 URL 部分属性对应的输入部分（该部分必须与模式匹配）。这可能是空字符串 ("")。

groups

一个对象，包含 URL 部分中每个匹配组（如果有）的属性，以及输入中对应的匹配值。组属性从 0 开始编号，用于无名匹配组（如通配符）。对于命名匹配组，属性名称就是组名。

异常

TypeError

当传递 input 对象时（它只应与 url 字符串一起传递），表示提供了 baseURL。

描述

该方法在一个 URLPattern 对象上调用，通过字符串形式的输入 URL（可选择性地带有一个基础 URL），或通过具有每个 URL 部分属性的对象来指定。

该方法返回一个包含 URL 与模式匹配结果的对象，或者如果 URL 与模式不匹配则返回 null。如果传递了相对 url 但未指定 baseURL（无法解析绝对测试 URL），它也会返回 null。请注意，当传递 input 对象时，input.baseURL 始终是可选的。

从 BaseURL 继承

比 url 中定义的最低特异性部分更具体的 URL 部分可以在某些情况下从 baseURL（或对于 input 从 input.baseURL）继承。直观地说，这意味着如果输入中指定了 pathname 部分，那么 URL 中它左边的部分（protocol、hostname 和 port）可以从基础 URL 继承，而它右边的部分则不能（search 和 hash）。username 和 password 永远不会从基础 URL 继承。

有关更多信息，请参阅 API 概述中的 从 BaseURL 继承。

示例

示例显示了如何使用 exec() 方法将 URL 与模式进行匹配。

匹配绝对 URL

首先，我们定义用于匹配 URL 的模式。此模式匹配具有 http 或 https 协议、是 .example.com 的子域且路径为 /books/ 后跟任意值的 URL。

const pattern = new URLPattern("http{s}?://*.example.com/books/:id");

接下来，我们将 URL 字符串 "https://store.example.com/books/123" 与此模式进行测试，然后分别记录每个属性的对象。请注意，input 显示了 URL 中与模式匹配的部分。在许多情况下，这是空字符串 ("")，因为输入 URL 未指定特定的 URL 部分（这与模式匹配，因为默认情况下它对未指定的 URL 部分使用通配符匹配）。

let match = pattern.exec("https://store.example.com/books/123");

console.log(match.inputs); // ['https://store.example.com/books/123']
console.log(match.protocol); // { input: "https", groups: {} }
console.log(match.username); // { input: "", groups: {"0": ""} }
console.log(match.password); // { input: "", groups: {"0": ""} }
console.log(match.hostname); // { input: "store.example.com", groups: { "0": "store" } }
console.log(match.port); // { input: "", groups: {} }
console.log(match.pathname); // { input: "/books/123", groups: { "id": "123" } }
console.log(match.search); // { input: "", groups: {"0": ""} }
console.log(match.hash); // { input: "", groups: {"0": ""} }

另请注意，pathname 输入 "/books/123" 如何与模式 /books/:id 匹配，以及 groups 是否包含一个名为 id 的命名属性，该属性包含输入中的匹配值。

匹配相对 URL

此示例使用与之前相同的模式来匹配一系列相对 URL 及其对应的基础 URL。

const pattern = new URLPattern("http{s}?://*.example.com/books/:id");

下面的代码有效地匹配了前一个示例中的相同绝对 URL，但将其拆分为一个相对 url 字符串和一个基础 URL。返回的对象仅在 inputs 属性上有所不同。

match = pattern.exec("/books/123", "http://store.example.com"); // returns object
console.log(match.inputs); // ['/books/123', 'https://store.example.com']

下面的两个示例都返回 null。第一个示例不匹配，因为相对 URL 和基础 URL 未解析为有效的绝对 URL。第二个示例不匹配，因为未提供基础 URL。

pattern.exec("/books/123", "data:text/plain,hello world!"); // returns null
pattern.exec("/books/123"); // returns null

使用 URL 对象进行匹配

此示例使用与之前相同的模式来匹配一系列定义为结构化对象 URL。

const pattern = new URLPattern("http{s}?://*.example.com/books/:id");

此代码测试与前一个示例 匹配绝对 URL 中使用的相同 URL。在这种情况下，虽然它作为结构化对象传入。由于它是相同的 URL，唯一的变化是 inputs 属性数组将包含下面传入的对象。

pattern.exec({
  protocol: "https",
  hostname: "store.example.com",
  pathname: "/books/123",
}); // returns object

以下代码也能匹配，但这次 protocol 是 http，从 baseURL 继承。返回的对象将类似，除了 protocol.input 将是 http，并且 inputs 数组将匹配传入的对象。

pattern.exec({
  pathname: "/books/123",
  baseURL: "http://store.example.com",
}); // returns object

以下代码不匹配，因为 file 协议不是模式中指定的选项之一（http 或 https）。这会返回 null。

pattern.exec({
  protocol: "file",
  hostname: "store.example.com",
  pathname: "/books/123",
}); // returns null

规范

浏览器兼容性

另见

• 在 GitHub 上提供了 URLPattern 的 polyfill