@zl-ui-kit/components 0.18.7 → 0.18.8

package/README.md

@@ -803,6 +803,16 @@ presetIconifyIcon(icons)
 
 来源：`@zl-ui-kit/composables`。`service` 统一签名：`(...args) => Promise<R>`。
 
+四个 hook 共享同一套状态与方法（`loading` / `data` / `error` / `status` / `run` / `runAsync` /
+`refresh` / `refreshAsync` / `cancel` / `mutate`），差别只在 `data` 怎么取：
+
+| Hook                   | 适用的接口响应                       | `data` 内容                                                                 |
+| ---------------------- | ------------------------------------ | --------------------------------------------------------------------------- |
+| `useRequest`           | 任意                                 | 原始响应 `R`                                                                |
+| `useDataRequest`       | 信封对象（如 `{ code, msg, data }`） | 解包后的 `响应[dataKey]`，取不到时回落到 `initialData`                      |
+| `usePageableRequest`   | 数组 **或** 分页对象                 | 数组原样返回；对象则 `{ ...响应, pageNum, pageSize }`（页码取本次请求入参） |
+| `usePaginationRequest` | 分页对象                             | 行数组，另给 `total` / `current` / `pageSize` / `change*`                   |
+
 #### `useRequest(service, options?, plugins?)` —— 基础形态
 
 ```ts
@@ -825,13 +835,82 @@ const { loading, data, error, status, run, runAsync, refresh, refreshAsync, canc
 | `options.onBefore/onSuccess/onError/onFinally` | 生命周期回调                                                |
 | `options.loadingDelay` / `refreshDeps`         | 延迟 loading / 依赖变更刷新                                 |
 
-#### `useDataRequest(service, { dataKey = 'data' })` —— 自动解包信封
+#### `useDataRequest(service, { dataKey = 'data' })` —— 解包信封响应
+
+适用：后端统一返回 `{ code, msg, data }` 这类信封，页面只关心内层业务数据。
+
+```ts
+const { data, loading, run, runAsync, refresh } = useDataRequest(getDetailApi)
+// data.value === 响应.data
+```
+
+| 选项          | 说明                                                                              |
+| ------------- | --------------------------------------------------------------------------------- |
+| `dataKey`     | 信封里承载业务数据的字段名，默认 `data`                                           |
+| `initialData` | 解包结果为空（未请求 / 该 key 不存在）时的兜底值，**按解包后的数据形态传**        |
+| `manual`      | `true` 时挂载不请求，需 `run` / `runAsync` 触发；其余选项与 `useRequest` 完全一致 |
+
+真实页面里最常见的三种写法：
+
+```ts
+// 1) 自动请求 + 兜底：模板可直接渲染，不必到处判空
+const { data: detail, loading } = useDataRequest(getDetailApi, { initialData: {} })
+
+// 2) 手动触发：点击按钮 / 打开抽屉时再查
+const { data: detail, loading, runAsync } = useDataRequest(getDetailApi, { manual: true })
+async function open(row: { id: number }) {
+  const res = await runAsync({ id: row.id }) // res 是原始信封，不是解包后的 data
+  // 需要解包值请读 detail.value
+}
+
+// 3) service 用闭包读取 props（详情组件按 id 查询）
+const { data: detail, run: fetchDetail } = useDataRequest(() => getDetailApi({ id: props.id }))
+// props.id 变化后需自行 refresh() / run()，或把变化源放进 refreshDeps
+```
+
+> 注意：`useDataRequest` 只适合**对象信封**。接口直接返回数组时 `rawData[dataKey]` 取不到值，
+> `data` 会恒等于 `initialData`——数组 / 分页响应请改用 `usePageableRequest` 或 `useRequest`。
+> 另外 `onSuccess(data, params)` 与 `runAsync()` 拿到的都是**原始响应 `R`**，不是解包后的值。
+
+#### `usePageableRequest(service, options?, plugins?)` —— 列表 / 分页响应适配
+
+适用：把「数组响应」和「分页对象响应」统一成同一份 `data`，供 `ZlSearchTable` / `ZlCardPage`
+或自定义列表使用。返回值与 `useRequest` 相同，只改写了 `data`：
+
+| 接口响应                                    | `data.value`                                                         |
+| ------------------------------------------- | -------------------------------------------------------------------- |
+| `TreeNode[]` 等数组                         | 原样返回数组                                                         |
+| `{ rows, total, pageNum, pageSize }` 等对象 | `{ ...响应, pageNum, pageSize }`（响应没回页码时用本次请求入参补齐） |
+
+```ts
+// 后端直接返回数组：data 就是数组，initialData 兜底空列表
+const { data: treeData, loading } = usePageableRequest(getTreeApi, { initialData: [] })
+
+// 后端返回分页对象：data.rows 是行数据，data.pageNum / data.pageSize 已被补齐
+const { data: pageData, loading, run } = usePageableRequest(getPageApi, { manual: true })
+run({ pageNum: 2, pageSize: 20 })
+// pageData.value.rows / total / pageNum / pageSize
+```
+
+**它不提供 `total` / `current` / `pageSize` / 翻页方法**——需要自己控制分页器时用
+`usePaginationRequest`；只是给组件喂数据、或读取 `loading` / `refresh` 时用 `usePageableRequest`。
+
+**实例形态直传组件**（页面侧要接管 `loading` / `refresh` 时）：
 
 ```ts
