x-next 1.8.2 → 1.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/AI_USAGE.md +68 -71
  2. package/CHANGELOG.md +24 -2
  3. package/README.md +34 -12
  4. package/package.json +2 -1
package/AI_USAGE.md CHANGED
@@ -1,11 +1,11 @@
1
- <!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage-recipes.md and script/ai-usage/manifest.js. -->
1
+ <!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage.md and script/ai-usage/manifest.js. -->
2
2
  # x-next AI 使用手册
3
3
 
4
- 适用版本：**x-next@1.8.2**。Vue：`^3.5.0`；Node：`>=20.19.0`。
4
+ 适用版本：**x-next@1.8.3**。Vue：`^3.5.0`；Node：`>=20.19.0`。
5
5
 
6
- 来源指纹（精选示例、映射、版本与公开类型声明）：`c34fe0b5eea3d8bce2e9746c48cb98ee067149bfd006291967c77540d25d9acb`。
6
+ 来源指纹（精选示例、映射、版本与公开类型声明）：`e4afe24538854d4bf7c373777a8eaed10cc5172205980ab5949b469f0ca0b581`。
7
7
 
8
- 先按业务需要选择组件，不要求全部迁移。本手册限定在用户确认的 26 个组件及必要的同族子组件，未覆盖的导出不表示已完成业务验收。
8
+ 本手册覆盖 26 个常用组件与服务；包内还有更多导出可用，只是未在此逐个展开。按业务需要选择即可，不必全部使用。
9
9
 
10
10
  读取入口：`node_modules/x-next/AI_USAGE.md`；可用 `require.resolve('x-next/AI_USAGE.md')` 定位。这个文件名不会自动让所有 AI 工具加载，消费项目应在自己的指令中明确引用。
11
11
 
@@ -13,37 +13,35 @@
13
13
 
14
14
  | 组件/服务 | 公共导出 | 全局标签/形式 | 受控模型 | 详细文档 |
15
15
  | --- | --- | --- | --- | --- |
