x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/notification.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Notification AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Notification, NotificationComponent`；模型：无；已核对事件：未在精选映射登记事件；其他 API 见下方用法。
+先读 [通用接入](../core.md)。公开导出：`Notification, NotificationComponent`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./notification-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/notification`（包含 base.css、notification.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/notification)。`Notification(options)` 或 `.success()` 等显示通知。服务默认 `type='info'`、`duration=3000` 毫秒、`position='top-right'`、`offset=20`、`showClose=true`；四角位置可选，`duration=0` 持续显示。
 
 根入口 `NotificationComponent` 是模板组件，默认 `offset=0`，与命令式服务不同；模板组件和服务选项按各自公开类型使用。
@@ -36,4 +38,274 @@ onBeforeUnmount(() => handle?.close());
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/notification.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./notification-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于在页面角落展示较完整的通知内容，通常由命令式方法触发。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Button } from 'x-next';
+import { Notification } from 'x-next';
+
+const showBasicNotification = () => {
+  Notification.success({
+    title: '处理完成',
+    message: '后台任务已成功处理',
+  });
+};
+
+const showCloseableNotification = () => {
+  Notification.info({
+    title: '常驻通知',
+    message: 'duration=0 时不会自动关闭',
+    duration: 0,
+    showClose: true,
+  });
+};
+</script>
+<template>
+<Space>
+    <Button type="primary" @click="showBasicNotification">显示通知</Button>
+    <Button @click="showCloseableNotification">常驻通知</Button>
+  </Space>
+</template>
+```
+
+### 通知类型
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+import { Notification } from 'x-next';
+type NotificationType = 'success' | 'info' | 'warning' | 'error' | 'strong';
+
+const showTypedNotification = (type: NotificationType) => {
+  Notification[type]({
+    title: `${type} 通知`,
+    message: '不同类型会使用不同的状态图标和强调色',
+  });
+};
+</script>
+<template>
+<div class="demo-inline-group">
+    <Button @click="showTypedNotification('info')">Info</Button>
+    <Button status="success" @click="showTypedNotification('success')">Success</Button>
+    <Button status="warning" @click="showTypedNotification('warning')">Warning</Button>
+    <Button status="strong" @click="showTypedNotification('strong')">Strong</Button>
+    <Button status="danger" @click="showTypedNotification('error')">Error</Button>
+  </div>
+</template>
+```
+
+### 位置
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+import { Notification } from 'x-next';
+type NotificationPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+const showPositionNotification = (position: NotificationPosition) => {
+  Notification.info({
+    title: position,
+    message: '通知会从对应角落弹出',
+    position,
+  });
+};
+</script>
+<template>
+<div class="demo-inline-group">
+    <Button @click="showPositionNotification('top-right')">右上角</Button>
+    <Button @click="showPositionNotification('top-left')">左上角</Button>
+    <Button @click="showPositionNotification('bottom-right')">右下角</Button>
+    <Button @click="showPositionNotification('bottom-left')">左下角</Button>
+  </div>
+</template>
+```
+
+### 手动关闭和清空
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Button } from 'x-next';
+import { Notification } from 'x-next';
+
+const showManualCloseNotification = () => {
+  const handler = Notification.warning({
+    title: '手动关闭',
+    message: '这条通知会在 2 秒后关闭',
+    duration: 0,
+  });
+  window.setTimeout(() => handler.close(), 2000);
+};
+
+const clearNotifications = () => Notification.clear();
+</script>
+<template>
+<Space>
+    <Button type="primary" @click="showManualCloseNotification">2 秒后关闭</Button>
+    <Button @click="clearNotifications">清空通知</Button>
+  </Space>
+</template>
+```
+
+### 更新通知
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Button } from 'x-next';
+import { ref } from 'vue';
+import { Notification } from 'x-next';
+
+const progress = ref(1);
+
+const showUpdatedNotification = () => {
+  Notification.info({
+    id: 'notification-update-demo',
+    title: '任务进度',
+    message: `当前进度 ${progress.value++}`,
+    duration: 3000,
+  });
+};
+
+const removeUpdatedNotification = () => {
+  Notification.remove('notification-update-demo');
+};
+</script>
+<template>
+<Space>
+    <Button @click="showUpdatedNotification">更新同一条</Button>
+    <Button @click="removeUpdatedNotification">移除指定通知</Button>
+  </Space>
+</template>
+```
+
+### 自定义内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Button } from 'x-next';
+import { h } from 'vue';
+import { Notification } from 'x-next';
+
+const showCustomIconNotification = () => {
+  Notification.info({
+    title: '自定义图标',
+    message: '可以传入 icon 渲染函数',
+    icon: () => h('span', { class: 'notification-custom-icon' }, '★'),
+  });
+};
+
+const showFooterNotification = () => {
+  const handler = Notification.warning({
+    title: '需要处理',
+    message: '通知底部可以承载业务操作',
+    duration: 0,
+    footer: () =>
+      h('div', { style: 'display:flex;gap:8px;justify-content:flex-end;' }, [
+        h('button', { onClick: () => handler.close() }, '稍后'),
+        h('button', { onClick: () => handler.close() }, '处理'),
+      ]),
+  });
+};
+</script>
+<template>
+<Space>
+    <Button @click="showCustomIconNotification">自定义图标</Button>
+    <Button @click="showFooterNotification">底部操作</Button>
+  </Space>
+</template>
+```
+
+### 局部容器
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+import { Notification } from 'x-next';
+
+const showLocalNotification = () => {
+  Notification.success({
+    title: '局部通知',
+    message: '通知挂载到指定容器内',
+    renderTo: '#notification-local-container',
+    position: 'top-right',
+    duration: 4000,
+  });
+};
+</script>
+<template>
+<Button @click="showLocalNotification">显示到局部容器</Button>
+  <div id="notification-local-container" class="notification-local-container"></div>
+</template>
+```
+
+### 组件形态与原生属性
+
+组件形态的 id、data-*、ARIA 和原生鼠标事件落到通知根节点；class/style 与结构样式合并。默认 role 为 alert，可以按业务语义设置为 status。点击关闭按钮会派发 close，需要父级决定移除节点。
+
+命令式 `Notification(options)` 只接受下表列出的选项，不会自动接收任意原生属性。局部 ConfigProvider 的注入也不会自动传入独立创建的命令式实例；需要局部主题时使用组件形态，或指定实际位于主题边界内的 renderTo 容器。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button } from 'x-next';
+import { ref } from 'vue';
+import { NotificationComponent } from 'x-next';
+const visible = ref(true);
+const count = ref(0);
+const nativeEvents = { mouseenter: () => { count.value++; } };
+import type { HTMLAttributes } from 'vue';
+const nativeAttrs1 = { "id": "inline-note", "data-testid": "note", "role": "status", "aria-label": "任务进度通知" } satisfies HTMLAttributes & { "data-testid"?: string };
+</script>
+<template>
+<Button @click="visible = true">恢复组件通知</Button>
+  <NotificationComponent v-bind="nativeAttrs1" v-if="visible"
+      message="移动鼠标到通知上查看回调"
+    :duration="0" v-on="nativeEvents" @close="visible = false" />
+  <p role="status">鼠标进入 {{ count }} 次；通知{{ visible ? '显示' : '已关闭' }}</p>
+</template>
+```
+
+### NotificationOptions
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| `id` | 通知唯一标识，相同 id 会更新已有通知 | `string \| number` | `-` |
+| `title` | 通知标题 | `NotificationContent` | `-` |
+| `message` | 通知内容 | `NotificationContent` | `-` |
+| `content` | `message` 的别名 | `NotificationContent` | `-` |
+| `type` | 通知类型 | `'success' \| 'strong' \| 'warning' \| 'error' \| 'info'` | `'info'` |
+| `duration` | 自动关闭时间，单位毫秒，`0` 表示不自动关闭 | `number` | `3000` |
+| `position` | 通知弹出位置 | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'top-right'` |
+| `offset` | 与容器边缘的初始偏移 | `number` | `20` |
+| `renderTo` | 挂载容器，找不到时回退到 body | `string \| HTMLElement` | `'body'` |
+| `showClose` | 是否显示关闭按钮 | `boolean` | `true` |
+| `closable` | `showClose` 的别名 | `boolean` | `true` |
+| `showIcon` | 是否显示图标 | `boolean` | `true` |
+| `icon` | 自定义图标 | `RenderFunction \| VNode` | `-` |
+| `footer` | 自定义底部 | `RenderFunction \| VNode` | `-` |
+| `closeIcon` | 自定义关闭图标 | `RenderFunction \| VNode` | `-` |
+| `popupClass` | 自定义类名 | `string` | `-` |
+| `class` | 自定义类名 | `string` | `-` |
+| `style` | 自定义样式 | `CSSProperties` | `-` |
+| `onClick` | 点击通知回调 | `() => void` | `-` |
+| `onClose` | 关闭回调 | `(id?: string \| number) => void` | `-` |
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./notification-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/pagination-api.md

@@ -0,0 +1,62 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Pagination 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Pagination API
+
+公开声明：`dist/components/pagination/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| total | 数据总数 | number | 是 | 未声明 |
+| current | 当前页码 | undefined &#124; number | 否 | 未声明 |
+| defaultCurrent | 默认页码，非受控模式 | undefined &#124; number | 否 | 1 |
+| pageSize | 每页条数 | undefined &#124; number | 否 | 未声明 |
+| defaultPageSize | 默认每页条数，非受控模式 | undefined &#124; number | 否 | 10 |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| hideOnSinglePage | 单页时是否隐藏 | undefined &#124; false &#124; true | 否 | false |
+| simple | 是否为简单模式 | undefined &#124; false &#124; true | 否 | false |
+| showTotal | 是否显示总数 | undefined &#124; false &#124; true | 否 | false |
+| showMore | 是否显示更多按钮 | undefined &#124; false &#124; true | 否 | false |
+| showJumper | 是否显示跳转输入 | undefined &#124; false &#124; true | 否 | false |
+| showPageSize | 是否显示每页条数选择器 | undefined &#124; false &#124; true | 否 | false |
+| pageSizeOptions | 正安全整数条数选项，过滤非法值并去重排序；并入当前值 | undefined &#124; number[] | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| pageSizeProps | Select 附加配置，受分页维护的字段见使用说明 | undefined &#124; SelectProps | 否 | 未声明 |
+| size | 分页尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| pageItemStyle | 页码、步进和省略按钮的共有样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+| activePageItemStyle | 当前页码覆盖共有样式的部分 | undefined &#124; CSSProperties | 否 | 未声明 |
+| baseSize | 折叠阈值的基础数，取整限制在 1–100 | undefined &#124; number | 否 | 6 |
+| bufferSize | 当前页左右页码个数，取整限制在 0–100 | undefined &#124; number | 否 | 2 |
+| autoAdjust | 改变每页条数或总页数时是否自动调整页码 | undefined &#124; false &#124; true | 否 | true |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:current | 当前页码变化时触发 | undefined &#124; (current: number) => any |
+| update:pageSize | 每页条数变化时触发 | undefined &#124; (pageSize: number) => any |
+| change | 页码改变时触发 | undefined &#124; (current: number) => any |
+| pageSizeChange | 每页条数改变时触发 | undefined &#124; (pageSize: number) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| page-item | 自定义页码按钮 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| page-item-step | 自定义上一页/下一页按钮 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| page-item-ellipsis | 自定义省略按钮 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| total | 自定义总数内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| jumper-prepend | 普通模式跳转输入前置内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| jumper-append | 普通模式跳转输入后置内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [Pagination 用法](./pagination.md)。