@zl-ui-kit/components 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +309 -162
  2. package/dist/components/ZlAddSub/index.css +1 -1
  3. package/dist/components/ZlAddSub/index.vue.mjs +2 -2
  4. package/dist/components/ZlAppMenu/AppMenu.vue.d.ts +1 -1
  5. package/dist/components/ZlCardPage/index.vue.d.ts +94 -36
  6. package/dist/components/ZlCardPage/index.vue.mjs +2 -0
  7. package/dist/components/ZlChart/index.vue.d.ts +1 -0
  8. package/dist/components/ZlChart/index.vue.mjs +1 -0
  9. package/dist/components/ZlCheckAll/index.css +1 -1
  10. package/dist/components/ZlCheckAll/index.vue.mjs +1 -1
  11. package/dist/components/ZlDynamicComponent/index.vue.d.ts +8 -3
  12. package/dist/components/ZlDynamicComponent/index.vue.mjs +24 -19
  13. package/dist/components/ZlEditor/ZlSqlEditor.vue.d.ts +28 -2
  14. package/dist/components/ZlEditor/ZlSqlEditor.vue.mjs +27 -18
  15. package/dist/components/ZlEditor/index.vue.d.ts +22 -1
  16. package/dist/components/ZlEditor/index.vue.mjs +47 -24
  17. package/dist/components/ZlForm/index.vue.d.ts +26 -2
  18. package/dist/components/ZlForm/index.vue.mjs +96 -90
  19. package/dist/components/ZlGrid/index.vue.d.ts +1 -1
  20. package/dist/components/ZlIcon/index.css +1 -1
  21. package/dist/components/ZlIcon/index.vue.d.ts +6 -2
  22. package/dist/components/ZlIcon/index.vue.mjs +2 -2
  23. package/dist/components/ZlIcon/index2.vue.mjs +30 -23
  24. package/dist/components/ZlPagination/index.css +1 -1
  25. package/dist/components/ZlPagination/index.vue.mjs +1 -1
  26. package/dist/components/ZlSearch/index.vue.d.ts +82 -23
  27. package/dist/components/ZlSearch/index.vue.mjs +8 -1
  28. package/dist/components/ZlSearchTable/index.vue.d.ts +180 -40
  29. package/dist/components/ZlSearchTable/index.vue.mjs +4 -0
  30. package/dist/components/ZlSorter/ZlSorterList.css +1 -1
  31. package/dist/components/ZlSorter/ZlSorterList.vue.d.ts +1 -1
  32. package/dist/components/ZlSorter/ZlSorterList.vue.mjs +2 -2
  33. package/dist/components/ZlSorter/index.css +1 -1
  34. package/dist/components/ZlSorter/index.vue.mjs +2 -2
  35. package/dist/components/ZlSwitch/index.vue.d.ts +6 -2
  36. package/dist/components/ZlSwitch/index.vue.mjs +26 -24
  37. package/dist/components/ZlTable/index.vue.d.ts +36 -1
  38. package/dist/components/ZlTable/index.vue.mjs +98 -75
  39. package/dist/components/ZlTabs/index.vue.d.ts +20 -3
  40. package/dist/components/ZlTabs/index.vue.mjs +30 -20
  41. package/dist/components/ZlTag/index.vue.d.ts +2 -2
  42. package/package.json +6 -6
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @zl-ui-kit/components
2
2
 
3
- ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，47 个业务组件；配 `@zl-ui-kit/composables`（`useRequest` / `useDict`）、`@zl-ui-kit/theme`、`@zl-ui-kit/utils`、`@zl-ui-kit/icons` 使用。
3
+ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，55 个业务组件（含国际化根容器共 56 个对外组件）；配 `@zl-ui-kit/composables`（`useRequest` / `useDict`）、`@zl-ui-kit/theme`、`@zl-ui-kit/utils`、`@zl-ui-kit/icons` 使用。
4
4
 
5
- **本页即完整使用文档**：安装与四个导入入口、47 个组件用法、`useRequest` 请求体系与 Mock 联调、主题定制（L1/L2）、国际化接入、公共 Hooks 与 Utils —— 全部都在这一页。
5
+ **本页即完整使用文档**：安装与四个导入入口、55 个组件用法、`useRequest` 请求体系与 Mock 联调、主题定制（L1/L2）、国际化接入、公共 Hooks 与 Utils —— 全部都在这一页。
6
6
 
7
7
  > 本文档即 UI 组件的**权威文档**，直接在本文件维护；npm 官网包页面渲染的就是它，改完随下一次发版对外生效。
8
8
 
