URLSearchParams()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

URLSearchParams() 생성자는 새로운 URLSearchParams 객체를 생성하고 반환합니다.

참고 : 이 기능은 Web Worker에서 사용할 수 있습니다.

구문

js
new URLSearchParams();
new URLSearchParams(init);

매개변수

init Optional

다음 중 하나입니다.

  • 문자열. application/x-www-form-urlencoded 형식으로 파싱합니다. 선행 '?' 문자는 무시합니다.
  • 이름-값 문자열 쌍을 생성하는 순회기를 가지는 객체. FormData 등의 객체가 이 범주에 속합니다. 참고로 File 값은 파일 이름이 아니라 [object File]로 직렬화됩니다. (application/x-www-form-urlencoded 양식에서의 동작과 동일)
  • 문자열 키와 문자열 값으로 구성된 레코드.

반환값

URLSearchParams 객체 인스턴스입니다.

예제

다음 예제는 URL 문자열에서 URLSearchParams 객체를 생성하는 모습입니다.

js
// url 생성자에 전달된 주소를 url.search를 통해 params라는 변수로 검색합니다.
var url = new URL("https://example.com?foo=1&bar=2");
var params = new URLSearchParams(url.search);

// 문자열 리터럴을 전달합니다.
var params2 = new URLSearchParams("foo=1&bar=2");
var params2a = new URLSearchParams("?foo=1&bar=2");

// 일련의 쌍으로 전달합니다.
var params3 = new URLSearchParams([
  ["foo", "1"],
  ["bar", "2"],
]);

// 레코드로 전달합니다.
var params4 = new URLSearchParams({ foo: "1", bar: "2" });

다음 예제는 검색 매개변수를 포함한 URL과, 검색 매개변수 객체를 사용해 새로운 URL을 만드는 모습을 보입니다.

js
const url = new URL("https://example.com/?a=hello&b=world");

console.log(url.href);
// https://example.com/?a=hello&b=world

console.log(url.origin);
// https://example.com

const add_params = {
  c: "a",
  d: new String(2),
  e: false.toString(),
};

const new_params = new URLSearchParams([
  ...Array.from(url.searchParams.entries()), // [["a","hello"],["b","world"]]
  ...Object.entries(add_params), // [["c","a"],["d","2"],["e","false"]]
]).toString();
console.log(new_params);
// a=hello&b=world&c=a&d=2&e=false

const new_url = new URL(`${url.origin}${url.pathname}?${new_params}`);

console.log(new_url.href);
// https://example.com/?a=hello&b=world&c=a&d=2&e=false

// (URL, Record<string, string>)을 받는 함수
const addSearchParams = (url, params = {}) =>
  new URL(
    `${url.origin}${url.pathname}?${new URLSearchParams([
      ...Array.from(url.searchParams.entries()),
      ...Object.entries(params),
    ]).toString()}`,
  );

명세

Specification
URL Standard
# dom-urlsearchparams-urlsearchparams

브라우저 호환성

BCD tables only load in the browser