xt-element-ui 2.1.3 → 2.1.5

package/docs/components/base/xt-date-picker.md

@@ -1,111 +1,180 @@
-## XtDatePicker 日期选择器组件
-
-日期选择器组件用于选择日期范围，支持多种日期类型（年月日、年月、年、季度等）。
-
-## 基本用法
-
-::: demo 基本用法
-```vue
-<template>
-  <XtDatePicker v-model="dateRange" />
-</template>
-
-<script>
-export default {
-  data() {
-    return {
-      dateRange: []
-    }
-  }
-}
-</script>
-```
-:::
-
-## 属性说明
-
-| 属性 | 类型 | 默认值 | 可选值 | 说明 |
-|------|------|--------|--------|------|
-| `value` / `v-model` | Array | - | - | 日期范围，格式为 `[startDate, endDate]` |
-| `dateType` | String | `date` | `date`、`datetime`、`month`、`year`、`quarter`、`week` | 日期类型 |
-| `separator` | String | `至` | - | 分隔符文本 |
-| `disabled` | Boolean | `false` | - | 是否禁用 |
-| `width` | Number | `280` | - | 组件宽度（px） |
-
-## 示例
-
-### 不同日期类型
-
-::: demo 不同日期类型
-```vue
-<template>
-  <div style="display: flex; flex-direction: column; gap: 12px;">
-    <XtDatePicker v-model="dateRange" dateType="date" />
-    <XtDatePicker v-model="monthRange" dateType="month" />
-    <XtDatePicker v-model="yearRange" dateType="year" />
-    <XtDatePicker v-model="quarterRange" dateType="quarter" />
-  </div>
-</template>
-
-<script>
-export default {
-  data() {
-    return {
-      dateRange: [],
-      monthRange: [],
-      yearRange: [],
-      quarterRange: []
-    }
-  }
-}
-</script>
-```
-:::
-
-### 自定义分隔符
-
-::: demo 自定义分隔符
-```vue
-<template>
-  <XtDatePicker v-model="dateRange" separator="~" />
-</template>
-
-<script>
-export default {
-  data() {
-    return {
-      dateRange: []
-    }
-  }
-}
-</script>
-```
-:::
-
-### 禁用状态
-
-::: demo 禁用状态
-```vue
-<template>
-  <XtDatePicker v-model="dateRange" disabled />
-</template>
-
-<script>
-export default {
-  data() {
-    return {
-      dateRange: []
-    }
-  }
-}
-</script>
-```
-:::
-
-## 事件
-
-| 事件名 | 说明 | 参数 |
-|--------|------|------|
-| `change` | 日期值改变时触发 | `[startDate, endDate]` |
-| `focus` | 输入框获得焦点时触发 | - |
-| `blur` | 输入框失去焦点时触发 | - |
+## XtDatePicker 日期选择器组件
+
+日期选择器组件用于选择日期范围或单个日期，支持多种日期类型（年月日、年月、年、季度等），并提供时间维度选择功能，满足统计分析场景。
+
+## 基本用法
+
+::: demo 基本用法
+```vue
+<template>
+  <XtDatePicker v-model="dateRange" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      dateRange: []
+    }
+  }
+}
+</script>
+```
+:::
+
+## 属性说明
+
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `value` / `v-model` | Array / Date | - | - | 日期范围 `[startDate, endDate]` 或单个日期 |
+| `dateType` | String | `date` | `date`、`datetime`、`month`、`year`、`quarter`、`week` | 日期类型 |
+| `separator` | String | `至` | - | 分隔符文本 |
+| `disabled` | Boolean | `false` | - | 是否禁用 |
+| `width` | String | `100%` | - | 组件宽度 |
+| `rangeMode` | Boolean | `true` | - | 是否为范围选择模式，false 时为单选 |
+| `showDimension` | Boolean | `false` | - | 是否显示时间维度选择器 |
+| `dimension` | String | `day` | `day`、`month`、`year`、`custom` | 当前时间维度 |
+
+## 事件
+
+| 事件名 | 说明 | 参数 |
+|--------|------|------|
+| `change` | 日期值改变时触发 | `[startDate, endDate]` 或 `date` |
+| `dimension-change` | 时间维度或值变化时触发 | `{ dimension, value }` |
+| `focus` | 输入框获得焦点时触发 | - |
+| `blur` | 输入框失去焦点时触发 | - |
+
+## 示例
+
+### 不同日期类型
+
+::: demo 不同日期类型
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <XtDatePicker v-model="dateRange" dateType="date" />
+    <XtDatePicker v-model="monthRange" dateType="month" />
+    <XtDatePicker v-model="yearRange" dateType="year" />
+    <XtDatePicker v-model="quarterRange" dateType="quarter" />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      dateRange: [],
+      monthRange: [],
+      yearRange: [],
+      quarterRange: []
+    }
+  }
+}
+</script>
+```
+:::
+
+### 单选模式
+
+::: demo 单选模式
+```vue
+<template>
+  <XtDatePicker v-model="singleDate" :range-mode="false" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      singleDate: null
+    }
+  }
+}
+</script>
+```
+:::
+
+### 时间维度选择（统计分析）
+
+::: demo 时间维度选择
+```vue
+<template>
+  <XtDatePicker 
+    v-model="dateRange" 
+    :show-dimension="true" 
+    :dimension="currentDimension"
+    @update:dimension="currentDimension = $event"
+    @dimension-change="handleDimensionChange"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      dateRange: [],
+      currentDimension: 'day'
+    }
+  },
+  methods: {
+    handleDimensionChange({ dimension, value }) {
+      console.log('维度:', dimension, '值:', value)
+    }
+  }
+}
+</script>
+```
+:::
+
+### 自定义分隔符
+
+::: demo 自定义分隔符
+```vue
+<template>
+  <XtDatePicker v-model="dateRange" separator="~" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      dateRange: []
+    }
+  }
+}
+</script>
+```
+:::
+
+### 禁用状态
+
+::: demo 禁用状态
+```vue
+<template>
+  <XtDatePicker v-model="dateRange" disabled />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      dateRange: []
+    }
+  }
+}
+</script>
+```
+:::
+
+## 时间维度说明
+
+当启用 `showDimension` 后，选择不同维度会有以下效果：
+
+| 维度 | 日期类型 | 选择模式 | 范围限制 |
+|------|----------|----------|----------|
+| `day` | date | 范围选择 | 无限制 |
+| `month` | month | 范围选择 | 结束日期必须与开始日期同月份 |
+| `year` | year | 范围选择 | 结束日期必须与开始日期同年份 |
+| `custom` | 保持原值 | 单选 | 用户自定义 |
+
+选择"月"维度后，结束日期会限制在开始日期所在月份内，方便统计分析时快速选择同一月内的日期范围。

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

@@ -42,7 +42,7 @@ Vue.component(XtStepPriceItem.name, XtStepPriceItem)
 ```
 
 ### 基本用法
