xdc-ui-lib 1.0.3 → 1.0.4

package/README.md

@@ -1,11 +1,1110 @@
-# xdc-ui-lib
-
-Vue 3 组件库，包含常用的业务组件。
-
-## 组件列表
-
-- **CategorySearch**: 分类搜索组件
-- **BaseModal**: 模态框组件
-- **BaseForm**: 动态表单组件
-- **FileUpload**: 文件上传组件
-
+# xdc-ui-lib
+
+Vue 3 组件库，包含常用的业务组件。
+
+## 组件列表
+
+- **CategorySearch**: 分类搜索组件
+- **BaseModal**: 模态框组件
+- **BaseForm**: 动态表单组件
+- **FileUpload**: 文件上传组件
+
+## CategorySearch 分类搜索组件
+
+一个功能强大的分类搜索组件，支持多种筛选类型和列设置功能。
+
+### 基本用法
+
+```vue
+<template>
+  <CategorySearch
+    :loading="loading"
+    :filter-types="filterTypes"
+    :columns="columns"
+    @search="handleSearch"
+  />
+</template>
+
+<script setup>
+import { CategorySearch } from 'xdc-ui-lib';
+
+const filterTypes = [
+  {
+    id: 'name',
+    label: '名称',
+    type: 'input',
+    placeholder: '请输入名称'
+  },
+  {
+    id: 'status',
+    label: '状态',
+    type: 'select',
+    options: [
+      { label: '启用', value: 1 },
+      { label: '禁用', value: 0 }
+    ]
+  }
+];
+
+const columns = [
+  { title: '名称', dataIndex: 'name' },
+  { title: '状态', dataIndex: 'status' }
+];
+</script>
+```
+
+### 支持的筛选类型
+
+- `input`: 文本输入
+- `textarea`: 多行文本
+- `select`: 下拉选择
+- `cascader`: 级联选择
+- `treeSelect`: 树形选择
+- `checkbox`: 多选框
+- `radio`: 单选框
+- `date`: 日期选择
+- `datetime`: 日期时间选择
+- `dateRange`: 日期范围
+- `datetimeRange`: 日期时间范围
+- `time`: 时间选择
+- `numberRange`: 数字范围
+- `rate`: 评分
+- `slider`: 滑块
+- `switch`: 开关
+- `slot`: 自定义插槽
+
+### 高级功能
+
+#### 1. 表单模式 (type="form")
+
+```vue
+<template>
+  <CategorySearch
+    type="form"
+    :filter-types="filterTypes"
+    :form-layout="'vertical'"
+    :form-span="8"
+    v-model:filter-value="searchParams"
+    @search="handleSearch"
+  />
+</template>
+```
+
+#### 2. 列设置功能
+
+```vue
+<template>
+  <CategorySearch
+    :show-setting-columns="true"
+    :columns="columns"
+    :disabled-columns="['id', 'name']"
+    @columns-change="handleColumnsChange"
+  />
+</template>
+```
+
+#### 3. 自定义插槽
+
+```vue
+<template>
+  <CategorySearch :filter-types="filterTypes">
+    <template #filter-slots="{ filter, filterTemp, confirm }">
+      <CustomComponent 
+        v-if="filter.id === 'customField'"
+        v-model:value="filterTemp[filter.id]"
+        @change="confirm"
+      />
+    </template>
+  </CategorySearch>
+</template>
+```
+
+#### 4. 国际化支持
+
+```javascript
+const filterTypes = [
+  {
+    id: 'status',
+    type: 'select',
+    label: $t('table.probe') + $t('table.Blank') + $t('table.Status'),
+    options: [...]
+  }
+];
+```
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| type | 搜索模式 | 'input' \| 'form' | 'input' |
+| filterValue | 默认的筛选条件 | object | {} |
+| loading | 加载状态 | boolean | - |
+| filterTypes | 筛选类型配置 | array | [] |
+| placeholder | 输入框占位符 | string | '点击选择搜索条件' |
+| storageKey | 存储键，如果提供则使用，否则自动生成 | string | '' |
+| hideRefresh | 是否隐藏刷新按钮 | boolean | false |
+| showSwitch | 是否显示切换按钮 | boolean | false |
+| showSave | 是否显示保存按钮 | boolean | false |
+| showSettingColumns | 是否显示列设置 | boolean | true |
+| columns | 表格列配置 | array | [] |
+| disabledColumns | 禁用的列 | array | ['id', 'name'] |
+| isDefaultSearch | 是否默认执行搜索 | boolean | true |
+| formLayout | 表单布局 | 'horizontal' \| 'vertical' \| 'grid' | 'horizontal' |
+| formSpan | 表单网格列数 | number | 2 |
+| labelBorder | 是否显示标签边框 | boolean | false |
+
+### 存储键生成规则
+
+组件会根据以下规则生成存储键：
+
+1. **如果提供了 `storageKey`**：直接使用提供的值
+2. **如果没有提供 `storageKey`**：自动生成基于页面路径和配置的唯一键
+
+#### 自动生成存储键
+
+当没有提供 `storageKey` 时，组件会自动生成一个基于以下信息的唯一存储键：
+- 当前页面路径
+- 筛选类型配置
+- 表格列配置
+
+生成的键格式为：`category_search_auto_${hash}`
+
+这样可以确保每个页面和配置组合都有唯一的存储键，避免数据冲突。
+
+### 在 Vue Router 项目中使用
+
+```vue
+<template>
+  <!-- 使用路由名称作为存储键 -->
+  <CategorySearch
+    :storage-key="`search-${$route.name}`"
+    :loading="loading"
+    :filter-types="filterTypes"
+    @search="handleSearch"
+  />
+</template>
+```
+
+### 在非路由项目中使用
+
+```vue
+<template>
+  <CategorySearch
+    storage-key="user-list-search"
+    :loading="loading"
+    :filter-types="filterTypes"
+    @search="handleSearch"
+  />
+</template>
+```
+
+### 使用自动生成存储键
+
+```vue
+<template>
+  <!-- 不提供 storageKey，自动生成 -->
+  <CategorySearch
+    :loading="loading"
+    :filter-types="filterTypes"
+    :columns="columns"
+    @search="handleSearch"
+  />
+</template>
+```
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| search | 搜索事件 | (params: object) |
+| switch | 切换事件 | (filters: array) |
+| clear | 清空事件 | - |
+| reset | 重置事件 | - |
+| columnsChange | 列变化事件 | (columns: array) |
+| update:columns | 列更新事件 | (columns: array) |
+| update:filterValue | 筛选值更新事件 | (value: object) |
+
+## BaseForm 动态表单组件
+
+一个功能强大的动态表单组件，支持多种表单元素类型、布局方式和自定义功能。
+
+### 基本用法
+
+```vue
+<template>
+  <BaseForm
+    v-model="formData"
+    :items="formItems"
+    :submit-loading="loading"
+    submit-text="提交"
+    @submit="handleSubmit"
+  />
+</template>
+
+<script setup>
+import { BaseForm } from 'xdc-ui-lib';
+
+const formData = reactive({
+  username: '',
+  email: '',
+  age: null,
+  gender: '',
+  hobbies: []
+});
+
+const formItems = [
+  {
+    name: 'username',
+    label: '用户名',
+    type: 'input',
+    placeholder: '请输入用户名',
+    required: true,
+    rules: [
+      { required: true, message: '请输入用户名' },
+      { min: 3, max: 20, message: '用户名长度为3-20个字符' }
+    ]
+  },
+  {
+    name: 'email',
+    label: '邮箱',
+    type: 'input',
+    placeholder: '请输入邮箱',
+    required: true,
+    rules: [
+      { required: true, message: '请输入邮箱' },
+      { type: 'email', message: '请输入正确的邮箱格式' }
+    ]
+  },
+  {
+    name: 'age',
+    label: '年龄',
+    type: 'number',
+    min: 0,
+    max: 120
+  },
+  {
+    name: 'gender',
+    label: '性别',
+    type: 'radio',
+    options: [
+      { label: '男', value: 'male' },
+      { label: '女', value: 'female' }
+    ]
+  },
+  {
+    name: 'hobbies',
+    label: '兴趣爱好',
+    type: 'checkbox',
+    options: [
+      { label: '读书', value: 'reading' },
+      { label: '运动', value: 'sports' },
+      { label: '音乐', value: 'music' }
+    ]
+  }
+];
+</script>
+```
+
+### 支持的表单元素类型
+
+- `input`: 文本输入框
+- `password`: 密码输入框
+- `textarea`: 多行文本框
+- `number`: 数字输入框
+- `select`: 下拉选择器
+- `treeSelect`: 树形选择器
+- `radio`: 单选框组
+- `checkbox`: 复选框组
+- `checkbox-single`: 单个复选框
+- `switch`: 开关
+- `date`: 日期选择器
+- `time`: 时间选择器
+- `dateRange`: 日期范围选择器
+- `slider`: 滑块
+- `rate`: 评分
+- `custom`: 自定义组件
+
+### 布局方式
+
+#### 1. 水平布局 (默认)
+
+```vue
+<BaseForm
+  :items="formItems"
+  layout="horizontal"
+  :label-col="{ span: 4 }"
+  :wrapper-col="{ span: 20 }"
+/>
+```
+
+#### 2. 垂直布局
+
+```vue
+<BaseForm
+  :items="formItems"
+  layout="vertical"
+/>
+```
+
+#### 3. 网格布局
+
+```vue
+<BaseForm
+  :items="formItems"
+  layout="grid"
+  :columns="3"
+/>
+```
+
+### 自定义插槽
+
+#### 1. 自定义表单项
+
+```vue
+<BaseForm :items="formItems">
+  <template #field-customField="{ item, modelValue, updateValue }">
+    <div class="custom-field">
+      <a-input 
+        :value="modelValue" 
+        placeholder="自定义字段"
+        @input="(e) => updateValue(e.target.value)" 
+      />
+    </div>
+  </template>
+</BaseForm>
+```
+
+#### 2. 自定义操作按钮
+
+```vue
+<BaseForm :items="formItems" :show-actions="true">
+  <template #actions="{ submit, reset, validateForm, formData, loading }">
+    <a-space>
+      <a-button type="primary" :loading="loading" @click="submit">
+        确认提交
+      </a-button>
+      <a-button @click="reset">重置</a-button>
+      <a-button type="dashed" @click="handlePreview">
+        预览数据
+      </a-button>
+    </a-space>
+  </template>
+</BaseForm>
+```
+
+#### 3. 自定义表单项前缀/后缀
+
+```vue
+<BaseForm :items="formItems">
+  <!-- 只在 input 类型的表单项中可用 -->
+  <template #username-prefix>
+    <UserOutlined />
+  </template>
+  <template #username-suffix>
+    <InfoCircleOutlined />
+  </template>
+  <template #username-after="{ item, value }">
+    <small>用户名将用于登录</small>
+  </template>
+</BaseForm>
+```
+
+#### 4. 自定义整个表单项
+
+```vue
+<BaseForm :items="formItems">
+  <template #form-item-customField="{ item, modelValue, updateValue }">
+    <a-form-item :label="item.label">
+      <div class="custom-form-item">
+        <a-input :value="modelValue" placeholder="自定义表单项" @input="(e) => updateValue(e.target.value)" />
+        <small>这是完全自定义的表单项</small>
+      </div>
+    </a-form-item>
+  </template>
+</BaseForm>
+```
+
+#### 5. 自定义表单项插槽
+
+```vue
+<BaseForm :items="formItems">
+  <template #custom-items="{ formData, updateField, formRef }">
+    <a-form-item label="自定义表单项">
+      <a-input v-model:value="formData.customField" placeholder="自定义字段" />
+    </a-form-item>
+  </template>
+</BaseForm>
+```
+
+### 复杂表单示例
+
+```vue
+<template>
+  <BaseForm
+    ref="formRef"
+    v-model="formData"
+    :items="formItems"
+    :initial-values="initialValues"
+    :submit-loading="loading"
+    submit-text="创建用户"
+    @submit="handleSubmit"
+    @field-change="handleFieldChange"
+  >
+    <!-- 头像上传自定义字段 -->
+    <template #field-avatar="{ modelValue, updateValue }">
+      <div class="avatar-upload">
+        <a-upload
+          name="avatar"
+          list-type="picture-card"
+          :show-upload-list="false"
+          :before-upload="beforeUpload"
+          @change="(info) => handleAvatarChange(info, updateValue)"
+        >
+          <img v-if="modelValue" :src="modelValue" alt="avatar" />
+          <div v-else>
+            <PlusOutlined />
+            <div>上传头像</div>
+          </div>
+        </a-upload>
+      </div>
+    </template>
+
+    <!-- 技能标签自定义字段 -->
+    <template #field-skills="{ modelValue, updateValue }">
+      <a-select
+        :value="modelValue"
+        mode="tags"
+        placeholder="输入技能并按回车添加"
+        @change="updateValue"
+      />
+    </template>
+  </BaseForm>
+</template>
+```
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| modelValue | 表单数据模型 | object | {} |
+| items | 表单项配置数组 | array | [] |
+| layout | 表单布局 | 'horizontal' \| 'vertical' \| 'grid' | 'horizontal' |
+| columns | 网格布局列数 | number | 2 |
+| labelCol | 标签列配置 | object | { span: 4 } |
+| wrapperCol | 控件列配置 | object | { span: 20 } |
+| colon | 是否显示冒号 | boolean | true |
+| labelAlign | 标签对齐方式 | 'left' \| 'right' | 'right' |
+| scrollToFirstError | 是否滚动到第一个错误字段 | boolean | true |
+| showActions | 是否显示操作按钮 | boolean | false |
+| hideDefaultActions | 是否隐藏默认操作按钮 | boolean | false |
+| showReset | 是否显示重置按钮 | boolean | true |
+| submitText | 提交按钮文本 | string | '提交' |
+| resetText | 重置按钮文本 | string | '重置' |
+| submitLoading | 提交时是否显示加载状态 | boolean | false |
+| initialValues | 初始值 | object | {} |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| update:modelValue | 模型值更新事件 | (value: object) |
+| submit | 提交事件 | (values: object) |
+| reset | 重置事件 | (values: object) |
+| finish | 表单提交成功事件 | (values: object) |
+| finish-failed | 表单提交失败事件 | (errorInfo: any) |
+| values-change | 表单值变化事件 | (changedValues: object, values: object) |
+| field-change | 字段值变化事件 | (name: string, value: any, item: object) |
+| field-blur | 字段失焦事件 | (name: string, value: any, item: object) |
+| field-search | 字段搜索事件 | (name: string, value: string, item: object) |
+| field-press-enter | 字段回车事件 | (name: string, value: any, item: object) |
+
+### 组件方法
+
+| 方法名 | 说明 | 参数 |
+|--------|------|------|
+| validateForm | 验证表单 | (nameList?: string[]) |
+| validateFields | 验证指定字段 | (nameList?: string[]) |
+| clearValidate | 清除验证状态 | (nameList?: string[]) |
+| setFieldsValue | 设置字段值 | (values: object) |
+| getFieldsValue | 获取字段值 | (nameList?: string[]) |
+| handleSubmit | 手动提交表单 | - |
+| handleReset | 重置表单 | - |
+| updateFieldValue | 更新字段值 | (name: string, value: any) |
+| updateFieldOptions | 更新字段选项 | (fieldName: string, options: array) |
+| updateFieldTreeData | 更新树形数据 | (fieldName: string, treeData: array) |
+| updateFieldConfig | 更新字段配置 | (fieldName: string, config: object) |
+| setFieldsValueWithTrigger | 批量设置字段值（支持联动） | (values: object, triggerChange?: boolean) |
+| currentFormItems | 当前表单项配置（响应式） | - |
+
+### 表单项配置详解
+
+#### 基础配置
+
+```javascript
+{
+  name: 'fieldName',        // 字段名（必填）
+  label: '字段标签',        // 标签文本
+  type: 'input',           // 表单元素类型
+  placeholder: '请输入',    // 占位符
+  disabled: false,         // 是否禁用
+  required: false,         // 是否必填
+  hidden: false,           // 是否隐藏
+  rules: [],              // 验证规则
+  help: '帮助信息',        // 帮助文本
+  extra: '额外信息'        // 额外信息
+}
+```
+
+#### 输入框配置
+
+```javascript
+{
+  name: 'username',
+  type: 'input',
+  maxLength: 20,          // 最大字符长度
+  showCount: true,        // 显示字符计数
+  prefix: '用户',         // 前缀
+  suffix: '@example.com', // 后缀
+  addonBefore: 'http://', // 前置标签
+  addonAfter: '.com'      // 后置标签
+}
+```
+
+#### 选择器配置
+
+```javascript
+{
+  name: 'category',
+  type: 'select',
+  options: [
+    { label: '选项1', value: 'value1' },
+    { label: '选项2', value: 'value2' }
+  ],
+  showSearch: true,       // 显示搜索
+  mode: 'multiple',       // 多选模式
+  maxTagCount: 3,         // 最多显示标签数
+  loading: false          // 加载状态
+}
+```
+
+#### 日期时间配置
+
+```javascript
+{
+  name: 'birthday',
+  type: 'date',
+  format: 'YYYY-MM-DD',   // 显示格式
+  valueFormat: 'YYYY-MM-DD', // 值格式
+  picker: 'date',         // 选择器类型
+  showTime: false,        // 是否显示时间
+  disabledDate: (date) => date && date > dayjs().endOf('day') // 禁用日期
+}
+```
+
+#### 验证规则配置
+
+```javascript
+{
+  name: 'email',
+  type: 'input',
+  rules: [
+    { required: true, message: '请输入邮箱' },
+    { type: 'email', message: '请输入正确的邮箱格式' },
+    { min: 5, max: 50, message: '邮箱长度为5-50个字符' },
+    { pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, message: '邮箱格式不正确' }
+  ]
+}
+```
+
+#### 树形选择器配置
+
+```javascript
+{
+  name: 'department',
+  type: 'treeSelect',
+  treeData: [
+    {
+      title: '技术部',
+      value: 'tech',
+      children: [
+        { title: '前端组', value: 'frontend' },
+        { title: '后端组', value: 'backend' }
+      ]
+    }
+  ],
+  showSearch: true,
+  multiple: false,
+  treeCheckable: false,
+  treeDefaultExpandAll: true
+}
+```
+
+#### 单选框配置
+
+```javascript
+{
+  name: 'gender',
+  type: 'radio',
+  optionType: 'button', // 'default' | 'button'
+  buttonStyle: 'outline', // 'outline' | 'solid'
+  size: 'middle', // 'large' | 'middle' | 'small'
+  options: [
+    { label: '男', value: 'male' },
+    { label: '女', value: 'female' }
+  ]
+}
+```
+
+#### 开关配置
+
+```javascript
+{
+  name: 'enabled',
+  type: 'switch',
+  checkedChildren: '开启',
+  unCheckedChildren: '关闭',
+  checkedValue: true,
+  unCheckedValue: false,
+  size: 'default' // 'default' | 'small'
+}
+```
+
+#### 滑块配置
+
+```javascript
+{
+  name: 'quality',
+  type: 'slider',
+  min: 0,
+  max: 100,
+  step: 1,
+  range: false, // 是否为范围选择
+  marks: {
+    0: '低',
+    50: '中',
+    100: '高'
+  },
+  dots: false,
+  included: true,
+  tooltip: { formatter: (value) => `${value}%` }
+}
+```
+
+#### 评分配置
+
+```javascript
+{
+  name: 'rating',
+  type: 'rate',
+  count: 5,
+  allowHalf: true,
+  allowClear: true,
+  character: '★',
+  tooltips: ['很差', '差', '一般', '好', '很好']
+}
+```
+
+#### 自定义组件配置
+
+```javascript
+{
+  name: 'customField',
+  type: 'custom',
+  component: CustomComponent,
+  props: {
+    // 传递给自定义组件的属性
+    customProp: 'value'
+  }
+}
+```
+
+### 动态更新功能
+
+#### 1. 动态更新字段选项
+
+```javascript
+const formRef = ref();
+
+// 更新选择器选项
+formRef.value?.updateFieldOptions('category', [
+  { label: '新选项1', value: 'new1' },
+  { label: '新选项2', value: 'new2' }
+]);
+```
+
+#### 2. 动态更新树形数据
+
+```javascript
+// 更新树形选择器数据
+formRef.value?.updateFieldTreeData('department', [
+  {
+    title: '技术部',
+    value: 'tech',
+    children: [
+      { title: '前端组', value: 'frontend' },
+      { title: '后端组', value: 'backend' }
+    ]
+  }
+]);
+```
+
+#### 3. 动态更新字段配置
+
+```javascript
+// 更新字段的整个配置
+formRef.value?.updateFieldConfig('username', {
+  disabled: true,
+  placeholder: '用户名已被锁定'
+});
+```
+
+#### 4. 批量设置字段值
+
+```javascript
+// 批量设置字段值，支持联动
+formRef.value?.setFieldsValueWithTrigger({
+  department: 'tech',
+  position: 'developer',
+  skills: ['javascript', 'vue']
+}, true); // 第二个参数表示是否触发 change 事件
+```
+
+#### 5. 动态隐藏/显示表单项
+
+```javascript
+// 在 handleFieldChange 事件中动态隐藏/显示表单项
+const handleFieldChange = (name, value, item) => {
+  if (name === 'userType') {
+    // 根据用户类型隐藏/显示相关字段
+    if (value === 'individual') {
+      // 隐藏公司相关字段
+      formRef.value?.updateFieldConfig('companyName', { hidden: true });
+      formRef.value?.updateFieldConfig('companyAddress', { hidden: true });
+      // 显示个人相关字段
+      formRef.value?.updateFieldConfig('idCard', { hidden: false });
+    } else if (value === 'company') {
+      // 显示公司相关字段
+      formRef.value?.updateFieldConfig('companyName', { hidden: false });
+      formRef.value?.updateFieldConfig('companyAddress', { hidden: false });
+      // 隐藏个人相关字段
+      formRef.value?.updateFieldConfig('idCard', { hidden: true });
+    }
+  }
+};
+```
+
+#### 6. 条件显示表单项
+
+```javascript
+// 根据多个字段值组合来控制表单项显示
+const handleFieldChange = (name, value, item) => {
+  if (name === 'country' || name === 'region') {
+    const country = formData.country;
+    const region = formData.region;
+    
+    // 只有选择特定国家和地区时才显示某些字段
+    if (country === 'china' && region === 'beijing') {
+      formRef.value?.updateFieldConfig('specialField', { hidden: false });
+    } else {
+      formRef.value?.updateFieldConfig('specialField', { hidden: true });
+    }
+  }
+};
+```
+
+#### 7. 动态禁用/启用表单项
+
+```javascript
+// 动态禁用/启用表单项
+const handleFieldChange = (name, value, item) => {
+  if (name === 'agreeTerms') {
+    // 根据是否同意条款来启用/禁用提交按钮
+    formRef.value?.updateFieldConfig('submitButton', { 
+      disabled: !value 
+    });
+  }
+};
+```
+
+### 表单验证功能
+
+#### 1. 验证整个表单
+
+```javascript
+try {
+  await formRef.value?.validateForm();
+  console.log('表单验证通过');
+} catch (error) {
+  console.log('表单验证失败:', error);
+}
+```
+
+#### 2. 验证指定字段
+
+```javascript
+try {
+  await formRef.value?.validateFields(['username', 'email']);
+  console.log('指定字段验证通过');
+} catch (error) {
+  console.log('指定字段验证失败:', error);
+}
+```
+
+#### 3. 清除验证状态
+
+```javascript
+// 清除所有字段的验证状态
+formRef.value?.clearValidate();
+
+// 清除指定字段的验证状态
+formRef.value?.clearValidate(['username', 'email']);
+```
+
+### 表单数据操作
+
+#### 1. 设置字段值
+
+```javascript
+// 设置单个或多个字段值
+formRef.value?.setFieldsValue({
+  username: 'admin',
+  email: 'admin@example.com'
+});
+```
+
+#### 2. 获取字段值
+
+```javascript
+// 获取所有字段值
+const allValues = formRef.value?.getFieldsValue();
+
+// 获取指定字段值
+const specificValues = formRef.value?.getFieldsValue(['username', 'email']);
+```
+
+### 响应式布局
+
+#### 1. 网格布局响应式
+
+```vue
+<BaseForm
+  :items="formItems"
+  layout="grid"
+  :columns="4"
+  :style="{
+    '--form-columns-xl': 4,
+    '--form-columns-lg': 3,
+    '--form-columns-md': 2,
+    '--form-columns-sm': 1,
+    '--form-columns-xs': 1
+  }"
+/>
+```
+
+#### 2. 自定义响应式断点
+
+```css
+/* 自定义响应式断点 */
+.base-form.layout-grid {
+  @media (max-width: 1600px) {
+    --form-columns-xl: 4;
+  }
+  @media (max-width: 1200px) {
+    --form-columns-lg: 3;
+  }
+  @media (max-width: 992px) {
+    --form-columns-md: 2;
+  }
+  @media (max-width: 768px) {
+    --form-columns-sm: 1;
+  }
+  @media (max-width: 576px) {
+    --form-columns-xs: 1;
+  }
+}
+```
+
+## BaseModal 模态框组件
+
+一个增强的模态框组件，支持模态框管理和全局控制。
+
+### 基本用法
+
+```vue
+<template>
+  <BaseModal
+    v-model="visible"
+    title="标题"
+    :width="600"
+    @ok="handleOk"
+    @cancel="handleCancel"
+  >
+    <p>模态框内容</p>
+  </BaseModal>
+</template>
+
+<script setup>
+import { BaseModal } from 'xdc-ui-lib';
+
+const visible = ref(false);
+
+const handleOk = () => {
+  console.log('确认');
+  visible.value = false;
+};
+
+const handleCancel = () => {
+  console.log('取消');
+  visible.value = false;
+};
+</script>
+```
+
+### 使用模态框管理
+
+```vue
+<template>
+  <BaseModal
+    v-model="visible"
+    modal-id="user-modal"
+    title="用户信息"
+  >
+    <p>用户信息内容</p>
+  </BaseModal>
+</template>
+
+<script setup>
+import { BaseModal, useModalManager } from 'xdc-ui-lib';
+
+const { closeAllModals } = useModalManager();
+
+// 关闭所有模态框
+const closeAll = () => {
+  closeAllModals();
+};
+</script>
+```
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| modelValue | 是否显示模态框 | boolean | false |
+| open | 是否显示模态框（与 modelValue 相同） | boolean | false |
+| modalId | 模态框唯一标识，用于模态框管理 | string | - |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| update:modelValue | 模态框显示状态更新 | (value: boolean) |
+| update:open | 模态框显示状态更新 | (value: boolean) |
+| ok | 确认按钮点击事件 | (e: Event) |
+| cancel | 取消按钮点击事件 | (e: Event) |
+| after-close | 模态框关闭后事件 | - |
+
+### 插槽
+
+| 插槽名 | 说明 |
+|--------|------|
+| default | 模态框内容 |
+| title | 标题内容 |
+| footer | 底部内容 |
+| closeIcon | 关闭图标 |
+
+### 模态框管理 Hook
+
+#### useModalManager
+
+提供模态框管理功能。
+
+```typescript
+import { useModalManager } from 'xdc-ui-lib';
+
+const { registerModal, unregisterModal, closeAllModals } = useModalManager();
+```
+
+**方法：**
+
+- `registerModal(id: string, ref: ModalRef)`: 注册模态框
+- `unregisterModal(id: string)`: 注销模态框  
+- `closeAllModals()`: 关闭所有模态框
+
+**全局事件：**
+
+- `close-all-modals`: 关闭所有模态框的全局事件
+
+```javascript
+// 触发全局关闭事件
+window.dispatchEvent(new Event('close-all-modals'));
+```
+
+## FileUpload 文件上传组件
+
+基于 [ant-design-vue](https://www.antdv.com/) 的文件上传组件，支持多选、大小限制、数量限制、删除等功能。
+
+## 安装
+
+```bash
+npm install xdc-ui-lib ant-design-vue
+```
+
+## 使用
+
+```vue
+<template>
+  <FileUpload
+    :limit="3"
+    :fileSizeLimit="2 * 1024 * 1024"
+    btnTxt="上传文件"
+    @select="onSelect"
+    @exceed="onExceed"
+  />
+</template>
+
+<script setup>
+import { FileUpload } from 'xdc-ui-lib';
+
+function onSelect(files) {
+  console.log('已选文件:', files);
+}
+function onExceed(file) {
+  alert('文件超出大小限制: ' + file.name);
+}
+</script>
+```
+
+## Props
+
+| 属性           | 说明               | 类型      | 默认值      |
+| -------------- | ------------------ | --------- | ----------- |
+| accept         | 接受的文件类型     | string    | ''          |
+| btnTxt         | 按钮文字           | string    | '上传'      |
+| btnType        | 按钮类型           | string    | 'button'    |
+| btnProps       | 按钮属性           | object    | {}          |
+| limit          | 最大文件数         | number    | 1           |
+| multiple       | 是否多选           | boolean   | 自动由 limit 控制 |
+| disabled       | 是否禁用           | boolean   | false       |
+| icon           | 自定义图标         | 组件/函数/null | undefined |
+| fileSizeLimit  | 单文件大小限制（字节）| number | 5242880     |
+
+## 事件
+
+| 事件名   | 说明               | 回调参数         |
+| -------- | ------------------ | --------------- |
+| select   | 文件选择后触发     | files/file      |
+| exceed   | 文件超出大小限制时 | file            |
+
+
+## 开发
+
+```bash
+# 安装依赖
+npm install
+
+# 启动开发服务器
+npm run dev
+
+# 构建
+npm run build
+```