xt-element-ui 2.1.22 → 2.1.72

package/docs/components/base/xt-form-schema.md

@@ -0,0 +1,356 @@
+用于解决大量检索条件场景下的表单使用，支持使用抽屉或对话框显示高级搜索表单，自动展示已检索标签。
+
+## 基本用法
+
+::: 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

@@ -1,5 +1,3 @@
-## XtGridBox 网格布局组件
-
 基于 CSS Grid 实现的网格布局组件，提供强大的二维布局能力，支持响应式设计和灵活的配置选项。
 
 ## 基本用法
@@ -42,10 +40,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` | 垂直对齐 |

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

@@ -1,5 +1,3 @@
-## XtIcon 图标组件
-
 图标组件支持多种图标类型：ElementUI 字体图标、SVG Sprite、内联 SVG 和自定义字体图标。
 
 ## 基本用法

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

@@ -1,6 +1,4 @@
-## XtInput 输入框组件
-
-输入框组件用于收集用户输入的信息。
+输入框组件用于收集用户输入的信息，支持多种输入场景和格式校验。
 
 ## 基本用法
 
@@ -23,26 +21,147 @@ export default {
 :::
 
 ## 属性说明
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `value` | String / Number | - | 输入值（支持 v-model） |
-| `placeholder` | String | '请输入内容' | 占位提示文本 |
-| `color` | String | - | 自定义聚焦颜色 |
+
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `value` | String / Number | - | - | 输入值（支持 v-model） |
+| `placeholder` | String | '请输入内容' | - | 占位提示文本 |
+| `type` | String | 'text' | 见下表 | 输入类型 |
+| `size` | String | - | 'small'、'medium'、'large' | 输入框尺寸 |
+| `disabled` | Boolean | false | - | 是否禁用 |
+| `readonly` | Boolean | false | - | 是否只读 |
+| `color` | String | - | - | 自定义聚焦颜色 |
+| `precision` | Number | 2 | 0-10 | 小数位数（数字类型） |
+| `min` | Number | undefined | - | 最小值（数字类型） |
+| `max` | Number | undefined | - | 最大值（数字类型） |
+| `allowNegative` | Boolean | false | - | 是否允许负数（数字类型） |
+| `thousandSeparator` | Boolean | false | - | 是否显示千分位分隔符 |
+| `maxlength` | Number | undefined | - | 最大输入长度 |
+| `showWordLimit` | Boolean | false | - | 是否显示字数统计 |
+| `prefixIcon` | String | - | - | 前缀图标 |
+| `suffixIcon` | String | - | - | 后缀图标 |
+| `trim` | Boolean | false | - | 是否自动去除首尾空格 |
+
+## 支持的输入类型
+
+| 类型 | 说明 | 特性 |
+|------|------|------|
+| `text` | 普通文本 | 默认类型，支持所有字符 |
+| `number` | 数字输入 | 支持整数和小数，可配置精度 |
+| `integer` | 整数输入 | 仅允许整数，自动过滤小数 |
+| `decimal` | 小数输入 | 支持小数，精度可配置 |
+| `money` | 金额输入 | 支持小数，默认2位精度，适合金额场景 |
+| `phone` | 手机号输入 | 自动过滤非数字，校验手机号格式 |
+| `email` | 邮箱输入 | 实时校验邮箱格式，错误时标红 |
+| `idcard` | 身份证输入 | 自动过滤非法字符，校验身份证格式 |
+| `password` | 密码输入 | 密码隐藏显示 |
+| `textarea` | 多行文本 | 多行输入框 |
+
+## 事件说明
+
+| 事件名 | 参数 | 说明 |
+|--------|------|------|
+| `input` | `value` | 输入值变化时触发 |
+| `change` | `value` | 输入框失去焦点且值变化时触发 |
+| `focus` | `event` | 输入框获得焦点时触发 |
+| `blur` | `value, event` | 输入框失去焦点时触发 |
+| `clear` | - | 点击清除按钮时触发 |
 
 ## 示例
 
-### 基础输入框
-::: demo 基础输入框
+### 整数输入
+
+::: demo 整数输入
+```vue
+<template>
+  <XtInput v-model="count" type="integer" placeholder="请输入整数"></XtInput>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      count: ''
+    }
+  }
+}
+</script>
+```
+:::
+
+### 小数输入（自定义精度）
+
+::: demo 小数输入
+```vue
+<template>
+  <XtInput v-model="price" type="decimal" :precision="4" placeholder="最多4位小数"></XtInput>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      price: ''
+    }
+  }
+}
+</script>
+```
+:::
+
+### 金额输入（带千分位）
+
+::: demo 金额输入
+```vue
+<template>
+  <XtInput v-model="amount" type="money" thousandSeparator placeholder="请输入金额"></XtInput>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      amount: ''
+    }
+  }
+}
+</script>
+```
+:::
+
+### 数字输入（带范围限制）
+
+::: demo 数字输入范围限制
+```vue
+<template>
+  <XtInput v-model="score" type="number" :min="0" :max="100" placeholder="0-100"></XtInput>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      score: ''
+    }
+  }
+}
+</script>
+```
+:::
+
+### 手机号输入
+
+::: demo 手机号输入
 ```vue
 <template>
