xt-element-ui 1.2.5 → 1.2.7

package/docs/README.md

@@ -1,201 +1,100 @@
-## XT-Element-UI
-
-> 基于 Vue2 + ElementUI 的企业级组件库
-
-## 特性
-
-- **丰富的组件**：提供多种常用组件，覆盖布局、表单、数据展示等场景
-- **开箱即用**：基于 ElementUI 构建，无缝集成现有项目
-- **可分发**：完整的 npm 包架构，支持按需引入
-- **可覆盖**：组件设计支持覆盖 Element UI 原有组件
-- **双架构设计**：Xt 自定义组件 + Ex 扩展组件，便于维护管理
-- **主题系统**：支持亮色/暗色主题切换，支持自定义主色调
-- **响应式设计**：组件支持多种尺寸配置，适配不同屏幕
-
-## 组件架构
-
-XT-Element-UI 采用双架构设计，将组件分为两大类：
-
-### Xt 组件（自定义组件）
-
-全新开发的自定义组件，不依赖 ElementUI 原有组件：
-
-| 组件 | 说明 |
-|------|------|
-| XtButton | 按钮组件 |
-| XtCard | 卡片组件 |
-| XtCardItem | 卡片项组件 |
-| XtFlexBox | 弹性布局组件 |
-| XtGridBox | 网格布局组件 |
-| XtGridItem | 网格子项组件 |
-| XtText | 文本组件 |
-| XtInput | 输入框组件 |
-| XtDatePicker | 日期选择组件 |
-| XtConfigProvider | 配置提供器 |
-
-### Ex 组件（扩展组件）
-
-基于 ElementUI 或 ECharts 二次封装的增强组件：
-
-| 组件 | 说明 |
-|------|------|
-| ExButton | 基于 ElementUI Button 的扩展按钮 |
-| ExCard | 基于 ElementUI Card 的扩展卡片 |
-| ExTable | 基于 ElementUI Table 的扩展表格 |
-| ExChart | 图表容器组件 |
-| ExBar | 基于 ECharts 的柱状图 |
-| ExLine | 基于 ECharts 的折线图 |
-| ExPie | 基于 ECharts 的饼图 |
-| ExMulti | 基于 ECharts 的混合图表 |
-| ExTrend | 基于 ECharts 的趋势图 |
-
-### 命名规范
-
-| 前缀 | 含义 | 示例 |
-|------|------|------|
-| `Xt` | 自定义组件，全新开发 | XtButton, XtCard, XtFlexBox, XtGridBox |
-| `Ex` | 基于 ElementUI/ECharts 二次封装 | ExTable, ExBar, ExLine, ExChart |
-
-## 快速开始
+---
+home: true
+heroImage: /favicon.ico
+heroText: XT-Element-UI
+tagline: 基于 Vue 2.7 + ElementUI 的企业级组件库
+actionText: 🚀 快速上手
+actionLink: /components/base/xt-button
+features:
+  - title: 🎯 丰富的组件
+    details: 提供 15+ 组件，覆盖布局、表单、数据展示、图表等常见场景
+  - title: 📦 开箱即用
+    details: 基于 ElementUI 构建，与现有 ElementUI 项目无缝集成
+  - title: 🪶 按需引入
+    details: 完整的 npm 包架构，支持按需引入，减小打包体积
+  - title: 🎨 双架构设计
+    details: Xt 自定义组件 + Ex 扩展组件，职责清晰、便于维护
+  - title: 🌓 主题系统
+    details: 支持亮色/暗色主题切换，支持自定义主色调
+  - title: 📊 图表能力
+    details: 内置 ECharts 封装，提供柱状图、折线图、饼图、混合图
+footer: MIT Licensed | Copyright © 2026 XT-Element-UI
+---
+
+::: tip 💡 快速开始
 
 ```bash
 # 安装
-npm install xt-element-ui
-```
+npm install xt-element-ui --save
 
-```javascript
-// 全局引入
+# 全局引入
 import Vue from 'vue'
 import XtElementUI from 'xt-element-ui'
 import 'xt-element-ui/lib/index.css'
 
 Vue.use(XtElementUI)
-
-// 或按需引入
-import { XtButton, XtFlexBox, XtCard } from 'xt-element-ui'
-
-Vue.component('XtButton', XtButton)
-Vue.component('XtFlexBox', XtFlexBox)
-Vue.component('XtCard', XtCard)
 ```
 
-## 配置选项
+:::
 
-在安装时可以传入配置选项：
+---
 
