分页 pagination

导航组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

count 给的是总条数不是总页数；页码序列由 root 的插槽交出来，作者照着渲染 item 与省略号

…第 1 / 20 页

<script setup lang="ts">
import {
  XhPaginationEllipsis,
  XhPaginationItem,
  XhPaginationNextTrigger,
  XhPaginationPrevTrigger,
  XhPaginationRoot,
} from "@xihan-ui/vue";
</script>

<template>
  <XhPaginationRoot
    v-slot="{ pages, page, totalPages }"
    :count="196"
    :page-size="10"
    style="inline-size: 100%"
  >
    <XhPaginationPrevTrigger>上一页</XhPaginationPrevTrigger>
    <template v-for="(p, i) in pages" :key="`${p}-${i}`">
      <XhPaginationEllipsis v-if="p === 'ellipsis'">…</XhPaginationEllipsis>
      <XhPaginationItem v-else :value="p">{{ p }}</XhPaginationItem>
    </template>
    <XhPaginationNextTrigger>下一页</XhPaginationNextTrigger>
    <span style="flex-basis: 100%">第 {{ page }} / {{ totalPages }} 页</span>
  </XhPaginationRoot>
</template>

受控与切片

传了 page 就由宿主说了算；插槽里的 slice 按当前页从整份数据里切出这一页

• 第 1 条记录
• 第 2 条记录
• 第 3 条记录
• 第 4 条记录
• 第 5 条记录

第 1-5 条，共 23 条

<script setup lang="ts">
import { ref } from "vue";
import {
  XhPaginationEllipsis,
  XhPaginationItem,
  XhPaginationNextTrigger,
  XhPaginationPrevTrigger,
  XhPaginationRoot,
} from "@xihan-ui/vue";

const rows = Array.from({ length: 23 }, (_, i) => `第 ${i + 1} 条记录`);
const page = ref(1);
</script>

<template>
  <XhPaginationRoot
    v-slot="{ pages, pageRange, count, slice }"
    v-model:page="page"
    :count="rows.length"
    :page-size="5"
    style="inline-size: 100%"
  >
    <ul style="flex-basis: 100%; margin: 0 0 4px; padding-inline-start: 20px">
      <li v-for="row in slice(rows)" :key="row">{{ row }}</li>
    </ul>

    <XhPaginationPrevTrigger>上一页</XhPaginationPrevTrigger>
    <template v-for="(p, i) in pages" :key="`${p}-${i}`">
      <XhPaginationEllipsis v-if="p === 'ellipsis'">…</XhPaginationEllipsis>
      <XhPaginationItem v-else :value="p">{{ p }}</XhPaginationItem>
    </template>
    <XhPaginationNextTrigger>下一页</XhPaginationNextTrigger>
    <span style="flex-basis: 100%">
      第 {{ pageRange.start }}-{{ pageRange.end }} 条，共 {{ count }} 条
    </span>
  </XhPaginationRoot>
</template>

两侧页数

sibling-count 决定当前页两侧各留几页，序列长度恒定，切页时省略号左右挪、按钮不抖

……

<script setup lang="ts">
import {
  XhPaginationEllipsis,
  XhPaginationItem,
  XhPaginationNextTrigger,
  XhPaginationPrevTrigger,
  XhPaginationRoot,
} from "@xihan-ui/vue";
</script>

<template>
  <XhPaginationRoot
    v-slot="{ pages }"
    :count="500"
    :page-size="10"
    :default-page="12"
    :sibling-count="2"
    style="inline-size: 100%"
  >
    <XhPaginationPrevTrigger>上一页</XhPaginationPrevTrigger>
    <template v-for="(p, i) in pages" :key="`${p}-${i}`">
      <XhPaginationEllipsis v-if="p === 'ellipsis'">…</XhPaginationEllipsis>
      <XhPaginationItem v-else :value="p">{{ p }}</XhPaginationItem>
    </template>
    <XhPaginationNextTrigger>下一页</XhPaginationNextTrigger>
  </XhPaginationRoot>
</template>

读屏文案

translations 换掉 nav 地标名与各按钮的 aria-label，默认是英文

…

<script setup lang="ts">
import {
  XhPaginationEllipsis,
  XhPaginationItem,
  XhPaginationNextTrigger,
  XhPaginationPrevTrigger,
  XhPaginationRoot,
} from "@xihan-ui/vue";

const translations = {
  root: "订单列表分页",
  prevTrigger: "上一页",
  nextTrigger: "下一页",
  item: (page: number) => `第 ${page} 页`,
};
</script>

