xt-element-ui 1.3.0 → 1.3.1

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

@@ -1,280 +1,166 @@
 ## XtStepPrice 阶梯价格组件
 
-用于配置「根据数量区间 → 单价」阶梯型价格配置。
+用于配置阶梯式价格、数量区间等场景，支持区间自动校正、批量删除、自定义字段名等功能。
 
-- 最小数量从 `0` 开始，最后一档为 `[min, +∞)`
-- 支持动态增减阶梯；删除后前后区间自动对接到一起保证连续性
-- 提供 `XtStepPriceItem` 子组件，方便自定义场景下单独使用
+### 核心特性
 
-## 基本用法
+- **区间自动校正**：保证区间连续且不重叠，自动处理左闭右闭逻辑
+- **批量操作**：支持新增、删除档位，达到上限时自动禁用新增
+- **自定义字段名**：允许传入自定义字段名映射（如 min/max/price 可改为 start/end/value）
+- **单位与精度**：支持自定义货币单位和小数精度
+- **括号逻辑**：自动处理括号显示（单条显示 `]`，多条显示 `)`）
+
+### 安装与引入
+
+#### 方式1：全量引入（推荐）
 
-::: demo 基本用法
 ```vue
-<template>
-  <XtStepPrice v-model="items" title="阶梯价格" />
-  <XtText size="small" style="margin-top: 12px;">当前值：{{ JSON.stringify(items) }}</XtText>
-</template>
+import Vue from 'vue'
+import XtElementUI from 'xt-element-ui'
 
-<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>
+Vue.use(XtElementUI)
 ```
-:::
 
-## 自定义单位和小数位
+#### 方式2：单独引入（支持 Vue.use）
 
-::: demo 自定义单位和小数位
 ```vue
-<template>
-  <XtStepPrice
-    v-model="items"
-    title="批发阶梯价（美元，保留 4 位小数）"
-    unit="美元"
-    :precision="4"
-  />
-</template>
+import Vue from 'vue'
+import XtStepPrice from 'xt-element-ui/src/components/xt-step-price'
 
-<script>
-export default {
-  data() {
-    return {
-      items: [
-        { min: 0, max: 100, price: 1.25 },
-        { min: 100, max: null, price: 0.85 }
-      ]
-    }
-  }
-}
-</script>
+// 自动注册 XtStepPrice 和 XtStepPriceItem
+Vue.use(XtStepPrice)
 ```
-:::
 
-## 只读态
+#### 方式3：手动注册组件
 
-::: demo 只读态
 ```vue
-<template>
-  <XtStepPrice
-    v-model="items"
-    title="阶梯价格（只读）"
-    disabled
-  />
-</template>
+import Vue from 'vue'
+import { XtStepPrice, XtStepPriceItem } from 'xt-element-ui/src/components/xt-step-price'
 
-<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>
+Vue.component(XtStepPrice.name, XtStepPrice)
+Vue.component(XtStepPriceItem.name, XtStepPriceItem)
 ```
-:::
 
-## 自定义括号与字段名
+### 基本用法
 