-```javascript
-Vue.use(XtElementUI, {
-  theme: 'dark',        // 主题：'white' 或 'dark'
-  size: 'medium',       // 字体大小：'small', 'medium', 'large'
-  primaryColor: '#1890ff'  // 主色调
-})
-```
-
-## 工具函数
-
-提供全局工具函数用于动态配置：
-
-```javascript
-// 设置主题
-this.$xt.setTheme('dark')
-
-// 设置字体大小
-this.$xt.setSize('large')
+## 📦 组件概览
 
-// 设置主色调
-this.$xt.setPrimaryColor('#52c41a')
-
-// 获取当前配置
-console.log(this.$xt.getConfig())
-```
-
-## 布局类组件
-
-| 组件 | 说明 |
-|------|------|
-| XtFlexBox | 弹性盒布局，支持灵活的对齐和排列 |
-| XtGridBox | CSS Grid 网格布局，支持跨列跨行 |
-| XtGridItem | Grid 子项组件，支持 span、area 等属性 |
+### 🎨 Xt 组件（自定义组件）
 
-## 表单类组件
+全新开发、不依赖 ElementUI 原有组件：
 
 | 组件 | 说明 |
 |------|------|
-| XtButton | 按钮组件，支持多种类型和尺寸 |
-| XtInput | 输入框组件，支持前缀后缀和校验 |
-| XtDatePicker | 日期选择组件 |
+| **XtButton** | 按钮组件 |
+| **XtCard** | 卡片组件 |
+| **XtCardItem** | 卡片项组件 |
+| **XtFlexBox** | 弹性布局组件 |
+| **XtGridBox** | 网格布局组件 |
+| **XtText** | 文本组件 |
+| **XtInput** | 输入框组件 |
+| **XtConfigProvider** | 全局配置提供器 |
 
-## 数据展示组件
+### ✨ Ex 组件（扩展组件）
 
-| 组件 | 说明 |
-|------|------|
-| XtCard | 卡片容器组件 |
-| XtCardItem | 卡片内项组件 |
-| XtText | 文本组件，支持多种样式 |
-| ExTable | 扩展表格，支持导出等功能 |
-
-## 图表组件
+基于 ElementUI / ECharts 二次封装的增强组件：
 
 | 组件 | 说明 |
 |------|------|
-| ExChart | 图表容器，封装 ECharts |
-| ExBar | 柱状图组件 |
-| ExLine | 折线图组件 |
-| ExPie | 饼图组件 |
-| ExMulti | 混合图表组件 |
-| ExTrend | 趋势图组件 |
-
-## 主题系统
-
-### 亮色/暗色主题
-
-```vue
-<template>
-  <div>
-    <XtButton @click="$xt.setTheme('white')">亮色主题</XtButton>
-    <XtButton @click="$xt.setTheme('dark')">暗色主题</XtButton>
-  </div>
-</template>
-```
+| **ExButton** | 基于 ElementUI Button 的扩展按钮 |
+| **ExCard** | 基于 ElementUI Card 的扩展卡片 |
+| **ExTable** | 基于 ElementUI Table 的扩展表格（支持虚拟滚动） |
+| **ExBar / ExLine / ExPie / ExMulti** | 基于 ECharts 的图表组件 |
+| **ExSelectTree** | 下拉选择树组件 |
+| **ExUpload** | 上传组件（支持图片预览） |
+| **ExPage** | 页面组件 |
+| **ExDatePicker** | 日期选择组件 |
+| **ExIcon** | 图标组件（支持 SVG / 字体图标） |
 
-### 字体大小配置
+---
 
-```vue
-<template>
-  <div>
-    <XtButton @click="$xt.setSize('small')">小号字体</XtButton>
-    <XtButton @click="$xt.setSize('medium')">中号字体</XtButton>
-    <XtButton @click="$xt.setSize('large')">大号字体</XtButton>
-  </div>
-</template>
-```
-
-## 浏览器支持
+## 🌐 GitHub Pages 自动部署
 
-- Chrome（推荐）
-- Firefox
-- Safari
-- Edge
+本项目通过 **GitHub Actions** 自动构建并部署文档到 **GitHub Pages**：
 
-## 开发
+- 📖 **在线文档**：https://JobWebNie.github.io/xt-element-ui/
+- 🐛 **问题反馈**：https://github.com/JobWebNie/xt-element-ui/issues
+- 📦 **npm 主页**：https://www.npmjs.com/package/xt-element-ui
 
