Node.js中URL模块的常用属性

URL常用的属性方法笔记

URL 类

URL 类在 JavaScript 中用于创建和解析 URL 对象。通过使用 new URL(input[, base]) 构造函数，你可以创建一个 URL 对象，该对象提供了多种属性来访问和修改 URL 的不同部分

构造函数

new URL(input[, base])

• input 要解析的绝对或相对的输入网址。如果 input 是相对的，则需要 base。如果 input 是绝对的，则忽略 base。如果 input 不是字符串，则首先是 转换为字符串。
• base 如果 input 不是绝对的，则为要解析的基本网址。如果 base 不是字符串，则首先是 转换为字符串。

属性方法

url.hash

获取和设置网址的哈希片段。

const myURL = new URL('https://example.org:8080/index.html#section1');
console.log(myURL.hash); // 输出 #section1

url.host

获取和设置网址的主机部分。

const myURL = new URL('https://example.org:8080/index.html#section1');
console.log(myURL.host); // 输出 example.org:8080

url.hostname

获取和设置网址的主机名部分。url.host 和 url.hostname 之间的主要区别是 url.hostname 不包括端口。

  const myURL = new URL('https://example.org:8080/index.html#section1');
  console.log(myURL.hostname); // 输出 example.org

url.href

获取和设置网址的完整 href 部分。

const myURL = new URL('/index.html#section1','https://example.org:8080');
console.log(myURL.href); // 输出 https://example.org:8080/index.html#section1

url.origin

获取网址的源只读序列化（协议、主机和端口）。

  const myURL = new URL('https://example.org:8080/index.html#section1');
  console.log(myURL.origin)://输出 https://example.org:8080

url.password

获取和设置网址的密码部分。

const myURL = new URL('https://user:pass@example.org:8080/index.html#section1');
console.log(myURL.password); // 输出 pass

url.pathname

获取和设置网址的路径部分(哈希之前)。

  const myURL = new URL('https://user:pass@example.org:8080/index.html#section1');
  console.log(myURL.pathname); // 输出 /index.html

url.port

获取和设置网址的端口部分。 端口值可以是数字，也可以是包含 0 到 65535（含）范围内的数字的字符串。

  const myURL = new URL('https://user:pass@example.org:8080/index.html#section1');
  console.log(myURL.port); // 输出 8080

url.protocol

获取和设置网址的协议部分。

协议	端口
http	80
https	443
ftp	21
gopher	70
file	0

  const myURL = new URL('https://user:pass@example.org:8080/index.html#section1');
  console.log(myURL.protocol); // 输出 https:

注意：WHATWG URL 标准 认为少数 URL 协议方案在解析和序列化方面是特殊的。当使用这些特殊协议之一解析网址时，url.protocol 属性可能会更改为另一种特殊协议，但不能更改为非特殊协议，反之亦然。 例如，从 http 更改为 https 有效：

const u = new URL('http://example.org');
u.protocol = 'https';
console.log(u.href);
// https://example.org/ 

但是，从 http 更改为假设的 fish 协议并不是因为新协议并不特殊。

const u = new URL('http://example.org');
u.protocol = 'fish';
console.log(u.href);
// http://example.org/ 

同样，也不允许从非特殊协议更改为特殊协议：

const u = new URL('fish://example.org');
u.protocol = 'http';
console.log(u.href);
// fish://example.org

根据 WHATWG 网址标准，特殊协议方案有 ftp、file、http、https、ws 和 wss。

url.search

获取和设置网址的序列化的search部分。

const myURL = new URL('https://example.org/abc?123');
console.log(myURL.search);
// Prints ?123

myURL.search = 'abc=xyz';
console.log(myURL.href);
// Prints https://example.org/abc?abc=xyz

url.searchParams

获取一个 URLSearchParams 对象，该对象可用于操作网址的查询部分。