-::: 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>
+  <div style="width: 600px;">
+    <XtStepPrice
+      v-model="priceSteps"
+      title="阶梯价格"
+      unit="元"
+      :precision="2"
+      :limit="5"
+      :step="10"
+      tip="区间左闭右闭 [min, max]，最后一级为 [min, +∞)"
+    />
+  </div>
 </template>
 
 <script>
 export default {
   data() {
     return {
-      items: [
+      priceSteps: [
         { 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 }
+        { min: 100, max: 500, price: 9 },
+        { min: 500, max: Infinity, price: 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>
+  <XtStepPrice
+    v-model="customSteps"
+    :field-keys="{ min: 'start', max: 'end', price: 'value' }"
+    title="自定义字段名"
+  />
 </template>
 
 <script>
 export default {
   data() {
     return {
-      items: [
-        { min: 0, max: 100, price: 10 }
+      customSteps: [
+        { start: 0, end: 100, value: 10 },
+        { start: 100, end: 500, value: 9 }
       ]
     }
   }
 }
 </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
+  v-model="priceSteps"
+  disabled
+  title="禁用状态"
+/>
 ```
-:::
-
-## 属性说明
-
-### 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` 输入框 |
+| `value` / `v-model` | Array | `[]` | 阶梯数据数组，每个元素包含 `min`/`max`/`price` 字段 |
+| `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'}` | 自定义字段名映射 |
-| `removable` | Boolean | `true` | 是否可删除（`removable=true` 且 `items-length>1` 时才显示删除按钮） |
-| `disabled` | Boolean | `false` | 是否禁用 |
-
-## 事件
-
-### XtStepPrice
-
-| 事件 | 说明 | 参数 |
-|------|------|------|
-| `input` | 值变化（v-model 自动更新） | 最新的 items 数组 |
-| `change` | 任何引起值变化的动作（新增/删除/修改） | 最新的 items 数组 |
-
-### XtStepPriceItem
+| `precision` | Number | `2` | 价格小数精度 |
+| `leftBracket` | String | `'['` | 左括号，传空字符串则不显示 |
+| `rightBracket` | String | `null` | 右括号，默认自动逻辑（单条 `]`，多条 `)`）；传具体值强制使用 |
+| `fieldKeys` | Object | `{ min: 'min', max: 'max', price: 'price' }` | 字段名映射，支持自定义字段名 |
+| `limit` | Number | `0` | 阶梯数量上限，<=0 表示不限制 |
+| `step` | Number | `10` | 阶梯增量，新增时自动填充下一级的 min 值 |
+| `disabled` | Boolean | `false` | 是否禁用所有操作 |
+| `tip` | String | `'区间左闭右闭 [min, max]，最后一级为 [min, +∞)，保证连续且不重叠。'` | 底部提示文本 |
+| `defaultFirst` | Boolean | `true` | 空数组时是否自动生成默认阶梯 |
+
+### 事件
+
+| 事件名 | 说明 | 参数 |
+|--------|------|------|
+| `input` | 数据变化时触发 | 最新的阶梯数组 |
+| `add` | 新增档位时触发 | 新增的档位数据 |
+| `delete` | 删除档位时触发 | 删除的档位索引和数据 |
+| `change` | 任一档位数据变化时触发 | 变化后的完整阶梯数组 |
+
+### 插槽
+
+| 插槽名 | 说明 |
+|--------|------|
+| `header` | 标题栏右侧自定义内容 |
+| `tip` | 底部提示区域自定义内容 |
+
+### 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` | 底部提示自定义内容 |
+```vue
+<XtStepPriceItem
+  v-model="item"
+  :index="0"
+  :is-first="true"
+  :is-last="true"
+  :items-length="1"
+  :unit="'元'"
+  :precision="2"
+  @input="onItemInput"
+  @delete="onDelete"
+/>
+```
 
-## 注意事项
+### 注意事项
 
-1. **首条 `min` 固定为 `0` 且锁定不可编辑，保证最小数量从 0 开始。
-2. **末条 `max` 固定为 `+∞`，保证任何数量都能匹配到一个区间。
-3. **连续性保证**：任意两条相邻阶梯，后一条的 `min` 始终等于前一条的 `max`；删除中间阶梯后，前后自动对接到一起。
-4. 容器内的 `XtStepPriceItem` 的 `min` 输入框对非首条默认锁定，避免用户误操作破坏连续性；如需自由编辑，可单独使用 `XtStepPriceItem` 自行管理数据。
-5. `price` 输入值小于 `0` 时自动修正为 `0`。
+1. **区间逻辑**：采用左闭右闭 `[min, max]`，最后一级自动处理为 `[min, +∞)`
+2. **空值处理**：当 `v-model` 为空数组时，会自动生成默认阶梯（可通过 `defaultFirst=false` 关闭）
+3. **精度控制**：所有输入值会自动按 `precision` 四舍五入
+4. **性能优化**：当阶梯数量较多时，建议设置 `limit` 限制最大数量
+5. **字段名映射**：`fieldKeys` 必须与传入的 `value` 字段名完全匹配