URL API

The URL API is a component of the URL standard, which defines what constitutes a valid Uniform Resource Locator and the API that accesses and manipulates URLs. The URL standard also defines concepts such as domains, hosts, and IP addresses, and also attempts to describe in a standard way the legacy application/x-www-form-urlencoded MIME type used to submit web forms' contents as a set of key/value pairs.

URL concepts and usage

The majority of the URL standard is taken up by the definition of a URL and how it is structured and parsed. Also covered are definitions of various terms related to addressing of computers on a network, and the algorithms for parsing IP addresses and DOM addresses are specified. More interesting to most developers is the API itself.

Accessing URL components

Creating an URL object for a given URL parses the URL and provides quick access to its constituent parts through its properties.

let addr = new URL("https://developer.mozilla.org/en-US/docs/Web/API/URL_API");
let host = addr.host;
let path = addr.pathname;
					

The snippet above creates a URL object for the article you're reading right now, then fetches the host and pathname properties. In this case, those strings are developer.mozilla.org and /en-US/docs/Web/API/URL_API , respectively.

Changing the URL

Most of the properties of URL are settable; you can write new values to them to alter the URL represented by the object. For example, to create a URL and set its username:

let myUsername = "someguy";
let addr = new URL("https://mysite.com/login");
addr.username = myUsername;
					

Setting the value of username not only sets that property's value, but it updates the overall URL. After executing the code snippet above, the value returned by addr.href is https://someguy@mysite.com/login . This is true for any of the writable properties.

查询

search property on a URL contains the query string portion of the URL. For example, if the URL is https://mysite.com/login?user=someguy&page=news , then the value of the search 特性为 ?user=someguy&page=news . You can also look up the values of individual parameters with the URLSearchParams object's get() method:

let addr = new URL("https://mysite.com/login?user=someguy&page=news");
try {
  loginUser(addr.searchParams.get("user"));
  gotoPage(addr.searchParams.get("page"));
} catch(err) {
  showErrorMessage(err);
}
					

For example, in the above snippet, the username and target page are taken from the query and passed to appropriate functions that are used by the site's code to log in and route the user to their desired destination within the site.

Other functions within URLSearchParams let you change the value of keys, add and delete keys and their values, and even sort the list of parameters.

URL API interfaces

The URL API is a simple one, with only a couple of interfaces to its name:

Older versions of the specification included an interface called URLUtilsReadOnly , which has since been merged into the WorkerLocation 接口。

范例

If you want to process the parameters included in a URL, you could do it manually, but it's much easier to create a URL object to do it for you. The fillTableWithParameters() function below takes as input a HTMLTableElement object representing a <table> . Rows are added to the table, one for each key found in the parameters, with the first column containing the key's name, and the second column having the value.

Note the call to URLSearchParams.sort() to sort the parameter list before generating the table.

function fillTableWithParameters(tbl) {
  let url = new URL(document.location.href);
  url.searchParams.sort();
  let keys = url.searchParams.keys();
  for (let key of keys) {
    let val = url.searchParams.get(key);
    let row = document.createElement("tr");
    let cell = document.createElement("td");
    cell.innerText = key;
    row.appendChild(cell);
    cell = document.createElement("td");
    cell.innerText = val;
    row.appendChild(cell);
    tbl.appendChild(row);
  };
}
					

A working version of this example can be found on Glitch . Just add parameters to the URL when loading the page to see them in the table. For instance, try https://url-api.glitch.me?from=mdn&excitement=high&likelihood=inconceivable .

规范

规范 状态 Comment
URL 实时标准 WHATWG specification

浏览器兼容性