-const { data } = useDataRequest(getChartDataApi, { dataKey: 'data' })
-// data.value === 响应里的 data 字段
+const cardRequest = usePageableRequest(getPageApi, { manual: true, initialData: [] })
+// 组件内部的搜索 / 翻页仍调用同一实例的 run，loading / data 与页面共享
 ```
 
+```vue
+<ZlCardPage :request="cardRequest" card-min-width="200px" :pagination="{ pageSize: 6 }">
+  <template #default="{ data }">…</template>
+</ZlCardPage>
+```
+
+> `ZlSearchTable` / `ZlCardPage` 默认在内部自行创建 `usePageableRequest`，**页面直接传 service 即可**；
+> 只有需要在页面里读取同一份 `loading` / `data` / `refresh` 时才传实例（见 §6.3 ⑨）。
+
 #### `usePaginationRequest(service, { pagination })` —— 分页专用
 
 额外返回 `data`(行数组) / `total` / `current` / `pageSize` / `changeCurrent` / `changePageSize` / `changePagination`，分页键名（`pageNum/pageSize/total/rows`）可配置，与后端契约对齐时通过 `pagination` 选项或 `setGlobalOptions` 调整。
@@ -1150,9 +1229,10 @@ const { data: treeData, loading: treeLoading } = treeReq
 `ZlChart` 显式 prop 为 `series`，其余配置（title/xAxis/yAxis/tooltip/grid）经 attrs 透传，故用 `v-bind` 传完整 echarts option：
 
 ```ts
-const chartReq = useDataRequest(getChartDataApi, { dataKey: 'data' })
+const chartReq = useDataRequest(getChartDataApi) // 默认 dataKey='data'
+const { data: chartData, loading: chartLoading } = chartReq // 顶层 ref 才会在模板自动解包
 const chartOption = computed(() => {
-  const d = chartReq.data.value
+  const d = chartData.value
   if (!d) return {}
   return {
     tooltip: { trigger: 'axis' },
@@ -1164,7 +1244,8 @@ const chartOption = computed(() => {
 ```
 
 ```vue
-<ZlChart v-bind="chartOption" />
+<el-skeleton v-if="chartLoading" :rows="5" />
+<ZlChart v-else v-bind="chartOption" />
 ```
 
 | Prop     | 类型                 | 说明                                                                                                                |
@@ -1174,7 +1255,44 @@ const chartOption = computed(() => {
 
 > 暴露方法：`clear()`（模板 ref 调用）。尺寸自适应由 `useResizeObserver` 负责，容器需有明确高度。
 
-#### ⑨ `useRequest` 生命周期面板
+需要「点击后再拉取」时用 `manual + runAsync`；`runAsync()` 返回原始信封，解包后的值仍看 `data`：
+
+```ts
+const { data: chartData, runAsync: fetchChartAsync } = useDataRequest(getChartDataApi, {
+  manual: true,
+})
+async function fetchChart() {
+  const res = await fetchChartAsync() // res: { code, msg, data }
+  console.log(res.code, chartData.value)
+}
+```
+
+#### ⑨ `usePageableRequest` —— 数组 / 分页对象 / 实例直传
+
+接口返回数组或分页对象都能用；组件需要自己接管 `loading` / `refresh` 时，直接传实例：
+
+```ts
+// 数组响应：data 原样是数组
+const { data: treeData, loading } = usePageableRequest(getTreeApi, { initialData: [] })
+
+// 分页对象响应：data.rows 是行数据，pageNum / pageSize 已用本次入参补齐
+const { data: pageData, loading, run } = usePageableRequest(getPageApi, { manual: true })
+run({ pageNum: 1, pageSize: 20 })
+
+// 实例形态直传 ZlCardPage：组件的搜索 / 翻页复用同一实例
+const cardRequest = usePageableRequest(getPageApi, { manual: true, initialData: [] })
+```
+
+```vue
+<ZlCardPage :request="cardRequest" card-min-width="200px" :pagination="{ pageSize: 6 }">
+  <template #default="{ data }">{{ data.name }}</template>
+</ZlCardPage>
+```
+
+> 与 `usePaginationRequest` 的区别：`usePageableRequest` 只改写 `data`、不提供 `total` / 翻页方法，
+> 用于给组件喂数据；页面要自己渲染分页器时用 `usePaginationRequest`（见 ③ / ④）。
+
+#### ⑩ `useRequest` 生命周期面板
 
 ```ts
 const req = useRequest(getResourcePageMaybeFail, { defaultParams: [{ pageNum: 1, pageSize: 5 }] })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zl-ui-kit/components",
-  "version": "0.18.7",
+  "version": "0.18.8",
   "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.18.7",
-    "@zl-ui-kit/icons": "0.18.7",
-    "@zl-ui-kit/utils": "0.18.7"
+    "@zl-ui-kit/utils": "0.18.8",
+    "@zl-ui-kit/composables": "0.18.8",
+    "@zl-ui-kit/icons": "0.18.8"
   },
   "peerDependencies": {
     "@vueuse/core": "^12.3.0 || ^13.0.0 || ^14.0.0 || ^15.0.0",
@@ -98,10 +98,10 @@
     "@vue-office/pdf": "^2.0.10",
     "@vue-office/pptx": "1.0.1",
     "echarts": "^5.6.0",
-    "@jichuang/eslint-config": "1.0.0",
     "@jichuang/tsconfig": "1.0.0",
-    "@jichuang/vite-config": "1.0.0",
-    "@zl-ui-kit/theme": "0.18.7"
+    "@zl-ui-kit/theme": "0.18.8",
+    "@jichuang/eslint-config": "1.0.0",
+    "@jichuang/vite-config": "1.0.0"
   },
   "repository": {
     "type": "git",