URL SearchParams 객체에 대해서

puka·2024년 1월 12일

URLSearchParams란?

URLSearchParams() 생성자는 새로운 URLSearchParams 객체를 생성하고 반환합니다.
이는 주소창의 경로를 다룰 수 있는 브라우저의 내장 객체입니다.

특징

웹은 주소를 기반으로 동작하기 때문에 주소를 자유자재로 다룰 수 있으면 좋습니다.
쿼리스트링을 파싱하는 것과 같은 귀찮은 작업을 간단히 처리할 수 있어 편리합니다.

new URL 와 다른점은 무엇인가?

new URL: URL 객체를 생성하며, URL 문자열을 파싱하고 그 구성요소(프로토콜, 호스트, 경로, 쿼리 파라미터 등)에 접근하거나 수정하는 작업을 수행합니다. 예를 들어, URL의 호스트나 경로를 변경하거나, 쿼리 파라미터를 추가하거나 제거하는 등의 작업을 할 수 있습니다.
여기서 mdn에 URL serachParams는 읽기 전용이라고 나와 있습니다. 이 말은 URL 인터페이스의 serachParmas 읽기 전용 속성은 URL 내의 GET 디코딩 된 쿼리 매개변수에 접근할 수 있는 URLSerachParams 객체를 반환합니다.

const url = new URL('http://example.com/path?param1=value1');
url.host = 'new-example.com';
url.pathname = '/new-path';
url.searchParams.append('param2', 'value2');
console.log(url.toString()); // http://new-example.com/new-path?param1=value1&param2=value2

console.log(url.searchParams.get("param2"))
//is the string "value2".

new URLSearchParams: URL의 쿼리 파라미터를 파싱하고 조작하는데 사용됩니다. 이는 URL의 쿼리 파라미터 부분만을 다루므로 URL 객체보다 더 특화된 기능을 가지고 있습니다. URLSearchParams는 쿼리 파라미터를 추가, 제거, 검색하는 등의 작업을 수행하며, toString 메서드를 통해 쿼리 파라미터를 문자열 형태로 출력할 수도 있습니다.

const params = new URLSearchParams('param1=value1');
params.append('param2', 'value2');
console.log(params.toString()); // param1=value1&param2=value2

그러면 URLSrachParams를 사용하지 않고 쿼리스트링으로 넣는 것은 괜찮은가?

쿼리 스트링의 정의: URL의 쿼리 스트링은 URL의 경로 바로 다음에 오는 ? 기호로 시작하는 문자열입니다. 이는 검색 파라미터라고도 불립니다.
쿼리 스트링의 용도: 쿼리 스트링은 검색, 필터링, 페이지네이션, 정렬 등 다양한 목적으로 사용됩니다. 웹 서버는 이 쿼리 스트링을 분석하여 요청한 리소스를 처리합니다.
쿼리 스트링의 구성: 쿼리 스트링은 일반적으로 "키=값"의 쌍을 & 기호로 연결하여 형성됩니다. 이러한 매개변수가 많아질수록 읽기 어렵고, 다국어나 특수 문자가 포함될 경우 인코딩도 신경 써야 합니다.
쿼리 스트링의 특징: URL 명세에 따르면, 쿼리 스트링은 동일한 키에 여러 개의 값을 할당하는 것을 허용합니다. 이 경우, 처리 시 주의가 필요합니다.
쿼리 스트링의 처리 방법: 과거에는 자바스크립트에서 쿼리 스트링을 문자열로 처리하였지만, 이제는 URL API의 URLSearchParams를 사용하여 쿼리 스트링을 더 안전하게 처리할 수 있습니다. 이를 통해 쿼리 스트링의 파싱, 조작, 인코딩 등의 작업을 간편하게 처리할 수 있습니다.

URLSearchParams 사용

1. URLSearchParams 객체의 생성

2차원 배열을 이용한 URLSearchParams 객체 생성 : URLSearchParams 생성자는 키와 값의 쌍으로 이루어진 2차원 배열을 인자로 받을 수 있습니다.

new URLSearchParams([
  ["mode", "dark"],
  ["page", 1],
  ["draft", false],
  ["sort", "email"],
  ["sort", "date"],
]);