const myURL = new URL('https://example.org/?abc=xyz&a=b');
const searchParams = myURL.searchParams;
console.log(searchParams.has('abc')); // 输出 true
console.log(searchParams.get('abc')); // 输出 xyz
searchParams.append('a', 'c');`
console.log(searchParams.get('a')); // 输出 b,c

url.username

获取和设置网址的用户名部分。

const myURL = new URL('https://user:pass@example.org:8080/index.html');
console.log(myURL.username); // 输出 user

url.toString()

返回一个字符串，表示与 URL 对象关联的 URL。 url 对象上的 toString() 方法返回序列化的网址。返回值等同于 url.href 和 url.toJSON() 的值

url.toJSON()

返回一个字符串，表示与 URL 对象关联的 URL。 url 对象上的 toJSON() 方法返回序列化的网址。返回值等同于 url.href 和 url.toString() 的值

URL.canParse(input[, base])

检查相对于 base 的 input 是否可以解析为 URL。

const isValid = URL.canParse('/foo', 'https://example.org/'); // true

const isNotValid = URL.canParse('/foo'); // false

URLSearchParams 类

URLSearchParams 对象表示一个 URL 的Search部分。 URLSearchParams API 提供对 URL 查询的读写访问。URLSearchParams 类也可以与以下四个构造函数之一单独使用。URLSearchParams 类也在全局对象上可用。

WHATWG URLSearchParams 接口和 querystring 模块具有相似的用途，但 querystring 模块的用途更通用，因为它允许自定义的分隔符（& 和 =）。换句话说，此 API 纯粹是为网址查询字符串而设计。

构造函数

new URLSearchParams(string)

• string String 表示查询字符串的序列化字符串

将 string 解析为查询字符串，并使用它来实例化新的 URLSearchParams 对象。前导 '?'（如果存在）将被忽略。

let params;

params = new URLSearchParams('user=abc&query=xyz');
console.log(params.get('user'));
// Prints 'abc'
console.log(params.toString());
// Prints 'user=abc&query=xyz'

params = new URLSearchParams('?user=abc&query=xyz');
console.log(params.toString());
// Prints 'user=abc&query=xyz'

new URLSearchParams(obj)

• obj Object 表示键值对集合的对象

let obj = {  
  name: "John",  
  age: 30,  // 注意：这是一个数字，但在URLSearchParams中，它将被转换为字符串  
  isStudent: false  // 注意：这是一个布尔值，同样，它将被转换为字符串  
};  
  
let searchParams = new URLSearchParams(Object.entries(obj));  
  
console.log(searchParams.toString());  
// 输出可能是：name=John&age=30&isStudent=false

new URLSearchParams(iterable)

• iterable Iterable 表示键值对集合的可迭代对象
• URLSearchParams 是一个接口，用于处理 URL 中的查询字符串部分。它接受一个可迭代的对象（如数组或 Map）作为参数，其中每个元素（或键值对）都必须是一个包含两个元素的数组（或键值对），分别对应 URL 参数的名称和值。如果试图传递一个不符合这个格式的数组或对象，将会抛出一个错误。

let params;  
  
// 使用数组  
// 注意：每个键值对都必须是形如 [key, value] 的数组  
params = new URLSearchParams([  
  ['user', 'abc'],  // 用户名为 'abc'  
  ['query', 'first'],  // 查询参数名为 'query'，值为 'first'  
  ['query', 'second'],  // 再次添加查询参数名为 'query'，值为 'second'（允许同名的键有多个值）  
]);  
console.log(params.toString());  
// 输出：'user=abc&query=first&query=second'  
  
// 使用 Map 对象  
const map = new Map();  
map.set('user', 'abc');  // 设置键 'user'，值为 'abc'  
map.set('query', 'xyz');  // 设置键 'query'，值为 'xyz'（注意这里覆盖了之前可能的 'query' 值）  
params = new URLSearchParams(map);  
console.log(params.toString());  
// 输出：'user=abc&query=xyz'  
  
// 使用生成器函数  
function* getQueryPairs() {  
  yield ['user', 'abc'];  // 生成一个键值对 ['user', 'abc']  
  yield ['query', 'first'];  // 生成一个键值对 ['query', 'first']  
  yield ['query', 'second'];  // 生成一个键值对 ['query', 'second']  
}  
params = new URLSearchParams(getQueryPairs());  
console.log(params.toString());  
// 输出：'user=abc&query=first&query=second'  
  
// 注意：每个键值对必须恰好有两个元素  
// 错误的用法：尝试添加一个包含三个元素的数组作为键值对  
new URLSearchParams([  
  ['user', 'abc', 'error'],  // 这将抛出一个错误，因为每个键值对必须有两个元素  
]);  
// 抛出 TypeError [ERR_INVALID_TUPLE]:  
//        每个查询对必须是一个可迭代的 [名称, 值] 元组

属性方法：

urlSearchParams.append(name, value)

• name String 表示参数的名称
• value String 表示参数的值

将一个键值对添加到查询字符串中。如果该键已经存在，则添加一个值。

let params = new URLSearchParams('user=abc');
params.append('user', 'xyz');
console.log(params.toString());
// 输出：'user=abc&user=xyz'

urlSearchParams.delete(name[, value])

• name String 表示参数的名称
• value String 表示参数的值

从查询字符串中删除一个键值对。如果指定了 value，则只删除具有指定名称和值的键值对。如果未指定 value，则删除具有指定名称的所有键值对。

let params = new URLSearchParams('user=abc&user=xyz');
params.delete('user', 'xyz');
console.log(params.toString());
// 输出：'user=abc'

urlSearchParams.get(name)

• name String 表示参数的名称

返回指定名称的第一个参数的值。

let params = new URLSearchParams('user=abc&user=xyz');
console.log(params.get('user'));
// 输出：'abc'

urlSearchParams.entries()

返回 一个迭代器对象 在查询中的每个名称-值对上返回 ES6 Iterator。迭代器的每一项都是 JavaScript Array。Array 的第一项是 name，Array 的第二项是 value。

let params = new URLSearchParams('user=abc&user=xyz');
for (let [name, value] of params.entries()) {
  console.log(name, value);
}
// 输出：
// user "abc"
// user "xyz"

urlSearchParams.forEach(fn[, thisArg])

URLSearchParams.prototype.forEach() 方法是 URLSearchParams 接口的一个方法，它允许你遍历 URL 参数列表并执行一个指定的函数对每个参数。

• fn 一个回调函数，它会被依次对 URL 参数列表中的每个键值对调用。这个回调函数接收三个参数：
  • 第一个参数是当前参数的值（value）。
  • 第二个参数是当前参数的名称（name）。
  • 第三个参数是调用 forEach 的 URLSearchParams 实例（可选的，通常不使用）。
• thisArg（可选） 在 fn 函数中作为 this 使用的对象。如果省略了 thisArg，或者设为 null 或 undefined，则 undefined 会被用作 this 值。

let paramsString = "user=abc&query=first&query=second";  
let urlSearchParams = new URLSearchParams(paramsString);  
  
urlSearchParams.forEach(function(value, name, urlSearchParams) {  
  console.log(name + '=' + value);  
});  
  
// 输出：  
// user=abc  
// query=first  
// query=second  
  
// 注意：如果有重复的键（如这里的 'query'），则会多次调用回调函数

urlSearchParams.get(name)

返回名称为 name 的第一个名称-值对的值。如果没有这样的对，则返回 null。

urlSearchParams.getAll(name)

返回名称为 name 的所有名称-值对的值。如果没有这样的对，则返回空数组。

urlSearchParams.has(name[, value])

检查 URLSearchParams 对象是否包含基于 name 和可选的 value 参数的键值对。

urlSearchParams.keys()

返回一个迭代器对象，该迭代器对象按顺序包含了 URLSearchParams 对象中的每个名称。

const params = new URLSearchParams('foo=bar&foo=baz');
for (const name of params.keys()) {
  console.log(name);
}
// Prints:
//   foo
//   foo

urlSearchParams.values()

返回一个迭代器对象，该迭代器对象按顺序包含了 URLSearchParams 对象中的每个值。

const params = new URLSearchParams('foo=bar&foo=baz');
for (const value of params.values()) {
  console.log(value);
}
// Prints:
//   bar
//   baz

urlSearchParamsSymbol.iterator

返回一个迭代器对象，该迭代器对象按顺序包含了 URLSearchParams 对象中的每个名称-值对。

const params = new URLSearchParams('foo=bar&foo=baz');
for (const [name, value] of params) {
  console.log(name, value);
}
// Prints:
//   foo bar
//   foo baz

urlSearchParams.set(name, value)

• name String 表示参数的名称
• value String 表示参数的值

设置一个键值对，覆盖掉已有的键相同的的键值对。

const params = new URLSearchParams();
params.append('foo', 'bar');
params.append('foo', 'baz');
params.append('abc', 'def');
console.log(params.toString());
// Prints foo=bar&foo=baz&abc=def

params.set('foo', 'def');
params.set('xyz', 'opq');
console.log(params.toString());
// Prints foo=def&abc=def&xyz=opq

urlSearchParams.size

返回 URLSearchParams 对象中的参数数量。

let params = new URLSearchParams('user=abc&user=xyz');
console.log(params.size);
// 输出：2

urlSearchParams.sort()

对查询字符串中的参数进行排序。

urlSearchParams.toString()

返回序列化为字符串的搜索参数，必要时使用百分比编码的字符。