16
- | Button | `Button` | `<x-button>` | 无 | [组件文档](https://x-next.ztes.com/components/button) |
17
- | Checkbox | `Checkbox` | `<x-checkbox>` | `v-model` | [组件文档](https://x-next.ztes.com/components/checkbox) |
18
- | Radio | `Radio` | `<x-radio>` | `v-model` | [组件文档](https://x-next.ztes.com/components/radio) |
19
- | Select | `Select` | `<x-select>` | `v-model`, `v-model:popup-visible` | [组件文档](https://x-next.ztes.com/components/select) |
20
- | Slider | `Slider` | `<x-slider>` | `v-model` | [组件文档](https://x-next.ztes.com/components/slider) |
21
- | Rate | `Rate` | `<x-rate>` | `v-model` | [组件文档](https://x-next.ztes.com/components/rate) |
22
- | Switch | `Switch` | `<x-switch>` | `v-model` | [组件文档](https://x-next.ztes.com/components/switch) |
23
- | DatePicker | `DatePicker` | `<x-date-picker>` | `v-model`, `v-model:popup-visible` | [组件文档](https://x-next.ztes.com/components/date-picker) |
24
- | TimePicker | `TimePicker` | `<x-time-picker>` | `v-model`, `v-model:popup-visible` | [组件文档](https://x-next.ztes.com/components/time-picker) |
25
- | Alert | `Alert` | `<x-alert>` | `v-model:visible` | [组件文档](https://x-next.ztes.com/components/alert) |
26
- | Dialog | `DialogComponent`, `Dialog` | `<x-dialog>` | `v-model` | [组件文档](https://x-next.ztes.com/components/dialog) |
27
- | Message | `Message`, `MessageComponent` | 命令式服务 | 无 | [组件文档](https://x-next.ztes.com/components/message) |
28
- | MessageBox | `MessageBox` | 命令式服务 | 无 | [组件文档](https://x-next.ztes.com/components/message-box) |
29
- | Notification | `Notification`, `NotificationComponent` | 命令式服务 | 无 | [组件文档](https://x-next.ztes.com/components/notification) |
30
- | Popconfirm | `Popconfirm` | `<x-popconfirm>` | `v-model` | [组件文档](https://x-next.ztes.com/components/popconfirm) |
31
- | Popover | `Popover` | `<x-popover>` | `v-model:popup-visible` | [组件文档](https://x-next.ztes.com/components/popover) |
32
- | Progress | `Progress` | `<x-progress>` | 无 | [组件文档](https://x-next.ztes.com/components/progress) |
33
- | Dropdown | `Dropdown` | `<x-dropdown>` | `v-model:popup-visible` | [组件文档](https://x-next.ztes.com/components/dropdown) |
34
- | Pagination | `Pagination` | `<x-pagination>` | `v-model:current`, `v-model:page-size` | [组件文档](https://x-next.ztes.com/components/pagination) |
35
- | Steps | `Steps` | `<x-steps>` | `v-model:current` | [组件文档](https://x-next.ztes.com/components/steps) |
36
- | Tabs | `Tabs` | `<x-tabs>` | `v-model:active-key` | [组件文档](https://x-next.ztes.com/components/tabs) |
37
- | Empty | `Empty` | `<x-empty>` | 无 | [组件文档](https://x-next.ztes.com/components/empty) |
38
- | Upload | `Upload` | `<x-upload>` | `v-model:file-list` | [组件文档](https://x-next.ztes.com/components/upload) |
39
- | BarChart | `BarChart` | `<x-bar-chart>` | 无 | [组件文档](https://x-next.ztes.com/components/bar-chart) |
40
- | LineChart | `LineChart` | `<x-line-chart>` | 无 | [组件文档](https://x-next.ztes.com/components/line-chart) |
41
- | PieChart | `PieChart` | `<x-pie-chart>` | 无 | [组件文档](https://x-next.ztes.com/components/pie-chart) |
42
- 这是一份给业务开发者和 AI Coding 使用的中文代码手册。以下 26 个入口是本手册选定的常用组件与服务；公开导出还有其他能力，不能据此推断所有导出都具有相同成熟度，也不要求每个项目全部使用。
43
-
44
- 每节提供一个可复制到 `App.vue` 的独立 Vue SFC，显式从 `x-next` 根入口导入，并包含全量 CSS。实际项目可将重复的 CSS 导入统一移到应用入口。本文是代码配方，不新增 live demo；每节链接的既有组件文档提供可交互示例和完整 API。
45
-
46
- 根目录生成的 `AI_USAGE.md` 随 npm 包分发，可将它提供给 AI 作为消费方用法上下文。编写页面时先选相应配方，再按链接核对所需能力，避免套用其他组件库的属性名。
16
+ | Button | `Button` | `<x-button>` | 无 | [组件文档](https://x-next.yjmf.com/components/button) |
17
+ | Checkbox | `Checkbox` | `<x-checkbox>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/checkbox) |
18
+ | Radio | `Radio` | `<x-radio>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/radio) |
19
+ | Select | `Select` | `<x-select>` | `v-model`, `v-model:popup-visible` | [组件文档](https://x-next.yjmf.com/components/select) |
20
+ | Slider | `Slider` | `<x-slider>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/slider) |
21
+ | Rate | `Rate` | `<x-rate>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/rate) |
22
+ | Switch | `Switch` | `<x-switch>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/switch) |
23
+ | DatePicker | `DatePicker` | `<x-date-picker>` | `v-model`, `v-model:popup-visible` | [组件文档](https://x-next.yjmf.com/components/date-picker) |
24
+ | TimePicker | `TimePicker` | `<x-time-picker>` | `v-model`, `v-model:popup-visible` | [组件文档](https://x-next.yjmf.com/components/time-picker) |
25
+ | Alert | `Alert` | `<x-alert>` | `v-model:visible` | [组件文档](https://x-next.yjmf.com/components/alert) |
26
+ | Dialog | `DialogComponent`, `Dialog` | `<x-dialog>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/dialog) |
27
+ | Message | `Message`, `MessageComponent` | 命令式服务 | 无 | [组件文档](https://x-next.yjmf.com/components/message) |
28
+ | MessageBox | `MessageBox` | 命令式服务 | 无 | [组件文档](https://x-next.yjmf.com/components/message-box) |
29
+ | Notification | `Notification`, `NotificationComponent` | 命令式服务 | 无 | [组件文档](https://x-next.yjmf.com/components/notification) |
30
+ | Popconfirm | `Popconfirm` | `<x-popconfirm>` | `v-model` | [组件文档](https://x-next.yjmf.com/components/popconfirm) |
31
+ | Popover | `Popover` | `<x-popover>` | `v-model:popup-visible` | [组件文档](https://x-next.yjmf.com/components/popover) |
32
+ | Progress | `Progress` | `<x-progress>` | 无 | [组件文档](https://x-next.yjmf.com/components/progress) |
33
+ | Dropdown | `Dropdown` | `<x-dropdown>` | `v-model:popup-visible` | [组件文档](https://x-next.yjmf.com/components/dropdown) |
34
+ | Pagination | `Pagination` | `<x-pagination>` | `v-model:current`, `v-model:page-size` | [组件文档](https://x-next.yjmf.com/components/pagination) |
35
+ | Steps | `Steps` | `<x-steps>` | `v-model:current` | [组件文档](https://x-next.yjmf.com/components/steps) |
36
+ | Tabs | `Tabs` | `<x-tabs>` | `v-model:active-key` | [组件文档](https://x-next.yjmf.com/components/tabs) |
37
+ | Empty | `Empty` | `<x-empty>` | 无 | [组件文档](https://x-next.yjmf.com/components/empty) |
38
+ | Upload | `Upload` | `<x-upload>` | `v-model:file-list` | [组件文档](https://x-next.yjmf.com/components/upload) |
39
+ | BarChart | `BarChart` | `<x-bar-chart>` | 无 | [组件文档](https://x-next.yjmf.com/components/bar-chart) |
40
+ | LineChart | `LineChart` | `<x-line-chart>` | 无 | [组件文档](https://x-next.yjmf.com/components/line-chart) |
41
+ | PieChart | `PieChart` | `<x-pie-chart>` | 无 | [组件文档](https://x-next.yjmf.com/components/pie-chart) |
42
+ 本页为每个组件提供一段可直接复制的 Vue SFC，从 `x-next` 根入口导入。把这些示例交给 AI 编程助手作为上下文，它生成的代码就会使用真实的 props 与事件，而不是照搬其他组件库的属性名。
43
+
44
+ 每节开头链接到对应的组件文档，那里有可交互的在线示例和完整 API 表；本页代码聚焦用法要点。随包分发的 `node_modules/x-next/AI_USAGE.md` 是本页的完整版本，可直接提供给 AI 工具读取。
47
45
 
48
46
  ## 安装与初始化
49
47
 
@@ -51,7 +49,7 @@
51
49
  npm install x-next
52
50
  ```
53
51
 
54
- 应用需已有 Vue 3、TypeScript 和 Vue SFC 构建支持。在 `main.ts` 全局安装插件；`App.vue` 使用下方任一配方即可。
52
+ 应用需已有 Vue 3、TypeScript 和 Vue SFC 构建支持。在 `main.ts` 全局安装插件：
55
53
 
56
54
  ```ts
57
55
  import { createApp } from 'vue';
@@ -62,21 +60,20 @@ import 'x-next/dist/style.css';
62
60
  createApp(App).use(XNext).mount('#app');
63
61
  ```
64
62
 
65
- `app.use(XNext)` 注册全局组件；下方局部具名导入也可独立使用。根入口的 `Dialog` 是服务，模板组件入口是 `DialogComponent`；MessageBox 使用服务函数。
63
+ `app.use(XNext)` 注册全部全局组件；下方各节的局部具名导入也可独立使用。根入口的 `Dialog` 是命令式服务，模板组件是 `DialogComponent`；MessageBox 使用服务函数。
66
64
 
67
65
  接入时遵循这些约定：
68
66
 
69
- - **原生属性不是组件 props**：部分公开类型没有列出所有原生 `id/name/aria-*`。配方通过明确的属性对象 `v-bind` 传递已核对可用的原生属性，组件 props 和事件仍直接绑定并接受严格模板检查；不要用属性对象绕过对未知组件 API 的核对。
70
- - **保持受控值稳定**：`v-model` 要初始化为明确的布尔值、字符串、数字或数组。`defaultValue` / `defaultChecked` 用于非受控初始化；将受控值改为 `undefined` 可能切换到内部状态。清空日期、时间时，本手册统一保存 `''`。
71
- - **选择正确的弹层宿主**：Select、DatePicker、TimePicker、Popover、Dropdown 使用 `popupContainer`；Dialog、Message、MessageBox、Notification、Popconfirm 使用 `renderTo`。容器须已挂载，局部容器需留意定位、滚动和裁剪；Teleport 到 `body` 的弹层不继承原局部容器的主题变量。
72
- - **先用公开主题变量**：参考[样式与主题](https://x-next.ztes.com/guide/theme)。暗色容器上的 alias 链会重新声明；更深子容器只改语义变量仍可能继承祖先已解析的 alias。`themeColor` 写入的内联 primary alias 也有覆盖边界，需按主题文档设置相关公开 alias。
73
- - **约束业务全局 CSS**：reset 可用 `:where(...)` 降低优先级，并限定业务作用域；宽泛的原生元素选择器可能覆盖组件样式。自定义内容用插槽和公开属性，不依赖内部结构类名。
74
- - **清理页面创建的服务**：保留句柄，在路由页面卸载时调用 `close()`；KeepAlive 页面可在停用时清理。Dialog / MessageBox 的命令式关闭不触发确认、取消回调，业务取消逻辑需自行调用；Message / Notification 的关闭会触发各自 `onClose`。
75
- - **本地链接要刷新产物**：链接源码仓库时，消费方仍可能读取 `dist`；修改后需重新构建库并刷新消费方依赖缓存。本手册的代码使用包根入口与 `dist/style.css`。
67
+ - **原生属性直接传**：`id`、`name`、`aria-*` 等原生属性不在组件的 props 类型里，需要时用属性对象 `v-bind` 传入；组件 props 和事件照常直接绑定。
68
+ - **保持受控值稳定**：`v-model` 要初始化为明确的布尔值、字符串、数字或数组。非受控初始化用 `defaultValue` / `defaultChecked`；把受控值改成 `undefined` 可能切换到内部状态。清空日期、时间统一保存 `''`。
69
+ - **选择正确的弹层宿主**：Select、DatePicker、TimePicker、Popover、Dropdown 用 `popupContainer`；Dialog、Message、MessageBox、Notification、Popconfirm 用 `renderTo`。容器须已挂载；局部容器要留意定位、滚动和裁剪，Teleport 到 `body` 的弹层不继承原局部容器的主题变量。
70
+ - **优先用公开主题变量**：参考[样式与主题](https://x-next.yjmf.com/guide/theme)。暗色容器上的 alias 链会重新声明；`themeColor` 写入的内联 primary alias 有覆盖边界，按主题文档设置相关公开 alias。
71
+ - **约束业务全局 CSS**：reset 用 `:where(...)` 降低优先级并限定作用域；宽泛的原生元素选择器可能覆盖组件样式。自定义内容用插槽和公开属性，不依赖内部结构类名。
72
+ - **清理页面创建的服务**：保留句柄，在路由页面卸载时调用 `close()`；KeepAlive 页面可在停用时清理。Dialog / MessageBox 的命令式关闭不触发确认、取消回调，业务取消逻辑需自行调用；Message / Notification 的关闭会触发各自的 `onClose`。
76
73
 
77
74
  ## Button
78
75
 
79
- [组件文档与 live demo](https://x-next.ztes.com/components/button)。`type` 默认 `'default'`，视觉主按钮用 `'primary'`；`htmlType` 默认 `'button'`，原生提交用 `'submit'`。独立使用时尺寸回退为 `'medium'`，`disabled` / `loading` 默认关闭。
76
+ [组件文档与 live demo](https://x-next.yjmf.com/components/button)。`type` 默认 `'default'`，视觉主按钮用 `'primary'`；`htmlType` 默认 `'button'`，原生提交用 `'submit'`。独立使用时尺寸回退为 `'medium'`，`disabled` / `loading` 默认关闭。
80
77
 
81
78
  `click` 载荷为 `MouseEvent`，禁用或加载中不会触发。`default`、`prefix`、`suffix`、`icon` 插槽可组合内容；异步业务自行维护 `loading`。
82
79
 
@@ -103,7 +100,7 @@ async function save(_event: MouseEvent) {
103
100
 
104
101
  ## Checkbox
105
102
 
106
- [组件文档与 live demo](https://x-next.ztes.com/components/checkbox)。使用普通 `v-model`；模型支持 `boolean` 或 `(string | number | boolean)[]`，数组模式配合 `value`。`defaultChecked`、`disabled`、`indeterminate` 默认 `false`；半选状态不会替代模型值。
103
+ [组件文档与 live demo](https://x-next.yjmf.com/components/checkbox)。使用普通 `v-model`；模型支持 `boolean` 或 `(string | number | boolean)[]`，数组模式配合 `value`。`defaultChecked`、`disabled`、`indeterminate` 默认 `false`；半选状态不会替代模型值。
107
104
 
108
105
  `change(value, event)` 返回新值和原生 `Event`。默认插槽是文案，`checkbox` 插槽提供 `checked` / `disabled`。`id`、`name`、`required`、`form`、`tabindex`、`autofocus`、`autocomplete` 和 `aria-*` 传给原生复选框。
109
106
 
@@ -129,7 +126,7 @@ function changed(value: boolean | (string | number | boolean)[], event: Event) {
129
126
 
130
127
  ## Radio
131
128
 
132
- [组件文档与 live demo](https://x-next.ztes.com/components/radio)。`Radio` / `RadioGroup` 的模型和选项值支持 `string | number | boolean`，保留值类型；布尔选项写 `:value="true"`。单个 Radio 的 `value` 默认 `true`，组的非受控默认值为 `''`。
129
+ [组件文档与 live demo](https://x-next.yjmf.com/components/radio)。`Radio` / `RadioGroup` 的模型和选项值支持 `string | number | boolean`，保留值类型；布尔选项写 `:value="true"`。单个 Radio 的 `value` 默认 `true`，组的非受控默认值为 `''`。
133
130
 
134
131
  组默认 `type='radio'`、`direction='horizontal'`、`disabled=false`；`change(value, event)` 返回选项值和 `Event`。Radio 默认插槽是文案，组也支持 `options` 和 `label` / `radio` 插槽。
135
132
 
@@ -156,7 +153,7 @@ function changed(value: string | number | boolean, _event: Event) {
156
153
 
157
154
  ## Select
158
155
 
159
- [组件文档与 live demo](https://x-next.ztes.com/components/select)。`v-model` 返回选项的 `value`；单选通常为标量，多选为数组，也支持对象值。`multiple=false`、`allowClear=false`；单选搜索默认关闭，多选默认开启。`options` 使用可变数组，常用字段是 `label`、`value`、`disabled`。
156
+ [组件文档与 live demo](https://x-next.yjmf.com/components/select)。`v-model` 返回选项的 `value`；单选通常为标量，多选为数组，也支持对象值。`multiple=false`、`allowClear=false`；单选搜索默认关闭，多选默认开启。`options` 使用可变数组，常用字段是 `label`、`value`、`disabled`。
160
157
 
161
158
  `change(value)` 返回新值，`clear(event)` 返回 `Event`；单选清空通常为 `''`，多选为 `[]`，已选禁用项可能保留。`v-model:popup-visible` 控制弹层，`option` / `empty` / `header` / `footer` 等插槽见组件文档。
162
159
 
@@ -184,7 +181,7 @@ function changed(value: unknown) {
184
181
 
185
182
  ## Slider
186
183
 
187
- [组件文档与 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`；范围端点按大小排序并按步长归一化。
184
+ [组件文档与 live demo](https://x-next.yjmf.com/components/slider)。普通模型为 `number`，`range` 模式为 `[number, number]`。默认 `min=0`、`max=100`、`step=1`、`range=false`、`disabled=false`、`showTooltip=true`；范围端点按大小排序并按步长归一化。
188
185
 
189
186
  `change(value)` 表示值变化，`change-end(value)` 表示一次拖拽、点击、键盘或输入提交结束，载荷均为 `number | [number, number]`。`marks` 是数值键到文字的映射，`formatTooltip` 可格式化提示。
190
187
 
@@ -210,7 +207,7 @@ function finish(value: number | [number, number]) {
210
207
 
211
208
  ## Rate
212
209
 
213
- [组件文档与 live demo](https://x-next.ztes.com/components/rate)。数值模型默认非受控值为 `0`，`count=5`；`allowHalf`、`allowClear`、`readonly`、`disabled` 默认关闭。启用半星后步长为 `0.5`，值限制在有效数量内；没有 `size` 属性。
210
+ [组件文档与 live demo](https://x-next.yjmf.com/components/rate)。数值模型默认非受控值为 `0`，`count=5`；`allowHalf`、`allowClear`、`readonly`、`disabled` 默认关闭。启用半星后步长为 `0.5`，值限制在有效数量内；没有 `size` 属性。
214
211
 
215
212
  `change(value)` 返回 `number`，`hover-change(value)` 返回 `number | undefined`。`character` 插槽提供 `index`、`value`、`count`、`disabled`；`tooltips` 为提示数组。
216
213
 
@@ -232,7 +229,7 @@ function changed(value: number) { feedback.value = value ? `评分 ${value}` : '
232
229
 
233
230
  ## Switch
234
231
 
235
- [组件文档与 live demo](https://x-next.ztes.com/components/switch)。普通 `v-model` 支持 `boolean | string | number`；`checkedValue=true`、`uncheckedValue=false`、`defaultChecked=false`，默认 `type='circle'`。`disabled` / `loading` 阻止切换。
232
+ [组件文档与 live demo](https://x-next.yjmf.com/components/switch)。普通 `v-model` 支持 `boolean | string | number`；`checkedValue=true`、`uncheckedValue=false`、`defaultChecked=false`，默认 `type='circle'`。`disabled` / `loading` 阻止切换。
236
233
 
237
234
  `change(value, event)` 返回新值和 `Event`；`beforeChange(newValue)` 可返回布尔值或 Promise，`false` 或拒绝阻止切换。`checked` / `unchecked` 插槽及 `checkedText` / `uncheckedText` 显示两态文案，line 类型不显示文案。
238
235
 
@@ -256,7 +253,7 @@ function changed(value: boolean | string | number, _event: Event) {
256
253
 
257
254
  ## DatePicker
258
255
 
259
- [组件文档与 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`。
256
+ [组件文档与 live demo](https://x-next.yjmf.com/components/date-picker)。默认 `type='date'`、`allowClear=true`、`showToday=true`、`showTime=false`、`position='bl'`。`format` 控制显示，`valueFormat` 控制输出；本例使用 `'YYYY-MM-DD'` 字符串。公开 `DatePickerModelValue` 还包含数字、Date、数组和 `undefined`。
260
257
 
261
258
  `change(value, date, dateString)` 为提交值，`select` 是面板选择；后两个参数声明为 `unknown`。清空返回 `undefined`，本例归一化为 `''` 保持受控。支持 `cell` / `extra` / `prefix` / `suffix-icon` 插槽；带时间选择需确认后提交。
262
259
 
@@ -282,7 +279,7 @@ function changed(value: DatePickerModelValue, _date: unknown, _text: unknown) {
282
279
 
283
280
  ## TimePicker
284
281
 
285
- [组件文档与 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`。
282
+ [组件文档与 live demo](https://x-next.yjmf.com/components/time-picker)。默认 `type='time'`、`allowClear=true`、`disableConfirm=false`，默认格式为 `'HH:mm:ss'`。`format` 同时决定显示与输出；`step` 用 `{ hour, minute, second }`，各步长默认 `1`。
286
283
 
287
284
  `change(timeString, time)` 是确认值变化，`select` 是面板选择；字符串载荷为 `string | (string | undefined)[] | undefined`，第二参数为 `unknown`。清空归一化为 `''`；支持 `prefix` / `suffix-icon` / `extra` 插槽及 `disabledHours` 等限制。
288
285
 
@@ -308,7 +305,7 @@ function changed(value: string | (string | undefined)[] | undefined, _time: unkn
308
305
 
309
306
  ## Alert
310
307
 
311
- [组件文档与 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。
308
+ [组件文档与 live demo](https://x-next.yjmf.com/components/alert)。用 `v-model:visible` 控制显示；`defaultVisible=true`、`type='info'`、`showIcon=true`、`closable=false`。常用类型为 info、success、warning、error、normal。
312
309
 
313
310
  `close(event)` 返回 `MouseEvent`，`after-close` 在关闭动画结束后触发且无参数。默认插槽放正文，`title` / `icon` / `action` / `close-element` 插槽可自定义对应内容。
314
311
 
@@ -333,7 +330,7 @@ function restore() { visible.value = true; feedback.value = '提示显示中'; }
333
330
 
334
331
  ## Dialog
335
332
 
336
- [组件文档与 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 长度。
333
+ [组件文档与 live demo](https://x-next.yjmf.com/components/dialog)。从根入口导入 `DialogComponent as XDialog`，普通 `v-model` 为布尔值且默认 `false`。`renderTo='body'`、`mask=true`、`maskToClose=true`、`escToClose=true`、`destroyOnClosed=true`；`width` 支持数字或 CSS 长度。
337
334
 
338
335
  `title`、默认正文、`footer` 是公开插槽，默认不生成业务按钮。`close(action, event?)` 的 action 为 `'cancel' | 'ok'`，`closed` 表示关闭动画结束；直接改模型不会调用业务取消逻辑。根入口服务 `Dialog(options)` 返回 `close()` / `update(options)` 句柄。
339
336
 
@@ -362,7 +359,7 @@ function cancel() { feedback.value = '已取消'; visible.value = false; }
362
359
 
363
360
  ## Message
364
361
 
365
- [组件文档与 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`。
362
+ [组件文档与 live demo](https://x-next.yjmf.com/components/message)。`Message(options)` 或 `.success()` / `.error()` / `.loading()` 等显示提示。默认 `type='info'`、`duration=3000` 毫秒、`position='top'`、`showClose=false`；`duration=0` 持续显示，内容用 `message` 或 `content`。
366
363
 
367
364
  返回句柄只有 `close()`；同一容器和位置下再次传相同 `id` 更新消息，没有句柄 `update()`。`onClose(id?)` 在自动或手动关闭时触发；自定义内容可用 VNode / 渲染函数。页面只清理自己持有的句柄。
368
365
 
@@ -390,7 +387,7 @@ onBeforeUnmount(() => handle?.close());
390
387
 
391
388
  ## MessageBox
392
389
 
393
- [组件文档与 live demo](https://x-next.ztes.com/components/message-box)。调用 `MessageBox(options)`，默认类型为 `'success'`、宽度 `360`、居中、显示遮罩和关闭按钮、点击遮罩不关闭。`title` / `content` 支持文字、VNode 或渲染函数；`footer=false` 隐藏页脚。
390
+ [组件文档与 live demo](https://x-next.yjmf.com/components/message-box)。调用 `MessageBox(options)`，默认类型为 `'success'`、宽度 `360`、居中、显示遮罩和关闭按钮、点击遮罩不关闭。`title` / `content` 支持文字、VNode 或渲染函数；`footer=false` 隐藏页脚。
394
391
 
395
392
  返回 `close()` / `update(options)` 句柄，结果通过 `onOk(event)` / `onCancel(event)` 回调处理。`beforeOnOk` / `beforeOnCancel` 返回 `boolean | Promise<boolean>`，必须返回 `true` 才放行；异步业务放在前置钩子。它不是 Promise，没有 `confirm()`；`.warning(title, content)` 等返回的 `.ok()` / `.cancel()` 用于注册链式回调。
396
393
 
@@ -421,7 +418,7 @@ onBeforeUnmount(() => handle?.close());
421
418
 
422
419
  ## Notification
423
420
 
424
- [组件文档与 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` 持续显示。
421
+ [组件文档与 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` 持续显示。
425
422
 
426
423
  `title` 和 `message` / `content` 是内容，`footer` / `icon` 可用 VNode 或渲染函数。返回句柄只有 `close()`；同一容器与位置下复用 `id` 更新。`onClick()` 无参数，`onClose(id?)` 接收标识；`.remove(id)` / `.clear(position?)` 是服务级方法。
427
424
 
@@ -450,7 +447,7 @@ onBeforeUnmount(() => handle?.close());
450
447
 
451
448
  ## Popconfirm
452
449
 
453
- [组件文档与 live demo](https://x-next.ztes.com/components/popconfirm)。普通布尔 `v-model` 控制显示，`defaultVisible=false`、`type='danger'`、`position='top'`、`width=150`，点击默认插槽触发。`content` / `icon` 插槽可自定义确认内容；按钮文字用 `okText` / `cancelText`。
450
+ [组件文档与 live demo](https://x-next.yjmf.com/components/popconfirm)。普通布尔 `v-model` 控制显示，`defaultVisible=false`、`type='danger'`、`position='top'`、`width=150`，点击默认插槽触发。`content` / `icon` 插槽可自定义确认内容；按钮文字用 `okText` / `cancelText`。
454
451
 
455
452
  `ok(event)` / `cancel(event)` 返回 `Event`，`change(visible)` 返回布尔值。`onBeforeOk` / `onBeforeCancel` 支持布尔、void 或 Promise，返回 `false` 可阻止关闭；异步钩子可自动等待，普通 `ok` 监听器不会自动阻止关闭。
456
453
 
@@ -475,7 +472,7 @@ function cancel(_event: Event) { feedback.value = '已取消删除'; }
475
472
 
476
473
  ## Popover
477
474
 
478
- [组件文档与 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` 插槽放浮层内容。
475
+ [组件文档与 live demo](https://x-next.yjmf.com/components/popover)。使用 `v-model:popup-visible`；默认 `trigger='click'`、`position='bottom'`、`showArrow=false`、`defaultPopupVisible=false`、`unmountOnClose=true`。默认插槽是触发器，`title` / `content` 插槽放浮层内容。
479
476
 
480
477
  `popup-visible-change(visible)` 返回布尔值，`show` / `hide` 无参数。点击触发器或外部默认可以关闭；`popupContainer` 和 `renderToBody` 决定宿主，局部主题下按实际挂载位置核对样式。
481
478
 
@@ -502,7 +499,7 @@ function changed(value: boolean) { feedback.value = value ? '说明已打开' :
502
499
 
503
500
  ## Progress
504
501
 
505
- [组件文档与 live demo](https://x-next.ztes.com/components/progress)。`percent` 为 **0 到 1** 的比例，默认 `0`，不是 0 到 100；超出范围会裁剪，非有限值显示为 0。默认 `type='line'`、`showText=true`、`animation=false`，`steps>0` 使用分段模式。
502
+ [组件文档与 live demo](https://x-next.yjmf.com/components/progress)。`percent` 为 **0 到 1** 的比例，默认 `0`，不是 0 到 100；超出范围会裁剪，非有限值显示为 0。默认 `type='line'`、`showText=true`、`animation=false`，`steps>0` 使用分段模式。
506
503
 
507
504
  无模型和业务 change 事件，由业务更新 `percent`。`status` 为 normal、success、warning、danger，未设置时达到 1 自动为 success；`text` 插槽提供 `{ percent }`。
508
505
 
@@ -526,7 +523,7 @@ function advance() { percent.value = Math.min(1, percent.value + 0.25); }
526
523
 
527
524
  ## Dropdown
528
525
 
529
- [组件文档与 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` 插槽。
526
+ [组件文档与 live demo](https://x-next.yjmf.com/components/dropdown)。使用 `v-model:popup-visible`，默认 `trigger='click'`、`position='bottom'`、`hideOnSelect=true`。根入口导出 `DropdownOption`、`DropdownGroup`、`DropdownSubmenu`；菜单内容放 `content` 插槽，另有 `empty` / `footer` 插槽。
530
527
 
531
528
  `select(value, event)` 返回 `string | number | Record<string, any> | undefined` 和 `Event`，`popup-visible-change` 返回布尔值。选项支持 `disabled`；字符搜索 typeahead、自定义控件的通用键盘代理及 Tab 自动关闭仍有边界，不能据方向键导航推断这些能力已实现。
532
529
 
@@ -556,7 +553,7 @@ function select(value: unknown, _event: Event) {
556
553
 
557
554
  ## Pagination
558
555
 
559
- [组件文档与 live demo](https://x-next.ztes.com/components/pagination)。`total` 必填且表示记录总数。使用 `v-model:current` 和 `v-model:page-size`；默认非受控值为页码 `1`、每页 `10`，`showTotal` / `showPageSize` / `showJumper` 默认关闭，`autoAdjust=true`。
556
+ [组件文档与 live demo](https://x-next.yjmf.com/components/pagination)。`total` 必填且表示记录总数。使用 `v-model:current` 和 `v-model:page-size`；默认非受控值为页码 `1`、每页 `10`，`showTotal` / `showPageSize` / `showJumper` 默认关闭，`autoAdjust=true`。
560
557
 
561
558
  `change(current)` 和 `page-size-change(pageSize)` 各返回一个数字；不会请求数据。页码按总数裁剪，每页条数应为正数。`total` 插槽提供总数，`page-item` 提供页码；改变条数后的业务重新查询需自行实现。
562
559
 
@@ -580,7 +577,7 @@ function resized(size: number) { current.value = 1; feedback.value = `每页 ${s
580
577
 
581
578
  ## Steps
582
579
 
583
- [组件文档与 live demo](https://x-next.ztes.com/components/steps)。子组件的公开名称是 `Step`。使用 `v-model:current`，序号从 **1** 开始，`defaultCurrent=1`、`status='process'`、`type='default'`、`direction='horizontal'`；点击切换需开启 `changeable`，默认关闭。
580
+ [组件文档与 live demo](https://x-next.yjmf.com/components/steps)。子组件的公开名称是 `Step`。使用 `v-model:current`，序号从 **1** 开始，`defaultCurrent=1`、`status='process'`、`type='default'`、`direction='horizontal'`；点击切换需开启 `changeable`，默认关闭。
584
581
 
585
582
  `change(step, event)` 返回步骤号和 `Event`。Step 支持 `title`、`description`、`disabled`、`status`；`node` / `icon` 插槽提供步骤与状态，默认 / `description` 插槽可替换文案。业务完成状态由业务自身维护。
586
583
 
@@ -605,7 +602,7 @@ function changed(step: number, _event: Event) { feedback.value = `已切换到
605
602
 
606
603
  ## Tabs
607
604
 
608
- [组件文档与 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`。
605
+ [组件文档与 live demo](https://x-next.yjmf.com/components/tabs)。使用 `v-model:active-key`，类型为 `string | number`；TabPane 用 Vue 的 `key` 标识页签，键类型须与模型一致。默认 `type='line'`、`position='top'`、`trigger='click'`、`lazyLoad=false`、`destroyOnHide=false`。
609
606
 
610
607
  `change(key)` 返回键值，`tab-click(key, event)` 还返回 `Event`。禁用配置放在 TabPane；TabPane 默认插槽放正文，`title` 插槽自定义标题，Tabs 的 `extra` 放额外内容。可编辑模式的 `add` / `delete` 事件需要业务维护页签数据。
611
608
 
@@ -630,7 +627,7 @@ function changed(key: string | number) { feedback.value = `当前页签：${key}
630
627
 
631
628
  ## Empty
632
629
 
633
- [组件文档与 live demo](https://x-next.ztes.com/components/empty)。`description` 未传时使用语言包默认文案，`null` 或 `''` 隐藏描述；`imgSrc` 自定义图片，`image` 插槽优先于图片地址。默认插槽替代描述，可放业务操作按钮。
630
+ [组件文档与 live demo](https://x-next.yjmf.com/components/empty)。`description` 未传时使用语言包默认文案，`null` 或 `''` 隐藏描述；`imgSrc` 自定义图片，`image` 插槽优先于图片地址。默认插槽替代描述，可放业务操作按钮。
634
631
 
635
632
  没有模型或业务事件；刷新、创建等动作由插槽中的业务控件处理。显式提供描述、图片或插槽时采用调用方配置；裸 Empty 才会交由外层 ConfigProvider 的 `empty` 插槽接管。
636
633
 
@@ -652,7 +649,7 @@ function refresh() { refreshed.value = true; }
652
649
 
653
650
  ## Upload
654
651
 
655
- [组件文档与 live demo](https://x-next.ztes.com/components/upload)。`action` 是上传地址，也可用 `customRequest` 接管请求；两者都没提供时组件不会发起上传。`name` 是 FormData 字段名，默认 `'file'`；`method` 默认 `'post'`，`withCredentials` 默认 `false`。
652
+ [组件文档与 live demo](https://x-next.yjmf.com/components/upload)。`action` 是上传地址，也可用 `customRequest` 接管请求；两者都没提供时组件不会发起上传。`name` 是 FormData 字段名，默认 `'file'`；`method` 默认 `'post'`，`withCredentials` 默认 `false`。
656
653
 
657
654
  **接入已有上传方法的推荐写法**：`customRequest` 返回 Promise 时组件自动接管状态，resolve 即成功（结果写入 `file.response`，可用 `responseUrlKey` 提取 url，字符串支持 `data.url` 嵌套路径）、reject 即失败并出现重试入口，无需手动调用 `onSuccess` / `onError`。axios、flyio、fetch 或任何返回 Promise 的方法都适用。返回值是 fetch `Response` 时组件读取响应体；非 2xx 按失败处理，`error.status` 为状态码。需要进度与取消时，把 option 的 `signal`（取消 / 移除 / 卸载时触发）与 `onProgress`（0 ~ 1）透传给底层请求。返回 `{ abort }` 并手动回调的旧写法仍然支持。
658
655
 
@@ -704,7 +701,7 @@ function beforeUpload(file: File) {
704
701
 
705
702
  ## BarChart
706
703
 
707
- [组件文档与 live demo](https://x-next.ztes.com/components/bar-chart)。按天 / 小时聚合的柱状趋势图：`categories` 是类目轴标签，`series` 是数据系列（`{ name, data, color }`），两者按下标对应。单系列就是普通柱状图；多系列默认并排，加 `stack` 变成堆叠并显示合计。轻量迷你走势用 TrendChart，需要坐标轴与读数用本组件。
704
+ [组件文档与 live demo](https://x-next.yjmf.com/components/bar-chart)。按天 / 小时聚合的柱状趋势图：`categories` 是类目轴标签，`series` 是数据系列（`{ name, data, color }`），两者按下标对应。单系列就是普通柱状图；多系列默认并排，加 `stack` 变成堆叠并显示合计。轻量迷你走势用 TrendChart，需要坐标轴与读数用本组件。
708
705
 
709
706
  数值轴自动取 1/2/5 步长的整洁刻度（所以刻度行数可能少于 `grid.horizontalLinesNumber`）；传 `max` 可锁定上界。`loading` 显示加载遮罩；数据全为 0 时显示空态，可用 `empty` 插槽替换。`null` / 负数按 0 处理且不画柱体。
710
707
 
@@ -742,7 +739,7 @@ function onBarClick(data: { label: string; total: number; value: number | null }
742
739
 
743
740
  ## LineChart
744
741
 
745
- [组件文档与 live demo](https://x-next.ztes.com/components/line-chart)。随时间看趋势就用它：`categories` 是时间轴标签，`series` 是数据系列（`{ name, data, color }`），按下标对应。多系列默认叠放，加 `area` 填充、再加 `stack` 变堆叠面积。按类目比大小用 BarChart，看占比用 PieChart，卡片角落的迷你走势用 TrendChart——完整选择指引见[图表总览](https://x-next.ztes.com/components/charts)。
742
+ [组件文档与 live demo](https://x-next.yjmf.com/components/line-chart)。随时间看趋势就用它：`categories` 是时间轴标签，`series` 是数据系列（`{ name, data, color }`），按下标对应。多系列默认叠放，加 `area` 填充、再加 `stack` 变堆叠面积。按类目比大小用 BarChart，看占比用 PieChart，卡片角落的迷你走势用 TrendChart——完整选择指引见[图表总览](https://x-next.yjmf.com/components/charts)。
746
743
 
747
744
  **缺测要显式表达**：把没有数据的点写成 `null`，默认会在该处**断开**折线（不会画成跌到 0）；确需连线时传 `:connect-nulls="true"`。数值轴对纯正数数据保持 0 基线，出现负值才向下扩展；`min` / `max` 可锁定区间。`smooth` 默认开启，`show-points` 默认 `'auto'`（点数少时常显）。
748
745
 
@@ -779,9 +776,9 @@ function onLineClick(data: { label: string; value: number | null }) {
779
776
 
780
777
  ## PieChart
781
778
 
782
- [组件文档与 live demo](https://x-next.ztes.com/components/pie-chart)。表达占比：`data` 是 `{ name, value }[]`，值按**可见**分片求和换算角度。`innerRadius="62%"` 渲染成环形并在中心显示合计（推荐形态，信息密度更高）；数字形式的 `innerRadius` 按 px。负值、0 与非有限数会被跳过，不计入总量。
779
+ [组件文档与 live demo](https://x-next.yjmf.com/components/pie-chart)。表达占比：`data` 是 `{ name, value }[]`，值按**可见**分片求和换算角度。`innerRadius="62%"` 渲染成环形并在中心显示合计（推荐形态，信息密度更高）；数字形式的 `innerRadius` 按 px。负值、0 与非有限数会被跳过，不计入总量。
783
780
 
784
- **类别要收敛**：饼图超过 7 个分片就难以阅读，先按值排序、把尾部合并成「其他」再传入（本配方给出写法）。需要精确比较大小改用 BarChart，需要看随时间的变化改用 LineChart。
781
+ **类别要收敛**：饼图超过 7 个分片就难以阅读，先按值排序、把尾部合并成「其他」再传入（下面给出写法）。需要精确比较大小改用 BarChart，需要看随时间的变化改用 LineChart。
785
782
 
786
783
  `legend` 开启后图例项展示数值与占比，点击可隐藏分片——剩余分片重新分配角度、中心合计同步更新，并触发 `legendChange`；点击分片触发 `itemClick`。`center` / `tooltip` / `label` / `legend` 插槽可分别自定义。
787
784
 
package/CHANGELOG.md CHANGED
@@ -2,20 +2,42 @@
2
2
 
3
3
  本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
4
4
 
5
+ ## [1.8.3] - 2026-10-05
6
+
7
+ ### 变更
8
+
9
+ - **文档站地址迁移至 `https://x-next.yjmf.com`**：README、`package.json` 的 `homepage`、AI 使用手册中的全部链接同步更新（npm 包页的 Homepage 也指向该地址）。
10
+ - **「AI 使用配方」更名并改写为「AI 使用指南」**：文档路径由 `/guide/ai-usage-recipes` 变为 `/guide/ai-usage`。原页面开头是写给维护者的内部说明（手册覆盖范围、生成流程、验收口径），现改为面向使用者的说明——这份示例是给 AI 编程助手的上下文，怎么用它、和组件文档如何配合。
11
+ - **README 重写**：补齐当前组件清单（含图表分类与 ConfigProvider、Icon、Upload 等此前缺失项）；移除「AI Coding 使用入口」里面向维护者的生成与校验命令说明，改为面向使用者的「AI 辅助开发」小节；安装、主题、指令等示例保持可用。
12
+
13
+ 本版无代码变更，为文档与包元数据修正。
14
+
5
15
  ## [1.8.2] - 2026-10-05
6
16
 
17
+ > 与 1.8.1 内容完全相同。1.8.1 发布时 npm 将其转为暂存（staged）状态并返回 409，
18
+ > 当时无法确认发布结果，故以相同内容提为 1.8.2；随后 1.8.1 的暂存也通过了审批。
19
+ > 两版功能一致，使用 **1.8.2** 即可。
20
+
7
21
  ### 修复
8
22
 
9
- - **Heatmap 行列整体错位（1.6.0 起存在）**：格子的位置由「DOM 顺序 + `grid-auto-flow` 自动填充」共同决定，而渲染顺序（行优先）与数据顺序（列优先）不一致，导致整块热力图错排——视觉上「一列」是 7 个连续周的同一天，而不是同一周的 7 天；月份标签与格子内容、悬浮提示与实际位置全部对不上（表现为「点 7 月的位置，提示显示 9-30」）。
23
+ - **Heatmap 行列整体错位（1.6.0 起存在）**：格子的位置由「DOM 顺序 + `grid-auto-flow` 自动填充」共同决定，而渲染顺序（行优先）与数据顺序（列优先）不一致，导致整块热力图错排——视觉上「一列」是 7 个连续周的同一天，而不是同一周的 7 天；月份标签、格子内容与悬浮提示三者全部对不上（表现为「点 7 月的位置，提示显示 9-30」）。
10
24
  现改为**显式 `grid-row` / `grid-column` 定位**：位置只由格子的行列号决定，DOM 顺序不再参与布局，与悬浮提示、键盘导航使用的语义坐标天然一致。
11
25
  - 移除网格上已无意义的 `grid-auto-flow`（自动填充顺序是本次错位的成因之一）。
12
26
  - 新增防转置回归测试：断言同一列日期连续（同周）、同一行日期相隔 7 天（同星期几），以及格子的 grid 定位与行列号一致。
13
27
 
28
+ ## [1.8.1] - 2026-10-05
29
+
30
+ > 与 1.8.2 为同一修复的两个发布号，内容完全一致。
31
+
32
+ ### 修复
33
+
34
+ - Heatmap 行列整体错位修复，详见 1.8.2。
35
+
14
36
  ## [1.8.0] - 2026-10-05
15
37
 
16
38
  ### 新增
17
39
 
18
- - **图表族：BarChart 柱状趋势图 / LineChart 折线图 / PieChart 饼图**，与既有 TrendChart、Heatmap 组成完整的基础图表集，文档站新增「图表」分类与[图表总览](https://x-next.ztes.com/components/charts)（含「怎么选」指引）。
40
+ - **图表族：BarChart 柱状趋势图 / LineChart 折线图 / PieChart 饼图**，与既有 TrendChart、Heatmap 组成完整的基础图表集，文档站新增「图表」分类与[图表总览](https://x-next.yjmf.com/components/charts)（含「怎么选」指引）。
19
41
  - **BarChart**：单系列柱状、多系列并排 / 堆叠；数值轴按 1/2/5 取整洁刻度，`max` 可锁定上界；`legend` 点击隐藏系列并重算轴；`bar` / `tooltip` / `legend` / `empty` 插槽。
20
42
  - **LineChart**：多系列、面积、堆叠面积、平滑曲线；`null` 缺测**默认断线**（不画成跌到 0），`connectNulls` 可跨过；纯正数保持 0 基线，出现负值才扩展负向刻度；`min` / `max` 锁域；`point` 插槽自定义数据点。
21
43
  - **PieChart**：饼图 / 环形一体（`innerRadius` 支持 px 与百分比）；环形中心默认显示合计，`center` 插槽可自定义；`legend` 展示「数值·占比」并可点击隐藏分片，剩余分片重新分配角度；小于 4% 的分片不画外围标签。
package/README.md CHANGED
@@ -2,24 +2,16 @@
2
2
 
3
3
  一套面向 Vue 3 + TypeScript 的企业级 UI 组件库。
4
4
 
5
- X-Next 提供常用基础组件、表单组件、反馈组件、导航组件和数据展示组件，适合中后台系统、业务平台和内部工具使用。
5
+ X-Next 提供通用、布局、表单、反馈、导航、数据展示与图表等常用组件，适合中后台系统、业务平台和内部工具使用。内置图表为手写 SVG 实现，不依赖外部图表库；主题变量、暗色模式与无障碍约定在各组件间保持一致。
6
6
 
7
7
  ## 文档
8
8
 
9
9
  完整文档、组件示例和 API 说明请访问：
10
10
 
11
11
  ```text
12
- https://x-next.ztes.com
12
+ https://x-next.yjmf.com
13
13
  ```
14
14
 
15
- ## AI Coding 使用入口
16
-
17
- 消费项目优先阅读随包发布的 [AI_USAGE.md](./AI_USAGE.md)，包含当前版本、22 个选定组件/服务的真实模型与事件、可复制 Vue SFC、命令式服务及接入限制。
18
-
19
- 安装后文件位于 `node_modules/x-next/AI_USAGE.md`；也可以用 `require.resolve('x-next/AI_USAGE.md')` 定位。建议在消费项目的 AI 指令中明确写出这个入口，文件名本身不会让所有工具自动加载。
20
-
21
- 维护者修改 [示例源文档](./src/docs/guide/ai-usage-recipes.md) 后执行 `pnpm build && pnpm generate:ai-usage`。`pnpm check:ai-usage` 会检查版本/来源是否过期，并用严格 Vue TypeScript 模板校验所有示例；`pnpm test:ai-usage` 验证错误示例和过期结果确实被拒绝。打包时也会运行手册检查。
22
-
23
15
  ## 安装
24
16
 
25
17
  ```bash
@@ -127,6 +119,10 @@ X-Next 基于 CSS Variables 提供运行时主题能力。你可以在全局或
127
119
 
128
120
  ### 通用
129
121
 
122
+ - ConfigProvider 全局配置
123
+ - Icon 图标
124
+ - Finicon 金融图标
125
+ - Boxicons 图标
130
126
  - Button 按钮
131
127
  - Link 链接
132
128
  - Tag 标签
@@ -151,6 +147,7 @@ X-Next 基于 CSS Variables 提供运行时主题能力。你可以在全局或
151
147
  - Select 选择器
152
148
  - Slider 滑块
153
149
  - Rate 评分
150
+ - ColorPicker 颜色选择器
154
151
  - Switch 开关
155
152
  - DatePicker 日期选择器
156
153
  - TimePicker 时间选择器
@@ -184,16 +181,31 @@ X-Next 基于 CSS Variables 提供运行时主题能力。你可以在全局或
184
181
  - Image 图片
185
182
  - Table 表格
186
183
  - Timeline 时间线
187
- - TrendChart 趋势图
184
+ - Upload 上传
185
+
186
+ ### 图表
187
+
188
+ 内置手写 SVG 图表，不依赖外部图表库；选择指引见[图表总览](https://x-next.yjmf.com/components/charts)。
189
+
190
+ - LineChart 折线图
191
+ - BarChart 柱状趋势图
192
+ - PieChart 饼图
193
+ - TrendChart 迷你趋势图
194
+ - Heatmap 热力图
188
195
 
189
196
  ### 其他能力
190
197
 
191
198
  - Draggable 拖拽
192
199
  - Network 网络状态
193
200
  - Tooltip 文字提示
194
- - Trigger 触发器
195
201
  - Watermark 水印
196
202
 
203
+ ### 底层能力
204
+
205
+ 主要供组件库内部和高级封装使用，业务优先选择上方语义组件。
206
+
207
+ - Trigger 触发器
208
+
197
209
  ## 命令式组件
198
210
 
199
211
  ```ts
@@ -219,6 +231,16 @@ import {
219
231
  } from 'x-next';
220
232
  ```
221
233
 
234
+ ## AI 辅助开发
235
+
236
+ 包内附带 `AI_USAGE.md`，包含常用组件的真实 props、事件与可直接复制的 Vue 示例，可作为 AI 编程助手的上下文：
237
+
238
+ ```text
239
+ node_modules/x-next/AI_USAGE.md
240
+ ```
241
+
242
+ 可用 `require.resolve('x-next/AI_USAGE.md')` 定位该文件。建议在项目自己的 AI 指令里写明这个路径——文件名本身不会让工具自动加载。文档站的 [AI 使用指南](https://x-next.yjmf.com/guide/ai-usage) 是同一份内容。
243
+
222
244
  ## 类型提示
223
245
 
224
246
  X-Next 提供 TypeScript 类型声明和 Vue 全局组件类型声明。安装后可直接在 Vue 3 + TypeScript 项目中获得组件类型提示。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "x-next",
3
- "version": "1.8.2",
3
+ "version": "1.8.3",
4
4
  "private": false,
5
5
  "description": "A Vue 3 and TypeScript component library for enterprise applications.",
6
6
  "keywords": [
@@ -8,6 +8,7 @@
8
8
  "vue 3",
9
9
  "component"
10
10
  ],
11
+ "homepage": "https://x-next.yjmf.com/",
11
12
  "bugs": {
12
13
  "url": "https://github.com/ztes/x-next/issues"
13
14
  },