URL Pattern API

简介

URL Pattern API 基于正则表达式和通配符，对 URL 进行匹配和解析。

它提供一个构造函数URLPattern()，用于新建一个 URL 模式实例。

  1. const pattern = new URLPattern(input);

有了模式实例，就可以知道某个 URL 是否符合该模式。

  1. const pattern = new URLPattern({ pathname: "/books" });
  2. console.log(pattern.test("https://example.com/books")); // true

上面示例中，模式实例是 包含/books路径的 URL，实例方法test()用来检测指定网址是否符合该模式，结果为true。

URL Pattern 支持多种协议，不仅是 HTTP 协议。

  1. const pattern = new URLPattern("data\\:foo*");

上面示例中，URL Pattern 新建了一个 Data 协议的模式。

构造函数 URLPattern()

基本用法

构造函数URLPattern()用于新建一个 URL 模式实例。

  1. const pattern = new URLPattern(input);

该构造函数的参数input是一个模式字符串或者模式对象。

  1. new URLPattern("https://example.com/books/:id")
  2. // {
  3. //   hasRegExpGroups: false,
  4. //   hash: "*",
  5. //   hostname: "example.com",
  6. //   password: "*",
  7. //   pathname: "/books/:id",
  8. //   port: "",
  9. //   protocol: "https",
  10. //   search: "*",
  11. //   username: "*",
  12. //   ...
  13. // }

上面示例中，参数https://example.com/books/:id就是一个模式字符串，执行后返回一个 URLPattern 实例对象，包含模式的各个组成部分。

参数input也可以写成一个对象，用属性指定模式 URL 的每个部分。也就是说，模式对象可以有以下属性。

  • protocol
  • username
  • password
  • hostname
  • port
  • pathname
  • search
  • hash
  • baseURL

上面的示例，如果参数改成模式对象，就是下面这样。

  1. new URLPattern({
  2.   protocol: 'https',
  3.   hostname: 'example.com',
  4.   pathname: '/books/:id',
  5. })

模式字符串或者模式对象之中，没有定义的部分，默认为*，表示所有可能的字符，包括零字符的情况。

URLPattern()正常情况下将返回一个 URLPattern 实例对象，但是遇到参数无效或语法不正确，则会报错。

  1. new URLPattern(123) // 报错

上面示例中，参数123不是一个有效的 URL 模式，就报错了。

需要注意的是，如果模式字符串为相对路径，那么URLPattern()还需要第二个参数，用来指定基准 URL。

  1. new URLPattern(input, baseURL)

上面代码中，第二个参数baseURL就是基准 URL。

  1. new URLPattern('/books/:id') // 报错
  2. new URLPattern('/books/:id', 'https://example.com') // 正确

上面示例中，第一个参数/books/:id是一个相对路径，这时就需要第二个参数https://example.com，用来指定基准 URL，否则报错。

但是，如果参数为模式对象，则可以只指定 URL 模式的某个部分。

  1. new URLPattern({
  2.   pathname: '/books/:id'
  3. }) // 正确

上面示例中，参数是一个模式对象，那么参数允许只指定 URL 的部分模式。

模式对象里面，也可以指定基准 URL。

  1. let pattern4 = new URLPattern({
  2.   pathname: "/books/:id",
  3.   baseURL: "https://example.com",
  4. });

基准 URL 必须是合法的 URL，不能包含模式。

注意，如果用了模式对象，就不能使用基准 URL 作为第二个参数，这样会报错。

  1. new URLPattern({ pathname: "/foo/bar" }, "https://example.com") // 报错
  2. new URLPattern({ pathname: "/foo/bar" }, "https://example.com/baz") // 报错

上面示例中，同时使用了模式对象和第二个参数，结果就报错了。

URLpattern()还可以加入配置对象参数，用于定制匹配行为。

  1. new URLPattern(input, options)
  2. new URLPattern(input, baseURL, options)

上面代码中，参数options就是一个配置对象。

