3.4URLSearchParams

URL의 쿼리 문자열을 자바스크립트로 다룰 수 있는 Web API

TL;DR

추억의 쪽지 시험

개요

URLSearchParams란, 브라우저(및 일부 Node.js 환경)에서 제공하는 내장 Web API로, URL의 쿼리 문자열(Query String)을 쉽게 읽고 / 추가하고 / 수정하고 / 삭제할 수 있도록 도와준다. 즉, 브라우저가 자바스크립트에게 쿼리 문자열을 다룰 수 있게 제공하는 API다.

사용법

1. 생성

URLSearchParams 객체의 인스턴스를 생성하는 방식을 쓸 수 있다.

javascript
const params = new URLSearchParams('category=books&sort=asc');

또는, URL 객체의 searchParams에 접근하는 방식도 가능하다.

javascript
const url = new URL('https://sungyup.com/study?category=book&sort=asc');
const params = url.searchParams;

이는 URL이 전체 URL을 다루는 클래스이고, URLSearchParams는 쿼리 문자열만 다루는 별도 클래스로, URL과는 포함 관계에 있기 때문이다.

typescript
interface URL {
  href: string;
  origin: string;
  // ...
  readonly searchParams: URLSearchParams;
}

2. 주요 메소드

메소드	설명	예시
`.get(name)`	특정 파라미터 값을 반환	`params.get('category')` // books
`.getAll(name)`	같은 키가 여러번 등장할때 모두 반환	`params.getAll('tag')`
`.set(name, value)`	값 설정. 기존 키를 덮어씀	`params.set('page', '4')`
`.append(name, value)`	값을 추가. 기존 키를 덮어쓰지 않음.	`params.append('tag', 'browser')`
`.delete(name)`	특정 파라미터 제거	`params.delete('sort')`
`.has(name)`	파라미터 존재 여부 확인	`params.has('page')`
`.toString()`	문자열로 변환	쿼리 문자열 반환

3. 특징: iterable 객체

URLSearchParams는 iterable 객체로,for...of 반복문을 적용할 수 있다.

javascript
for (const [key, value] of params){
  console.log(key, value);
}

// category books
// sort asc
// page 3

4. 활용

검색 페이지 상태 관리에 유용하다. 사용자가 필터를 바꾸면 URL 쿼리를 업데이트하는 식으로 관리하면, 새로고침 시에도 같은 상태를 유지할 수 있다. 이 링크는 공유하기 기능에도 유용하다.

또, API 호출 시 쿼리 파라미터를 직렬화하는데도 자주 쓰인다. 아래와 같은 식이다.

javascript
const params = new URLSearchParams({ category: 'books', page: 2 });
fetch(`/api/items?${params}`);

5. 주의점

5-1. URL encoding

한글이나 공백은 %EC%84.... 식으로 변환된다. 이는 URL이 ASCII 문자로만 구성될 수 있기 때문이고, 한글이나 공백, 특수문자와 같은 비 ASCII 문자를 직접 넣을 수 없기 때문에 퍼센트 인코딩(percent-encoding)이라는 규칙으로 변환을 해야하기 때문이다. 예를 들어 공백은 %20이고 !는 %21인 식이다.

문자열을 이렇게 URL encode 하고 싶으면 encodeURIComponent()라는 자바스크립트 내장 함수를 활용할 수 있다.(디코딩은 decodeURIComponent) 다만 브라우저나 fetch()는 내부적으로 URLSearchParams.toString()시 자동 인코딩을 수행하므로 대부분의 경우 직접 URL encode할 필요는 없다. 커스텀 문자열을 직접 조합하는 등 특수 경우에만 쓸 일이 있을 것이다.

참고로, URL(Uniform Resource Locator)가 아니라 URI(Uniform Resource Identifier)인 것은 자바스크립트 초창기(1990년대 후반 ~ 2000년대 초반)에는 URI 사양이 웹 표준의 기본이어서 더 넓고 일반적인 개념으로 쓰였기 때문이다. URI는 리소스를 식별하는 모든 문자열로, https://sungyup.com과 같은 URL(리소스의 위치를 구체적으로 표현하는 URI의 한 종류)을 포함해 tel:+821025666483이나 mailto:chickenjuicyham@gmail.com과 같은 문자열도 포함하는 개념이다.

5-2. 해시(#)는 미포함

해시(#)는 Fragment Identifier로, 문서 내부의 특정 위치를 가리킨다. URL에서 # 뒤에 오는 내용은 서버로 전송되지 않고, 문서 내 특정 지점이나 상태를 식별하는데 쓰인다. 이는 해시 fragment가 HTTP 요청의 일부가 아니고, 브라우저가 클라이언트 단에서만 해석하기 때문이다.

이 해시는 HTML 문서의 id 속성과 직접적으로 연결되어 있다. 아래 링크를 들어가면 이 항목으로 자동 스크롤 되는데, 사실 이 블로그 전체에 적용된건 아니고 <div id="section5-2"/>를 이 예시를 위해 살짝 끼워둔 것이다.

bash
https://sungyup.com/study/web_miscellaneous/URLSearchParams#section5-2

PreviousStorage

WebIT

NextGetting Started with Web Audio API

Web