x-next 1.13.0 → 1.15.0

package/AI_USAGE/components/pagination.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Pagination AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
 
-先读 [通用接入](../core.md)。公开导出：`Pagination`；模型：v-model:current、v-model:page-size；已核对事件：change、pageSizeChange。
+先读 [通用接入](../core.md)。公开导出：`Pagination`；主要模型：v-model:current、v-model:page-size。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./pagination-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/pagination`（包含 base.css、button.css、empty.css、form-checkbox.css、form-input.css、form-input-number.css、form-select.css、pagination.css、scrollbar-v2.css、spin.css、trigger.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/pagination)。`total` 必填且表示记录总数。使用 `v-model:current` 和 `v-model:page-size`；默认非受控值为页码 `1`、每页 `10`，`showTotal` / `showPageSize` / `showJumper` 默认关闭，`autoAdjust=true`。
 
 `change(current)` 和 `page-size-change(pageSize)` 各返回一个数字；不会请求数据。页码按总数裁剪并取整，每页条数必须为正安全整数；非法值回退到有效 `defaultPageSize` 或 10。`total=0` 保留第 1 页，开启 `hideOnSinglePage` 可隐藏整个分页。`total` 插槽提供总数，`page-item` 提供页码；改变条数后的业务重新查询需自行实现。
@@ -33,4 +35,379 @@ function resized(size: number) { current.value = 1; feedback.value = `每页 ${s
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/pagination.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./pagination-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于长列表和表格的数据分页浏览，可切换页码、调整每页条数或输入页码快速跳转。
+
+
+### 何时使用
+
+- 数据量较大，需要拆分为多个页面展示。
+- 表格、列表或搜索结果需要保留当前页、每页条数等浏览状态。
+- 需要在完整分页、简单分页和跳转输入之间按场景切换。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Pagination } from 'x-next';
+import 'x-next/style/pagination';
+import { ref } from 'vue';
+
+const current = ref(2);
+</script>
+<template>
+<Pagination v-model:current="current" :total="120" show-total />
+</template>
+```
+
+### 受控页码和事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Pagination } from 'x-next';
+import 'x-next/style/pagination';
+import { ref } from 'vue';
+
+const current = ref(3);
+const pageSize = ref(10);
+const logs = ref<string[]>([]);
+
+const handleCurrentChange = (current: number) => {
+  logs.value = [`change: 第 ${current} 页`, ...logs.value].slice(0, 5);
+};
+
+const handlePageSizeChange = (pageSize: number) => {
+  logs.value = [`page-size-change: ${pageSize} 条/页`, ...logs.value].slice(0, 5);
+};
+</script>
+<template>
+<Pagination
+    v-model:current="current"
+    v-model:page-size="pageSize"
+    :total="240"
+    show-total
+    show-page-size
+    :page-size-options="[10, 20, 40]"
+    @change="handleCurrentChange"
+    @page-size-change="handlePageSizeChange"
+  />
+  <p>当前：第 {{ current }} 页，{{ pageSize }} 条/页</p>
+  <p v-for="(log, index) in logs" :key="index">{{ log }}</p>
+</template>
+```
+
+### 自动调整与动态总数
+
+默认保留旧页第一条记录所在的数据页。例如每页 10 条的第 20 页首条是第 191 条，改为 50 条后跳到第 4 页，总页数减少时再裁剪到最后一页。每次调整只发一组页码事件。
+
+关闭 `autoAdjust` 后只裁剪显示，不改写业务值；同一批更新中业务主动改了 `current`（例如返回第一页），优先使用业务值。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Button, Pagination } from 'x-next';
+import 'x-next/style/pagination';
+import 'x-next/style/button';
+const current = ref(20);
+const pageSize = ref(10);
+const total = ref(240);
+const autoAdjust = ref(true);
+const changes = ref<number[]>([]);
+const resetKey = ref(0);
+function reset() {
+  resetKey.value += 1;
+  current.value = 20;
+  pageSize.value = 10;
+  total.value = 240;
+  changes.value = [];
+}
+</script>
+<template>
+<label><input v-model="autoAdjust" type="checkbox" /> 自动调整</label>
+  <Button @click="pageSize = 50">每页改为 50</Button>
+  <Button @click="total = 100">总数减为 100</Button>
+  <Button @click="reset">重置</Button>
+  <Pagination :key="resetKey" v-model:current="current" v-model:page-size="pageSize" :total="total"
+    :auto-adjust="autoAdjust" show-total show-page-size :page-size-options="[10, 50]"
+    @change="(page) => changes.push(page)" />
+  <p role="status">业务值：第 {{ current }} 页，{{ pageSize }} 条/页；change：{{ changes.join(' → ') || '无' }}</p>
+</template>
+```
+
+### 每页条数
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Pagination } from 'x-next';
+import 'x-next/style/pagination';
+import { ref } from 'vue';
+
+const current = ref(5);
+const pageSize = ref(10);
+</script>
+<template>
+<Pagination
+    v-model:current="current"
+    v-model:page-size="pageSize"
+    :total="320"
+    show-page-size
+    :page-size-options="[10, 20, 50, 100]"
+  />
+</template>
+```
+
+### 条数选择器定制
+
+可透传搜索、加载、弹层和格式化等 Select 能力。当前条数不在选项中时自动并入，非法选项会过滤并去重、排序。分页维护单个数字值，不支持多选、清空和创建条数。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Pagination } from 'x-next';
+import 'x-next/style/pagination';
+const current = ref(4);
+const pageSize = ref(25);
+</script>
+<template>
+<Pagination v-model:current="current" v-model:page-size="pageSize" :total="500"
+    show-page-size :page-size-options="[10, 20, 50]"
+    :page-size-props="{ allowSearch: true, formatLabel: (option) => `${option.value} 条记录 / 页` }" />
+  <p role="status">当前：第 {{ current }} 页，{{ pageSize }} 条/页</p>
+  <Pagination :total="100" show-page-size :page-size-props="{ loading: true }" />
+</template>
+```
+
+### 跳转输入
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Pagination } from 'x-next';
+import 'x-next/style/pagination';
+import { ref } from 'vue';
+
+const current = ref(1);
+</script>
+<template>
+<Pagination v-model:current="current" :total="180" show-jumper>
+    <template #jumper-append>页</template>
+  </Pagination>
+</template>
+```
+
+### 简单模式
+
+简单模式输入提交或失焦后显示实际当前页。清空不翻页；受控父级未接受新值时，恢复父级页码。普通跳转输入提交后清空，输入超出范围会裁剪；小数输入按整数部分处理。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Pagination } from 'x-next';
+import 'x-next/style/pagination';
+import { ref } from 'vue';
+
+const current = ref(4);
+</script>
+<template>
+<Pagination v-model:current="current" :total="120" simple />
+</template>
+```
+
+### 更多页码和边界
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Pagination } from 'x-next';
+import 'x-next/style/pagination';
+</script>
+<template>
+<Pagination :total="500" :default-current="18" show-more />
+  <Pagination :total="8" hide-on-single-page />
+</template>
+```
+
+### 空数据和隐藏
+
+`total=0` 时保留第 1 页，两侧箭头禁用，简单模式显示 `1 / 1`。开启 `hideOnSinglePage` 会同时隐藏总数、页码、条数选择器和跳转输入。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Button, Pagination } from 'x-next';
+import 'x-next/style/button';
+import 'x-next/style/pagination';
+const total = ref(0);
+</script>
+<template>
+<Button @click="total = total ? 0 : 25">切换空数据 / 25 条</Button>
+  <Pagination :total="total" show-total />
+  <Pagination :total="total" simple show-total />
+  <Pagination :total="total" hide-on-single-page show-total />
+  <p role="status">总数 {{ total }}；最后一组在单页时隐藏</p>
+</template>
+```
+
+### 页码密度和按钮样式
+
+`baseSize + 2 * bufferSize` 是开始折叠页码的阈值，`bufferSize` 还控制当前页两边的页码数量和省略号步进。`activePageItemStyle` 在共有 `pageItemStyle` 上覆盖，不会丢失共有圆角、宽度等规则。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Pagination } from 'x-next';
+import 'x-next/style/pagination';
+const current = ref(8);
+</script>
+<template>
+<Pagination v-model:current="current" :total="1000" :base-size="4" :buffer-size="1"
+    :page-item-style="{ minWidth: '40px', borderRadius: '12px' }"
+    :active-page-item-style="{ fontWeight: '700' }" />
+  <p role="status">当前第 {{ current }} 页，省略号跨 3 页跳转</p>
+</template>
+```
+
+### 尺寸和禁用
+
+上一页/下一页使用标准 `chevron-left` / `chevron-right` 图标，四档图标尺寸分别为 16 / 18 / 20 / 22px，描边为 1.5。首末页的对应箭头保持禁用状态。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Pagination, Radio, RadioGroup } from 'x-next';
+import 'x-next/style/pagination';
+import 'x-next/style/radio';
+import 'x-next/style/radio-group';
+import { ref } from 'vue';
+
+const size = ref<'mini' | 'small' | 'medium' | 'large'>('medium');
+</script>
+<template>
+<RadioGroup v-model="size" type="button">
+    <Radio value="mini">Mini</Radio>
+    <Radio value="small">Small</Radio>
+    <Radio value="medium">Medium</Radio>
+    <Radio value="large">Large</Radio>
+  </RadioGroup>
+  <Pagination :total="120" :size="size" show-total show-page-size show-jumper />
+  <Pagination :total="120" :default-current="3" disabled show-total show-page-size />
+</template>
+```
+
+### 自定义内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Pagination } from 'x-next';
+import 'x-next/style/pagination';
+import { ref } from 'vue';
+
+const current = ref(6);
+</script>
+<template>
+<Pagination v-model:current="current" :total="260" show-total show-jumper>
+    <template #total="{ total }">共 {{ total }} 条记录</template>
+    <template #page-item="{ page }">P{{ page }}</template>
+    <template #page-item-step="{ type }">
+      {{ type === 'previous' ? '上一页' : '下一页' }}
+    </template>
+    <template #page-item-ellipsis>...</template>
+    <template #jumper-prepend>到第</template>
+    <template #jumper-append>页</template>
+  </Pagination>
+</template>
+```
+
+### 列表组合与异步状态
+
+分页组件只发出状态变更。这里由业务按页切片并模拟 400ms 加载；加载期间使用 `disabled` 阻止重复操作。真实接口应由业务处理请求取消、错误和响应顺序。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { computed, onUnmounted, ref, watch } from 'vue';
+import { Pagination, Table } from 'x-next';
+import 'x-next/style/pagination';
+import 'x-next/style/table';
+const records = Array.from({ length: 65 }, (_, index) => ({
+  key: String(index + 1), name: `任务 ${index + 1}`,
+}));
+const current = ref(1);
+const pageSize = ref(10);
+const loading = ref(false);
+const data = computed(() => records.slice((current.value - 1) * pageSize.value, current.value * pageSize.value));
+let timer: ReturnType<typeof setTimeout> | undefined;
+watch([current, pageSize], () => {
+  clearTimeout(timer);
+  loading.value = true;
+  timer = setTimeout(() => { loading.value = false; }, 400);
+});
+onUnmounted(() => clearTimeout(timer));
+</script>
+<template>
+<div :aria-busy="loading">
+    <p role="status">{{ loading ? '加载中…' : `已显示第 ${current} 页` }}</p>
+    <Table :data="data" :columns="[{ title: '任务', dataIndex: 'name' }]" :pagination="false" :loading="loading" />
+    <Pagination v-model:current="current" v-model:page-size="pageSize" :total="records.length"
+      :disabled="loading" show-total show-page-size show-jumper :page-size-options="[10, 20]" />
+  </div>
+</template>
+```
+
+### 本地化
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ConfigProvider, Pagination, enUS } from 'x-next';
+import 'x-next/style/pagination';
+// 原生 aria 属性透传到组件根节点，用于区分多个分页区域。
+const navigationAttrs = { 'aria-label': 'Search results' };
+</script>
+<template>
+<ConfigProvider :locale="enUS">
+    <Pagination v-bind="navigationAttrs" :total="120" show-total show-page-size show-jumper />
+  </ConfigProvider>
+</template>
+```
+
+### 使用说明
+
+- 页码、总数按整数处理；每页条数必须是正安全整数，非法值回退到有效 `defaultPageSize` 或 10。
+- 页码项、上一页、下一页和省略跳转支持键盘聚焦，可使用 Enter 或 Space 触发。
+- 窄容器下辅助区域换行，页码列表可横向滚动；更紧凑的工具栏可使用 `simple`。组件不会按屏宽自动改变模式。
+- `pageSizeProps` 中 `modelValue`、`options`、`size`、`disabled`、`multiple`、`allowClear`、`allowCreate`、`fieldNames` 由分页维护，其余能力按 Select API 使用。
+
+
+### 无障碍
+
+- 根节点是 `role="navigation"` 地标，带 `aria-label`（跟随 locale），读屏用户可以按地标快速定位。
+- 当前页用 `aria-current="page"` 标注，页码、上一页/下一页与省略号带本地化 `aria-label`，自定义图标插槽也保留名称。
+- 禁用时所有分页项（包括省略号）都不可聚焦、不响应键盘。
+- 跳转输入框与条数选择器带无障碍名称。键盘快速跳转导致当前节点被移除时，焦点接续到当前页。
+- 可通过根节点 `aria-label` 区分多个分页区域；locale 的 `pageLabel`、`pageSizeLabel` 为可选文案，旧自定义语言包会回退到现有文案。
+
+
+### 已知限制
+
+- `total` 应为非负整数；非有限或负数按 0 处理，有限超大值限制到 `Number.MAX_SAFE_INTEGER`。未知总数分页由业务层适配。
+- 初始或单独传入越界 `current` 时只裁剪显示，不发事件；`autoAdjust` 处理后续总页数或条数变化。受控父级未接受更新时继续显示其值裁剪后的页码。
+- 不提供记录加载、请求、页面路由或真实页码链接。`page-item` 用于内容定制，避免嵌套可聚焦按钮；需要 SEO 链接导航时由业务实现。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./pagination-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/pie-chart-api.md