<template>
  <XhPaginationRoot
    v-slot="{ pages }"
    :count="80"
    :page-size="10"
    :translations="translations"
    style="inline-size: 100%"
  >
    <XhPaginationPrevTrigger>上一页</XhPaginationPrevTrigger>
    <template v-for="(p, i) in pages" :key="`${p}-${i}`">
      <XhPaginationEllipsis v-if="p === 'ellipsis'">…</XhPaginationEllipsis>
      <XhPaginationItem v-else :value="p">{{ p }}</XhPaginationItem>
    </template>
    <XhPaginationNextTrigger>下一页</XhPaginationNextTrigger>
  </XhPaginationRoot>
</template>

语气

tone 换的是当前页选中态的底色与文字色，这里预置第 3 页为当前页

brand（缺省）

neutral

success

warning

danger

info

<script setup lang="ts">
import {
  XhPaginationEllipsis,
  XhPaginationItem,
  XhPaginationNextTrigger,
  XhPaginationPrevTrigger,
  XhPaginationRoot,
} from "@xihan-ui/vue";

const tones = [
  { value: "brand", label: "brand（缺省）" },
  { value: "neutral", label: "neutral" },
  { value: "success", label: "success" },
  { value: "warning", label: "warning" },
  { value: "danger", label: "danger" },
  { value: "info", label: "info" },
];
</script>

<template>
  <div style="inline-size: 100%; display: grid; gap: 12px">
    <div
      v-for="t in tones"
      :key="t.value"
      style="display: flex; align-items: center; gap: 12px"
    >
      <span style="inline-size: 120px; flex: none">{{ t.label }}</span>
      <XhPaginationRoot
        v-slot="{ pages }"
        :count="50"
        :page-size="10"
        :default-page="3"
        :tone="t.value"
      >
        <XhPaginationPrevTrigger>上一页</XhPaginationPrevTrigger>
        <template v-for="(p, i) in pages" :key="`${p}-${i}`">
          <XhPaginationEllipsis v-if="p === 'ellipsis'">…</XhPaginationEllipsis>
          <XhPaginationItem v-else :value="p">{{ p }}</XhPaginationItem>
        </template>
        <XhPaginationNextTrigger>下一页</XhPaginationNextTrigger>
      </XhPaginationRoot>
    </div>
  </div>
</template>

尺寸

size 一档换掉页码格子的高度、内边距与字号，上一页 / 下一页与省略号一并跟着变

sm

…

缺省

…

lg

…

<script setup lang="ts">
import {
  XhPaginationEllipsis,
  XhPaginationItem,
  XhPaginationNextTrigger,
  XhPaginationPrevTrigger,
  XhPaginationRoot,
} from "@xihan-ui/vue";

const sizes = [
  { value: "sm", label: "sm" },
  { value: undefined, label: "缺省" },
  { value: "lg", label: "lg" },
];
</script>

<template>
  <div style="inline-size: 100%; display: grid; gap: 16px">
    <div
      v-for="s in sizes"
      :key="s.label"
      style="display: flex; align-items: center; gap: 12px"
    >
      <span style="inline-size: 60px; flex: none">{{ s.label }}</span>
      <XhPaginationRoot
        v-slot="{ pages }"
        :count="200"
        :page-size="10"
        :default-page="4"
        :size="s.value"
      >
        <XhPaginationPrevTrigger>上一页</XhPaginationPrevTrigger>
        <template v-for="(p, i) in pages" :key="`${p}-${i}`">
          <XhPaginationEllipsis v-if="p === 'ellipsis'">…</XhPaginationEllipsis>
          <XhPaginationItem v-else :value="p">{{ p }}</XhPaginationItem>
        </template>
        <XhPaginationNextTrigger>下一页</XhPaginationNextTrigger>
      </XhPaginationRoot>
    </div>
  </div>
</template>

极简排布

页码序列不渲染也行，只留上一页 / 下一页与一行位置回显；先后顺序归作者

2 / 100

<script setup lang="ts">
import { ref } from "vue";
import {
  XhPaginationNextTrigger,
  XhPaginationPrevTrigger,
  XhPaginationRoot,
} from "@xihan-ui/vue";

const page = ref(2);
</script>

<template>
  <XhPaginationRoot
    v-slot="{ page: current, totalPages }"
    v-model:page="page"
    :count="1000"
    :page-size="10"
    style="inline-size: 100%"
  >
    <XhPaginationPrevTrigger>上一页</XhPaginationPrevTrigger>
    <span>{{ current }} / {{ totalPages }}</span>
    <XhPaginationNextTrigger>下一页</XhPaginationNextTrigger>
  </XhPaginationRoot>
