x-next 1.18.1 → 1.19.0

package/README.md

@@ -1,269 +1,165 @@
-# X-Next
-
-一套面向 Vue 3 + TypeScript 的企业级 UI 组件库。
-
-X-Next 提供通用、布局、表单、反馈、导航、数据展示与图表等常用组件，适合中后台系统、业务平台和内部工具使用。内置图表为手写 SVG 实现，不依赖外部图表库；主题变量、暗色模式与无障碍约定在各组件间保持一致。
-
-## 文档
-
-完整文档、组件示例和 API 说明请访问：
-
-```text
-https://x-next.yjmf.com
-```
+<p align="center">
+  <a href="https://x-next.yjmf.com">
+    <img src="https://x-next.yjmf.com/logo.svg" width="88" height="88" alt="X-Next Logo" />
+  </a>
+</p>
+
+<h1 align="center">X-Next</h1>
+
+<p align="center"><strong>把想法，变成界面。</strong></p>
+
+<p align="center">面向企业级应用的 Vue 3 组件库，讲究视觉、交互与开发体验。</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/x-next">
+    <img src="https://img.shields.io/npm/v/x-next?color=1c61ff" alt="npm version" />
+  </a>
+  <a href="https://vuejs.org">
+    <img src="https://img.shields.io/badge/Vue-3.5%2B-42b883?logo=vuedotjs&amp;logoColor=white" alt="Vue 3.5+" />
+  </a>
+  <a href="./LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-1c61ff" alt="MIT License" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://x-next.yjmf.com"><strong>官方文档</strong></a> ·
+  <a href="https://x-next.yjmf.com/guide/getting-started">快速开始</a> ·
+  <a href="https://x-next.yjmf.com/components/">浏览组件</a> ·
+  <a href="./CHANGELOG.md">更新日志</a>
+</p>
+
+---
+
+X-Next 基于 Vue 3 与 TypeScript 构建，为中后台系统、业务平台与数据看板提供统一的界面基础。从表单录入、数据展示到交互反馈与图表，让团队专注于业务，也让应用保持一致的视觉与使用体验。
+
+## 特性
+
+- **覆盖业务常用场景** — 提供表单、表格、树选择、数据穿梭、日期时间、上传与反馈等组件，支持组合构建复杂界面。
+- **统一的视觉语言** — 通过颜色、尺寸、间距与状态规范，保持组件之间的设计一致性。
+- **灵活的主题能力** — 基于 CSS Variables，支持品牌色定制、亮暗主题与局部主题配置。
+- **TypeScript 支持** — 提供组件、事件与服务的类型声明，以及 Vue 模板类型提示。
+- **按需加载** — 组件代码与样式均提供按需入口，按项目需要选择引入范围。
+- **面向 AI 辅助开发** — 随包提供独立使用手册、API 约束与完整示例，让 AI 基于当前版本编写代码。
 
 ## 安装
 
+在已有的 Vue 3 项目中安装：
+
 ```bash
 pnpm add x-next
 ```
 
-或使用 npm：
-
 ```bash
 npm install x-next
 ```
 
+需要 Vue **3.5 及以上的 3.x 版本**，支持现代浏览器。
+
 ## 快速开始
 
-### 全量引入
+### 按需引入
 
-```ts
-import { createApp } from 'vue';
-import XNext from 'x-next';
-import 'x-next/dist/style.css';
-import App from './App.vue';
+在 Vue 单文件组件中直接导入所需组件。样式入口会自动包含共享基础样式与组件的内部样式依赖。
 
-const app = createApp(App);
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { Button } from 'x-next';
+  import 'x-next/style/button';
 
-app.use(XNext);
-app.mount('#app');
-```
+  const count = ref(0);
+</script>
 
-```vue
 <template>
-  <x-button type="primary">保存</x-button>
+  <Button type="primary" @click="count++">已点击 {{ count }} 次</Button>
 </template>
 ```
 
-### 按需引入
+### 完整引入
+
+在应用入口注册全部组件，并引入完整样式：
 
 ```ts
 import { createApp } from 'vue';
-import { Button, Table, Message } from 'x-next';
-import 'x-next/dist/style.css';
+import XNext from 'x-next';
+import 'x-next/style.css';
 import App from './App.vue';
 
-const app = createApp(App);
-
-app.use(Button);
-app.use(Table);
-app.mount('#app');
-
-Message.success('保存成功');
+createApp(App).use(XNext).mount('#app');
 ```
 
