SwPagination

SwPagination 是頁碼翻頁器：受控 v-model:page，頁碼切換後由父層整組替換列表資料（替換式）——與 SwGallery 的 @load-more（追加式）是兩套互斥的資料流，按場景選一種，不要混用。

響應式是純 CSS media query 雙形態：桌面完整版（頁碼視窗 + 省略號 + 跳轉 + 總數）與行動簡化版（上一頁 N / M 下一頁）同時渲染、按斷點顯隱（768px，對齊 framework）——無 JS 測寬，SSR 無 hydration 風險。

基礎分頁（total/pageSize 算頁數 + 共 N 條）

加载中...

與 SwGallery 組合（頁碼翻頁場景）

網格 + 頁碼 = loadMode="none" 的 SwGallery + 本元件；頁碼變化時整組替換 items：

SwGallery（none）+ SwPagination 組合換頁

加载中...
<script setup lang="ts">
const page = ref(1)
const { data } = await useAsyncData(
  () => `list-${page.value}`,
  () => request<MovieList>('/movie/list', { body: { page: page.value, page_size: 24 } }),
  { watch: [page] },
)
</script>

<template>
  <SwGallery :items="data?.list ?? []" load-mode="none">
    <template #default="{ item }">…</template>
  </SwGallery>
  <!-- 舊協議數字下發 string：一行 + 號歸一 -->
  <SwPagination v-model:page="page" :page-count="+(data?.last_page ?? 1)" :total="+(data?.total ?? 0)" show-total />
</template>

定制

pageCount 直傳 + 視窗 7 + 自訂箭頭 + disabled 載入鎖

加载中...

maxVisible 視窗摺疊 + showTotal

加载中...

disabled 載入鎖（防連點）

加载中...

Props

名稱類型必填預設值說明
page（v-model）number✓—當前頁碼（從 1 開始，受控）
totalnumber0條目總數，與 pageSize 算總頁數
pageSizenumber20每頁條數
pageCountnumberundefined總頁數直傳（後端直給 last_page），優先於 total 計算
maxVisiblenumber5頁碼視窗寬（建議奇數），超出折疊省略號
showJumperbooleantrue桌面端「前往 N 页」跳轉輸入（元件實際輸出為簡體中文；Enter 提交，越界 clamp）
showTotalbooleanfalse「共 N 条」文案（即「共 N 條」，元件實際輸出為簡體中文；需傳 total）
disabledbooleanfalse整體禁交互（載入中）
ariaLabelstring'分页'<nav> 的 aria-label（元件預設值為簡體中文）

Events

名稱攜帶說明
update:pagepage: number頁碼變化（同頁 / 越界 / disabled 不觸發）

Slots

名稱說明
prev / next自訂上 / 下一頁內容（預設內聯 SVG 箭頭）

樣式訂製 Token

以下 CSS 變數可在業務端覆蓋（fallback 即預設值）：

變數預設值說明
--sw-pagination-gap0.25rem頁碼之間的間距
--sw-pagination-item-size2rem單個頁碼的最小寬高（正方形熱區）
--sw-pagination-item-padding0.375rem頁碼內距（頁數變多時撐寬用）
--sw-pagination-font-size0.875rem頁碼字級

注意事項

  • 總頁數 ≤ 1 時整體隱藏（無可翻內容不渲染）。
  • 替換式 vs 追加式：要無限滾動 / 載入更多請用 SwGallery 的 loadMode，不要拿頁碼模擬。
  • ISR 頁面的翻頁用 URL 承載頁碼（RESTful 路徑如 /list/page/2 或 GET query），讓快取 key 區分頁碼——v-model:page 綁路由參數即可。

相關