xt-element-ui 2.1.5 → 2.1.6

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

@@ -4,7 +4,7 @@
 
 ## 基本用法
 
-::: demo 基本用法
+::: demo 基本用法（日期范围）
 ```vue
 <template>
   <XtDatePicker v-model="dateRange" />
@@ -14,7 +14,7 @@
 export default {
   data() {
     return {
-      dateRange: []
+      dateRange: ""
     }
   }
 }
@@ -26,47 +26,100 @@ export default {
 
 | 属性 | 类型 | 默认值 | 可选值 | 说明 |
 |------|------|--------|--------|------|
-| `value` / `v-model` | Array / Date | - | - | 日期范围 `[startDate, endDate]` 或单个日期 |
+| `value` / `v-model` | Array / String | - | - | 日期范围 `[start, end]` 或单个日期字符串 |
 | `dateType` | String | `date` | `date`、`datetime`、`month`、`year`、`quarter`、`week` | 日期类型 |
-| `separator` | String | `至` | - | 分隔符文本 |
+| `separator` | String | `至` | - | 范围选择时的分隔符文本 |
 | `disabled` | Boolean | `false` | - | 是否禁用 |
-| `width` | String | `100%` | - | 组件宽度 |
+| `width` | String | `100%` | - | 组件宽度，如 `'500px'` |
 | `rangeMode` | Boolean | `true` | - | 是否为范围选择模式，false 时为单选 |
-| `showDimension` | Boolean | `false` | - | 是否显示时间维度选择器 |
-| `dimension` | String | `day` | `day`、`month`、`year`、`custom` | 当前时间维度 |
+| `showDimension` | Boolean | `false` | - | 是否显示时间维度选择器（日/月/年/自定义） |
+| `dimension` | String | `date` | `date`、`month`、`year`、`daterange` | 当前时间维度 |
+| `immediate` | Boolean | `true` | - | 切换维度后是否立即触发事件 |
 
-## 事件
+## 事件说明
 
-| 事件名 | 说明 | 参数 |
+| 事件名 | 参数 | 说明 |
 |--------|------|------|
-| `change` | 日期值改变时触发 | `[startDate, endDate]` 或 `date` |
-| `dimension-change` | 时间维度或值变化时触发 | `{ dimension, value }` |
-| `focus` | 输入框获得焦点时触发 | - |
-| `blur` | 输入框失去焦点时触发 | - |
+| `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 不同日期类型
+::: 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>
+  <XtDatePicker v-model="monthRange" dateType="month" />
 </template>
 
 <script>
 export default {
   data() {
     return {
-      dateRange: [],
-      monthRange: [],
-      yearRange: [],
-      quarterRange: []
+      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: ""
     }
   }
 }
