xt-element-ui 1.2.6 → 1.2.8

package/README.md

@@ -94,7 +94,6 @@ Vue.component('ExBar', ExBar)
 | **XtGridItem** | 网格子项组件 |
 | **XtText** | 文本组件 |
 | **XtInput** | 输入框组件 |
-| **XtDatePicker** | 日期选择组件 |
 | **XtConfigProvider** | 全局配置提供器 |
 
 ### Ex 组件（扩展组件）
@@ -112,6 +111,7 @@ Vue.component('ExBar', ExBar)
 | **ExSelectTree** | 下拉选择树组件 |
 | **ExUpload** | 上传组件（支持图片预览） |
 | **ExPage** | 页面组件 |
+| **ExDatePicker** | 日期选择组件 |
 | **ExIcon** | 图标组件（支持 SVG / 字体图标） |
 
 ---

package/docs/README.md

@@ -54,7 +54,6 @@ Vue.use(XtElementUI)
 | **XtGridBox** | 网格布局组件 |
 | **XtText** | 文本组件 |
 | **XtInput** | 输入框组件 |
-| **XtDatePicker** | 日期选择组件 |
 | **XtConfigProvider** | 全局配置提供器 |
 
 ### ✨ Ex 组件（扩展组件）
@@ -70,6 +69,7 @@ Vue.use(XtElementUI)
 | **ExSelectTree** | 下拉选择树组件 |
 | **ExUpload** | 上传组件（支持图片预览） |
 | **ExPage** | 页面组件 |
+| **ExDatePicker** | 日期选择组件 |
 | **ExIcon** | 图标组件（支持 SVG / 字体图标） |
 
 ---

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`。

package/docs/components/base/xt-time.md

@@ -0,0 +1,165 @@
+## XtTime 时间组件
+
+集三种模式于一身的时间组件：当前时间实时显示、目标时间倒计时、日期文本格式化展示。
+
+## 基本用法
+
+### 三种显示模式
+
+::: demo 三种显示模式
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <div>当前时间：<XtTime type="now" /></div>
+    <div>距 2026-12-31：<XtTime type="countdown" target-time="2026-12-31 23:59:59" /></div>
+    <div>创建时间：<XtTime type="text" :value="1704067200000" /></div>
+  </div>
+</template>
+```
+:::
+
+## 属性说明
+
+### 通用属性
+
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `type` | String | `now` | `now`、`countdown`、`text` | 显示模式 |
+| `format` | String | `YYYY-MM-DD HH:mm:ss` | - | `now` / `text` 模式下的日期格式 |
+| `size` | String | base | `extra-large`、`large`、`medium`、`base`、`small`、`extra-small` | 字体大小 |
+| `type-color` | String | - | `primary`、`success`、`warning`、`danger` | 颜色语义 |
+| `bold` | Boolean | false | - | 是否加粗 |
+| `prefix` | String | - | - | 前缀文本 |
+| `suffix` | String | - | - | 后缀文本 |
+| `empty-text` | String | `-` | - | 空值/无效值时展示的占位文本 |
+| `hide-empty` | Boolean | false | - | 值为空时是否不渲染内容 |
+| `interval` | Number | `1000` | `>= 100` | 刷新间隔（毫秒），仅 `now` / `countdown` 生效 |
+
+### text 模式专属属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | String / Number / Date | - | 待格式化的日期值，支持时间戳（10 位秒或 13 位毫秒）、Date 对象、`2024-01-01 12:00:00` 等字符串 |
+
+### countdown 模式专属属性
+
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `target-time` | String / Number / Date | - | - | 目标时间，取值同 `value` |
+| `countdown-format` | String | `DHMS` | `DHMS`、`HMS`、`MS`、`SEC` | 倒计时显示格式 |
+| `finished-text` | String | `已结束` | - | 倒计时结束后显示的文本 |
+
+## 事件
+
+| 事件名 | 说明 | 参数 |
+|--------|------|------|
+| `finish` | 倒计时结束触发（仅 `countdown` 模式） | - |
+| `click` | 点击组件触发 | `(event: MouseEvent)` |
+
+## 插槽
+
+| 插槽 | 说明 |
+|------|------|
+| `prefix` | 前缀插槽，优先级高于 `prefix` 属性 |
+| `suffix` | 后缀插槽，优先级高于 `suffix` 属性 |
+| `finished` | 倒计时结束态自定义内容（仅 `countdown` 模式） |
+| `default` | 自定义整体内容，覆盖默认渲染 |
+
+## 示例
+
+### 当前时间（now 模式）
+
+::: demo 当前时间
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <XtTime type="now" />
+    <XtTime type="now" format="YYYY年MM月DD日 HH时mm分ss秒" type-color="primary" bold />
+    <XtTime type="now" format="HH:mm:ss" size="extra-large" type-color="danger" />
+  </div>
+</template>
+```
+:::
+
+### 日期文本（text 模式）
+
+`value` 支持时间戳、字符串、Date 对象，自动识别并格式化：
+
+::: demo 日期文本
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <XtTime type="text" value="2024-01-01 12:00:00" />
+    <XtTime type="text" :value="1704067200" format="YYYY-MM-DD" />
+    <XtTime type="text" :value="new Date('2024-06-15')" format="YYYY/MM/DD" />
+    <XtTime type="text" value="无效值" />
+    <XtTime type="text" value="2024-01-01" prefix="创建于 " type-color="success" />
+  </div>
+</template>
+```
+:::
+
+### 倒计时（countdown 模式）
+
+::: demo 倒计时
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <XtTime type="countdown" target-time="2026-12-31 23:59:59" />
+    <XtTime type="countdown" target-time="2026-12-31 23:59:59" countdown-format="HMS" type-color="primary" />
+    <XtTime type="countdown" target-time="2026-12-31 23:59:59" countdown-format="MS" />
+    <XtTime type="countdown" target-time="2026-12-31 23:59:59" countdown-format="SEC" suffix="后结束" />
+    <XtTime
+      type="countdown"
+      :target-time="Date.now() + 5000"
+      @finish="onFinish"
+    />
+  </div>
+</template>
+
+<script>
+export default {
+  methods: {
+    onFinish() {
+      this.$message && this.$message('倒计时结束！')
+    }
+  }
+}
+</script>
+```
+:::
+
+### 自定义结束态（finished 插槽）
+
+::: demo 自定义结束态
+```vue
+<template>
+  <XtTime type="countdown" :target-time="Date.now() + 3000">
+    <template #finished>
+      <span style="color: #67c23a;">🎉 活动已开始，欢迎参加</span>
+    </template>
+  </XtTime>
+</template>
+```
+:::
+
+### 前缀 / 后缀
+
+::: demo 前缀后缀
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <XtTime type="now" prefix="当前时间：" />
+    <XtTime type="countdown" target-time="2026-12-31 23:59:59" suffix=" 后截止" type-color="warning" />
+    <XtTime type="text" value="2024-01-01 08:00:00" prefix="入职日期：" suffix="（周一）" />
+  </div>
+</template>
+```
+:::
+
+## 注意事项
+
+- `value` / `target-time` 对**纯数字时间戳**自动识别：10 位数字视作秒级时间戳，13 位数字视作毫秒级时间戳。
+- `countdown` 模式下组件销毁、切出 `keep-alive` 缓存时会自动清理定时器，避免内存泄漏。
+- `type` 从 `now`/`countdown` 切换为 `text`（或反向），组件会自动重置定时器。
+- 如需不同的时区展示，可在父组件中将 `value` 先转换为本地时区 Date 对象再传入。