-```bash
-# 克隆项目
-git clone <repository-url>
+推送代码到 `main` / `master` 分支后，GitHub Actions 将自动执行：
+1. 安装依赖
+2. 构建 VuePress 文档
+3. 部署到 GitHub Pages
 
-# 安装依赖
-npm install
+---
 
-# 启动开发服务器
-npm run dev
+## 📚 更多资源
 
-# 构建文档
-npm run docs:dev
-
-# 构建生产版本
-npm run build
-```
+- **[查看完整文档](https://JobWebNie.github.io/xt-element-ui/)**
+- **[更新日志](https://github.com/JobWebNie/xt-element-ui/blob/main/CHANGELOG.md)**
+- **[贡献指南](https://github.com/JobWebNie/xt-element-ui/blob/main/CONTRIBUTING.md)**
+- **[GitHub 仓库](https://github.com/JobWebNie/xt-element-ui)**
 
-## 许可证
 
-MIT License
+# 在 GitHub 新建仓库后

package/docs/components/base/xt-card-item.md

@@ -7,7 +7,7 @@
 ::: demo 基本用法
 ```vue
 <template>
-  <XtCardItem label="销售额" value="12345" unit="元"></XtCardItem>
+  <XtCardItem title="销售额" label="销售额" value="12345" unit="元" style="width: 350px;"></XtCardItem>
 </template>
 ```
 :::

package/docs/components/base/xt-step-price.md

@@ -0,0 +1,280 @@
+## XtStepPrice 阶梯价格组件
+
+用于配置「根据数量区间 → 单价」阶梯型价格配置。
+
+- 最小数量从 `0` 开始，最后一档为 `[min, +∞)`
+- 支持动态增减阶梯；删除后前后区间自动对接到一起保证连续性
+- 提供 `XtStepPriceItem` 子组件，方便自定义场景下单独使用
+
+## 基本用法
+
+::: demo 基本用法
+```vue
+<template>
+  <XtStepPrice v-model="items" title="阶梯价格" />
+  <XtText size="small" style="margin-top: 12px;">当前值：{{ JSON.stringify(items) }}</XtText>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      items: [
+        { min: 0, max: 100, price: 10 },
+        { min: 100, max: 500, price: 8 },
+        { min: 500, max: null, price: 5 }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 自定义单位和小数位
+
+::: demo 自定义单位和小数位
+```vue
+<template>
+  <XtStepPrice
+    v-model="items"
+    title="批发阶梯价（美元，保留 4 位小数）"
+    unit="美元"
+    :precision="4"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      items: [
+        { min: 0, max: 100, price: 1.25 },
+        { min: 100, max: null, price: 0.85 }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 只读态
+
+::: demo 只读态
+```vue
+<template>
+  <XtStepPrice
+    v-model="items"
+    title="阶梯价格（只读）"
+    disabled
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      items: [
+        { min: 0, max: 100, price: 10 },
+        { min: 100, max: 500, price: 8 },
+        { min: 500, max: null, price: 5 }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 自定义括号与字段名
+
+::: demo 自定义括号与字段名
+```vue
+<template>
+  <XtStepPrice
+    v-model="items"
+    title="自定义括号"
+    left-bracket="("
+    right-bracket="]"
+  />
+  <XtText size="small" style="margin-top: 12px;">输出：{{ JSON.stringify(items) }}</XtText>
+
+  <XtStepPrice
+    v-model="backendItems"
+    title="适配后端字段结构"
+    :field-keys="{ min: 'low', max: 'high', price: 'unitPrice' }"
+    style="margin-top: 24px;"
+  />
+  <XtText size="small" style="margin-top: 12px;">后端字段：{{ JSON.stringify(backendItems) }}</XtText>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      items: [
+        { min: 0, max: 100, price: 10 },
+        { min: 100, max: null, price: 5 }
+      ],
+      backendItems: [
+        { low: 0, high: 200, unitPrice: 15 },
+        { low: 200, high: null, unitPrice: 8 }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 限制阶梯数量（limit）
+
+::: demo 限制阶梯数量
+```vue
+<template>
+  <XtStepPrice v-model="items" title="最多 3 档" :limit="3" />
+  <XtText size="small" style="margin-top: 12px;">输出：{{ JSON.stringify(items) }}</XtText>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      items: [
+        { min: 0, max: 100, price: 10 }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 使用 XtStepPriceItem 自定义布局
+
+::: demo 使用 XtStepPriceItem 自定义布局
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <XtStepPriceItem
+      v-for="(item, idx) in items"
+      :key="idx"
+      :value="item"
+      :index="idx"
+      :is-first="idx === 0"
+      :is-last="idx === items.length - 1"
+      :items-length="items.length"
+      :min-locked="idx !== 0"
+      @input="(val) => onInput(val, idx)"
+      @delete="onDelete"
+    />
+    <el-button size="small" type="primary" plain icon="el-icon-plus" @click="onAdd">新增</el-button>
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      items: [
+        { min: 0, max: 100, price: 10 },
+        { min: 100, max: null, price: 6 }
+      ]
+    }
+  },
+  methods: {
+    onInput(val, idx) {
+      this.$set(this.items, idx, val)
+    },
+    onAdd() {
+      const last = this.items[this.items.length - 1]
+      if (!last) {
+        this.items.push({ min: 0, max: null, price: 0 })
+        return
+      }
+      const cur = { min: last.min, max: last.min + 1, price: last.price }
+      last.min = cur.max
+      this.items.splice(this.items.length - 1, 0, cur)
+    },
+    onDelete(idx) {
+      if (this.items.length <= 1) return
+      this.items.splice(idx, 1)
+    }
+  }
+}
+</script>
+```
+:::
+
+## 属性说明
+
+### XtStepPrice
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `Array<{min, max, price}>` | `[{min:0, max:null, price:0}]` | 阶梯数组，`v-model` 绑定，支持 `.sync` 风格亦可 |
+| `title` | String | `''` | 标题 |
+| `unit` | String | `'元'` | 价格单位 |
+| `precision` | Number | `2` | 价格小数位（失焦后自动格式化） |
+| `left-bracket` | String | `'['` | 左括号显示字符，传空字符串则不显示 |
+| `right-bracket` | String | `null` | 右括号显示字符；传 `null` 走内置规则（仅 1 条时为 `]`，多条为 `)`），传具体值则强制显示 |
+| `field-keys` | `{min, max, price}` | `{min:'min', max:'max', price:'price'}` | 自定义字段名映射 |
+| `limit` | Number | `0` | 阶梯数量上限；`<= 0` 表示不限制；达到上限时隐藏新增按钮并提示 |
+| `disabled` | Boolean | `false` | 是否禁用/只读 |
+| `tip` | String | 中文提示文案 | 底部提示文案 |
+| `default-first` | Boolean | `true` | 传入空数组时是否自动生成首条 `[0, +∞)` |
+
+### XtStepPriceItem
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | `{min, max, price}` | `{min: 0, max: null, price: 0}` | 单条阶梯的值 |
+| `index` | Number | `0` | 索引，用于事件回调 |
+| `is-first` | Boolean | `false` | 是否首条（首条 `min` 固定为 `0` 且锁定不可改） |
+| `is-last` | Boolean | `false` | 是否末条（末条 `max` 显示为 `+∞`） |
+| `items-length` | Number | `1` | 当前阶梯总数，用于决定是否可删除及右括号默认策略 |
+| `min-locked` | Boolean | `false` | 是否锁定 `min` 输入框 |
+| `unit` | String | `'元'` | 价格单位 |
+| `precision` | Number | `2` | 价格小数位 |
+| `left-bracket` | String | `'['` | 左括号显示字符 |
+| `right-bracket` | String | `null` | 右括号；为 `null` 走默认逻辑（仅 1 条→ `]`，多条→ `)`） |
+| `field-keys` | `{min, max, price}` | `{min:'min', max:'max', price:'price'}` | 自定义字段名映射 |
+| `removable` | Boolean | `true` | 是否可删除（`removable=true` 且 `items-length>1` 时才显示删除按钮） |
+| `disabled` | Boolean | `false` | 是否禁用 |
+
+## 事件
+
+### XtStepPrice
+
+| 事件 | 说明 | 参数 |
+|------|------|------|
+| `input` | 值变化（v-model 自动更新） | 最新的 items 数组 |
+| `change` | 任何引起值变化的动作（新增/删除/修改） | 最新的 items 数组 |
+
+### XtStepPriceItem
+
+| 事件 | 说明 | 参数 |
+|------|------|------|
+| `input` | 该条值变化 | `{min, max, price}` |
+| `change` | 该条值变化 | `{min, max, price}, index` |
+| `min-change` | min 失焦修改 | `min, index` |
+| `max-change` | max 失焦修改 | `max, index` |
+| `delete` | 点击删除 | `index` |
+
+## 插槽
+
+### XtStepPrice
+
+| 插槽 | 说明 |
+|------|------|
+| `header` | 头部右侧自定义内容 |
+| `tip` | 底部提示自定义内容 |
+
+## 注意事项
+
+1. **首条 `min` 固定为 `0` 且锁定不可编辑，保证最小数量从 0 开始。
+2. **末条 `max` 固定为 `+∞`，保证任何数量都能匹配到一个区间。
+3. **连续性保证**：任意两条相邻阶梯，后一条的 `min` 始终等于前一条的 `max`；删除中间阶梯后，前后自动对接到一起。
+4. 容器内的 `XtStepPriceItem` 的 `min` 输入框对非首条默认锁定，避免用户误操作破坏连续性；如需自由编辑，可单独使用 `XtStepPriceItem` 自行管理数据。
+5. `price` 输入值小于 `0` 时自动修正为 `0`。