@@ -18,13 +18,13 @@ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，47 个业务组
18
18
  - [2.2 启动 playground（组件示例与联调）](#22-启动-playground组件示例与联调)
19
19
  - [2.3 主题快速接入（宿主项目）](#23-主题快速接入宿主项目)
20
20
  - [2.4 示例页面索引](#24-示例页面索引)
21
- - [3. 组件总览（47 个业务组件）](#3-组件总览47-个业务组件)
21
+ - [3. 组件总览（55 个业务组件）](#3-组件总览55-个业务组件)
22
22
  - [3.1 通用展示组件](#31-通用展示组件)
23
23
  - [3.2 数据型组件](#32-数据型组件)
24
24
  - [3.3 表单与交互组件](#33-表单与交互组件)
25
25
  - [3.4 布局与权限](#34-布局与权限)
26
26
  - [3.5 文件与编辑](#35-文件与编辑)
27
- - [3.6 国际化基础设施（独立于 47 个业务组件）](#36-国际化基础设施独立于-47-个业务组件)
27
+ - [3.6 国际化基础设施（独立于 55 个业务组件）](#36-国际化基础设施独立于-55-个业务组件)
28
28
  - [3.7 内部子组件（不对外导出，随父组件使用）](#37-内部子组件不对外导出随父组件使用)
29
29
  - [4. 图标组件 `ZlIcon`](#4-图标组件-zlicon)
30
30
  - [4.1 必须先注册图标集（否则一个图标都不显示）](#41-必须先注册图标集否则一个图标都不显示)
@@ -88,6 +88,7 @@ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，47 个业务组
88
88
  - [15.2 常用 el-* → Zl-* 对照表（持续补充）](#152-常用-el--zl--对照表持续补充)
89
89
  - [15.3 列表页操作按钮归位（search-actions 插槽）](#153-列表页操作按钮归位search-actions-插槽)
90
90
  - [15.4 宿主工具方法 → `@zl-ui-kit/utils` 替换对照（持续补充）](#154-宿主工具方法-zl-ui-kitutils-替换对照持续补充)
91
+ - [15.5 迁移行为差异与透传契约（必读）](#155-迁移行为差异与透传契约必读)
91
92
 
92
93
  <!-- TOC:END -->
93
94
 
@@ -99,9 +100,9 @@ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，47 个业务组
99
100
 
100
101
  | 包 | 职责 |
101
102
  | -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
102
- | [`@zl-ui-kit/components`](https://www.npmjs.com/package/@zl-ui-kit/components) | EP 化业务组件库（`Zl` 前缀，47 个组件） |
103
+ | [`@zl-ui-kit/components`](https://www.npmjs.com/package/@zl-ui-kit/components) | EP 化业务组件库（`Zl` 前缀，55 个业务组件） |
103
104
  | [`@zl-ui-kit/composables`](https://www.npmjs.com/package/@zl-ui-kit/composables) | `useRequest` 请求体系、`useDict`、`useGlobalData` 全局数据、国际化 |
104
- | [`@zl-ui-kit/icons`](https://www.npmjs.com/package/@zl-ui-kit/icons) | 444 个离线 SVG 图标（prefix `zl`，开源图标库） |
105
+ | [`@zl-ui-kit/icons`](https://www.npmjs.com/package/@zl-ui-kit/icons) | 470 个离线 SVG 图标（prefix `zl`，开源图标库） |
105
106
  | [`@zl-ui-kit/theme`](https://www.npmjs.com/package/@zl-ui-kit/theme) | 5 套主题 + `defineTheme` 运行时定制（内置 OFL 开源中文字体） |
106
107
  | [`@zl-ui-kit/utils`](https://www.npmjs.com/package/@zl-ui-kit/utils) | TS 工具函数库 + Axios 请求封装 |
107
108
 
@@ -301,11 +302,11 @@ import { ZlI18nProvider } from '@zl-ui-kit/components'
301
302
 
302
303
  #### 1.2.3 组件注册的三种方式（以及 EP 的坑）
303
304
 
304
- | 方式 | 写法 | 适用 |
305
- | ----------- | --------------------------------------------------------------------- | --------------------------------------- |
306
- | 全量插件 | `app.use(ZlUI)` | 业务项目首选，47 个组件全注册，一次搞定 |
307
- | 按名注册 | `app.component('ZlTable', ZlTable)` | 只要几个组件，控制产物 |
308
- | 直接 import | `<script setup>` 里 `import { ZlTable } from '@zl-ui-kit/components'` | 单文件用一次，无需全局 |
305
+ | 方式 | 写法 | 适用 |
306
+ | ----------- | --------------------------------------------------------------------- | ---------------------------------------------- |
307
+ | 全量插件 | `app.use(ZlUI)` | 业务项目首选，主入口 51 个组件全注册，一次搞定 |
308
+ | 按名注册 | `app.component('ZlTable', ZlTable)` | 只要几个组件，控制产物 |
309
+ | 直接 import | `<script setup>` 里 `import { ZlTable } from '@zl-ui-kit/components'` | 单文件用一次，无需全局 |
309
310
 
310
311
  > ⚠️ **不管用哪种，Element Plus 的组件都必须能被「按名」解析到。**
311
312
  > `@zl-ui-kit/components` 发布的是**编译后的 render 函数**，内部用 `resolveComponent('el-select')` 之类按名取组件，**不是模板**。所以 `unplugin-vue-components` 的 ElementPlusResolver **改不到它**（那个插件只处理源码里的模板标签）。
@@ -422,9 +423,9 @@ setTheme('dark') // 切换主题（light/dark/red-light/red-dark/blue）
422
423
 
423
424
  ---
424
425
 
425
- ## 3. 组件总览（47 个业务组件）
426
+ ## 3. 组件总览（55 个业务组件）
426
427
 
427
- > 下面按功能分组，列出的是**导出符号**（含同目录变体，如 `ZlCornerTag` / `ZlIconHover` / `ZlActionList`），所以条目数略多于 47；组件目录共 48 个（47 个业务组件 + `ZlI18nProvider`）。
428
+ > 口径：主入口 `@zl-ui-kit/components` 导出 **51 个**组件，另有 **5 个**重型组件走子路径入口（`/chart`、`/editor`、`/file-preview`），合计 **56 个对外组件**（§14 逐条覆盖这 56 个）；其中 `ZlI18nProvider` 是国际化基础设施，故**业务组件为 55 个**（playground 的 `/gallery` 逐个渲染的就是这 55 个）。组件目录共 48 个（一个目录可产出多个导出符号，如 `ZlTag` 目录同时产出 `ZlTag` / `ZlCornerTag`）。§3.1~§3.5 按功能分组列出业务组件，其中混列了 4 个**不对外导出**的内部子组件（`ZlHorizontalLayout` / `ZlVerticalLayout` / `ZlAppMenuItem` / `ZlFileFetchError`，见 §3.7），去掉这 4 个后正好 55 个。
428
429
 
429
430
  > **要查精确的 props / 事件 / 插槽 / 暴露方法 / schema 类型？** 直接看 **[§14 组件 API 参考](#14-组件-api-参考自动生成)**——逐个组件给出 `import`、可直接照抄的 **用法示例**（props 怎么写）与 **插槽用法**（`<template #name>` 怎么写），再用表格列出 TS 类型表达式、默认值、是否必填，**且每个 prop / 每个插槽都带一列「示例」**（能直接粘到标签上的写法），以及 `TableColumn` / `FormItem` / `SearchItem` / `ActionItem` 等 schema 类型的字段表。本章及 §4~§9 讲的是**场景化用法**，§14 是**逐字段的契约 + 可粘贴代码**。
430
431
 
@@ -446,11 +447,11 @@ setTheme('dark') // 切换主题（light/dark/red-light/red-dark/blue）
446
447
 
447
448
  ### 3.5 文件与编辑
448
449
 
449
- `ZlFilePreview` · `ZlFileFetchError` · `ZlFileViewer` · `ZlPdfViewer` · `ZlEditor` · `ZlSqlEditor` · `ZlLogin`
450
+ `ZlFilePreview` · `ZlFileFetchError` · `ZlFileViewer` · `ZlPdfViewer` · `ZlEditor` · `ZlSqlEditor` · `ZlLogin` · `ZlLoginForm`
450
451
 
451
452
  > 页签/微前端类组件（`ZlMicroPage`/`ZlAppTabs`/`ZlPageTabs`/`ZlDevMenu`）与配套 composables（`usePageTabs` 等）均已移除，`0.5.0` 起组件库不含任何微前端能力。
452
453
 
453
- ### 3.6 国际化基础设施（独立于 47 个业务组件）
454
+ ### 3.6 国际化基础设施（独立于 55 个业务组件）
454
455
 
455
456
  `ZlI18nProvider` —— 国际化根容器，将 Element Plus 语言包经 `<el-config-provider>` 挂载到 Element Plus（详见第 13 章）。
456
457
 
@@ -474,15 +475,17 @@ setTheme('dark') // 切换主题（light/dark/red-light/red-dark/blue）
474
475
 
475
476
  #### `ZlHorizontalLayout` / `ZlVerticalLayout` —— 布局形态（供 `ZlAppLayout` 分发）
476
477
 
477
- 由 `ZlAppLayout` 的 `horizontal` 布尔值二选一渲染，不单独使用。插槽用法（写在 `ZlAppLayout` 标签内）：
478
+ 由 `ZlAppLayout` 的 `layout`（`'horizontal'`（默认）/ `'vertical'`）二选一渲染，不单独使用。
479
+ `ZlAppLayout` **只声明 `layout` 一个 prop**，插槽一律写在 `ZlAppLayout` 标签内；菜单数据自己传给 `#menu` 里的
480
+ `ZlAppMenu`（传 `:menus` 给 `ZlAppLayout` 是无效的——它不声明该 prop）：
478
481
 
479
482
  ```vue
480
- <ZlAppLayout :menus="menus" :horizontal="true">
483
+ <ZlAppLayout layout="vertical">
481
484
  <template #logo>
482
485
  <img src="/logo.svg" />
483
486
  </template>
484
487
  <template #menu>
485
- <!-- horizontal 形态下自行放菜单 -->
488
+ <!-- 各形态自行放菜单，如 <ZlAppMenu :menus="menus" /> -->
486
489
  </template>
487
490
  <template #breadcrumb>
488
491
  <el-breadcrumb />
@@ -522,22 +525,26 @@ vertical 形态的 `logo` / `menu` 插槽会收到 `{ collapsed }`，可据此
522
525
 
523
526
  ## 4. 图标组件 `ZlIcon`
524
527
 
525
- 底层为 `@iconify/vue` 离线渲染，图标名以 `zl:` 前缀引用，全部来自内置的 444 个开源图标。
528
+ 底层为 `@iconify/vue` 离线渲染，图标名以 `zl:` 前缀引用，全部来自内置的 470 个开源图标。
526
529
 
527
530
  ```vue
528
531
  <ZlIcon icon="zl:add-color" />
529
532
  <ZlIcon icon="zl:database-color" :size="20" />
533
+ <ZlIcon icon="zl:refresh" color="var(--zl-primary)" spin />
530
534
  ```
531
535
 
532
- | prop | 说明 |
533
- | ------------------- | -------------------------------------------------------------------------------------- |
534
- | `icon` | 图标名，支持 `zl:xxx`（内置）、`https://...`（外链）、普通名（iconify 在线集，需联网） |
535
- | `size` | 字号/尺寸，默认 `14px` |
536
- | `color` / `spin` 等 | 透传至底层 iconify-icon |
536
+ | prop | 说明 |
537
+ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
538
+ | `icon` | 图标名，支持 `zl:xxx`（内置）、`https://...`（外链）、普通名（iconify 在线集，需联网） |
539
+ | `size` | 尺寸，作用在容器的 `font-size` 上（数字按 `px` 处理），图标本体按 `1em` 缩放；不传时默认 `14px` |
540
+ | `color` | 颜色，不传时继承当前文字色（`currentColor`） |
541
+ | 其余属性 | 透传给真正渲染的图标元素：`zl:` 前缀走 `<iconify-icon>`，因此 `spin` / `rotate` / `flip` 等 iconify 属性直接生效；外链与本地 sprite 分支只响应 `size` / `color`（无 `spin` 能力） |
542
+
543
+ > 三种渲染模式（iconify / 外链 mask / 本地 sprite）都是单色图标：外链模式用 `mask` + `background-color: currentColor`，本地 sprite 用 `fill: currentColor`，所以改 `color` 就能变色，不需要多色图标集。
537
544
 
538
545
  ### 4.1 必须先注册图标集（否则一个图标都不显示）
539
546
 
540
- `ZlIcon` 走 `@iconify/vue/offline`，**库不会自动把 444 个图标塞进打包结果**（否则不用图标的宿主也会白扛 ~150KB）。
547
+ `ZlIcon` 走 `@iconify/vue/offline`，**库不会自动把 470 个图标塞进打包结果**（否则不用图标的宿主也会白扛 ~150KB）。
541
548
  消费方需要在应用启动时把内置图标集注册进 offline 集合，只需一次：
542
549
 
543
550
  ```ts
@@ -1146,7 +1153,8 @@ treeRef.value.getCheckedKeys(true)
1146
1153
 
1147
1154
  ### ZlAppLayout / ZlAppMenu
1148
1155
 
1149
- - `ZlAppLayout`：horizontal/vertical 双形态布局骨架，折叠按钮 `el-button circle`。
1156
+ - `ZlAppLayout`：双形态布局骨架，用 `layout="horizontal" | "vertical"` 选形态（默认 `horizontal`），
1157
+ 插槽为 `logo` / `menu` / `header` / `breadcrumb` / `footer` / 默认（详见 §3.7），vertical 形态自带折叠按钮（`el-button circle`）。
1150
1158
  - `ZlAppMenu`(+Item)：`el-menu` 重写（index=menu.name），主题经 `--zl-menu-*` CSS 变量对接 `--el-menu-*`。
1151
1159
 
1152
1160
  ### ZlPermission
@@ -1163,6 +1171,10 @@ treeRef.value.getCheckedKeys(true)
1163
1171
 
1164
1172
  - `ZlFilePreview` / `ZlFileViewer` / `ZlPdfViewer`：文件预览（含 PDF），样例见 `/general`。
1165
1173
  - `ZlEditor` / `ZlSqlEditor`(+`useSqlCompletion`)：富文本 / SQL 编辑器。
1174
+ 通过 `ref` 调 API：常用能力已显式暴露（`getValue` / `setValue` / `getModel` / `getSelection` / `revealLine` /
1175
+ `focus` / `layout` / `updateOptions` / `dispose`；`ZlSqlEditor` 另有 `validate`（**校验不通过会 `throw diagnostics`**，调用方需 catch）
1176
+ 与 `format`）；需要未列出的 monaco 原生 API 时，用 `editorRef.value.monacoEditor`（`ZlSqlEditor` 用 `.zlEditor`）
1177
+ 拿实例后直接调用，不要直接写未列出的键（旧版本靠 Proxy 下钻能调，但那不是契约，见 §15.5）。
1166
1178
  - `ZlLogin`(+`LoginForm`+`SlideChecker`)：登录框，背景改半透明 + `backdrop-filter`。
1167
1179
 
1168
1180
  ### 9.1 `ZlEditor`：monaco worker 配置与首屏治理
@@ -3165,7 +3177,7 @@ const { i18n } = useLocale({ messages })
3165
3177
  | [`ZlAction`](#zlaction) | 主入口 | 0 | 0 | 0 | 0 |
3166
3178
  | [`ZlActionList`](#zlactionlist) | 主入口 | 6 | 1 | 1 | 0 |
3167
3179
  | [`ZlAddSub`](#zladdsub) | 主入口 | 2 | 1 | 1 | 0 |
3168
- | [`ZlAppLayout`](#zlapplayout) | 主入口 | 1 | 0 | 1 | 0 |
3180
+ | [`ZlAppLayout`](#zlapplayout) | 主入口 | 1 | 0 | 8 | 0 |
3169
3181
  | [`ZlAppMenu`](#zlappmenu) | 主入口 | 3 | 1 | 0 | 0 |
3170
3182
  | [`ZlAppSlogan`](#zlappslogan) | 主入口 | 3 | 0 | 0 | 0 |
3171
3183
  | [`ZlAutoTooltip`](#zlautotooltip) | 主入口 | 0 | 0 | 1 | 0 |
@@ -3184,12 +3196,12 @@ const { i18n } = useLocale({ messages })
3184
3196
  | [`ZlLogin`](#zllogin) | 主入口 | 2 | 0 | 2 | 0 |
3185
3197
  | [`ZlLoginForm`](#zlloginform) | 主入口 | 1 | 0 | 1 | 0 |
3186
3198
  | [`ZlEmpty`](#zlempty) | 主入口 | 2 | 0 | 0 | 0 |
3187
- | [`ZlForm`](#zlform) | 主入口 | 2 | 0 | 3 | 0 |
3199
+ | [`ZlForm`](#zlform) | 主入口 | 2 | 0 | 3 | 9 |
3188
3200
  | [`ZlFormChild`](#zlformchild) | 主入口 | 1 | 0 | 0 | 0 |
3189
3201
  | [`ZlGridItem`](#zlgriditem) | 主入口 | 1 | 0 | 1 | 0 |
3190
3202
  | [`ZlGrid`](#zlgrid) | 主入口 | 9 | 0 | 2 | 0 |
3191
3203
  | [`ZlHorizontalTable`](#zlhorizontaltable) | 主入口 | 4 | 0 | 1 | 0 |
3192
- | [`ZlIcon`](#zlicon) | 主入口 | 1 | 0 | 1 | 0 |
3204
+ | [`ZlIcon`](#zlicon) | 主入口 | 3 | 0 | 1 | 0 |
3193
3205
  | [`ZlI18nProvider`](#zli18nprovider) | 主入口 | 0 | 0 | 1 | 0 |
3194
3206
  | [`ZlIconHover`](#zliconhover) | 主入口 | 0 | 0 | 0 | 0 |
3195
3207
  | [`ZlIconLabel`](#zliconlabel) | 主入口 | 1 | 1 | 1 | 0 |
@@ -3204,9 +3216,9 @@ const { i18n } = useLocale({ messages })
3204
3216
  | [`ZlSection`](#zlsection) | 主入口 | 4 | 0 | 3 | 0 |
3205
3217
  | [`ZlSorter`](#zlsorter) | 主入口 | 2 | 2 | 1 | 0 |
3206
3218
  | [`ZlSorterList`](#zlsorterlist) | 主入口 | 2 | 1 | 0 | 0 |
3207
- | [`ZlSwitch`](#zlswitch) | 主入口 | 6 | 1 | 2 | 0 |
3208
- | [`ZlTable`](#zltable) | 主入口 | 6 | 3 | 3 | 0 |
3209
- | [`ZlTabs`](#zltabs) | 主入口 | 4 | 0 | 3 | 0 |
3219
+ | [`ZlSwitch`](#zlswitch) | 主入口 | 8 | 2 | 2 | 0 |
3220
+ | [`ZlTable`](#zltable) | 主入口 | 6 | 3 | 3 | 16 |
3221
+ | [`ZlTabs`](#zltabs) | 主入口 | 5 | 1 | 3 | 0 |
3210
3222
  | [`ZlTag`](#zltag) | 主入口 | 15 | 4 | 1 | 0 |
3211
3223
  | [`ZlText`](#zltext) | 主入口 | 1 | 0 | 1 | 0 |
3212
3224
  | [`ZlTitle`](#zltitle) | 主入口 | 5 | 0 | 3 | 0 |
@@ -3214,8 +3226,8 @@ const { i18n } = useLocale({ messages })
3214
3226
  | [`ZlTree`](#zltree) | 主入口 | 10 | 2 | 5 | 23 |
3215
3227
  | [`ZlTreeSelect`](#zltreeselect) | 主入口 | 6 | 1 | 0 | 0 |
3216
3228
  | [`ZlChart`](#zlchart) | 子入口 chart | 2 | 0 | 0 | 1 |
3217
- | [`ZlEditor`](#zleditor) | 子入口 editor | 3 | 1 | 0 | 0 |
3218
- | [`ZlSqlEditor`](#zlsqleditor) | 子入口 editor | 4 | 1 | 0 | 0 |
3229
+ | [`ZlEditor`](#zleditor) | 子入口 editor | 3 | 1 | 0 | 10 |
3230
+ | [`ZlSqlEditor`](#zlsqleditor) | 子入口 editor | 4 | 1 | 0 | 3 |
3219
3231
  | [`ZlFilePreview`](#zlfilepreview) | 子入口 file-preview | 1 | 0 | 0 | 0 |
3220
3232
  | [`ZlFileViewer`](#zlfileviewer) | 子入口 file-preview | 1 | 0 | 0 | 0 |
3221
3233
 
@@ -3282,9 +3294,9 @@ import { ZlActionList } from '@zl-ui-kit/components'
3282
3294
 
3283
3295
  **事件（emits）**
3284
3296
 
3285
- | 事件 | 参数 | 说明 |
3286
- | -------- | ------------------- | ---- |
3287
- | `action` | `ActionItem, any[]` | — |
3297
+ | 事件 | 参数 | 说明 |
3298
+ | -------- | ------------------- | ---------------------------------------------------------------------------------------------- |
3299
+ | `action` | `ActionItem, any[]` | 点击（或从「更多」下拉选中）某个操作项时触发，参数为被选中的 `ActionItem` 与其后透传的调用参数 |
3288
3300
 
3289
3301
  **插槽（slots）**
3290
3302
 
@@ -3331,9 +3343,9 @@ import { ZlAddSub } from '@zl-ui-kit/components'
3331
3343
 
3332
3344
  **事件（emits）**
3333
3345
 
3334
- | 事件 | 参数 | 说明 |
3335
- | -------------- | ------- | ---- |
3336
- | `update:model` | `any[]` | — |
3346
+ | 事件 | 参数 | 说明 |
3347
+ | -------------- | ------- | ------------------------------------------ |
3348
+ | `update:model` | `any[]` | `v-model:model` 更新，参数为变化后的整组值 |
3337
3349
 
3338
3350
  **插槽（slots）**
3339
3351
 
@@ -3345,7 +3357,7 @@ import { ZlAddSub } from '@zl-ui-kit/components'
3345
3357
 
3346
3358
  <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAppLayout/index.vue`</sub>
3347
3359
 
3348
- **接口概览**：1 props · 1 插槽
3360
+ **接口概览**：1 props · 8 插槽
3349
3361
 
3350
3362
  **用法示例**
3351
3363
 
@@ -3365,6 +3377,13 @@ import { ZlAppLayout } from '@zl-ui-kit/components'
3365
3377
  <template>
3366
3378
  <ZlAppLayout>
3367
3379
  <template #default>…</template>
3380
+ <template #logo>…</template>
3381
+ <template #menu>…</template>
3382
+ <template #header>…</template>
3383
+ <template #breadcrumb>…</template>
3384
+ <template #logo="{ collapsed }">…</template>
3385
+ <template #menu="{ collapsed }">…</template>
3386
+ <template #footer>…</template>
3368
3387
  </ZlAppLayout>
3369
3388
  </template>
3370
3389
  ```
@@ -3377,12 +3396,20 @@ import { ZlAppLayout } from '@zl-ui-kit/components'
3377
3396
 
3378
3397
  > 选项式组件（`defineComponent`），props 定义在 `props: {}` 中
3379
3398
  > 把 `$attrs` 透传给内部组件，未列出的属性会继续下传
3399
+ > 本组件是**分发器**：插槽由同目录子组件定义，同名插槽在不同形态下的作用域与是否存在可能不同
3380
3400
 
3381
3401
  **插槽（slots）**
3382
3402
 
3383
- | 插槽 | 作用域参数 | 示例 | 说明 |
3384
- | --------- | ---------- | --------------------------------- | ------------------------------------------- |
3385
- | `default` | — | `<template #default>…</template>` | 整个 `slots` 对象原样透传，插槽由子组件决定 |
3403
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3404
+ | ------------ | ----------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |
3405
+ | `default` | — | `<template #default>…</template>` | 整个 `slots` 对象原样透传，插槽由子组件决定 |
3406
+ | `logo` | — | `<template #logo>…</template>` | 顶栏左侧 logo 区（不写则整块不渲染） |
3407
+ | `menu` | — | `<template #menu>…</template>` | 顶栏中部菜单区（横向形态下占满剩余宽度） |
3408
+ | `header` | — | `<template #header>…</template>` | 顶栏右侧用户 / 操作区 |
3409
+ | `breadcrumb` | — | `<template #breadcrumb>…</template>` | 主区上方的面包屑 / 页签区 |
3410
+ | `logo` | `v-bind="{ collapsed }"` 展开 | `<template #logo="{ collapsed }">…</template>` | 侧栏顶部 logo 区（纵向形态下作用域带 `{ collapsed }`，可据此在折叠态隐去文字） |
3411
+ | `menu` | `v-bind="{ collapsed }"` 展开 | `<template #menu="{ collapsed }">…</template>` | 侧栏菜单区（作用域带 `{ collapsed }`） |
3412
+ | `footer` | — | `<template #footer>…</template>` | 侧栏底部区（排在内置折叠按钮之后，仅纵向形态有） |
3386
3413
 
3387
3414
  #### `ZlAppMenu`
3388
3415
 
@@ -3414,9 +3441,9 @@ import { ZlAppMenu } from '@zl-ui-kit/components'
3414
3441
 
3415
3442
  **事件（emits）**
3416
3443
 
3417
- | 事件 | 参数 | 说明 |
3418
- | ----------------- | ---------- | ---- |
3419
- | `menu-item-click` | `MenuItem` | — |
3444
+ | 事件 | 参数 | 说明 |
3445
+ | ----------------- | ---------- | ---------------------------------------------------------- |
3446
+ | `menu-item-click` | `MenuItem` | 点击菜单项时触发，参数为被点击的菜单项配置（子项冒泡上来） |
3420
3447
 
3421
3448
  #### `ZlAppSlogan`
3422
3449
 
@@ -3640,9 +3667,9 @@ import { ZlCardPage } from '@zl-ui-kit/components'
3640
3667
 
3641
3668
  **事件（emits）**
3642
3669
 
3643
- | 事件 | 参数 | 说明 |
3644
- | -------------- | ---- | ---- |
3645
- | `search-reset` | — | — |
3670
+ | 事件 | 参数 | 说明 |
3671
+ | -------------- | ---- | ---------------------------------------------------------- |
3672
+ | `search-reset` | — | 查询区重置时触发（此时表单已清空，随后会自动发起一次查询） |
3646
3673
 
3647
3674
  **插槽（slots）**
3648
3675
 
@@ -3654,11 +3681,11 @@ import { ZlCardPage } from '@zl-ui-kit/components'
3654
3681
 
3655
3682
  **暴露（defineExpose）**
3656
3683
 
3657
- | 名称 | 说明 |
3658
- | --------- | ------------------------------------------------------------------------ |
3659
- | `refresh` | — |
3660
- | `params` | — |
3661
- | `search` | 重新查询并回到第 1 页；消费方可在 useRequest 的 refreshDepsAction 里调用 |
3684
+ | 名称 | 说明 |
3685
+ | --------- | ------------------------------------------------------------------------------------ |
3686
+ | `refresh` | 原地重查：用最近一次入参重新请求，保持当前页码（区别于 `search()` 会回到第 1 页） |
3687
+ | `params` | 最近一次请求的入参（`{ pageNum, pageSize, ...查询表单 }`），未请求过时为 `undefined` |
3688
+ | `search` | 重新查询并回到第 1 页；消费方可在 useRequest 的 refreshDepsAction 里调用 |
3662
3689
 
3663
3690
  #### `ZlCheckAll`
3664
3691
 
@@ -3691,9 +3718,9 @@ import { ZlCheckAll } from '@zl-ui-kit/components'
3691
3718
 
3692
3719
  **事件（emits）**
3693
3720
 
3694
- | 事件 | 参数 | 说明 |
3695
- | -------------- | ------------------------- | ---- |
3696
- | `update:model` | `Array<string \| number>` | — |
3721
+ | 事件 | 参数 | 说明 |
3722
+ | -------------- | ------------------------- | --------------------------------------------------- |
3723
+ | `update:model` | `Array<string \| number>` | `v-model:model` 更新，参数为当前已勾选的 value 集合 |
3697
3724
 
3698
3725
  #### `ZlCheckboxTag`
3699
3726
 
@@ -3910,6 +3937,8 @@ import { ZlDrawer } from '@zl-ui-kit/components'
3910
3937
  | `readonly` | `boolean` | — | 否 | `readonly` | 只读模式：隐藏取消按钮，只留「关闭」 |
3911
3938
  | `loading` | `boolean` | — | 否 | `loading` | 内容区加载态，为 true 时显示遮罩 loading |
3912
3939
 
3940
+ > 把未声明的入参与事件（`useAttrs()`）透传给 `el-drawer`，未列出的属性会继续下传
3941
+
3913
3942
  **事件（emits）**
3914
3943
 
3915
3944
  | 事件 | 参数 | 说明 |
@@ -3955,10 +3984,10 @@ import { ZlDynamicComponent } from '@zl-ui-kit/components'
3955
3984
 
3956
3985
  **事件（emits）**
3957
3986
 
3958
- | 事件 | 参数 | 说明 |
3959
- | ------------------- | ---- | ---- |
3960
- | `update:modelValue` | — | — |
3961
- | `input` | — | — |
3987
+ | 事件 | 参数 | 说明 |
3988
+ | ------------------- | ----- | ------------------------------------------------------------------------------ |
3989
+ | `input` | `any` | 子组件值变化时触发，参数为新值与其后透传的其余参数（在业务侧自行接管写入时用） |
3990
+ | `update:modelValue` | `any` | `v-model:modelValue` 更新；若 schema 里写了 `model`，会同步写回 `model[model]` |
3962
3991
 
3963
3992
  #### `ZlPdfViewer`
3964
3993
 
@@ -4105,7 +4134,9 @@ import { ZlEmpty } from '@zl-ui-kit/components'
4105
4134
 
4106
4135
  <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlForm/index.vue`</sub>
4107
4136
 
4108
- **接口概览**：2 props · 3 插槽
4137
+ **简介**：表单：`items` schema 驱动，控件由 `component`/`props` 描述； 单字段可用 `#<model>` 插槽整块接管，未声明的入参与事件透传给 `el-form`
4138
+
4139
+ **接口概览**：2 props · 3 插槽 · 9 暴露
4109
4140
 
4110
4141
  **用法示例**
4111
4142
 
@@ -4140,6 +4171,7 @@ import { ZlForm } from '@zl-ui-kit/components'
4140
4171
  | `items` | `FormItem[]` | `() => []` | 否 | `:items="items"` | 表单字段 schema，决定渲染哪些表单项 |
4141
4172
  | `model` | `Record<string, any>` | — | 否 | `:model="{}"` | 表单值对象，不传时由组件内部自建 |
4142
4173
 
4174
+ > 暴露对象是 `Proxy`：下表为显式实现的能力，**未列出的键会运行时下钻到内部实例**（不建议依赖，请用上表的实例 getter 取原生对象）
4143
4175
  > 把 `$attrs` 透传给 `el-form`，未列出的属性会继续下传
4144
4176
 
4145
4177
  **插槽（slots）**
@@ -4150,6 +4182,20 @@ import { ZlForm } from '@zl-ui-kit/components'
4150
4182
  | `[item.model]` | `model` / `field` | `<template #[item.model]="{ model, field }">…</template>` | 按该项 model 命名，传出 model、field；覆盖默认控件 |
4151
4183
  | `default` | — | `<template #default>…</template>` | 追加在末尾的表单内容（如额外区块、按钮） |
4152
4184
 
4185
+ **暴露（defineExpose）**
4186
+
4187
+ | 名称 | 说明 |
4188
+ | ------------------ | --------------------------------------------------------------------------- |
4189
+ | `validate` | 校验整个表单；同 `el-form.validate()`（无回调时失败会 reject 错误字段集合） |
4190
+ | `validateField` | 校验指定字段（字段名或数组），语义同 `validate()` |
4191
+ | `resetFields` | 重置字段并清除校验结果；不传参重置全部 |
4192
+ | `clearValidate` | 清除校验提示；不传参清除全部 |
4193
+ | `scrollToField` | 滚动到指定字段 |
4194
+ | `getField` | 取单个表单项上下文（含 `resetField`/`clearValidate`/`validateMessage` 等） |
4195
+ | `fields` | 全部表单项上下文（含 `prop`/`value`/`validateState` 等） |
4196
+ | `setInitialValues` | 写入字段初始值（`resetFields` 会回到这些值） |
4197
+ | `elForm` | 内部 ElForm 实例，未列出的能力兜底用 |
4198
+
4153
4199
  #### `ZlFormChild`
4154
4200
 
4155
4201
  <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlForm/ZlFormChild.vue`</sub>
@@ -4323,7 +4369,7 @@ import { ZlHorizontalTable } from '@zl-ui-kit/components'
4323
4369
 
4324
4370
  <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlIcon/index.vue`</sub>
4325
4371
 
4326
- **接口概览**：1 props · 1 插槽
4372
+ **接口概览**：3 props · 1 插槽
4327
4373
 
4328
4374
  **用法示例**
4329
4375
 
@@ -4349,9 +4395,13 @@ import { ZlIcon } from '@zl-ui-kit/components'
4349
4395
 
4350
4396
  **props**
4351
4397
 
4352
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4353
- | ------ | -------- | ------ | ---- | ------------------ | --------------------------------------------------------------- |
4354
- | `icon` | `string` | — | 是 | `icon="zl:search"` | 图标：zl:xxx（本地图标集）/ http(s) 地址 / 本地 svg sprite 名称 |
4398
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4399
+ | ------- | ------------------ | ------ | ---- | ------------------ | --------------------------------------------------------------------------------- |
4400
+ | `icon` | `string` | — | 是 | `icon="zl:search"` | 图标：zl:xxx（本地图标集）/ http(s) 地址 / 本地 svg sprite 名称 |
4401
+ | `size` | `string \| number` | — | 否 | `:size="size"` | 尺寸，作用在 `font-size` 上（数字按 px 处理），图标本体按 `1em` 缩放；默认 `14px` |
4402
+ | `color` | `string` | — | 否 | `color="#409eff"` | 颜色，默认继承当前文字色（`currentColor`） |
4403
+
4404
+ > 把未声明的入参与事件（`useAttrs()`）透传给 `iconify-icon`，未列出的属性会继续下传
4355
4405
 
4356
4406
  **插槽（slots）**
4357
4407
 
@@ -4453,9 +4503,9 @@ import { ZlIconLabel } from '@zl-ui-kit/components'
4453
4503
 
4454
4504
  **事件（emits）**
4455
4505
 
4456
- | 事件 | 参数 | 说明 |
4457
- | ------- | ------------ | ---- |
4458
- | `click` | `MouseEvent` | — |
4506
+ | 事件 | 参数 | 说明 |
4507
+ | ------- | ------------ | ------------------------------------------- |
4508
+ | `click` | `MouseEvent` | 点击图标/文字区域时触发，参数为原生鼠标事件 |
4459
4509
 
4460
4510
  **插槽（slots）**
4461
4511
 
@@ -4573,11 +4623,11 @@ import { ZlPagination } from '@zl-ui-kit/components'
4573
4623
 
4574
4624
  **事件（emits）**
4575
4625
 
4576
- | 事件 | 参数 | 说明 |
4577
- | ------------------ | --------------------------------------- | ---------------------------------- |
4578
- | `change` | `{ pageNum: number; pageSize: number }` | — |
4579
- | `page-change` | `number` | 仅页码变化（区别于 pageSize 变化） |
4580
- | `page-size-change` | `number` | 仅每页条数变化 |
4626
+ | 事件 | 参数 | 说明 |
4627
+ | ------------------ | --------------------------------------- | -------------------------------------------------------- |
4628
+ | `change` | `{ pageNum: number; pageSize: number }` | 页码或每页条数变化后触发，参数为 `{ pageNum, pageSize }` |
4629
+ | `page-change` | `number` | 仅页码变化（区别于 pageSize 变化） |
4630
+ | `page-size-change` | `number` | 仅每页条数变化 |
4581
4631
 
4582
4632
  #### `ZlPermission`
4583
4633
 
@@ -4664,10 +4714,10 @@ import { ZlPopconfirm } from '@zl-ui-kit/components'
4664
4714
 
4665
4715
  **事件（emits）**
4666
4716
 
4667
- | 事件 | 参数 | 说明 |
4668
- | --------- | ---- | ---- |
4669
- | `confirm` | — | — |
4670
- | `cancel` | — | — |
4717
+ | 事件 | 参数 | 说明 |
4718
+ | --------- | ---- | ----------------------------------------- |
4719
+ | `confirm` | — | 点击「确定」时触发（不会自动关闭浮层） |
4720
+ | `cancel` | — | 点击「取消」或通过遮罩/按钮关闭浮层时触发 |
4671
4721
 
4672
4722
  **插槽（slots）**
4673
4723
 
@@ -4787,11 +4837,11 @@ import { ZlSearch } from '@zl-ui-kit/components'
4787
4837
 
4788
4838
  **暴露（defineExpose）**
4789
4839
 
4790
- | 名称 | 说明 |
4791
- | -------- | ---- |
4792
- | `params` | — |
4793
- | `search` | — |
4794
- | `reset` | — |
4840
+ | 名称 | 说明 |
4841
+ | -------- | ---------------------------------------------------------------------------- |
4842
+ | `params` | 当前查询表单值（已按各项 `toParams` 转换），可直接当请求入参 |
4843
+ | `search` | 收起展开态并触发 `search` 事件（本身不做校验，带校验的查询走组件内查询按钮） |
4844
+ | `reset` | 重置表单并清除校验提示，随后触发 `reset` 事件与一次 `search` |
4795
4845
 
4796
4846
  #### `ZlSearchTable`
4797
4847
 
@@ -4845,9 +4895,9 @@ import { ZlSearchTable } from '@zl-ui-kit/components'
4845
4895
 
4846
4896
  **事件（emits）**
4847
4897
 
4848
- | 事件 | 参数 | 说明 |
4849
- | -------------- | ---- | ---- |
4850
- | `search-reset` | — | — |
4898
+ | 事件 | 参数 | 说明 |
4899
+ | -------------- | ---- | ---------------------------------------------------------- |
4900
+ | `search-reset` | — | 查询区重置时触发（此时表单已清空，随后会自动发起一次查询） |
4851
4901
 
4852
4902
  **插槽（slots）**
4853
4903
 
@@ -4859,12 +4909,12 @@ import { ZlSearchTable } from '@zl-ui-kit/components'
4859
4909
 
4860
4910
  **暴露（defineExpose）**
4861
4911
 
4862
- | 名称 | 说明 |
4863
- | --------- | ---- |
4864
- | `refresh` | — |
4865
- | `params` | — |
4866
- | `search` | — |
4867
- | `table` | — |
4912
+ | 名称 | 说明 |
4913
+ | --------- | --------------------------------------------------------------------------------- |
4914
+ | `refresh` | 原地重查：用最近一次入参重新请求，保持当前页码（区别于 `search()` 会回到第 1 页） |
4915
+ | `params` | 最近一次请求的入参（`{ pageNum, pageSize, ...查询表单 }`） |
4916
+ | `search` | 内部 ZlSearch 实例，`params` / `search()` / `reset()` 等可直接调用 |
4917
+ | `table` | 内部 ZlTable 实例，`toggleRowSelection()` / `doLayout()` 等可直接调用 |
4868
4918
 
4869
4919
  #### `ZlSection`
4870
4920
 
@@ -4952,10 +5002,10 @@ import { ZlSorter } from '@zl-ui-kit/components'
4952
5002
 
4953
5003
  **事件（emits）**
4954
5004
 
4955
- | 事件 | 参数 | 说明 |
4956
- | ------------------- | ----------------------- | -------------- |
4957
- | `update:modelValue` | `'' \| 'asc' \| 'desc'` | `v-model` 更新 |
4958
- | `change` | `'' \| 'asc' \| 'desc'` | — |
5005
+ | 事件 | 参数 | 说明 |
5006
+ | ------------------- | ----------------------- | ---------------------------------------------------- |
5007
+ | `update:modelValue` | `'' \| 'asc' \| 'desc'` | `v-model` 更新 |
5008
+ | `change` | `'' \| 'asc' \| 'desc'` | 排序切换时触发，参数为新的排序值（空串表示取消排序） |
4959
5009
 
4960
5010
  **插槽（slots）**
4961
5011
 
@@ -4994,17 +5044,17 @@ import { ZlSorterList } from '@zl-ui-kit/components'
4994
5044
 
4995
5045
  **事件（emits）**
4996
5046
 
4997
- | 事件 | 参数 | 说明 |
4998
- | -------- | ------------------------------------- | ---- |
4999
- | `change` | `Record<string, any>, string, string` | — |
5047
+ | 事件 | 参数 | 说明 |
5048
+ | -------- | ------------------------------------- | -------------------------------------------------------------- |
5049
+ | `change` | `Record<string, any>, string, string` | 某字段排序变化时触发，参数依次为整份排序对象、字段名、新排序值 |
5000
5050
 
5001
5051
  #### `ZlSwitch`
5002
5052
 
5003
5053
  <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlSwitch/index.vue`</sub>
5004
5054
 
5005
- **简介**：开关：值可为 boolean/string/number，支持 checkedText/uncheckedText 文案
5055
+ **简介**：开关：值可为 boolean/string/number，支持 checkedText/uncheckedText 文案； 兼容 `el-switch` 的 `active-value`/`inactive-value` 写法，`disabled`/`loading`/`before-change` 等透传 `el…
5006
5056
 
5007
- **接口概览**：6 props · 1 事件 · 2 插槽
5057
+ **接口概览**：8 props · 2 事件 · 2 插槽
5008
5058
 
5009
5059
  **用法示例**
5010
5060
 
@@ -5031,22 +5081,25 @@ import { ZlSwitch } from '@zl-ui-kit/components'
5031
5081
 
5032
5082
  **props**
5033
5083
 
5034
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
5035
- | ---------------- | ----------------------------- | ------- | ---- | ----------------------------------- | ---------------------------- |
5036
- | `modelValue` | `boolean \| string \| number` | — | 否 | `v-model="value"` | 当前开关值，支持受控双向绑定 |
5037
- | `defaultChecked` | `boolean` | `false` | 否 | `default-checked` | 非受控模式下的初始选中状态 |
5038
- | `checkedValue` | `boolean \| string \| number` | `true` | 否 | `:checked-value="checkedValue"` | 选中状态对应的提交值 |
5039
- | `uncheckedValue` | `boolean \| string \| number` | `false` | 否 | `:unchecked-value="uncheckedValue"` | 未选中状态对应的提交值 |
5040
- | `checkedText` | `string` | — | 否 | `checked-text="开"` | 选中时显示的文案 |
5041
- | `uncheckedText` | `string` | — | 否 | `unchecked-text="关"` | 未选中时显示的文案 |
5084
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
5085
+ | ---------------- | ----------------------------- | ------- | ---- | ----------------------------------- | --------------------------------------------------------------------------------------------------- |
5086
+ | `modelValue` | `boolean \| string \| number` | — | 否 | `v-model="value"` | 当前开关值，支持受控双向绑定 |
5087
+ | `defaultChecked` | `boolean` | `false` | 否 | `default-checked` | 非受控模式下的初始选中状态 |
5088
+ | `checkedValue` | `boolean \| string \| number` | — | 否 | `:checked-value="checkedValue"` | 选中状态对应的提交值 |
5089
+ | `uncheckedValue` | `boolean \| string \| number` | — | 否 | `:unchecked-value="uncheckedValue"` | 未选中状态对应的提交值 |
5090
+ | `activeValue` | `boolean \| string \| number` | — | 否 | `:active-value="activeValue"` | `checked-value` 的别名（对齐 `el-switch` 的 `active-value`），两者同传时 `checked-value` 优先 |
5091
+ | `inactiveValue` | `boolean \| string \| number` | — | 否 | `:inactive-value="inactiveValue"` | `unchecked-value` 的别名（对齐 `el-switch` 的 `inactive-value`），两者同传时 `unchecked-value` 优先 |
5092
+ | `checkedText` | `string` | — | 否 | `checked-text="开"` | 选中时显示的文案 |
5093
+ | `uncheckedText` | `string` | — | 否 | `unchecked-text="关"` | 未选中时显示的文案 |
5042
5094
 
5043
5095
  > 把 `$attrs` 透传给 `el-switch`，未列出的属性会继续下传
5044
5096
 
5045
5097
  **事件（emits）**
5046
5098
 
5047
- | 事件 | 参数 | 说明 |
5048
- | ------------------- | ----------------------------- | ---- |
5049
- | `update:modelValue` | `boolean \| string \| number` | — |
5099
+ | 事件 | 参数 | 说明 |
5100
+ | ------------------- | ----------------------------- | ------------------------------------------------------------------------------------ |
5101
+ | `update:modelValue` | `boolean \| string \| number` | v-model 更新 |
5102
+ | `change` | `boolean \| string \| number` | 开关值变化后触发，参数为业务值（即 `checked-value`/`unchecked-value`，不是内部布尔） |
5050
5103
 
5051
5104
  **插槽（slots）**
5052
5105
 
@@ -5059,7 +5112,9 @@ import { ZlSwitch } from '@zl-ui-kit/components'
5059
5112
 
5060
5113
  <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlTable/index.vue`</sub>
5061
5114
 
5062
- **接口概览**：6 props · 3 事件 · 3 插槽
5115
+ **简介**：表格：`columns` schema 驱动 + 内置分页；单元格可用 `#<slot>` 接管（作用域含 `row`/`column`/`$index`）， 未声明的入参与事件透传给 `el-table`
5116
+
5117
+ **接口概览**：6 props · 3 事件 · 3 插槽 · 16 暴露
5063
5118
 
5064
5119
  **用法示例**
5065
5120
 
@@ -5098,15 +5153,16 @@ import { ZlTable } from '@zl-ui-kit/components'
5098
5153
  | `pagination` | `Record<string, any> \| boolean` | — | 否 | `:pagination="{}"` | 分页配置，设为 false 时隐藏分页 |
5099
5154
  | `loading` | `boolean` | `false` | 否 | `loading` | 表格 loading（作用于表格区） |
5100
5155
 
5156
+ > 暴露对象是 `Proxy`：下表为显式实现的能力，**未列出的键会运行时下钻到内部实例**（不建议依赖，请用上表的实例 getter 取原生对象）
5101
5157
  > 把 `$attrs` 透传给 `el-table`，未列出的属性会继续下传
5102
5158
 
5103
5159
  **事件（emits）**
5104
5160
 
5105
- | 事件 | 参数 | 说明 |
5106
- | ------------------- | --------------------------------------- | ---- |
5107
- | `pagination-change` | `{ pageNum: number; pageSize: number }` | — |
5108
- | `page-change` | `number` | — |
5109
- | `page-size-change` | `number` | — |
5161
+ | 事件 | 参数 | 说明 |
5162
+ | ------------------- | --------------------------------------- | -------------------------------------------------- |
5163
+ | `pagination-change` | `{ pageNum: number; pageSize: number }` | 分页状态变化时触发，参数为 `{ pageNum, pageSize }` |
5164
+ | `page-change` | `number` | 仅页码变化时触发 |
5165
+ | `page-size-change` | `number` | 仅每页条数变化时触发 |
5110
5166
 
5111
5167
  **插槽（slots）**
5112
5168
 
@@ -5116,11 +5172,32 @@ import { ZlTable } from '@zl-ui-kit/components'
5116
5172
  | `[column.headerSlotName]` | `v-bind="scope"` 展开 | `<template #[column.headerSlotName]="scope">…</template>` | 按列字段生成 header-* 名，参数为列上下文 |
5117
5173
  | `[column.slotName]` | `v-bind="scope"` 展开 | `<template #[column.slotName]="scope">…</template>` | 按 slot 或字段名生成，参数为单元格上下文 |
5118
5174
 
5175
+ **暴露（defineExpose）**
5176
+
5177
+ | 名称 | 说明 |
5178
+ | ---------------------- | ------------------------------------------------------------- |
5179
+ | `setCurrentRow` | 单选表格下将指定行设为选中；不传参则清除当前行选中 |
5180
+ | `toggleRowSelection` | 多选表格下切换某行选中状态；第二个参数可直接指定是否选中 |
5181
+ | `clearSelection` | 清空用户的多选状态 |
5182
+ | `toggleAllSelection` | 多选表格全选 / 取消全选 |
5183
+ | `getSelectionRows` | 取当前被选中的行 |
5184
+ | `getHalfSelectionRows` | 取当前半选（父子联动）的行 |
5185
+ | `toggleRowExpansion` | 展开/收起某行的展开内容或子节点；第二个参数可直接指定是否展开 |
5186
+ | `clearSort` | 清除排序，恢复原始顺序 |
5187
+ | `clearFilter` | 清除列筛选；不传 columnKey 则清除全部 |
5188
+ | `sort` | 手动排序：`prop` 指定列字段，`order` 指定升/降序 |
5189
+ | `doLayout` | 重新计算表格布局（容器由隐藏变可见时常用） |
5190
+ | `updateKeyChildren` | 懒加载树形表格下更新某行的子节点（需配合 `row-key`） |
5191
+ | `scrollTo` | 滚动到指定坐标 |
5192
+ | `setScrollLeft` | 设置横向滚动位置 |
5193
+ | `setScrollTop` | 设置纵向滚动位置 |
5194
+ | `elTable` | 内部 ElTable 实例，未列出的能力（`store`/`columns` 等）兜底用 |
5195
+
5119
5196
  #### `ZlTabs`
5120
5197
 
5121
5198
  <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlTabs/index.vue`</sub>
5122
5199
 
5123
- **接口概览**：4 props · 3 插槽
5200
+ **接口概览**：5 props · 1 事件 · 3 插槽
5124
5201
 
5125
5202
  **用法示例**
5126
5203
 
@@ -5153,16 +5230,23 @@ import { ZlTabs } from '@zl-ui-kit/components'
5153
5230
 
5154
5231
  **props**
5155
5232
 
5156
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
5157
- | --------- | --------- | ---------- | ---- | ------------------- | --------------------------------- |
5158
- | `tabs` | `any[]` | `() => []` | 否 | `:tabs="[]"` | 页签配置列表，以 key 关联内容插槽 |
5159
- | `border` | `boolean` | `true` | 否 | `:border="false"` | 是否显示页签导航分隔线，默认显示 |
5160
- | `fit` | `boolean` | — | 否 | `fit` | 是否撑满容器并让内容区滚动 |
5161
- | `darkNav` | `boolean` | `true` | 否 | `:dark-nav="false"` | 是否启用导航背景色，默认启用 |
5233
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
5234
+ | ------------ | ------------------ | ----------- | ---- | ------------------- | ----------------------------------------- |
5235
+ | `tabs` | `any[]` | `() => []` | 否 | `:tabs="[]"` | 页签配置列表，以 key 关联内容插槽 |
5236
+ | `modelValue` | `[String, Number]` | `undefined` | 否 | `v-model="value"` | 当前激活页签的 key，可用 v-model 双向绑定 |
5237
+ | `border` | `boolean` | `true` | 否 | `:border="false"` | 是否显示页签导航分隔线，默认显示 |
5238
+ | `fit` | `boolean` | — | 否 | `fit` | 是否撑满容器并让内容区滚动 |
5239
+ | `darkNav` | `boolean` | `true` | 否 | `:dark-nav="false"` | 是否启用导航背景色，默认启用 |
5162
5240
 
5163
5241
  > 选项式组件（`defineComponent`），props 定义在 `props: {}` 中
5164
5242
  > 把 `$attrs` 透传给内部组件，未列出的属性会继续下传
5165
5243
 
5244
+ **事件（emits）**
5245
+
5246
+ | 事件 | 参数 | 说明 |
5247
+ | ------------------- | ------------------------------- | ---------------------------------------------------------- |
5248
+ | `update:modelValue` | `string \| number \| undefined` | 点击页签切换后触发，参数为新激活页签的 key（v-model 更新） |
5249
+
5166
5250
  **插槽（slots）**
5167
5251
 
5168
5252
  | 插槽 | 作用域参数 | 示例 | 说明 |
@@ -5221,12 +5305,12 @@ import { ZlTag } from '@zl-ui-kit/components'
5221
5305
 
5222
5306
  **事件（emits）**
5223
5307
 
5224
- | 事件 | 参数 | 说明 |
5225
- | ----------------- | ------------ | ---- |
5226
- | `close` | `MouseEvent` | — |
5227
- | `update:visible` | `boolean` | — |
5228
- | `update:selected` | `boolean` | — |
5229
- | `select` | `boolean` | — |
5308
+ | 事件 | 参数 | 说明 |
5309
+ | ----------------- | ------------ | --------------------------------------------------------------------------- |
5310
+ | `close` | `MouseEvent` | 点击关闭图标时触发，参数为原生鼠标事件（`closable` 开启时有效） |
5311
+ | `update:visible` | `boolean` | `v-model:visible` 更新 |
5312
+ | `update:selected` | `boolean` | `v-model:selected` 更新 |
5313
+ | `select` | `boolean` | 点击标签切换选中态时触发，参数为切换后的选中状态（`selectable` 开启时有效） |
5230
5314
 
5231
5315
  **插槽（slots）**
5232
5316
 
@@ -5441,6 +5525,8 @@ import { ZlTree } from '@zl-ui-kit/components'
5441
5525
  | `checkStrictly` | `boolean` | `false` | 否 | `check-strictly` | 勾选时父子不关联（每个节点独立勾选） |
5442
5526
  | `checkDescendants` | `boolean` | `false` | 否 | `check-descendants` | 勾选父节点时联动勾选全部子孙（懒加载未展开的层级需要展开后才纳入） |
5443
5527
 
5528
+ > 把未声明的入参与事件（`useAttrs()`）透传给 `el-tree`，未列出的属性会继续下传
5529
+
5444
5530
  **事件（emits）**
5445
5531
 
5446
5532
  | 事件 | 参数 | 说明 |
@@ -5556,15 +5642,15 @@ import { ZlChart } from '@zl-ui-kit/components/chart'
5556
5642
 
5557
5643
  **暴露（defineExpose）**
5558
5644
 
5559
- | 名称 | 说明 |
5560
- | ------- | ---- |
5561
- | `clear` | — |
5645
+ | 名称 | 说明 |
5646
+ | ------- | ----------------------------------------------------------------- |
5647
+ | `clear` | 清空图表内容（保留 echarts 实例，后续 `option` 变化仍可继续渲染） |
5562
5648
 
5563
5649
  #### `ZlEditor`
5564
5650
 
5565
5651
  <sub>入口 `@zl-ui-kit/components/editor` · 源码 `packages/components/src/components/ZlEditor/index.vue` · ⚠️ 不在主入口，需从子路径 import，并自行安装对应 peer 依赖</sub>
5566
5652
 
5567
- **接口概览**：3 props · 1 事件
5653
+ **接口概览**：3 props · 1 事件 · 10 暴露
5568
5654
 
5569
5655
  **用法示例**
5570
5656
 
@@ -5586,17 +5672,34 @@ import { ZlEditor } from '@zl-ui-kit/components/editor'
5586
5672
  | `language` | `string` | `'javascript'` | 否 | `language="javascript"` | 语法高亮所用语言 id，默认 javascript |
5587
5673
  | `options` | `Record<string, any>` | `() => ({})` | 否 | `:options="{}"` | monaco 编辑器配置，覆盖内置默认项 |
5588
5674
 
5675
+ > 暴露对象是 `Proxy`：下表为显式实现的能力，**未列出的键会运行时下钻到内部实例**（不建议依赖，请用上表的实例 getter 取原生对象）
5676
+
5589
5677
  **事件（emits）**
5590
5678
 
5591
5679
  | 事件 | 参数 | 说明 |
5592
5680
  | ------------------- | -------- | -------------- |
5593
5681
  | `update:modelValue` | `string` | `v-model` 更新 |
5594
5682
 
5683
+ **暴露（defineExpose）**
5684
+
5685
+ | 名称 | 说明 |
5686
+ | --------------- | ---------------------------------------------------------------------------------- |
5687
+ | `monacoEditor` | 底层 monaco 编辑器实例（`IStandaloneCodeEditor`），需要未列出的原生 API 时仍这里取 |
5688
+ | `getValue` | 读取当前文本（`v-model` 已自动同步，一般无需主动调用） |
5689
+ | `setValue` | 设置整本文本，会同步触发 `v-model` 更新 |
5690
+ | `getModel` | 当前文本模型（monaco `ITextModel`），打 marker / 取行内容时需要 |
5691
+ | `getSelection` | 当前选区（未选中时为空） |
5692
+ | `revealLine` | 滚动到指定行使其进入可视区 |
5693
+ | `focus` | 让编辑器获得焦点 |
5694
+ | `layout` | 重算布局（容器尺寸变化已由组件内部 `useResizeObserver` 自动处理，无需手动调） |
5695
+ | `updateOptions` | 运行时更新 monaco 创建选项 |
5696
+ | `dispose` | 销毁编辑器实例（组件卸载时自动调用，重复调用 monaco 会抛错） |
5697
+
5595
5698
  #### `ZlSqlEditor`
5596
5699
 
5597
5700
  <sub>入口 `@zl-ui-kit/components/editor` · 源码 `packages/components/src/components/ZlEditor/ZlSqlEditor.vue` · ⚠️ 不在主入口，需从子路径 import，并自行安装对应 peer 依赖</sub>
5598
5701
 
5599
- **接口概览**：4 props · 1 事件
5702
+ **接口概览**：4 props · 1 事件 · 3 暴露
5600
5703
 
5601
5704
  **用法示例**
5602
5705
 
@@ -5619,6 +5722,7 @@ import { ZlSqlEditor } from '@zl-ui-kit/components/editor'
5619
5722
  | `customKeywords` | `string[]` | `() => []` | 否 | `:custom-keywords="[]"` | 追加到内置保留字表的自定义关键字 |
5620
5723
  | `customFunctions` | `string[]` | `() => []` | 否 | `:custom-functions="[]"` | 参与补全提示的自定义函数名 |
5621
5724
 
5725
+ > 暴露对象是 `Proxy`：下表为显式实现的能力，**未列出的键会运行时下钻到内部实例**（不建议依赖，请用上表的实例 getter 取原生对象）
5622
5726
  > 把 `$attrs` 透传给 `ZlEditor`，未列出的属性会继续下传
5623
5727
 
5624
5728
  **事件（emits）**
@@ -5627,6 +5731,14 @@ import { ZlSqlEditor } from '@zl-ui-kit/components/editor'
5627
5731
  | ------------------- | -------- | -------------- |
5628
5732
  | `update:modelValue` | `string` | `v-model` 更新 |
5629
5733
 
5734
+ **暴露（defineExpose）**
5735
+
5736
+ | 名称 | 说明 |
5737
+ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
5738
+ | `validate` | 用 dt-sql-parser 校验当前 SQL：无错时清空 marker；有错时打红色 marker + `ElMessage` 提示，并 **`throw diagnostics`**（调用方需 catch） |
5739
+ | `format` | 先跑 `validate()`（不通过会抛），通过则用 sql-formatter 格式化并写回 `v-model` |
5740
+ | `zlEditor` | 内部 `ZlEditor` 实例（其暴露对象代理 monaco），需要原生编辑器 API 时从这里取 |
5741
+
5630
5742
  #### `ZlFilePreview`
5631
5743
 
5632
5744
  <sub>入口 `@zl-ui-kit/components/file-preview` · 源码 `packages/components/src/components/ZlFilePreview/index.vue` · ⚠️ 不在主入口，需从子路径 import，并自行安装对应 peer 依赖</sub>
@@ -5840,36 +5952,41 @@ ZlGrid 子项 schema
5840
5952
  10. **列表页操作按钮归位**：使用 `ZlSearchTable` 或 `ZlCardPage` 替换的列表页，其「新增 / 导入 / 导出」等操作按钮统一放进对应组件的 `search-actions` 插槽（亦兼容 camelCase `searchActions`）。
5841
5953
  11. **其余 Element Plus 组件**：剩余 `el-` 开头的 Element Plus 组件，均按 §3 组件总览的命名对应关系替换为对应的 Zl 组件（如 `el-tree`→`ZlTree`、`el-upload`→`ZlUpload`、`el-tag`→`ZlTag`、`el-tabs`→`ZlTabs` 等）。
5842
5954
  12. **工具方法复用**：宿主项目里使用的工具类方法，需先与 `@zl-ui-kit/utils` 中的工具方法比对（完整清单见 §12.2，精确签名见 §12.3）；若存在**最终效果一致**的实现，统一使用 `@zl-ui-kit/utils` 的方法替换，避免重复实现与行为不一致。
5955
+ 13. **先读透传契约**：动手替换前读完 [§15.5 迁移行为差异与透传契约](#155-迁移行为差异与透传契约必读)——未列在 props 表的属性与事件大多直接透传给内部 `el-*`，而少数默认值 / 入参语义与 EP 不等价，需逐条核对。
5843
5956
 
5844
5957
  ### 15.2 常用 el-* → Zl-* 对照表（持续补充）
5845
5958
 
5846
- | Element Plus 组件 | 替换为 | 说明 |
5847
- | ------------------------------ | --------------- | -------------------------------------------------- |
5848
- | `el-table`（普通 / 分页列表） | `ZlSearchTable` | 自带查询条、分页、loading |
5849
- | `el-table`（卡片分页列表） | `ZlCardPage` | 卡片式分页列表 |
5850
- | `el-table`（纯表格，无查询） | `ZlTable` | 普通表格展示 |
5851
- | `el-dialog` / `el-drawer` | `ZlDrawer` | 所有弹窗统一为抽屉 |
5852
- | `el-form` | `ZlForm` | 弹窗内新增 / 编辑 / 详情表单（schema 驱动） |
5853
- | `el-card` | `ZlCard` | 卡片容器 |
5854
- | `el-button`（操作栏 / 卡片内） | `ZlAction` | 操作列与卡片按钮；页面级独立按钮仍可用 `el-button` |
5855
- | `el-tooltip`（超长省略） | `ZlAutoTooltip` | 文字溢出时自动提示 |
5856
- | `el-icon` | `ZlIcon` | 需先注册图标集（§4.1） |
5857
- | `el-tree` | `ZlTree` | 勾选多选 / 字段映射 / 暴露方法见 §7 › ZlTree |
5858
- | `el-upload` | `ZlUpload` | |
5859
- | `el-tag` | `ZlTag` | |
5860
- | `el-tabs` | `ZlTabs` | |
5861
- | `el-radio`（标签式） | `ZlRadioTag` | |
5862
- | `el-checkbox`（标签式） | `ZlCheckboxTag` | |
5863
- | `el-switch` | `ZlSwitch` | |
5864
- | `el-popconfirm` | `ZlPopconfirm` | |
5865
- | `el-empty` | `ZlEmpty` | |
5866
- | `el-avatar` | `ZlAvatar` | |
5867
- | `el-descriptions` | `ZlDescription` | |
5868
- | `el-text` | `ZlText` | |
5869
- | `el-pagination` | `ZlPagination` | |
5870
- | `el-select`（树形） | `ZlTreeSelect` | |
5959
+ | Element Plus 组件 | 替换为 | 说明 |
5960
+ | ------------------------------------------------- | ------------------- | -------------------------------------------------- |
5961
+ | `el-table`（普通 / 分页列表） | `ZlSearchTable` | 自带查询条、分页、loading |
5962
+ | `el-table`（卡片分页列表） | `ZlCardPage` | 卡片式分页列表 |
5963
+ | `el-table`（纯表格，无查询） | `ZlTable` | 普通表格展示 |
5964
+ | `el-dialog` / `el-drawer` | `ZlDrawer` | 所有弹窗统一为抽屉 |
5965
+ | `el-form` | `ZlForm` | 弹窗内新增 / 编辑 / 详情表单（schema 驱动） |
5966
+ | `el-card` | `ZlCard` | 卡片容器 |
5967
+ | `el-button`（操作栏 / 卡片内） | `ZlAction` | 操作列与卡片按钮；页面级独立按钮仍可用 `el-button` |
5968
+ | `el-tooltip`（超长省略） | `ZlAutoTooltip` | 文字溢出时自动提示 |
5969
+ | `el-icon` | `ZlIcon` | 需先注册图标集（§4.1） |
5970
+ | `el-tree` | `ZlTree` | 勾选多选 / 字段映射 / 暴露方法见 §7 › ZlTree |
5971
+ | `el-upload` | `ZlUpload` | |
5972
+ | `el-tag` | `ZlTag` | |
5973
+ | `el-tabs` | `ZlTabs` | 页签内容默认懒挂载，差异见 §15.5 |
5974
+ | `el-radio`（标签式） | `ZlRadioTag` | 仅此形态封装 |
5975
+ | `el-checkbox`（标签式） | `ZlCheckboxTag` | 仅此形态封装 |
5976
+ | `el-checkbox`（全选 / 半选） | `ZlCheckAll` | 自带半选态，可替代表头全选勾选框 |
5977
+ | `el-radio` / `el-checkbox`（普通单选框 / 复选框） | —（**有意不封装**） | 继续用 `el-*`，库内无对应物（见 §15.5） |
5978
+ | `el-radio-group` / `el-checkbox-group` | —（**有意不封装**） | 继续用 `el-*`，组内选项自行渲染 |
5979
+ | `el-switch` | `ZlSwitch` | |
5980
+ | `el-popconfirm` | `ZlPopconfirm` | |
5981
+ | `el-empty` | `ZlEmpty` | |
5982
+ | `el-avatar` | `ZlAvatar` | |
5983
+ | `el-descriptions` | `ZlDescription` | |
5984
+ | `el-text` | `ZlText` | |
5985
+ | `el-pagination` | `ZlPagination` | |
5986
+ | `el-select`（树形） | `ZlTreeSelect` | |
5871
5987
 
5872
5988
  > 未在上表中的 `el-*` 组件，请对照 §3 组件总览的命名与用途选择对应 Zl 组件；若暂无对应实现，暂保留 `el-*`，并在本规范登记为待补充项。
5989
+ > 替换前请先读 **[§15.5 迁移行为差异与透传契约](#155-迁移行为差异与透传契约必读)**：哪些属性默认直接透传、哪些行为与 EP 不等价。
5873
5990
 
5874
5991
  ### 15.3 列表页操作按钮归位（search-actions 插槽）
5875
5992
 
@@ -5925,3 +6042,33 @@ ZlGrid 子项 schema
5925
6042
  > 比对原则：**先看最终效果是否一致，再决定替换**——若宿主实现带特殊业务分支（如特定容错、字段命名差异），替换后需回归验证；
5926
6043
  > 无法确认一致时暂保留宿主实现，并在本表登记为待补充项。
5927
6044
  > 完整方法清单与精确签名见 §12.2 / §12.3（§12.3 由源码自动生成，始终与代码同步）。
6045
+
6046
+ ### 15.5 迁移行为差异与透传契约（必读）
6047
+
6048
+ > **先建立判定方法，再改代码。**绝大多数 Zl 组件是 `inheritAttrs: false` + 把**未声明的入参与事件透传给内部 `el-*`**，
6049
+ > 因此「props 表里没列出」不等于「不能用」。判断某个 `el-*` 的属性 / 事件在 Zl 组件上是否生效，按三步：
6050
+ >
6051
+ > 1. 看 [§14 组件 API 参考](#14-组件-api-参考自动生成) 该组件的**「说明」列**——它会写明“把未声明的入参与事件透传给 `el-xxx`”；
6052
+ > 2. 未声明也没被内部占用的属性与 `@事件` → **直接照抄 EP 写法**即可（如 `disabled` / `loading` / `before-change` / `tab-click`）；
6053
+ > 3. 若同名 prop 已被 Zl 声明、或内部有固定绑定 → 以 Zl 为准，已知冲突点见下表。
6054
+ >
6055
+ > ⚠️ **不要用 `.d.ts` / 构建产物反推契约**：`inheritAttrs: false` 的透传能力不会出现在类型声明里，从 d.ts 看会得出“事件无法监听”“属性不支持”这类错误结论。
6056
+ > 契约以三处为准：**§14（源码自动生成，与代码同步）+ playground 示例 + 内部 `el-*` 的官方文档**。
6057
+
6058
+ #### 与 Element Plus 不等价 / 需注意事项
6059
+
6060
+ | 组件 | 差异 | 迁移注意 |
6061
+ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
6062
+ | `ZlDrawer` | `width` 映射到内部 `size`（默认 `600`）；`destroy-on-close` **默认 `true`**（EP 默认 `false`）；自带底部取消 / 确定按钮区 | 抽屉内容**关闭即销毁**，内部状态不保留；需保留状态时显式传 `:destroy-on-close="false"` |
6063
+ | `ZlForm` | `validate()` / `validateField()` 与 `el-form` **完全同语义**（成功 `resolve(true)`、失败 `reject(invalidFields)`、支持 callback）；暴露 `el-form` 的 8 项能力 + `elForm` | 需 `el-form` 未暴露的方法时用 `formRef.elForm` |
6064
+ | `ZlTable` | 列插槽按 `prop` 名命名，作用域含 `{ row, column, $index }`；暴露 `el-table` 的 15 个公开方法 + `elTable` getter | `tableRef.toggleRowSelection(row)` 等均有类型提示；其余方法走 `tableRef.elTable` |
6065
+ | `ZlSwitch` | 主名 `checked-value` / `unchecked-value`，同时**兼容 EP 的 `active-value` / `inactive-value` 别名**（同传时主名优先）；`@change` 参数是**业务值**而非内部布尔 | 直搬 `:active-value="'1'"` 可用；从 `el-switch` 迁移时注意 `@change` 入参含义已变 |
6066
+ | `ZlTabs` | schema 驱动：`tab.key`→`name`、`tab.title`→`label`；页签内容**默认懒挂载**（`lazy` / `lazyLoad` 默认 `true`）；内容写在以 key 命名的插槽里 | 需挂载时就初始化的页签要显式 `lazyLoad: false`；`type` / `tab-click` 等透传 `el-tabs` |
6067
+ | `ZlIcon` | 单色图标：尺寸走 `size`（作用在 `font-size`），颜色走 `color` / `currentColor`；`spin` / `rotate` 等仅 `zl:` 前缀（iconify）分支生效 | 图标名未注册或拼错时**不报错、不告警、只渲染空白**；迁移前用 `@zl-ui-kit/icons` 核名（见 §4.1） |
6068
+ | `ZlTree` | 勾选多选 / 字段映射 / 暴露方法的完整说明见 §7 › ZlTree | 从 `el-tree` 直搬时先核对 `node-key` 与字段映射 |
6069
+ | `ZlEditor` / `ZlSqlEditor` | 暴露对象是 `Proxy`：§14 列的是显式能力，未列出的 monaco 原生 API 靠运行时下钻（旧行为，**不算契约**）；`ZlSqlEditor.validate()` 不通过时 **`throw diagnostics`** | 需要原生能力时用 `editorRef.value.monacoEditor`（SQL 编辑器用 `.zlEditor`）；`format()` 内部会先校验 |
6070
+ | `ZlAppLayout` | 只声明 `layout`（`horizontal` / `vertical`）；插槽由同目录形态子组件定义（`footer` 仅 vertical，`logo` / `menu` 在 vertical 下带 `{ collapsed }`） | 菜单数据传给 `#menu` 里的 `ZlAppMenu`，**不要写 `:menus="…"` 给 `ZlAppLayout`**（未声明的 prop 会落到 DOM） |
6071
+ | 普通单选 / 复选框 | **有意不封装**：库内只有标签式的 `ZlRadioTag` / `ZlCheckboxTag` 与自带半选的 `ZlCheckAll` | `el-radio` / `el-checkbox` / `el-radio-group` / `el-checkbox-group` **继续用 `el-*`**，不要找 Zl 对应物；表头全选 / 半选场景可直接用 `ZlCheckAll` |
6072
+
6073
+ > 发现**文档与实现不一致**（包括本节未覆盖的组件）：先以源码与 playground 实跑为准，并在宿主侧登记；
6074
+ > 属组件缺陷的回到本仓库修复（优先把契约补齐到与 EP 等价），属文档错误的直接修正本文件与 §14。修复方向以“**不破坏已有写法**”为序。