@@ -103,7 +156,6 @@ export default {
     v-model="dateRange" 
     :show-dimension="true" 
     :dimension="currentDimension"
-    @update:dimension="currentDimension = $event"
     @dimension-change="handleDimensionChange"
   />
 </template>
@@ -112,12 +164,13 @@ export default {
 export default {
   data() {
     return {
-      dateRange: [],
-      currentDimension: 'day'
+      dateRange: "",
+      currentDimension: 'date'
     }
   },
   methods: {
     handleDimensionChange({ dimension, value }) {
+      this.currentDimension = dimension
       console.log('维度:', dimension, '值:', value)
     }
   }
@@ -138,7 +191,7 @@ export default {
 export default {
   data() {
     return {
-      dateRange: []
+      dateRange: ""
     }
   }
 }
@@ -158,7 +211,27 @@ export default {
 export default {
   data() {
     return {
-      dateRange: []
+      dateRange: ""
+    }
+  }
+}
+</script>
+```
+:::
+
+### 自定义宽度
+
+::: demo 自定义宽度
+```vue
+<template>
+  <XtDatePicker v-model="dateRange" width="600" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      dateRange: ""
     }
   }
 }
@@ -170,11 +243,28 @@ export default {
 
 当启用 `showDimension` 后，选择不同维度会有以下效果：
 
-| 维度 | 日期类型 | 选择模式 | 范围限制 |
-|------|----------|----------|----------|
-| `day` | date | 范围选择 | 无限制 |
-| `month` | month | 范围选择 | 结束日期必须与开始日期同月份 |
-| `year` | year | 范围选择 | 结束日期必须与开始日期同年份 |
-| `custom` | 保持原值 | 单选 | 用户自定义 |
+| 维度 | 日期类型 | 格式 | 说明 |
+|------|----------|------|------|
+| `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-form-schema.md

@@ -0,0 +1,358 @@
+## XtFormSchema 表单配置化搜索组件
+
+用于解决大量检索条件场景下的表单使用，支持使用抽屉或对话框显示高级搜索表单，自动展示已检索标签。
+
+## 基本用法
+
+::: demo 基本用法（抽屉模式）
+```vue
+<template>
+  <div>
+    <XtButton type="primary" @click="showForm = true">高级搜索</XtButton>
+    <XtFormSchema
+      v-model="searchForm"
+      :visible.sync="showForm"
+      :schema="schema"
+      mode="drawer"
+      title="高级搜索"
+      @confirm="handleConfirm"
+    />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      showForm: false,
+      searchForm: {},
+      schema: [
+        {
+          prop: 'name',
+          label: '姓名',
+          type: 'input',
+          placeholder: '请输入姓名'
+        },
+        {
+          prop: 'gender',
+          label: '性别',
+          type: 'select',
+          options: [
+            { value: 'male', label: '男' },
+            { value: 'female', label: '女' }
+          ]
+        },
+        {
+          prop: 'dateRange',
+          label: '时间范围',
+          type: 'daterange'
+        }
+      ]
+    }
+  },
+  methods: {
+    handleConfirm(formData) {
+      console.log('搜索条件:', formData)
+    }
+  }
+}
+</script>
+```
+:::
+
+## 属性说明
+
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `value / v-model` | Object | {} | - | 表单数据对象 |
+| `visible` | Boolean | false | - | 是否显示弹窗/抽屉 |
+| `schema` | Array | [] | - | 表单字段配置数组 |
+| `mode` | String | drawer | `dialog`、`drawer` | 展示模式：对话框或抽屉 |
+| `title` | String | 高级搜索 | - | 弹窗/抽屉标题 |
+| `width` | String / Number | 500px | - | 弹窗/抽屉宽度 |
+| `direction` | String | rtl | `ltr`、`rtl`、`ttb`、`btt` | 抽屉弹出方向 |
+| `showSearchTags` | Boolean | true | - | 是否显示已检索标签 |
+| `simpleFields` | Array | [] | - | 页面上简单展示的字段 |
+
+## schema 字段配置说明
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `prop` | String | 是 | 字段名，对应表单数据的 key |
+| `label` | String | 是 | 字段标签 |
+| `type` | String | 是 | 字段类型，见下表 |
+| `placeholder` | String | 否 | 占位提示 |
+| `defaultValue` | Any | 否 | 默认值 |
+| `options` | Array | 否 | 下拉选项，用于 select/radio-group/checkbox-group |
+| `disabled` | Boolean | 否 | 是否禁用 |
+| `size` | String | 否 | 字段尺寸 |
+| `filterable` | Boolean | 否 | 是否可搜索（select） |
+| `multiple` | Boolean | 否 | 是否多选（select） |
+| `format` | String | 否 | 日期格式化（date-picker） |
+| `valueFormat` | String | 否 | 日期值格式（date-picker） |
+| `dateType` | String | 否 | 日期类型（date-picker） |
+| `min` | Number | 否 | 最小值（number） |
+| `max` | Number | 否 | 最大值（number） |
+| `step` | Number | 否 | 步长（number） |
+| `rows` | Number | 否 | 行数（textarea） |
+
+## 支持的字段类型
+
+| 类型 | 说明 | 对应 Element 组件 |
+|------|------|-------------------|
+| `input` | 文本输入 | el-input |
+| `textarea` | 多行文本 | el-input(type="textarea") |
+| `select` | 下拉选择 | el-select |
+| `checkbox` | 单选框 | el-checkbox |
+| `checkbox-group` | 多选框组 | el-checkbox-group |
+| `radio` | 单选按钮 | el-radio |
+| `radio-group` | 单选按钮组 | el-radio-group |
+| `date` | 日期选择 | el-date-picker |
+| `daterange` | 日期范围 | el-date-picker(type="daterange") |
+| `datetime` | 日期时间 | el-date-picker(type="datetime") |
+| `datetime-range` | 日期时间范围 | el-date-picker(type="datetimerange") |
+| `number` | 数字输入 | el-input-number |
+| `switch` | 开关 | el-switch |
+
+## 事件说明
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `input` | `formData` | 表单数据变化时触发 |
+| `change` | `{ prop, value }` | 单个字段值变化时触发 |
+| `confirm` | `formData` | 点击确认按钮时触发 |
+| `cancel` | - | 点击取消按钮或关闭时触发 |
+
+## 方法说明
+
+| 方法名 | 参数 | 说明 |
+|--------|------|------|
+| `resetFields` | - | 重置表单到默认值 |
+
+## 示例
+
+### 对话框模式
+
+::: demo 对话框模式
+```vue
+<template>
+  <div>
+    <XtButton type="primary" @click="showForm = true">高级搜索（对话框）</XtButton>
+    <XtFormSchema
+      v-model="searchForm"
+      :visible.sync="showForm"
+      :schema="schema"
+      mode="dialog"
+      width="600px"
+      title="高级搜索"
+      @confirm="handleConfirm"
+    />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      showForm: false,
+      searchForm: {},
+      schema: [
+        {
+          prop: 'name',
+          label: '姓名',
+          type: 'input',
+          placeholder: '请输入姓名'
+        },
+        {
+          prop: 'status',
+          label: '状态',
+          type: 'select',
+          options: [
+            { value: 'active', label: '活跃' },
+            { value: 'inactive', label: '不活跃' },
+            { value: 'pending', label: '待审核' }
+          ],
+          filterable: true
+        }
+      ]
+    }
+  },
+  methods: {
+    handleConfirm(formData) {
+      console.log('搜索条件:', formData)
+    }
+  }
+}
+</script>
+```
+:::
+
+### 包含日期范围和多选框
+
+::: demo 包含日期范围和多选框
+```vue
+<template>
+  <div>
+    <XtButton type="primary" @click="showForm = true">高级搜索</XtButton>
+    <XtFormSchema
+      v-model="searchForm"
+      :visible.sync="showForm"
+      :schema="schema"
+      @confirm="handleConfirm"
+    />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      showForm: false,
+      searchForm: {},
+      schema: [
+        {
+          prop: 'keywords',
+          label: '关键词',
+          type: 'input',
+          placeholder: '请输入关键词'
+        },
+        {
+          prop: 'type',
+          label: '类型',
+          type: 'checkbox-group',
+          options: [
+            { value: 'article', label: '文章' },
+            { value: 'video', label: '视频' },
+            { value: 'image', label: '图片' }
+          ]
+        },
+        {
+          prop: 'dateRange',
+          label: '发布时间',
+          type: 'daterange',
+          format: 'yyyy-MM-dd'
+        }
+      ]
+    }
+  },
+  methods: {
+    handleConfirm(formData) {
+      console.log('搜索条件:', formData)
+    }
+  }
+}
+</script>
+```
+:::
+
+### 完整搜索示例
+
+::: demo 完整搜索示例
+```vue
+<template>
+  <div>
+    <XtFlexBox class="search-bar" style="gap: 12px; margin-bottom: 16px;">
+      <XtInput v-model="searchForm.name" placeholder="姓名" style="width: 200px;" />
+      <XtInput v-model="searchForm.phone" placeholder="手机号" style="width: 200px;" />
+      <XtButton type="primary" @click="showForm = true">高级搜索</XtButton>
+      <XtButton @click="handleReset">重置</XtButton>
+    </XtFlexBox>
+
+    <XtFormSchema
+      ref="formSchema"
+      v-model="searchForm"
+      :visible.sync="showForm"
+      :schema="schema"
+      mode="drawer"
+      title="高级搜索"
+      @confirm="handleSearch"
+    />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      showForm: false,
+      searchForm: {
+        name: '',
+        phone: '',
+        gender: '',
+        department: '',
+        dateRange: [],
+        status: []
+      },
+      schema: [
+        {
+          prop: 'gender',
+          label: '性别',
+          type: 'select',
+          options: [
+            { value: 'male', label: '男' },
+            { value: 'female', label: '女' }
+          ]
+        },
+        {
+          prop: 'department',
+          label: '部门',
+          type: 'select',
+          options: [
+            { value: 'tech', label: '技术部' },
+            { value: 'sales', label: '销售部' },
+            { value: 'hr', label: '人事部' }
+          ],
+          filterable: true
+        },
+        {
+          prop: 'dateRange',
+          label: '入职时间',
+          type: 'daterange'
+        },
+        {
+          prop: 'status',
+          label: '状态',
+          type: 'checkbox-group',
+          options: [
+            { value: 'active', label: '在职' },
+            { value: 'leave', label: '休假' },
+            { value: 'resigned', label: '离职' }
+          ]
+        },
+        {
+          prop: 'score',
+          label: '绩效评分',
+          type: 'number',
+          min: 0,
+          max: 100
+        }
+      ]
+    }
+  },
+  methods: {
+    handleSearch(formData) {
+      console.log('搜索条件:', formData)
+    },
+    handleReset() {
+      this.searchForm = {
+        name: '',
+        phone: '',
+        gender: '',
+        department: '',
+        dateRange: [],
+        status: []
+      }
+      this.$refs.formSchema.resetFields()
+    }
+  }
+}
+</script>
+```
+:::
+
+## 注意事项
+
+1. 表单数据通过 `v-model` 双向绑定，页面上的简单搜索字段和组件内的字段会自动同步
+2. `showSearchTags` 开启后，已选择的条件会自动展示为标签，点击标签右侧的关闭按钮可清除对应条件
+3. `schema` 中的 `prop` 需要与 `v-model` 对象的 key 对应
+4. 组件支持通过 `ref` 调用 `resetFields` 方法重置表单

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

@@ -42,10 +42,10 @@
 
 | 属性 | 类型 | 默认值 | 可选值 | 说明 |
 |------|------|--------|--------|------|
-| `span` | Number | `1` | >0 | 跨列数 |
-| `rowSpan` | Number | `1` | >0 | 跨行数 |
-| `start` | Number | `0` | >=0 | 起始列位置 |
-| `rowStart` | Number | `0` | >=0 | 起始行位置 |
+| `span` | Number | `1` | >1 | 跨列数 |
+| `rowSpan` | Number | `1` | >1 | 跨行数 |
+| `start` | Number | `0` | >0 | 起始列位置 |
+| `rowStart` | Number | `0` | >0 | 起始行位置 |
 | `area` | String | - | - | 命名区域名称 |
 | `justifySelf` | String | `auto` | `auto`、`start`、`end`、`center`、`stretch` | 水平对齐 |
 | `alignSelf` | String | `auto` | `auto`、`start`、`end`、`center`、`stretch`、`baseline` | 垂直对齐 |