</template>

快速跳页

输入框按 Enter 调插槽给的 setPage；越界页码由它夹回合法区间

……

<script setup lang="ts">
import { ref } from "vue";
import {
  XhPaginationEllipsis,
  XhPaginationItem,
  XhPaginationNextTrigger,
  XhPaginationPrevTrigger,
  XhPaginationRoot,
  XhTextFieldInput,
  XhTextFieldRoot,
} from "@xihan-ui/vue";

const target = ref("");

// 只放正整数进去，其余按无效输入丢掉
function jump(setPage: (page: number) => void): void {
  const next = Number(target.value);
  if (Number.isInteger(next) && next > 0) {
    setPage(next);
  }
  target.value = "";
}
</script>

<template>
  <XhPaginationRoot
    v-slot="{ pages, setPage }"
    :count="1000"
    :page-size="10"
    :default-page="5"
    style="inline-size: 100%"
  >
    <XhPaginationPrevTrigger>上一页</XhPaginationPrevTrigger>
    <template v-for="(p, i) in pages" :key="`${p}-${i}`">
      <XhPaginationEllipsis v-if="p === 'ellipsis'">…</XhPaginationEllipsis>
      <XhPaginationItem v-else :value="p">{{ p }}</XhPaginationItem>
    </template>
    <XhPaginationNextTrigger>下一页</XhPaginationNextTrigger>

    <XhTextFieldRoot v-model:value="target" size="sm" placeholder="页码">
      <XhTextFieldInput
        style="inline-size: 72px"
        aria-label="跳至页码"
        @keydown.enter="jump(setPage)"
      />
    </XhTextFieldRoot>
  </XhPaginationRoot>
</template>

每页条数

pageSize 归宿主持有；换档后总页数重算，越界的当前页被夹回末页

10每页条数

…… 第 71-80 条，共 196 条

<script setup lang="ts">
import { computed, ref } from "vue";
import {
  XhPaginationEllipsis,
  XhPaginationItem,
  XhPaginationNextTrigger,
  XhPaginationPrevTrigger,
  XhPaginationRoot,
  XhSelectContent,
  XhSelectIndicator,
  XhSelectItem,
  XhSelectItemIndicator,
  XhSelectItemText,
  XhSelectLabel,
  XhSelectPositioner,
  XhSelectRoot,
  XhSelectTrigger,
  XhSelectValueText,
} from "@xihan-ui/vue";

const options = ["10", "20", "50"];
const picked = ref<string[]>(["10"]);
const pageSize = computed(() => Number(picked.value[0] ?? "10"));
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%">
    <XhSelectRoot v-model:value="picked" size="sm">
      <XhSelectLabel>每页条数</XhSelectLabel>
      <XhSelectTrigger>
        <XhSelectValueText />
        <XhSelectIndicator>▾</XhSelectIndicator>
      </XhSelectTrigger>
      <XhSelectPositioner>
        <XhSelectContent>
          <XhSelectItem v-for="o in options" :key="o" :value="o">
            <XhSelectItemText>{{ o }} 条 / 页</XhSelectItemText>
            <XhSelectItemIndicator>✓</XhSelectItemIndicator>
          </XhSelectItem>
        </XhSelectContent>
      </XhSelectPositioner>
    </XhSelectRoot>

    <XhPaginationRoot
      v-slot="{ pages, pageRange, count }"
      :count="196"
      :page-size="pageSize"
      :default-page="8"
      style="inline-size: 100%"
    >
      <XhPaginationPrevTrigger>上一页</XhPaginationPrevTrigger>
      <template v-for="(p, i) in pages" :key="`${p}-${i}`">
        <XhPaginationEllipsis v-if="p === 'ellipsis'">…</XhPaginationEllipsis>
        <XhPaginationItem v-else :value="p">{{ p }}</XhPaginationItem>
      </template>
      <XhPaginationNextTrigger>下一页</XhPaginationNextTrigger>
      <span style="flex-basis: 100%">
        第 {{ pageRange.start }}-{{ pageRange.end }} 条，共 {{ count }} 条
      </span>
    </XhPaginationRoot>
  </div>
</template>

整组禁用

分页自己没有禁用开关：裹一层 disabled 的 fieldset，里面的按钮统一失效并脱出 Tab 序

数据加载中，整组分页不可操作

…

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhPaginationEllipsis,
  XhPaginationItem,
  XhPaginationNextTrigger,
  XhPaginationPrevTrigger,
  XhPaginationRoot,
} from "@xihan-ui/vue";