-### 可选 Finicon 图标集
+注册后，可在模板中使用全局组件：
 
-Finicon 包含大量金融场景 SVG，不会随根入口自动注册。项目需要使用 `finicon:*` 图标时，在应用入口显式注册一次：
-
-```ts
-import { registerFiniconIcons } from 'x-next';
-
-registerFiniconIcons();
+```vue
+<template>
+  <x-button type="primary">开始构建</x-button>
+</template>
 ```
 
-这样未使用 Finicon 的应用可以正常 tree-shaking，不会仅因导入单个基础组件而携带整套金融图标。
+更多接入方式与样式说明见[快速开始](https://x-next.yjmf.com/guide/getting-started)。
 
-## 样式
+## 探索组件
 
-使用组件时需要引入样式文件：
+| 分类 | 常用组件 |
+| --- | --- |
+| 通用 | [Button 按钮](https://x-next.yjmf.com/components/button) · [Link 链接](https://x-next.yjmf.com/components/link) · [Tag 标签](https://x-next.yjmf.com/components/tag) · [Icon 图标](https://x-next.yjmf.com/components/icon) |
+| 布局 | [Layout 布局](https://x-next.yjmf.com/components/layout) · [Grid 栅格](https://x-next.yjmf.com/components/grid) · [Space 间距](https://x-next.yjmf.com/components/space) |
+| 表单 | [Form 表单](https://x-next.yjmf.com/components/form) · [Input 输入框](https://x-next.yjmf.com/components/input) · [Select 选择器](https://x-next.yjmf.com/components/select) · [DatePicker 日期选择器](https://x-next.yjmf.com/components/date-picker) |
+| 复杂选择 | [TreeSelect 树选择器](https://x-next.yjmf.com/components/tree-select) · [Transfer 数据穿梭框](https://x-next.yjmf.com/components/transfer) · [TimeRangeSelector 时间范围选择](https://x-next.yjmf.com/components/time-range-selector) |
+| 数据展示 | [Table 表格](https://x-next.yjmf.com/components/table) · [Image 图片](https://x-next.yjmf.com/components/image) · [Upload 上传](https://x-next.yjmf.com/components/upload) · [Timeline 时间线](https://x-next.yjmf.com/components/timeline) |
+| 导航 | [Menu 菜单](https://x-next.yjmf.com/components/menu) · [Tabs 标签页](https://x-next.yjmf.com/components/tabs) · [Pagination 分页](https://x-next.yjmf.com/components/pagination) · [Steps 步骤条](https://x-next.yjmf.com/components/steps) |
+| 反馈 | [Dialog 对话框](https://x-next.yjmf.com/components/dialog) · [Drawer 抽屉](https://x-next.yjmf.com/components/drawer) · [Message 全局提示](https://x-next.yjmf.com/components/message) · [Notification 通知提醒](https://x-next.yjmf.com/components/notification) |
+| 图表 | [LineChart 折线图](https://x-next.yjmf.com/components/line-chart) · [BarChart 柱状趋势图](https://x-next.yjmf.com/components/bar-chart) · [PieChart 饼图](https://x-next.yjmf.com/components/pie-chart) · [Heatmap 热力图](https://x-next.yjmf.com/components/heatmap) |
 
-```ts
-import 'x-next/dist/style.css';
-```
+查看[全部组件与交互示例](https://x-next.yjmf.com/components/)。内置图表覆盖趋势、比较、占比与热力分布，无需额外安装图表库。
 
 ## 主题定制
 
-X-Next 基于 CSS Variables 提供运行时主题能力。你可以在全局或局部容器中覆盖 `--x-*` 变量。
-
-```css
-:root {
-  --x-color-primary: #0f766e;
-}
-```
-
-局部覆盖示例：
+使用 `ConfigProvider` 配置品牌色、组件尺寸与暗色模式，也可以通过公开的 CSS Variables 调整应用风格。
 
 ```vue
+<script setup lang="ts">
+  import { Button, ConfigProvider } from 'x-next';
+  import 'x-next/style/button';
+</script>
+
 <template>
-  <section class="brand-theme">
-    <x-button type="primary">品牌按钮</x-button>
-    <x-time-range-selector v-model="ranges" />
-  </section>
+  <ConfigProvider theme-color="#0f766e" :dark="true">
+    <Button type="primary">品牌主题</Button>
+  </ConfigProvider>
 </template>
