xt-element-ui 2.1.5 → 2.1.7

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

@@ -1,180 +1,268 @@
-## 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` | 保持原值 | 单选 | 用户自定义 |
-
-选择"月"维度后，结束日期会限制在开始日期所在月份内，方便统计分析时快速选择同一月内的日期范围。
+日期选择器组件用于选择日期范围或单个日期，支持多种日期类型（年月日、年月、年、季度等），并提供时间维度选择功能，满足统计分析场景。
+
+## 基本用法
+
+::: demo 基本用法（日期范围）
+```vue
+<template>
+  <XtDatePicker v-model="dateRange" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      dateRange: ""
+    }
+  }
+}
+</script>
+```
+:::
+
+## 属性说明
+
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `value` / `v-model` | Array / String | - | - | 日期范围 `[start, end]` 或单个日期字符串 |
+| `dateType` | String | `date` | `date`、`datetime`、`month`、`year`、`quarter`、`week` | 日期类型 |
+| `separator` | String | `至` | - | 范围选择时的分隔符文本 |
+| `disabled` | Boolean | `false` | - | 是否禁用 |
+| `width` | String | `100%` | - | 组件宽度，如 `'500px'` |
+| `rangeMode` | Boolean | `true` | - | 是否为范围选择模式，false 时为单选 |
+| `showDimension` | Boolean | `false` | - | 是否显示时间维度选择器（日/月/年/自定义） |
+| `dimension` | String | `date` | `date`、`month`、`year`、`daterange` | 当前时间维度 |
+| `immediate` | Boolean | `true` | - | 切换维度后是否立即触发事件 |
+
+## 事件说明
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `change` | `value` | 日期值改变时触发 |
+| `dimension-change` | `{ dimension, value }` | 时间维度或值变化时触发 |
+| `focus` | - | 输入框获得焦点时触发 |
+| `blur` | - | 输入框失去焦点时触发 |
+
+## 示例
+
+### 日期范围选择
+
+::: demo 日期范围选择
+```vue
+<template>
+  <XtDatePicker v-model="dateRange" rangeMode="true" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      dateRange: []
+    }
+  }
+}
+</script>
+```
+:::
+
+### 月份范围选择
+
+::: demo 月份范围选择
+```vue
+<template>
+  <XtDatePicker v-model="monthRange" dateType="month" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      monthRange: ""
+    }
+  }
+}
+</script>
+```
+:::
+
+### 年份范围选择
+
+::: demo 年份范围选择
+```vue
+<template>
+  <XtDatePicker v-model="yearRange" dateType="year" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      yearRange: ""
+    }
+  }
+}
+</script>
+```
+:::
+
+### 季度选择
+
+::: demo 季度选择
+```vue
+<template>
+  <XtDatePicker v-model="quarterRange" dateType="quarter" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      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"
+    @dimension-change="handleDimensionChange"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      dateRange: "",
+      currentDimension: 'date'
+    }
+  },
+  methods: {
+    handleDimensionChange({ dimension, value }) {
+      this.currentDimension = dimension
+      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>
+```
+:::
+
+### 自定义宽度
+
+::: demo 自定义宽度
+```vue
+<template>
+  <XtDatePicker v-model="dateRange" width="600" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      dateRange: ""
+    }
+  }
+}
+</script>
+```
+:::
+
+## 时间维度说明
+
+当启用 `showDimension` 后，选择不同维度会有以下效果：
+
+| 维度 | 日期类型 | 格式 | 说明 |
+|------|----------|------|------|
+| `date` | date | yyyy-MM-dd | 日维度，选择日期范围 |
+| `month` | month | yyyy-MM | 月维度，选择月份范围 |
+| `year` | year | yyyy | 年维度，选择年份范围 |
+| `daterange` | date | yyyy-MM-dd | 自定义区间，选择日期范围 |
+
+## 日期类型格式
+
+| 类型 | 显示格式 | 说明 |
+|------|----------|------|
+| `date` | yyyy-MM-dd | 日期 |
+| `month` | yyyy-MM | 月份 |
+| `year` | yyyy | 年份 |
+| `quarter` | yyyy-Qq | 季度（如 2026-Q3） |
+| `week` | yyyy-WW | 周 |
+| `datetime` | yyyy-MM-dd HH:mm | 日期时间 |
+
+## 注意事项
+
+1. **范围模式**：默认开启范围选择（`rangeMode: true`），返回值为数组 `[start, end]`
+2. **单选模式**：设置 `rangeMode: false` 后，返回值为单个日期字符串
+3. **维度切换**：切换维度时会自动关闭下拉面板，避免页面布局跳动
+4. **季度格式**：季度类型使用自定义格式 `yyyy-Qq`，如 `2026-Q3`
+5. **值类型**：所有日期值均为字符串类型，便于后端交互

package/docs/components/base/xt-flex-box.md

