浅析 URLSearchParams 使用

2024-11-22 08:13:28

一. 目的

URLSearchParams 接口定义了一些实用的方法来处理 URL 的查询字符串。

二. 基本定义

URLSearchParams 是一个构造函数，接受一个参数，通过 new URLSearchParams(options) 会创建并返回一个新的 URLSearchParams 实例对象。

当然，我们可以直接从 URL 实例对象上直接获取 URLSearchParams 实例对象。

const url = new URL(window.location.href);
const searchParams = url.searchParams;

1. 语法

new URLSearchParams();
new URLSearchParams(options);

2. 参数

options 可选，options 可以是以下几种情况：

（1）可以为空，不传入任何值，相当于一个空字符串

const searchParams = new URLSearchParams();
searchParams.toString(); // ""

（2）一个字符串，会按 application/x-www-form-urlencoded 的格式进行解析。开头的 “?” 字符会被忽略。

const searchParams = new URLSearchParams("?name=123&age=18");
searchParams.toString(); // "name=123&age=18"

（3）一系列基于字面量的字符串键值对，或者任何对象（例如 FormData 对象），能提供一系列字符串对的迭代器对象。需要注意，File 将被序列化为 [object File]，而不是它们的文件名（就像 application/x-www-form-urlencoded 格式中的那样）。例如：

传入一系列键值对：

const searchParams = new URLSearchParams([
  ["foo", "1"],
  ["bar", "2"],
]);
searchParams.get("foo"); // "1"
searchParams.get("bar"); // "2"

传入 FormData 实例对象：

const formData = new FormData();
formData.append("foo", "1");
formData.append("bar", "2");
const searchParams = new URLSearchParams(formData);
searchParams.toString(); // "foo=1&bar=2"

传入能提供一系列字符串对的迭代器对象：

const obj = {
  [Symbol.iterator]: function* () {
    yield ["foo", "1"];
    yield ["bar", "2"];
  }
}
const searchParams = new URLSearchParams(obj);
searchParams.toString(); // "foo=1&bar=2"

（4）一个由字符串键和字符串值组成的键值对对象。

// 传入键值对对象
const searchParams = new URLSearchParams({
  foo: "1",
  bar: "2"
});
searchParams.get("foo"); // "1"
searchParams.get("bar"); // "2"

需要注意：不支持嵌套，会调用其 toString 方法，返回结果

const searchParams = new URLSearchParams({
  foo: {
      name: "liming"
  },
  bar: "2"
});
searchParams.get("foo"); // "[object Object]"

const obj = {
  toString: () => {
    return "我来了"
  }
}
const searchParams = new URLSearchParams({
  foo: obj,
  bar: "2"
});
searchParams.get("foo"); // "我来了"

三. 实例方法和属性

我们打印一个 URLSearchParams 实例，可以看到继承了很多实例方法和实例属性：

console.log(new URLSearchParams())

URLSearchParams {}
  size: 0
  __proto__: URLSearchParams
    append: ƒ append()
    delete: ƒ delete()
    entries: ƒ entries()
    forEach: ƒ forEach()
    get: ƒ ()
    getAll: ƒ getAll()
    has: ƒ has()
    keys: ƒ keys()
    set: ƒ ()
    sort: ƒ sort()
    toString: ƒ toString()
    values: ƒ values()
    constructor: ƒ URLSearchParams()
    Symbol(Symbol.iterator): ƒ entries()
    Symbol(Symbol.toStringTag): "URLSearchParams"
    __proto__: Object

接下来，一个一个说：

1. size

一个数字，表示 URLSearchParams 对象的查询参数条目的总数。

const searchParams = new URLSearchParams("c=4&a=2&b=3&a=1");
searchParams.size; // 4

请注意，参数 a 出现了两次，但是 size 返回的数值是 4 不是 3。要获取唯一键的数量，你可以使用 Set，例如：

[...new Set(searchParams.keys())].length; // 3

2. append

URLSearchParams 接口的 append() 方法将指定的键/值对附加为新的查询参数。语法如下：

append(name, value)

name: 要附加的参数的键名
value: 要附加的参数的值