-
+::: demo
 ```vue
 <template>
   <div style="width: 600px;">
@@ -72,6 +72,7 @@ export default {
 }
 </script>
 ```
+:::
 
 ### 自定义字段名
 
@@ -121,7 +122,7 @@ export default {
 | `fieldKeys` | Object | `{ min: 'min', max: 'max', price: 'price' }` | 字段名映射，支持自定义字段名 |
 | `limit` | Number | `0` | 阶梯数量上限，<=0 表示不限制 |
 | `step` | Number | `10` | 阶梯增量，新增时自动填充下一级的 min 值 |
-| `disabled` | Boolean | `false` | 是否禁用所有操作 |
+| `disabled` | Boolean | `false` | 是否禁用所有操作 |
 | `allowNegative` | Boolean | `false` | 是否允许输入负数价格和下限 |
 | `tip` | String | `'区间左闭右闭 [min, max]，最后一级为 [min, +∞)，保证连续且不重叠。'` | 底部提示文本 |
 | `defaultFirst` | Boolean | `true` | 空数组时是否自动生成默认阶梯 |

package/docs/components/base/xt-transfer-tree.md

@@ -0,0 +1,272 @@
+## XtTransferTree 树形穿梭框组件
+
+树形穿梭框组件，支持树形结构数据的穿梭，提供多种穿梭模式满足不同业务场景。
+
+## 基本用法
+
+::: demo 基本用法
+```vue
+<template>
+  <XtTransferTree 
+    :data="treeData" 
+    v-model="selectedIds" 
+    :height="400"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      selectedIds: [],
+      treeData: [
+        {
+          id: '1',
+          label: '一级菜单',
+          children: [
+            {
+              id: '1-1',
+              label: '二级菜单1'
+            },
+            {
+              id: '1-2',
+              label: '二级菜单2'
+            }
+          ]
+        },
+        {
+          id: '2',
+          label: '一级菜单2',
+          children: [
+            {
+              id: '2-1',
+              label: '二级菜单3'
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 属性说明
+
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `value` / `v-model` | Array | `[]` | - | 已选择的节点 ID 数组 |
+| `data` | Array | `[]` | - | 树形数据源 |
+| `leftTitle` | String | `待选择` | - | 左侧面板标题 |
+| `rightTitle` | String | `已选择` | - | 右侧面板标题 |
+| `treeProps` | Object | `{ label, children, value }` | - | 树节点属性配置 |
+| `defaultExpandAll` | Boolean | `true` | - | 是否默认展开所有节点 |
+| `filterable` | Boolean | `false` | - | 是否支持搜索过滤 |
+| `showCheckbox` | Boolean | `true` | - | 是否显示复选框 |
+| `cascade` | Boolean | `true` | - | 是否级联选择 |
+| `transferMode` | String | `single` | `single`, `multiple`, `parent-child` | 穿梭模式 |
+| `buttonSize` | String | `small` | - | 按钮尺寸 |
+
+## 穿梭模式说明
+
+| 模式 | 说明 |
+|------|------|
+| `single` | 单选模式，点击节点或勾选后只穿梭当前节点 |
+| `multiple` | 多选模式，勾选多个节点后一次性穿梭 |
+| `parent-child` | 父子模式，穿梭父节点时自动包含所有子节点 |
+
+## 事件
+
+| 事件名 | 说明 | 参数 |
+|--------|------|------|
+| `change` | 数据变化时触发 | `{ value, addedKeys, removedKeys }` |
+
+## 示例
+
+### 父子级联穿梭
+
+::: demo 父子级联穿梭
+```vue
+<template>
+  <XtTransferTree 
+    :data="treeData" 
+    v-model="selectedIds" 
+    :height="400"
+    transfer-mode="parent-child"
+    @change="handleChange"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      selectedIds: [],
+      treeData: [
+        {
+          id: '1',
+          label: '部门A',
+          children: [
+            { id: '1-1', label: '员工1' },
+            { id: '1-2', label: '员工2' }
+          ]
+        },
+        {
+          id: '2',
+          label: '部门B',
+          children: [
+            { id: '2-1', label: '员工3' }
+          ]
+        }
+      ]
+    }
+  },
+  methods: {
+    handleChange({ value, addedKeys, removedKeys }) {
+      console.log('已选择:', value)
+      console.log('新增:', addedKeys)
+      console.log('移除:', removedKeys)
+    }
+  }
+}
+</script>
+```
+:::
+
+### 支持搜索过滤
+
+::: demo 支持搜索过滤
+```vue
+<template>
+  <XtTransferTree 
+    :data="treeData" 
+    v-model="selectedIds" 
+    :height="400"
+    :filterable="true"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      selectedIds: [],
+      treeData: [
+        {
+          id: '1',
+          label: '水果',
+          children: [
+            { id: '1-1', label: '苹果' },
+            { id: '1-2', label: '香蕉' },
+            { id: '1-3', label: '橙子' }
+          ]
+        },
+        {
+          id: '2',
+          label: '蔬菜',
+          children: [
+            { id: '2-1', label: '西红柿' },
+            { id: '2-2', label: '黄瓜' }
+          ]
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+### 不级联选择
+
+::: demo 不级联选择
+```vue
+<template>
+  <XtTransferTree 
+    :data="treeData" 
+    v-model="selectedIds" 
+    :height="400"
+    :cascade="false"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      selectedIds: [],
+      treeData: [
+        {
+          id: '1',
+          label: '分类1',
+          children: [
+            { id: '1-1', label: '项目1' },
+            { id: '1-2', label: '项目2' }
+          ]
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+### 点击穿梭（无复选框）
+
+::: demo 点击穿梭
+```vue
+<template>
+  <XtTransferTree 
+    :data="treeData" 
+    v-model="selectedIds" 
+    :height="400"
+    :show-checkbox="false"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      selectedIds: [],
+      treeData: [
+        {
+          id: '1',
+          label: '选项1'
+        },
+        {
+          id: '2',
+          label: '选项2'
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 方法
+
+| 方法名 | 说明 | 参数 |
+|--------|------|------|
+| `clearSelection` | 清空选择 | - |
+
+## 数据格式
+
+```javascript
+[
+  {
+    id: 'node-id',
+    label: '节点名称',
+    children: [
+      {
+        id: 'child-id',
+        label: '子节点名称'
+      }
+    ]
+  }
+]
+```