React Academy · 강의

URL 검색 매개변수로 상태 관리하기

useSearchParams로 필터, 정렬, 페이지 매김을 URL과 동기화합니다.

URL 검색 매개변수로 상태 관리하기은(는) CoddyKit의 무료 React Academy 강의입니다. 이것은 4개 중 4번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 React Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. React Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

상태를 URL에 저장하는 이유

필터, 검색 쿼리, 정렬 순서, 페이지 매김은 사용자가 같은 화면을 북마크하고 공유하고 다시 탐색할 때 상태를 잃지 않도록 URL에 저장해야 합니다.

useSearchParams 훅

useSearchParams()는 현재 URLSearchParams 인스턴스와 설정 함수를 반환합니다. URL 쿼리 문자열을 기반으로 한다는 점에서 useState와 비슷합니다.

import { useSearchParams } from 'react-router-dom';

function ProductList() {
  const [searchParams, setSearchParams] = useSearchParams();
  const query = searchParams.get('q') || '';
  const page = Number(searchParams.get('page') || 1);
  // ...
}

단일 매개변수 읽기

searchParams.get('key')를 사용해 값을 읽습니다. 매개변수가 없으면 null을 반환하므로 대체값을 제공해야 합니다.

const sort = searchParams.get('sort') ?? 'name';
const order = searchParams.get('order') ?? 'asc';

탐색 없이 매개변수 작성하기

새 객체 또는 업데이트 함수를 전달해 setSearchParams()를 호출하고 매개변수를 변경합니다. 리액트 라우터는 전체 탐색 없이 URL을 업데이트하고 다시 렌더링합니다.

function SortButton({ field }) {
  const [searchParams, setSearchParams] = useSearchParams();
  const handleClick = () => {
    setSearchParams(prev => {
      prev.set('sort', field);
      prev.set('page', '1');
      return prev;
    });
  };
  return <button onClick={handleClick}>Sort by {field}</button>;
}

업데이트할 때 다른 매개변수 보존하기

setSearchParams의 업데이트 함수 형식을 사용하면 변경하려는 매개변수만 수정하고 나머지는 모두 그대로 유지할 수 있습니다.

setSearchParams(prev => {
  prev.set('q', newQuery);
  // 'sort' and 'page' are unchanged
  return prev;
});

검색 매개변수와 입력 동기화하기

URL 매개변수에서 입력값을 제어하고 변경될 때 URL을 업데이트하여 두 값을 동기화합니다.

function SearchBar() {
  const [params, setParams] = useSearchParams();
  const q = params.get('q') || '';
  return (
    <input
      value={q}
      onChange={e => setParams(prev => {
        prev.set('q', e.target.value);
        prev.set('page', '1');
        return prev;
      })}
    />
  );
}

검색 매개변수의 불리언 플래그

매개변수의 존재 여부 또는 '1'/'0' 문자열을 사용해 패널이 열려 있는지, 필터가 활성화되어 있는지와 같은 불리언 사용자 인터페이스 상태를 나타냅니다.

const showFilters = searchParams.has('filters');

const toggleFilters = () => {
  setSearchParams(prev => {
    if (prev.has('filters')) prev.delete('filters');
    else prev.set('filters', '1');
    return prev;
  });
};

검색 매개변수의 배열 값

URLSearchParams는 같은 키에 여러 값을 저장할 수 있습니다. getAll('key')를 사용하면 값을 배열로 읽을 수 있습니다.

// URL: /products?tag=react&tag=typescript
const tags = searchParams.getAll('tag'); // ['react', 'typescript']

// Setting multiple values:
const newParams = new URLSearchParams();
selectedTags.forEach(t => newParams.append('tag', t));
setSearchParams(newParams);

기록 대체와 추가

setSearchParams의 두 번째 인수로 { replace: true }를 전달하면 필터 변경 사항이 브라우저 기록 스택에 지나치게 많이 쌓이지 않습니다.

setSearchParams(prev => { prev.set('q', val); return prev; }, { replace: true });

매개변수에서 상태 도출하기

컴포넌트 상단에서 원시 문자열 매개변수로부터 파생 값(구문 분석한 정수나 유효성을 검사한 열거형 등)을 계산하면 이후에 안전하게 사용할 수 있습니다.

const rawPage = searchParams.get('page');
const page = Math.max(1, parseInt(rawPage || '1', 10));

const rawSort = searchParams.get('sort');
const sort = ['name', 'price', 'date'].includes(rawSort) ? rawSort : 'name';

검색 매개변수와 연결하기

Link 또는 to 객체의 search 속성을 사용하면 특정 검색 매개변수가 설정된 URL로 이동할 수 있습니다.

<Link to={{ pathname: '/products', search: '?sort=price&order=asc' }}>
  Sort by Price
</Link>

빠른 확인

?tag=react&tag=ts처럼 반복된 키의 모든 값을 읽는 URLSearchParams의 메서드는 무엇입니까?

복습

useSearchParams()는 컴포넌트 상태를 URL 쿼리 문자열과 동기화합니다. 다른 매개변수를 보존하려면 업데이트 형식을 사용하고, 기록이 불필요하게 커지는 것을 방지하려면 { replace: true }를 사용하며, 배열 값 매개변수에는 getAll()을 사용합니다.

자주 묻는 질문

“URL 검색 매개변수로 상태 관리하기” 강의는 무료인가요?

네 — “URL 검색 매개변수로 상태 관리하기” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 React Academy 강의 전체를 잠금 해제할 수 있습니다. React Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“URL 검색 매개변수로 상태 관리하기”에서 뭘 배우나요?

useSearchParams로 필터, 정렬, 페이지 매김을 URL과 동기화합니다. 브라우저에서 직접 실행하는 실습 코드로 React Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

React Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 React Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 4번째 강의입니다.

“URL 검색 매개변수로 상태 관리하기” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 React Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 React Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← React Academy(으)로 돌아가기