const searchParams = new URLSearchParams(?foo=1&bar=2");

// 添加第二个 foo 查询参数。
searchParams.append("foo", 4);
searchParams.toString(); // "foo=1&bar=2&foo=4"

3. delete

delete(name, value) 方法从所有查询参数的列表中删除指定的参数及其关联值。

一个参数名称和可选值用于匹配参数。如果指定了一个参数名称，则会删除所有与该名称匹配的查询参数及其关联值。如果同时指定了参数名称和值，则会删除所有与参数名称和数值匹配的查询参数。

语法:

delete(name)
delete(name, value)

name: 需要删除的键值名称
value: 可选，参数必须匹配的值以及要删除的给定名称

例如：

删除具有特定名称的所有查询参数：

const searchParams = new URLSearchParams("foo=1&bar=2&foo=3");
searchParams.toString(); // "foo=1&bar=2&foo=3"
searchParams.delete("foo");
searchParams.toString(); // "bar=2"

除具有特定的名称和值的查询参数:

const searchParams = new URLSearchParams("foo=1&bar=2&foo=3");
searchParams.toString(); // "foo=1&bar=2&foo=3"
searchParams.delete("foo", "1");
searchParams.toString(); // "bar=2&foo=3"

4. entries

entries() 方法返回一个用于遍历该对象中包含的所有键/值对的迭代器。迭代器按照查询字符串中出现的顺序返回键/值对，每一组键和值都是字符串对象。

例如：

const searchParams = new URLSearchParams("foo=1&bar=2&foo=3");

// 显示键/值对
for (const [key, value] of searchParams.entries()) {
  console.log(`${key}, ${value}`);
}

结果：

foo, 1
bar, 2
foo, 3

5. forEach

forEach() 方法允许通过回调函数来遍历实例对象上的键值对。

语法

forEach(callback)
forEach(callback, thisArg)

参数

callback：在每个元素上执行的函数，会传入以下参数：

value：URLSearchParams 对象中正在处理的条目的值。

key：URLSearchParams 对象中正在处理的条目的键。

searchParams：当前调用 forEach() 方法的 URLSearchParams 对象。

thisArg 可选，执行 callback 时 this 的值

例如：

const searchParams = new URLSearchParams(("foo=1&bar=2&foo=3");

// 输出值
searchParams.forEach((value, key) => {
  console.log(`${key}, ${value}`);
});

结果：

foo, 1
bar, 2
foo, 3

6. get

get(name) 方法返回第一个与查询参数对应的值，如果找不到，返回 null。

const searchParams= new URLSearchParams("foo=1&bar=2&foo=3");
searchParams.get("foo"); // "1"
searchParams.get("name"); // null

7. getAll

getAll(name) 方法指定查询参数对应的所有值，返回值是一个数组，如果没有，则返回 null。

const searchParams= new URLSearchParams("foo=1&bar=2&foo=3");
searchParams.getAll("foo"); // ["1", "3"]
searchParams.get("name"); // null

8. hash

has() 方法返回一个布尔值，表示指定的键名对应的值是否存在于查询参数中。

一个参数名称和可选值用于匹配参数。如果只指定了一个参数名称，那么如果查询字符串中的任何参数与名称匹配，则该方法将返回 true，否则返回 false。如果同时指定了参数名称和值，则如果参数与名称和值都匹配，该方法才返回 true。

语法：

has(name)
has(name, value)

检查查询字符串是否有具有特定名称的参数

const searchParams = new URLSearchParams("foo=1&bar=2&foo=3");

// 如果参数在查询字符串中，则 has() 返回 true
searchParams.has("foo"); // true
searchParams.has("bar"); // true
searchParams.has("name"); // false

检查查询字符串是否有具有特定名称的参数和值

const searchParams = new URLSearchParams("foo=1&bar=2&foo=3");

// 如果具有指定名称和值的参数在查询字符串中，则 has() 返回 true
searchParams.has("foo", "1"); // true
searchParams.has("foo", "3"); // true
searchParams.has("foo", "5"); // false

9. keys

keys() 方法返回一个迭代器 iterator，此对象包含了键/值对的所有键。

例如：

const searchParams = new URLSearchParams("foo=1&bar=2&foo=3");

// 输出键值对
for (const key of searchParams.keys()) {
  console.log(key);
}

结果：

foo
bar
foo

10. set

set(name, value) 方法用于设置和查询参数相关联的值。如果设置前已经存在多个匹配的值，此方法会删除重复的查询参数；如果查询参数不存在，则创建它。

const searchParams = new URLSearchParams("foo=1&bar=2&foo=3");

searchParams.set("baz", 3);
searchParams.toString(); // "foo=1&bar=2&foo=3&baz=3"

// 如果已存在多个值，会先删除所有，在设置最新值
searchParams.set("foo", "5"); // "foo=5&bar=2&baz=3"
searchParams.toString(); // "foo=5&bar=2&baz=3"

11. sort

sort() 方法对包含在此对象中的所有键/值对进行排序，并返回 undefined。排序顺序是根据键的 Unicode 码位。

const searchParams = new URLSearchParams("foo=1&bar=2&foo=3");

// 对键/值对进行排序
searchParams.sort();
searchParams.toString(); // "bar=2&foo=1&foo=3"

12. toString

toString() 方法返回一个不带问号的字符串，如果未设置查询参数，则返回空字符串。

const params = new URLSearchParams("?foo=1&bar=2&foo=3");
// ?会去掉
params.toString(); // “foo=1&bar=2&foo=3”

13. values

values() 方法返回一个迭代器 iterator，此对象包含了键/值对的所有值。

例如：

var searchParams= new URLSearchParams("foo=1&bar=2&foo=3")
var oValues = params.values()
for(var value of searchParams.values()) {
  console.log(value);
}

结果：

1
2
3