SwPagination

SwPagination 是页码翻页器：受控 v-model:page，页码切换后由父层整组替换列表数据（替换式）——与 SwGallery 的 @load-more（追加式）是两套互斥的数据流，按场景选一种，不要混用。

响应式是纯 CSS media query 双形态：桌面完整版（页码窗口 + 省略号 + 跳转 + 总数）与移动简化版（上一页 N / M 下一页）同时渲染、按断点显隐（768px，对齐 framework）——无 JS 测宽，SSR 无 hydration 风险。

加载中...

与 SwGallery 组合（页码翻页场景）

网格 + 页码 = loadMode="none" 的 SwGallery + 本组件；页码变化时整组替换 items：

加载中...

<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>

定制

加载中...

Props

名称	类型	必填	默认值	说明
`page`（v-model）	`number`	✓	—	当前页码（从 1 开始，受控）
`total`	`number`		`0`	条目总数，与 pageSize 算总页数
`pageSize`	`number`		`20`	每页条数
`pageCount`	`number`		`undefined`	总页数直传（后端直给 `last_page`），优先于 total 计算
`maxVisible`	`number`		`5`	页码窗口宽（建议奇数），超出折叠省略号
`showJumper`	`boolean`		`true`	桌面端「前往 N 页」跳转输入（回车提交，越界 clamp）
`showTotal`	`boolean`		`false`	「共 N 条」文案（需传 total）
`disabled`	`boolean`		`false`	整体禁交互（加载中）
`ariaLabel`	`string`		`'分页'`	`<nav>` 的 aria-label

Events

名称	携带	说明
`update:page`	`page: number`	页码变化（同页 / 越界 / disabled 不触发）

Slots

名称	说明
`prev` / `next`	自定义上 / 下一页内容（默认内联 SVG 箭头）

样式定制 Token

以下 CSS 变量可在业务侧覆盖（fallback 即默认值）：

变量	默认值	说明
`--sw-pagination-gap`	`0.25rem`	页码之间的间距
`--sw-pagination-item-size`	`2rem`	单个页码的最小宽高（正方形热区）
`--sw-pagination-item-padding`	`0.375rem`	页码内边距（页数变多时撑宽用）
`--sw-pagination-font-size`	`0.875rem`	页码字号

注意事项

总页数 ≤ 1 时整体隐藏（无可翻内容不渲染）。
替换式 vs 追加式：要无限滚动 / 加载更多请用 SwGallery 的 loadMode，不要拿页码模拟。
ISR 页面的翻页用 URL 承载页码（RESTful 路径如 /list/page/2 或 GET query），让缓存 key 区分页码——v-model:page 绑路由参数即可。