쿼리 스트링을 문자열로 이용한 URLSearchParams 객체 생성 : 쿼리 스트링을 문자열의 형태로 넘겨 생성할 수 있습니다. 이 때, 맨 앞의 ? 기호는 생략 가능합니다.

new URLSearchParams("?mode=dark&page=1&draft=false&sort=email&sort=date");

//? 기호 생략
new URLSearchParams("mode=dark&page=1&draft=false&sort=email&sort=date");

빈 객체로 URLSearchParams 객체 생성 : 인자 없이 빈 객체를 생성한 후, 나중에 메서드를 통해 파라미터를 추가할 수 있습니다.

new URLSearchParams();

2. searchParams 프로퍼티 사용하기

URLSearchParams 객체를 생성합니다.

javascriptvar url = new URL('https://example.com?mode=dark&page=1');

이제 URLSearchParams 객체의 기능들을 한번 살펴보겠습니다.

조회하기: 특정 파라미터 하나를 조회하거나, 특정 파라미터의 여러 값을 모두 조회할 수 있습니다.

url.searchParams.get('mode'); // 'dark'
url.searchParams.getAll('page'); // ['1']

추가하기: 같은 키로 여러 값을 추가하는 것도 가능합니다.

url.searchParams.append('theme', 'light');
console.log(url.search); // ?mode=dark&page=1&theme=light
url.searchParams.append('theme', 'blue');
console.log(url.search); // ?mode=dark&page=1&theme=light&theme=blue

수정하기: set 메서드는 기본적으로 추가 역할을 하지만, 같은 이름의 기존 키가 있다면 그 값을 전부 삭제하고 새로운 내용으로 교체합니다.

url.searchParams.set('theme', 'green');
console.log(url.search); // ?mode=dark&page=1&theme=green

삭제하기: 특정 키를 삭제할 수 있습니다.

url.searchParams.delete('theme');
console.log(url.search); // ?mode=dark&page=1

MDN에 나와있는 예시

URL 객체와 URLSearchParams 객체 같이 쓰기

let url = new URL('https://example.com?foo=1&bar=2');

// url.search로 url 주소를 검색할 때
let params1 = new URLSearchParams(url.search);

// 문자열 리터럴 전달하기
let params2 = new URLSearchParams("foo=1&bar=2");
let params2a = new URLSearchParams("?foo=1&bar=2");

// 2차원 배열 전달하기
let params3 = new URLSearchParams([["foo", "1"], ["bar", "2"]]);

// 객체 전달하기
let params4 = new URLSearchParams({ "foo": "1", "bar": "2" });

여러 개의 params를 한번에 추가하기

// params로 추가할 내용을 객체로 선언 (값은 전부 문자열화)
const add_params = {
	c: 'a',
    d: new String(2),
    e: false.toString(),
};

// 기존 url 뒤에 새로운 params 추가
const new_params = new URLSearchParams([

      // url.searchParams의 entries(): 기존 url의 params를 각각 배열로 변환 	
      // Array.from 메서드로 하나의 배열로 만듦
      ...Array.from(url.searchParams.entries()), // [["a", "hello"], ["b", "world"]]

      // Object.entries(객체): 객체를 바로 2차원 배열로 반환
      ...Object.entries(add_params), // [["c", "a"], ["d", "2"], ["e", "false"]]
    
	]).toString(); // URLSearchParams 객체로 만들어진 값은 반드시 따로 문자열화 해줘야 한다.

// '&'로 연결된 새로운 params 반환
console.log(new_params); // a=hello&b=world&c=a&d=2&e=false

여러 개의 params를 한번에 추가하는 고차 함수

위의 내용을 고차 함수로 커스텀한 것입니다. (출처: MDN)

// url에 params가 없을 때를 대비하여 params에 기본값으로 빈 객체 할당
const addSearchParams = (url, params = {}) => { 
	return (
    	new URL(
        	`${url.origin}$url.pathname}?
             ${new URLSearchParams([
              ...Array.from(url.searchParams.entries()),
              ...Object.entries(params),
          	 ])
             .toString()}`
        );
    );
}