@zl-ui-kit/components 0.21.1 → 0.22.1

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 (25) hide show
  1. package/README.md +179 -87
  2. package/dist/components/ZlButton/index.vue.d.ts +64 -0
  3. package/dist/components/ZlButton/index.vue.mjs +44 -0
  4. package/dist/components/ZlButton/index2.vue.mjs +5 -0
  5. package/dist/components/ZlCopy/copy.mjs +17 -7
  6. package/dist/components/ZlCopy/index.css +1 -1
  7. package/dist/components/ZlCopy/index.vue.mjs +2 -2
  8. package/dist/components/ZlCopy/index2.vue.mjs +12 -12
  9. package/dist/components/ZlDevMenu/index.css +1 -0
  10. package/dist/components/ZlDevMenu/index.vue.d.ts +33 -0
  11. package/dist/components/ZlDevMenu/index.vue.mjs +109 -0
  12. package/dist/components/ZlDevMenu/index3.vue.mjs +6 -0
  13. package/dist/components/ZlDevMenu/types.d.ts +8 -0
  14. package/dist/components/ZlDialog/index.vue.mjs +17 -17
  15. package/dist/components/ZlDrawer/index.vue.mjs +23 -23
  16. package/dist/components/ZlMenu/index.vue.d.ts +1 -1
  17. package/dist/index.d.ts +3 -2
  18. package/dist/index.mjs +148 -145
  19. package/package.json +6 -6
  20. package/dist/components/ZlAppMenu/AppMenu.vue.d.ts +0 -27
  21. package/dist/components/ZlAppMenu/AppMenu.vue.mjs +0 -37
  22. package/dist/components/ZlAppMenu/AppMenu3.vue.mjs +0 -6
  23. package/dist/components/ZlAppMenu/AppMenuItem.vue.d.ts +0 -11
  24. package/dist/components/ZlAppMenu/AppMenuItem.vue.mjs +0 -58
  25. package/dist/components/ZlAppMenu/AppMenuItem2.vue.mjs +0 -5
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # @zl-ui-kit/components
2
2
 
3
- ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，56 个业务组件（含国际化根容器共 57 个对外组件）；配 `@zl-ui-kit/composables`（`useRequest` / `useDict`）、`@zl-ui-kit/theme`、`@zl-ui-kit/utils`、`@zl-ui-kit/icons` 使用。
3
+ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，62 个业务组件（含国际化根容器共 63 个对外组件）；配 `@zl-ui-kit/composables`（`useRequest` / `useDict`）、`@zl-ui-kit/theme`、`@zl-ui-kit/utils`、`@zl-ui-kit/icons` 使用。
4
4
 
5
- **本页即完整使用文档**：安装与四个导入入口、56 个组件用法、`useRequest` 请求体系与 Mock 联调、主题定制（L1/L2）、国际化接入、公共 Hooks 与 Utils —— 全部都在这一页。
5
+ **本页即完整使用文档**：安装与四个导入入口、62 个组件用法、`useRequest` 请求体系与 Mock 联调、主题定制（L1/L2）、国际化接入、公共 Hooks 与 Utils —— 全部都在这一页。
6
6
 
7
7
  > 本文档即 UI 组件的**权威文档**，直接在本文件维护；npm 官网包页面渲染的就是它，改完随下一次发版对外生效。
8
8
 
