Pagination 공통 컴포넌트

[Seon-K]

1. ✨ 설계 배경 및 목적

Pagination 컴포넌트는 사용자에게 페이지 탐색의 일관된 UI/UX 제공를 제공하기 위해 설계되었습니다.

Pagination 컴포넌트는 단일 컴포넌트로 구성되어있으며, 해당 컴포넌트를 단일 컴포넌트로 구성한 이유는 아래와 같습니다,

단일 컴포넌트로 구성한 이유

1. 구조가 단순하고 역할이 명확합니다.
   • 페이지 번호, 생략 기호(...), 이전/다음 버튼 등의 UI 요소들이 고정된 위치와 정해진 로직에 따라 배치되므로 별도로 쪼갤 필요가 없다고 생각했습니다.
2. 합성 컴포넌트로 나눌만큼 구조가 복잡하지 않다고 판단했습니다.
   • <Pagination.Page>, <Pagination.Prev> 같은 구성이 필요한 상황이 아니며, 대부분의 사용 사례에서 단일 컴포넌트로 충분히 커버 가능하다고 생각했습니다.

2. 🧱 구성요소 및 구조

디렉터리 구조

shared/components/ui/pagination/
├── Pagination.tsx //  Pagination 컴포넌트

3. ⚙️ 동작 흐름 요약

사용자 관점

1. 페이지 번호 또는 Prev/Next 버튼을 클릭
2. 현재 페이지는 시각적으로 강조되고, 첫 페이지와 마지막 페이지 수는 고정으로 노출됨
3. 페이지 숫자 클릭으로 해당 페이지 이동 가능

개발자 관점

1. currentPage, totalPages, onPageChange props로 제어
2. 내부에서 generatePages() 함수로 페이지 버튼 리스트 생성
   • "..." 기호는 생략 영역 표현을 위한 값
   • currentPage에 따라 세 가지 위치(시작, 중간, 끝)로 나눠 처리
3. prev, next 버튼으로 페이지 이동 처리

4. 🔮 설계 의도 및 고려사항

• 복잡한 합성 방식보다 단일 컴포넌트로 제공해 간단하게 사용 가능하도록 함
• 페이지 수가 많은 경우에도 UX를 해치지 않도록 "..." 생략 기호 사용
• 전체 페이지가 5개 이하이면 생략 없이 모두 보여줌
• currentPage는 외부 상태로 제어하며, 내부에 별도 state는 없음

5. 🪄 세부 설명: 주요 훅 / 컴포넌트 / 유틸

Props 설명

이름	타입	필수 여부	설명
currentPage	number	✅	현재 활성화된 페이지 번호입니다. 외부 상태로 관리되어야 합니다.
totalPages	number	✅	전체 페이지 수입니다. 1 이상의 값이어야 하며, 버튼 생성의 기준이 됩니다.
onPageChange	(page: number) => void	✅	페이지 번호 클릭 또는 Prev/Next 클릭 시 호출되는 콜백입니다.
pageRange	number	❌	한 번에 보여줄 페이지 버튼 수입니다. 기본값은 5입니다.

💡 페이지 수가 pageRange 이하일 경우에는 생략 없이 모든 페이지를 보여줍니다.
💡 페이지 수가 많아질 경우 "..." 기호로 중간 페이지를 생략하여 UI를 간결하게 유지합니다.

---

내부 유틸: generatePages()

• 현재 페이지 위치에 따라 보여줄 페이지 버튼을 동적으로 구성하는 함수입니다.
• 예시 출력:
  • currentPage = 2 → [1, 2, 3, 4, 5, '...', 20]
  • currentPage = 10 → [1, '...', 9, 10, 11, '...', 20]
  • currentPage = 19 → [1, '...', 16, 17, 18, 19, 20]

6. 🧩 사용 예시 및 패턴

<Pagination
  currentPage={1}
  totalPages={20}
  onPageChange={(page) => setCurrentPage(page)}
/>

7. ⚠️ 사용 시 주의사항

• onPageChange는 외부 상태(setState 등)로 연결되어 있어야 정상 동작합니다.
• currentPage도 외부 상태와 연결되어 있으며 내부에서 관리하는 것이 아닙니다.

8. 📎 참고 파일 및 링크

KRDS
Material UI
/test/pagination 경로에서 실제 동작 테스트가 가능합니다.