@@ -0,0 +1,109 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# PieChart 完整公开 API
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## PieChart API
+
+公开声明：`dist/components/pie-chart/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| data | 分片数据，必填 | undefined &#124; PieChartItem[] | 是 | [] |
+| innerRadius | 内半径：0 为饼图，数字按 px，'62%' 按比例 | undefined &#124; string &#124; number | 否 | 0 |
+| height | 图表高度，数字按 px | undefined &#124; string &#124; number | 否 | 280 |
+| width | 图表宽度，数字按 px | undefined &#124; string &#124; number | 否 | "100%" |
+| labels | 外围标签：false 关闭，对象配置字号与颜色 | undefined &#124; false &#124; true &#124; { fontSize?: number; color?: string; } | 否 | true |
+| center | 环形中心内容：false 关闭 | undefined &#124; false &#124; true &#124; { fontSize?: number; } | 否 | true |
+| tooltip | 悬浮提示 | undefined &#124; false &#124; true | 否 | true |
+| legend | 图例，点击可隐藏/显示分片 | undefined &#124; false &#124; true | 否 | false |
+| valueFormatter | 数值格式化，用于提示、图例与中心内容 | undefined &#124; (value: number) => string | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| loading | 加载中 | undefined &#124; false &#124; true &#124; { [x: string]: unknown; } | 否 | false |
+| ariaLabel | 无障碍名称；设置后画布带 role="img" | undefined &#124; string | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| item-click | 见场景用法与类型 | undefined &#124; (data: PieChartClickData) => any |
+| legend-change | 见场景用法与类型 | undefined &#124; (visibleIndexes: number[]) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| center | 环形中心内容 | undefined &#124; (props: { total: number; formatValue: (value: number) => string; }) => unknown |
+| tooltip | 自定义悬浮提示内容 | undefined &#124; (props: PieChartActiveData) => unknown |
+| label | 自定义外围标签 | undefined &#124; (props: PieChartActiveData) => unknown |
+| legend | 自定义图例 | undefined &#124; (props: { items: PieChartItem[]; hiddenIndexes: number[]; }) => unknown |
+| empty | 自定义空态内容 | undefined &#124; () => unknown |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+interface PieChartItem {
+    /** 分片名称，用于标签、提示与图例 */
+    name: string;
+    /** 分片数值（非负） */
+    value: number;
+}
+
+interface PieChartTooltipEntry {
+    /** 分片下标 */
+    index: number;
+    name: string;
+    /** 原始数值 */
+    value: number;
+    /** 占比（0 ~ 1） */
+    percent: number;
+    /** 生效颜色 */
+    color: string;
+}
+
+interface PieChartActiveData extends PieChartTooltipEntry {
+    /** 所有可见分片的合计 */
+    total: number;
+    /** 已格式化数值的便捷函数，与组件内保持一致 */
+    formatValue: (value: number) => string;
+    /** 已格式化占比的函数，如 12.3% */
+    formatPercent: (percent: number) => string;
+}
+
+interface PieChartClickData extends PieChartActiveData {
+}
+
+interface PieChartSegment {
+    /** 分片下标（对应 data 下标） */
+    index: number;
+    name: string;
+    value: number;
+    /** 占比（0 ~ 1，按可见分片总量计算） */
+    percent: number;
+    /** 生效颜色 */
+    color: string;
+    /** 扇形 / 环形分段路径 */
+    d: string;
+    /** 外围标签锚点 */
+    labelX: number;
+    labelY: number;
+    /** 标签对齐方式：右半圆左对齐、左半圆右对齐 */
+    labelAnchor: 'start' | 'end';
+    /** 占比是否达到可读阈值（未达到则不画外围标签） */
+    showLabel: boolean;
+    /** 分片中间角（用于提示锚点定位） */
+    midAngle: number;
+}
+```
+
+
+返回 [PieChart 用法](./pie-chart.md)。