目前，这个配置对象options只有ignoreCase一个属性，如果设为true，将不区分大小写，默认值为false，表示区分大小写。

  1. new URLPattern(input, {
  2.   ignoreCase: false // 默认值，区分大小写
  3. })

请看下面的例子。

  1. const pattern = new URLPattern("https://example.com/2022/feb/*");
  3. pattern.test("https://example.com/2022/feb/xc44rsz") // true
  4. pattern.test("https://example.com/2022/Feb/xc44rsz") // false

上面示例，默认匹配时，会区分feb和Feb。

我们可以用ignoreCase将其关闭。

  1. const pattern = new URLPattern(
  2.   "https://example.com/2022/feb/*",
  3.   {  ignoreCase: true, }
  4. );
  6. pattern.test("https://example.com/2022/feb/xc44rsz") // true
  7. pattern.test("https://example.com/2022/Feb/xc44rsz") // true

模式写法

模式字符串基本上采用正则表达式的写法，但是不是所有的正则语法都支持，比如先行断言和后行断言就不支持。

（1）普通字符

如果都是普通字符，就表示原样匹配。

  1. const p = new URLPattern('https://example.com/abc');

上面代码就表示确切匹配路径https://example.com/abc。

  1. p.test('https://example.com') // false
  2. p.test('https://example.com/a') //false
  3. p.test('https://example.com/abc') // true
  4. p.test('https://example.com/abcd') //false
  5. p.test('https://example.com/abc/') //false
  6. p.test('https://example.com/abc?123') //true

上面示例中，URL 必须严格匹配路径https://example.com/abc，即使尾部多一个斜杠都不行，但是加上查询字符串是可以的。

（2）?

量词字符?表示前面的字符串，可以出现0次或1次，即该部分可选。

  1. let pattern = new URLPattern({
  2.   protocol: "http{s}?",
  3. });

上面示例中，{s}?表示字符组s可以出现0次或1次。

?不包括路径的分隔符/。

  1. const pattern = new URLPattern("/books/:id?", "https://example.com");
  3. pattern.test("https://example.com/books/123") // true
  4. pattern.test("https://example.com/books") // true
  5. pattern.test("https://example.com/books/") // false
  6. pattern.test("https://example.com/books/123/456") // false
  7. pattern.test("https://example.com/books/123/456/789") // false
  8. pattern.test("https://example.com/books/123/456/") // false

上面示例中，?不能匹配网址结尾的斜杠。

如果一定要匹配，可以把结尾的斜杠放在{}里面。

  1. const pattern = new URLPattern({ pathname: "/product{/}?" });
  3. pattern.test({ pathname: "/product" }) // true
  4. pattern.test({ pathname: "/product/" }) // true

上面示例中，不管网址有没有结尾的斜杠，{/}?都会成功匹配。

（3）+

量词字符+表示前面的字符串出现1次或多次。

  1. const pattern = new URLPattern({
  2.   pathname: "/books/(\\d+)",
  3. })

上面示例中，\\d+表示1个或多个数字，其中的\d是一个内置的字符类，表示0-9的数字，因为放在双引号里面，所以反斜杠前面还要再加一个反斜杠进行转义。

+可以包括/分隔的路径的多个部分，但不包括路径结尾的斜杠。

  1. const pattern = new URLPattern("/books/:id+", "https://example.com");
  3. pattern.test("https://example.com/books/123") // true
  4. pattern.test("https://example.com/books") // false
  5. pattern.test("https://example.com/books/") // false
  6. pattern.test("https://example.com/books/123/456") // true
  7. pattern.test("https://example.com/books/123/456/789") // true
  8. pattern.test("https://example.com/books/123/456/") // false

（4）*

量词字符*表示出现零次或多次。

  1. const pattern = new URLPattern('https://example.com/{abc}*');
  3. pattern.test('https://example.com') // true
  4. pattern.test('https://example.com/') // true
  5. pattern.test('https://example.com/abc') // true
  6. pattern.test('https://example.com/abc/') // false
  7. pattern.test('https://example.com/ab') // false
  8. pattern.test('https://example.com/abcabc') // true
  9. pattern.test('https://example.com/abc/abc/abc') // false