更新 GitHub 上的兼容性数据
Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari Android webview Chrome for Android Firefox for Android Opera for Android Safari on iOS Samsung Internet
URL Chrome 32
32
19
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Edge 12 Firefox 19
注意事项
19
注意事项
Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683 ).
To use it from chrome code, JSM and Bootstrap scope, you have to import it with Cu.importGlobalProperties(['URL']); .
IE 10 Opera 19
19
15
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Safari 7
7
6
Prefixed
Prefixed Implemented with the vendor prefix: webkit
WebView Android 4.4
4.4
4
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Chrome Android 32
32
25
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Firefox Android 19
注意事项
19
注意事项
Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683 ).
To use it from chrome code, JSM and Bootstrap scope, you have to import it with Cu.importGlobalProperties(['URL']); .
Opera Android 19
19
14
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Safari iOS 7
7
6
Prefixed
Prefixed Implemented with the vendor prefix: webkit
Samsung Internet Android 2.0
2.0
1.5
Prefixed
Prefixed Implemented with the vendor prefix: webkit
URL() 构造函数 Chrome 19 Edge 12 Firefox 26 IE 不支持 No Opera 15 Safari 6 WebView Android ≤37 Chrome Android 25 Firefox Android 26 Opera Android 14 Safari iOS 6 Samsung Internet Android 1.5
createObjectURL
Chrome 19 Edge 12 Firefox 19
注意事项
19
注意事项
createObjectURL() is no longer available within the context of a ServiceWorker .
IE 10
注意事项
10
注意事项
If the underlying object does not have a content type set, using this URL as the src of an img tag fails intermittently with error DOM7009.
Opera 15 Safari 6 WebView Android Yes Chrome Android 25 Firefox Android 19
注意事项
19
注意事项
createObjectURL() is no longer available within the context of a ServiceWorker .
Opera Android 14 Safari iOS 6 Samsung Internet Android 1.5
hash Chrome Yes Edge 13 Firefox 22 IE 不支持 No Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android 22 Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
host Chrome Yes Edge 13 Firefox 22 IE 不支持 No Opera Yes Safari Yes WebView Android Yes Chrome Android Yes Firefox Android 22 Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
hostname Chrome Yes Edge 13 Firefox 22 IE 不支持 No Opera Yes Safari 10 WebView Android Yes Chrome Android Yes Firefox Android 22 Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
href Chrome Yes Edge 13 Firefox 22 IE 不支持 No Opera Yes Safari 10 WebView Android Yes Chrome Android Yes Firefox Android 22 Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
origin Chrome 32 Edge 12 Firefox 26
26
26 — 49
注意事项
Results for URL 使用 blob scheme incorrectly returned null .
IE 不支持 No Opera Yes Safari 10 WebView Android ≤37 Chrome Android 32 Firefox Android 26
26
26 — 49
注意事项
Results for URL 使用 blob scheme incorrectly returned null .
Opera Android Yes Safari iOS Yes Samsung Internet Android 6.0
password Chrome 32 Edge 12 Firefox 26 IE 不支持 No Opera Yes Safari 10 WebView Android ≤37 Chrome Android 32 Firefox Android 26 Opera Android Yes Safari iOS Yes Samsung Internet Android 6.0
pathname Chrome Yes Edge 13 Firefox 53
53
22 — 53
注意事项
pathname and search returned the wrong values so that for a URL of http://z.com/x?a=true&b=false , pathname would return "/x?a=true&b=false" and search would return "", rather than "/x" and "?a=true&b=false" respectively.
IE 不支持 No Opera Yes Safari 10 WebView Android Yes Chrome Android Yes Firefox Android 53
53
22 — 53
注意事项
pathname and search returned the wrong values so that for a URL of http://z.com/x?a=true&b=false , pathname would return "/x?a=true&b=false" and search would return "", rather than "/x" and "?a=true&b=false" respectively.
Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
port Chrome Yes Edge 13 Firefox 22 IE 不支持 No Opera Yes Safari 10 WebView Android Yes Chrome Android Yes Firefox Android 22 Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
protocol Chrome Yes Edge 13 Firefox 22 IE 不支持 No Opera Yes Safari 10 WebView Android Yes Chrome Android Yes Firefox Android 22 Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
revokeObjectURL
Chrome 19 Edge 12 Firefox 19
注意事项
19
注意事项
revokeObjectURL() is no longer available within the context of a ServiceWorker .
IE 10 Opera 15 Safari 6 WebView Android ≤37 Chrome Android 25 Firefox Android 19
注意事项
19
注意事项
revokeObjectURL() is no longer available within the context of a ServiceWorker .
Opera Android 14 Safari iOS 6 Samsung Internet Android 1.5
search Chrome Yes Edge 13 Firefox 53
53
22 — 53
注意事项
pathname and search returned the wrong values so that for a URL of http://z.com/x?a=true&b=false , pathname would return "/x?a=true&b=false" and search would return "", rather than "/x" and "?a=true&b=false" respectively.
IE 不支持 No Opera Yes Safari 10 WebView Android Yes Chrome Android Yes Firefox Android 53
53
22 — 53
注意事项
pathname and search returned the wrong values so that for a URL of http://z.com/x?a=true&b=false , pathname would return "/x?a=true&b=false" and search would return "", rather than "/x" and "?a=true&b=false" respectively.
Opera Android Yes Safari iOS Yes Samsung Internet Android Yes
searchParams Chrome 51 Edge 17 Firefox 29 IE 不支持 No Opera 38 Safari 10 WebView Android 51 Chrome Android 51 Firefox Android 29 Opera Android 41 Safari iOS 10 Samsung Internet Android 5.0
toJSON Chrome 71 Edge 17 Firefox 54 IE 不支持 No Opera Yes Safari Yes WebView Android 71 Chrome Android 71 Firefox Android 54 Opera Android Yes Safari iOS Yes Samsung Internet Android 10.0
toString Chrome 19 Edge 17 Firefox 54 IE 不支持 No Opera Yes Safari Yes WebView Android ≤37 Chrome Android 25 Firefox Android 54 Opera Android Yes Safari iOS Yes Samsung Internet Android 6.0
username Chrome 32 Edge 12 Firefox 26 IE 不支持 No Opera Yes Safari 10 WebView Android ≤37 Chrome Android 32 Firefox Android 26 Opera Android Yes Safari iOS Yes Samsung Internet Android 6.0

图例

完整支持
完整支持
不支持
不支持
实验。期望将来行为有所改变。
实验。期望将来行为有所改变。
见实现注意事项。
要求使用供应商前缀或不同名称。
要求使用供应商前缀或不同名称。

另请参阅