-
-<style scoped>
-.brand-theme {
-  --x-color-primary: #0f766e;
-  --x-button-color-bg-primary-solid: var(--x-color-primary);
-  --x-button-color-border-primary: var(--x-color-primary);
-  --x-time-range-selector-color-default: var(--x-color-primary);
-}
-</style>
 ```
 
-更多主题变量和组件级变量请查看文档站。
-
-## 组件
-
-### 通用
+了解[样式与主题](https://x-next.yjmf.com/guide/theme)，查看全局配置、局部主题与运行时换色示例。
 
-- ConfigProvider 全局配置
-- Icon 图标
-- Finicon 金融图标
-- Boxicons 图标
-- Button 按钮
-- Link 链接
-- Tag 标签
-
-### 布局
-
-- Grid 栅格
-- Layout 布局
-- Space 间距
-- ResizeBox 可调整区域
-- Scrollbar 滚动条
-
-### 表单
-
-- Form 表单
-- Input 输入框
-- Textarea 文本域
-- InputNumber 数字输入
-- InputTag 标签输入
-- Checkbox 复选框
-- Radio 单选框
-- Select 选择器
-- Slider 滑块
-- Rate 评分
-- ColorPicker 颜色选择器
-- Switch 开关
-- DatePicker 日期选择器
-- TimePicker 时间选择器
-- TimeRangeSelector 时间范围选择
-
-### 反馈
-
-- Alert 警告提示
-- Dialog 对话框
-- Drawer 抽屉
-- Message 全局提示
-- MessageBox 消息框
-- Notification 通知提醒
-- Popconfirm 气泡确认
-- Popover 气泡卡片
-- Progress 进度条
-- Spin 加载中
-- Skeleton 骨架屏
-
-### 导航
-
-- Dropdown 下拉菜单
-- Menu 菜单
-- Pagination 分页
-- Steps 步骤条
-- Tabs 标签页
-
-### 数据展示
-
-- Empty 空状态
-- Image 图片
-- Table 表格
-- Timeline 时间线
-- Upload 上传
-
-### 图表
-
-内置手写 SVG 图表，不依赖外部图表库；选择指引见[图表总览](https://x-next.yjmf.com/components/charts)。
-
-- LineChart 折线图
-- BarChart 柱状趋势图
-- PieChart 饼图
-- TrendChart 迷你趋势图
-- Heatmap 热力图
-
-### 其他能力
-
-- Draggable 拖拽
-- Network 网络状态
-- Tooltip 文字提示
-- Watermark 水印
-
-### 底层能力
-
-主要供组件库内部和高级封装使用，业务优先选择上方语义组件。
-
-- Trigger 触发器
+## AI 辅助开发
 
-## 命令式组件
+X-Next 的 npm 包包含与版本配套的 AI 编程资料，覆盖接入规则、组件 API 与可运行的 Vue 示例。
 
-```ts
-import { Message, Notification, Dialog, MessageBox } from 'x-next';
+从 [AI_CODING.md](./AI_CODING.md) 开始，将其中的使用规则合并到业务项目的 Agent 指令中；再读取 [AI_USAGE/index.md](./AI_USAGE/index.md) 与 [core.md](./AI_USAGE/core.md)，按任务查阅所需组件或场景。资料需要由项目规则显式引用。
 