@@ -8,31 +8,21 @@
 ```vue
 <template>
   <XtFlexBox gap="16px">
-    <div style="width: 80px; height: 40px; background: #f0f0f0; display: flex; align-items: center; justify-content: center;">子元素1</div>
-    <div style="width: 80px; height: 40px; background: #f0f0f0; display: flex; align-items: center; justify-content: center;">子元素2</div>
-    <div style="width: 80px; height: 40px; background: #f0f0f0; display: flex; align-items: center; justify-content: center;">子元素3</div>
+    <div style="background: #1890ff; color: white; padding: 8px;">元素1</div>
+    <div style="background: #52c41a; color: white; padding: 8px;">元素2</div>
+    <div style="background: #faad14; color: white; padding: 8px;">元素3</div>
   </XtFlexBox>
 </template>
 ```
 :::
 
-## 属性说明
-| 属性 | 类型 | 默认值 | 可选值 | 说明 |
-|------|------|--------|--------|------|
-| `type` | String | flex | - | 布局类型 |
-| `align` | String | center | `start`、`center`、`end`、`stretch`、`baseline` | 交叉轴对齐方式 |
-| `content` | String | start | `start`、`center`、`end`、`between`、`around`、`evenly` | 主轴对齐方式 |
-| `direction` | String | row | `row`、`row-reverse`、`column`、`column-reverse` | 排列方向 |
-| `wrap` | String | unset | `wrap`、`nowrap`、`wrap-reverse` | 是否换行 |
-| `gap` | String | - | - | 子元素间距 |
-
 ## 示例
 
 ### 水平居中且两端对齐
 ::: demo 水平居中且两端对齐
 ```vue
 <template>
-  <XtFlexBox content="space-between" align="center">
+  <XtFlexBox content="between" align="center">
     <span>左侧内容</span>
     <span>右侧内容</span>
   </XtFlexBox>
@@ -59,11 +49,11 @@
 ::: demo 均匀分布
 ```vue
 <template>
-  <XtFlexBox content="space-around">
-    <div style="width: 60px; height: 60px; background: #e6f7ff; border-radius: 8px; display: flex; align-items: center; justify-content: center;">1</div>
-    <div style="width: 60px; height: 60px; background: #e6f7ff; border-radius: 8px; display: flex; align-items: center; justify-content: center;">2</div>
-    <div style="width: 60px; height: 60px; background: #e6f7ff; border-radius: 8px; display: flex; align-items: center; justify-content: center;">3</div>
-    <div style="width: 60px; height: 60px; background: #e6f7ff; border-radius: 8px; display: flex; align-items: center; justify-content: center;">4</div>
+  <XtFlexBox content="around">
+    <div style="background: #1890ff; color: white; padding: 8px;">元素1</div>
+    <div style="background: #52c41a; color: white; padding: 8px;">元素2</div>
+    <div style="background: #faad14; color: white; padding: 8px;">元素3</div>
+    <div style="background: #ea1d34; color: white; padding: 8px;">元素4</div>
   </XtFlexBox>
 </template>
 ```
@@ -75,7 +65,7 @@
 ```vue
 <template>
   <XtFlexBox wrap="wrap" gap="8px">
-    <div v-for="i in 10" :key="i" style="width: 80px; height: 80px; background: #f0f0f0; border-radius: 8px; display: flex; align-items: center; justify-content: center;">{{ i }}</div>
+    <div v-for="i in 10" :key="i" style="padding: 8px; background: #1890ff; color: white; width: 80px;">{{ i }}</div>
   </XtFlexBox>
 </template>
 ```
@@ -86,10 +76,10 @@
 ::: demo 反向排列
 ```vue
 <template>
-  <XtFlexBox direction="row-reverse">
-    <span style="padding: 8px; background: #f5f5f5;">第一</span>
-    <span style="padding: 8px; background: #f5f5f5;">第二</span>
-    <span style="padding: 8px; background: #f5f5f5;">第三</span>
+  <XtFlexBox direction="row-reverse" gap="8px">
+    <span style="padding: 8px; background: #1890ff; color: white; width: 80px;">第一</span>
+    <span style="padding: 8px; background: #1890ff; color: white; width: 80px;">第二</span>
+    <span style="padding: 8px; background: #1890ff; color: white; width: 80px;">第三</span>
   </XtFlexBox>
 </template>
 ```
@@ -101,7 +91,7 @@
 ```vue
 <template>
   <XtFlexBox direction="column" gap="16px">
-    <XtFlexBox content="space-between">
+    <XtFlexBox content="between">
       <span>头部左侧</span>
       <span>头部右侧</span>
     </XtFlexBox>
@@ -113,3 +103,13 @@
 </template>
 ```
 :::
+
+## 属性说明
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `type` | String | flex | - | 布局类型 |
+| `align` | String | center | `start`、`center`、`end`、`stretch`、`baseline` | 交叉轴对齐方式 |
+| `content` | String | start | `start`、`center`、`end`、`between`、`around`、`evenly` | 主轴对齐方式 |
+| `direction` | String | row | `row`、`row-reverse`、`column`、`column-reverse` | 排列方向 |
+| `wrap` | String | unset | `wrap`、`nowrap`、`wrap-reverse` | 是否换行 |
+| `gap` | String | - | - | 子元素间距 |