上面示例中，{abc}*表示abc出现零次或多次，也不包括路径分隔符/。

如果*前面没有任何字符，就表示所有字符，包括零字符的情况，也包括分隔符/。

  1. let pattern = new URLPattern({
  2.   search: "*",
  3.   hash: "*",
  4. });

上面示例中，*表示匹配所有字符，包括零字符。

下面是另一个例子。

  1. const pattern = new URLPattern("/*.png", "https://example.com");
  3. pattern.test("https://example.com/image.png") // true
  4. pattern.test("https://example.com/image.png/123") // false
  5. pattern.test("https://example.com/folder/image.png") // true
  6. pattern.test("https://example.com/.png") // true

*匹配的部分可以从对应部分的数字属性上获取。

  1. const pattern = new URLPattern({
  2.   hostname: "example.com",
  3.   pathname: "/foo/*"
  4. });
  6. const result = pattern.exec("/foo/bar", "https://example.com/baz");
  8. result.pathname.input // '/foo/bar'
  9. result.pathname.groups[0] // 'bar'

上面示例中，*的匹配结果可以从pathname.groups[0]获取。

  1. const pattern = new URLPattern({ hostname: "*.example.com" });
  2. const result = pattern.exec({ hostname: "cdn.example.com" });
  4. result.hostname.groups[0] // 'cdn'
  5. result.hostname.input // 'cdn.example.com'

上面示例中，*的匹配结果可以从hostname.groups[0]获取。

（5）{}

特殊字符{}用来定义量词?、+、+的生效范围。

如果{}后面没有量词，那就跟没有使用的效果一样。

  1. const pattern = new URLPattern('https://example.com/{abc}');
  3. pattern.test('https://example.com/') // false
  4. pattern.test('https://example.com/abc') // true

（6）()

特殊字符()用来定义一个组匹配，匹配结果可以按照出现顺序的编号，从pathname.groups对象上获取。

  1. const pattern = new URLPattern("/books/(\\d+)", "https://example.com");
  2. pattern.exec("https://example.com/books/123").pathname.groups
  3. // { '0': '123' }

上面示例中，(\\d+)是一个组匹配，因为它是第一个组匹配，所以匹配结果放在pathname.groups的属性0。

（7）|

特殊字符|表示左右两侧的字符，都可以出现，即表示逻辑OR。

  1. let pattern = new URLPattern({
  2.   port: "(80|443)",
  3. });

上面示例中，(80|443)表示80或者443都可以。

（8）:

特殊字符:用来定义一个具名组匹配，后面跟着变量名。

  1. let pattern = new URLPattern({
  2.   pathname: "/:path",
  3. });

上面示例中，/:path表示斜杠后面的部分，都被捕捉放入变量path，可以从匹配结果的pathname.groups上的对应属性获取。

  1. const pattern = new URLPattern({ pathname: "/books/:id" });
  3. pattern.exec("https://example.com/books/123").pathname.groups
  4. // { id: '123' }

上面示例中，pathname.groups返回一个对象，该对象的属性就是所有捕捉成功的组变量，上例是id。

下面是另一个例子。

  1. const pattern = new URLPattern({ pathname: "/:product/:user/:action" });
  2. const result = pattern.exec({ pathname: "/store/wanderview/view" });
  4. result.pathname.groups.product // 'store'
  5. result.pathname.groups.user // 'wanderview'
  6. result.pathname.groups.action // 'view'
  7. result.pathname.input // '/store/wanderview/view'

上面示例中，:product、:user、:action的匹配结果，都可以从pathname.groups的对应属性上获取。

组匹配可以放在模式的前面。

  1. const pattern = new URLPattern(
  2.   "/books/:id(\\d+)",
  3.   "https://example.com"
  4. );

上面示例中，组匹配:id后面跟着模型定义\\d+，模式需要放在括号里面。

