xdc-ui-lib 1.0.7 → 2.0.0

package/README.md

@@ -2,12 +2,38 @@
 
 Vue 3 组件库，包含常用的业务组件。
 
-## 组件列表
+## 安装
+
+```bash
+npm install xdc-ui-lib ant-design-vue
+```
+
+## 快速开始
+
+```ts
+import { createApp } from 'vue'
+import Antd from 'ant-design-vue'
+import 'ant-design-vue/dist/reset.css'
+
+import XdcUiLib from 'xdc-ui-lib'
+
+const app = createApp(App)
+app.use(Antd)
+app.use(XdcUiLib)
+app.mount('#app')
+```
 
-- **CategorySearch**: 分类搜索组件
-- **BaseModal**: 模态框组件
-- **BaseForm**: 动态表单组件
-- **FileUpload**: 文件上传组件
+## 组件列表（目录）
+
+- [CategorySearch 分类搜索组件](#categorysearch-分类搜索组件)
+- [SearchPanel 搜索面板组件](#searchpanel-搜索面板组件)
+- [ColumnSetting 表格列设置组件](#columnsetting-表格列设置组件)
+- [BaseTable 表格增强组件](#basetable-表格增强组件)
+- [BaseForm 动态表单组件](#baseform-动态表单组件)
+- [BaseModal 模态框组件](#basemodal-模态框组件)
+- [FileUpload 文件上传组件](#fileupload-文件上传组件)
+
+---
 
 ## CategorySearch 分类搜索组件
 
@@ -75,7 +101,8 @@ const columns = [
 
 ### 高级功能
 
-#### 1. 表单模式 (type="form")
+<details>
+<summary><b>1. 表单模式 (type="form")</b></summary>
 
 ```vue
 <template>
@@ -90,7 +117,10 @@ const columns = [
 </template>
 ```
 
-#### 2. 列设置功能
+</details>
+
+<details>
+<summary><b>2. 列设置功能</b></summary>
 
 ```vue
 <template>
@@ -103,13 +133,16 @@ const columns = [
 </template>
 ```
 
-#### 3. 自定义插槽
+</details>
+
+<details>
+<summary><b>3. 自定义插槽</b></summary>
 
 ```vue
 <template>
   <CategorySearch :filter-types="filterTypes">
     <template #filter-slots="{ filter, filterTemp, confirm }">
-      <CustomComponent 
+      <CustomComponent
         v-if="filter.id === 'customField'"
         v-model:value="filterTemp[filter.id]"
         @change="confirm"
@@ -119,9 +152,12 @@ const columns = [
 </template>
 ```
 
-#### 4. 国际化支持
+</details>
+
+<details>
+<summary><b>4. 国际化支持</b></summary>
 
-```javascript
+```js
 const filterTypes = [
   {
     id: 'status',
@@ -132,6 +168,8 @@ const filterTypes = [
 ];
 ```
 
+</details>
+
 ### Props
 
 | 参数 | 说明 | 类型 | 默认值 |
@@ -160,9 +198,11 @@ const filterTypes = [
 1. **如果提供了 `storageKey`**：直接使用提供的值
 2. **如果没有提供 `storageKey`**：自动生成基于页面路径和配置的唯一键
 
-#### 自动生成存储键
+<details>
+<summary><b>自动生成存储键</b></summary>
 
 当没有提供 `storageKey` 时，组件会自动生成一个基于以下信息的唯一存储键：
+
 - 当前页面路径
 - 筛选类型配置
 - 表格列配置
@@ -171,7 +211,10 @@ const filterTypes = [
 
 这样可以确保每个页面和配置组合都有唯一的存储键，避免数据冲突。
 
-### 在 Vue Router 项目中使用
+</details>
+
+<details>
+<summary><b>在 Vue Router 项目中使用</b></summary>
 
 ```vue
 <template>
@@ -185,7 +228,10 @@ const filterTypes = [
 </template>
 ```
 
-### 在非路由项目中使用
+</details>
+
+<details>
+<summary><b>在非路由项目中使用</b></summary>
 
 ```vue
 <template>
@@ -198,7 +244,10 @@ const filterTypes = [
 </template>
 ```
 
-### 使用自动生成存储键
+</details>
+
+<details>
+<summary><b>使用自动生成存储键</b></summary>
 
 ```vue
 <template>
@@ -212,6 +261,8 @@ const filterTypes = [
 </template>
 ```
 
+</details>
+
 ### Events
 
 | 事件名 | 说明 | 回调参数 |
@@ -224,6 +275,323 @@ const filterTypes = [
 | update:columns | 列更新事件 | (columns: array) |
 | update:filterValue | 筛选值更新事件 | (value: object) |
 
+---
+
+## SearchPanel 搜索面板组件
+
+SearchPanel 是一个“搜索条件构建器”组件，支持两种模式：
+
+- `type="input"`：输入框 + tag 的交互式条件选择（带下拉面板）
+- `type="form"`：表单平铺模式（可折叠），更适合复杂筛选场景
+
+同时内置：
+
+- 筛选条件本地缓存（基于 `storageKey`）
+- 条件保存/恢复
+- 筛选项显示/隐藏/排序（“列设置”面板，但作用对象是 filterTypes）
+- 国际化（使用内置 `useI18n` 的 `t('searchPanel.xxx')`）
+
+### 基本用法（Input 模式）
+
+```vue
+<template>
+  <SearchPanel
+    :loading="loading"
+    :filter-types="filterTypes"
+    v-model:filter-value="params"
+    @search="onSearch"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { SearchPanel } from 'xdc-ui-lib'
+
+const loading = ref(false)
+const params = ref<Record<string, any>>({})
+
+const filterTypes = [
+  { id: 'name', label: '名称', type: 'input', placeholder: '请输入名称' },
+  {
+    id: 'status',
+    label: '状态',
+    type: 'select',
+    options: [
+      { label: '启用', value: 1 },
+      { label: '禁用', value: 0 },
+    ],
+  },
+]
+
+function onSearch(payload: Record<string, any>) {
+  console.log('search:', payload)
+}
+</script>
+```
+
+### 基本用法（Form 模式）
+
+```vue
+<template>
+  <SearchPanel
+    type="form"
+    :loading="loading"
+    :filter-types="filterTypes"
+    :form-layout="'grid'"
+    :form-span="4"
+    :collapsed-count="6"
+    v-model:filter-value="params"
+    @search="onSearch"
+  />
+</template>
+```
+
+### 支持的筛选类型（filterTypes[].type）
+
+与 CategorySearch 基本一致，另外支持更多日期 picker：
+
+- `input` / `textarea`
+- `select` / `cascader` / `treeSelect`
+- `checkbox` / `radio`
+- `date` / `datetime` / `month` / `week` / `quarter` / `year`
+- `time`
+- `dateRange` / `datetimeRange`
+- `numberRange`
+- `rate` / `slider` / `switch`
+- `slot`
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| type | 模式：`input` / `form` | `'input' \| 'form'` | `'input'` |
+| loading | 加载状态（会阻止 search/refresh） | `boolean` | **必传** |
+| filterTypes | 筛选项配置 | `any[]` | **必传** |
+| filterValue | 当前筛选值（用于回显/受控） | `any` | `{}` |
+| placeholder | Input 模式占位文案 | `string` | `'点击选择搜索条件'` |
+| storageKey | 本地缓存 key；不传时默认使用 `search-panel:${pathname}${search}` | `string` | `''` |
+| hideRefresh | 是否隐藏刷新/搜索按钮 | `boolean` | `false` |
+| showSwitch | 是否显示“切换”按钮 | `boolean` | `false` |
+| showSave | 是否显示“保存”按钮 | `boolean` | `false` |
+| showSettingColumns | 是否显示“筛选项显示设置”按钮 | `boolean` | `true` |
+| disabledFilterTypes | 不允许隐藏的筛选项 id 列表（例如必须展示的条件） | `string[]` | `[]` |
+| isDefaultSearch | 初始化时是否自动触发 search（会读取缓存） | `boolean` | `true` |
+| formLayout | Form 模式布局：`horizontal`/`vertical`/`inline`/`grid` | `'horizontal' \| 'vertical' \| 'inline' \| 'grid'` | `'grid'` |
+| formSpan | Form 模式 grid 布局下列数（CSS 变量） | `number` | `4` |
+| labelCol | Form 模式 labelCol（horizontal/grid 相关） | `any` | `-` |
+| wrapperCol | Form 模式 wrapperCol（horizontal/grid 相关） | `any` | `-` |
+| labelBorder | Form 模式是否显示 label 边框样式（grid-form） | `boolean` | `false` |
+| colon | Form 模式 label 是否显示冒号 | `boolean` | `false` |
+| collapsedCount | Form 模式折叠时展示前 N 个筛选项（传了就启用折叠逻辑，支持 0） | `number` | `undefined` |
+| defaultCollapsed | Form 模式默认是否折叠（仅在启用折叠逻辑时生效） | `boolean` | `true` |
+| columns | 兼容旧入参（已不再使用） | `any[]` | `[]` |
+| disabledColumns | 兼容旧入参（已不再使用） | `string[]` | `[]` |
+
+> 说明：组件内部还存在 `collapsible` 默认值，但当前 props 定义里未显式声明（属于历史字段/可忽略）。
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+|------|------|----------|
+| search | 点击刷新/确认/表单搜索时触发（会扁平化部分日期结构） | `(params: Record<string, any>)` |
+| switch | 点击切换按钮触发 | `(filters: any[])` |
+| clear | 调用 reset/清空时触发 | `()` |
+| reset | （当前代码未 emit reset，仅保留事件名；如需可补） | `()` |
+| columnsChange | （历史事件名：当前主要用于 filterTypes 显示设置，不建议依赖） | `(cols: any[])` |
+| update:columns | （历史 v-model：当前主要用于 filterTypes 显示设置，不建议依赖） | `(cols: any[])` |
+| update:filterValue | v-model 回写，用于回显/受控 | `(value: any)` |
+
+### Slots
+
+| 插槽名 | 说明 | 参数 |
+|------|------|------|
+| icon | Input 模式右侧自定义操作按钮区域（点击事件需自行处理） | - |
+| filter-slots | 当 `filterTypes[].type === 'slot'` 时渲染 | `{ filter, filterTemp, confirm }` |
+
+### 方法（Expose）
+
+通过 ref 可调用：
+
+- `reset()`：清空条件并触发一次 search
+- `search()`：触发一次 search（内部有 throttle 800ms）
+
+---
+
+## ColumnSetting 表格列设置组件
+
+用于表格列的显示/隐藏、拖拽排序、左右固定，并支持 localStorage 持久化。
+
+### 适用场景
+
+- 表格列“显隐/排序/固定（左/右）”需要给用户自定义
+- 需要把列配置持久化到 localStorage（同页面刷新仍保持）
+- 需要禁用某些关键列（不可隐藏/不可拖拽）
+
+### 基本用法
+
+```vue
+<template>
+  <ColumnSetting
+    v-model:columns="columnSetting"
+    storageKey="user-list-columns"
+    :disabledColumns="['id']"
+  >
+    <template #trigger>
+      <a-button>列设置</a-button>
+    </template>
+  </ColumnSetting>
+
+  <a-table :columns="columnSetting" :data-source="dataSource" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { ColumnSetting } from 'xdc-ui-lib'
+
+const columns = [
+  { title: 'ID', dataIndex: 'id', key: 'id' },
+  { title: '名称', dataIndex: 'name', key: 'name' },
+  { title: '状态', dataIndex: 'status', key: 'status' },
+]
+
+const dataSource = []
+
+const columnSetting = ref([])
+</script>
+```
+
+### 与其他组件的关系
+
+ColumnSetting 已解耦，可 **独立使用**（不依赖 CategorySearch / SearchPanel 等组件）。
+
+- 只要提供 `v-model:columns` 绑定的列配置，即可完成列的显隐/排序/固定与持久化。
+- 如需在其他组件中集成（例如放在表格工具栏里），直接按本章「基本用法（与 antd Table 配合）」接入即可。
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| columns | 原始列配置 | array | [] |
+| modelValue(v-model) | 当前列设置（包含 checked/fixed/顺序） | array | - |
+| disabledColumns | 禁用列（不可隐藏/不可拖拽） | string[] | [] |
+| storageKey | localStorage 存储 key（不传则不持久化） | string | - |
+| placement | Popover 弹出位置 | string | bottomRight |
+| maxHeight | 面板最大高度 | number\|string | 400 |
+| title | 面板标题文案 | string | 列展示 |
+| resetText | 重置文案 | string | 重置 |
+| fixedLeftText | 固定到左侧提示 | string | 固定到左侧 |
+| fixedRightText | 固定到右侧提示 | string | 固定到右侧 |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+|------|------|----------|
+| update:modelValue | 列设置变更（全量） | (cols: array) |
+| update:visibleColumns | 可见列变更（过滤 checked=false） | (cols: array) |
+| change | 同 update:modelValue | (cols: array) |
+| reset | 点击重置触发 | - |
+
+---
+
+## BaseTable 表格增强组件
+
+BaseTable 是对 `ant-design-vue` 的 `a-table` 做的“增强但不打扰”的封装：
+
+- **不重复声明 a-table 的全部 props/emits**：通过 `useAttrs()` 全量透传
+- **动态转发所有 a-table 插槽**：不影响你使用官方的 slots
+- 提供可选工具条（标题/操作区）
+- 内置列设置按钮（复用 `ColumnSetting`），以及刷新/密度（size）切换
+- loading 兼容增强、error 空态兜底
+
+### 基本用法
+
+```vue
+<template>
+  <BaseTable
+    :columns="columns"
+    :data-source="dataSource"
+    :pagination="pagination"
+    @change="onChange"
+  />
+</template>
+
+<script setup lang="ts">
+import { BaseTable } from 'xdc-ui-lib'
+
+const columns = [
+  { title: 'ID', dataIndex: 'id', key: 'id' },
+  { title: '名称', dataIndex: 'name', key: 'name' },
+]
+
+const dataSource = []
+const pagination = { current: 1, pageSize: 10, total: 0 }
+
+function onChange(...args: any[]) {
+  console.log('table change', args)
+}
+</script>
+```
+
+### 工具条（title + 操作）
+
+```vue
+<BaseTable title="用户列表" :columns="columns" :data-source="dataSource" @refresh="fetchList" />
+```
+
+### 列设置（ColumnSetting 集成）
+
+BaseTable 会在工具条右侧渲染列设置入口（前提：你传入了 `columns`）。
+
+你可以直接把 ColumnSetting 的相关 props 当作 attribute 传给 BaseTable：
+
+```vue
+<BaseTable
+  title="用户列表"
+  :columns="columns"
+  :data-source="dataSource"
+  storageKey="user-list-columns"
+  :disabledColumns="['id']"
+/>
+```
+
+### Props（BaseTable 自身声明的）
+
+> 说明：除下表外，`a-table` 的所有 props/事件都可以直接 `v-bind`/监听传入。
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| title | 工具条标题（默认展示在左侧） | `string` | `-` |
+| toolbar | 是否展示工具条；不传时按“title/slot/toolbarActions 是否存在”自动判断 | `boolean` | `undefined` |
+| toolbarActions | 是否显示右侧默认操作区（列设置/刷新/密度） | `boolean` | `true` |
+| error | 错误信息（string 或 Error），用于空态兜底 | `string \| Error \| null` | `null` |
+| loading | loading 增强：boolean / {spinning, tip} / AntD 原生 loading 对象 | `boolean \| {spinning?: boolean; tip?: string} \| Record<string, any>` | `undefined` |
+| defaultSize | 默认表格密度（仅当外部未传 `size` 时生效） | `'small' \| 'middle' \| 'large'` | `'middle'` |
+
+### Events（BaseTable 自身声明的）
+
+| 事件名 | 说明 | 回调参数 |
+|------|------|----------|
+| refresh | 点击刷新按钮触发 | `()` |
+| update:size | 点击密度切换触发；若外部未受控，会同时更新内部 size | `(size: 'small' \| 'middle' \| 'large')` |
+
+### Slots
+
+| 插槽名 | 说明 |
+|------|------|
+| toolbar-left | 覆盖工具条左侧区域（默认显示 title） |
+| toolbar-right | 覆盖工具条右侧区域（默认显示 toolbarActions 区） |
+| toolbar-extra | 在默认 toolbarActions 区后追加内容 |
+
+> 除以上 3 个工具条插槽外，**所有 a-table 的插槽都会被动态透传**（例如 `bodyCell`、`headerCell`、`expandedRowRender`、`emptyText` 等）。
+
+### 默认行为（仅在外部未传时生效）
+
+- `rowKey` 默认为 `'id'`
+- `scroll` 默认为 `{ x: 'max-content' }`
+- `locale.emptyText` 默认为 `'暂无数据'`（若传入 error 且外部未提供 empty slot/locale.emptyText，则显示 error）
+
+---
+
 ## BaseForm 动态表单组件
 
 一个功能强大的动态表单组件，支持多种表单元素类型、布局方式和自定义功能。
@@ -326,7 +694,8 @@ const formItems = [
 
 ### 布局方式
 
-#### 1. 水平布局 (默认)
+<details>
+<summary><b>1. 水平布局 (默认)</b></summary>
 
 ```vue
 <BaseForm
@@ -337,62 +706,66 @@ const formItems = [
 />
 ```
 
-#### 2. 垂直布局
+</details>
+
+<details>
+<summary><b>2. 垂直布局</b></summary>
 
 ```vue
-<BaseForm
-  :items="formItems"
-  layout="vertical"
-/>
+<BaseForm :items="formItems" layout="vertical" />
 ```
 
-#### 3. 网格布局
+</details>
+
+<details>
+<summary><b>3. 网格布局</b></summary>
 
 ```vue
-<BaseForm
-  :items="formItems"
-  layout="grid"
-  :columns="3"
-/>
+<BaseForm :items="formItems" layout="grid" :columns="3" />
 ```
 
+</details>
+
 ### 自定义插槽
 
-#### 1. 自定义表单项
+<details>
+<summary><b>1. 自定义表单项</b></summary>
 
 ```vue
 <BaseForm :items="formItems">
   <template #field-customField="{ item, modelValue, updateValue }">
     <div class="custom-field">
-      <a-input 
-        :value="modelValue" 
+      <a-input
+        :value="modelValue"
         placeholder="自定义字段"
-        @input="(e) => updateValue(e.target.value)" 
+        @input="(e) => updateValue(e.target.value)"
       />
     </div>
   </template>
 </BaseForm>
 ```
 
-#### 2. 自定义操作按钮
+</details>
+
+<details>
+<summary><b>2. 自定义操作按钮</b></summary>
 
 ```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 type="primary" :loading="loading" @click="submit">确认提交</a-button>
       <a-button @click="reset">重置</a-button>
-      <a-button type="dashed" @click="handlePreview">
-        预览数据
-      </a-button>
+      <a-button type="dashed" @click="handlePreview">预览数据</a-button>
     </a-space>
   </template>
 </BaseForm>
 ```
 
-#### 3. 自定义表单项前缀/后缀
+</details>
+
+<details>
+<summary><b>3. 自定义前缀/后缀/after</b></summary>
 
 ```vue
 <BaseForm :items="formItems">
@@ -409,14 +782,21 @@ const formItems = [
 </BaseForm>
 ```
 
-#### 4. 自定义整个表单项
+</details>
+
+<details>
+<summary><b>4. 自定义整个表单项</b></summary>
 
 ```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)" />
+        <a-input
+          :value="modelValue"
+          placeholder="自定义表单项"
+          @input="(e) => updateValue(e.target.value)"
+        />
         <small>这是完全自定义的表单项</small>
       </div>
     </a-form-item>
@@ -424,11 +804,14 @@ const formItems = [
 </BaseForm>
 ```
 
-#### 5. 自定义表单项插槽
+</details>
+
+<details>
+<summary><b>5. 自定义 custom-items 插槽</b></summary>
 
 ```vue
 <BaseForm :items="formItems">
-  <template #custom-items="{ formData, updateField, formRef }">
+  <template #custom-items="{ formData }">
     <a-form-item label="自定义表单项">
       <a-input v-model:value="formData.customField" placeholder="自定义字段" />
     </a-form-item>
@@ -436,8 +819,13 @@ const formItems = [
 </BaseForm>
 ```
 
+</details>
+
 ### 复杂表单示例
 
+<details>
+<summary><b>点击展开</b></summary>
+
 ```vue
 <template>
   <BaseForm
@@ -482,6 +870,8 @@ const formItems = [
 </template>
 ```
 
+</details>
+
 ### Props
 
 | 参数 | 说明 | 类型 | 默认值 |
@@ -518,411 +908,7 @@ const formItems = [
 | 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 模态框组件
 
@@ -964,11 +950,7 @@ const handleCancel = () => {
 
 ```vue
 <template>
-  <BaseModal
-    v-model="visible"
-    modal-id="user-modal"
-    title="用户信息"
-  >
+  <BaseModal v-model="visible" modal-id="user-modal" title="用户信息">
     <p>用户信息内容</p>
   </BaseModal>
 </template>
@@ -978,7 +960,6 @@ import { BaseModal, useModalManager } from 'xdc-ui-lib';
 
 const { closeAllModals } = useModalManager();
 
-// 关闭所有模态框
 const closeAll = () => {
   closeAllModals();
 };
@@ -1014,11 +995,10 @@ const closeAll = () => {
 
 ### 模态框管理 Hook
 
-#### useModalManager
-
-提供模态框管理功能。
+<details>
+<summary><b>useModalManager</b></summary>
 
-```typescript
+```ts
 import { useModalManager } from 'xdc-ui-lib';
 
 const { registerModal, unregisterModal, closeAllModals } = useModalManager();
@@ -1027,29 +1007,26 @@ const { registerModal, unregisterModal, closeAllModals } = useModalManager();
 **方法：**
 
 - `registerModal(id: string, ref: ModalRef)`: 注册模态框
-- `unregisterModal(id: string)`: 注销模态框  
+- `unregisterModal(id: string)`: 注销模态框
 - `closeAllModals()`: 关闭所有模态框
 
 **全局事件：**
 
 - `close-all-modals`: 关闭所有模态框的全局事件
 
-```javascript
-// 触发全局关闭事件
+```js
 window.dispatchEvent(new Event('close-all-modals'));
 ```
 
-## FileUpload 文件上传组件
+</details>
 
-基于 [ant-design-vue](https://www.antdv.com/) 的文件上传组件，支持多选、大小限制、数量限制、删除等功能。
+---
 
-## 安装
+## FileUpload 文件上传组件
 
-```bash
-npm install xdc-ui-lib ant-design-vue
-```
+基于 [ant-design-vue](https://www.antdv.com/) 的文件上传组件，支持多选、大小限制、数量限制、删除等功能。
 
-## 使用
+### 使用
 
 ```vue
 <template>
@@ -1074,27 +1051,28 @@ function onExceed(file) {
 </script>
 ```
 
-## Props
+### 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     |
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| accept | 接受的文件类型 | string | '' |
+| btnTxt | 按钮文字 | string | '上传' |
+| btnType | 按钮类型 | string | 'button' |
+| btnProps | 按钮属性 | object | {} |
+| limit | 最大文件数 | number | 1 |
+| multiple | 是否多选 | boolean | 自动由 limit 控制 |
+| disabled | 是否禁用 | boolean | false |
+| icon | 自定义图标 | 组件/函数/null | undefined |
+| fileSizeLimit | 单文件大小限制（字节） | number | 5242880 |
 
-## 事件
+### Events
 
-| 事件名   | 说明               | 回调参数         |
-| -------- | ------------------ | --------------- |
-| select   | 文件选择后触发     | files/file      |
-| exceed   | 文件超出大小限制时 | file            |
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| select | 文件选择后触发 | files/file |
+| exceed | 文件超出大小限制时 | file |
 
+---
 
 ## 开发