const loading = ref(true);

// 禁用期间把页码格子的取色也压成禁用态：上一页 / 下一页由皮肤的 :disabled 规则自己接管
const mutedTokens = {
  "--xh-pagination-item-fg": "var(--xh-fg-disabled)",
  "--xh-pagination-item-bg-hover": "transparent",
  "--xh-pagination-item-bg-selected": "var(--xh-bg-muted)",
  "--xh-pagination-item-border-selected": "var(--xh-bg-muted)",
  "--xh-pagination-item-fg-selected": "var(--xh-fg-disabled)",
};
</script>

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; inline-size: 100%">
    <div style="display: flex; align-items: center; gap: 8px">
      <XhButton size="sm" variant="outline" @click="loading = !loading">
        {{ loading ? "加载完成" : "重新加载" }}
      </XhButton>
      <span>{{ loading ? "数据加载中，整组分页不可操作" : "可以翻页了" }}</span>
    </div>

    <fieldset
      :disabled="loading"
      :style="[
        { margin: 0, padding: 0, border: 0, minInlineSize: 0 },
        loading ? mutedTokens : {},
      ]"
    >
      <XhPaginationRoot
        v-slot="{ pages }"
        :count="196"
        :page-size="10"
        :default-page="3"
      >
        <XhPaginationPrevTrigger>上一页</XhPaginationPrevTrigger>
        <template v-for="(p, i) in pages" :key="`${p}-${i}`">
          <XhPaginationEllipsis v-if="p === 'ellipsis'">…</XhPaginationEllipsis>
          <XhPaginationItem v-else :value="p">{{ p }}</XhPaginationItem>
        </template>
        <XhPaginationNextTrigger>下一页</XhPaginationNextTrigger>
      </XhPaginationRoot>
    </fieldset>
  </div>
</template>

产物

层	值
自定义元素	<xh-pagination>
Vue 组件	XhPaginationEllipsis XhPaginationItem XhPaginationNextTrigger XhPaginationPrevTrigger XhPaginationRoot
组合式函数	usePagination
状态机	paginationMachine
皮肤	@xihan-ui/styles/pagination.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="pagination"：root · prev-trigger · next-trigger · item · ellipsis

Props

属性	类型	必填	说明
count	number		总条数（不是总页数）。总页数由它与 pageSize 算出。
pageSize	number		每页条数，默认 10；小于 1 的值一律按 1 处理。
page	number		当前页。给定即受控：内部不再自改，只发 onPageChange。
defaultPage	number		非受控初始页，默认 1。
siblingCount	number		当前页两侧各显示几页，默认 1。
dir	Direction		文字方向，只作用于排版；上一页/下一页的语义不随之翻转，"上一页"永远是 page - 1。
translations	Partial<PaginationTranslations>
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定用哪族颜色。
size	Size		尺寸：sm / md / lg。
onPageChange	(details: PaginationPageChangeDetails) => void		页码变化意图回调；受控时是唯一出口，非受控随内部写入一并通知。

状态机

状态：idle

事件：PAGE.SET · PAGE.PREV · PAGE.NEXT

connect API

usePagination 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
page	number	当前页，恒在 [1, max(totalPages, 1)] 内。
pageSize	number
count	number
totalPages	number
pages	PaginationPage[]	页码序列，作者照着渲染 item 与 ellipsis。
pageRange	PaginationEntryRange	当前页对应的条目区间，1 基闭区间；无数据时是 { start: 0, end: 0 }。
previousPage	number | null	上一页页码；已在首页（或无数据）时为 null。
nextPage	number | null
setPage	(page: number) => void	页码会被夹进合法区间，越界入参不会写出越界的页。
goToPrevPage	() => void
goToNextPage	() => void
slice	<V>(data: readonly V[]) => V[]	按当前页从整份数据里切出这一页。
getRootProps	() => T['element']
getPrevTriggerProps	() => T['button']
getNextTriggerProps	() => T['button']
getItemProps	(props: PaginationItemProps) => T['button']
getEllipsisProps	() => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
Enter / Space	focus in item	跳到该页码（原生按钮激活，平台把按键翻成 click）
Enter / Space	focus in prev-trigger, 非首页	回上一页；首页时按钮是原生 disabled，焦点根本落不上去
Enter / Space	focus in next-trigger, 非末页	进下一页；末页时按钮是原生 disabled
Tab / Shift+Tab	focus in root	逐个走过每个可用按钮——分页不做 roving tabindex，用户要能 Tab 到某一页再确认；禁用的首尾按钮自动脱序