-  <XtInput v-model="username" placeholder="请输入用户名"></XtInput>
+  <XtInput v-model="phone" type="phone" placeholder="请输入手机号"></XtInput>
 </template>
 
 <script>
 export default {
   data() {
     return {
-      username: ''
+      phone: ''
     }
   }
 }
@@ -50,12 +169,12 @@ export default {
 ```
 :::
 
-### 自定义占位符
+### 邮箱输入（格式校验）
 
-::: demo 自定义占位符
+::: demo 邮箱输入
 ```vue
 <template>
-  <XtInput v-model="email" placeholder="请输入您的邮箱地址"></XtInput>
+  <XtInput v-model="email" type="email" placeholder="请输入邮箱"></XtInput>
 </template>
 
 <script>
@@ -70,7 +189,68 @@ export default {
 ```
 :::
 
+### 身份证输入
+
+::: demo 身份证输入
+```vue
+<template>
+  <XtInput v-model="idcard" type="idcard" placeholder="请输入身份证号"></XtInput>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      idcard: ''
+    }
+  }
+}
+</script>
+```
+:::
+
+### 密码输入
+
+::: demo 密码输入
+```vue
+<template>
+  <XtInput v-model="password" type="password" placeholder="请输入密码"></XtInput>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      password: ''
+    }
+  }
+}
+</script>
+```
+:::
+
+### 多行文本
+
+::: demo 多行文本
+```vue
+<template>
+  <XtInput v-model="content" type="textarea" :maxlength="200" showWordLimit placeholder="请输入内容"></XtInput>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      content: ''
+    }
+  }
+}
+</script>
+```
+:::
+
 ### 自定义聚焦颜色
+
 ::: demo 自定义聚焦颜色
 ```vue
 <template>
@@ -102,8 +282,8 @@ export default {
 <template>
   <div style="display: flex; flex-direction: column; gap: 12px;">
     <XtInput v-model="name" placeholder="姓名"></XtInput>
-    <XtInput v-model="phone" placeholder="手机"></XtInput>
-    <XtInput v-model="address" placeholder="地址"></XtInput>
+    <XtInput v-model="phone" type="phone" placeholder="手机"></XtInput>
+    <XtInput v-model="email" type="email" placeholder="邮箱"></XtInput>
   </div>
 </template>
 
@@ -113,7 +293,7 @@ export default {
     return {
       name: '',
       phone: '',
-      address: ''
+      email: ''
     }
   }
 }
@@ -121,30 +301,10 @@ export default {
 ```
 :::
 
-### 监听输入事件
+## 注意事项
 
-::: demo 监听输入事件
-```vue
-<template>
-  <div>
-    <XtInput :value="inputValue" placeholder="实时监听输入" @input="handleInput"></XtInput>
-    <p style="margin-top: 12px;">输入长度: {{ inputValue.length }}</p>
-  </div>
-</template>
-
-<script>
-export default {
-  data() {
-    return {
-      inputValue: ''
-    }
-  },
-  methods: {
-    handleInput(value) {
-      this.inputValue = value
-    }
-  }
-}
-</script>
-```
-:::
+1. **数字类型输入**：`type="number"`、`type="integer"`、`type="decimal"`、`type="money"` 返回的是 Number 类型，空值时返回 undefined
+2. **小数精度**：`precision` 属性控制小数位数，blur 时自动四舍五入
+3. **千分位显示**：`thousandSeparator` 仅影响显示，实际绑定的值不包含千分位分隔符
+4. **负数控制**：`allowNegative` 默认 false，数字类型输入不允许负数
+5. **范围限制**：`min` 和 `max` 在输入时自动限制，超出范围自动修正