（9）特殊字符转义

如果要将特殊字符当作普通字符使用，必须在其前面加入双重反斜杠进行转义。

  1. let pattern1 = new URLPattern({
  2.   pathname: "/a:b",
  3. });
  5. let pattern2 = new URLPattern({
  6.   pathname: "/a\\:b",
  7. });

上面示例中，a:b表示路径以字符a开头，后面的部分都放入变量b。而a\\:b表示路径本身就是a:b就是。

实例属性

URLPattern 实例的属性对应URLPattern()模式对象参数的各个部分。

  1. const pattern = new URLPattern({
  2.   hostname: "{*.}?example.com",
  3. });
  5. pattern.hostname // '{*.}?example.com'
  6. pattern.protocol // '*'
  7. pattern.username // '*'
  8. pattern.password // '*'
  9. pattern.port // ""
  10. pattern.pathname // '*'
  11. pattern.search // '*'
  12. pattern.hash // '*'

上面示例中，pattern是一个实例对象，它的属性与URLPattern()的参数对象的属性一致。

注意，search不包括开头的?，hash不包括开头的#，但是pathname包括开头的/。

下面是另一个例子。

  1. const pattern = new URLPattern("https://cdn-*.example.com/*.jpg");
  3. pattern.protocol // 'https'
  4. pattern.hostname // 'cdn-*.example.com'
  5. pattern.pathname // '/*.jpg'
  6. pattern.username // ''
  7. pattern.password // ''
  8. pattern.search // ''
  9. pattern.hash // ''

实例方法

exec()

实例的exec()方法，把模式用于解析参数网址，返回匹配结果。

exec()方法的参数与new URLPattern()是一致的。它可以是一个 URL 字符串。

  1. pattern.exec("https://store.example.com/books/123");

如果第一个参数是相对 URL，那么需要基准 URL，作为第二个参数。

  1. pattern.exec("/foo/bar", "https://example.com/baz");

exec()方法的参数，也可以是一个对象。

  1. pattern.exec({
  2.   protocol: "https",
  3.   hostname: "store.example.com",
  4.   pathname: "/books/123",
  5. });

如果匹配成功，它返回一个包括匹配结果的对象。如果匹配失败，返回null。

  1. const pattern = new URLPattern("http{s}?://*.example.com/books/:id");
  2. pattern.exec("https://example.com/books/123") // null

上面示例中，匹配失败返回null。

匹配成功返回的对象，有一个inputs属性，包含传入pattern.exec()的参数数组。其他属性的值也是一个对象，该对象的input属性对应传入值，groups属性包含各个组匹配。

  1. const pattern = new URLPattern("http{s}?://*.example.com/books/:id");
  2. let match = pattern.exec("https://store.example.com/books/123");
  4. match.inputs // ['https://store.example.com/books/123']
  5. match.protocol // { input: "https", groups: {} }
  6. match.username // { input: "", groups: {} }
  7. match.password // { input: "", groups: {} }
  8. match.hostname // { input: "store.example.com", groups: { "0": "store" } }
  9. match.port // { input: "", groups: {} }
  10. match.pathname // { input: "/books/123", groups: { "id": "123" } }
  11. match.search // { input: "", groups: {} }
  12. match.hash // { input: "", groups: {} }

test()

实例的test()方法，用来检测参数网址是否符合当前模式。

它的参数跟URLPattern()是一样的，可以是模式字符串，也可以是模式对象。

  1. const pattern = new URLPattern({
  2.   hostname: "example.com",
  3.   pathname: "/foo/*"
  4.  });
  6. pattern.test({
  7.   pathname: "/foo/bar",
  8.   baseURL: "https://example.com/baz",
  9. }) // true
  11. pattern.test("/foo/bar", "https://example.com/baz") // true

正常情况下，它返回一个布尔值。但是，如果语法不合法，它也会抛错。

  1. pattern.test({ pathname: "/foo/bar" }, "https://example.com/baz") // 报错