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