@zl-ui-kit/components 0.10.1 → 0.10.3

package/README.md

@@ -41,6 +41,7 @@ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，55 个业务组
   - [6.2 Mock 模块（playground 离线联调）](#62-mock-模块playground-离线联调)
   - [6.3 组件对接实战（对应 `/use-request` 页面）](#63-组件对接实战对应-use-request-页面)
   - [6.4 常见坑位](#64-常见坑位)
+  - [6.5 组合用法范式（列表页 / 抽屉表单 / 卡片列表）](#65-组合用法范式列表页-抽屉表单-卡片列表)
 - [7. 表单与交互组件](#7-表单与交互组件)
   - [ZlForm —— schema 驱动](#zlform-schema-驱动)
   - [ZlSearch —— 查询条](#zlsearch-查询条)
@@ -992,6 +993,234 @@ req.cancel()                                    // 取消进行中请求
 
 ---
 
+### 6.5 组合用法范式（列表页 / 抽屉表单 / 卡片列表）
+
+§6.3 与 §7 是「单组件」用法；这里给出三种最常见的**页面级组合范式**，把数据组件、`ZlForm`、`ZlAction` 与 `useRequest` 家族串起来。命名与字段均按当前 Element Plus 版组件的实际 API 书写，可直接套用。
+
+#### 6.5.1 列表页范式：ZlSearchTable + usePageableRequest（内置）
+
+`ZlSearchTable` 内部已用 `usePageableRequest` 驱动分页与查询，页面只需传 `request` / `columns` / `queryItems`；新增、导入、导出等按钮统一放进 `search-actions` 插槽；行内操作交给列的 `actions`；字典列与超长列用同名插槽（`#<prop>`）接管。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { ZlSearchTable, ZlAction, ZlDictTag, ZlAutoTooltip } from '@zl-ui-kit/components'
+import { useRequest, useDict, useGlobalMessage } from '@zl-ui-kit/composables'
+import EditDrawer from './EditDrawer.vue'
+
+const { Message, Modal } = useGlobalMessage()
+const statusOptions = useDict('resourceStatus') // 字典项数组，渲染用 statusOptions.value
+
+// 列定义：prop 命名；slot:true 的列用同名插槽 #<prop> 接管；actions 列渲染行内操作
+const columns = [
+  { prop: 'name', label: '名称', minWidth: 160 },
+  { prop: 'type', label: '类型', width: 120 },
+  { prop: 'status', label: '状态', width: 100, slot: true },
+  {
+    prop: 'actions',
+    label: '操作',
+    width: 180,
+    fixed: 'right',
+    actions: [
+      { label: '编辑', handler: (row: any) => openEdit(row) },
+      { label: '删除', visible: (row: any) => row.id !== 1, handler: (row: any) => onDelete(row) },
+    ],
+  },
+]
+
+const queryItems = [
+  {
+    model: 'keyword',
+    label: '名称',
+    component: 'el-input',
+    props: { placeholder: '请输入名称', clearable: true },
+  },
+  {
+    model: 'status',
+    label: '状态',
+    component: 'el-select',
+    props: { options: statusOptions, clearable: true },
+  },
+]
+
+const tableRef = ref()
+const editVisible = ref(false)
+const editData = ref<any>({})
+
+function openEdit(row?: any) {
+  editData.value = row ? { ...row } : {}
+  editVisible.value = true
+}
+
+// 删除：确认框 + 反馈 + 原地重查（保持当前页码）
+function onDelete(row: any) {
+  Modal.confirmPromise({ title: '确认删除', content: `确认删除「${row.name}」？` }, async () => {
+    await removeApi(row.id)
+    Message.success('删除成功')
+    tableRef.value?.refresh()
+  })
+}
+
+// 导出：带 loading 的单次请求；outputFile 选项触发浏览器下载
+const { loading: exportLoading, run: runExport } = useRequest(exportApi, {
+  manual: true,
+  outputFile: () => `list_${Date.now()}.xlsx`,
+})
+function onExport() {
+  runExport(tableRef.value?.search.params) // 用当前查询条件导出
+}
+</script>
+
+<template>
+  <ZlSearchTable
+    ref="tableRef"
+    :request="getPageApi"
+    :columns="columns"
+    :query-items="queryItems"
+    :pagination="{ pageSize: 10 }"
+    height="420"
+  >
+    <!-- 查询条右侧操作区：新增 / 导出 统一归位到这里 -->
+    <template #search-actions>
+      <ZlAction
+        :actions="[
+          { label: '新增', icon: 'zl:plus', handler: () => openEdit() },
+          { label: '导出', icon: 'zl:download', disabled: exportLoading, handler: onExport },
+        ]"
+      />
+    </template>
+
+    <!-- 状态列：字典标签（全局 setDictSource 已注册，无需逐行传 dict） -->
+    <template #status="{ row }">
+      <ZlDictTag dict-key="resourceStatus" :value="row.status" />
+    </template>
+
+    <!-- 名称列：超长省略 + 悬浮提示 -->
+    <template #name="{ row }">
+      <ZlAutoTooltip>{{ row.name }}</ZlAutoTooltip>
+    </template>
+  </ZlSearchTable>
+
+  <!-- 新增 / 编辑抽屉（实现见 6.5.2） -->
+  <EditDrawer v-model:visible="editVisible" :data="editData" @saved="tableRef?.refresh()" />
+</template>
+```
+
+> 行内改状态、删除后刷新用 `tableRef.refresh()`（原地重查、保持页码）；换查询条件由 `ZlSearch` 自动回到第 1 页。`search-actions` 之外的批量按钮（如「导入」）也可放进这里。
+
+#### 6.5.2 抽屉表单范式：ZlDrawer + ZlForm + useRequest
+
+新增 / 编辑 / 详情建议抽成独立的抽屉子组件，用 `defineModel('visible')` 承接父级 `v-model:visible`，内部用 `ZlForm` 的 `validate()` 校验，保存走 `useRequest`，反馈用 `useGlobalMessage`，保存成功后再通知父级 `refresh()`。
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+import { ZlDrawer, ZlForm } from '@zl-ui-kit/components'
+import { useRequest, useDict, useGlobalMessage } from '@zl-ui-kit/composables'
+
+const props = defineProps<{ data?: any }>()
+const emit = defineEmits<{ saved: [] }>()
+const visible = defineModel<boolean>('visible', { required: true })
+
+const { Message } = useGlobalMessage()
+const typeOptions = useDict('resourceType')
+
+const model = ref<any>({})
+const formRef = ref()
+
+// 打开即回填：新增给默认值，编辑用传入行数据
+watch(
+  visible,
+  (open) => {
+    if (open) model.value = props.data ? { ...props.data } : { status: 'enabled' }
+  },
+  { immediate: true },
+)
+
+const items = [
+  { model: 'name', label: '名称', component: 'el-input', rules: [{ required: true, message: '请输入名称' }] },
+  { model: 'type', label: '类型', component: 'el-select', props: { options: typeOptions } },
+  {
+    model: 'status',
+    label: '状态',
+    component: 'ZlSwitch',
+    props: { checkedValue: 'enabled', uncheckedValue: 'disabled' },
+  },
+]
+
+// 确定回调：校验 → 保存 → 关闭 → 通知父级刷新
+async function onSubmit() {
+  await formRef.value?.validate()
+  const isEdit = !!props.data?.id
+  await saveApi({ ...model.value, id: props.data?.id })
+  Message.success(isEdit ? '修改成功' : '新增成功')
+  visible.value = false
+  emit('saved')
+}
+</script>
+
+<template>
+  <ZlDrawer
+    v-model:visible="visible"
+    :title="data?.id ? '编辑' : '新增'"
+    :on-ok="onSubmit"
+    :auto-close-after-confirm="false"
+  >
+    <ZlForm ref="formRef" :model="model" :items="items" label-width="auto" />
+  </ZlDrawer>
+</template>
+```
+
+> `ZlForm` 的 `validate()` 返回 `Promise<boolean>`（`0.9.0` 及更早版本成功时 `resolve(undefined)`，判断成功请用 `await` 捕获异常而非当布尔用）。表单数据用 `:model` 传入，`props` 里的 `update:modelValue` 会写回该对象，无需手写 `v-model`。`ZlDrawer` 的 `onOk` 异步期间确定按钮自动保持 loading，`auto-close-after-confirm` 默认 `true`，需要自行控制关闭时设为 `false`。
+
+#### 6.5.3 卡片列表范式：ZlCardPage + ZlCard + ZlAction
+
+分页卡片列表用 `ZlCardPage`（内部同样 `usePageableRequest`），默认插槽逐项渲染 `ZlCard`；卡片的图标、标题、副标题、底部操作区用具名插槽；底部操作按钮同样用 `ZlAction`，状态角标用 `ZlDictTag`。
+
+```vue
+<script setup lang="ts">
+import { ZlCardPage, ZlCard, ZlAction, ZlIcon, ZlDictTag } from '@zl-ui-kit/components'
+import { useDict } from '@zl-ui-kit/composables'
+
+const typeOptions = useDict('resourceType')
+
+function cardActions(data: any) {
+  return [
+    { label: '查看', icon: 'zl:eye', handler: () => open(data) },
+    { label: '编辑', icon: 'zl:edit', handler: () => openEdit(data) },
+  ]
+}
+</script>
+
+<template>
+  <ZlCardPage :request="getPageApi" :query-items="queryItems" :pagination="{ pageSize: 30 }">
+    <!-- 顶部操作区：新增统一放这里 -->
+    <template #search-actions>
+      <ZlAction :actions="[{ label: '新增', icon: 'zl:plus', handler: onAdd }]" />
+    </template>
+
+    <!-- 逐项渲染卡片 -->
+    <template #default="{ data }">
+      <ZlCard>
+        <template #icon>
+          <ZlIcon :icon="`zl:${data.type === '数据库' ? 'database' : 'folder'}`" />
+        </template>
+        <template #title>{{ data.name }}</template>
+        <template #subtitle>{{ data.createTime }}</template>
+        <template #footer>
+          <ZlDictTag dict-key="resourceStatus" :value="data.status" />
+          <ZlAction :actions="cardActions(data)" />
+        </template>
+      </ZlCard>
+    </template>
+  </ZlCardPage>
+</template>
+```
+
+> 卡片列表的分页键名、条件重查（如页签切换）与列表页一致，参见 §6.3 ②。`ZlCard` 的 `icon` / `title` / `subtitle` / `footer` 均为具名插槽；需要正文区时用默认插槽。`ZlIcon` 的 `icon` 传 `zl:` 前缀图标名，未注册的图标会渲染空白。
+
+---
+
 ## 7. 表单与交互组件
 
 ### ZlForm —— schema 驱动
@@ -3262,10 +3491,12 @@ import { ZlAction } from '@zl-ui-kit/components'
 </script>
 
 <template>
-  <ZlAction />
+  <ZlAction :actions="actions" />
 </template>
 ```
 
+> 示例中的 `actions` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
 > 把 `$attrs` 透传给 `ZlActionList`，未列出的属性会继续下传
 
 > 纯容器组件：不接收 props，也无自定义事件/插槽/暴露方法。
@@ -3653,7 +3884,7 @@ import { ZlCardPage } from '@zl-ui-kit/components'
 </script>
 
 <template>
-  <ZlCardPage :request="mockPageRequest" card-min-width="180px" />
+  <ZlCardPage :request="mockPageRequest" card-min-width="200px" />
 </template>
 ```
 
@@ -3894,11 +4125,11 @@ import { ZlDictTag } from '@zl-ui-kit/components'
 </script>
 
 <template>
-  <ZlDictTag dict-key="dictTagDemo" value="1" :dict="dict" />
+  <ZlDictTag dict-key="resourceStatus" :value="data.status" />
 </template>
 ```
 
-> 示例中的 `dict` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+> 示例中的 `value` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
 
 **props**
 
@@ -3928,10 +4159,12 @@ import { ZlDrawer } from '@zl-ui-kit/components'
 </script>
 
 <template>
-  <ZlDrawer v-model:visible="value" title="抽屉标题" />
+  <ZlDrawer v-model:visible="value" title="新增" :on-ok="onOk" />
 </template>
 ```
 
+> 示例中的 `onOk` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
 **插槽用法**
 
 ```vue
@@ -4163,7 +4396,7 @@ import { ZlForm } from '@zl-ui-kit/components'
 </script>
 
 <template>
-  <ZlForm :model="model" :items="items" label-width="80px" style="max-width: 420px" />
+  <ZlForm :model="model.value" :items="items" label-width="80px" />
 </template>
 ```
 
@@ -4396,10 +4629,12 @@ import { ZlIcon } from '@zl-ui-kit/components'
 </script>
 
 <template>
-  <ZlIcon icon="zl:bug" />
+  <ZlIcon :icon="icon" />
 </template>
 ```
 
+> 示例中的 `icon` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
 **插槽用法**
 
 ```vue
@@ -4876,10 +5111,10 @@ import { ZlSearchTable } from '@zl-ui-kit/components'
 <template>
   <ZlSearchTable
     :request="mockPageRequest"
-    :columns="tableColumns"
+    :columns="columns"
     :query-items="queryItems"
     :pagination="{ pageSize: 5 }"
-    height="320"
+    height="340"
   />
 </template>
 ```
@@ -5953,7 +6188,7 @@ ZlGrid 子项 schema
 ## 15. 组件替换规范（Element Plus → Zl-*）
 
 > 本规范约定：宿主项目引入本组件库后，**优先使用 Zl 系列组件替代对应的 Element Plus 组件**，并**复用 `@zl-ui-kit/utils` 的工具方法替代重复实现**，以保证主题、国际化、字典、权限与交互体验统一。
-> 规范持续补充中——新增替换项请追加到 §15.2（组件）/ §15.4（工具方法）对照表，并在对应规则处补充示例。各组件的具体 props / 插槽 / 事件以 §14 组件 API 参考与 playground 示例为准。
+> 规范持续补充中——新增替换项请追加到 §15.2（组件）/ §15.4（工具方法）对照表，hooks 类替换补进 §15.1 规则，并在对应规则处补充示例。各组件的具体 props / 插槽 / 事件以 §14 组件 API 参考与 playground 示例为准。
 
 ### 15.1 核心替换规则
 
@@ -5969,38 +6204,42 @@ ZlGrid 子项 schema
 10. **列表页操作按钮归位**：使用 `ZlSearchTable` 或 `ZlCardPage` 替换的列表页，其「新增 / 导入 / 导出」等操作按钮统一放进对应组件的 `search-actions` 插槽（亦兼容 camelCase `searchActions`）。
 11. **其余 Element Plus 组件**：剩余 `el-` 开头的 Element Plus 组件，均按 §3 组件总览的命名对应关系替换为对应的 Zl 组件（如 `el-tree`→`ZlTree`、`el-upload`→`ZlUpload`、`el-tag`→`ZlTag`、`el-tabs`→`ZlTabs` 等）。
 12. **工具方法复用**：宿主项目里使用的工具类方法，需先与 `@zl-ui-kit/utils` 中的工具方法比对（完整清单见 §12.2，精确签名见 §12.3）；若存在**最终效果一致**的实现，统一使用 `@zl-ui-kit/utils` 的方法替换，避免重复实现与行为不一致。
-13. **先读透传契约**：动手替换前读完 [§15.5 迁移行为差异与透传契约](#155-迁移行为差异与透传契约必读)——未列在 props 表的属性与事件大多直接透传给内部 `el-*`，而少数默认值 / 入参语义与 EP 不等价，需逐条核对。
+13. **字典加载与翻译**：宿主页面里「请求字典接口 → 存成选项数组 → 再用 `Record<value, label>` 把码值转中文」的自建逻辑，统一换成 `useDict` + `ZlDictTag` —— 应用入口用 `setDictSource(...)` 注册**一次**数据源（静态表，或 `(key) => api.getDict(key)` 异步加载），页面内用 `useDict(key)` 取字典项与 `value → label` 映射（`useDict(key).value` 是 `DictItem[]`，`useDict(key).label.value[code]` 是中文）供下拉 / 单选等选项使用，表格与详情里的字典列直接用 `<ZlDictTag :dict-key="key" :value="row.xxx" />` 渲染；**不要在页面里各自请求字典接口，也不要再维护 label 常量表**（同一字典被多处重复请求、各处文案不一致，正是这类自建逻辑的典型副作用）。两个易踩点：`dictKey` 是**全局缓存键**（同一 key 只加载一次、跨组件复用），列表里**不要逐行直传不同的 `:dict`**（会覆盖全局同名缓存、最后一行赢，行级字典请用专属 key）；`DictItem.value` 是字符串且与业务值做**严格相等**比较，后端返回数字码时要先 `String()`。详见 §6.3 ⑤ 与 §12.1.3。
+14. **提示消息**：页面里的 `ElMessage` / `ElMessageBox` / `ElNotification`（含 `ElMessage.success(...)`、`ElMessageBox.confirm(...)`、`ElNotification({...})` 等写法）统一改用 `useGlobalMessage()` 取实例 —— `const { Message, Modal, Notification } = useGlobalMessage()`；其中 `Modal` 在 `ElMessageBox` 之上扩展了 `confirmPromise(config, onOk, onCancel)`，需要「二次确认 + 执行异步操作（如删除）」时优先用它：返回 `'Ok' | 'Cancel' | false`，由它统一处理关闭时机与 `onOk` 抛错（`throwOnOk` / `throwOnCancel` 可控），不必每处各写一遍 `.then/.catch`；同时保证与组件库走**同一份 element-plus 实例**（peer 依赖），而不是再引入一套 EP。详见 §12.1.4。
+15. **先读透传契约**：动手替换前读完 [§15.5 迁移行为差异与透传契约](#155-迁移行为差异与透传契约必读)——未列在 props 表的属性与事件大多直接透传给内部 `el-*`，而少数默认值 / 入参语义与 EP 不等价，需逐条核对。
 
 ### 15.2 常用 el-* → Zl-* 对照表（持续补充）
 
-| Element Plus 组件                                 | 替换为              | 说明                                               |
-| ------------------------------------------------- | ------------------- | -------------------------------------------------- |
-| `el-table`（普通 / 分页列表）                     | `ZlSearchTable`     | 自带查询条、分页、loading                          |
-| `el-table`（卡片分页列表）                        | `ZlCardPage`        | 卡片式分页列表                                     |
-| `el-table`（纯表格，无查询）                      | `ZlTable`           | 普通表格展示                                       |
-| `el-dialog` / `el-drawer`                         | `ZlDrawer`          | 所有弹窗统一为抽屉                                 |
-| `el-form`                                         | `ZlForm`            | 弹窗内新增 / 编辑 / 详情表单（schema 驱动）        |
-| `el-card`                                         | `ZlCard`            | 卡片容器                                           |
-| `el-button`（操作栏 / 卡片内）                    | `ZlAction`          | 操作列与卡片按钮；页面级独立按钮仍可用 `el-button` |
-| `el-tooltip`（超长省略）                          | `ZlAutoTooltip`     | 文字溢出时自动提示                                 |
-| `el-icon`                                         | `ZlIcon`            | 需先注册图标集（§4.1）                             |
-| `el-tree`                                         | `ZlTree`            | 勾选多选 / 字段映射 / 暴露方法见 §7 › ZlTree       |
-| `el-upload`                                       | `ZlUpload`          |                                                    |
-| `el-tag`                                          | `ZlTag`             |                                                    |
-| `el-tabs`                                         | `ZlTabs`            | 页签内容默认懒挂载，差异见 §15.5                   |
-| `el-radio`（标签式）                              | `ZlRadioTag`        | 仅此形态封装                                       |
-| `el-checkbox`（标签式）                           | `ZlCheckboxTag`     | 仅此形态封装                                       |
-| `el-checkbox`（全选 / 半选）                      | `ZlCheckAll`        | 自带半选态，可替代表头全选勾选框                   |
-| `el-radio` / `el-checkbox`（普通单选框 / 复选框） | —（**有意不封装**） | 继续用 `el-*`，库内无对应物（见 §15.5）            |
-| `el-radio-group` / `el-checkbox-group`            | —（**有意不封装**） | 继续用 `el-*`，组内选项自行渲染                    |
-| `el-switch`                                       | `ZlSwitch`          |                                                    |
-| `el-popconfirm`                                   | `ZlPopconfirm`      |                                                    |
-| `el-empty`                                        | `ZlEmpty`           |                                                    |
-| `el-avatar`                                       | `ZlAvatar`          |                                                    |
-| `el-descriptions`                                 | `ZlDescription`     |                                                    |
-| `el-text`                                         | `ZlText`            |                                                    |
-| `el-pagination`                                   | `ZlPagination`      |                                                    |
-| `el-select`（树形）                               | `ZlTreeSelect`      |                                                    |
+| Element Plus 组件                                 | 替换为               | 说明                                                               |
+| ------------------------------------------------- | -------------------- | ------------------------------------------------------------------ |
+| `el-table`（普通 / 分页列表）                     | `ZlSearchTable`      | 自带查询条、分页、loading                                          |
+| `el-table`（卡片分页列表）                        | `ZlCardPage`         | 卡片式分页列表                                                     |
+| `el-table`（纯表格，无查询）                      | `ZlTable`            | 普通表格展示                                                       |
+| `el-dialog` / `el-drawer`                         | `ZlDrawer`           | 所有弹窗统一为抽屉                                                 |
+| `el-form`                                         | `ZlForm`             | 弹窗内新增 / 编辑 / 详情表单（schema 驱动）                        |
+| `el-card`                                         | `ZlCard`             | 卡片容器                                                           |
+| `el-button`（操作栏 / 卡片内）                    | `ZlAction`           | 操作列与卡片按钮；页面级独立按钮仍可用 `el-button`                 |
+| `el-tooltip`（超长省略）                          | `ZlAutoTooltip`      | 文字溢出时自动提示                                                 |
+| `el-icon`                                         | `ZlIcon`             | 需先注册图标集（§4.1）                                             |
+| `el-tree`                                         | `ZlTree`             | 勾选多选 / 字段映射 / 暴露方法见 §7 › ZlTree                       |
+| `el-upload`                                       | `ZlUpload`           |                                                                    |
+| `el-tag`                                          | `ZlTag`              |                                                                    |
+| `el-tabs`                                         | `ZlTabs`             | 页签内容默认懒挂载，差异见 §15.5                                   |
+| `el-radio`（标签式）                              | `ZlRadioTag`         | 仅此形态封装                                                       |
+| `el-checkbox`（标签式）                           | `ZlCheckboxTag`      | 仅此形态封装                                                       |
+| `el-checkbox`（全选 / 半选）                      | `ZlCheckAll`         | 自带半选态，可替代表头全选勾选框                                   |
+| `el-radio` / `el-checkbox`（普通单选框 / 复选框） | —（**有意不封装**）  | 继续用 `el-*`，库内无对应物（见 §15.5）                            |
+| `el-radio-group` / `el-checkbox-group`            | —（**有意不封装**）  | 继续用 `el-*`，组内选项自行渲染                                    |
+| `el-switch`                                       | `ZlSwitch`           |                                                                    |
+| `el-popconfirm`                                   | `ZlPopconfirm`       |                                                                    |
+| `el-empty`                                        | `ZlEmpty`            |                                                                    |
+| `el-avatar`                                       | `ZlAvatar`           |                                                                    |
+| `el-descriptions`                                 | `ZlDescription`      |                                                                    |
+| `el-text`                                         | `ZlText`             |                                                                    |
+| `el-pagination`                                   | `ZlPagination`       |                                                                    |
+| `el-select`（树形）                               | `ZlTreeSelect`       |                                                                    |
+| `ElMessage` / `ElNotification`（提示消息）        | `useGlobalMessage()` | 非组件，用 hook 取 `Message` / `Notification` 实例（§12.1.4）      |
+| `ElMessageBox`（确认框）                          | `useGlobalMessage()` | 取 `Modal`（扩展 `confirmPromise`），二次确认 + 异步操作统一在这里 |
 
 > 未在上表中的 `el-*` 组件，请对照 §3 组件总览的命名与用途选择对应 Zl 组件；若暂无对应实现，暂保留 `el-*`，并在本规范登记为待补充项。
 > 替换前请先读 **[§15.5 迁移行为差异与透传契约](#155-迁移行为差异与透传契约必读)**：哪些属性默认直接透传、哪些行为与 EP 不等价。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zl-ui-kit/components",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "type": "module",
   "description": "ZL UI 业务组件库（Element Plus 体系，Zl 前缀）——首批：Icon/AutoTooltip/Tag/CornerTag/Text/Title/Copy/Empty/Pagination/DictTag",
   "license": "MIT",
@@ -39,9 +39,9 @@
     "file-type": "^20.4.1",
     "dt-sql-parser": "^4.3.1",
     "sql-formatter": "^15.4.2",
-    "@zl-ui-kit/composables": "0.10.1",
-    "@zl-ui-kit/utils": "0.10.1",
-    "@zl-ui-kit/icons": "0.10.1"
+    "@zl-ui-kit/composables": "0.10.3",
+    "@zl-ui-kit/utils": "0.10.3",
+    "@zl-ui-kit/icons": "0.10.3"
   },
   "peerDependencies": {
     "@vueuse/core": "^12.3.0",
@@ -98,10 +98,10 @@
     "@vue-office/pdf": "^2.0.10",
     "@vue-office/pptx": "1.0.1",
     "echarts": "^5.6.0",
+    "@jichuang/vite-config": "1.0.0",
     "@jichuang/tsconfig": "1.0.0",
     "@jichuang/eslint-config": "1.0.0",
-    "@zl-ui-kit/theme": "0.10.1",
-    "@jichuang/vite-config": "1.0.0"
+    "@zl-ui-kit/theme": "0.10.3"
   },
   "repository": {
     "type": "git",