x-next 1.2.0 → 1.3.1

package/AI_USAGE.md

@@ -0,0 +1,647 @@
+<!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage-recipes.md and script/ai-usage/manifest.js. -->
+# x-next AI 使用手册
+
+适用版本：**x-next@1.3.1**。Vue：`^3.5.0`；Node：`>=20.19.0`。
+
+来源指纹（精选示例、映射、版本与公开类型声明）：`026780d75893368a0a1da6edd95df58545bcfefe87f3a5390756065500e73fe7`。
+
+先按业务需要选择组件，不要求全部迁移。本手册限定在用户确认的 22 个组件及必要的同族子组件，未覆盖的导出不表示已完成业务验收。
+
+读取入口：`node_modules/x-next/AI_USAGE.md`；可用 `require.resolve('x-next/AI_USAGE.md')` 定位。这个文件名不会自动让所有 AI 工具加载，消费项目应在自己的指令中明确引用。
+
+## 组件选择索引
+
+| 组件/服务 | 公共导出 | 全局标签/形式 | 受控模型 | 详细文档 |
+| --- | --- | --- | --- | --- |
+| Button | `Button` | `<x-button>` | 无 | [组件文档](https://x-next.ztes.com/components/button) |
+| Checkbox | `Checkbox` | `<x-checkbox>` | `v-model` | [组件文档](https://x-next.ztes.com/components/checkbox) |
+| Radio | `Radio` | `<x-radio>` | `v-model` | [组件文档](https://x-next.ztes.com/components/radio) |
+| Select | `Select` | `<x-select>` | `v-model`, `v-model:popup-visible` | [组件文档](https://x-next.ztes.com/components/select) |
+| Slider | `Slider` | `<x-slider>` | `v-model` | [组件文档](https://x-next.ztes.com/components/slider) |
+| Rate | `Rate` | `<x-rate>` | `v-model` | [组件文档](https://x-next.ztes.com/components/rate) |
+| Switch | `Switch` | `<x-switch>` | `v-model` | [组件文档](https://x-next.ztes.com/components/switch) |
+| DatePicker | `DatePicker` | `<x-date-picker>` | `v-model`, `v-model:popup-visible` | [组件文档](https://x-next.ztes.com/components/date-picker) |
+| TimePicker | `TimePicker` | `<x-time-picker>` | `v-model`, `v-model:popup-visible` | [组件文档](https://x-next.ztes.com/components/time-picker) |
+| Alert | `Alert` | `<x-alert>` | `v-model:visible` | [组件文档](https://x-next.ztes.com/components/alert) |
+| Dialog | `DialogComponent`, `Dialog` | `<x-dialog>` | `v-model` | [组件文档](https://x-next.ztes.com/components/dialog) |
+| Message | `Message`, `MessageComponent` | 命令式服务 | 无 | [组件文档](https://x-next.ztes.com/components/message) |
+| MessageBox | `MessageBox` | 命令式服务 | 无 | [组件文档](https://x-next.ztes.com/components/message-box) |
+| Notification | `Notification`, `NotificationComponent` | 命令式服务 | 无 | [组件文档](https://x-next.ztes.com/components/notification) |
+| Popconfirm | `Popconfirm` | `<x-popconfirm>` | `v-model` | [组件文档](https://x-next.ztes.com/components/popconfirm) |
+| Popover | `Popover` | `<x-popover>` | `v-model:popup-visible` | [组件文档](https://x-next.ztes.com/components/popover) |
+| Progress | `Progress` | `<x-progress>` | 无 | [组件文档](https://x-next.ztes.com/components/progress) |
+| Dropdown | `Dropdown` | `<x-dropdown>` | `v-model:popup-visible` | [组件文档](https://x-next.ztes.com/components/dropdown) |
+| Pagination | `Pagination` | `<x-pagination>` | `v-model:current`, `v-model:page-size` | [组件文档](https://x-next.ztes.com/components/pagination) |
+| Steps | `Steps` | `<x-steps>` | `v-model:current` | [组件文档](https://x-next.ztes.com/components/steps) |
+| Tabs | `Tabs` | `<x-tabs>` | `v-model:active-key` | [组件文档](https://x-next.ztes.com/components/tabs) |
+| Empty | `Empty` | `<x-empty>` | 无 | [组件文档](https://x-next.ztes.com/components/empty) |
+这是一份给业务开发者和 AI Coding 使用的中文代码手册。以下 22 个入口是本手册选定的常用组件与服务；公开导出还有其他能力，不能据此推断所有导出都具有相同成熟度，也不要求每个项目全部使用。
+
+每节提供一个可复制到 `App.vue` 的独立 Vue SFC，显式从 `x-next` 根入口导入，并包含全量 CSS。实际项目可将重复的 CSS 导入统一移到应用入口。本文是代码配方，不新增 live demo；每节链接的既有组件文档提供可交互示例和完整 API。
+
+根目录生成的 `AI_USAGE.md` 随 npm 包分发，可将它提供给 AI 作为消费方用法上下文。编写页面时先选相应配方，再按链接核对所需能力，避免套用其他组件库的属性名。
+
+## 安装与初始化
+
+```sh
+npm install x-next
+```
+
+应用需已有 Vue 3、TypeScript 和 Vue SFC 构建支持。在 `main.ts` 全局安装插件；`App.vue` 使用下方任一配方即可。
+
+```ts
+import { createApp } from 'vue';
+import XNext from 'x-next';
+import App from './App.vue';
+import 'x-next/dist/style.css';
+
+createApp(App).use(XNext).mount('#app');
+```
+
+`app.use(XNext)` 注册全局组件；下方局部具名导入也可独立使用。根入口的 `Dialog` 是服务，模板组件入口是 `DialogComponent`；MessageBox 使用服务函数。
+
+接入时遵循这些约定：
+
+- **原生属性不是组件 props**：部分公开类型没有列出所有原生 `id/name/aria-*`。配方通过明确的属性对象 `v-bind` 传递已核对可用的原生属性，组件 props 和事件仍直接绑定并接受严格模板检查；不要用属性对象绕过对未知组件 API 的核对。
+- **保持受控值稳定**：`v-model` 要初始化为明确的布尔值、字符串、数字或数组。`defaultValue` / `defaultChecked` 用于非受控初始化；将受控值改为 `undefined` 可能切换到内部状态。清空日期、时间时，本手册统一保存 `''`。
+- **选择正确的弹层宿主**：Select、DatePicker、TimePicker、Popover、Dropdown 使用 `popupContainer`；Dialog、Message、MessageBox、Notification、Popconfirm 使用 `renderTo`。容器须已挂载，局部容器需留意定位、滚动和裁剪；Teleport 到 `body` 的弹层不继承原局部容器的主题变量。
+- **先用公开主题变量**：参考[样式与主题](https://x-next.ztes.com/guide/theme)。暗色容器上的 alias 链会重新声明；更深子容器只改语义变量仍可能继承祖先已解析的 alias。`themeColor` 写入的内联 primary alias 也有覆盖边界，需按主题文档设置相关公开 alias。
+- **约束业务全局 CSS**：reset 可用 `:where(...)` 降低优先级，并限定业务作用域；宽泛的原生元素选择器可能覆盖组件样式。自定义内容用插槽和公开属性，不依赖内部结构类名。
+- **清理页面创建的服务**：保留句柄，在路由页面卸载时调用 `close()`；KeepAlive 页面可在停用时清理。Dialog / MessageBox 的命令式关闭不触发确认、取消回调，业务取消逻辑需自行调用；Message / Notification 的关闭会触发各自 `onClose`。
+- **本地链接要刷新产物**：链接源码仓库时，消费方仍可能读取 `dist`；修改后需重新构建库并刷新消费方依赖缓存。本手册的代码使用包根入口与 `dist/style.css`。
+
+## Button
+
+[组件文档与 live demo](https://x-next.ztes.com/components/button)。`type` 默认 `'default'`，视觉主按钮用 `'primary'`；`htmlType` 默认 `'button'`，原生提交用 `'submit'`。独立使用时尺寸回退为 `'medium'`，`disabled` / `loading` 默认关闭。
+
+`click` 载荷为 `MouseEvent`，禁用或加载中不会触发。`default`、`prefix`、`suffix`、`icon` 插槽可组合内容；异步业务自行维护 `loading`。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button } from 'x-next';
+import 'x-next/dist/style.css';
+const loading = ref(false);
+const result = ref('尚未保存');
+async function save(_event: MouseEvent) {
+  loading.value = true;
+  try {
+    await Promise.resolve();
+    result.value = '保存完成';
+  } finally { loading.value = false; }
+}
+</script>
+<template>
+  <Button type="primary" html-type="button" :loading="loading" @click="save">保存</Button>
+  <p role="status">{{ result }}</p>
+</template>
+```
+
+## Checkbox
+
+[组件文档与 live demo](https://x-next.ztes.com/components/checkbox)。使用普通 `v-model`；模型支持 `boolean` 或 `(string | number | boolean)[]`，数组模式配合 `value`。`defaultChecked`、`disabled`、`indeterminate` 默认 `false`；半选状态不会替代模型值。
+
+`change(value, event)` 返回新值和原生 `Event`。默认插槽是文案，`checkbox` 插槽提供 `checked` / `disabled`。`id`、`name`、`required`、`form`、`tabindex`、`autofocus`、`autocomplete` 和 `aria-*` 传给原生复选框。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Checkbox } from 'x-next';
+import 'x-next/dist/style.css';
+const accepted = ref(false);
+const inputAttrs = { id: 'accept-terms', name: 'terms', required: true };
+const feedback = ref('尚未选择');
+function changed(value: boolean | (string | number | boolean)[], event: Event) {
+  feedback.value = `${value === true ? '已同意' : '未同意'}（${event.type}）`;
+}
+</script>
+<template>
+  <Checkbox v-model="accepted" v-bind="inputAttrs" @change="changed">
+    我已阅读使用说明
+  </Checkbox>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Radio
+
+[组件文档与 live demo](https://x-next.ztes.com/components/radio)。`Radio` / `RadioGroup` 的模型和选项值支持 `string | number | boolean`，保留值类型；布尔选项写 `:value="true"`。单个 Radio 的 `value` 默认 `true`，组的非受控默认值为 `''`。
+
+组默认 `type='radio'`、`direction='horizontal'`、`disabled=false`；`change(value, event)` 返回选项值和 `Event`。Radio 默认插槽是文案，组也支持 `options` 和 `label` / `radio` 插槽。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Radio, RadioGroup } from 'x-next';
+import 'x-next/dist/style.css';
+const enabled = ref<string | number | boolean>(true);
+const controlAttrs = { name: 'delivery-mode', 'aria-label': '是否开启通知' };
+const feedback = ref('当前开启');
+function changed(value: string | number | boolean, _event: Event) {
+  feedback.value = value === true ? '当前开启' : '当前关闭';
+}
+</script>
+<template>
+  <RadioGroup v-model="enabled" v-bind="controlAttrs" @change="changed">
+    <Radio :value="true">开启</Radio>
+    <Radio :value="false">关闭</Radio>
+  </RadioGroup>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Select
+
+[组件文档与 live demo](https://x-next.ztes.com/components/select)。`v-model` 返回选项的 `value`；单选通常为标量，多选为数组，也支持对象值。`multiple=false`、`allowClear=false`；单选搜索默认关闭，多选默认开启。`options` 使用可变数组，常用字段是 `label`、`value`、`disabled`。
+
+`change(value)` 返回新值，`clear(event)` 返回 `Event`；单选清空通常为 `''`，多选为 `[]`，已选禁用项可能保留。`v-model:popup-visible` 控制弹层，`option` / `empty` / `header` / `footer` 等插槽见组件文档。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Select } from 'x-next';
+import 'x-next/dist/style.css';
+const city = ref('');
+const options = [
+  { label: '杭州', value: 'hangzhou' },
+  { label: '上海', value: 'shanghai' },
+  { label: '暂未开放', value: 'pending', disabled: true },
+];
+const feedback = ref('尚未选择');
+function changed(value: unknown) {
+  feedback.value = typeof value === 'string' && value ? `城市代码：${value}` : '已清空';
+}
+</script>
+<template>
+  <Select v-model="city" :options="options" allow-search allow-clear placeholder="选择城市" @change="changed" />
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Slider
+
+[组件文档与 live demo](https://x-next.ztes.com/components/slider)。普通模型为 `number`，`range` 模式为 `[number, number]`。默认 `min=0`、`max=100`、`step=1`、`range=false`、`disabled=false`、`showTooltip=true`；范围端点按大小排序并按步长归一化。
+
+`change(value)` 表示值变化，`change-end(value)` 表示一次拖拽、点击、键盘或输入提交结束，载荷均为 `number | [number, number]`。`marks` 是数值键到文字的映射，`formatTooltip` 可格式化提示。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Slider } from 'x-next';
+import 'x-next/dist/style.css';
+const volume = ref(40);
+const controlAttrs = { 'aria-label': '音量' };
+const committed = ref('尚未调整');
+function finish(value: number | [number, number]) {
+  committed.value = typeof value === 'number' ? `已提交音量 ${value}` : value.join(' ～ ');
+}
+</script>
+<template>
+  <div style="max-width: 320px">
+    <Slider v-model="volume" :step="10" :marks="{ 0: '静音', 100: '最大' }" v-bind="controlAttrs" @change-end="finish" />
+    <p role="status">当前 {{ volume }}；{{ committed }}</p>
+  </div>
+</template>
+```
+
+## Rate
+
+[组件文档与 live demo](https://x-next.ztes.com/components/rate)。数值模型默认非受控值为 `0`，`count=5`；`allowHalf`、`allowClear`、`readonly`、`disabled` 默认关闭。启用半星后步长为 `0.5`，值限制在有效数量内；没有 `size` 属性。
+
+`change(value)` 返回 `number`，`hover-change(value)` 返回 `number | undefined`。`character` 插槽提供 `index`、`value`、`count`、`disabled`；`tooltips` 为提示数组。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Rate } from 'x-next';
+import 'x-next/dist/style.css';
+const score = ref(3.5);
+const controlAttrs = { 'aria-label': '服务评分' };
+const feedback = ref('请评分');
+function changed(value: number) { feedback.value = value ? `评分 ${value}` : '已清除评分'; }
+</script>
+<template>
+  <Rate v-model="score" allow-half allow-clear v-bind="controlAttrs" @change="changed" />
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Switch
+
+[组件文档与 live demo](https://x-next.ztes.com/components/switch)。普通 `v-model` 支持 `boolean | string | number`；`checkedValue=true`、`uncheckedValue=false`、`defaultChecked=false`，默认 `type='circle'`。`disabled` / `loading` 阻止切换。
+
+`change(value, event)` 返回新值和 `Event`；`beforeChange(newValue)` 可返回布尔值或 Promise，`false` 或拒绝阻止切换。`checked` / `unchecked` 插槽及 `checkedText` / `uncheckedText` 显示两态文案，line 类型不显示文案。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Switch } from 'x-next';
+import 'x-next/dist/style.css';
+const enabled = ref(false);
+const controlAttrs = { 'aria-label': '通知开关' };
+const feedback = ref('通知关闭');
+function changed(value: boolean | string | number, _event: Event) {
+  feedback.value = value === true ? '通知开启' : '通知关闭';
+}
+</script>
+<template>
+  <Switch v-model="enabled" checked-text="开" unchecked-text="关" v-bind="controlAttrs" @change="changed" />
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## DatePicker
+
+[组件文档与 live demo](https://x-next.ztes.com/components/date-picker)。默认 `type='date'`、`allowClear=true`、`showToday=true`、`showTime=false`、`position='bl'`。`format` 控制显示，`valueFormat` 控制输出；本例使用 `'YYYY-MM-DD'` 字符串。公开 `DatePickerModelValue` 还包含数字、Date、数组和 `undefined`。
+
+`change(value, date, dateString)` 为提交值，`select` 是面板选择；后两个参数声明为 `unknown`。清空返回 `undefined`，本例归一化为 `''` 保持受控。支持 `cell` / `extra` / `prefix` / `suffix-icon` 插槽；带时间选择需确认后提交。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { DatePicker, type DatePickerModelValue } from 'x-next';
+import 'x-next/dist/style.css';
+const date = ref('');
+const feedback = ref('尚未选择日期');
+function update(value: DatePickerModelValue) { date.value = typeof value === 'string' ? value : ''; }
+function changed(value: DatePickerModelValue, _date: unknown, _text: unknown) {
+  update(value);
+  feedback.value = date.value ? `日期：${date.value}` : '已清空日期';
+}
+</script>
+<template>
+  <DatePicker :model-value="date" value-format="YYYY-MM-DD" placeholder="选择日期"
+    @update:model-value="update" @change="changed" />
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## TimePicker
+
+[组件文档与 live demo](https://x-next.ztes.com/components/time-picker)。默认 `type='time'`、`allowClear=true`、`disableConfirm=false`，默认格式为 `'HH:mm:ss'`。`format` 同时决定显示与输出；`step` 用 `{ hour, minute, second }`，各步长默认 `1`。
+
+`change(timeString, time)` 是确认值变化，`select` 是面板选择；字符串载荷为 `string | (string | undefined)[] | undefined`，第二参数为 `unknown`。清空归一化为 `''`；支持 `prefix` / `suffix-icon` / `extra` 插槽及 `disabledHours` 等限制。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TimePicker } from 'x-next';
+import 'x-next/dist/style.css';
+const time = ref('');
+const feedback = ref('尚未选择时间');
+function update(value: unknown) { time.value = typeof value === 'string' ? value : ''; }
+function changed(value: string | (string | undefined)[] | undefined, _time: unknown) {
+  update(value);
+  feedback.value = time.value ? `时间：${time.value}` : '已清空时间';
+}
+</script>
+<template>
+  <TimePicker :model-value="time" format="HH:mm" :step="{ minute: 15 }" placeholder="选择时间"
+    @update:model-value="update" @change="changed" />
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Alert
+
+[组件文档与 live demo](https://x-next.ztes.com/components/alert)。用 `v-model:visible` 控制显示；`defaultVisible=true`、`type='info'`、`showIcon=true`、`closable=false`。常用类型为 info、success、warning、error、normal。
+
+`close(event)` 返回 `MouseEvent`，`after-close` 在关闭动画结束后触发且无参数。默认插槽放正文，`title` / `icon` / `action` / `close-element` 插槽可自定义对应内容。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Alert, Button } from 'x-next';
+import 'x-next/dist/style.css';
+const visible = ref(true);
+const feedback = ref('提示显示中');
+function closed(_event: MouseEvent) { feedback.value = '已点击关闭'; }
+function restore() { visible.value = true; feedback.value = '提示显示中'; }
+</script>
+<template>
+  <Alert v-model:visible="visible" type="warning" title="检查待提交内容" closable @close="closed">
+    提交前请核对所选日期。
+  </Alert>
+  <Button @click="restore">重新显示</Button>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Dialog
+
+[组件文档与 live demo](https://x-next.ztes.com/components/dialog)。从根入口导入 `DialogComponent as XDialog`，普通 `v-model` 为布尔值且默认 `false`。`renderTo='body'`、`mask=true`、`maskToClose=true`、`escToClose=true`、`destroyOnClosed=true`；`width` 支持数字或 CSS 长度。
+
+`title`、默认正文、`footer` 是公开插槽，默认不生成业务按钮。`close(action, event?)` 的 action 为 `'cancel' | 'ok'`，`closed` 表示关闭动画结束；直接改模型不会调用业务取消逻辑。根入口服务 `Dialog(options)` 返回 `close()` / `update(options)` 句柄。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, DialogComponent as XDialog } from 'x-next';
+import 'x-next/dist/style.css';
+const visible = ref(false);
+const feedback = ref('尚未确认');
+function confirm() { feedback.value = '已确认'; visible.value = false; }
+function cancel() { feedback.value = '已取消'; visible.value = false; }
+</script>
+<template>
+  <Button @click="visible = true">打开对话框</Button>
+  <XDialog v-model="visible" title="确认安排" :width="420">
+    <p>核对安排后确认。</p>
+    <template #footer>
+      <Button @click="cancel">取消</Button>
+      <Button type="primary" @click="confirm">确认</Button>
+    </template>
+  </XDialog>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Message
+
+[组件文档与 live demo](https://x-next.ztes.com/components/message)。`Message(options)` 或 `.success()` / `.error()` / `.loading()` 等显示提示。默认 `type='info'`、`duration=3000` 毫秒、`position='top'`、`showClose=false`；`duration=0` 持续显示，内容用 `message` 或 `content`。
+
+返回句柄只有 `close()`；同一容器和位置下再次传相同 `id` 更新消息，没有句柄 `update()`。`onClose(id?)` 在自动或手动关闭时触发；自定义内容可用 VNode / 渲染函数。页面只清理自己持有的句柄。
+
+```vue
+<script setup lang="ts">
+import { onBeforeUnmount, ref } from 'vue';
+import { Button, Message } from 'x-next';
+import 'x-next/dist/style.css';
+const feedback = ref('尚未显示提示');
+let handle: ReturnType<typeof Message> | undefined;
+function show() {
+  handle?.close();
+  handle = Message({ message: '保存完成', type: 'success', duration: 0, showClose: true,
+    onClose: () => { feedback.value = '提示已关闭'; } });
+  feedback.value = '提示显示中';
+}
+onBeforeUnmount(() => handle?.close());
+</script>
+<template>
+  <Button @click="show">显示提示</Button>
+  <Button @click="handle?.close()">关闭提示</Button>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## MessageBox
+
+[组件文档与 live demo](https://x-next.ztes.com/components/message-box)。调用 `MessageBox(options)`，默认类型为 `'success'`、宽度 `360`、居中、显示遮罩和关闭按钮、点击遮罩不关闭。`title` / `content` 支持文字、VNode 或渲染函数；`footer=false` 隐藏页脚。
+
+返回 `close()` / `update(options)` 句柄，结果通过 `onOk(event)` / `onCancel(event)` 回调处理。`beforeOnOk` / `beforeOnCancel` 返回 `boolean | Promise<boolean>`，必须返回 `true` 才放行；异步业务放在前置钩子。它不是 Promise，没有 `confirm()`；`.warning(title, content)` 等返回的 `.ok()` / `.cancel()` 用于注册链式回调。
+
+```vue
+<script setup lang="ts">
+import { onBeforeUnmount, ref } from 'vue';
+import { Button, MessageBox } from 'x-next';
+import 'x-next/dist/style.css';
+const feedback = ref('尚未确认');
+let handle: ReturnType<typeof MessageBox> | undefined;
+function ask() {
+  handle?.close();
+  feedback.value = '等待确认';
+  handle = MessageBox({ title: '确认保存？', content: '确认后保存当前安排。', type: 'warning',
+    beforeOnOk: () => true,
+    onOk: (_event: Event) => { feedback.value = '已确认保存'; },
+    onCancel: (_event: Event) => { feedback.value = '用户已取消'; } });
+}
+function close() { handle?.close(); feedback.value = '已主动关闭'; }
+onBeforeUnmount(() => handle?.close());
+</script>
+<template>
+  <Button @click="ask">请求确认</Button>
+  <Button @click="close">主动关闭</Button>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Notification
+
+[组件文档与 live demo](https://x-next.ztes.com/components/notification)。`Notification(options)` 或 `.success()` 等显示通知。服务默认 `type='info'`、`duration=3000` 毫秒、`position='top-right'`、`offset=20`、`showClose=true`；四角位置可选，`duration=0` 持续显示。
+
+`title` 和 `message` / `content` 是内容，`footer` / `icon` 可用 VNode 或渲染函数。返回句柄只有 `close()`；同一容器与位置下复用 `id` 更新。`onClick()` 无参数，`onClose(id?)` 接收标识；`.remove(id)` / `.clear(position?)` 是服务级方法。
+
+```vue
+<script setup lang="ts">
+import { onBeforeUnmount, ref } from 'vue';
+import { Button, Notification } from 'x-next';
+import 'x-next/dist/style.css';
+const feedback = ref('尚未显示通知');
+let handle: ReturnType<typeof Notification> | undefined;
+function show() {
+  handle?.close();
+  handle = Notification({ title: '任务完成', message: '结果已准备好。', type: 'success', duration: 0,
+    onClick: () => { feedback.value = '已点击通知'; },
+    onClose: () => { feedback.value = '通知已关闭'; } });
+  feedback.value = '通知显示中';
+}
+onBeforeUnmount(() => handle?.close());
+</script>
+<template>
+  <Button @click="show">显示通知</Button>
+  <Button @click="handle?.close()">关闭通知</Button>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Popconfirm
+
+[组件文档与 live demo](https://x-next.ztes.com/components/popconfirm)。普通布尔 `v-model` 控制显示，`defaultVisible=false`、`type='danger'`、`position='top'`、`width=150`，点击默认插槽触发。`content` / `icon` 插槽可自定义确认内容；按钮文字用 `okText` / `cancelText`。
+
+`ok(event)` / `cancel(event)` 返回 `Event`，`change(visible)` 返回布尔值。`onBeforeOk` / `onBeforeCancel` 支持布尔、void 或 Promise，返回 `false` 可阻止关闭；异步钩子可自动等待，普通 `ok` 监听器不会自动阻止关闭。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Popconfirm } from 'x-next';
+import 'x-next/dist/style.css';
+const visible = ref(false);
+const feedback = ref('记录保留中');
+function remove(_event: Event) { feedback.value = '已确认删除'; }
+function cancel(_event: Event) { feedback.value = '已取消删除'; }
+</script>
+<template>
+  <Popconfirm v-model="visible" content="删除这条记录？" ok-text="删除" cancel-text="保留"
+    @ok="remove" @cancel="cancel">
+    <Button status="danger">删除记录</Button>
+  </Popconfirm>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Popover
+
+[组件文档与 live demo](https://x-next.ztes.com/components/popover)。使用 `v-model:popup-visible`；默认 `trigger='click'`、`position='bottom'`、`showArrow=false`、`defaultPopupVisible=false`、`unmountOnClose=true`。默认插槽是触发器，`title` / `content` 插槽放浮层内容。
+
+`popup-visible-change(visible)` 返回布尔值，`show` / `hide` 无参数。点击触发器或外部默认可以关闭；`popupContainer` 和 `renderToBody` 决定宿主，局部主题下按实际挂载位置核对样式。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Popover } from 'x-next';
+import 'x-next/dist/style.css';
+const visible = ref(false);
+const feedback = ref('说明未打开');
+function changed(value: boolean) { feedback.value = value ? '说明已打开' : '说明已关闭'; }
+</script>
+<template>
+  <Popover v-model:popup-visible="visible" title="安排说明" show-arrow @popup-visible-change="changed">
+    <Button>查看说明</Button>
+    <template #content>
+      <p>时间以页面所选值为准。</p>
+      <Button @click="visible = false">关闭说明</Button>
+    </template>
+  </Popover>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Progress
+
+[组件文档与 live demo](https://x-next.ztes.com/components/progress)。`percent` 为 **0 到 1** 的比例，默认 `0`，不是 0 到 100；超出范围会裁剪，非有限值显示为 0。默认 `type='line'`、`showText=true`、`animation=false`，`steps>0` 使用分段模式。
+
+无模型和业务 change 事件，由业务更新 `percent`。`status` 为 normal、success、warning、danger，未设置时达到 1 自动为 success；`text` 插槽提供 `{ percent }`。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Progress } from 'x-next';
+import 'x-next/dist/style.css';
+const percent = ref(0.25);
+function advance() { percent.value = Math.min(1, percent.value + 0.25); }
+</script>
+<template>
+  <div style="max-width: 320px">
+    <Progress :percent="percent">
+      <template #text="scope">已完成 {{ Math.round(scope.percent * 100) }}%</template>
+    </Progress>
+    <Button :disabled="percent >= 1" @click="advance">推进任务</Button>
+  </div>
+</template>
+```
+
+## Dropdown
+
+[组件文档与 live demo](https://x-next.ztes.com/components/dropdown)。使用 `v-model:popup-visible`，默认 `trigger='click'`、`position='bottom'`、`hideOnSelect=true`。根入口导出 `DropdownOption`、`DropdownGroup`、`DropdownSubmenu`；菜单内容放 `content` 插槽，另有 `empty` / `footer` 插槽。
+
+`select(value, event)` 返回 `string | number | Record<string, any> | undefined` 和 `Event`，`popup-visible-change` 返回布尔值。选项支持 `disabled`；字符搜索 typeahead、自定义控件的通用键盘代理及 Tab 自动关闭仍有边界，不能据方向键导航推断这些能力已实现。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Dropdown, DropdownOption } from 'x-next';
+import 'x-next/dist/style.css';
+const visible = ref(false);
+const feedback = ref('尚未选择操作');
+function select(value: unknown, _event: Event) {
+  feedback.value = value === 'copy' ? '已选择复制' : '已选择下载';
+}
+</script>
+<template>
+  <Dropdown v-model:popup-visible="visible" @select="select">
+    <Button>更多操作</Button>
+    <template #content>
+      <DropdownOption value="copy">复制</DropdownOption>
+      <DropdownOption value="download">下载</DropdownOption>
+      <DropdownOption value="archive" disabled>归档暂不可用</DropdownOption>
+    </template>
+  </Dropdown>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Pagination
+
+[组件文档与 live demo](https://x-next.ztes.com/components/pagination)。`total` 必填且表示记录总数。使用 `v-model:current` 和 `v-model:page-size`；默认非受控值为页码 `1`、每页 `10`，`showTotal` / `showPageSize` / `showJumper` 默认关闭，`autoAdjust=true`。
+
+`change(current)` 和 `page-size-change(pageSize)` 各返回一个数字；不会请求数据。页码按总数裁剪，每页条数应为正数。`total` 插槽提供总数，`page-item` 提供页码；改变条数后的业务重新查询需自行实现。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Pagination } from 'x-next';
+import 'x-next/dist/style.css';
+const current = ref(1);
+const pageSize = ref(10);
+const feedback = ref('当前第 1 页');
+function changed(page: number) { feedback.value = `当前第 ${page} 页`; }
+function resized(size: number) { current.value = 1; feedback.value = `每页 ${size} 条，返回第一页`; }
+</script>
+<template>
+  <Pagination v-model:current="current" v-model:page-size="pageSize" :total="95" show-total show-page-size
+    :page-size-options="[10, 20, 50]" @change="changed" @page-size-change="resized" />
+  <p role="status">{{ feedback }}；每页 {{ pageSize }} 条</p>
+</template>
+```
+
+## Steps
+
+[组件文档与 live demo](https://x-next.ztes.com/components/steps)。子组件的公开名称是 `Step`。使用 `v-model:current`，序号从 **1** 开始，`defaultCurrent=1`、`status='process'`、`type='default'`、`direction='horizontal'`；点击切换需开启 `changeable`，默认关闭。
+
+`change(step, event)` 返回步骤号和 `Event`。Step 支持 `title`、`description`、`disabled`、`status`；`node` / `icon` 插槽提供步骤与状态，默认 / `description` 插槽可替换文案。业务完成状态由业务自身维护。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Steps, Step } from 'x-next';
+import 'x-next/dist/style.css';
+const current = ref(1);
+const feedback = ref('正在填写');
+function changed(step: number, _event: Event) { feedback.value = `已切换到第 ${step} 步`; }
+</script>
+<template>
+  <Steps v-model:current="current" changeable @change="changed">
+    <Step title="填写" description="准备安排" />
+    <Step title="核对" description="检查内容" />
+    <Step title="完成" description="提交结果" />
+  </Steps>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Tabs
+
+[组件文档与 live demo](https://x-next.ztes.com/components/tabs)。使用 `v-model:active-key`，类型为 `string | number`；TabPane 用 Vue 的 `key` 标识页签，键类型须与模型一致。默认 `type='line'`、`position='top'`、`trigger='click'`、`lazyLoad=false`、`destroyOnHide=false`。
+
+`change(key)` 返回键值，`tab-click(key, event)` 还返回 `Event`。禁用配置放在 TabPane；TabPane 默认插槽放正文，`title` 插槽自定义标题，Tabs 的 `extra` 放额外内容。可编辑模式的 `add` / `delete` 事件需要业务维护页签数据。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Tabs, TabPane } from 'x-next';
+import 'x-next/dist/style.css';
+const active = ref<string | number>('overview');
+const feedback = ref('当前概览');
+function changed(key: string | number) { feedback.value = `当前页签：${key}`; }
+</script>
+<template>
+  <Tabs v-model:active-key="active" @change="changed">
+    <TabPane key="overview" title="概览">查看当前安排。</TabPane>
+    <TabPane key="history" title="历史">查看已完成记录。</TabPane>
+    <TabPane key="restricted" title="未开放" disabled>此内容暂不可选。</TabPane>
+  </Tabs>
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
+## Empty
+
+[组件文档与 live demo](https://x-next.ztes.com/components/empty)。`description` 未传时使用语言包默认文案，`null` 或 `''` 隐藏描述；`imgSrc` 自定义图片，`image` 插槽优先于图片地址。默认插槽替代描述，可放业务操作按钮。
+
+没有模型或业务事件；刷新、创建等动作由插槽中的业务控件处理。显式提供描述、图片或插槽时采用调用方配置；裸 Empty 才会交由外层 ConfigProvider 的 `empty` 插槽接管。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, Empty } from 'x-next';
+import 'x-next/dist/style.css';
+const refreshed = ref(false);
+function refresh() { refreshed.value = true; }
+</script>
+<template>
+  <Empty>
+    <p>{{ refreshed ? '刷新完成，仍无记录' : '暂无记录' }}</p>
+    <Button @click="refresh">刷新记录</Button>
+  </Empty>
+</template>
+```