@zl-ui-kit/components 0.10.2 → 0.10.4

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>
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zl-ui-kit/components",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "type": "module",
   "description": "ZL UI 业务组件库（Element Plus 体系，Zl 前缀）——首批：Icon/AutoTooltip/Tag/CornerTag/Text/Title/Copy/Empty/Pagination/DictTag",
   "license": "MIT",
@@ -39,12 +39,12 @@
     "file-type": "^20.4.1",
     "dt-sql-parser": "^4.3.1",
     "sql-formatter": "^15.4.2",
-    "@zl-ui-kit/utils": "0.10.2",
-    "@zl-ui-kit/icons": "0.10.2",
-    "@zl-ui-kit/composables": "0.10.2"
+    "@zl-ui-kit/composables": "0.10.4",
+    "@zl-ui-kit/icons": "0.10.4",
+    "@zl-ui-kit/utils": "0.10.4"
   },
   "peerDependencies": {
-    "@vueuse/core": "^12.3.0",
+    "@vueuse/core": "^12.3.0 || ^13.0.0 || ^14.0.0 || ^15.0.0",
     "element-plus": "^2.9.2",
     "vue": "^3.5.13",
     "monaco-editor": "^0.41.0",
@@ -79,7 +79,7 @@
     "@typescript-eslint/eslint-plugin": "^8.19.1",
     "@typescript-eslint/parser": "^8.19.1",
     "@vitejs/plugin-vue": "^5.2.1",
-    "@vueuse/core": "^12.3.0",
+    "@vueuse/core": "^12.3.0 || ^13.0.0 || ^14.0.0 || ^15.0.0",
     "cross-env": "^7.0.3",
     "element-plus": "^2.9.2",
     "eslint-plugin-vue": "^9.32.0",
@@ -100,7 +100,7 @@
     "echarts": "^5.6.0",
     "@jichuang/vite-config": "1.0.0",
     "@jichuang/tsconfig": "1.0.0",
-    "@zl-ui-kit/theme": "0.10.2",
+    "@zl-ui-kit/theme": "0.10.4",
     "@jichuang/eslint-config": "1.0.0"
   },
   "repository": {