-Message.info('加载完成');
+查看[AI 使用指南](https://x-next.yjmf.com/guide/ai-usage)。
 
-Notification.success({
-  title: '成功',
-  content: '数据已同步',
-});
-```
+## 参与贡献
 
-## 指令和 Hooks
+欢迎反馈使用问题、提出功能建议，以及参与组件开发与文档建设。
 
-```ts
-import {
-  useDraggable,
-  useResizeObserver,
-  vDraggable,
-  vWatermark,
-  type WatermarkOptions,
-} from 'x-next';
-```
+本地开发：
 
-## AI 辅助开发
-
-AI 编程资料独立随包分发，文档站组件说明仍保持完整。推荐先读 `AI_CODING.md` 中的使用流程，并把其中的 x-next 规则合并到业务仓库 `AGENTS.md`；模型不需要预先了解 x-next。
-
-```text
-node_modules/x-next/AI_CODING.md
-node_modules/x-next/AI_USAGE/index.md
-node_modules/x-next/AI_USAGE/core.md
-node_modules/x-next/AI_USAGE/components/select.md
+```bash
+pnpm install
+pnpm docs:dev
 ```
 
-Agent 先读短索引与通用规则，再按任务读取组件/场景文件。组件页包含真实 API 约束、模型、事件、样式及完整 Vue SFC，与严格校验的手册同源；不要把全文或整个目录反复加入上下文。未收录的能力通过 `AI_USAGE/catalog.md` 查公开类型。
+提交前请阅读 [AGENTS.md](./AGENTS.md)，并运行相应检查：
 
-这些文件可用 `require.resolve('x-next/AI_USAGE/index.md')` 等公开路径定位。文件名不会让所有 AI 工具自动加载，业务项目应在自己的指令中明确引用。
-
-完整 `AI_USAGE.md` 继续兼容提供，旧包按章节读取：
-
-```text
-node_modules/x-next/AI_USAGE.md
+```bash
+pnpm build
+pnpm docs:build
+pnpm check
 ```
 
-文档站的 [AI 使用指南](https://x-next.yjmf.com/guide/ai-usage) 保留完整示例内容。
-
-## 类型提示
-
-X-Next 提供 TypeScript 类型声明和 Vue 全局组件类型声明。安装后可直接在 Vue 3 + TypeScript 项目中获得组件类型提示。
-
-如需生成或更新 Volar 全局组件声明，请查看文档站说明。
-
-## 浏览器兼容性
-
-推荐使用现代浏览器环境。主题能力依赖 CSS Variables，部分视觉效果会使用现代 CSS 能力。
-
-## License
+## 开源协议
 
-MIT
+[MIT](./LICENSE)

package/dist/components/form-select/index.d.ts

@@ -86,7 +86,7 @@ export declare const Select: {
             default: () => never[];
         };
         virtualListProps: {
-            type: import('vue').PropType<import('../virtual-list-v2/interface.ts').VirtualListProps>;
+            type: import('vue').PropType<import('../index.ts').VirtualListProps>;
         };
         triggerProps: {
             type: import('vue').PropType<import('../index.ts').TriggerProps>;
@@ -1017,7 +1017,7 @@ export declare const Select: {
             default: () => never[];
         };
         virtualListProps: {
-            type: import('vue').PropType<import('../virtual-list-v2/interface.ts').VirtualListProps>;
+            type: import('vue').PropType<import('../index.ts').VirtualListProps>;
         };
         triggerProps: {
             type: import('vue').PropType<import('../index.ts').TriggerProps>;
@@ -1199,7 +1199,7 @@ export declare const Select: {
         default: () => never[];
     };
     virtualListProps: {
-        type: import('vue').PropType<import('../virtual-list-v2/interface.ts').VirtualListProps>;
+        type: import('vue').PropType<import('../index.ts').VirtualListProps>;
     };
     triggerProps: {
         type: import('vue').PropType<import('../index.ts').TriggerProps>;

package/dist/components/index.d.ts

@@ -38,6 +38,7 @@ export * from './progress';
 export * from './rate';
 export * from './resize-box';
 export * from './scrollbar-v2';
+export * from './virtual-list-v2';
 export * from './skeleton';
 export * from './space';
 export * from './spin';

package/dist/components/pagination/page-options.vue.d.ts

@@ -138,7 +138,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
                 default: () => never[];
             };
             virtualListProps: {
-                type: PropType<import('../virtual-list-v2/interface.ts').VirtualListProps>;
+                type: PropType<import('../index.ts').VirtualListProps>;
             };
             triggerProps: {
                 type: PropType<import('../index.ts').TriggerProps>;
@@ -1069,7 +1069,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
                 default: () => never[];
             };
             virtualListProps: {
-                type: PropType<import('../virtual-list-v2/interface.ts').VirtualListProps>;
+                type: PropType<import('../index.ts').VirtualListProps>;
             };
             triggerProps: {
                 type: PropType<import('../index.ts').TriggerProps>;
@@ -1251,7 +1251,7 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
             default: () => never[];
         };
         virtualListProps: {
-            type: PropType<import('../virtual-list-v2/interface.ts').VirtualListProps>;
+            type: PropType<import('../index.ts').VirtualListProps>;
         };
         triggerProps: {
             type: PropType<import('../index.ts').TriggerProps>;

package/dist/components/table/index.d.ts

@@ -93,7 +93,7 @@ export declare const Table: {
             default: boolean;
         };
         virtualListProps: {
-            type: import('vue').PropType<import('../virtual-list-v2/interface.ts').VirtualListProps>;
+            type: import('vue').PropType<import('../index.ts').VirtualListProps>;
         };
         spanMethod: {
             type: import('vue').PropType<(data: {
@@ -350,7 +350,7 @@ export declare const Table: {
             default: boolean;
         };
         virtualListProps: {
-            type: import('vue').PropType<import('../virtual-list-v2/interface.ts').VirtualListProps>;
+            type: import('vue').PropType<import('../index.ts').VirtualListProps>;
         };
         spanMethod: {
             type: import('vue').PropType<(data: {
@@ -581,7 +581,7 @@ export declare const Table: {
         default: boolean;
     };
     virtualListProps: {
-        type: import('vue').PropType<import('../virtual-list-v2/interface.ts').VirtualListProps>;
+        type: import('vue').PropType<import('../index.ts').VirtualListProps>;
     };
     spanMethod: {
         type: import('vue').PropType<(data: {

package/dist/components/transfer/index.d.ts

@@ -65,7 +65,7 @@ export declare const Transfer: {
             type: import('vue').PropType<boolean | import('./interface').TransferPagination>;
             default: boolean;
         };
-        virtualListProps: import('vue').PropType<import('../virtual-list-v2/interface').VirtualListProps>;
+        virtualListProps: import('vue').PropType<import('..').VirtualListProps>;
     }>> & Readonly<{
         onSearch?: ((_value: string, _type: import('./interface').TransferType) => any) | undefined;
         onSelect?: ((_sourceSelected: import('./interface').TransferValue[], _targetSelected: import('./interface').TransferValue[]) => any) | undefined;
@@ -168,7 +168,7 @@ export declare const Transfer: {
             type: import('vue').PropType<boolean | import('./interface').TransferPagination>;
             default: boolean;
         };
-        virtualListProps: import('vue').PropType<import('../virtual-list-v2/interface').VirtualListProps>;
+        virtualListProps: import('vue').PropType<import('..').VirtualListProps>;
     }>> & Readonly<{
         onSearch?: ((_value: string, _type: import('./interface').TransferType) => any) | undefined;
         onSelect?: ((_sourceSelected: import('./interface').TransferValue[], _targetSelected: import('./interface').TransferValue[]) => any) | undefined;
@@ -261,7 +261,7 @@ export declare const Transfer: {
         type: import('vue').PropType<boolean | import('./interface').TransferPagination>;
         default: boolean;
     };
-    virtualListProps: import('vue').PropType<import('../virtual-list-v2/interface').VirtualListProps>;
+    virtualListProps: import('vue').PropType<import('..').VirtualListProps>;
 }>> & Readonly<{
     onSearch?: ((_value: string, _type: import('./interface').TransferType) => any) | undefined;
     onSelect?: ((_sourceSelected: import('./interface').TransferValue[], _targetSelected: import('./interface').TransferValue[]) => any) | undefined;

package/dist/components/tree-select/index.d.ts

@@ -142,7 +142,7 @@ export declare const TreeSelect: {
             default: boolean;
         };
         virtualListProps: {
-            type: import('vue').PropType<import('../virtual-list-v2/interface.ts').VirtualListProps>;
+            type: import('vue').PropType<import('../index.ts').VirtualListProps>;
         };
         scrollbar: {
             type: import('vue').PropType<boolean | import('../index.ts').ScrollbarProps>;
@@ -1117,7 +1117,7 @@ export declare const TreeSelect: {
             default: boolean;
         };
         virtualListProps: {
-            type: import('vue').PropType<import('../virtual-list-v2/interface.ts').VirtualListProps>;
+            type: import('vue').PropType<import('../index.ts').VirtualListProps>;
         };
         scrollbar: {
             type: import('vue').PropType<boolean | import('../index.ts').ScrollbarProps>;
@@ -1342,7 +1342,7 @@ export declare const TreeSelect: {
         default: boolean;
     };
     virtualListProps: {
-        type: import('vue').PropType<import('../virtual-list-v2/interface.ts').VirtualListProps>;
+        type: import('vue').PropType<import('../index.ts').VirtualListProps>;
     };
     scrollbar: {
         type: import('vue').PropType<boolean | import('../index.ts').ScrollbarProps>;