@zl-ui-kit/components 0.5.1 → 0.6.1

package/README.md

@@ -12,13 +12,13 @@ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，47 个业务组
 
 `zl-ui` 是一套基于 **Element Plus（EP）** 的企业级 Vue 3 组件库，以 EP 为底座，封装了 47 个 `Zl` 前缀业务组件，并提供请求、主题、图标、工具四套配套能力。
 
-| 包 | 职责 |
-| --- | --- |
-| [`@zl-ui-kit/components`](https://www.npmjs.com/package/@zl-ui-kit/components) | EP 化业务组件库（`Zl` 前缀，47 个组件） |
+| 包                                                                               | 职责                                                               |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| [`@zl-ui-kit/components`](https://www.npmjs.com/package/@zl-ui-kit/components)   | EP 化业务组件库（`Zl` 前缀，47 个组件）                            |
 | [`@zl-ui-kit/composables`](https://www.npmjs.com/package/@zl-ui-kit/composables) | `useRequest` 请求体系、`useDict`、`useGlobalData` 全局数据、国际化 |
-| [`@zl-ui-kit/icons`](https://www.npmjs.com/package/@zl-ui-kit/icons) | 444 个离线 SVG 图标（prefix `zl`，开源图标库） |
-| [`@zl-ui-kit/theme`](https://www.npmjs.com/package/@zl-ui-kit/theme) | 5 套主题 + `defineTheme` 运行时定制（内置 OFL 开源中文字体） |
-| [`@zl-ui-kit/utils`](https://www.npmjs.com/package/@zl-ui-kit/utils) | TS 工具函数库 + Axios 请求封装 |
+| [`@zl-ui-kit/icons`](https://www.npmjs.com/package/@zl-ui-kit/icons)             | 444 个离线 SVG 图标（prefix `zl`，开源图标库）                     |
+| [`@zl-ui-kit/theme`](https://www.npmjs.com/package/@zl-ui-kit/theme)             | 5 套主题 + `defineTheme` 运行时定制（内置 OFL 开源中文字体）       |
+| [`@zl-ui-kit/utils`](https://www.npmjs.com/package/@zl-ui-kit/utils)             | TS 工具函数库 + Axios 请求封装                                     |
 
 **三个关键约定（使用组件前必读）**
 
@@ -41,11 +41,11 @@ npm i vue element-plus @vueuse/core
 
 以下组件**不在主入口**，走独立子路径，依赖按需安装（`peerDependenciesMeta.optional`，没装也不会导致主入口编译失败）：
 
-| 子入口 | 组件 | 需安装 |
-| --- | --- | --- |
-| `@zl-ui-kit/components/chart` | `ZlChart` | `echarts` |
-| `@zl-ui-kit/components/editor` | `ZlEditor` / `ZlSqlEditor` / `useSqlCompletion` | `monaco-editor` |
-| `@zl-ui-kit/components/file-preview` | `ZlFilePreview` / `ZlFileViewer` | `@vue-office/docx` `@vue-office/excel` `@vue-office/pdf` `@vue-office/pptx` |
+| 子入口                               | 组件                                            | 需安装                                                                      |
+| ------------------------------------ | ----------------------------------------------- | --------------------------------------------------------------------------- |
+| `@zl-ui-kit/components/chart`        | `ZlChart`                                       | `echarts`                                                                   |
+| `@zl-ui-kit/components/editor`       | `ZlEditor` / `ZlSqlEditor` / `useSqlCompletion` | `monaco-editor`                                                             |
+| `@zl-ui-kit/components/file-preview` | `ZlFilePreview` / `ZlFileViewer`                | `@vue-office/docx` `@vue-office/excel` `@vue-office/pdf` `@vue-office/pptx` |
 
 ```ts
 import { ZlChart } from '@zl-ui-kit/components/chart'
@@ -71,7 +71,7 @@ import { ZlFilePreview, ZlFileViewer } from '@zl-ui-kit/components/file-preview'
 import { createApp } from 'vue'
 import ElementPlus from 'element-plus'
 import 'element-plus/dist/index.css'
-import '@zl-ui-kit/theme/themes.css'      // 主题变量（--zl-* / --el-*）
+import '@zl-ui-kit/theme/themes.css' // 主题变量（--zl-* / --el-*）
 import ZlUI from '@zl-ui-kit/components'
 
 createApp(App).use(ElementPlus).use(ZlUI).mount('#app')
@@ -141,41 +141,60 @@ pnpm --filter @zl-ui-kit/playground dev     # http://localhost:3100
 
 playground 以 **源码模式** 运行，vite alias 将 `@zl-ui-kit/*` 五包精确指向各自 `src/`：
 
-| 别名 | 指向 |
-| --- | --- |
-| `@zl-ui-kit/utils` | `packages/utils/src/index.ts` |
-| `@zl-ui-kit/composables` | `packages/composables/src/index.ts` |
-| `@zl-ui-kit/components` | `packages/components/src/index.ts` |
-| `@zl-ui-kit/theme`（JS API） | `packages/theme/src/index.ts` |
-| `@zl-ui-kit/icons` | `packages/icons/src/index.mjs` |
+| 别名                         | 指向                                |
+| ---------------------------- | ----------------------------------- |
+| `@zl-ui-kit/utils`           | `packages/utils/src/index.ts`       |
+| `@zl-ui-kit/composables`     | `packages/composables/src/index.ts` |
+| `@zl-ui-kit/components`      | `packages/components/src/index.ts`  |
+| `@zl-ui-kit/theme`（JS API） | `packages/theme/src/index.ts`       |
+| `@zl-ui-kit/icons`           | `packages/icons/src/index.mjs`      |
 
 **效果：直接改任意包的 `src` 源码，playground 即时热更，无需先构建。**
 
+playground 的界面按 **Element Plus 官网的信息架构**组织（顶栏 + 左侧分组目录 + 右侧内容）：
+
+| 位置     | 内容                                                                                                                                          |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 顶栏     | Logo、一级导航（组件/主题/图标/示例/手册）、组件搜索（`Ctrl K` 聚焦，↑↓ 选择、Enter 跳转）、语言与主题切换                                    |
+| 左侧栏   | 「指南」「综合示例」+ 按功能分 7 组（基础/布局/表单/数据展示/反馈/文件与编辑器/其他）的全部组件，分组可折叠                                   |
+| 组件总览 | `/#/`，每个组件一张卡片（图标 + 中文名 + 导出符号），点击进入组件页                                                                           |
+| 组件页   | `/#/component/ZlTable`，依次是「基础用法」实时示例 → 用法示例 / 插槽用法代码块 → props/事件/插槽/暴露方法表（props 与插槽表各带一列「示例」） |
+| 接口手册 | `/#/manual`，跨组件检索（按 props 名 / 事件名反查组件），支持 `?name=ZlTable` 直接定位                                                        |
+
+> 组件页的示例来自 `apps/playground/src/pages/gallery-demos.ts`（与冒烟测试同一份渲染函数），
+> 接口表来自 `pnpm docs:api` 产物 —— 与本文件第 14 章同源：改完组件源码记得重跑，否则 `pnpm check` 会报产物过期。
+> 两处的 **用法示例 / 插槽用法** 代码块也是同一份字符串，页面里可一键复制；
+> 每个 prop / 插槽的「示例」列同样是同一份字符串（可直接粘贴的属性写法 / `<template #name>` 片段）。
+
 > 注意：`@zl-ui-kit/theme/light`、`@zl-ui-kit/theme/themes.css` 等 CSS 子路径不走别名，读取 `src/generated/` 生成物——改主题 token 后需先 `pnpm --filter @zl-ui-kit/theme gen`。
 
 ### 2.3 主题快速接入（宿主项目）
 
 ```ts
 // main.ts
-import '@zl-ui-kit/theme/themes.css'   // 全部内置主题（或按需 '@zl-ui-kit/theme/light' 等）
+import '@zl-ui-kit/theme/themes.css' // 全部内置主题（或按需 '@zl-ui-kit/theme/light' 等）
 import { setTheme } from '@zl-ui-kit/theme'
 
-setTheme('dark')               // 切换主题（light/dark/red-light/red-dark/blue）
+setTheme('dark') // 切换主题（light/dark/red-light/red-dark/blue）
 ```
 
 ### 2.4 示例页面索引
 
-| 路由 | 页面 | 覆盖内容 |
-| --- | --- | --- |
-| `/` | 首页 | 说明与导航 |
-| `/icons` | 图标集 | 全量图标浏览/搜索，`zl:` 前缀渲染 |
-| `/theme` | 主题工场 | 5 套主题切换 + `defineTheme` 运行时自定义 |
-| `/components` | 组件示例 | ZlTitle/ZlTag/ZlCornerTag/ZlIcon/ZlText/ZlCopy/ZlAutoTooltip/ZlPagination/ZlEmpty |
-| `/table-form` | 表格/表单示例 | ZlTable/ZlSearchTable/ZlForm/ZlDrawer/ZlPopconfirm/ZlSwitch/ZlDescription/ZlAction/ZlIconLabel/ZlIconHover/ZlSearch |
-| `/general` | 通用/布局示例 | ZlAvatar/ZlCheckAll/ZlRadioTag/ZlCheckboxTag/ZlAddSub/ZlSorter/ZlLayoutSwitch/ZlSection/ZlCard/ZlAppSlogan/ZlPermission/ZlHorizontalTable/ZlUpload/ZlTabs/ZlGrid/ZlDynamicComponent/ZlCardPage |
-| `/use-request` | useRequest 联调 | 用 Mock 模块驱动各数据型组件（见第 6 章） |
-| `/search-table` | ZlSearchTable 专项 | 基础用法 / `{ service, options }` 用法 / 暴露方法 / 无查询项 immediate，含分页与查询验证 |
-| `/gallery` | 组件陈列 | 55 个组件逐个渲染（用于批量截图与冒烟） |
+| 路由                     | 页面               | 覆盖内容                                                                                                                                                                                       |
+| ------------------------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/`                      | 组件总览           | 按功能分组的组件卡片，点击进入组件页（Element Plus 官网 overview 的组织方式）                                                                                                                  |
+| `/component/:name`       | 组件页             | 基础用法实时示例 + 用法示例 / 插槽用法代码块 + props / 事件 / 插槽 / 暴露方法表 + 上/下一页                                                                                                    |
+| `/manual`                | 接口手册           | 全量 API 检索，支持按 props 名 / 事件名反查组件，`?name=ZlTable` 直接定位                                                                                                                      |
+| `/icons`                 | 图标集             | 全量图标浏览/搜索，`zl:` 前缀渲染                                                                                                                                                              |
+| `/theme`                 | 主题工场           | 5 套主题切换 + `defineTheme` 运行时自定义                                                                                                                                                      |
+| `/gallery`               | 组件陈列           | 55 个组件逐个渲染（用于批量截图与冒烟）                                                                                                                                                        |
+| `/use-request`           | useRequest 联调    | 用 Mock 模块驱动各数据型组件（见第 6 章）                                                                                                                                                      |
+| `/examples/basic`        | 通用展示示例       | ZlTitle/ZlTag/ZlCornerTag/ZlIcon/ZlText/ZlCopy/ZlAutoTooltip/ZlPagination/ZlEmpty                                                                                                              |
+| `/examples/table-form`   | 表格/表单示例      | ZlTable/ZlSearchTable/ZlForm/ZlDrawer/ZlPopconfirm/ZlSwitch/ZlDescription/ZlAction/ZlIconLabel/ZlIconHover/ZlSearch                                                                            |
+| `/examples/general`      | 布局与交互示例     | ZlAvatar/ZlCheckAll/ZlRadioTag/ZlCheckboxTag/ZlAddSub/ZlSorter/ZlLayoutSwitch/ZlSection/ZlCard/ZlAppSlogan/ZlPermission/ZlHorizontalTable/ZlUpload/ZlTabs/ZlGrid/ZlDynamicComponent/ZlCardPage |
+| `/examples/search-table` | ZlSearchTable 专项 | 基础用法 / `{ service, options }` 用法 / 暴露方法 / 无查询项 immediate，含分页与查询验证                                                                                                       |
+
+> 改造前的扁平路由（`/components`、`/general`、`/table-form`、`/search-table`）保留 **redirect**，历史链接与自动化脚本不会失效。
 
 ---
 
@@ -183,24 +202,32 @@ setTheme('dark')               // 切换主题（light/dark/red-light/red-dark/b
 
 > 下面按功能分组，列出的是**导出符号**（含同目录变体，如 `ZlCornerTag` / `ZlIconHover` / `ZlActionList`），所以条目数略多于 47；组件目录共 48 个（47 个业务组件 + `ZlI18nProvider`）。
 
+> **要查精确的 props / 事件 / 插槽 / 暴露方法 / schema 类型？** 直接看 **[§14 组件 API 参考](#14-组件-api-参考自动生成)**——逐个组件给出 `import`、可直接照抄的 **用法示例**（props 怎么写）与 **插槽用法**（`<template #name>` 怎么写），再用表格列出 TS 类型表达式、默认值、是否必填，**且每个 prop / 每个插槽都带一列「示例」**（能直接粘到标签上的写法），以及 `TableColumn` / `FormItem` / `SearchItem` / `ActionItem` 等 schema 类型的字段表。本章及 §4~§9 讲的是**场景化用法**，§14 是**逐字段的契约 + 可粘贴代码**。
+
 ### 3.1 通用展示组件
+
 `ZlIcon` · `ZlTitle` · `ZlTag` · `ZlCornerTag` · `ZlText` · `ZlCopy` · `ZlAutoTooltip` · `ZlEmpty` · `ZlDictTag` · `ZlDescription` · `ZlSection` · `ZlCard` · `ZlAvatar` · `ZlAppSlogan` · `ZlIconLabel` · `ZlIconHover`
 
 ### 3.2 数据型组件
+
 `ZlTable` · `ZlSearchTable` · `ZlCardPage` · `ZlPagination` · `ZlTree` · `ZlTreeSelect` · `ZlChart` · `ZlUpload`
 
 ### 3.3 表单与交互组件
+
 `ZlForm` · `ZlSearch` · `ZlDrawer` · `ZlPopconfirm` · `ZlSwitch` · `ZlAction` · `ZlActionList` · `ZlRadioTag` · `ZlCheckboxTag` · `ZlCheckAll` · `ZlSorter` · `ZlAddSub` · `ZlLayoutSwitch` · `ZlTabs` · `ZlDynamicComponent` · `ZlGrid`
 
 ### 3.4 布局与权限
+
 `ZlAppLayout` · `ZlAppMenu` · `ZlPermission` · `ZlHorizontalTable`
 
 ### 3.5 文件与编辑
+
 `ZlFilePreview` · `ZlFileViewer` · `ZlPdfViewer` · `ZlEditor` · `ZlSqlEditor` · `ZlLogin`
 
 > 页签/微前端类组件（`ZlMicroPage`/`ZlAppTabs`/`ZlPageTabs`/`ZlDevMenu`）与配套 composables（`usePageTabs` 等）均已移除，`0.5.0` 起组件库不含任何微前端能力。
 
 ### 3.6 国际化基础设施（独立于 47 个业务组件）
+
 `ZlI18nProvider` —— 国际化根容器，将 Element Plus 语言包经 `<el-config-provider>` 挂载到 Element Plus（详见第 13 章）。
 
 ---
@@ -214,11 +241,33 @@ setTheme('dark')               // 切换主题（light/dark/red-light/red-dark/b
 <ZlIcon icon="zl:database-color" :size="20" />
 ```
 
-| prop | 说明 |
-| --- | --- |
-| `icon` | 图标名，支持 `zl:xxx`（内置）、`https://...`（外链）、普通名（iconify 在线集，需联网） |
-| `size` | 字号/尺寸，默认 `14px` |
-| `color` / `spin` 等 | 透传至底层 iconify-icon |
+| prop                | 说明                                                                                   |
+| ------------------- | -------------------------------------------------------------------------------------- |
+| `icon`              | 图标名，支持 `zl:xxx`（内置）、`https://...`（外链）、普通名（iconify 在线集，需联网） |
+| `size`              | 字号/尺寸，默认 `14px`                                                                 |
+| `color` / `spin` 等 | 透传至底层 iconify-icon                                                                |
+
+### 4.1 必须先注册图标集（否则一个图标都不显示）
+
+`ZlIcon` 走 `@iconify/vue/offline`，**库不会自动把 444 个图标塞进打包结果**（否则不用图标的宿主也会白扛 ~150KB）。
+消费方需要在应用启动时把内置图标集注册进 offline 集合，只需一次：
+
+```ts
+// main.ts（或你的 kit 接入入口）
+import { presetIconifyIcon } from '@zl-ui-kit/components'
+import { icons } from '@zl-ui-kit/icons'
+
+presetIconifyIcon(icons)
+```
+
+> **漏掉这一步的表现**：`ZlIcon` 只渲染出一个空的 `<div class="zl-icon">`，不报错、不告警，
+> 组件内部（查询条的「查询/重置/展开」按钮、表单 label 后的问号、空态插画等）的图标同样全部空白——
+> 排查时容易误判成图标名写错或样式问题。
+>
+> `@zl-ui-kit/icons` 需要作为**直接依赖**安装（`pnpm add @zl-ui-kit/icons`），不要依赖它被 `components` 间接带进 `node_modules`：
+> 幽灵依赖在提升规则变化或切换包管理器后会直接解析失败。
+
+`presetIconifyIcon(...collections)` 接受多个集合，可叠加自建图标：`presetIconifyIcon(icons, myIcons)`。
 
 > 图标名须真实存在于 `packages/icons/src/icons.json`，否则不显示。可用 `Object.keys(require('@zl-ui-kit/icons').icons).includes('database-color')` 校验。
 
@@ -227,52 +276,69 @@ setTheme('dark')               // 切换主题（light/dark/red-light/red-dark/b
 ## 5. 通用展示组件
 
 ### ZlTitle — 区块标题
+
 ```vue
 <ZlTitle size="medium" text="资源列表" />
 ```
+
 `size`: `small`(12px) / `medium`(14px) / `large`；自带左侧竖条与可选图标（`zl:help-color`）。
 
 ### ZlTag — 标签
+
 ```vue
 <ZlTag type="primary" :closable="true" icon="zl:star-color">标签</ZlTag>
 ```
-| prop | 取值 |
-| --- | --- |
-| `type` | `primary` / `success` / `warning` / `info` / `danger` |
-| `size` | `mini` / `small` / `medium` |
-| `color` | 自定义色（覆盖 type） |
-| `icon` / `iconColor` | 前置图标 |
-| `closable` / `rounded` | 可关闭 / 圆角 |
+
+| prop                   | 取值                                                  |
+| ---------------------- | ----------------------------------------------------- |
+| `type`                 | `primary` / `success` / `warning` / `info` / `danger` |
+| `size`                 | `mini` / `small` / `medium`                           |
+| `color`                | 自定义色（覆盖 type）                                 |
+| `icon` / `iconColor`   | 前置图标                                              |
+| `closable` / `rounded` | 可关闭 / 圆角                                         |
 
 `ZlCornerTag` 为四角定位标签，语义一致、定位展开为显式四类。
 
 ### ZlCopy — 一键复制
+
 ```vue
 <ZlCopy :text="row.id" />
 ```
+
 `text`（或插槽文本）经 `copy()` 写入剪贴板，按钮 `size="small" text`。
 
 ### ZlEmpty — 空状态
+
 ```vue
 <ZlEmpty description="暂无数据" />
-<ZlEmpty :image="customImg" />   <!-- 传入自定义图，缺省为内置轻量 SVG 线稿 -->
+<ZlEmpty :image="customImg" />
+<!-- 传入自定义图，缺省为内置轻量 SVG 线稿 -->
 ```
 
 ### ZlDictTag — 字典标签
+
 经 `useDict(dictKey)` 解析独立字典 store（`useDictStore`，Vue3 状态管理缓存，不依赖全局数据）。**支持三种数据注入方式**（详见第 12.1.3 节与第 6.3 节 ⑤）：
 
 ```vue
 <!-- 1. 组件级直传（最轻量，无需任何全局配置即可翻译） -->
-<ZlDictTag dict-key="resourceType" :value="row.type"
-  :dict="[{ label: '图片', value: '1', icon: 'zl:image' }, { label: '视频', value: '2' }]" />
+<ZlDictTag
+  dict-key="resourceType"
+  :value="row.type"
+  :dict="[
+    { label: '图片', value: '1', icon: 'zl:image' },
+    { label: '视频', value: '2' },
+  ]"
+/>
 
 <!-- 2. 全局/局部数据源（应用入口注册一次，全项目共享） -->
 <ZlDictTag dict-key="resourceType" :value="row.type" />
 <ZlDictTag dict-key="resourceType" :value="row.type" simple />
 ```
+
 详见第 6.3 节 ⑤。
 
 ### 其余
+
 `ZlText`（文本省略）、`ZlAutoTooltip`（超长省略 + tooltip）、`ZlDescription`（描述列表）、`ZlSection`（分区容器）、`ZlCard`（卡片，背景图已改为纯 CSS）、`ZlAvatar`(+Group)、`ZlAppSlogan`（品牌标语，字体走 `--zl-slogan-font-family`）、`ZlIconLabel`/`ZlIconHover`（图标 + 文字组合）。
 
 ---
@@ -286,30 +352,36 @@ setTheme('dark')               // 切换主题（light/dark/red-light/red-dark/b
 来源：`@zl-ui-kit/composables`。`service` 统一签名：`(...args) => Promise<R>`。
 
 #### `useRequest(service, options?, plugins?)` —— 基础形态
+
 ```ts
-const { loading, data, error, status, run, runAsync, refresh, refreshAsync, cancel, mutate } =
-  useRequest(service, { manual: false, defaultParams: [], initialData, onSuccess, onError })
-```
-| 返回/选项 | 说明 |
-| --- | --- |
-| `loading` / `data` / `error` / `status` | 响应式状态（`status`: `''`/`pending`/`finished`/`error`） |
-| `run(...args)` | 同步触发，错误被吞（除非传 `onError`） |
-| `runAsync(...args)` | 返回 Promise，可 await 捕获 |
-| `refresh()` / `refreshAsync()` | 用上次参数重跑 |
-| `cancel()` | 取消进行中请求（结果丢弃） |
-| `mutate(data | prev => R)` | 本地立即改 `data`，不触网 |
-| `options.manual` | `true` 时不自动执行 |
-| `options.defaultParams` / `initialData` | 首参 / 初始占位 |
-| `options.onBefore/onSuccess/onError/onFinally` | 生命周期回调 |
-| `options.loadingDelay` / `refreshDeps` | 延迟 loading / 依赖变更刷新 |
+const { loading, data, error, status, run, runAsync, refresh, refreshAsync, cancel, mutate } = useRequest(
+  service,
+  { manual: false, defaultParams: [], initialData, onSuccess, onError },
+)
+```
+
+| 返回/选项                                      | 说明                                                      |
+| ---------------------------------------------- | --------------------------------------------------------- |
+| `loading` / `data` / `error` / `status`        | 响应式状态（`status`: `''`/`pending`/`finished`/`error`） |
+| `run(...args)`                                 | 同步触发，错误被吞（除非传 `onError`）                    |
+| `runAsync(...args)`                            | 返回 Promise，可 await 捕获                               |
+| `refresh()` / `refreshAsync()`                 | 用上次参数重跑                                            |
+| `cancel()`                                     | 取消进行中请求（结果丢弃）                                |
+| `mutate(data \| prev => R)`                    | 本地立即改 `data`，不触网                                 |
+| `options.manual`                               | `true` 时不自动执行                                       |
+| `options.defaultParams` / `initialData`        | 首参 / 初始占位                                           |
+| `options.onBefore/onSuccess/onError/onFinally` | 生命周期回调                                              |
+| `options.loadingDelay` / `refreshDeps`         | 延迟 loading / 依赖变更刷新                               |
 
 #### `useDataRequest(service, { dataKey = 'data' })` —— 自动解包信封
+
 ```ts
 const { data } = useDataRequest(getChartDataApi, { dataKey: 'data' })
 // data.value === 响应里的 data 字段
 ```
 
 #### `usePaginationRequest(service, { pagination })` —— 分页专用
+
 额外返回 `data`(行数组) / `total` / `current` / `pageSize` / `changeCurrent` / `changePageSize` / `changePagination`，分页键名（`pageNum/pageSize/total/rows`）可配置，与后端契约对齐时通过 `pagination` 选项或 `setGlobalOptions` 调整。
 
 > `ZlSearchTable` / `ZlCardPage` 内部已用 `usePageableRequest`，**直接传 service 即可**，无需在外层再包。
@@ -318,26 +390,27 @@ const { data } = useDataRequest(getChartDataApi, { dataKey: 'data' })
 
 位置 `apps/playground/src/mock/`：
 
-| 文件 | 内容 |
-| --- | --- |
-| `data.ts` | 内存假数据：`genResources(count=137)`、`dicts`(resourceType/resourceStatus/region)、`treeData`、`chartData` |
+| 文件          | 内容                                                                                                                                                                                             |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `data.ts`     | 内存假数据：`genResources(count=137)`、`dicts`(resourceType/resourceStatus/region)、`treeData`、`chartData`                                                                                      |
 | `services.ts` | Promise service（300~600ms 延迟）：`getResourcePage` / `getResourceDetail` / `getTreeData` / `getChartDataApi` / `getDictMap` / `uploadFile` / `submitResourceForm` / `getResourcePageMaybeFail` |
-| `index.ts` | 统一出口 |
-
-| service | 返回结构 | 用途 |
-| --- | --- | --- |
-| `getResourcePage(params)` | `{ rows, total, pageNum, pageSize }` | 分页列表，喂 `ZlSearchTable`/`ZlCardPage`/`usePaginationRequest` |
-| `getResourceDetail(id)` | `ResourceItem` | 详情 |
-| `getTreeData()` | `TreeNode[]` | 组织树 |
-| `getChartDataApi()` | `{ code:200, msg, data }` 信封 | 演示 `useDataRequest` 解包 |
-| `getDictMap()` | `Record<string, DictItem[]>` | 经 `setDictSource()` 注册为全局字典数据源 |
-| `uploadFile(formData)` | `{ url }` | 演示 `ZlUpload` |
-| `submitResourceForm(data)` | `{ code:200, msg, data }` | 表单提交 |
-| `getResourcePageMaybeFail(params)` | `fail:true` 时 reject | 演示错误态 |
+| `index.ts`    | 统一出口                                                                                                                                                                                         |
+
+| service                            | 返回结构                             | 用途                                                             |
+| ---------------------------------- | ------------------------------------ | ---------------------------------------------------------------- |
+| `getResourcePage(params)`          | `{ rows, total, pageNum, pageSize }` | 分页列表，喂 `ZlSearchTable`/`ZlCardPage`/`usePaginationRequest` |
+| `getResourceDetail(id)`            | `ResourceItem`                       | 详情                                                             |
+| `getTreeData()`                    | `TreeNode[]`                         | 组织树                                                           |
+| `getChartDataApi()`                | `{ code:200, msg, data }` 信封       | 演示 `useDataRequest` 解包                                       |
+| `getDictMap()`                     | `Record<string, DictItem[]>`         | 经 `setDictSource()` 注册为全局字典数据源                        |
+| `uploadFile(formData)`             | `{ url }`                            | 演示 `ZlUpload`                                                  |
+| `submitResourceForm(data)`         | `{ code:200, msg, data }`            | 表单提交                                                         |
+| `getResourcePageMaybeFail(params)` | `fail:true` 时 reject                | 演示错误态                                                       |
 
 ### 6.3 组件对接实战（对应 `/use-request` 页面）
 
 #### ① `ZlSearchTable` —— 直接传 service
+
 ```vue
 <ZlSearchTable
   :request="getResourcePage"
@@ -347,9 +420,11 @@ const { data } = useDataRequest(getChartDataApi, { dataKey: 'data' })
   height="380"
 />
 ```
+
 内部用 `usePageableRequest` 驱动分页与查询；`columns` 为 `TableColumn[]`，`queryItems` 为 `SearchItem[]`。
 
 #### ② `ZlCardPage` —— 直接传 service
+
 ```vue
 <ZlCardPage :request="getResourcePage" card-min-width="200px">
   <template #default="{ data }">
@@ -357,30 +432,42 @@ const { data } = useDataRequest(getChartDataApi, { dataKey: 'data' })
   </template>
 </ZlCardPage>
 ```
+
 内部组合 `usePageableRequest + ZlSearch + ZlPagination + ZlEmpty`。
 
 #### ③ `ZlTable` + `ZlPagination` —— 自行 `usePaginationRequest`
+
 ```ts
 const req = usePaginationRequest(getResourcePage, { manual: true })
 onMounted(() => req.run({ pageNum: 1, pageSize: 8 }))
 ```
+
 ```vue
 <ZlTable :columns="columns" :data="req.data" :loading="req.loading" height="320" />
 <ZlPagination
-  :total="req.total" :page-num="req.current" :page-size="req.pageSize"
+  :total="req.total"
+  :page-num="req.current"
+  :page-size="req.pageSize"
   @change="({ pageNum, pageSize }) => req.changePagination(pageNum, pageSize)"
 />
 ```
 
 #### ④ `ZlSearch` 触发 `run(params)`
+
 ```ts
 const req = usePaginationRequest(getResourcePage, { manual: true })
-function onSearch(params) { req.run({ pageNum: 1, pageSize: 6, ...params }) }
+function onSearch(params) {
+  req.run({ pageNum: 1, pageSize: 6, ...params })
+}
 ```
+
 ```vue
 <ZlSearch :items="queryItems" @search="onSearch" />
 ```
-`ZlSearch` 自带 `overflowCount`（默认 4，折叠溢出项），`@search` 回传查询参数对象。
+
+`ZlSearch` 按容器宽度自适应排列（每项最小 240px，列数随宽度变化）。**一行放不下的项会自动隐藏**，
+此时「查询」左侧出现展开按钮（筛选图标）：点击在查询条上层展开全量表单，再点即收起。
+是否溢出由实测宽度算出（不是按项数猜），窗口拉宽后按钮会自动消失。`@search` 回传查询参数对象。
 
 #### ⑤ `ZlDictTag` —— 注入字典后由 `useDict` 解析
 
@@ -391,8 +478,14 @@ function onSearch(params) { req.run({ pageNum: 1, pageSize: 6, ...params }) }
 **A. 组件级直传（最轻量，推荐一次性/局部使用）**
 
 ```vue
-<ZlDictTag dict-key="resourceType" :value="row.type"
-  :dict="[{ label: '图片', value: '1', icon: 'zl:image' }, { label: '视频', value: '2' }]" />
+<ZlDictTag
+  dict-key="resourceType"
+  :value="row.type"
+  :dict="[
+    { label: '图片', value: '1', icon: 'zl:image' },
+    { label: '视频', value: '2' },
+  ]"
+/>
 ```
 
 **B. 全局注册数据源（应用入口注册一次，全项目共享，适配不同项目）**
@@ -400,10 +493,14 @@ function onSearch(params) { req.run({ pageNum: 1, pageSize: 6, ...params }) }
 ```ts
 import { setDictSource } from '@zl-ui-kit/composables'
 // 静态字典表
-setDictSource({ resourceType: [{ label: '图片', value: '1' }], resourceStatus: [{ label: '正常', value: '1' }] })
+setDictSource({
+  resourceType: [{ label: '图片', value: '1' }],
+  resourceStatus: [{ label: '正常', value: '1' }],
+})
 // 或按需异步加载（推荐对接各自项目后端）
 setDictSource(async (key) => await api.getDictOptions(key))
 ```
+
 之后任意 `<ZlDictTag dict-key="resourceType" :value="row.type" />` 自动翻译，无需逐个传 `dict`。
 
 **C. 局部注入（为某棵组件子树单独指定数据源，覆盖全局）**
@@ -418,26 +515,33 @@ useDictProvider({ source: { resourceType: [...] } })
 <ZlDictTag dict-key="resourceType" :value="row.type" />
 <ZlDictTag dict-key="resourceType" :value="row.type" simple />
 ```
+
 > **注意**：`ZlTable` 列上的 `dictKey` 仅作 schema 字段透传，**不会**自动渲染字典标签，需用列插槽自行渲染 `ZlDictTag`（如 demo 中 `#type`/`#status`/`#region` 插槽）。
 
 #### ⑥ `ZlUpload` —— 传上传 service
+
 ```vue
 <ZlUpload v-model="uploadModel" :request="uploadFile" accept=".png,.jpg,.pdf" :max-size="5" :limit="3" />
 ```
+
 `request` 接收 `FormData` 返回 `{ url }`；`maxSize` 单位 MB。
 
 #### ⑦ `ZlTree` —— `useRequest` 绑定 `data`
+
 ```ts
 const treeReq = useRequest(getTreeData)
 // 必须提取为顶层 ref，否则模板中取到的是 Ref 对象本身（见 6.2 注意事项）
 const { data: treeData, loading: treeLoading } = treeReq
 ```
+
 ```vue
 <ZlTree v-if="!treeLoading" :data="treeData" :props="{ label: 'title', children: 'children' }" />
 ```
 
 #### ⑧ `ZlChart` —— `useDataRequest` 解包后构建 option
+
 `ZlChart` 显式 prop 为 `series`，其余配置（title/xAxis/yAxis/tooltip/grid）经 attrs 透传，故用 `v-bind` 传完整 echarts option：
+
 ```ts
 const chartReq = useDataRequest(getChartDataApi, { dataKey: 'data' })
 const chartOption = computed(() => {
@@ -451,18 +555,20 @@ const chartOption = computed(() => {
   }
 })
 ```
+
 ```vue
 <ZlChart v-bind="chartOption" />
 ```
 
-| Prop | 类型 | 说明 |
-| --- | --- | --- |
-| `series` | `object \| object[]` | 系列（单个或数组）；其余 option 字段经 attrs 透传 |
-| `theme` | `string` | 主题名，initialize 时指定。需先注册，如 `import 'echarts/theme/v5'` 后传 `theme="v5"`；echarts 6 想保留 v5 观感时用 |
+| Prop     | 类型                 | 说明                                                                                                                |
+| -------- | -------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `series` | `object \| object[]` | 系列（单个或数组）；其余 option 字段经 attrs 透传                                                                   |
+| `theme`  | `string`             | 主题名，initialize 时指定。需先注册，如 `import 'echarts/theme/v5'` 后传 `theme="v5"`；echarts 6 想保留 v5 观感时用 |
 
 > 暴露方法：`clear()`（模板 ref 调用）。尺寸自适应由 `useResizeObserver` 负责，容器需有明确高度。
 
 #### ⑨ `useRequest` 生命周期面板
+
 ```ts
 const req = useRequest(getResourcePageMaybeFail, { defaultParams: [{ pageNum: 1, pageSize: 5 }] })
 req.refresh()                                   // 重跑
@@ -480,18 +586,23 @@ req.cancel()                                    // 取消进行中请求
    // ❌ 错误：模板里取到的是 Ref 对象
    const req = useRequest(getList)
    ```
+
    ```vue
    <Table v-if="!req.loading" :data="req.data" />
    ```
+
    ```ts
    // ✅ 正确：提取为顶层 ref，模板中自动解包
    const req = useRequest(getList)
    const { data: listData, loading: listLoading } = req
    ```
+
    ```vue
    <Table v-if="!listLoading" :data="listData" />
    ```
+
    方法调用不受影响（事件处理器中可直接写 `req.refresh()`，无需解包）。
+
 3. **`ZlChart` 传参**：用 `series` prop + 其余 attrs 透传（推荐 `v-bind` 传整个 option），勿只传 `:option`。
 4. **图标名必须存在**：字典/组件 `icon` 用的名字须在 `icons.json` 真实存在。
 5. **分页键名对齐**：后端用 `current/pageSize/list` 而非 `pageNum/pageSize/rows` 时，用 `pagination` 选项或 `setGlobalOptions` 覆盖。
@@ -501,6 +612,7 @@ req.cancel()                                    // 取消进行中请求
 ## 7. 表单与交互组件
 
 ### ZlForm —— schema 驱动
+
 ```ts
 const items: FormItem[] = [
   { model: 'name', label: '名称', component: 'el-input', props: { placeholder: '请输入' }, rules: [{ required: true }] },
@@ -508,23 +620,41 @@ const items: FormItem[] = [
   { model: 'enable', label: '启用', component: 'ZlSwitch' },
 ]
 ```
+
 ```vue
 <ZlForm :model="form" :items="items" label-width="auto" />
 ```
+
 `FormItem` 关键字段：`model`(必填) / `label` / `component`(组件名或组件) / `props`(自动包装 `update:modelValue` 回写) / `slots` / `rules` / `defaultValue` / `visible`(布尔或函数) / `tooltip`(label 后帮助图标 + tooltip)。
 
 ### ZlSearch —— 查询条
+
 见 6.3 ④。`items: SearchItem[]`，`SearchItem` 继承 `FormItem` 并扩展 `toLabel`(值→条件标签) 与 `toParams`(值→查询参数合并)。
 
+**自适应溢出**（`useSearchFormOverflow`，移植自源组件逻辑，非按项数猜）：
+
+- 布局 `auto-fill` 网格，单列 `minmax(min(240px, 100%), 1fr)`，列数随容器宽度变化；
+- 按实测宽度算出**一行能放几列**，记下最后可见项下标 `lastVisibleIndex`；超出的项打上
+  `zl-search-form-item-hide`（`position: absolute` + `visibility: hidden`，不占位但**仍在表单里**，
+  校验与取值不受影响），所以查询条永远只有一行高；
+- `ResizeObserver` 监听宽度变化重算，拉宽窗口后展开按钮会自己消失；查询项增删/显隐后也会重测。
+
+**展开 / 收起**：`lastVisibleIndex !== null` 时在「查询」左侧出现筛选图标按钮，点击在查询条**上层**
+展开全量表单浮层（`position: absolute` + 上滑 `--28px` 淡入，不改变页面高度），再点收起；查询/重置后自动收起。
+`showLabels` 不显式传时，仅在发生溢出时展示「筛选条件」标签行。
+
 ### ZlDrawer / ZlPopconfirm / ZlSwitch
+
 - `ZlDrawer`：自绘 footer（okLoading/hideCancel/readonly 语义保持），`loading`→`v-loading`。
 - `ZlPopconfirm`：基于 `el-popover` 自绘面板，保留 title/content 双插槽与确认/取消事件。
 - `ZlSwitch`：`active-value`/`inactive-value` 包装，文本在侧（`checked-text`）。
 
 ### ZlAction / ZlActionList —— 操作列与操作列表
+
 基于 `ActionItem`（label/icon/onClick/disabled/divider 等），`ZlTable` 列 `actions` 即渲染 `ZlActionList`。
 
 ### ZlRadioTag / ZlCheckboxTag / ZlCheckAll / ZlSorter / ZlAddSub / ZlLayoutSwitch
+
 - `ZlRadioTag`/`ZlCheckboxTag`：隐藏原生 input，标签本体即 `ZlTag`，checked 由 model 推导；`ZlCheckboxTag` 支持 exclusive。
 - `ZlCheckAll`：全选态 computed 推导。
 - `ZlSorter`/`ZlSorterList`：排序控件。
@@ -532,6 +662,7 @@ const items: FormItem[] = [
 - `ZlLayoutSwitch`：布局形态切换（el-radio-button + `zl:` 图标）。
 
 ### ZlTabs / ZlDynamicComponent / ZlGrid
+
 - `ZlTabs`：`el-tabs` 封装，schema `{ key, title, lazy }`，extra 经外层绝对定位承载。
 - `ZlDynamicComponent`：schema→VNode 渲染引擎，默认 `el-input`。
 - `ZlGrid`(+`ZlGridItem`)：自绘栅格，label 自适应/跨列/省略提示/字典。
@@ -541,13 +672,16 @@ const items: FormItem[] = [
 ## 8. 布局与权限
 
 ### ZlAppLayout / ZlAppMenu
+
 - `ZlAppLayout`：horizontal/vertical 双形态布局骨架，折叠按钮 `el-button circle`。
 - `ZlAppMenu`(+Item)：`el-menu` 重写（index=menu.name），主题经 `--zl-menu-*` CSS 变量对接 `--el-menu-*`。
 
 ### ZlPermission
+
 配合 `usePermissionProvider` 提供权限上下文，`usePermission` 校验；样例见 `/general`。
 
 ### ZlHorizontalTable
+
 `el-row`/`el-col`（24 栅格）实现的横向描述表。
 
 ---
@@ -595,9 +729,7 @@ setupMonacoEnvironment((_, label) => {
 **让编辑器不进首屏**（体积 3MB+，务必异步）：
 
 ```ts
-const ZlEditor = defineAsyncComponent(() =>
-  import('@zl-ui-kit/components/editor').then(m => m.ZlEditor),
-)
+const ZlEditor = defineAsyncComponent(() => import('@zl-ui-kit/components/editor').then((m) => m.ZlEditor))
 ```
 
 路由级拆分（`() => import('./EditorPage.vue')`）效果相同 —— 只要 `@zl-ui-kit/components/editor`
@@ -616,6 +748,7 @@ const ZlEditor = defineAsyncComponent(() =>
 > 主题负责「视觉」的定义与覆盖；**「文案」的同等人格能力见第 13 章**（`createZlI18n`，与 `defineTheme` 对称）。
 
 ### L1 变量直覆（小幅微调）
+
 ```css
 body {
   --zl-primary-6: #3056d3;
@@ -625,23 +758,36 @@ body {
 ```
 
 ### L2 运行时定义主题（换肤/多租户推荐）
+
 ```ts
 import { defineTheme, setTheme, enableThemePersistence, useTheme } from '@zl-ui-kit/theme'
-defineTheme({ name: 'brand-purple', base: 'light', colors: { primary: '#722ED1', danger: '#f53f3f' }, apply: true })
+defineTheme({
+  name: 'brand-purple',
+  base: 'light',
+  colors: { primary: '#722ED1', danger: '#f53f3f' },
+  apply: true,
+})
 setTheme('brand-purple')
-enableThemePersistence()           // 可选：localStorage 记住选择（key: zl-theme）
-const { theme, themes, setTheme } = useTheme()   // 组件内响应式
+enableThemePersistence() // 可选：localStorage 记住选择（key: zl-theme）
+const { theme, themes, setTheme } = useTheme() // 组件内响应式
 ```
+
 自定义主题与内置主题变量完全同构，色阶派生算法与 EP theme-chalk 对齐，支持任意数量并存切换；`tokens` 参数可覆盖任意底层 token 深度定制。
 
 ### L3 构建时生成主题（深度定制，规划中）
+
 需求 §12-Q14：将提供 CLI 产出与内置同构的完整 CSS，当前可先用 L2 `tokens` 覆盖近似。
 
 ### SCSS 工具（编译期定制）
+
 ```scss
 @use '@zl-ui-kit/theme/scss/colors.scss' as *;
-.my-card { @include colorGradient(primary, to right); color: var(--zl-primary-6); }
+.my-card {
+  @include colorGradient(primary, to right);
+  color: var(--zl-primary-6);
+}
 ```
+
 - `scss/colors.scss`：`colorForEach` / `colorGradient`
 - `scss/map.scss`：`mapGet`
 - `scss/theme.scss`：`theme()` mixin（为每套主题生成选择器块）
@@ -651,13 +797,14 @@ const { theme, themes, setTheme } = useTheme()   // 组件内响应式
 ## 11. 调试与常见问题
 
 ### 各包常用命令
-| 包 | 生成 | 构建 | 单测 |
-| --- | --- | --- | --- |
-| @zl-ui-kit/icons | `pnpm --filter @zl-ui-kit/icons gen`（svg → icons.json，prefix `zl`） | 同 gen | — |
-| @zl-ui-kit/theme | `pnpm --filter @zl-ui-kit/theme gen`（_json → generated/） | `build`(gen + tsup) | — |
-| @zl-ui-kit/utils | — | `build`(tsup) | `test:unit`(vitest) |
-| @zl-ui-kit/composables | — | `build`(tsup) | — |
-| @zl-ui-kit/components | — | `build`(vite lib + dts + 样式注入) | — |
+
+| 包                     | 生成                                                                  | 构建                               | 单测                |
+| ---------------------- | --------------------------------------------------------------------- | ---------------------------------- | ------------------- |
+| @zl-ui-kit/icons       | `pnpm --filter @zl-ui-kit/icons gen`（svg → icons.json，prefix `zl`） | 同 gen                             | —                   |
+| @zl-ui-kit/theme       | `pnpm --filter @zl-ui-kit/theme gen`（_json → generated/）            | `build`(gen + tsup)                | —                   |
+| @zl-ui-kit/utils       | —                                                                     | `build`(tsup)                      | `test:unit`(vitest) |
+| @zl-ui-kit/composables | —                                                                     | `build`(tsup)                      | —                   |
+| @zl-ui-kit/components  | —                                                                     | `build`(vite lib + dts + 样式注入) | —                   |
 
 ### 文档维护位置
 
@@ -669,6 +816,7 @@ const { theme, themes, setTheme } = useTheme()   // 组件内响应式
 - 其余四包 README 只保留本包速查，并在顶部指向本页。
 
 ### 常见问题
+
 - **改了 theme 的 `_json/*.json` 不生效**：先 `pnpm --filter @zl-ui-kit/theme gen`（生成 `src/generated/`），再刷新 playground。
 - **新增 svg 图标**：放入 `packages/icons/src/svg/`，执行 icons 的 `gen` 后重启 playground。
 - **`@zl-ui-kit/theme/scss/*.scss` 找不到**：确认已执行 theme `gen`（`generated/_constants.scss` 是其依赖）。
@@ -707,7 +855,9 @@ setGlobalOptions({ pagination: { currentKey: 'current', totalKey: 'totalCount',
 
 // 自定义插件示例
 const logPlugin = defineUseRequestPlugin((inst) => ({
-  onSuccess(data) { console.log('[req]', inst.params.value, data) },
+  onSuccess(data) {
+    console.log('[req]', inst.params.value, data)
+  },
 }))
 const { data } = useRequest(getList, {}, [logPlugin])
 ```
@@ -718,6 +868,7 @@ const { data } = useRequest(getList, {}, [logPlugin])
 import { useGlobalData } from '@zl-ui-kit/composables'
 const g = useGlobalData()
 ```
+
 响应式字段（均为 `WritableComputedRef`）：`locale` / `theme` / `token` / `isI18nKeyVisible` / `roles` / `permissions` / `user` / `localeMessages` / `elLocaleMessages` / `config`。（注：字典数据已独立为 `useDictStore`，不挂在全局数据上。）
 
 方法：`getConfig(key, default?)` / `isConfig(key, compareValue='true')` / `setAndWaitUntil({ set?, until? })`（设置并等待条件成立）/ `resetUser()`。
@@ -726,12 +877,12 @@ const g = useGlobalData()
 ```ts
 // 应用入口：初始化登录态与业务配置
 const g = useGlobalData()
-g.token.value = loginToken                                  // 持久化到 $zl_token
-g.config.value = { 'zl.service.type': 'platform' }           // useServiceType 读取它
+g.token.value = loginToken // 持久化到 $zl_token
+g.config.value = { 'zl.service.type': 'platform' } // useServiceType 读取它
 g.user.value = { name: '张三' }
 
-g.locale.value = 'en'                                       // 切换语言，useLocale / ZlI18nProvider 跟随
-g.resetUser()                                               // 登出：清 user / roles / permissions / token
+g.locale.value = 'en' // 切换语言，useLocale / ZlI18nProvider 跟随
+g.resetUser() // 登出：清 user / roles / permissions / token
 ```
 
 > 本 hook 只依赖 `localStorage`，**不依赖任何微前端框架**。它替代了 `0.4.x` 及更早版本的
@@ -756,11 +907,18 @@ g.resetUser()                                               // 登出：清 user
 const { Message, Modal, Notification } = useGlobalMessage()
 Message.success('保存成功')
 // Modal 在 ElMessageBox 基础上扩展了 confirmPromise
-const r = await Modal.confirmPromise({ title: '删除', message: '确认删除？' },
-  async (ctx) => { await doDelete() },                 // onOk
-  async (ctx) => { /* onCancel */ })
+const r = await Modal.confirmPromise(
+  { title: '删除', message: '确认删除？' },
+  async (ctx) => {
+    await doDelete()
+  }, // onOk
+  async (ctx) => {
+    /* onCancel */
+  },
+)
 // r: 'Ok' | 'Cancel' | false（onOk 抛错且 throwOnOk=false 时）
 ```
+
 `throwOnOk` / `throwOnCancel` 控制错误是否向上抛出（默认吞错 resolve(false) / resolve('Cancel')）。
 
 #### 12.1.5 其它 Hooks
@@ -776,7 +934,7 @@ const r = await Modal.confirmPromise({ title: '删除', message: '确认删除
 
 ```ts
 import { createRequest, deepCopy, formatFilesize /* … */ } from '@zl-ui-kit/utils'
-import request from '@zl-ui-kit/utils'          // 默认导出一个开箱即用的 createRequest 实例
+import request from '@zl-ui-kit/utils' // 默认导出一个开箱即用的 createRequest 实例
 ```
 
 #### 12.2.1 网络请求封装 `createRequest`
@@ -795,30 +953,34 @@ api.get('/resources', { params: { pageNum: 1, pageSize: 10 } })
 
 #### 12.2.2 数组 / 对象 / 类型判断
 
-| 函数 | 说明 |
-| --- | --- |
-| `convertArrayToTree(list, { id='id', pid='pid', children='children' })` | 扁平数组转树（基于 id/pid，支持乱序输入） |
-| `ensureArray(val)` | 非数组值包装为单元素数组 |
-| `deepCopy(obj)` / `shallowCopy(obj)` | 深拷贝 / 浅拷贝（内部用 `hasOwn`） |
-| `hasOwn(obj, key)` | `Object.prototype.hasOwnProperty` 封装 |
-| `isObject` / `isPlainObject` / `isArray` / `isFunction` / `isPromise` / `isBoolean` / `isNumber` / `isDefined` | 类型判断（TS 类型守卫） |
+| 函数                                                                                                           | 说明                                      |
+| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| `convertArrayToTree(list, { id='id', pid='pid', children='children' })`                                        | 扁平数组转树（基于 id/pid，支持乱序输入） |
+| `ensureArray(val)`                                                                                             | 非数组值包装为单元素数组                  |
+| `deepCopy(obj)` / `shallowCopy(obj)`                                                                           | 深拷贝 / 浅拷贝（内部用 `hasOwn`）        |
+| `hasOwn(obj, key)`                                                                                             | `Object.prototype.hasOwnProperty` 封装    |
+| `isObject` / `isPlainObject` / `isArray` / `isFunction` / `isPromise` / `isBoolean` / `isNumber` / `isDefined` | 类型判断（TS 类型守卫）                   |
 
 #### 12.2.3 函数 / 加密 / DOM / 文件 / 杂项
 
 **函数**
+
 - `debounce(fn, delay = 300)`：防抖。
 - `traverseTree(tree, cb, { children = 'children' })`：深度遍历树结构数组。
 - `withResolvers<T>()`：`Promise.withResolvers` 兼容实现，返回 `{ resolve, reject, promise }`。
 
 **加密**（CryptoJS AES-CBC-PKCS7）
+
 - `aesEncrypt(plain, aesKey = DEFAULT_AES_KEY, aesIvKey = DEFAULT_AES_IV_KEY)` / `aesDecrypt(cipher, ...)`
 - 默认密钥常量：`DEFAULT_AES_KEY` / `DEFAULT_AES_IV_KEY`、`DATABASE_AES_KEY` / `DATABASE_AES_IV_KEY`（均可自行传入覆盖）。
 
 **DOM**
+
 - `getRelativeRect(target, relative)` → `{ top, bottom, left, right, width, height }`：元素相对参照元素的矩形。
 - `getStyle(el, prop)`：读取样式（含计算样式回退；`float` → `cssFloat`）。
 
 **文件**
+
 - `fileSave`（re-export `file-saver` 的 `saveAs`）。
 - `joinFilePrefix(path, prefix = '/_file')`：拼接文件服务前缀路径。
 - `downloadFileByUrl(url, prefix?)`：创建临时 `<a>` 触发浏览器下载。
@@ -826,6 +988,7 @@ api.get('/resources', { params: { pageNum: 1, pageSize: 10 } })
 - `formatFilesize(size, { precision = 2, units })`：文件大小格式化（B/KB/MB/GB）。
 
 **杂项**
+
 - `generateUUID()`：UUID v4。
 - `getRandomInt(min, max)`：`[min, max]` 区间随机整数。
 - `paginate(data, pageSize, pageNum)` → `{ rows, pageNum, total }`：内存数组静态分页。
@@ -840,11 +1003,11 @@ api.get('/resources', { params: { pageNum: 1, pageSize: 10 } })
 
 ### 13.1 三层结构
 
-| 层 | 来源 | 负责 |
-| --- | --- | --- |
-| 业务文案多语言 | 宿主经 `createZlI18n`（或底层 `useLocale`）安装的 vue-i18n 实例 | `t('zl.xxx')` 解析内置包 + 覆盖包 |
-| Element Plus 内置组件本地化 | `ZlI18nProvider` → `<el-config-provider>` | 绑定 `elLocaleMessages` 到 EP |
-| 调试开关 | `isI18nKeyVisible` | 开启后所有 `t()` 直接显示 key，便于排查漏翻 |
+| 层                          | 来源                                                            | 负责                                        |
+| --------------------------- | --------------------------------------------------------------- | ------------------------------------------- |
+| 业务文案多语言              | 宿主经 `createZlI18n`（或底层 `useLocale`）安装的 vue-i18n 实例 | `t('zl.xxx')` 解析内置包 + 覆盖包           |
+| Element Plus 内置组件本地化 | `ZlI18nProvider` → `<el-config-provider>`                       | 绑定 `elLocaleMessages` 到 EP               |
+| 调试开关                    | `isI18nKeyVisible`                                              | 开启后所有 `t()` 直接显示 key，便于排查漏翻 |
 
 > ⚠️ **关键：仅 `useLocale` 不够。** `elLocaleMessages` 由 `useLocale` 的 `loader` 写入全局数据，但必须由 `ZlI18nProvider` 经 `<el-config-provider>` 真正挂载到 Element Plus，否则分页器等内置组件不会翻译。
 
@@ -865,9 +1028,9 @@ locale.value = 'zh'
 const { i18n } = createZlI18n({
   // 只覆盖想改的 key；未写的走组件库内置默认包
   messages: {
-    zh: { 'zl.login.username': '账号' },              // 覆盖已有语言
+    zh: { 'zl.login.username': '账号' }, // 覆盖已有语言
     en: { 'zl.empty.noData': 'Nothing here yet' },
-    ja: { 'zl.empty.noData': 'データがありません' },  // 新增语言
+    ja: { 'zl.empty.noData': 'データがありません' }, // 新增语言
   },
   // Element Plus 语言包（随 locale 自动切换，由 <ZlI18nProvider> 挂载）
   elLocales: { zh: zhCn, en },
@@ -923,14 +1086,14 @@ const text = t('zl.empty.noData', '暂无相关数据')
 
 主题让消费者「定义并覆盖视觉」，国际化让消费者「定义并覆盖文案」——二者地位对等：
 
-| 能力 | 主题（`@zl-ui-kit/theme`） | 国际化（`@zl-ui-kit/components` + `@zl-ui-kit/composables`） |
-| --- | --- | --- |
-| 内置默认 | 5 套主题（light / dark / red-light / red-dark / blue） | `zlMessages`（zh / zh-cn / en） |
-| 运行时定义 | `defineTheme({ name, base, colors, tokens })` | `createZlI18n({ messages })` 覆盖 / 新增语言 |
-| 引用 / 切换 | `setTheme('dark')` / `useTheme()` | `locale.value = 'en'` / `useLocale()` 返回的 `locale` |
-| 持久化 | `enableThemePersistence()` | `useGlobalData().locale` 经 `$zl_locale` 持久化 |
-| 细粒度覆盖 | CSS 变量 L1 覆写（`--zl-primary-6`） | `mergeMessages` / 直接覆盖单个 key |
-| 挂载点 | `body[data-theme]` | `<ZlI18nProvider>`（EP locale）+ `app.use(i18n)`（业务文案） |
+| 能力        | 主题（`@zl-ui-kit/theme`）                             | 国际化（`@zl-ui-kit/components` + `@zl-ui-kit/composables`） |
+| ----------- | ------------------------------------------------------ | ------------------------------------------------------------ |
+| 内置默认    | 5 套主题（light / dark / red-light / red-dark / blue） | `zlMessages`（zh / zh-cn / en）                              |
+| 运行时定义  | `defineTheme({ name, base, colors, tokens })`          | `createZlI18n({ messages })` 覆盖 / 新增语言                 |
+| 引用 / 切换 | `setTheme('dark')` / `useTheme()`                      | `locale.value = 'en'` / `useLocale()` 返回的 `locale`        |
+| 持久化      | `enableThemePersistence()`                             | `useGlobalData().locale` 经 `$zl_locale` 持久化              |
+| 细粒度覆盖  | CSS 变量 L1 覆写（`--zl-primary-6`）                   | `mergeMessages` / 直接覆盖单个 key                           |
+| 挂载点      | `body[data-theme]`                                     | `<ZlI18nProvider>`（EP locale）+ `app.use(i18n)`（业务文案） |
 
 **三种覆盖方式（按力度递增）**
 
@@ -951,23 +1114,2743 @@ const { i18n } = useLocale({ messages })
 
 **内置可覆盖 key 一览**（`zl.<组件>.<语义>`）
 
-| 组件 | key | 默认（zh） |
-| --- | --- | --- |
-| ZlEmpty | `zl.empty.noData` | 暂无相关数据 |
-| ZlDrawer | `zl.drawer.cancel` / `confirm` / `close` | 取消 / 确定 / 关闭 |
-| ZlPopconfirm | `zl.popconfirm.confirm` / `cancel` | 确定 / 取消 |
-| ZlLayoutSwitch | `zl.layoutSwitch.grid` / `table` | 网格 / 表格 |
-| ZlUpload | `zl.upload.accept` / `limit` / `maxSize` / `nameSpace` | 仅支持{accept}格式的文件 / 最多可上传{limit}个 / 大小不超过{maxSize}MB / 文件名中不得包含空格 |
-| ZlSearch | `zl.search.search` / `filterConditions` / `all` | 查询 / 筛选条件 / 全部 |
-| ZlLogin | `zl.login.username` / `password` / `usernamePlaceholder` / `passwordPlaceholder` / `slideRequired` / `slideText` / `slideSuccess` / `submit` / `welcome` | 用户名 / 密码 / 请输入用户名 / 请输入密码 / 请将滑块移至右侧 / 请滑动到右侧 / 验证通过 / 登 录 / 欢迎登录 |
-| ZlFilePreview | `zl.filePreview.typeError` / `fetchError` | 获取文件类型失败 / 文件获取失败 |
-| ZlAction | `zl.action.more` | 更多 |
-| ZlCheckAll | `zl.checkAll.selectAll` | 全选 |
-| ZlCopy | `zl.copy.copy` / `success` / `failed` | 复制 / 复制成功 / 复制失败 |
-| ZlDescription | `zl.description.empty` | 暂无 |
-| ZlGrid | `zl.grid.empty` | 暂无 |
-| ZlSqlEditor | `zl.sqlEditor.invalid` | 请检查SQL语法 |
+| 组件           | key                                                                                                                                                      | 默认（zh）                                                                                                |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| ZlEmpty        | `zl.empty.noData`                                                                                                                                        | 暂无相关数据                                                                                              |
+| ZlDrawer       | `zl.drawer.cancel` / `confirm` / `close`                                                                                                                 | 取消 / 确定 / 关闭                                                                                        |
+| ZlPopconfirm   | `zl.popconfirm.confirm` / `cancel`                                                                                                                       | 确定 / 取消                                                                                               |
+| ZlLayoutSwitch | `zl.layoutSwitch.grid` / `table`                                                                                                                         | 网格 / 表格                                                                                               |
+| ZlUpload       | `zl.upload.accept` / `limit` / `maxSize` / `nameSpace`                                                                                                   | 仅支持{accept}格式的文件 / 最多可上传{limit}个 / 大小不超过{maxSize}MB / 文件名中不得包含空格             |
+| ZlSearch       | `zl.search.search` / `filterConditions` / `all`                                                                                                          | 查询 / 筛选条件 / 全部                                                                                    |
+| ZlLogin        | `zl.login.username` / `password` / `usernamePlaceholder` / `passwordPlaceholder` / `slideRequired` / `slideText` / `slideSuccess` / `submit` / `welcome` | 用户名 / 密码 / 请输入用户名 / 请输入密码 / 请将滑块移至右侧 / 请滑动到右侧 / 验证通过 / 登 录 / 欢迎登录 |
+| ZlFilePreview  | `zl.filePreview.typeError` / `fetchError`                                                                                                                | 获取文件类型失败 / 文件获取失败                                                                           |
+| ZlAction       | `zl.action.more`                                                                                                                                         | 更多                                                                                                      |
+| ZlCheckAll     | `zl.checkAll.selectAll`                                                                                                                                  | 全选                                                                                                      |
+| ZlCopy         | `zl.copy.copy` / `success` / `failed`                                                                                                                    | 复制 / 复制成功 / 复制失败                                                                                |
+| ZlDescription  | `zl.description.empty`                                                                                                                                   | 暂无                                                                                                      |
+| ZlGrid         | `zl.grid.empty`                                                                                                                                          | 暂无                                                                                                      |
+| ZlSqlEditor    | `zl.sqlEditor.invalid`                                                                                                                                   | 请检查SQL语法                                                                                             |
 
 > **props 优先于 i18n**：组件显式传入的 props（如 `ZlPopconfirm` 的 `confirmButtonText`、`ZlDescription`/`ZlGrid` 的 `emptyText`）优先；i18n 只决定「未传时的默认文案」。新增文案请同步补 `packages/components/src/locales/{zh-cn,en}.ts`。
 
 > **当前未接入 i18n 的中文**：仅剩开发态告警（`ZlDynamicComponent` 的 `console.warn`、`ZlPermission` 的 `throw new Error('权限格式错误')`、`ZlEditor` 的 worker 未配置提示）——这些不面向终端用户，保持中文以便排查。
+
+---
+
+<!-- API:START -->
+
+## 14. 组件 API 参考（自动生成）
+
+> 本章由 `pnpm docs:api`（`scripts/gen-component-api.mjs`）从各组件源码**静态提取**后自动写入，**请勿手改**——会被下次生成覆盖。要补充 prop 说明，请给源码里的 prop 加 `/** ... */` 注释。
+>
+> 提取口径：`defineProps`（含 `withDefaults` 默认值、`defineComponent({ props })` 选项式）/ `defineEmits` / `<slot>` / `defineExpose`。类型列显示的是源码里的 TS 类型表达式，可直接当入参类型用。
+>
+> 代码块取自 `apps/playground/src/pages/gallery-demos.ts` 的逐组件最小示例（同一份代码在冒烟测试里真实渲染），因此不会出现过期写法；改示例后重跑即同步。
+>
+> **每个 prop / 每个插槽都有示例**：`props` 表的「示例」列是该属性的**可直接粘贴写法**（`v-model` 用简写，布尔值按默认值给反例，字面量联合取首个取值，数组 / 对象 / 函数给空字面量占位）；`插槽` 表的「示例」列是对应的 `<template #name>` 片段。想直接改原始代码，用上面的「用法示例 / 插槽用法」块。
+>
+> 同一次生成还会写出 `apps/playground/src/data/component-api.json`，playground 的 **UI 组件使用手册**（`/#/manual`）页直接渲染它 —— 可检索、可复制 `import`，内容与本章一致。
+
+### 组件索引
+
+| 组件                 | 入口                | props | 事件 | 插槽 | 暴露 |
+| -------------------- | ------------------- | ----- | ---- | ---- | ---- |
+| `ZlAction`           | 主入口              | 0     | 0    | 0    | 0    |
+| `ZlActionList`       | 主入口              | 6     | 1    | 1    | 0    |
+| `ZlAddSub`           | 主入口              | 2     | 1    | 1    | 0    |
+| `ZlAppLayout`        | 主入口              | 1     | 0    | 1    | 0    |
+| `ZlAppMenu`          | 主入口              | 3     | 1    | 0    | 0    |
+| `ZlAppSlogan`        | 主入口              | 3     | 0    | 0    | 0    |
+| `ZlAutoTooltip`      | 主入口              | 0     | 0    | 1    | 0    |
+| `ZlAvatar`           | 主入口              | 3     | 0    | 0    | 0    |
+| `ZlAvatarGroup`      | 主入口              | 3     | 0    | 0    | 0    |
+| `ZlCard`             | 主入口              | 1     | 0    | 8    | 0    |
+| `ZlCardPage`         | 主入口              | 6     | 1    | 3    | 3    |
+| `ZlCheckAll`         | 主入口              | 2     | 1    | 0    | 0    |
+| `ZlCheckboxTag`      | 主入口              | 7     | 1    | 1    | 0    |
+| `ZlCopy`             | 主入口              | 2     | 0    | 2    | 0    |
+| `ZlDescription`      | 主入口              | 5     | 0    | 1    | 0    |
+| `ZlDictTag`          | 主入口              | 6     | 0    | 0    | 0    |
+| `ZlDrawer`           | 主入口              | 6     | 1    | 2    | 0    |
+| `ZlDynamicComponent` | 主入口              | 3     | 2    | 0    | 0    |
+| `ZlPdfViewer`        | 主入口              | 2     | 0    | 0    | 0    |
+| `ZlLogin`            | 主入口              | 2     | 0    | 2    | 0    |
+| `ZlLoginForm`        | 主入口              | 1     | 0    | 1    | 0    |
+| `ZlEmpty`            | 主入口              | 2     | 0    | 0    | 0    |
+| `ZlForm`             | 主入口              | 2     | 0    | 3    | 0    |
+| `ZlFormChild`        | 主入口              | 1     | 0    | 0    | 0    |
+| `ZlGridItem`         | 主入口              | 1     | 0    | 1    | 0    |
+| `ZlGrid`             | 主入口              | 9     | 0    | 2    | 0    |
+| `ZlHorizontalTable`  | 主入口              | 4     | 0    | 1    | 0    |
+| `ZlIcon`             | 主入口              | 1     | 0    | 1    | 0    |
+| `ZlI18nProvider`     | 主入口              | 0     | 0    | 1    | 0    |
+| `ZlIconHover`        | 主入口              | 0     | 0    | 0    | 0    |
+| `ZlIconLabel`        | 主入口              | 1     | 1    | 1    | 0    |
+| `ZlCornerTag`        | 主入口              | 3     | 0    | 1    | 0    |
+| `ZlLayoutSwitch`     | 主入口              | 2     | 1    | 0    | 0    |
+| `ZlPagination`       | 主入口              | 3     | 3    | 0    | 0    |
+| `ZlPermission`       | 主入口              | 1     | 0    | 1    | 0    |
+| `ZlPopconfirm`       | 主入口              | 4     | 2    | 3    | 0    |
+| `ZlRadioTag`         | 主入口              | 3     | 1    | 1    | 0    |
+| `ZlSearch`           | 主入口              | 5     | 2    | 2    | 3    |
+| `ZlSearchTable`      | 主入口              | 5     | 1    | 3    | 4    |
+| `ZlSection`          | 主入口              | 4     | 0    | 3    | 0    |
+| `ZlSorter`           | 主入口              | 2     | 2    | 1    | 0    |
+| `ZlSorterList`       | 主入口              | 2     | 1    | 0    | 0    |
+| `ZlSwitch`           | 主入口              | 6     | 1    | 2    | 0    |
+| `ZlTable`            | 主入口              | 6     | 3    | 3    | 0    |
+| `ZlTabs`             | 主入口              | 4     | 0    | 3    | 0    |
+| `ZlTag`              | 主入口              | 15    | 4    | 1    | 0    |
+| `ZlText`             | 主入口              | 1     | 0    | 1    | 0    |
+| `ZlTitle`            | 主入口              | 5     | 0    | 3    | 0    |
+| `ZlUpload`           | 主入口              | 11    | 1    | 1    | 0    |
+| `ZlTree`             | 主入口              | 5     | 0    | 3    | 0    |
+| `ZlTreeSelect`       | 主入口              | 6     | 1    | 0    | 0    |
+| `ZlChart`            | 子入口 chart        | 2     | 0    | 0    | 1    |
+| `ZlEditor`           | 子入口 editor       | 3     | 1    | 0    | 0    |
+| `ZlSqlEditor`        | 子入口 editor       | 4     | 1    | 0    | 0    |
+| `ZlFilePreview`      | 子入口 file-preview | 1     | 0    | 0    | 0    |
+| `ZlFileViewer`       | 子入口 file-preview | 1     | 0    | 0    | 0    |
+
+> 说明列为 `—` 表示该属性在源码里没写 `/** */` 注释（当前 133/189 个）；补完注释重跑 `pnpm docs:api` 即可同步。
+
+### 14.1 主入口组件（`@zl-ui-kit/components`）
+
+#### `ZlAction`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAction/index.vue`</sub>
+
+**简介**：操作列与操作列表
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlAction } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlAction />
+</template>
+```
+
+> 把 `$attrs` 透传给 `ZlActionList`，未列出的属性会继续下传
+
+> 纯容器组件：不接收 props，也无自定义事件/插槽/暴露方法。
+
+**完整示例**：见 §7 表单与交互组件 › ZlAction / ZlActionList —— 操作列与操作列表
+
+#### `ZlActionList`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAction/List.vue`</sub>
+
+**简介**：操作列与操作列表
+
+**接口概览**：6 props · 1 事件 · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlActionList } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlActionList :list-count="2" />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlActionList>
+    <template #more>…</template>
+  </ZlActionList>
+</template>
+```
+
+**props**
+
+| 属性          | 类型                             | 默认值     | 必填 | 示例                    | 说明                                 |
+| ------------- | -------------------------------- | ---------- | ---- | ----------------------- | ------------------------------------ |
+| `actions`     | `ActionItem[]`                   | `() => []` | 否   | `:actions="actions"`    | —                                    |
+| `actionArgs`  | `any[]`                          | `() => []` | 否   | `:action-args="[]"`     | —                                    |
+| `visibleArgs` | `any[]`                          | `() => []` | 否   | `:visible-args="[]"`    | —                                    |
+| `listCount`   | `number`                         | `2`        | 否   | `:list-count="1"`       | 直接展示的操作数，超出收入"更多"下拉 |
+| `iconMore`    | `boolean \| Record<string, any>` | —          | 否   | `:icon-more="iconMore"` | —                                    |
+| `separator`   | `boolean`                        | —          | 否   | `separator`             | —                                    |
+
+**事件（emits）**
+
+| 事件     | 参数                | 说明 |
+| -------- | ------------------- | ---- |
+| `action` | `ActionItem, any[]` | —    |
+
+**插槽（slots）**
+
+| 插槽   | 作用域参数 | 示例                           | 说明 |
+| ------ | ---------- | ------------------------------ | ---- |
+| `more` | —          | `<template #more>…</template>` | —    |
+
+**完整示例**：见 §7 表单与交互组件 › ZlAction / ZlActionList —— 操作列与操作列表
+
+#### `ZlAddSub`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAddSub/index.vue`</sub>
+
+**接口概览**：2 props · 1 事件 · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlAddSub } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlAddSub :model-value="['示例项']" />
+</template>
+```
+
+> 示例中的 `modelValue` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlAddSub>
+    <template #add="{ index }">…</template>
+  </ZlAddSub>
+</template>
+```
+
+**props**
+
+| 属性         | 类型              | 默认值     | 必填 | 示例                        | 说明           |
+| ------------ | ----------------- | ---------- | ---- | --------------------------- | -------------- |
+| `model`      | `any[]`           | `() => []` | 否   | `v-model:model="value"`     | —              |
+| `defaultVal` | `any[] \| string` | `() => []` | 否   | `:default-val="defaultVal"` | 新增项的默认值 |
+
+**事件（emits）**
+
+| 事件           | 参数    | 说明 |
+| -------------- | ------- | ---- |
+| `update:model` | `any[]` | —    |
+
+**插槽（slots）**
+
+| 插槽  | 作用域参数 | 示例                                      | 说明 |
+| ----- | ---------- | ----------------------------------------- | ---- |
+| `add` | `index`    | `<template #add="{ index }">…</template>` | —    |
+
+**完整示例**：见 §7 表单与交互组件 › ZlRadioTag / ZlCheckboxTag / ZlCheckAll / ZlSorter / ZlAddSub / ZlLayoutSwitch
+
+#### `ZlAppLayout`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAppLayout/index.vue`</sub>
+
+**接口概览**：1 props · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlAppLayout } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlAppLayout />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlAppLayout>
+    <template #default>…</template>
+  </ZlAppLayout>
+</template>
+```
+
+**props**
+
+| 属性     | 类型                         | 默认值         | 必填 | 示例                  | 说明 |
+| -------- | ---------------------------- | -------------- | ---- | --------------------- | ---- |
+| `layout` | `'horizontal' \| 'vertical'` | `'horizontal'` | 否   | `layout="horizontal"` | —    |
+
+> 选项式组件（`defineComponent`），props 定义在 `props: {}` 中
+> 把 `$attrs` 透传给内部组件，未列出的属性会继续下传
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明                                        |
+| --------- | ---------- | --------------------------------- | ------------------------------------------- |
+| `default` | —          | `<template #default>…</template>` | 整个 `slots` 对象原样透传，插槽由子组件决定 |
+
+**完整示例**：见 §8 布局与权限 › ZlAppLayout / ZlAppMenu
+
+#### `ZlAppMenu`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAppMenu/AppMenu.vue`</sub>
+
+**接口概览**：3 props · 1 事件
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlAppMenu } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlAppMenu :menus="menus" />
+</template>
+```
+
+> 示例中的 `menus` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**props**
+
+| 属性        | 类型                         | 默认值       | 必填 | 示例                | 说明                                |
+| ----------- | ---------------------------- | ------------ | ---- | ------------------- | ----------------------------------- |
+| `collapsed` | `boolean`                    | `false`      | 否   | `collapsed`         | —                                   |
+| `layout`    | `'vertical' \| 'horizontal'` | `'vertical'` | 否   | `layout="vertical"` | el-menu 模式：vertical / horizontal |
+| `menus`     | `MenuItem[]`                 | `() => []`   | 否   | `:menus="menus"`    | —                                   |
+
+**事件（emits）**
+
+| 事件              | 参数       | 说明 |
+| ----------------- | ---------- | ---- |
+| `menu-item-click` | `MenuItem` | —    |
+
+**完整示例**：见 §8 布局与权限 › ZlAppLayout / ZlAppMenu
+
+#### `ZlAppSlogan`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAppSlogan/index.vue`</sub>
+
+**简介**：应用标识（Logo + 标题）：侧栏折叠时可用 `collapsed` 只显示图标
+
+**接口概览**：3 props
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlAppSlogan } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlAppSlogan title="ZL UI 组件库" />
+</template>
+```
+
+**props**
+
+| 属性        | 类型      | 默认值 | 必填 | 示例                                  | 说明 |
+| ----------- | --------- | ------ | ---- | ------------------------------------- | ---- |
+| `collapsed` | `boolean` | —      | 否   | `collapsed`                           | —    |
+| `logo`      | `string`  | —      | 否   | `logo="https://example.com/logo.png"` | —    |
+| `title`     | `string`  | —      | 否   | `title="标题"`                        | —    |
+
+#### `ZlAutoTooltip`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAutoTooltip/index.vue`</sub>
+
+**简介**：文本溢出自动 tooltip：内容超出容器宽度时才出提示，未溢出不出
+
+**接口概览**：1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlAutoTooltip } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlAutoTooltip> 超长文本自动省略并悬浮提示：zl-ui 是 Vue3 + Element Plus 组件库 </ZlAutoTooltip>
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlAutoTooltip>
+    <template #default>…</template>
+  </ZlAutoTooltip>
+</template>
+```
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+
+#### `ZlAvatar`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAvatar/index.vue`</sub>
+
+**接口概览**：3 props
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlAvatar } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlAvatar label="湛" size="40px" />
+</template>
+```
+
+**props**
+
+| 属性       | 类型     | 默认值   | 必填 | 示例                                         | 说明             |
+| ---------- | -------- | -------- | ---- | -------------------------------------------- | ---------------- |
+| `imageUrl` | `string` | —        | 否   | `image-url="https://example.com/avatar.png"` | —                |
+| `label`    | `string` | —        | 否   | `label="标签"`                               | —                |
+| `size`     | `string` | `'20px'` | 否   | `size="24px"`                                | 尺寸（CSS 长度） |
+
+#### `ZlAvatarGroup`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAvatar/Group.vue`</sub>
+
+**接口概览**：3 props
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlAvatarGroup } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlAvatarGroup :list="list" size="32px" />
+</template>
+```
+
+> 示例中的 `list` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**props**
+
+| 属性    | 类型                                    | 默认值                                             | 必填 | 示例           | 说明                                |
+| ------- | --------------------------------------- | -------------------------------------------------- | ---- | -------------- | ----------------------------------- |
+| `list`  | `Array<Record<string, any>>`            | —                                                  | 是   | `:list="list"` | —                                   |
+| `props` | `{ imageUrl?: string; label?: string }` | `() => ({ imageUrl: 'imageUrl', label: 'label' })` | 否   | `:props="{}"`  | 字段映射（imageUrl/label 的取值键） |
+| `size`  | `string`                                | —                                                  | 否   | `size="24px"`  | —                                   |
+
+#### `ZlCard`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlCard/index.vue`</sub>
+
+**简介**：卡片容器：默认带悬停阴影（`hoverable`），内容走默认插槽
+
+**接口概览**：1 props · 8 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlCard } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlCard style="max-width: 360px">
+    <template #title>数据库资源</template>
+    <template #subtitle>副标题描述文案</template>
+  </ZlCard>
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlCard>
+    <template #icon>…</template>
+    <template #title>…</template>
+    <template #title-append>…</template>
+    <template #subtitle>…</template>
+    <template #default>…</template>
+    <template #footer-prepend>…</template>
+    <template #footer>…</template>
+    <template #extra>…</template>
+  </ZlCard>
+</template>
+```
+
+**props**
+
+| 属性        | 类型      | 默认值 | 必填 | 示例                 | 说明 |
+| ----------- | --------- | ------ | ---- | -------------------- | ---- |
+| `hoverable` | `boolean` | `true` | 否   | `:hoverable="false"` | —    |
+
+**插槽（slots）**
+
+| 插槽             | 作用域参数 | 示例                                     | 说明 |
+| ---------------- | ---------- | ---------------------------------------- | ---- |
+| `icon`           | —          | `<template #icon>…</template>`           | —    |
+| `title`          | —          | `<template #title>…</template>`          | —    |
+| `title-append`   | —          | `<template #title-append>…</template>`   | —    |
+| `subtitle`       | —          | `<template #subtitle>…</template>`       | —    |
+| `default`        | —          | `<template #default>…</template>`        | —    |
+| `footer-prepend` | —          | `<template #footer-prepend>…</template>` | —    |
+| `footer`         | —          | `<template #footer>…</template>`         | —    |
+| `extra`          | —          | `<template #extra>…</template>`          | —    |
+
+#### `ZlCardPage`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlCardPage/index.vue`</sub>
+
+**简介**：直接传 service
+
+**接口概览**：6 props · 1 事件 · 3 插槽 · 3 暴露
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlCardPage } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlCardPage :request="mockPageRequest" card-min-width="180px" />
+</template>
+```
+
+> 示例中的 `request` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlCardPage>
+    <template #search-actions>…</template>
+    <template #default="{ data }">…</template>
+    <!-- 动态插槽：名字运行时取自 search-${slot} -->
+  </ZlCardPage>
+</template>
+```
+
+**props**
+
+| 属性           | 类型                                                                                                                          | 默认值     | 必填 | 示例                        | 说明                              |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------- | ---- | --------------------------- | --------------------------------- |
+| `immediate`    | `boolean`                                                                                                                     | `true`     | 否   | `:immediate="false"`        | —                                 |
+| `request`      | `\| ((...args: any[]) => Promise<any>)       \| { service: (...args: any[]) => Promise<any>; options?: Record<string, any> }` | —          | 是   | `:request="async () => {}"` | 请求函数，或 { service, options } |
+| `queryItems`   | `SearchItem[]`                                                                                                                | `() => []` | 否   | `:query-items="queryItems"` | —                                 |
+| `pagination`   | `Record<string, any> \| boolean`                                                                                              | `true`     | 否   | `:pagination="{}"`          | —                                 |
+| `itemKey`      | `string`                                                                                                                      | `'id'`     | 否   | `item-key="id"`             | —                                 |
+| `cardMinWidth` | `string`                                                                                                                      | —          | 否   | `card-min-width="280px"`    | —                                 |
+
+**事件（emits）**
+
+| 事件           | 参数 | 说明 |
+| -------------- | ---- | ---- |
+| `search-reset` | —    | —    |
+
+**插槽（slots）**
+
+| 插槽               | 作用域参数                     | 示例                                               | 说明                         |
+| ------------------ | ------------------------------ | -------------------------------------------------- | ---------------------------- |
+| `search-actions`   | —                              | `<template #search-actions>…</template>`           | —                            |
+| `[search-${slot}]` | `v-bind="scope"` 展开          | `<template #[search-${slot}]="scope">…</template>` | 动态插槽：名字由该表达式决定 |
+| `default`          | `v-bind="{ data: item }"` 展开 | `<template #default="{ data }">…</template>`       | —                            |
+
+**暴露（defineExpose）**
+
+| 名称      | 说明 |
+| --------- | ---- |
+| `refresh` | —    |
+| `params`  | —    |
+| `search`  | —    |
+
+**完整示例**：见 §6 数据型组件 + useRequest 体系（核心） › ② ZlCardPage —— 直接传 service
+
+#### `ZlCheckAll`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlCheckAll/index.vue`</sub>
+
+**简介**：全选开关：勾选/取消全部（支持半选态），选项可带 disabled
+
+**接口概览**：2 props · 1 事件
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlCheckAll } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlCheckAll :model-value="modelValue" />
+</template>
+```
+
+> 示例中的 `modelValue` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**props**
+
+| 属性      | 类型                      | 默认值     | 必填 | 示例                    | 说明 |
+| --------- | ------------------------- | ---------- | ---- | ----------------------- | ---- |
+| `options` | `CheckAllOption[]`        | `() => []` | 否   | `:options="options"`    | —    |
+| `model`   | `Array<string \| number>` | `() => []` | 否   | `v-model:model="value"` | —    |
+
+**事件（emits）**
+
+| 事件           | 参数                      | 说明 |
+| -------------- | ------------------------- | ---- |
+| `update:model` | `Array<string \| number>` | —    |
+
+**完整示例**：见 §7 表单与交互组件 › ZlRadioTag / ZlCheckboxTag / ZlCheckAll / ZlSorter / ZlAddSub / ZlLayoutSwitch
+
+#### `ZlCheckboxTag`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlCheckboxTag/index.vue`</sub>
+
+**接口概览**：7 props · 1 事件 · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlCheckboxTag } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlCheckboxTag v-model="value" />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlCheckboxTag>
+    <template #default="{ item, checked }">…</template>
+  </ZlCheckboxTag>
+</template>
+```
+
+**props**
+
+| 属性         | 类型                            | 默认值     | 必填 | 示例                 | 说明                                         |
+| ------------ | ------------------------------- | ---------- | ---- | -------------------- | -------------------------------------------- |
+| `modelValue` | `any`                           | —          | 否   | `v-model="value"`    | `v-model` 绑定的值（`defineModel` 隐式声明） |
+| `options`    | `CheckboxTagOption[]`           | `() => []` | 否   | `:options="options"` | —                                            |
+| `single`     | `boolean`                       | —          | 否   | `single`             | 单选模式（值为单值）                         |
+| `rounded`    | `boolean`                       | `true`     | 否   | `:rounded="false"`   | —                                            |
+| `bordered`   | `boolean`                       | `true`     | 否   | `:bordered="false"`  | —                                            |
+| `fill`       | `boolean`                       | `true`     | 否   | `:fill="false"`      | —                                            |
+| `size`       | `'mini' \| 'small' \| 'medium'` | `'small'`  | 否   | `size="mini"`        | —                                            |
+
+**事件（emits）**
+
+| 事件                | 参数  | 说明           |
+| ------------------- | ----- | -------------- |
+| `update:modelValue` | `any` | `v-model` 更新 |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数                                                    | 示例                                                  | 说明 |
+| --------- | ------------------------------------------------------------- | ----------------------------------------------------- | ---- |
+| `default` | `v-bind="{ item, checked: checkedSet.has(item.value) }"` 展开 | `<template #default="{ item, checked }">…</template>` | —    |
+
+**完整示例**：见 §7 表单与交互组件 › ZlRadioTag / ZlCheckboxTag / ZlCheckAll / ZlSorter / ZlAddSub / ZlLayoutSwitch
+
+#### `ZlCopy`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlCopy/index.vue`</sub>
+
+**简介**：一键复制
+
+**接口概览**：2 props · 2 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlCopy } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlCopy text="被复制的文本内容" />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlCopy>
+    <template #default>…</template>
+    <template #trigger="{ copy }">…</template>
+  </ZlCopy>
+</template>
+```
+
+**props**
+
+| 属性       | 类型     | 默认值 | 必填 | 示例                   | 说明 |
+| ---------- | -------- | ------ | ---- | ---------------------- | ---- |
+| `text`     | `string` | —      | 否   | `text="文本"`          | —    |
+| `copyText` | `string` | —      | 否   | `copy-text="复制内容"` | —    |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                                         | 说明 |
+| --------- | ---------- | -------------------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>`            | —    |
+| `trigger` | `copy`     | `<template #trigger="{ copy }">…</template>` | —    |
+
+**完整示例**：见 §5 通用展示组件 › ZlCopy — 一键复制
+
+#### `ZlDescription`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlDescription/index.vue`</sub>
+
+**接口概览**：5 props · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlDescription } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlDescription :items="items" :data="{ name: '订单-1024', type: 'API', count: 32 }" secondary />
+</template>
+```
+
+> 示例中的 `items`、`data` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlDescription>
+    <!-- 动态插槽：名字运行时取自 item.key -->
+  </ZlDescription>
+</template>
+```
+
+**props**
+
+| 属性           | 类型                                                              | 默认值                                 | 必填 | 示例                        | 说明                                                                 |
+| -------------- | ----------------------------------------------------------------- | -------------------------------------- | ---- | --------------------------- | -------------------------------------------------------------------- |
+| `items`        | `DescriptionItem[]`                                               | —                                      | 是   | `:items="items"`            | —                                                                    |
+| `data`         | `Record<string, any>`                                             | `() => ({})`                           | 否   | `:data="{}"`                | —                                                                    |
+| `emptyChecker` | `(value: any, key: string, data: Record<string, any>) => boolean` | `(val: any) => !val && !isNumber(val)` | 否   | `:empty-checker="() => {}"` | —                                                                    |
+| `emptyText`    | `string`                                                          | —                                      | 否   | `empty-text="暂无数据"`     | 空值占位文案（缺省走 i18n zl.description.empty，未接入时兜底"暂无"） |
+| `secondary`    | `boolean`                                                         | —                                      | 否   | `secondary`                 | —                                                                    |
+
+**插槽（slots）**
+
+| 插槽         | 作用域参数 | 示例                                 | 说明                         |
+| ------------ | ---------- | ------------------------------------ | ---------------------------- |
+| `[item.key]` | —          | `<template #[item.key]>…</template>` | 动态插槽：名字由该表达式决定 |
+
+#### `ZlDictTag`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlDictTag/index.vue`</sub>
+
+**简介**：字典标签
+
+**接口概览**：6 props
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlDictTag } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlDictTag dict-key="resourceType" value="1" :dict="dict" />
+</template>
+```
+
+> 示例中的 `dict` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**props**
+
+| 属性       | 类型                                                                      | 默认值  | 必填 | 示例                | 说明                                                                                              |
+| ---------- | ------------------------------------------------------------------------- | ------- | ---- | ------------------- | ------------------------------------------------------------------------------------------------- |
+| `dictKey`  | `string`                                                                  | —       | 是   | `dict-key="gender"` | 字典键（对应全局字典缓存的键；外部直传数据也以该键写入共享缓存）                                  |
+| `dict`     | `DictItem[]`                                                              | —       | 否   | `:dict="dict"`      | 外部直传字典数据：无需依赖全局数据源即可翻译。格式同 DictItem[]（{ label, value, icon?, type? }） |
+| `corner`   | `boolean \| 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `false` | 否   | `corner="top-left"` | —                                                                                                 |
+| `value`    | `string`                                                                  | —       | 否   | `value="1"`         | —                                                                                                 |
+| `simple`   | `boolean`                                                                 | —       | 否   | `simple`            | —                                                                                                 |
+| `hideIcon` | `boolean`                                                                 | —       | 否   | `hide-icon`         | —                                                                                                 |
+
+> 把 `$attrs` 透传给 `zl-corner-tag`，未列出的属性会继续下传
+
+**完整示例**：见 §5 通用展示组件 › ZlDictTag — 字典标签
+
+#### `ZlDrawer`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlDrawer/index.vue`</sub>
+
+**接口概览**：6 props · 1 事件 · 2 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlDrawer } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlDrawer v-model:visible="value" title="抽屉标题" />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlDrawer>
+    <template #default>…</template>
+    <template #footer>…</template>
+  </ZlDrawer>
+</template>
+```
+
+**props**
+
+| 属性                    | 类型                                                | 默认值  | 必填 | 示例                                | 说明                                         |
+| ----------------------- | --------------------------------------------------- | ------- | ---- | ----------------------------------- | -------------------------------------------- |
+| `visible`               | `boolean`                                           | `false` | 否   | `v-model:visible="value"`           | `v-model` 绑定的值（`defineModel` 隐式声明） |
+| `onCancel`              | `() => boolean \| void \| Promise<boolean \| void>` | —       | 否   | `:on-cancel="async () => {}"`       | —                                            |
+| `onOk`                  | `() => void \| Promise<void>`                       | —       | 否   | `:on-ok="async () => {}"`           | —                                            |
+| `autoCloseAfterConfirm` | `boolean`                                           | `true`  | 否   | `:auto-close-after-confirm="false"` | —                                            |
+| `readonly`              | `boolean`                                           | —       | 否   | `readonly`                          | —                                            |
+| `loading`               | `boolean`                                           | —       | 否   | `loading`                           | —                                            |
+
+**事件（emits）**
+
+| 事件             | 参数      | 说明           |
+| ---------------- | --------- | -------------- |
+| `update:visible` | `boolean` | `v-model` 更新 |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+| `footer`  | —          | `<template #footer>…</template>`  | —    |
+
+**完整示例**：见 §7 表单与交互组件 › ZlDrawer / ZlPopconfirm / ZlSwitch
+
+#### `ZlDynamicComponent`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlDynamicComponent/index.vue`</sub>
+
+**接口概览**：3 props · 2 事件
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlDynamicComponent } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlDynamicComponent :model="{ keyword: '' }" :component="component" />
+</template>
+```
+
+> 示例中的 `model`、`component` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**props**
+
+| 属性        | 类型                               | 默认值                              | 必填 | 示例              | 说明 |
+| ----------- | ---------------------------------- | ----------------------------------- | ---- | ----------------- | ---- |
+| `model`     | `Record<string, any>`              | `() => ({})`                        | 否   | `:model="{}"`     | —    |
+| `value`     | `[String, Number, Array, Boolean]` | `null`                              | 否   | `:value="value"`  | —    |
+| `component` | `Record<string, any>`              | `() => ({ component: 'el-input' })` | 否   | `:component="{}"` | —    |
+
+> 选项式组件（`defineComponent`），props 定义在 `props: {}` 中
+
+**事件（emits）**
+
+| 事件                | 参数 | 说明 |
+| ------------------- | ---- | ---- |
+| `update:modelValue` | —    | —    |
+| `input`             | —    | —    |
+
+**完整示例**：见 §7 表单与交互组件 › ZlTabs / ZlDynamicComponent / ZlGrid
+
+#### `ZlPdfViewer`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlPdfViewer/index.vue`</sub>
+
+**简介**：PDF 预览：用浏览器原生 object 渲染，无重型依赖（所以留在主入口）
+
+**接口概览**：2 props
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlPdfViewer } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlPdfViewer :width="420" />
+</template>
+```
+
+**props**
+
+| 属性    | 类型               | 默认值 | 必填 | 示例                                 | 说明 |
+| ------- | ------------------ | ------ | ---- | ------------------------------------ | ---- |
+| `url`   | `string`           | —      | 否   | `url="https://example.com/file.pdf"` | —    |
+| `width` | `number \| string` | —      | 否   | `:width="width"`                     | —    |
+
+#### `ZlLogin`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlLogin/index.vue`</sub>
+
+**接口概览**：2 props · 2 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlLogin } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlLogin :config="{ title: 'ZL 统一登录' }" :on-submit="() => {}" />
+</template>
+```
+
+> 示例中的 `config`、`onSubmit` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlLogin>
+    <template #slogan>…</template>
+    <template #default>…</template>
+  </ZlLogin>
+</template>
+```
+
+**props**
+
+| 属性       | 类型                                                   | 默认值       | 必填 | 示例                          | 说明 |
+| ---------- | ------------------------------------------------------ | ------------ | ---- | ----------------------------- | ---- |
+| `onSubmit` | `(form: Record<string, any>) => Promise<void> \| void` | —            | 否   | `:on-submit="async () => {}"` | —    |
+| `config`   | `ZlLoginConfig`                                        | `() => ({})` | 否   | `:config="config"`            | —    |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `slogan`  | —          | `<template #slogan>…</template>`  | —    |
+| `default` | —          | `<template #default>…</template>` | —    |
+
+#### `ZlLoginForm`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlLogin/components/LoginForm.vue`</sub>
+
+**简介**：登录表单（账号 + 密码 + 可选滑块校验），提交经 `onSubmit` 回调交给宿主
+
+**接口概览**：1 props · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlLoginForm } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlLoginForm :on-submit="() => {}" />
+</template>
+```
+
+> 示例中的 `onSubmit` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlLoginForm>
+    <template #action>…</template>
+  </ZlLoginForm>
+</template>
+```
+
+**props**
+
+| 属性       | 类型                                                   | 默认值 | 必填 | 示例                          | 说明 |
+| ---------- | ------------------------------------------------------ | ------ | ---- | ----------------------------- | ---- |
+| `onSubmit` | `(form: Record<string, any>) => Promise<void> \| void` | —      | 否   | `:on-submit="async () => {}"` | —    |
+
+**插槽（slots）**
+
+| 插槽     | 作用域参数 | 示例                             | 说明 |
+| -------- | ---------- | -------------------------------- | ---- |
+| `action` | —          | `<template #action>…</template>` | —    |
+
+#### `ZlEmpty`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlEmpty/index.vue`</sub>
+
+**简介**：空状态
+
+**接口概览**：2 props
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlEmpty } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlEmpty />
+</template>
+```
+
+**props**
+
+| 属性    | 类型     | 默认值 | 必填 | 示例                                    | 说明                                        |
+| ------- | -------- | ------ | ---- | --------------------------------------- | ------------------------------------------- |
+| `image` | `string` | —      | 否   | `image="https://example.com/empty.png"` | 自定义空状态图片（缺省用内置轻量 SVG 线稿） |
+| `text`  | `string` | `''`   | 否   | `text="文本"`                           | 空状态文案（缺省走 i18n，未接入时兜底中文） |
+
+**完整示例**：见 §5 通用展示组件 › ZlEmpty — 空状态
+
+#### `ZlForm`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlForm/index.vue`</sub>
+
+**简介**：schema 驱动
+
+**接口概览**：2 props · 3 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlForm } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlForm :model="model" :items="items" label-width="80px" style="max-width: 420px" />
+</template>
+```
+
+> 示例中的 `model`、`items` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlForm>
+    <template #label="{ label, item }">…</template>
+    <template #default>…</template>
+    <!-- 动态插槽：名字运行时取自 item.model -->
+  </ZlForm>
+</template>
+```
+
+**props**
+
+| 属性    | 类型                  | 默认值     | 必填 | 示例             | 说明 |
+| ------- | --------------------- | ---------- | ---- | ---------------- | ---- |
+| `items` | `FormItem[]`          | `() => []` | 否   | `:items="items"` | —    |
+| `model` | `Record<string, any>` | —          | 否   | `:model="{}"`    | —    |
+
+> 把 `$attrs` 透传给 `el-form`，未列出的属性会继续下传
+
+**插槽（slots）**
+
+| 插槽           | 作用域参数                                  | 示例                                                      | 说明                         |
+| -------------- | ------------------------------------------- | --------------------------------------------------------- | ---------------------------- |
+| `label`        | `v-bind="{ label: item.label, item }"` 展开 | `<template #label="{ label, item }">…</template>`         | —                            |
+| `[item.model]` | `model` / `field`                           | `<template #[item.model]="{ model, field }">…</template>` | 动态插槽：名字由该表达式决定 |
+| `default`      | —                                           | `<template #default>…</template>`                         | —                            |
+
+**完整示例**：见 §7 表单与交互组件 › ZlForm —— schema 驱动
+
+#### `ZlFormChild`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlForm/ZlFormChild.vue`</sub>
+
+**接口概览**：1 props
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlFormChild } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlFormChild :item="item" />
+</template>
+```
+
+> 示例中的 `item` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**props**
+
+| 属性   | 类型                  | 默认值 | 必填 | 示例         | 说明 |
+| ------ | --------------------- | ------ | ---- | ------------ | ---- |
+| `item` | `Record<string, any>` | —      | 是   | `:item="{}"` | —    |
+
+> 选项式组件（`defineComponent`），props 定义在 `props: {}` 中
+
+#### `ZlGridItem`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlGrid/ZlGridItem.vue`</sub>
+
+**简介**：单个描述项：由 `ZlGrid` 内部渲染，一般不单独使用
+
+**接口概览**：1 props · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlGridItem } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlGridItem :item="item" />
+</template>
+```
+
+> 示例中的 `item` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlGridItem>
+    <template #default>…</template>
+  </ZlGridItem>
+</template>
+```
+
+**props**
+
+| 属性   | 类型                                                                              | 默认值 | 必填 | 示例           | 说明 |
+| ------ | --------------------------------------------------------------------------------- | ------ | ---- | -------------- | ---- |
+| `item` | `IGridItem & { text?: any; size?: number \| 'auto'; dict?: Record<string, any> }` | —      | 是   | `:item="item"` | —    |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+
+#### `ZlGrid`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlGrid/index.vue`</sub>
+
+**接口概览**：9 props · 2 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlGrid } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlGrid :data="data" :cols="2" border :grid="grid" />
+</template>
+```
+
+> 示例中的 `data`、`grid` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlGrid>
+    <template #default>…</template>
+    <!-- 动态插槽：名字运行时取自 item.key -->
+  </ZlGrid>
+</template>
+```
+
+**props**
+
+| 属性            | 类型                                                              | 默认值       | 必填 | 示例                        | 说明                                                          |
+| --------------- | ----------------------------------------------------------------- | ------------ | ---- | --------------------------- | ------------------------------------------------------------- |
+| `data`          | `Record<string, any>`                                             | `() => ({})` | 否   | `:data="{}"`                | —                                                             |
+| `grid`          | `IGridItem[]`                                                     | `() => []`   | 否   | `:grid="grid"`              | —                                                             |
+| `cols`          | `number`                                                          | `3`          | 否   | `:cols="1"`                 | —                                                             |
+| `border`        | `boolean`                                                         | —            | 否   | `border`                    | —                                                             |
+| `emptyChecker`  | `(value: any, key: string, data: Record<string, any>) => boolean` | —            | 否   | `:empty-checker="() => {}"` | —                                                             |
+| `labelWidth`    | `string \| number`                                                | `'auto'`     | 否   | `:label-width="labelWidth"` | —                                                             |
+| `labelSuffix`   | `string`                                                          | —            | 否   | `label-suffix="："`         | —                                                             |
+| `labelPosition` | `'left' \| 'top' \| 'right'`                                      | `'left'`     | 否   | `label-position="left"`     | —                                                             |
+| `emptyText`     | `string`                                                          | —            | 否   | `empty-text="暂无数据"`     | 空值占位文案（缺省走 i18n zl.grid.empty，未接入时兜底"暂无"） |
+
+**插槽（slots）**
+
+| 插槽         | 作用域参数 | 示例                                 | 说明                         |
+| ------------ | ---------- | ------------------------------------ | ---------------------------- |
+| `[item.key]` | —          | `<template #[item.key]>…</template>` | 动态插槽：名字由该表达式决定 |
+| `default`    | —          | `<template #default>…</template>`    | —                            |
+
+**完整示例**：见 §7 表单与交互组件 › ZlTabs / ZlDynamicComponent / ZlGrid
+
+#### `ZlHorizontalTable`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlHorizontalTable/index.vue`</sub>
+
+**接口概览**：4 props · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlHorizontalTable } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlHorizontalTable :items="items" :span="12" />
+</template>
+```
+
+> 示例中的 `items` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlHorizontalTable>
+    <!-- 动态插槽：名字运行时取自 item.slot -->
+  </ZlHorizontalTable>
+</template>
+```
+
+**props**
+
+| 属性         | 类型                    | 默认值     | 必填 | 示例                  | 说明 |
+| ------------ | ----------------------- | ---------- | ---- | --------------------- | ---- |
+| `items`      | `HorizontalTableItem[]` | `() => []` | 否   | `:items="items"`      | —    |
+| `span`       | `number \| string`      | `24`       | 否   | `:span="span"`        | —    |
+| `labelWidth` | `string`                | `'88px'`   | 否   | `label-width="100px"` | —    |
+| `labelAlign` | `string`                | `'center'` | 否   | `label-align="left"`  | —    |
+
+**插槽（slots）**
+
+| 插槽          | 作用域参数           | 示例                                         | 说明                         |
+| ------------- | -------------------- | -------------------------------------------- | ---------------------------- |
+| `[item.slot]` | `v-bind="item"` 展开 | `<template #[item.slot]="item">…</template>` | 动态插槽：名字由该表达式决定 |
+
+**完整示例**：见 §8 布局与权限 › ZlHorizontalTable
+
+#### `ZlIcon`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlIcon/index.vue`</sub>
+
+**接口概览**：1 props · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlIcon } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlIcon icon="zl:bug" />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlIcon>
+    <template #default>…</template>
+  </ZlIcon>
+</template>
+```
+
+**props**
+
+| 属性   | 类型     | 默认值 | 必填 | 示例               | 说明                                                            |
+| ------ | -------- | ------ | ---- | ------------------ | --------------------------------------------------------------- |
+| `icon` | `string` | —      | 是   | `icon="zl:search"` | 图标：zl:xxx（本地图标集）/ http(s) 地址 / 本地 svg sprite 名称 |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+
+#### `ZlI18nProvider`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlI18nProvider/index.vue`</sub>
+
+**简介**：国际化根容器：将全局数据里的 Element Plus 语言包（elLocaleMessages） 经 <el-config-provider> 绑定到 Element Plus，使分页/日期选择器等内置组件 随应用语言切换而本地化。 用法：在应用根（或子树根）包裹一次即可。 <ZlI18nProvider> <A…
+
+**接口概览**：1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlI18nProvider } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlI18nProvider />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlI18nProvider>
+    <template #default>…</template>
+  </ZlI18nProvider>
+</template>
+```
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+
+#### `ZlIconHover`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlIconHover/index.vue`</sub>
+
+**简介**：悬停变色的图标：内部复用 `ZlIconLabel`，仅换配色
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlIconHover } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlIconHover icon="zl:setting"> 悬浮操作 </ZlIconHover>
+</template>
+```
+
+> 纯容器组件：不接收 props，也无自定义事件/插槽/暴露方法。
+
+#### `ZlIconLabel`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlIconLabel/index.vue`</sub>
+
+**接口概览**：1 props · 1 事件 · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlIconLabel } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlIconLabel icon="zl:database"> 图标 + 文字 </ZlIconLabel>
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlIconLabel>
+    <template #default>…</template>
+  </ZlIconLabel>
+</template>
+```
+
+**props**
+
+| 属性          | 类型      | 默认值  | 必填 | 示例           | 说明                     |
+| ------------- | --------- | ------- | ---- | -------------- | ------------------------ |
+| `darkSurface` | `boolean` | `false` | 否   | `dark-surface` | 深色表面（悬浮背景更深） |
+
+> 把 `$attrs` 透传给 `zl-icon`，未列出的属性会继续下传
+
+**事件（emits）**
+
+| 事件    | 参数         | 说明 |
+| ------- | ------------ | ---- |
+| `click` | `MouseEvent` | —    |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+
+#### `ZlCornerTag`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlTag/ZlCornerTag.vue`</sub>
+
+**简介**：角落标签：贴在容器四个角（`position`），常用于「新」「热」等标记
+
+**接口概览**：3 props · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlCornerTag } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlCornerTag color="purple"> 角标 </ZlCornerTag>
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlCornerTag>
+    <template #default>…</template>
+  </ZlCornerTag>
+</template>
+```
+
+**props**
+
+| 属性       | 类型                                                           | 默认值        | 必填 | 示例                  | 说明 |
+| ---------- | -------------------------------------------------------------- | ------------- | ---- | --------------------- | ---- |
+| `icon`     | `string`                                                       | —             | 否   | `icon="zl:search"`    | —    |
+| `color`    | `string`                                                       | —             | 否   | `color="#409eff"`     | —    |
+| `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'top-right'` | 否   | `position="top-left"` | —    |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+
+#### `ZlLayoutSwitch`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlLayoutSwitch/index.vue`</sub>
+
+**简介**：布局切换：在网格视图（grid）与表格视图（table）之间切换
+
+**接口概览**：2 props · 1 事件
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlLayoutSwitch } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlLayoutSwitch v-model="value" />
+</template>
+```
+
+**props**
+
+| 属性         | 类型                | 默认值   | 必填 | 示例              | 说明                                         |
+| ------------ | ------------------- | -------- | ---- | ----------------- | -------------------------------------------- |
+| `modelValue` | `'grid' \| 'table'` | —        | 否   | `v-model="value"` | `v-model` 绑定的值（`defineModel` 隐式声明） |
+| `value`      | `'grid' \| 'table'` | `'grid'` | 否   | `value="grid"`    | —                                            |
+
+**事件（emits）**
+
+| 事件                | 参数                | 说明           |
+| ------------------- | ------------------- | -------------- |
+| `update:modelValue` | `'grid' \| 'table'` | `v-model` 更新 |
+
+**完整示例**：见 §7 表单与交互组件 › ZlRadioTag / ZlCheckboxTag / ZlCheckAll / ZlSorter / ZlAddSub / ZlLayoutSwitch
+
+#### `ZlPagination`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlPagination/index.vue`</sub>
+
+**简介**：自行 usePaginationRequest
+
+**接口概览**：3 props · 3 事件
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlPagination } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlPagination :total="120" :page-num="1" :page-size="30" />
+</template>
+```
+
+**props**
+
+| 属性          | 类型         | 默认值 | 必填 | 示例                          | 说明                               |
+| ------------- | ------------ | ------ | ---- | ----------------------------- | ---------------------------------- |
+| `pageNum`     | `（未声明）` | —      | 否   | `:page-num="pageNum"`         | 运行时从 `$attrs` 读取，无类型约束 |
+| `pageSize`    | `（未声明）` | —      | 否   | `:page-size="pageSize"`       | 运行时从 `$attrs` 读取，无类型约束 |
+| `currentPage` | `（未声明）` | —      | 否   | `:current-page="currentPage"` | 运行时从 `$attrs` 读取，无类型约束 |
+
+> 本组件不声明 props，入参由 `$attrs` 动态读取
+
+**事件（emits）**
+
+| 事件               | 参数                                    | 说明                               |
+| ------------------ | --------------------------------------- | ---------------------------------- |
+| `change`           | `{ pageNum: number; pageSize: number }` | —                                  |
+| `page-change`      | `number`                                | 仅页码变化（区别于 pageSize 变化） |
+| `page-size-change` | `number`                                | 仅每页条数变化                     |
+
+**完整示例**：见 §6 数据型组件 + useRequest 体系（核心） › ③ ZlTable + ZlPagination —— 自行 usePaginationRequest
+
+#### `ZlPermission`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlPermission/index.vue`</sub>
+
+**接口概览**：1 props · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlPermission } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlPermission permission="table:edit:*" />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlPermission>
+    <template #default>…</template>
+  </ZlPermission>
+</template>
+```
+
+**props**
+
+| 属性         | 类型                 | 默认值 | 必填 | 示例               | 说明                                     |
+| ------------ | -------------------- | ------ | ---- | ------------------ | ---------------------------------------- |
+| `permission` | `string \| string[]` | —      | 是   | `:permission="[]"` | 权限键（三段式，可传多个任一命中即显示） |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+
+**完整示例**：见 §8 布局与权限 › ZlPermission
+
+#### `ZlPopconfirm`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlPopconfirm/index.vue`</sub>
+
+**简介**：气泡确认框：点击触发气泡二次确认，文案可被 i18n 覆盖
+
+**接口概览**：4 props · 2 事件 · 3 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlPopconfirm } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlPopconfirm title="确认删除？" content="删除后不可恢复" />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlPopconfirm>
+    <template #default>…</template>
+    <template #title>…</template>
+    <template #content>…</template>
+  </ZlPopconfirm>
+</template>
+```
+
+**props**
+
+| 属性                | 类型     | 默认值 | 必填 | 示例                                   | 说明 |
+| ------------------- | -------- | ------ | ---- | -------------------------------------- | ---- |
+| `title`             | `string` | —      | 否   | `title="标题"`                         | —    |
+| `content`           | `string` | —      | 否   | `content="删除后不可恢复，是否继续？"` | —    |
+| `confirmButtonText` | `string` | —      | 否   | `confirm-button-text="确定"`           | —    |
+| `cancelButtonText`  | `string` | —      | 否   | `cancel-button-text="取消"`            | —    |
+
+> 把 `$attrs` 透传给 `el-popover`，未列出的属性会继续下传
+
+**事件（emits）**
+
+| 事件      | 参数 | 说明 |
+| --------- | ---- | ---- |
+| `confirm` | —    | —    |
+| `cancel`  | —    | —    |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+| `title`   | —          | `<template #title>…</template>`   | —    |
+| `content` | —          | `<template #content>…</template>` | —    |
+
+**完整示例**：见 §7 表单与交互组件 › ZlDrawer / ZlPopconfirm / ZlSwitch
+
+#### `ZlRadioTag`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlRadioTag/index.vue`</sub>
+
+**简介**：单选标签组：以标签形式做单选，选项支持图标与 disabled
+
+**接口概览**：3 props · 1 事件 · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlRadioTag } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlRadioTag v-model="value" />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlRadioTag>
+    <template #default="{ item, checked }">…</template>
+  </ZlRadioTag>
+</template>
+```
+
+**props**
+
+| 属性         | 类型                            | 默认值     | 必填 | 示例                 | 说明                                         |
+| ------------ | ------------------------------- | ---------- | ---- | -------------------- | -------------------------------------------- |
+| `modelValue` | `string \| number \| undefined` | —          | 否   | `v-model="value"`    | `v-model` 绑定的值（`defineModel` 隐式声明） |
+| `options`    | `RadioTagOption[]`              | `() => []` | 否   | `:options="options"` | —                                            |
+| `size`       | `'mini' \| 'small' \| 'medium'` | `'small'`  | 否   | `size="mini"`        | —                                            |
+
+**事件（emits）**
+
+| 事件                | 参数                            | 说明           |
+| ------------------- | ------------------------------- | -------------- |
+| `update:modelValue` | `string \| number \| undefined` | `v-model` 更新 |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数                                              | 示例                                                  | 说明 |
+| --------- | ------------------------------------------------------- | ----------------------------------------------------- | ---- |
+| `default` | `v-bind="{ item, checked: model === item.value }"` 展开 | `<template #default="{ item, checked }">…</template>` | —    |
+
+**完整示例**：见 §7 表单与交互组件 › ZlRadioTag / ZlCheckboxTag / ZlCheckAll / ZlSorter / ZlAddSub / ZlLayoutSwitch
+
+#### `ZlSearch`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlSearch/index.vue`</sub>
+
+**简介**：查询条：表单项按容器宽度自适应排列（auto-fill 网格），放不下的项自动隐藏， 并在「查询」左侧给出展开按钮（点击后在查询条上层展开全量表单，再点收起）。
+
+**接口概览**：5 props · 2 事件 · 2 插槽 · 3 暴露
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlSearch } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlSearch :items="items" />
+</template>
+```
+
+> 示例中的 `items` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlSearch>
+    <template #actions>…</template>
+    <!-- 动态插槽：名字运行时取自 slot -->
+  </ZlSearch>
+</template>
+```
+
+**props**
+
+| 属性         | 类型                  | 默认值      | 必填 | 示例                 | 说明                                                                                         |
+| ------------ | --------------------- | ----------- | ---- | -------------------- | -------------------------------------------------------------------------------------------- |
+| `items`      | `SearchItem[]`        | `() => []`  | 否   | `:items="items"`     | 查询项定义（SearchItem[]），按数组顺序排列                                                   |
+| `model`      | `Record<string, any>` | —           | 否   | `:model="{}"`        | 表单数据。传入时组件直接读写该对象（受控）； 不传则用内部副本，`params` / 标签行仍可正常工作 |
+| `immediate`  | `boolean`             | `true`      | 否   | `:immediate="false"` | 挂载后立即执行一次查询（默认 true）                                                          |
+| `disabled`   | `boolean`             | `false`     | 否   | `disabled`           | 禁用全部查询项                                                                               |
+| `showLabels` | `boolean`             | `undefined` | 否   | `show-labels`        | 是否展示「筛选条件」标签行；不传时按「是否发生溢出」自动判定                                 |
+
+**事件（emits）**
+
+| 事件     | 参数                  | 说明                                     |
+| -------- | --------------------- | ---------------------------------------- |
+| `search` | `Record<string, any>` | 查询：回传经 `toParams` 合并后的参数对象 |
+| `reset`  | —                     | 重置：表单已恢复初始值并重新查询之后触发 |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数            | 示例                                     | 说明                         |
+| --------- | --------------------- | ---------------------------------------- | ---------------------------- |
+| `[slot]`  | `v-bind="scope"` 展开 | `<template #[slot]="scope">…</template>` | 动态插槽：名字由该表达式决定 |
+| `actions` | —                     | `<template #actions>…</template>`        | —                            |
+
+**暴露（defineExpose）**
+
+| 名称     | 说明 |
+| -------- | ---- |
+| `params` | —    |
+| `search` | —    |
+| `reset`  | —    |
+
+**完整示例**：见 §6 数据型组件 + useRequest 体系（核心） › ④ ZlSearch 触发 run(params)
+
+#### `ZlSearchTable`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlSearchTable/index.vue`</sub>
+
+**简介**：直接传 service
+
+**接口概览**：5 props · 1 事件 · 3 插槽 · 4 暴露
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlSearchTable } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlSearchTable
+    :request="mockPageRequest"
+    :columns="tableColumns"
+    :query-items="queryItems"
+    :pagination="{ pageSize: 5 }"
+    height="320"
+  />
+</template>
+```
+
+> 示例中的 `request`、`columns`、`queryItems`、`pagination` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlSearchTable>
+    <template #search-actions>…</template>
+    <!-- 动态插槽：名字运行时取自 slot.slot -->
+    <!-- 动态插槽：名字运行时取自 slot -->
+  </ZlSearchTable>
+</template>
+```
+
+**props**
+
+| 属性         | 类型                                                                                                                          | 默认值     | 必填 | 示例                        | 说明                                                            |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------- | ---------- | ---- | --------------------------- | --------------------------------------------------------------- |
+| `immediate`  | `boolean`                                                                                                                     | `true`     | 否   | `:immediate="false"`        | —                                                               |
+| `request`    | `\| ((...args: any[]) => Promise<any>)       \| { service: (...args: any[]) => Promise<any>; options?: Record<string, any> }` | —          | 是   | `:request="async () => {}"` | 请求函数，或 { service, options }（usePageableRequest options） |
+| `columns`    | `TableColumn[]`                                                                                                               | `() => []` | 否   | `:columns="columns"`        | —                                                               |
+| `queryItems` | `SearchItem[]`                                                                                                                | `() => []` | 否   | `:query-items="queryItems"` | —                                                               |
+| `pagination` | `Record<string, any> \| boolean`                                                                                              | —          | 否   | `:pagination="{}"`          | —                                                               |
+
+> 把 `$attrs` 透传给 `ZlTable`，未列出的属性会继续下传
+
+**事件（emits）**
+
+| 事件           | 参数 | 说明 |
+| -------------- | ---- | ---- |
+| `search-reset` | —    | —    |
+
+**插槽（slots）**
+
+| 插槽             | 作用域参数            | 示例                                          | 说明                         |
+| ---------------- | --------------------- | --------------------------------------------- | ---------------------------- |
+| `search-actions` | —                     | `<template #search-actions>…</template>`      | —                            |
+| `[slot.slot]`    | `v-bind="scope"` 展开 | `<template #[slot.slot]="scope">…</template>` | 动态插槽：名字由该表达式决定 |
+| `[slot]`         | `v-bind="scope"` 展开 | `<template #[slot]="scope">…</template>`      | 动态插槽：名字由该表达式决定 |
+
+**暴露（defineExpose）**
+
+| 名称      | 说明 |
+| --------- | ---- |
+| `refresh` | —    |
+| `params`  | —    |
+| `search`  | —    |
+| `table`   | —    |
+
+**完整示例**：见 §6 数据型组件 + useRequest 体系（核心） › ① ZlSearchTable —— 直接传 service
+
+#### `ZlSection`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlSection/index.vue`</sub>
+
+**接口概览**：4 props · 3 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlSection } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlSection title="分区标题" icon="bug" block />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlSection>
+    <template #title-prepend>…</template>
+    <template #actions>…</template>
+    <template #default>…</template>
+  </ZlSection>
+</template>
+```
+
+**props**
+
+| 属性          | 类型      | 默认值 | 必填 | 示例               | 说明                           |
+| ------------- | --------- | ------ | ---- | ------------------ | ------------------------------ |
+| `icon`        | `string`  | —      | 否   | `icon="zl:search"` | 标题图标名（zl: 前缀自动补全） |
+| `title`       | `string`  | —      | 否   | `title="标题"`     | —                              |
+| `block`       | `boolean` | —      | 否   | `block`            | 块状布局（内容区滚动）         |
+| `blockHidden` | `boolean` | —      | 否   | `block-hidden`     | 块状布局且隐藏溢出             |
+
+**插槽（slots）**
+
+| 插槽            | 作用域参数 | 示例                                    | 说明 |
+| --------------- | ---------- | --------------------------------------- | ---- |
+| `title-prepend` | —          | `<template #title-prepend>…</template>` | —    |
+| `actions`       | —          | `<template #actions>…</template>`       | —    |
+| `default`       | —          | `<template #default>…</template>`       | —    |
+
+#### `ZlSorter`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlSorter/index.vue`</sub>
+
+**简介**：单字段排序：点一次升序、再点降序、第三次取消（`v-model` 为 '' | 'asc' | 'desc'）
+
+**接口概览**：2 props · 2 事件 · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlSorter } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlSorter label="名称" v-model="value" />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlSorter>
+    <template #default>…</template>
+  </ZlSorter>
+</template>
+```
+
+**props**
+
+| 属性         | 类型                    | 默认值 | 必填 | 示例              | 说明                                         |
+| ------------ | ----------------------- | ------ | ---- | ----------------- | -------------------------------------------- |
+| `modelValue` | `'' \| 'asc' \| 'desc'` | —      | 否   | `v-model="value"` | `v-model` 绑定的值（`defineModel` 隐式声明） |
+| `label`      | `string`                | —      | 否   | `label="标签"`    | —                                            |
+
+**事件（emits）**
+
+| 事件                | 参数                    | 说明           |
+| ------------------- | ----------------------- | -------------- |
+| `update:modelValue` | `'' \| 'asc' \| 'desc'` | `v-model` 更新 |
+| `change`            | `'' \| 'asc' \| 'desc'` | —              |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+
+**完整示例**：见 §7 表单与交互组件 › ZlRadioTag / ZlCheckboxTag / ZlCheckAll / ZlSorter / ZlAddSub / ZlLayoutSwitch
+
+#### `ZlSorterList`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlSorter/ZlSorterList.vue`</sub>
+
+**简介**：多字段排序列表：把若干个 `ZlSorter` 组织成一组，可单选/多选
+
+**接口概览**：2 props · 1 事件
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlSorterList } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlSorterList :model-value="{ name: 'asc' }" :sorters="sorters" />
+</template>
+```
+
+> 示例中的 `modelValue`、`sorters` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**props**
+
+| 属性       | 类型           | 默认值     | 必填 | 示例                 | 说明 |
+| ---------- | -------------- | ---------- | ---- | -------------------- | ---- |
+| `sorters`  | `SorterItem[]` | `() => []` | 否   | `:sorters="sorters"` | —    |
+| `multiple` | `boolean`      | `false`    | 否   | `multiple`           | —    |
+
+**事件（emits）**
+
+| 事件     | 参数                                  | 说明 |
+| -------- | ------------------------------------- | ---- |
+| `change` | `Record<string, any>, string, string` | —    |
+
+#### `ZlSwitch`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlSwitch/index.vue`</sub>
+
+**简介**：开关：值可为 boolean/string/number，支持 checkedText/uncheckedText 文案
+
+**接口概览**：6 props · 1 事件 · 2 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlSwitch } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlSwitch model-value="1" checked-value="1" unchecked-value="0" checked-text="开启" unchecked-text="关闭" />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlSwitch>
+    <template #checked>…</template>
+    <template #unchecked>…</template>
+  </ZlSwitch>
+</template>
+```
+
+**props**
+
+| 属性             | 类型                          | 默认值  | 必填 | 示例                                | 说明 |
+| ---------------- | ----------------------------- | ------- | ---- | ----------------------------------- | ---- |
+| `modelValue`     | `boolean \| string \| number` | —       | 否   | `v-model="value"`                   | —    |
+| `defaultChecked` | `boolean`                     | `false` | 否   | `default-checked`                   | —    |
+| `checkedValue`   | `boolean \| string \| number` | `true`  | 否   | `:checked-value="checkedValue"`     | —    |
+| `uncheckedValue` | `boolean \| string \| number` | `false` | 否   | `:unchecked-value="uncheckedValue"` | —    |
+| `checkedText`    | `string`                      | —       | 否   | `checked-text="开"`                 | —    |
+| `uncheckedText`  | `string`                      | —       | 否   | `unchecked-text="关"`               | —    |
+
+> 把 `$attrs` 透传给 `el-switch`，未列出的属性会继续下传
+
+**事件（emits）**
+
+| 事件                | 参数                          | 说明 |
+| ------------------- | ----------------------------- | ---- |
+| `update:modelValue` | `boolean \| string \| number` | —    |
+
+**插槽（slots）**
+
+| 插槽        | 作用域参数 | 示例                                | 说明 |
+| ----------- | ---------- | ----------------------------------- | ---- |
+| `checked`   | —          | `<template #checked>…</template>`   | —    |
+| `unchecked` | —          | `<template #unchecked>…</template>` | —    |
+
+**完整示例**：见 §7 表单与交互组件 › ZlDrawer / ZlPopconfirm / ZlSwitch
+
+#### `ZlTable`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlTable/index.vue`</sub>
+
+**简介**：自行 usePaginationRequest
+
+**接口概览**：6 props · 3 事件 · 3 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlTable } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlTable :columns="tableColumns" :data="tableData" :pagination="{ total: tableData.length }" />
+</template>
+```
+
+> 示例中的 `columns`、`data`、`pagination` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlTable>
+    <template #expand="scope">…</template>
+    <!-- 动态插槽：名字运行时取自 column.headerSlotName -->
+    <!-- 动态插槽：名字运行时取自 column.slotName -->
+  </ZlTable>
+</template>
+```
+
+**props**
+
+| 属性           | 类型                             | 默认值   | 必填 | 示例                 | 说明                                                                         |
+| -------------- | -------------------------------- | -------- | ---- | -------------------- | ---------------------------------------------------------------------------- |
+| `columns`      | `TableColumn[]`                  | —        | 是   | `:columns="columns"` | —                                                                            |
+| `data`         | `any[] \| Record<string, any>`   | —        | 是   | `:data="data"`       | 数组（本地数据）或 { [dataKey]: rows, pageNum, pageSize, total }（分页数据） |
+| `dataKey`      | `string`                         | `'rows'` | 否   | `data-key="rows"`    | —                                                                            |
+| `expandAction` | `boolean`                        | `false`  | 否   | `expand-action`      | actions 列宽加宽（参考实现 expandAction 语义）                               |
+| `pagination`   | `Record<string, any> \| boolean` | —        | 否   | `:pagination="{}"`   | —                                                                            |
+| `loading`      | `boolean`                        | `false`  | 否   | `loading`            | 表格 loading（作用于表格区）                                                 |
+
+> 把 `$attrs` 透传给 `el-table`，未列出的属性会继续下传
+
+**事件（emits）**
+
+| 事件                | 参数                                    | 说明 |
+| ------------------- | --------------------------------------- | ---- |
+| `pagination-change` | `{ pageNum: number; pageSize: number }` | —    |
+| `page-change`       | `number`                                | —    |
+| `page-size-change`  | `number`                                | —    |
+
+**插槽（slots）**
+
+| 插槽                      | 作用域参数            | 示例                                                      | 说明                         |
+| ------------------------- | --------------------- | --------------------------------------------------------- | ---------------------------- |
+| `expand`                  | `v-bind="scope"` 展开 | `<template #expand="scope">…</template>`                  | —                            |
+| `[column.headerSlotName]` | `v-bind="scope"` 展开 | `<template #[column.headerSlotName]="scope">…</template>` | 动态插槽：名字由该表达式决定 |
+| `[column.slotName]`       | `v-bind="scope"` 展开 | `<template #[column.slotName]="scope">…</template>`       | 动态插槽：名字由该表达式决定 |
+
+**完整示例**：见 §6 数据型组件 + useRequest 体系（核心） › ③ ZlTable + ZlPagination —— 自行 usePaginationRequest
+
+#### `ZlTabs`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlTabs/index.vue`</sub>
+
+**接口概览**：4 props · 3 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlTabs } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlTabs :tabs="tabs">
+    <template #a>页签 A 内容</template>
+    <template #b>页签 B 内容</template>
+  </ZlTabs>
+</template>
+```
+
+> 示例中的 `tabs` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlTabs>
+    <template #default>…</template>
+    <template #extra>…</template>
+    <!-- 动态插槽：名字运行时取自 key -->
+  </ZlTabs>
+</template>
+```
+
+**props**
+
+| 属性      | 类型      | 默认值     | 必填 | 示例                | 说明 |
+| --------- | --------- | ---------- | ---- | ------------------- | ---- |
+| `tabs`    | `any[]`   | `() => []` | 否   | `:tabs="[]"`        | —    |
+| `border`  | `boolean` | `true`     | 否   | `:border="false"`   | —    |
+| `fit`     | `boolean` | —          | 否   | `fit`               | —    |
+| `darkNav` | `boolean` | `true`     | 否   | `:dark-nav="false"` | —    |
+
+> 选项式组件（`defineComponent`），props 定义在 `props: {}` 中
+> 把 `$attrs` 透传给内部组件，未列出的属性会继续下传
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明                         |
+| --------- | ---------- | --------------------------------- | ---------------------------- |
+| `[key]`   | —          | `<template #[key]>…</template>`   | 动态插槽：名字由该表达式决定 |
+| `default` | —          | `<template #default>…</template>` | —                            |
+| `extra`   | —          | `<template #extra>…</template>`   | —                            |
+
+**完整示例**：见 §7 表单与交互组件 › ZlTabs / ZlDynamicComponent / ZlGrid
+
+#### `ZlTag`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlTag/index.vue`</sub>
+
+**简介**：标签
+
+**接口概览**：15 props · 4 事件 · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlTag } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlTag color="blue" bordered> blue 边框 </ZlTag>
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlTag>
+    <template #default>…</template>
+  </ZlTag>
+</template>
+```
+
+**props**
+
+| 属性              | 类型                            | 默认值      | 必填 | 示例                       | 说明 |
+| ----------------- | ------------------------------- | ----------- | ---- | -------------------------- | ---- |
+| `size`            | `'mini' \| 'small' \| 'medium'` | `undefined` | 否   | `size="mini"`              | —    |
+| `color`           | `string`                        | `undefined` | 否   | `color="#409eff"`          | —    |
+| `bordered`        | `boolean`                       | `false`     | 否   | `bordered`                 | —    |
+| `fill`            | `boolean`                       | `false`     | 否   | `fill`                     | —    |
+| `disabled`        | `boolean`                       | `false`     | 否   | `disabled`                 | —    |
+| `icon`            | `string`                        | `undefined` | 否   | `icon="zl:search"`         | —    |
+| `dotIcon`         | `boolean`                       | `false`     | 否   | `dot-icon`                 | —    |
+| `iconColor`       | `string`                        | `undefined` | 否   | `icon-color="#409eff"`     | —    |
+| `closable`        | `boolean`                       | `false`     | 否   | `closable`                 | —    |
+| `visible`         | `boolean \| undefined`          | `undefined` | 否   | `v-model:visible="value"`  | —    |
+| `defaultVisible`  | `boolean`                       | `true`      | 否   | `:default-visible="false"` | —    |
+| `selectable`      | `boolean`                       | `false`     | 否   | `selectable`               | —    |
+| `selected`        | `boolean \| undefined`          | `undefined` | 否   | `v-model:selected="value"` | —    |
+| `defaultSelected` | `boolean`                       | `false`     | 否   | `default-selected`         | —    |
+| `rounded`         | `boolean`                       | `false`     | 否   | `rounded`                  | —    |
+
+**事件（emits）**
+
+| 事件              | 参数         | 说明 |
+| ----------------- | ------------ | ---- |
+| `close`           | `MouseEvent` | —    |
+| `update:visible`  | `boolean`    | —    |
+| `update:selected` | `boolean`    | —    |
+| `select`          | `boolean`    | —    |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+
+**完整示例**：见 §5 通用展示组件 › ZlTag — 标签
+
+#### `ZlText`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlText/index.vue`</sub>
+
+**简介**：纯文本展示：默认渲染 `modelValue`，也可用默认插槽覆盖内容
+
+**接口概览**：1 props · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlText } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlText model-value="文本内容" />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlText>
+    <template #default>…</template>
+  </ZlText>
+</template>
+```
+
+**props**
+
+| 属性         | 类型                          | 默认值 | 必填 | 示例                        | 说明 |
+| ------------ | ----------------------------- | ------ | ---- | --------------------------- | ---- |
+| `modelValue` | `string \| number \| boolean` | —      | 否   | `:model-value="modelValue"` | —    |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+
+#### `ZlTitle`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlTitle/index.vue`</sub>
+
+**简介**：区块标题
+
+**接口概览**：5 props · 3 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlTitle } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlTitle title="页面标题" description="标题描述文案" tooltip="标题提示" />
+</template>
+```
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlTitle>
+    <template #default>…</template>
+    <template #description>…</template>
+    <template #extra>…</template>
+  </ZlTitle>
+</template>
+```
+
+**props**
+
+| 属性          | 类型                             | 默认值 | 必填 | 示例                   | 说明 |
+| ------------- | -------------------------------- | ------ | ---- | ---------------------- | ---- |
+| `title`       | `string`                         | —      | 否   | `title="标题"`         | —    |
+| `description` | `string`                         | —      | 否   | `description="副标题"` | —    |
+| `marker`      | `boolean`                        | `true` | 否   | `:marker="false"`      | —    |
+| `tooltip`     | `string`                         | —      | 否   | `tooltip="提示内容"`   | —    |
+| `size`        | `'small' \| 'medium' \| 'large'` | —      | 否   | `size="small"`         | —    |
+
+**插槽（slots）**
+
+| 插槽          | 作用域参数 | 示例                                  | 说明 |
+| ------------- | ---------- | ------------------------------------- | ---- |
+| `default`     | —          | `<template #default>…</template>`     | —    |
+| `description` | —          | `<template #description>…</template>` | —    |
+| `extra`       | —          | `<template #extra>…</template>`       | —    |
+
+**完整示例**：见 §5 通用展示组件 › ZlTitle — 区块标题
+
+#### `ZlUpload`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlUpload/index.vue`</sub>
+
+**简介**：传上传 service
+
+**接口概览**：11 props · 1 事件 · 1 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlUpload } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlUpload :request="mockUpload" accept=".png,.jpg,.pdf" :max-size="5" :limit="3" style="max-width: 420px" />
+</template>
+```
+
+> 示例中的 `request` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlUpload>
+    <template #default>…</template>
+  </ZlUpload>
+</template>
+```
+
+**props**
+
+| 属性                 | 类型                                                            | 默认值   | 必填 | 示例                                      | 说明                                         |
+| -------------------- | --------------------------------------------------------------- | -------- | ---- | ----------------------------------------- | -------------------------------------------- |
+| `request`            | `(form: FormData, config: Record<string, any>) => Promise<any>` | —        | 否   | `:request="async () => {}"`               | 自定义上传函数（form, config）→ Promise      |
+| `modelValue`         | `string \| any[]`                                               | `''`     | 否   | `v-model="value"`                         | `v-model` 绑定的值（`defineModel` 隐式声明） |
+| `accept`             | `string`                                                        | —        | 否   | `accept=".png,.jpg,.pdf"`                 | —                                            |
+| `maxSize`            | `number`                                                        | —        | 否   | `:max-size="1"`                           | 单文件大小上限（MB）                         |
+| `limit`              | `number`                                                        | —        | 否   | `:limit="1"`                              | —                                            |
+| `tip`                | `string`                                                        | —        | 否   | `tip="支持批量上传，单个文件不超过 10MB"` | —                                            |
+| `separator`          | `string`                                                        | `';'`    | 否   | `separator=","`                           | 多路径分隔符（modelValue 为字符串时）        |
+| `responseUrlKey`     | `string`                                                        | `'meta'` | 否   | `response-url-key="url"`                  | 响应中文件地址的取值键                       |
+| `showDownloadButton` | `boolean`                                                       | `true`   | 否   | `:show-download-button="false"`           | —                                            |
+| `showTip`            | `boolean`                                                       | `true`   | 否   | `:show-tip="false"`                       | —                                            |
+| `verifySpace`        | `boolean`                                                       | `false`  | 否   | `verify-space`                            | 校验文件名不得含空格                         |
+
+**事件（emits）**
+
+| 事件                | 参数  | 说明           |
+| ------------------- | ----- | -------------- |
+| `update:modelValue` | `any` | `v-model` 更新 |
+
+**插槽（slots）**
+
+| 插槽      | 作用域参数 | 示例                              | 说明 |
+| --------- | ---------- | --------------------------------- | ---- |
+| `default` | —          | `<template #default>…</template>` | —    |
+
+**完整示例**：见 §6 数据型组件 + useRequest 体系（核心） › ⑥ ZlUpload —— 传上传 service
+
+#### `ZlTree`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlTree/index.vue`</sub>
+
+**简介**：useRequest 绑定 data
+
+**接口概览**：5 props · 3 插槽
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlTree } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlTree :data="treeData" :field-names="fieldNames" />
+</template>
+```
+
+> 示例中的 `data`、`fieldNames` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**插槽用法**
+
+```vue
+<template>
+  <ZlTree>
+    <template #search-extra>…</template>
+    <template #title="{ node, data }">…</template>
+    <!-- 动态插槽：名字运行时取自 slot -->
+  </ZlTree>
+</template>
+```
+
+**props**
+
+| 属性               | 类型                                                  | 默认值                                                         | 必填 | 示例                           | 说明                                                    |
+| ------------------ | ----------------------------------------------------- | -------------------------------------------------------------- | ---- | ------------------------------ | ------------------------------------------------------- |
+| `fieldNames`       | `{ key?: string; title?: string; children?: string }` | `() => ({ key: 'key', title: 'title', children: 'children' })` | 否   | `:field-names="{}"`            | 字段映射（arco fieldNames 兼容：title→label、children） |
+| `inputSearchProps` | `Record<string, any>`                                 | —                                                              | 否   | `:input-search-props="{}"`     | 搜索框透传（el-input 属性）                             |
+| `filterTreeNode`   | `(value: string, data: any) => boolean`               | —                                                              | 否   | `:filter-tree-node="() => {}"` | 自定义过滤函数（缺省按 title 包含匹配）                 |
+| `disableFilter`    | `boolean`                                             | —                                                              | 否   | `disable-filter`               | 关闭搜索框                                              |
+| `loading`          | `boolean`                                             | —                                                              | 否   | `loading`                      | —                                                       |
+
+**插槽（slots）**
+
+| 插槽           | 作用域参数                     | 示例                                             | 说明                         |
+| -------------- | ------------------------------ | ------------------------------------------------ | ---------------------------- |
+| `search-extra` | —                              | `<template #search-extra>…</template>`           | —                            |
+| `title`        | `v-bind="{ node, data }"` 展开 | `<template #title="{ node, data }">…</template>` | —                            |
+| `[slot]`       | `v-bind="scope"` 展开          | `<template #[slot]="scope">…</template>`         | 动态插槽：名字由该表达式决定 |
+
+**完整示例**：见 §6 数据型组件 + useRequest 体系（核心） › ⑦ ZlTree —— useRequest 绑定 data
+
+#### `ZlTreeSelect`
+
+<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlTreeSelect/index.vue`</sub>
+
+**接口概览**：6 props · 1 事件
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlTreeSelect } from '@zl-ui-kit/components'
+</script>
+
+<template>
+  <ZlTreeSelect :origin-tree-data="treeData" v-model="value" />
+</template>
+```
+
+> 示例中的 `originTreeData` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**props**
+
+| 属性                | 类型                                                  | 默认值                                                         | 必填 | 示例                     | 说明                                             |
+| ------------------- | ----------------------------------------------------- | -------------------------------------------------------------- | ---- | ------------------------ | ------------------------------------------------ |
+| `modelValue`        | `any`                                                 | —                                                              | 否   | `v-model="value"`        | `v-model` 绑定的值（`defineModel` 隐式声明）     |
+| `originTreeData`    | `any[]`                                               | —                                                              | 是   | `:origin-tree-data="[]"` | 树数据                                           |
+| `allName`           | `string`                                              | —                                                              | 否   | `all-name="全部"`        | "全部"节点名（启用全选控制条）                   |
+| `labelInValue`      | `boolean`                                             | `false`                                                        | 否   | `label-in-value`         | 返回 {label, value} 对象数组（缺省返回键值数组） |
+| `fieldNames`        | `{ key?: string; title?: string; children?: string }` | `() => ({ key: 'key', title: 'title', children: 'children' })` | 否   | `:field-names="{}"`      | —                                                |
+| `treeCheckStrictly` | `boolean`                                             | `false`                                                        | 否   | `tree-check-strictly`    | 父子不关联                                       |
+
+> 把 `$attrs` 透传给 `el-tree-select`，未列出的属性会继续下传
+
+**事件（emits）**
+
+| 事件                | 参数  | 说明           |
+| ------------------- | ----- | -------------- |
+| `update:modelValue` | `any` | `v-model` 更新 |
+
+### 14.2 子路径入口组件（重型依赖，需单独安装）
+
+#### `ZlChart`
+
+<sub>入口 `@zl-ui-kit/components/chart` · 源码 `packages/components/src/components/ZlChart/index.vue` · ⚠️ 不在主入口，需从子路径 import，并自行安装对应 peer 依赖</sub>
+
+**简介**：useDataRequest 解包后构建 option
+
+**接口概览**：2 props · 1 暴露
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlChart } from '@zl-ui-kit/components/chart'
+</script>
+
+<template>
+  <ZlChart :series="series" :x-axis="xAxis" :y-axis="{ type: 'value' }" style="width: 520px; height: 260px" />
+</template>
+```
+
+> 示例中的 `series`、`xAxis`、`yAxis` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**props**
+
+| 属性     | 类型                                                | 默认值 | 必填 | 示例           | 说明                                                                                                             |
+| -------- | --------------------------------------------------- | ------ | ---- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `series` | `Record<string, any> \| Array<Record<string, any>>` | —      | 否   | `:series="{}"` | 系列（单对象或数组）；其余图表配置经 attrs 透传（title/xAxis/yAxis/tooltip 等，可用 src/utils/echarts 工具构造） |
+| `theme`  | `string`                                            | —      | 否   | `theme="dark"` | 主题名：先 `import 'echarts/theme/v5'` 之类注册主题，再传 `theme="v5"`。升级到 echarts 6 后想保持 v5 观感时用    |
+
+**暴露（defineExpose）**
+
+| 名称    | 说明 |
+| ------- | ---- |
+| `clear` | —    |
+
+**完整示例**：见 §6 数据型组件 + useRequest 体系（核心） › ⑧ ZlChart —— useDataRequest 解包后构建 option
+
+#### `ZlEditor`
+
+<sub>入口 `@zl-ui-kit/components/editor` · 源码 `packages/components/src/components/ZlEditor/index.vue` · ⚠️ 不在主入口，需从子路径 import，并自行安装对应 peer 依赖</sub>
+
+**简介**：monaco worker 配置与首屏治理
+
+**接口概览**：3 props · 1 事件
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlEditor } from '@zl-ui-kit/components/editor'
+</script>
+
+<template>
+  <ZlEditor language="javascript" v-model="value" />
+</template>
+```
+
+**props**
+
+| 属性         | 类型                  | 默认值         | 必填 | 示例                    | 说明                                         |
+| ------------ | --------------------- | -------------- | ---- | ----------------------- | -------------------------------------------- |
+| `modelValue` | `string`              | `''`           | 否   | `v-model="value"`       | `v-model` 绑定的值（`defineModel` 隐式声明） |
+| `language`   | `string`              | `'javascript'` | 否   | `language="javascript"` | —                                            |
+| `options`    | `Record<string, any>` | `() => ({})`   | 否   | `:options="{}"`         | —                                            |
+
+**事件（emits）**
+
+| 事件                | 参数     | 说明           |
+| ------------------- | -------- | -------------- |
+| `update:modelValue` | `string` | `v-model` 更新 |
+
+**完整示例**：见 §9 文件与编辑 › 9.1 ZlEditor：monaco worker 配置与首屏治理
+
+#### `ZlSqlEditor`
+
+<sub>入口 `@zl-ui-kit/components/editor` · 源码 `packages/components/src/components/ZlEditor/ZlSqlEditor.vue` · ⚠️ 不在主入口，需从子路径 import，并自行安装对应 peer 依赖</sub>
+
+**接口概览**：4 props · 1 事件
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlSqlEditor } from '@zl-ui-kit/components/editor'
+</script>
+
+<template>
+  <ZlSqlEditor v-model="value" />
+</template>
+```
+
+**props**
+
+| 属性              | 类型               | 默认值     | 必填 | 示例                            | 说明                                         |
+| ----------------- | ------------------ | ---------- | ---- | ------------------------------- | -------------------------------------------- |
+| `modelValue`      | `string`           | —          | 否   | `v-model="value"`               | `v-model` 绑定的值（`defineModel` 隐式声明） |
+| `tableSchemas`    | `SqlTableSchema[]` | `() => []` | 否   | `:table-schemas="tableSchemas"` | 表结构（补全提示）                           |
+| `customKeywords`  | `string[]`         | `() => []` | 否   | `:custom-keywords="[]"`         | —                                            |
+| `customFunctions` | `string[]`         | `() => []` | 否   | `:custom-functions="[]"`        | —                                            |
+
+> 把 `$attrs` 透传给 `ZlEditor`，未列出的属性会继续下传
+
+**事件（emits）**
+
+| 事件                | 参数     | 说明           |
+| ------------------- | -------- | -------------- |
+| `update:modelValue` | `string` | `v-model` 更新 |
+
+#### `ZlFilePreview`
+
+<sub>入口 `@zl-ui-kit/components/file-preview` · 源码 `packages/components/src/components/ZlFilePreview/index.vue` · ⚠️ 不在主入口，需从子路径 import，并自行安装对应 peer 依赖</sub>
+
+**接口概览**：1 props
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlFilePreview } from '@zl-ui-kit/components/file-preview'
+</script>
+
+<template>
+  <ZlFilePreview :url="inlineImage" />
+</template>
+```
+
+> 示例中的 `url` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**props**
+
+| 属性  | 类型     | 默认值 | 必填 | 示例                                 | 说明 |
+| ----- | -------- | ------ | ---- | ------------------------------------ | ---- |
+| `url` | `string` | —      | 否   | `url="https://example.com/file.pdf"` | —    |
+
+#### `ZlFileViewer`
+
+<sub>入口 `@zl-ui-kit/components/file-preview` · 源码 `packages/components/src/components/ZlFileViewer/index.vue` · ⚠️ 不在主入口，需从子路径 import，并自行安装对应 peer 依赖</sub>
+
+**接口概览**：1 props
+
+**用法示例**
+
+```vue
+<script setup lang="ts">
+import { ZlFileViewer } from '@zl-ui-kit/components/file-preview'
+</script>
+
+<template>
+  <ZlFileViewer :file-type="'image'" :src="inlineImage" style="width: 200px" />
+</template>
+```
+
+> 示例中的 `src` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+
+**props**
+
+| 属性       | 类型                                             | 默认值   | 必填 | 示例               | 说明 |
+| ---------- | ------------------------------------------------ | -------- | ---- | ------------------ | ---- |
+| `fileType` | `'word' \| 'pdf' \| 'excel' \| 'ppt' \| 'image'` | `'word'` | 否   | `file-type="word"` | —    |
+
+> 把 `$attrs` 透传给 `VueOfficePdf`，未列出的属性会继续下传
+
+### 14.3 公共类型声明（schema 用）
+
+> 这些类型从 `packages/components/src/index.ts` 导出，宿主的 `columns` / `schema` / `actions` 等入参都按它们书写。启用 `strict` 时可直接获得类型提示。
+
+#### `ActionItem`
+
+<sub>源码 `packages/components/src/components/ZlAction/types.ts`</sub>
+
+操作项模型（ZlActionList / ZlTable actions 列共用）
+
+| 字段         | 类型                          | 必填 | 说明                                                |
+| ------------ | ----------------------------- | ---- | --------------------------------------------------- |
+| `label`      | `string`                      | 是   | 操作文案                                            |
+| `icon`       | `string`                      | 否   | 图标（`zl:` 前缀走 ZlIcon，其余按 iconify/EP 规则） |
+| `iconProps`  | `Record<string, any>`         | 否   | 传给图标组件的 props                                |
+| `iconClass`  | `string`                      | 否   | 图标自定义类名                                      |
+| `tooltip`    | `boolean`                     | 否   | 是否用 tooltip 包住文案（文字过长时）               |
+| `disabled`   | `boolean`                     | 否   | 禁用（点击无响应）                                  |
+| `divided`    | `boolean`                     | 否   | 与下一项之间显示分割线                              |
+| `permission` | `string \| string[]`          | 否   | 权限键（三段式，经 usePermission 校验）             |
+| `visible`    | `(...args: any[]) => boolean` | 否   | 显隐判定（接收 visibleArgs）                        |
+| `handler`    | `(...args: any[]) => void`    | 否   | 点击处理（接收 actionArgs）                         |
+
+#### `IComponent`
+
+<sub>源码 `packages/components/src/components/ZlDynamicComponent/types.ts`</sub>
+
+| 字段        | 类型                                                                            | 必填 | 说明 |
+| ----------- | ------------------------------------------------------------------------------- | ---- | ---- |
+| `component` | `string \| any`                                                                 | 是   | —    |
+| `class`     | `string \| Record<string, boolean> \| Array<string \| Record<string, boolean>>` | 否   | —    |
+| `style`     | `string \| Record<string, boolean> \| Array<string \| Record<string, boolean>>` | 否   | —    |
+| `model`     | `string`                                                                        | 否   | —    |
+| `props`     | `Record<string, any>`                                                           | 否   | —    |
+| `domProps`  | `Record<string, any>`                                                           | 否   | —    |
+| `on`        | `Record<string, (...args: any[]) => any>`                                       | 否   | —    |
+| `nativeOn`  | `Record<string, (...args: any[]) => any>`                                       | 否   | —    |
+| `slots`     | `IComponentSlot[]`                                                              | 否   | —    |
+| `children`  | `string \| VNode \| Array<string \| VNode>`                                     | 否   | —    |
+| `refInFor`  | `boolean`                                                                       | 否   | —    |
+
+#### `IComponentSlot`
+
+<sub>源码 `packages/components/src/components/ZlDynamicComponent/types.ts`</sub>
+
+> 继承自 `IComponent`：下表只列自有字段，父类型字段同样可用。
+
+| 字段   | 类型     | 必填 | 说明 |
+| ------ | -------- | ---- | ---- |
+| `name` | `string` | 否   | —    |
+
+#### `VForSlot`
+
+<sub>源码 `packages/components/src/components/ZlDynamicComponent/types.ts`</sub>
+
+> 继承自 `IComponentSlot`：下表只列自有字段，父类型字段同样可用。
+
+| 字段   | 类型     | 必填 | 说明 |
+| ------ | -------- | ---- | ---- |
+| `type` | `'vFor'` | 是   | —    |
+| `data` | `Item[]` | 是   | —    |
+
+#### `VModelSlot`
+
+<sub>源码 `packages/components/src/components/ZlDynamicComponent/types.ts`</sub>
+
+> 继承自 `IComponentSlot`：下表只列自有字段，父类型字段同样可用。
+
+| 字段   | 类型       | 必填 | 说明 |
+| ------ | ---------- | ---- | ---- |
+| `type` | `'vModel'` | 是   | —    |
+
+#### `IGridItem`
+
+<sub>源码 `packages/components/src/components/ZlGrid/types.ts`</sub>
+
+ZlGrid 子项 schema
+
+| 字段       | 类型                                                                               | 必填 | 说明                                                                         |
+| ---------- | ---------------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------------------- |
+| `label`    | `string`                                                                           | 是   | 字段标签                                                                     |
+| `key`      | `string`                                                                           | 是   | 取值字段名（同时作为插槽名 `#key`）                                          |
+| `size`     | `number \| 'auto'`                                                                 | 否   | 跨列数（'auto' 占满剩余列）                                                  |
+| `getValue` | `(data: Record<string, any>, key: string, item: IGridItem) => any`                 | 否   | 自定义取值（缺省按 key 从 data 取）                                          |
+| `visible`  | `boolean \| ((value: unknown, key: string, data: Record<string, any>) => boolean)` | 否   | 显隐判定                                                                     |
+| `dict`     | `string \| { dictKey: string; simple?: boolean; showType?: boolean }`              | 否   | 字典：字典 key，或 `{ dictKey, simple, showType }` 配置（走 ZlDictTag 翻译） |
+| `slot`     | `boolean`                                                                          | 否   | 是否启用具名插槽（#key）渲染                                                 |
+| `ellipsis` | `number \| boolean`                                                                | 否   | 溢出省略行数（悬浮提示）                                                     |
+
+#### `TableColumn`
+
+<sub>源码 `packages/components/src/types.ts`</sub>
+
+表格列定义：label/prop(或 dataIndex)/slot/actions/columnSlot + el-table-column 其余属性
+
+| 字段          | 类型                  | 必填 | 说明                                               |
+| ------------- | --------------------- | ---- | -------------------------------------------------- |
+| `label`       | `string`              | 否   | 列标题（优先于 title）                             |
+| `title`       | `string`              | 否   | 列标题（兼容 arco/antd 写法，label 缺省时生效）    |
+| `prop`        | `string`              | 否   | 取值字段名（优先于 dataIndex）                     |
+| `dataIndex`   | `string`              | 否   | 取值字段名（兼容 arco/antd 写法，prop 缺省时生效） |
+| `slot`        | `string \| boolean`   | 否   | 单元格插槽名（缺省用 prop）                        |
+| `columnSlot`  | `boolean`             | 否   | 启用表头插槽（header-{prop}）                      |
+| `actions`     | `ActionItem[]`        | 否   | 操作列（渲染 ZlActionList）                        |
+| `actionProps` | `Record<string, any>` | 否   | 透传给操作列 ZlActionList 的 props                 |
+
+#### `FormItem`
+
+<sub>源码 `packages/components/src/types.ts`</sub>
+
+表单项 schema（ZlForm / ZlSearch 共用）
+
+| 字段            | 类型                                                                   | 必填 | 说明                                                |
+| --------------- | ---------------------------------------------------------------------- | ---- | --------------------------------------------------- |
+| `model`         | `string`                                                               | 是   | 字段名（必填）                                      |
+| `label`         | `string`                                                               | 否   | 标签文案（缺省用 model）                            |
+| `component`     | `string \| any`                                                        | 否   | 动态组件名/组件对象（如 'el-input'、ElSelect）      |
+| `props`         | `Record<string, any>`                                                  | 否   | 组件 props（自动包装 update:modelValue 回写 model） |
+| `slots`         | `Record<string, any>`                                                  | 否   | 组件插槽                                            |
+| `defaultValue`  | `any`                                                                  | 否   | 默认值                                              |
+| `slot`          | `boolean`                                                              | 否   | 是否启用具名插槽（#model）自定义渲染                |
+| `formItemProps` | `Record<string, any>`                                                  | 否   | el-form-item 其余属性（rules 等）                   |
+| `tooltip`       | `string`                                                               | 否   | 标签旁的问号提示文案                                |
+| `visible`       | `boolean \| ((model: Record<string, any>, item: FormItem) => boolean)` | 否   | 显隐控制：布尔值或判定函数                          |
+
+#### `SearchItem`
+
+<sub>源码 `packages/components/src/types.ts`</sub>
+
+搜索项 schema（ZlSearch / ZlSearchTable）
+
+> 继承自 `FormItem`：下表只列自有字段，父类型字段同样可用。
+
+| 字段       | 类型                                                            | 必填 | 说明                                   |
+| ---------- | --------------------------------------------------------------- | ---- | -------------------------------------- |
+| `toLabel`  | `(value: any) => any`                                           | 否   | 值 → 条件标签文本                      |
+| `toParams` | `(value: any, acc: Record<string, any>) => Record<string, any>` | 否   | 值 → 查询参数（返回对象合并入 params） |
+
+<!-- API:END -->