@@ -18,19 +18,20 @@ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，56 个业务组
18
18
  - [2.2 启动 playground（组件示例与联调）](#22-启动-playground组件示例与联调)
19
19
  - [2.3 主题快速接入（宿主项目）](#23-主题快速接入宿主项目)
20
20
  - [2.4 示例页面索引](#24-示例页面索引)
21
- - [3. 组件总览（59 个业务组件）](#3-组件总览59-个业务组件)
21
+ - [3. 组件总览（63 个业务组件）](#3-组件总览63-个业务组件)
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 国际化基础设施（独立于 59 个业务组件）](#36-国际化基础设施独立于-59-个业务组件)
27
+ - [3.6 国际化基础设施（独立于 63 个业务组件）](#36-国际化基础设施独立于-63-个业务组件)
28
28
  - [3.7 内部子组件（不对外导出，随父组件使用）](#37-内部子组件不对外导出随父组件使用)
29
29
  - [4. 图标组件 `ZlIcon`](#4-图标组件-zlicon)
30
30
  - [4.1 必须先注册图标集（否则一个图标都不显示）](#41-必须先注册图标集否则一个图标都不显示)
31
31
  - [5. 通用展示组件](#5-通用展示组件)
32
32
  - [ZlTitle — 区块标题](#zltitle-区块标题)
33
33
  - [ZlBreadcrumb — 面包屑](#zlbreadcrumb-面包屑)
34
+ - [ZlButton — 按钮](#zlbutton-按钮)
34
35
  - [ZlTag — 标签](#zltag-标签)
35
36
  - [ZlCopy — 一键复制](#zlcopy-一键复制)
36
37
  - [ZlEmpty — 空状态](#zlempty-空状态)
@@ -52,8 +53,9 @@ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，56 个业务组
52
53
  - [ZlTabs / ZlDynamicComponent / ZlGrid](#zltabs-zldynamiccomponent-zlgrid)
53
54
  - [ZlTree —— 树形控件（多选 / 暴露方法）](#zltree-树形控件多选-暴露方法)
54
55
  - [8. 布局与权限](#8-布局与权限)
55
- - [ZlAppLayout / ZlAppMenu](#zlapplayout-zlappmenu)
56
+ - [ZlAppLayout](#zlapplayout)
56
57
  - [ZlMenu — 通用菜单](#zlmenu-通用菜单)
58
+ - [ZlDevMenu — 开发菜单](#zldevmenu-开发菜单)
57
59
  - [ZlPermission](#zlpermission)
58
60
  - [ZlHorizontalTable](#zlhorizontaltable)
59
61
  - [9. 文件与编辑](#9-文件与编辑)
@@ -105,7 +107,7 @@ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，56 个业务组
105
107
 
106
108
  | 包 | 职责 |
107
109
  | -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
108
- | [`@zl-ui-kit/components`](https://www.npmjs.com/package/@zl-ui-kit/components) | EP 化业务组件库（`Zl` 前缀，56 个业务组件） |
110
+ | [`@zl-ui-kit/components`](https://www.npmjs.com/package/@zl-ui-kit/components) | EP 化业务组件库（`Zl` 前缀，58 个业务组件） |
109
111
  | [`@zl-ui-kit/composables`](https://www.npmjs.com/package/@zl-ui-kit/composables) | `useRequest` 请求体系、`useDict`、`useGlobalData` 全局数据、国际化 |
110
112
  | [`@zl-ui-kit/icons`](https://www.npmjs.com/package/@zl-ui-kit/icons) | 470 个离线 SVG 图标（prefix `zl`，开源图标库） |
111
113
  | [`@zl-ui-kit/theme`](https://www.npmjs.com/package/@zl-ui-kit/theme) | 5 套主题 + `defineTheme` 运行时定制（内置 OFL 开源中文字体） |
@@ -449,26 +451,26 @@ defineTheme({
449
451
  | `/manual` | 接口手册 | 全量 API 检索，支持按 props 名 / 事件名反查组件，`?name=ZlTable` 直接定位 |
450
452
  | `/icons` | 图标集 | 全量图标浏览/搜索，`zl:` 前缀渲染 |
451
453
  | `/theme` | 主题工场 | **默认主题零配置**（含从 `body` 实时读出的生效值）、5 套内置主题切换、L1/L2 覆盖与选层对照表、`defineTheme` 运行时自定义、不生效排查顺序 |
452
- | `/gallery` | 组件陈列 | 57 个组件逐个渲染（用于批量截图与冒烟） |
454
+ | `/gallery` | 组件陈列 | 62 个组件逐个渲染（用于批量截图与冒烟） |
453
455
  | `/use-request` | useRequest 联调 | 用 Mock 模块驱动各数据型组件（见第 6 章） |
454
456
  | `/examples/basic` | 通用展示示例 | ZlTitle/ZlTag/ZlCornerTag/ZlIcon/ZlText/ZlCopy/ZlAutoTooltip/ZlPagination/ZlEmpty |
455
457
  | `/examples/table-form` | 表格/表单示例 | ZlTable/ZlSearchTable/ZlForm/ZlDrawer/ZlPopconfirm/ZlSwitch/ZlDescription/ZlAction/ZlIconLabel/ZlIconHover/ZlSearch |
456
- | `/examples/general` | 布局与交互示例 | ZlAvatar/ZlBreadcrumb/ZlCheckAll/ZlRadioTag/ZlCheckboxTag/ZlAddSub/ZlSorter/ZlLayoutSwitch/ZlSection/ZlCard/ZlAppSlogan/ZlPermission/ZlHorizontalTable/ZlUpload/ZlTabs/ZlGrid/ZlDynamicComponent/ZlCardPage |
458
+ | `/examples/general` | 布局与交互示例 | ZlAvatar/ZlBreadcrumb/ZlButton/ZlCheckAll/ZlRadioTag/ZlCheckboxTag/ZlAddSub/ZlSorter/ZlLayoutSwitch/ZlSection/ZlCard/ZlAppSlogan/ZlPermission/ZlHorizontalTable/ZlUpload/ZlTabs/ZlGrid/ZlDynamicComponent/ZlCardPage |
457
459
  | `/examples/search-table` | ZlSearchTable 专项 | 基础用法 / `{ service, options }` 用法 / 暴露方法 / 无查询项 immediate，含分页与查询验证 |
458
460
 
459
461
  > 改造前的扁平路由（`/components`、`/general`、`/table-form`、`/search-table`）保留 **redirect**，历史链接与自动化脚本不会失效。
460
462
 
461
463
  ---
462
464
 
463
- ## 3. 组件总览（59 个业务组件）
465
+ ## 3. 组件总览（63 个业务组件）
464
466
 
465
- > 口径：主入口 `@zl-ui-kit/components` 导出 **55 个**组件，另有 **5 个**重型组件走子路径入口（`/chart`、`/editor`、`/file-preview`），合计 **60 个对外组件**（§14 逐条覆盖这 60 个）；其中 `ZlI18nProvider` 是国际化基础设施，故**业务组件为 59 个**（playground 的 `/gallery` 逐个渲染的就是这 59 个）。组件目录共 52 个（一个目录可产出多个导出符号，如 `ZlTag` 目录同时产出 `ZlTag` / `ZlCornerTag`）。§3.1~§3.5 按功能分组列出业务组件，其中混列了 4 个**不对外导出**的内部子组件（`ZlHorizontalLayout` / `ZlVerticalLayout` / `ZlAppMenuItem` / `ZlFileFetchError`，见 §3.7），去掉这 4 个后正好 59 个。
467
+ > 口径：主入口 `@zl-ui-kit/components` 导出 **58 个**组件，另有 **5 个**重型组件走子路径入口（`/chart`、`/editor`、`/file-preview`），合计 **63 个对外组件**（§14 逐条覆盖这 63 个）；其中 `ZlI18nProvider` 是国际化基础设施，故**业务组件为 62 个**（playground 的 `/gallery` 逐个渲染的就是这 62 个）。组件目录共 53 个（一个目录可产出多个导出符号，如 `ZlTag` 目录同时产出 `ZlTag` / `ZlCornerTag`）。§3.1~§3.5 按功能分组列出业务组件，其中混列了 3 个**不对外导出**的内部子组件（`ZlHorizontalLayout` / `ZlVerticalLayout` / `ZlFileFetchError`，见 §3.7），去掉这 3 个后正好 62 个。
466
468
 
467
469
  > **要查精确的 props / 事件 / 插槽 / 暴露方法 / schema 类型？** 直接看 **[§14 组件 API 参考](#14-组件-api-参考自动生成)**——逐个组件给出 `import`、可直接照抄的 **用法示例**（props 怎么写）与 **插槽用法**（`<template #name>` 怎么写），再用表格列出 TS 类型表达式、默认值、是否必填，**且每个 prop / 每个插槽都带一列「示例」**（能直接粘到标签上的写法），以及 `TableColumn` / `FormItem` / `SearchItem` / `ActionItem` 等 schema 类型的字段表。本章及 §4~§9 讲的是**场景化用法**，§14 是**逐字段的契约 + 可粘贴代码**。
468
470
 
469
471
  ### 3.1 通用展示组件
470
472
 
471
- `ZlIcon` · `ZlTitle` · `ZlBreadcrumb` · `ZlTag` · `ZlCornerTag` · `ZlText` · `ZlCopy` · `ZlAutoTooltip` · `ZlEmpty` · `ZlDictTag` · `ZlDescription` · `ZlSection` · `ZlCard` · `ZlAvatar` · `ZlAvatarGroup` · `ZlAppSlogan` · `ZlIconLabel` · `ZlIconHover`
473
+ `ZlIcon` · `ZlTitle` · `ZlBreadcrumb` · `ZlButton` · `ZlTag` · `ZlCornerTag` · `ZlText` · `ZlCopy` · `ZlAutoTooltip` · `ZlEmpty` · `ZlDictTag` · `ZlDescription` · `ZlSection` · `ZlCard` · `ZlAvatar` · `ZlAvatarGroup` · `ZlAppSlogan` · `ZlIconLabel` · `ZlIconHover`
472
474
 
473
475
  ### 3.2 数据型组件
474
476
 
@@ -480,41 +482,30 @@ defineTheme({
480
482
 
481
483
  ### 3.4 布局与权限
482
484
 
483
- `ZlAppLayout` · `ZlHorizontalLayout` · `ZlVerticalLayout` · `ZlAppMenu` · `ZlAppMenuItem` · `ZlPermission` · `ZlHorizontalTable`
485
+ `ZlAppLayout` · `ZlHorizontalLayout` · `ZlVerticalLayout` · `ZlDevMenu` · `ZlPermission` · `ZlHorizontalTable`
486
+
487
+ > `ZlAppMenu` / `ZlAppMenuItem` 与 `ZlMenu` 功能重复，**自 `0.22.0` 起移除**：菜单统一用 §8 的 `ZlMenu`（`items` + `v-model:selected`），迁移映射见 §15.5。
484
488
 
485
489
  ### 3.5 文件与编辑
486
490
 
487
491
  `ZlFilePreview` · `ZlFileFetchError` · `ZlFileViewer` · `ZlPdfViewer` · `ZlEditor` · `ZlSqlEditor` · `ZlLogin` · `ZlLoginForm`
488
492
 
489
- > 页签/微前端类组件（`ZlMicroPage`/`ZlAppTabs`/`ZlPageTabs`/`ZlDevMenu`）与配套 composables（`usePageTabs` 等）均已移除，`0.5.0` 起组件库不含任何微前端能力。
493
+ > 页签/微前端类组件（`ZlMicroPage`/`ZlAppTabs`/`ZlPageTabs`）与配套 composables（`usePageTabs` 等）均已移除，`0.5.0` 起组件库不含任何微前端能力；`ZlDevMenu` 以**开发模式路由快捷菜单**（不含微前端页签）的形式重新提供，用法见 §8。
490
494
 
491
- ### 3.6 国际化基础设施（独立于 59 个业务组件）
495
+ ### 3.6 国际化基础设施（独立于 63 个业务组件）
492
496
 
493
497
  `ZlI18nProvider` —— 国际化根容器，将 Element Plus 语言包经 `<el-config-provider>` 挂载到 Element Plus（详见第 13 章）。
494
498
 
495
499
  ### 3.7 内部子组件（不对外导出，随父组件使用）
496
500
 
497
- 下面 4 个组件被父组件内部递归/分发渲染，主入口**不导出**，因此不在 §14 的自动生成范围里。
501
+ 下面 3 个组件被父组件内部递归/分发渲染，主入口**不导出**，因此不在 §14 的自动生成范围里。
498
502
  这里单独给出 props 与插槽的可粘贴示例。
499
503
 
500
- #### `ZlAppMenuItem` —— 菜单项（供 `ZlAppMenu` 递归渲染）
501
-
502
- | prop | 类型 | 必填 | 示例 |
503
- | ------ | ---------- | ---- | ---------------------------------------------------------- |
504
- | `menu` | `MenuItem` | 是 | `:menu="{ name: 'home', title: '首页', icon: 'zl:home' }"` |
505
-
506
- | 事件 | 说明 | 示例 |
507
- | ----------------- | -------------------- | ----------------------------------------------------- |
508
- | `menu-item-click` | 点击叶子菜单项时触发 | `@menu-item-click="(menu) => router.push(menu.name)"` |
509
-
510
- `menu.children` 非空时渲染 `el-sub-menu` 并递归自身，否则渲染 `el-menu-item`。日常不需要手写——
511
- 把 `menus` 传给 `ZlAppMenu` 即可（见 §8）。
512
-
513
504
  #### `ZlHorizontalLayout` / `ZlVerticalLayout` —— 布局形态（供 `ZlAppLayout` 分发）
514
505
 
515
506
  由 `ZlAppLayout` 的 `layout`（`'horizontal'`（默认）/ `'vertical'`）二选一渲染，不单独使用。
516
- `ZlAppLayout` **只声明 `layout` 一个 prop**，插槽一律写在 `ZlAppLayout` 标签内；菜单数据自己传给 `#menu` 里的
517
- `ZlAppMenu`（传 `:menus` 给 `ZlAppLayout` 是无效的——它不声明该 prop）：
507
+ `ZlAppLayout` **只声明 `layout` 一个 prop**，插槽一律写在 `ZlAppLayout` 标签内；菜单自己放进 `#menu`，
508
+ 用 `ZlMenu` 的 `items` 渲染（传 `:menus` 给 `ZlAppLayout` 是无效的——它不声明该 prop）：
518
509
 
519
510
  ```vue
520
511
  <ZlAppLayout layout="vertical">
@@ -522,7 +513,7 @@ defineTheme({
522
513
  <img src="/logo.svg" />
523
514
  </template>
524
515
  <template #menu>
525
- <!-- 各形态自行放菜单，如 <ZlAppMenu :menus="menus" /> -->
516
+ <!-- 各形态自行放菜单，如 <ZlMenu :items="items" /> -->
526
517
  </template>
527
518
  <template #breadcrumb>
528
519
  <el-breadcrumb />
@@ -638,6 +629,25 @@ presetIconifyIcon(icons)
638
629
  </ZlBreadcrumb>
639
630
  ```
640
631
 
632
+ ### ZlButton — 按钮
633
+
634
+ `el-button` 的**零语义透传封装**：显式声明 EP 全部 19 个属性（`size` / `type` / `plain` / `text` / `link` / `bg` / `round` / `circle` / `dashed` / `loading` / `loadingIcon` / `icon` / `disabled` / `color` / `dark` / `nativeType` / `autofocus` / `autoInsertSpace` / `tag`），默认值一律 `undefined`，不覆盖 EP 默认与 `el-form` 的 `disabled` 继承；未声明的属性、事件与 `default` / `icon` / `loading` 插槽原样透传，不附带任何自定义样式。
635
+
636
+ ```vue
637
+ <ZlButton type="primary" @click="save">保存</ZlButton>
638
+ <ZlButton type="primary" plain round>朴素圆角</ZlButton>
639
+ <ZlButton type="warning" loading>提交中</ZlButton>
640
+ <ZlButton type="primary" text>文字按钮</ZlButton>
641
+ <ZlButton color="#5b8ff9" dark>自定义色</ZlButton>
642
+ <ZlButton type="primary" tag="a" href="/docs" target="_blank">链接标签</ZlButton>
643
+ <ZlButton type="primary">
644
+ <template #icon><zl-icon icon="zl:add" /></template>
645
+ 新增
646
+ </ZlButton>
647
+ ```
648
+
649
+ > 与 `ZlAction` 的分工：操作列 / 卡片内的按钮组用 `ZlAction`（汇总、折叠、权限），单颗按钮用 `ZlButton`（或直接用 `el-button`，两者行为完全一致）。
650
+
641
651
  ### ZlTag — 标签
642
652
 
643
653
  ```vue
@@ -1565,7 +1575,7 @@ async function onSubmit() {
1565
1575
  </template>
1566
1576
  ```
1567
1577
 
1568
- > `ZlForm` 的 `validate()` 返回 `Promise<boolean>`（`0.9.0` 及更早版本成功时 `resolve(undefined)`，判断成功请用 `await` 捕获异常而非当布尔用）。表单数据用 `:model` 传入，`props` 里的 `update:modelValue` 会写回该对象，无需手写 `v-model`。`ZlDrawer` 的 `onOk` 异步期间确定按钮自动保持 loading，`auto-close-after-confirm` 默认 `true`，需要自行控制关闭时设为 `false`。
1578
+ > `ZlForm` 的 `validate()` 返回 `Promise<boolean>`（`0.9.0` 及更早版本成功时 `resolve(undefined)`，判断成功请用 `await` 捕获异常而非当布尔用）。表单数据用 `:model` 传入，`props` 里的 `update:modelValue` 会写回该对象，无需手写 `v-model`。`ZlDrawer` 的 `onOk` 异步期间确定按钮自动保持 loading，`auto-close-after-confirm` 默认 `true`，需要自行控制关闭时设为 `false`；**未传 `onOk` 时点确定也会按 `auto-close-after-confirm` 关闭**（仅 ≥ 0.22.0，更早版本点确定无反应）。
1569
1579
 
1570
1580
  > 需要**对话框形态**（居中弹出、模态确认类）而非侧滑抽屉时，把 `ZlDrawer` 换成 `ZlDialog`——两者 API 完全一致（`v-model:visible` / `onOk` / `onCancel` / `readonly` / `loading` / `footerVisible` / `#footer` 插槽），仅容器从 `el-drawer` 换成 `el-dialog`、尺寸走 `el-dialog` 的 `width`。§15 替换规范里**弹窗默认仍用 `ZlDrawer`**，只有明确要对话框时才用 `ZlDialog`。
1571
1581
 
@@ -1883,16 +1893,16 @@ treeRef.value.getCheckedKeys(true)
1883
1893
 
1884
1894
  ## 8. 布局与权限
1885
1895
 
1886
- ### ZlAppLayout / ZlAppMenu
1896
+ ### ZlAppLayout
1887
1897
 
1888
1898
  - `ZlAppLayout`：双形态布局骨架，用 `layout="horizontal" | "vertical"` 选形态（默认 `horizontal`），
1889
1899
  插槽为 `logo` / `menu` / `header` / `breadcrumb` / `footer` / 默认（详见 §3.7），vertical 形态自带折叠按钮（`el-button circle`）。
1890
- - `ZlAppMenu`(+Item)：`el-menu` 重写（index=menu.name），主题经 `--zl-menu-*` CSS 变量对接 `--el-menu-*`。
1900
+ - 菜单放进 `#menu` 插槽，用下面的 `ZlMenu` 渲染；`ZlAppMenu` 已移除（迁移见 §15.5）。
1891
1901
 
1892
1902
  ### ZlMenu — 通用菜单
1893
1903
 
1894
1904
  `el-menu` 的 schema 封装：`items` 递归渲染多级菜单，`v-model:selected` 双向绑定选中项。
1895
- 与 `ZlAppMenu`（应用布局专用）不同，它不依赖布局，选中态、折叠、水平/垂直、跳转回调都可独立使用。
1905
+ 不依赖布局，选中态、折叠、水平/垂直、跳转回调都可独立使用。
1896
1906
 
1897
1907
  ```vue
1898
1908
  <script setup lang="ts">
@@ -1955,7 +1965,25 @@ const items: MenuOption[] = [
1955
1965
  ]
1956
1966
  ```
1957
1967
 
1958
- 主题变量：`--zl-menu-text-color` / `--zl-menu-hover-bg`（与 `ZlAppMenu` 同口径）。
1968
+ 主题变量：`--zl-menu-text-color` / `--zl-menu-hover-bg`（与 `--el-menu-*` 对接，主题包已配置）。
1969
+
1970
+ ### ZlDevMenu — 开发菜单
1971
+
1972
+ 开发调试用的固定浮球：可拖拽（松手吸附右侧、保留垂直位置），点击展开路由搜索面板，选中即跳转。
1973
+
1974
+ ```vue
1975
+ <!-- 只在开发模式挂载，生产构建不会渲染 -->
1976
+ <ZlDevMenu v-if="isDev" />
1977
+
1978
+ <!-- 也可显式给路由与跳转方式（不依赖 vue-router 时同样能用） -->
1979
+ <ZlDevMenu :routes="[{ label: '首页', path: '/' }]" :navigate="(path) => console.log(path)" />
1980
+ ```
1981
+
1982
+ - **路由来源**：默认读宿主 `vue-router` 的 `getRoutes()`，文案取 `meta.title`，自动过滤重定向路由与带动态参数的路由；`routes` 可显式覆盖。
1983
+ - **零新增依赖**：不 import `vue-router`，通过 `globalProperties.$router` 取实例；宿主没装 vue-router 时面板为空。
1984
+ - **显隐**：用 `visible` 或 `v-if` 控制，组件自身不判断开发模式。
1985
+ - **方法**：暴露 `open()` / `close()`，可绑快捷键唤起。
1986
+ - 旧版 `DnDevMenu` 的微前端页签（`AppTabs`）部分已去掉，只保留路由快捷跳转。
1959
1987
 
1960
1988
  ### ZlPermission
1961
1989
 
@@ -4063,18 +4091,19 @@ const { i18n } = useLocale({ messages })
4063
4091
  | [`ZlActionList`](#zlactionlist) | 主入口 | 6 | 1 | 1 | 0 |
4064
4092
  | [`ZlAddSub`](#zladdsub) | 主入口 | 2 | 1 | 1 | 0 |
4065
4093
  | [`ZlAppLayout`](#zlapplayout) | 主入口 | 1 | 0 | 8 | 0 |
4066
- | [`ZlAppMenu`](#zlappmenu) | 主入口 | 3 | 1 | 0 | 0 |
4067
4094
  | [`ZlAppSlogan`](#zlappslogan) | 主入口 | 3 | 0 | 0 | 0 |
4068
4095
  | [`ZlAutoTooltip`](#zlautotooltip) | 主入口 | 0 | 0 | 1 | 0 |
4069
4096
  | [`ZlAvatar`](#zlavatar) | 主入口 | 3 | 0 | 0 | 0 |
4070
4097
  | [`ZlAvatarGroup`](#zlavatargroup) | 主入口 | 3 | 0 | 0 | 0 |
4071
4098
  | [`ZlBreadcrumb`](#zlbreadcrumb) | 主入口 | 2 | 0 | 1 | 0 |
4099
+ | [`ZlButton`](#zlbutton) | 主入口 | 19 | 0 | 0 | 0 |
4072
4100
  | [`ZlCard`](#zlcard) | 主入口 | 3 | 0 | 8 | 0 |
4073
4101
  | [`ZlCardPage`](#zlcardpage) | 主入口 | 7 | 1 | 3 | 3 |
4074
4102
  | [`ZlCheckAll`](#zlcheckall) | 主入口 | 2 | 1 | 0 | 0 |
4075
4103
  | [`ZlCheckboxTag`](#zlcheckboxtag) | 主入口 | 7 | 1 | 1 | 0 |
4076
4104
  | [`ZlCopy`](#zlcopy) | 主入口 | 2 | 0 | 2 | 0 |
4077
4105
  | [`ZlDescription`](#zldescription) | 主入口 | 5 | 0 | 1 | 0 |
4106
+ | [`ZlDevMenu`](#zldevmenu) | 主入口 | 7 | 0 | 0 | 2 |
4078
4107
  | [`ZlDialog`](#zldialog) | 主入口 | 7 | 1 | 2 | 0 |
4079
4108
  | [`ZlDictTag`](#zldicttag) | 主入口 | 10 | 0 | 0 | 0 |
4080
4109
  | [`ZlDrawer`](#zldrawer) | 主入口 | 7 | 1 | 2 | 0 |
@@ -4325,49 +4354,6 @@ import { ZlAppLayout } from '@zl-ui-kit/components'
4325
4354
  | `menu` | `v-bind="{ collapsed }"` 展开 | `<template #menu="{ collapsed }">…</template>` | 侧栏菜单区（作用域带 `{ collapsed }`） |
4326
4355
  | `footer` | — | `<template #footer>…</template>` | 侧栏底部区（排在内置折叠按钮之后，仅纵向形态有） |
4327
4356
 
4328
- #### `ZlAppMenu`
4329
-
4330
- <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAppMenu/AppMenu.vue`</sub>
4331
-
4332
- **接口概览**：3 props · 1 事件
4333
-
4334
- **用法示例**
4335
-
4336
- ```vue
4337
- <script setup lang="ts">
4338
- import { ZlAppMenu } from '@zl-ui-kit/components'
4339
- </script>
4340
-
4341
- <template>
4342
- <ZlAppMenu :menus="menus" />
4343
- </template>
4344
- ```
4345
-
4346
- > 示例中的 `menus` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
4347
-
4348
- **props**
4349
-
4350
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4351
- | ----------- | --------------------------------------- | ------------ | ---- | ------------------- | ----------------------------------- |
4352
- | `collapsed` | `boolean` | `false` | 否 | `collapsed` | 菜单是否收起为图标，侧栏折叠时用 |
4353
- | `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | 否 | `layout="vertical"` | el-menu 模式：vertical / horizontal |
4354
- | `menus` | `MenuItem[]`<br>— 条目字段见下「menus」 | `() => []` | 否 | `:menus="menus"` | 菜单树数据，递归渲染为多级菜单项 |
4355
-
4356
- **`menus` 条目字段（`MenuItem`）**
4357
-
4358
- | 字段 | 类型 | 必填 | 说明 |
4359
- | ---------- | ------------ | ---- | ------ |
4360
- | `name` | `string` | 是 | 唯一键 |
4361
- | `title` | `string` | 是 | — |
4362
- | `icon` | `string` | 否 | — |
4363
- | `children` | `MenuItem[]` | 否 | — |
4364
-
4365
- **事件（emits）**
4366
-
4367
- | 事件 | 参数 | 说明 |
4368
- | ----------------- | ---------- | ---------------------------------------------------------- |
4369
- | `menu-item-click` | `MenuItem` | 点击菜单项时触发，参数为被点击的菜单项配置（子项冒泡上来） |
4370
-
4371
4357
  #### `ZlAppSlogan`
4372
4358
 
4373
4359
  <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAppSlogan/index.vue`</sub>
@@ -4543,6 +4529,50 @@ import { ZlBreadcrumb } from '@zl-ui-kit/components'
4543
4529
  | ------ | ---------------------------- | ------------------------------ | ------------------------------------------------- |
4544
4530
  | `item` | `item` / `index` / `is-last` | `<template #item>…</template>` | 条目内容自定义，作用域含 { item, index, is-last } |
4545
4531
 
4532
+ #### `ZlButton`
4533
+
4534
+ <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlButton/index.vue`</sub>
4535
+
4536
+ **简介**：ZlButton —— `el-button` 全属性透传封装 显式声明 `el-button` 的全部 props（默认值统一为 `undefined`，不覆盖 EP 自身默认与 `el-form` 的 disabled 继承）， `default` / `icon` / `loading` 插槽与未声明的事件、…
4537
+
4538
+ **接口概览**：19 props
4539
+
4540
+ **用法示例**
4541
+
4542
+ ```vue
4543
+ <script setup lang="ts">
4544
+ import { ZlButton } from '@zl-ui-kit/components'
4545
+ </script>
4546
+
4547
+ <template>
4548
+ <ZlButton :type="'primary'"> 主要按钮 </ZlButton>
4549
+ </template>
4550
+ ```
4551
+
4552
+ **props**
4553
+
4554
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4555
+ | ----------------- | ---------------------------------------------------------------------------------- | ----------- | ---- | ----------------------------- | ------------------------------------------------------ |
4556
+ | `size` | `'large' \| 'default' \| 'small'` | `undefined` | 否 | `size="large"` | 尺寸；不传时沿用 `el-form` / 全局配置 |
4557
+ | `disabled` | `boolean` | `undefined` | 否 | `disabled` | 是否禁用；不传时沿用 `el-form` 的 disabled |
4558
+ | `type` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'info' \| 'danger' \| 'text'` | `undefined` | 否 | `type="default"` | 按钮类型 |
4559
+ | `icon` | `string \| Component` | `undefined` | 否 | `:icon="icon"` | 图标（同 el-button 的 icon，支持组件或已注册的组件名） |
4560
+ | `nativeType` | `'button' \| 'submit' \| 'reset'` | `undefined` | 否 | `native-type="button"` | 原生 type 属性 |
4561
+ | `loading` | `boolean` | `undefined` | 否 | `loading` | 是否加载中 |
4562
+ | `loadingIcon` | `string \| Component` | `undefined` | 否 | `:loading-icon="loadingIcon"` | 自定义加载图标 |
4563
+ | `plain` | `boolean` | `undefined` | 否 | `plain` | 是否为朴素按钮 |
4564
+ | `text` | `boolean` | `undefined` | 否 | `text` | 是否为文字按钮 |
4565
+ | `link` | `boolean` | `undefined` | 否 | `link` | 是否为链接按钮 |
4566
+ | `bg` | `boolean` | `undefined` | 否 | `bg` | 文字按钮是否始终显示背景 |
4567
+ | `autofocus` | `boolean` | `undefined` | 否 | `autofocus` | 是否自动聚焦 |
4568
+ | `round` | `boolean` | `undefined` | 否 | `round` | 是否为圆角按钮 |
4569
+ | `circle` | `boolean` | `undefined` | 否 | `circle` | 是否为圆形按钮 |
4570
+ | `dashed` | `boolean` | `undefined` | 否 | `dashed` | 是否为虚线按钮 |
4571
+ | `color` | `string` | `undefined` | 否 | `color="#409eff"` | 自定义颜色（自动计算 hover / active） |
4572
+ | `dark` | `boolean` | `undefined` | 否 | `dark` | 自定义颜色是否走暗色模式 |
4573
+ | `autoInsertSpace` | `boolean` | `undefined` | 否 | `auto-insert-space` | 两个汉字之间是否自动插入空格 |
4574
+ | `tag` | `string \| Record<string, any>` | `undefined` | 否 | `:tag="tag"` | 自定义渲染标签，默认 `button` |
4575
+
4546
4576
  #### `ZlCard`
4547
4577
 
4548
4578
  <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlCard/index.vue`</sub>
@@ -4893,6 +4923,54 @@ import { ZlDescription } from '@zl-ui-kit/components'
4893
4923
  | ------------ | ---------- | ------------------------------------ | -------------------------------------------- |
4894
4924
  | `[item.key]` | — | `<template #[item.key]>…</template>` | 按 item.key 命名，仅在该项开启 slot 时才渲染 |
4895
4925
 
4926
+ #### `ZlDevMenu`
4927
+
4928
+ <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlDevMenu/index.vue`</sub>
4929
+
4930
+ **简介**：ZlDevMenu —— 开发模式路由快捷菜单（可拖拽浮球） 点击浮球展开路由搜索面板，选中后跳转；不传 `routes` 时从宿主 `vue-router` 自动读取 （不新增依赖，通过 `globalProperties.$router` 取实例），显隐由宿主用 `visible` 或 `v-if` 控制。
4931
+
4932
+ **接口概览**：7 props · 2 暴露
4933
+
4934
+ **用法示例**
4935
+
4936
+ ```vue
4937
+ <script setup lang="ts">
4938
+ import { ZlDevMenu } from '@zl-ui-kit/components'
4939
+ </script>
4940
+
4941
+ <template>
4942
+ <ZlDevMenu :offset-bottom="120" title="开发菜单（点击展开）" :routes="routes" :navigate="() => {}" />
4943
+ </template>
4944
+ ```
4945
+
4946
+ > 示例中的 `routes`、`navigate` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
4947
+
4948
+ **props**
4949
+
4950
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4951
+ | -------------- | -------------------------------------------- | ------------ | ---- | ---------------------- | ----------------------------------------------------- |
4952
+ | `visible` | `boolean` | `true` | 否 | `:visible="false"` | 是否显示浮球（默认 true，通常由宿主结合开发模式控制） |
4953
+ | `routes` | `DevMenuRoute[]`<br>— 条目字段见下「routes」 | `undefined` | 否 | `:routes="routes"` | 路由列表；不传时从宿主 vue-router 自动读取 |
4954
+ | `navigate` | `(path: string) => void` | `undefined` | 否 | `:navigate="() => {}"` | 选中后的跳转方式；不传时调用宿主 `router.push` |
4955
+ | `draggable` | `boolean` | `true` | 否 | `:draggable="false"` | 是否可拖拽；松手后会吸附回右侧，保留垂直位置 |
4956
+ | `title` | `string` | `'开发菜单'` | 否 | `title="标题"` | 面板标题 |
4957
+ | `offsetRight` | `number` | `20` | 否 | `:offset-right="1"` | 距右侧距离（px） |
4958
+ | `offsetBottom` | `number` | `20` | 否 | `:offset-bottom="1"` | 距底部距离（px） |
4959
+
4960
+ **`routes` 条目字段（`DevMenuRoute`）**
4961
+
4962
+ | 字段 | 类型 | 必填 | 说明 |
4963
+ | ------- | -------- | ---- | -------------------------------------------------- |
4964
+ | `label` | `string` | 是 | 显示文本，默认取路由的 `meta.title`，无则用 `path` |
4965
+ | `path` | `string` | 是 | 跳转路径 |
4966
+
4967
+ **暴露（defineExpose）**
4968
+
4969
+ | 名称 | 说明 |
4970
+ | ------- | ------------ |
4971
+ | `open` | 展开路由面板 |
4972
+ | `close` | 收起路由面板 |
4973
+
4896
4974
  #### `ZlDialog`
4897
4975
 
4898
4976
  <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlDialog/index.vue`</sub>
@@ -5286,7 +5364,7 @@ import { ZlLoginForm } from '@zl-ui-kit/components'
5286
5364
 
5287
5365
  <sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlMenu/index.vue`</sub>
5288
5366
 
5289
- **简介**：ZlMenu —— 通用 el-menu 封装 与 ZlAppMenu（应用布局专用）的区别：items 数据驱动 + v-model:selected 选中态， 可选 navigate 回调做路由跳转，适用于侧栏 / 顶部导航等任意菜单场景。
5367
+ **简介**：ZlMenu —— 通用 el-menu 封装 items 数据驱动 + v-model:selected 选中态，可选 navigate 回调做路由跳转， 适用于侧栏 / 顶部导航等任意菜单场景（已取代原 `ZlAppMenu`）。
5290
5368
 
5291
5369
  **接口概览**：8 props · 2 事件
5292
5370
 
@@ -5648,12 +5726,10 @@ import { ZlIcon } from '@zl-ui-kit/components'
5648
5726
  </script>
5649
5727
 
5650
5728
  <template>
5651
- <ZlIcon :icon="icon" />
5729
+ <ZlIcon icon="zl:add" />
5652
5730
  </template>
5653
5731
  ```
5654
5732
 
5655
- > 示例中的 `icon` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
5656
-
5657
5733
  **插槽用法**
5658
5734
 
5659
5735
  ```vue
@@ -7351,6 +7427,17 @@ import { ZlFileViewer } from '@zl-ui-kit/components/file-preview'
7351
7427
  | `click` | `(item: BreadcrumbItem, index: number) => void` | 否 | 无 `to` 时的点击回调；最后一项不触发 |
7352
7428
  | `key` | `string \| number` | 否 | `v-for` 的 key，缺省用索引 |
7353
7429
 
7430
+ #### `DevMenuRoute`
7431
+
7432
+ <sub>源码 `packages/components/src/components/ZlDevMenu/types.ts`</sub>
7433
+
7434
+ 开发菜单路由项
7435
+
7436
+ | 字段 | 类型 | 必填 | 说明 |
7437
+ | ------- | -------- | ---- | -------------------------------------------------- |
7438
+ | `label` | `string` | 是 | 显示文本，默认取路由的 `meta.title`，无则用 `path` |
7439
+ | `path` | `string` | 是 | 跳转路径 |
7440
+
7354
7441
  #### `IComponent`
7355
7442
 
7356
7443
  <sub>源码 `packages/components/src/components/ZlDynamicComponent/types.ts`</sub>
@@ -7515,7 +7602,8 @@ ZlMenu 菜单项配置
7515
7602
  | `el-dialog` / `el-drawer` | `ZlDrawer` | 所有弹窗统一为抽屉 |
7516
7603
  | `el-form` | `ZlForm` | 弹窗内新增 / 编辑 / 详情表单（schema 驱动） |
7517
7604
  | `el-card` | `ZlCard` | 卡片容器 |
7518
- | `el-button`（操作栏 / 卡片内） | `ZlAction` | 操作列与卡片按钮；页面级独立按钮仍可用 `el-button` |
7605
+ | `el-button`（操作栏 / 卡片内） | `ZlAction` | 操作列与卡片内的按钮组用 `ZlAction`（汇总 / 折叠 / 权限） |
7606
+ | `el-button`（单颗按钮） | `ZlButton` | 全属性零语义透传，行为与 `el-button` 完全一致；也可继续直接用 `el-button` |
7519
7607
  | `el-tooltip`（超长省略） | `ZlAutoTooltip` | 文字溢出时自动提示 |
7520
7608
  | `el-icon` | `ZlIcon` | 需先注册图标集（§4.1） |
7521
7609
  | `el-tree` | `ZlTree` | 勾选多选 / 字段映射 / 暴露方法见 §7 › ZlTree |
@@ -7613,17 +7701,21 @@ ZlMenu 菜单项配置
7613
7701
 
7614
7702
  | 组件 | 差异 | 迁移注意 |
7615
7703
  | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7616
- | `ZlDrawer` | `width` 映射到内部 `size`（默认 `600`）；`destroy-on-close` **默认 `true`**（EP 默认 `false`）；自带底部取消 / 确定按钮区（`footerVisible=false` 可整体收起，`ZlDialog` 同） | 抽屉内容**关闭即销毁**，内部状态不保留；需保留状态时显式传 `:destroy-on-close="false"` |
7704
+ | `ZlDrawer` | `width` 映射到内部 `size`（默认 `600`）；`destroy-on-close` **默认 `true`**（EP 默认 `false`）；自带底部取消 / 确定按钮区（`footerVisible=false` 可整体收起，`ZlDialog` 同）；**未传 `onOk` 时点确定同样按 `auto-close-after-confirm` 关闭**（仅 ≥ 0.22.0，更早版本点确定无反应） | 抽屉内容**关闭即销毁**，内部状态不保留；需保留状态时显式传 `:destroy-on-close="false"` |
7705
+ | `ZlCopy` | 复制走 Clipboard API，非安全上下文 / 不支持时退回 `execCommand`；失败（权限拒绝等）会 `ElMessage.error`，不再假报成功；`#trigger` 作用域直接给出 `copy` 方法，可自行控制触发器 | **仅 ≥ 0.22.0**：更早版本 `copy()` 未被 `await`，复制失败也提示「复制成功」；且模块顶层读 `window.navigator`，SSR 下 import 即抛错 |
7617
7706
  | `ZlForm` | `validate()` / `validateField()` 与 `el-form` **完全同语义**（成功 `resolve(true)`、失败 `reject(invalidFields)`、支持 callback）；暴露 `el-form` 的 8 项能力 + `elForm` | **仅 ≥ 0.10.0**：0.9.0 及更早成功时返回 `undefined`（签名为 `Promise<void>`），`const ok = await formRef.validate()` 判为 falsy；需 `el-form` 未暴露的方法时用 `formRef.elForm` |
7618
7707
  | `ZlTable` | 列插槽按 `prop` 名命名，作用域含 `{ row, column, $index }`；暴露 `el-table` 的 15 个公开方法 + `elTable` getter | `tableRef.toggleRowSelection(row)` 等均有类型提示；其余方法走 `tableRef.elTable` |
7619
7708
  | `ZlSwitch` | 主名 `checked-value` / `unchecked-value`，同时**兼容 EP 的 `active-value` / `inactive-value` 别名**（同传时主名优先）；`@change` 参数是**业务值**而非内部布尔 | 直搬 `:active-value="'1'"` 可用；从 `el-switch` 迁移时注意 `@change` 入参含义已变 |
7620
7709
  | `ZlTabs` | schema 驱动：`tab.key`→`name`、`tab.title`→`label`；页签内容**默认懒挂载**（`lazy` / `lazyLoad` 默认 `true`）；内容写在以 key 命名的插槽里；`border` **默认 `false`**（不显示导航下分隔线，与 EP 默认显示相反） | 需挂载时就初始化的页签要显式 `lazyLoad: false`；需要导航分隔线时显式传 `border`；`type` / `tab-click` 等透传 `el-tabs` |
7710
+ | `ZlButton` | 纯透传：EP 的 19 个属性全部显式声明，默认值统一 `undefined`（不覆盖 EP 默认与 `el-form` 继承），无自定义样式；`default` / `icon` / `loading` 插槽**仅在调用方传入时**才转发（否则会盖掉同名 prop 的默认渲染） | 想改样式直接覆盖 `.zl-button` 或 `.el-button`；不要期待它有额外行为 |
7711
+ | `ZlDevMenu` | 不依赖 `vue-router` 包：通过 `globalProperties.$router` 取实例（无路由时面板为空）；浮球 `fixed` 定位，松手吸附右侧并保留垂直位置；**不含微前端页签**（旧 `DnDevMenu` 的 `AppTabs` 已移除） | 生产环境务必用 `v-if` / `visible` 关掉；路由文案取 `meta.title`，未设置时显示 `path` |
7621
7712
  | `ZlBreadcrumb` | `items` schema 驱动：末项自动置为当前页（即使带 `to` 也不跳转、不触发 `click`）；`separator` / `separator-icon` 与 `el-breadcrumb` 同义，其余属性与事件透传 | 需要末项可点击时把它放到倒数第二项，或用 `#item` 自行渲染 |
7622
7713
  | `ZlIcon` | 单色图标：尺寸走 `size`（作用在 `font-size`），颜色走 `color` / `currentColor`；`spin` / `rotate` 等仅 `zl:` 前缀（iconify）分支生效 | 图标名未注册或拼错时**不报错、不告警、只渲染空白**；迁移前用 `@zl-ui-kit/icons` 核名（见 §4.1） |
7623
7714
  | `ZlTree` | 勾选多选 / 字段映射 / 暴露方法的完整说明见 §7 › ZlTree | 从 `el-tree` 直搬时先核对 `node-key` 与字段映射 |
7624
7715
  | `ZlUpload` | 自带 `httpRequest` 取代 EP 默认 XHR：`action` / `headers` / `method` / `data` / `name` / `with-credentials` **不生效**；`#file` / `#tip` 转发给调用方（**仅 ≥ 0.21.0**，更早版本这两个插槽不转发）；`before-upload` 与内置校验组合（**仅 ≥ 0.21.0**，更早版本会整段覆盖调用方钩子）；暴露 `submit` / `clearFiles` / `abort` / `handleStart` / `handleRemove`（更早版本无 expose） | 认证头写进 `request` 的请求头；`auto-upload=false` 时必须自己调 `submit()`；传 `#file` 后不再套用内置卡片样式 |
7625
7716
  | `ZlEditor` / `ZlSqlEditor` | 暴露对象是 `Proxy`：§14 列的是显式能力，未列出的 monaco 原生 API 靠运行时下钻（旧行为，**不算契约**）；`ZlSqlEditor.validate()` 不通过时 **`throw diagnostics`** | 需要原生能力时用 `editorRef.value.monacoEditor`（SQL 编辑器用 `.zlEditor`）；`format()` 内部会先校验 |
7626
- | `ZlAppLayout` | 只声明 `layout`（`horizontal` / `vertical`）；插槽由同目录形态子组件定义（`footer` 仅 vertical，`logo` / `menu` 在 vertical 下带 `{ collapsed }`） | 菜单数据传给 `#menu` 里的 `ZlAppMenu`，**不要写 `:menus="…"` 给 `ZlAppLayout`**（未声明的 prop 会落到 DOM） |
7717
+ | `ZlAppLayout` | 只声明 `layout`（`horizontal` / `vertical`）；插槽由同目录形态子组件定义（`footer` 仅 vertical，`logo` / `menu` 在 vertical 下带 `{ collapsed }`） | 菜单放进 `#menu` 用 `ZlMenu` 渲染，**不要写 `:items="…"` / `:menus="…"` 给 `ZlAppLayout`**（未声明的 prop 会落到 DOM） |
7718
+ | `ZlAppMenu`（已移除） | 与 `ZlMenu` 重复：`ZlMenu` 是其超集（`v-model:selected`、`navigate`、`disabled`、`uniqueOpened`、`defaultOpeneds`、图标支持组件 / VNode）；**自 0.22.0 起移除**，`ZlAppMenuItem` 与 `MenuItem` 类型一并移除 | 迁移：`menus`→`items`、`name`→`key`、`title`→`label`、`layout`→`mode`、`menu-item-click`→`select`（`(key, item)`）+ `navigate`；`MenuOption` 替代原 `MenuItem` 类型 |
7627
7719
  | `ZlDictTag` | 字典项的 `type` 从 **0.10.1** 起参与上色（`color ?? type`，`info` → `gray`）；更早版本只读 `color`，传 `type` 一律默认配色 | 升级后原来“无色”的标签会变有色（预期修正，属视觉变更，需回归）；直传 `:dict` 会覆盖全局同名 `dictKey` 缓存 |
7628
7720
  | 普通单选 / 复选框 | **有意不封装**：库内只有标签式的 `ZlRadioTag` / `ZlCheckboxTag` 与自带半选的 `ZlCheckAll` | `el-radio` / `el-checkbox` / `el-radio-group` / `el-checkbox-group` **继续用 `el-*`**，不要找 Zl 对应物；表头全选 / 半选场景可直接用 `ZlCheckAll` |
7629
7721
 
package/dist/components/ZlButton/index.vue.d.ts ADDED
@@ -0,0 +1,64 @@
1
+ import { Component } from 'vue';
2
+ type __VLS_Props = {
3
+ /** 尺寸；不传时沿用 `el-form` / 全局配置 */
4
+ size?: 'large' | 'default' | 'small';
5
+ /** 是否禁用；不传时沿用 `el-form` 的 disabled */
6
+ disabled?: boolean;
7
+ /** 按钮类型 */
8
+ type?: 'default' | 'primary' | 'success' | 'warning' | 'info' | 'danger' | 'text';
9
+ /** 图标（同 el-button 的 icon，支持组件或已注册的组件名） */
10
+ icon?: string | Component;
11
+ /** 原生 type 属性 */
12
+ nativeType?: 'button' | 'submit' | 'reset';
13
+ /** 是否加载中 */
14
+ loading?: boolean;
15
+ /** 自定义加载图标 */
16
+ loadingIcon?: string | Component;
17
+ /** 是否为朴素按钮 */
18
+ plain?: boolean;
19
+ /** 是否为文字按钮 */
20
+ text?: boolean;
21
+ /** 是否为链接按钮 */
22
+ link?: boolean;
23
+ /** 文字按钮是否始终显示背景 */
24
+ bg?: boolean;
25
+ /** 是否自动聚焦 */
26
+ autofocus?: boolean;
27
+ /** 是否为圆角按钮 */
28
+ round?: boolean;
29
+ /** 是否为圆形按钮 */
30
+ circle?: boolean;
31
+ /** 是否为虚线按钮 */
32
+ dashed?: boolean;
33
+ /** 自定义颜色（自动计算 hover / active） */
34
+ color?: string;
35
+ /** 自定义颜色是否走暗色模式 */
36
+ dark?: boolean;
37
+ /** 两个汉字之间是否自动插入空格 */
38
+ autoInsertSpace?: boolean;
39
+ /** 自定义渲染标签，默认 `button` */
40
+ tag?: string | Record<string, any>;
41
+ };
42
+ declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
43
+ icon: string | Component;
44
+ size: "large" | "default" | "small";
45
+ color: string;
46
+ link: boolean;
47
+ circle: boolean;
48
+ text: boolean;
49
+ round: boolean;
50
+ dashed: boolean;
51
+ dark: boolean;
52
+ disabled: boolean;
53
+ type: "default" | "primary" | "success" | "warning" | "info" | "danger" | "text";
54
+ nativeType: "button" | "submit" | "reset";
55
+ loading: boolean;
56
+ loadingIcon: string | Component;
57
+ plain: boolean;
58
+ bg: boolean;
59
+ autofocus: boolean;
60
+ autoInsertSpace: boolean;
61
+ tag: string | Record<string, any>;
62
+ }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
63
+ export default _default;
64
+ //# sourceMappingURL=index.vue.d.ts.map
package/dist/components/ZlButton/index.vue.mjs ADDED
@@ -0,0 +1,44 @@
1
+ import { defineComponent as f, useAttrs as c, useSlots as r, computed as p, mergeProps as t, resolveComponent as v, resolveDirective as B, withDirectives as y, openBlock as m, createBlock as _ } from "vue";
2
+ const h = /* @__PURE__ */ f({
3
+ name: "ZlButton",
4
+ inheritAttrs: !1,
5
+ __name: "index",
6
+ props: {
7
+ size: { default: void 0 },
8
+ disabled: { type: Boolean, default: void 0 },
9
+ type: { default: void 0 },
10
+ icon: { default: void 0 },
11
+ nativeType: { default: void 0 },
12
+ loading: { type: Boolean, default: void 0 },
13
+ loadingIcon: { default: void 0 },
14
+ plain: { type: Boolean, default: void 0 },
15
+ text: { type: Boolean, default: void 0 },
16
+ link: { type: Boolean, default: void 0 },
17
+ bg: { type: Boolean, default: void 0 },
18
+ autofocus: { type: Boolean, default: void 0 },
19
+ round: { type: Boolean, default: void 0 },
20
+ circle: { type: Boolean, default: void 0 },
21
+ dashed: { type: Boolean, default: void 0 },
22
+ color: { default: void 0 },
23
+ dark: { type: Boolean, default: void 0 },
24
+ autoInsertSpace: { type: Boolean, default: void 0 },
25
+ tag: { default: void 0 }
26
+ },
27
+ setup(l) {
28
+ const a = l, d = c(), o = r(), n = p(() => t(d, a));
29
+ function i() {
30
+ const e = {};
31
+ return o.default && (e.default = o.default), o.icon && (e.icon = o.icon), o.loading && (e.loading = o.loading), e;
32
+ }
33
+ return (e, g) => {
34
+ const u = v("el-button"), s = B("slots");
35
+ return y((m(), _(u, t(n.value, { class: "zl-button" }), null, 16)), [
36
+ [s, i()]
37
+ ]);
38
+ };
39
+ }
40
+ });
41
+ export {
42
+ h as default
43
+ };
44
+ //# sourceMappingURL=index.vue.mjs.map
package/dist/components/ZlButton/index2.vue.mjs ADDED
@@ -0,0 +1,5 @@
1
+ import f from "./index.vue.mjs";
2
+ export {
3
+ f as default
4
+ };
5
+ //# sourceMappingURL=index2.vue.mjs.map