HTML Academy · 강의

pushState 및 replaceState

전체 페이지를 다시 로드하지 않고 브라우저 URL 업데이트하기

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

History API

History API를 사용하면 전체 페이지 이동을 발생시키지 않고 주소 표시줄에 표시되는 URL을 변경할 수 있습니다. 클라이언트 측 렌더링과 결합하면 북마크할 수 있는 URL을 유지하면서도 네이티브 앱처럼 느껴지는 싱글 페이지 애플리케이션을 구현할 수 있습니다.

pushState

history.pushState(state, "", url)은 브라우저 방문 기록에 새 항목을 추가합니다. 주소 표시줄의 URL은 즉시 업데이트되며 네트워크 요청은 발생하지 않습니다. 사용자는 브라우저의 뒤로 가기 버튼으로 이전 항목으로 이동할 수 있습니다.

history.pushState({ view: "settings" }, "", "/settings");

state 인수

첫 번째 인수는 해당 기록 항목에 연결되는 직렬화 가능한 임의의 데이터입니다. 나중에 history.state를 통해 또는 popstate 이벤트에서 읽을 수 있습니다. 어떤 탭이 열려 있었는지나 스크롤 위치 같은 UI 상태를 전달하면, 뒤로 이동할 때 정확히 같은 화면을 복원할 수 있습니다.

제목 인수

두 번째 인수는 항목의 제목입니다. 실제로 모든 최신 브라우저는 이 값을 무시하므로, 제목을 바꾸려면 document.title = "..."을 직접 설정하시면 됩니다. 관례상 빈 문자열을 전달하지만, 아무런 영향을 주지 않습니다.

url 인수

세 번째 인수는 새 주소입니다. 상대 주소는 현재 페이지를 기준으로 해석되며, 새 주소는 동일 출처여야 합니다(교차 출처이면 SecurityError가 발생합니다). 브라우저는 이 주소를 가져오지 않습니다. pushState는 주소 표시줄과 히스토리만 업데이트합니다.

replaceState

history.replaceState(state, "", url)은 새 항목을 추가하는 대신 현재 히스토리 항목을 대체합니다. 새로 뒤로 이동하는 단계를 만들지 않고 주소를 업데이트하려는 경우에 사용하십시오(예: 필터 쿼리 문자열 업데이트).

// Update query string in place
const url = new URL(location);
url.searchParams.set("filter", "open");
history.replaceState(null, "", url);

pushState 사용 사례

SPA 경로 변경(전체를 다시 불러오지 않고 탐색 링크 클릭), 모달 열기(뒤로 가기 버튼으로 모달을 닫도록 하는 경우), 단계별 안내에서의 단계 전환 등에 사용합니다. 의미 있는 상태는 각각 새 히스토리 항목이어야 하므로, 뒤로 가기 버튼이 사용자가 예상하는 대로 작동합니다.

replaceState 사용 사례

히스토리에 불필요한 항목을 쌓지 않아야 하는 필터·정렬·페이지 매김 업데이트, 양식 일부 작성 후 리디렉션, 탐색 가능한 항목을 만들지 않는 추적 매개변수 업데이트 등에 사용합니다. 사용자가 뒤로 가기를 누르면 이러한 "중간" 상태를 건너뜁니다.

pushState 후 화면 업데이트

pushState는 주소만 변경하므로 코드가 DOM을 별도로 업데이트해야 합니다. 패턴은 새 콘텐츠를 표시한 다음 pushState를 호출하는 것입니다. 두 작업을 함께 수행해야 SPA 환경이 만들어집니다.

function navigate(path) {
  renderPage(path);
  history.pushState(null, "", path);
  window.scrollTo(0, 0);
}

제목 및 메타데이터 업데이트

이동 후 document.title과 소셜 공유용 제목 메타 태그를 업데이트하여 소셜 공유와 브라우저 탭 제목에 현재 화면이 반영되도록 하십시오. 이 작업을 잊으면 이후 공유에서도 원래 제목이 그대로 표시되는데, 이는 미묘하지만 흔한 SPA 버그입니다.

페이지 로드 시 초기 pushState

사용자가 이동하기 전에 pushState를 호출하면 초기 항목을 덮어씁니다. 페이지의 첫 번째 항목에 상태를 연결하려면 대신 replaceState를 사용하십시오. 히스토리 깊이는 바꾸지 않고 상태를 추가합니다.

보안 제약

pushState에 전달하는 주소는 동일 출처여야 합니다. https://evil.com으로 pushState를 시도하면 SecurityError가 발생합니다. 이를 통해 페이지가 주소 표시줄을 속여 사용자가 다른 사이트에 있다고 생각하게 만드는 일을 막습니다.

이해도 확인

히스토리의 replaceState는 pushState와 달리 무엇을 합니까?

요약

pushState는 페이지를 다시 불러오지 않고 새 히스토리 항목을 추가하며, SPA 라우팅의 기반이 됩니다. replaceState는 현재 항목을 제자리에서 업데이트하여 외관상의 주소 변경에 사용합니다. 두 메서드 모두 동일 출처 주소가 필요하며 제목 인수는 무시합니다. 항상 DOM을 별도로 업데이트하고, 이동 후에는 document.title과 메타 태그도 업데이트해야 합니다.

자주 묻는 질문

“pushState 및 replaceState” 강의는 무료인가요?

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

“pushState 및 replaceState”에서 뭘 배우나요?

전체 페이지를 다시 로드하지 않고 브라우저 URL 업데이트하기 브라우저에서 직접 실행하는 실습 코드로 HTML Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

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

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

“pushState 및 replaceState” 강의는 얼마나 걸리나요?

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

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

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

이 강의의 모든 강의

← HTML Academy(으)로 돌아가기