@zl-ui-kit/components 0.8.3 → 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.
- package/README.md +444 -179
- package/dist/components/ZlAddSub/index.css +1 -1
- package/dist/components/ZlAddSub/index.vue.mjs +2 -2
- package/dist/components/ZlAppMenu/AppMenu.vue.d.ts +1 -1
- package/dist/components/ZlCardPage/index.vue.d.ts +94 -36
- package/dist/components/ZlCardPage/index.vue.mjs +2 -0
- package/dist/components/ZlChart/index.vue.d.ts +1 -0
- package/dist/components/ZlChart/index.vue.mjs +1 -0
- package/dist/components/ZlCheckAll/index.css +1 -1
- package/dist/components/ZlCheckAll/index.vue.mjs +1 -1
- package/dist/components/ZlDynamicComponent/index.vue.d.ts +8 -3
- package/dist/components/ZlDynamicComponent/index.vue.mjs +24 -19
- package/dist/components/ZlEditor/ZlSqlEditor.vue.d.ts +28 -2
- package/dist/components/ZlEditor/ZlSqlEditor.vue.mjs +27 -18
- package/dist/components/ZlEditor/index.vue.d.ts +22 -1
- package/dist/components/ZlEditor/index.vue.mjs +47 -24
- package/dist/components/ZlForm/index.vue.d.ts +26 -2
- package/dist/components/ZlForm/index.vue.mjs +96 -90
- package/dist/components/ZlGrid/index.vue.d.ts +1 -1
- package/dist/components/ZlIcon/index.css +1 -1
- package/dist/components/ZlIcon/index.vue.d.ts +6 -2
- package/dist/components/ZlIcon/index.vue.mjs +2 -2
- package/dist/components/ZlIcon/index2.vue.mjs +30 -23
- package/dist/components/ZlPagination/index.css +1 -1
- package/dist/components/ZlPagination/index.vue.mjs +1 -1
- package/dist/components/ZlSearch/index.vue.d.ts +82 -23
- package/dist/components/ZlSearch/index.vue.mjs +8 -1
- package/dist/components/ZlSearchTable/index.vue.d.ts +180 -40
- package/dist/components/ZlSearchTable/index.vue.mjs +4 -0
- package/dist/components/ZlSorter/ZlSorterList.css +1 -1
- package/dist/components/ZlSorter/ZlSorterList.vue.d.ts +1 -1
- package/dist/components/ZlSorter/ZlSorterList.vue.mjs +2 -2
- package/dist/components/ZlSorter/index.css +1 -1
- package/dist/components/ZlSorter/index.vue.mjs +2 -2
- package/dist/components/ZlSwitch/index.vue.d.ts +6 -2
- package/dist/components/ZlSwitch/index.vue.mjs +26 -24
- package/dist/components/ZlTable/index.vue.d.ts +36 -1
- package/dist/components/ZlTable/index.vue.mjs +98 -75
- package/dist/components/ZlTabs/index.vue.d.ts +20 -3
- package/dist/components/ZlTabs/index.vue.mjs +30 -20
- package/dist/components/ZlTag/index.vue.d.ts +2 -2
- package/dist/components/ZlTree/index.vue.d.ts +83 -2
- package/dist/components/ZlTree/index.vue.mjs +218 -71
- 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` 前缀，
|
|
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
|
-
**本页即完整使用文档**：安装与四个导入入口、
|
|
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. 组件总览（
|
|
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 国际化基础设施（独立于
|
|
27
|
+
- [3.6 国际化基础设施（独立于 55 个业务组件）](#36-国际化基础设施独立于-55-个业务组件)
|
|
28
28
|
- [3.7 内部子组件（不对外导出，随父组件使用）](#37-内部子组件不对外导出随父组件使用)
|
|
29
29
|
- [4. 图标组件 `ZlIcon`](#4-图标组件-zlicon)
|
|
30
30
|
- [4.1 必须先注册图标集（否则一个图标都不显示）](#41-必须先注册图标集否则一个图标都不显示)
|
|
@@ -48,6 +48,7 @@ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，47 个业务组
|
|
|
48
48
|
- [ZlAction / ZlActionList —— 操作列与操作列表](#zlaction-zlactionlist-操作列与操作列表)
|
|
49
49
|
- [ZlRadioTag / ZlCheckboxTag / ZlCheckAll / ZlSorter / ZlAddSub / ZlLayoutSwitch](#zlradiotag-zlcheckboxtag-zlcheckall-zlsorter-zladdsub-zllayoutswitch)
|
|
50
50
|
- [ZlTabs / ZlDynamicComponent / ZlGrid](#zltabs-zldynamiccomponent-zlgrid)
|
|
51
|
+
- [ZlTree —— 树形控件（多选 / 暴露方法）](#zltree-树形控件多选-暴露方法)
|
|
51
52
|
- [8. 布局与权限](#8-布局与权限)
|
|
52
53
|
- [ZlAppLayout / ZlAppMenu](#zlapplayout-zlappmenu)
|
|
53
54
|
- [ZlPermission](#zlpermission)
|
|
@@ -87,6 +88,7 @@ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，47 个业务组
|
|
|
87
88
|
- [15.2 常用 el-* → Zl-* 对照表（持续补充）](#152-常用-el--zl--对照表持续补充)
|
|
88
89
|
- [15.3 列表页操作按钮归位（search-actions 插槽）](#153-列表页操作按钮归位search-actions-插槽)
|
|
89
90
|
- [15.4 宿主工具方法 → `@zl-ui-kit/utils` 替换对照（持续补充）](#154-宿主工具方法-zl-ui-kitutils-替换对照持续补充)
|
|
91
|
+
- [15.5 迁移行为差异与透传契约（必读）](#155-迁移行为差异与透传契约必读)
|
|
90
92
|
|
|
91
93
|
<!-- TOC:END -->
|
|
92
94
|
|
|
@@ -98,9 +100,9 @@ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，47 个业务组
|
|
|
98
100
|
|
|
99
101
|
| 包 | 职责 |
|
|
100
102
|
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
101
|
-
| [`@zl-ui-kit/components`](https://www.npmjs.com/package/@zl-ui-kit/components) | EP 化业务组件库（`Zl` 前缀，
|
|
103
|
+
| [`@zl-ui-kit/components`](https://www.npmjs.com/package/@zl-ui-kit/components) | EP 化业务组件库（`Zl` 前缀，55 个业务组件） |
|
|
102
104
|
| [`@zl-ui-kit/composables`](https://www.npmjs.com/package/@zl-ui-kit/composables) | `useRequest` 请求体系、`useDict`、`useGlobalData` 全局数据、国际化 |
|
|
103
|
-
| [`@zl-ui-kit/icons`](https://www.npmjs.com/package/@zl-ui-kit/icons) |
|
|
105
|
+
| [`@zl-ui-kit/icons`](https://www.npmjs.com/package/@zl-ui-kit/icons) | 470 个离线 SVG 图标（prefix `zl`，开源图标库） |
|
|
104
106
|
| [`@zl-ui-kit/theme`](https://www.npmjs.com/package/@zl-ui-kit/theme) | 5 套主题 + `defineTheme` 运行时定制（内置 OFL 开源中文字体） |
|
|
105
107
|
| [`@zl-ui-kit/utils`](https://www.npmjs.com/package/@zl-ui-kit/utils) | TS 工具函数库 + Axios 请求封装 |
|
|
106
108
|
|
|
@@ -300,11 +302,11 @@ import { ZlI18nProvider } from '@zl-ui-kit/components'
|
|
|
300
302
|
|
|
301
303
|
#### 1.2.3 组件注册的三种方式（以及 EP 的坑）
|
|
302
304
|
|
|
303
|
-
| 方式 | 写法 | 适用
|
|
304
|
-
| ----------- | --------------------------------------------------------------------- |
|
|
305
|
-
| 全量插件 | `app.use(ZlUI)` |
|
|
306
|
-
| 按名注册 | `app.component('ZlTable', ZlTable)` | 只要几个组件，控制产物
|
|
307
|
-
| 直接 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'` | 单文件用一次，无需全局 |
|
|
308
310
|
|
|
309
311
|
> ⚠️ **不管用哪种，Element Plus 的组件都必须能被「按名」解析到。**
|
|
310
312
|
> `@zl-ui-kit/components` 发布的是**编译后的 render 函数**，内部用 `resolveComponent('el-select')` 之类按名取组件，**不是模板**。所以 `unplugin-vue-components` 的 ElementPlusResolver **改不到它**（那个插件只处理源码里的模板标签）。
|
|
@@ -421,9 +423,9 @@ setTheme('dark') // 切换主题（light/dark/red-light/red-dark/blue）
|
|
|
421
423
|
|
|
422
424
|
---
|
|
423
425
|
|
|
424
|
-
## 3. 组件总览（
|
|
426
|
+
## 3. 组件总览（55 个业务组件）
|
|
425
427
|
|
|
426
|
-
>
|
|
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 个。
|
|
427
429
|
|
|
428
430
|
> **要查精确的 props / 事件 / 插槽 / 暴露方法 / schema 类型？** 直接看 **[§14 组件 API 参考](#14-组件-api-参考自动生成)**——逐个组件给出 `import`、可直接照抄的 **用法示例**（props 怎么写）与 **插槽用法**（`<template #name>` 怎么写），再用表格列出 TS 类型表达式、默认值、是否必填，**且每个 prop / 每个插槽都带一列「示例」**（能直接粘到标签上的写法），以及 `TableColumn` / `FormItem` / `SearchItem` / `ActionItem` 等 schema 类型的字段表。本章及 §4~§9 讲的是**场景化用法**，§14 是**逐字段的契约 + 可粘贴代码**。
|
|
429
431
|
|
|
@@ -445,11 +447,11 @@ setTheme('dark') // 切换主题（light/dark/red-light/red-dark/blue）
|
|
|
445
447
|
|
|
446
448
|
### 3.5 文件与编辑
|
|
447
449
|
|
|
448
|
-
`ZlFilePreview` · `ZlFileFetchError` · `ZlFileViewer` · `ZlPdfViewer` · `ZlEditor` · `ZlSqlEditor` · `ZlLogin`
|
|
450
|
+
`ZlFilePreview` · `ZlFileFetchError` · `ZlFileViewer` · `ZlPdfViewer` · `ZlEditor` · `ZlSqlEditor` · `ZlLogin` · `ZlLoginForm`
|
|
449
451
|
|
|
450
452
|
> 页签/微前端类组件（`ZlMicroPage`/`ZlAppTabs`/`ZlPageTabs`/`ZlDevMenu`）与配套 composables（`usePageTabs` 等）均已移除，`0.5.0` 起组件库不含任何微前端能力。
|
|
451
453
|
|
|
452
|
-
### 3.6 国际化基础设施（独立于
|
|
454
|
+
### 3.6 国际化基础设施（独立于 55 个业务组件）
|
|
453
455
|
|
|
454
456
|
`ZlI18nProvider` —— 国际化根容器，将 Element Plus 语言包经 `<el-config-provider>` 挂载到 Element Plus（详见第 13 章）。
|
|
455
457
|
|
|
@@ -473,15 +475,17 @@ setTheme('dark') // 切换主题（light/dark/red-light/red-dark/blue）
|
|
|
473
475
|
|
|
474
476
|
#### `ZlHorizontalLayout` / `ZlVerticalLayout` —— 布局形态（供 `ZlAppLayout` 分发）
|
|
475
477
|
|
|
476
|
-
由 `ZlAppLayout` 的 `horizontal
|
|
478
|
+
由 `ZlAppLayout` 的 `layout`（`'horizontal'`（默认）/ `'vertical'`）二选一渲染，不单独使用。
|
|
479
|
+
`ZlAppLayout` **只声明 `layout` 一个 prop**，插槽一律写在 `ZlAppLayout` 标签内；菜单数据自己传给 `#menu` 里的
|
|
480
|
+
`ZlAppMenu`（传 `:menus` 给 `ZlAppLayout` 是无效的——它不声明该 prop）：
|
|
477
481
|
|
|
478
482
|
```vue
|
|
479
|
-
<ZlAppLayout
|
|
483
|
+
<ZlAppLayout layout="vertical">
|
|
480
484
|
<template #logo>
|
|
481
485
|
<img src="/logo.svg" />
|
|
482
486
|
</template>
|
|
483
487
|
<template #menu>
|
|
484
|
-
<!--
|
|
488
|
+
<!-- 各形态自行放菜单，如 <ZlAppMenu :menus="menus" /> -->
|
|
485
489
|
</template>
|
|
486
490
|
<template #breadcrumb>
|
|
487
491
|
<el-breadcrumb />
|
|
@@ -521,22 +525,26 @@ vertical 形态的 `logo` / `menu` 插槽会收到 `{ collapsed }`，可据此
|
|
|
521
525
|
|
|
522
526
|
## 4. 图标组件 `ZlIcon`
|
|
523
527
|
|
|
524
|
-
底层为 `@iconify/vue` 离线渲染，图标名以 `zl:` 前缀引用，全部来自内置的
|
|
528
|
+
底层为 `@iconify/vue` 离线渲染，图标名以 `zl:` 前缀引用，全部来自内置的 470 个开源图标。
|
|
525
529
|
|
|
526
530
|
```vue
|
|
527
531
|
<ZlIcon icon="zl:add-color" />
|
|
528
532
|
<ZlIcon icon="zl:database-color" :size="20" />
|
|
533
|
+
<ZlIcon icon="zl:refresh" color="var(--zl-primary)" spin />
|
|
529
534
|
```
|
|
530
535
|
|
|
531
|
-
| prop
|
|
532
|
-
|
|
|
533
|
-
| `icon`
|
|
534
|
-
| `size`
|
|
535
|
-
| `color`
|
|
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` 就能变色，不需要多色图标集。
|
|
536
544
|
|
|
537
545
|
### 4.1 必须先注册图标集（否则一个图标都不显示）
|
|
538
546
|
|
|
539
|
-
`ZlIcon` 走 `@iconify/vue/offline`，**库不会自动把
|
|
547
|
+
`ZlIcon` 走 `@iconify/vue/offline`，**库不会自动把 470 个图标塞进打包结果**（否则不用图标的宿主也会白扛 ~150KB）。
|
|
540
548
|
消费方需要在应用启动时把内置图标集注册进 offline 集合，只需一次：
|
|
541
549
|
|
|
542
550
|
```ts
|
|
@@ -892,9 +900,11 @@ const { data: treeData, loading: treeLoading } = treeReq
|
|
|
892
900
|
```
|
|
893
901
|
|
|
894
902
|
```vue
|
|
895
|
-
<ZlTree v-if="!treeLoading" :data="treeData" :
|
|
903
|
+
<ZlTree v-if="!treeLoading" :data="treeData" disable-filter :field-names="{ key: 'id', title: 'name' }" />
|
|
896
904
|
```
|
|
897
905
|
|
|
906
|
+
字段映射用 `fieldNames`（不是 `el-tree` 的 `props`）；多选的勾选取值见 §7 › ZlTree。
|
|
907
|
+
|
|
898
908
|
#### ⑧ `ZlChart` —— `useDataRequest` 解包后构建 option
|
|
899
909
|
|
|
900
910
|
`ZlChart` 显式 prop 为 `series`，其余配置（title/xAxis/yAxis/tooltip/grid）经 attrs 透传，故用 `v-bind` 传完整 echarts option：
|
|
@@ -1074,13 +1084,77 @@ const statusActions = (item: Item): ActionItem[] => [
|
|
|
1074
1084
|
- `ZlDynamicComponent`：schema→VNode 渲染引擎，默认 `el-input`。
|
|
1075
1085
|
- `ZlGrid`(+`ZlGridItem`)：自绘栅格，label 自适应/跨列/省略提示/字典。
|
|
1076
1086
|
|
|
1087
|
+
### ZlTree —— 树形控件（多选 / 暴露方法）
|
|
1088
|
+
|
|
1089
|
+
`el-tree` 的封装：自带搜索框、节点图标与超长省略，**其余 `el-tree` 属性与事件原样透传**
|
|
1090
|
+
（懒加载 `load` / `lazy`、拖拽 `draggable`、`accordion`、`check-on-click-node`、`@node-click` 等直接写即可）。
|
|
1091
|
+
|
|
1092
|
+
**字段映射**（arco `fieldNames` 兼容，不用再传 `:props`）：
|
|
1093
|
+
|
|
1094
|
+
```vue
|
|
1095
|
+
<ZlTree :data="treeData" :field-names="{ key: 'id', title: 'name', children: 'items', disabled: 'locked' }" />
|
|
1096
|
+
```
|
|
1097
|
+
|
|
1098
|
+
| 字段 | 作用 |
|
|
1099
|
+
| ---------- | --------------------------------------------------------------------- |
|
|
1100
|
+
| `key` | 节点唯一标识字段（同时作为 `node-key`，勾选 / 展开 / 取值都按它匹配） |
|
|
1101
|
+
| `title` | 显示文本字段（对应 `el-tree` 的 `props.label`） |
|
|
1102
|
+
| `children` | 子级字段 |
|
|
1103
|
+
| `disabled` | 数据里的布尔字段名 → 节点置灰且**不可勾选** |
|
|
1104
|
+
| `isLeaf` | 数据里的布尔字段名 → 强制视为叶子（懒加载判断有没有下一级） |
|
|
1105
|
+
|
|
1106
|
+
> 需要按业务规则动态禁用时直接传 `:props="{ disabled: (data) => xxx }"`：该写法与 `fieldNames`
|
|
1107
|
+
> **合并生效**（只覆盖同名项，`label`/`children` 不丢）。
|
|
1108
|
+
|
|
1109
|
+
**多选（复选框）** —— 取值有两种写法，按需选一种：
|
|
1110
|
+
|
|
1111
|
+
```vue
|
|
1112
|
+
<!-- ① 受控：勾选态由外部数据管理，提交时直接用 checkedKeys -->
|
|
1113
|
+
<ZlTree
|
|
1114
|
+
v-model:checked-keys="checkedKeys"
|
|
1115
|
+
v-model:half-checked-keys="halfCheckedKeys"
|
|
1116
|
+
show-checkbox
|
|
1117
|
+
:data="treeData"
|
|
1118
|
+
/>
|
|
1119
|
+
|
|
1120
|
+
<!-- ② 命令式：只在需要时向实例取值 -->
|
|
1121
|
+
<ZlTree ref="treeRef" show-checkbox check-strictly :data="treeData" />
|
|
1122
|
+
```
|
|
1123
|
+
|
|
1124
|
+
```ts
|
|
1125
|
+
// ② 里的取法：leafOnly 只要叶子；includeHalfChecked 连半选一起返回
|
|
1126
|
+
treeRef.value.getCheckedNodes(false, true)
|
|
1127
|
+
treeRef.value.getCheckedKeys(true)
|
|
1128
|
+
```
|
|
1129
|
+
|
|
1130
|
+
- `check-strictly`：父子不关联，每个节点独立勾选；
|
|
1131
|
+
- `check-descendants`：勾选父节点时联动勾选全部子孙；
|
|
1132
|
+
- 受控 `checked-keys` 由组件写回树，**不要再同时传 `default-checked-keys`**（两份初始值会互相覆盖）；
|
|
1133
|
+
非受控场景用 `el-tree` 原生的 `default-checked-keys` / `default-expanded-keys` 透传即可。
|
|
1134
|
+
|
|
1135
|
+
**暴露方法**（完整逐条说明见 §14 `ZlTree` 的「暴露」表，模板 ref 调用）：
|
|
1136
|
+
|
|
1137
|
+
| 场景 | 方法 |
|
|
1138
|
+
| ------ | ------------------------------------------------------------------------------------------------------ |
|
|
1139
|
+
| 勾选 | `getCheckedKeys` / `getCheckedNodes` / `getHalfCheckedKeys` / `getHalfCheckedNodes` / `setChecked` |
|
|
1140
|
+
| 批量 | `setCheckedKeys` / `setAllChecked(true)` 全选 / `clearChecked()` 清空 |
|
|
1141
|
+
| 高亮 | `getCurrentKey` / `getCurrentNode` / `setCurrentKey` / `setCurrentNode` |
|
|
1142
|
+
| 展开 | `expandAll` / `collapseAll` / `filter('关键字')`（与内置搜索框同步） |
|
|
1143
|
+
| 改数据 | `getNode` / `getNodePath` / `updateKeyChildren` / `append` / `insertBefore` / `insertAfter` / `remove` |
|
|
1144
|
+
| 兜底 | `elTree`：内部 `el-tree` 实例，未列出的原生能力从这里取 |
|
|
1145
|
+
|
|
1146
|
+
**自定义节点**：`#title` 只换标题（保留内置图标与省略号）、`#icon` 只换图标、`#default` 接管整个节点
|
|
1147
|
+
（与 `el-tree` 的 `#default` 写法一致，内置图标/省略号会被替掉）。playground `/component/ZlTree` 有
|
|
1148
|
+
「勾选多选 + 业务禁用 + 全选/清空/展开/收起」的可交互示例。
|
|
1149
|
+
|
|
1077
1150
|
---
|
|
1078
1151
|
|
|
1079
1152
|
## 8. 布局与权限
|
|
1080
1153
|
|
|
1081
1154
|
### ZlAppLayout / ZlAppMenu
|
|
1082
1155
|
|
|
1083
|
-
- `ZlAppLayout
|
|
1156
|
+
- `ZlAppLayout`：双形态布局骨架，用 `layout="horizontal" | "vertical"` 选形态（默认 `horizontal`），
|
|
1157
|
+
插槽为 `logo` / `menu` / `header` / `breadcrumb` / `footer` / 默认（详见 §3.7），vertical 形态自带折叠按钮（`el-button circle`）。
|
|
1084
1158
|
- `ZlAppMenu`(+Item)：`el-menu` 重写（index=menu.name），主题经 `--zl-menu-*` CSS 变量对接 `--el-menu-*`。
|
|
1085
1159
|
|
|
1086
1160
|
### ZlPermission
|
|
@@ -1097,6 +1171,10 @@ const statusActions = (item: Item): ActionItem[] => [
|
|
|
1097
1171
|
|
|
1098
1172
|
- `ZlFilePreview` / `ZlFileViewer` / `ZlPdfViewer`：文件预览（含 PDF），样例见 `/general`。
|
|
1099
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）。
|
|
1100
1178
|
- `ZlLogin`(+`LoginForm`+`SlideChecker`)：登录框，背景改半透明 + `backdrop-filter`。
|
|
1101
1179
|
|
|
1102
1180
|
### 9.1 `ZlEditor`：monaco worker 配置与首屏治理
|
|
@@ -3099,7 +3177,7 @@ const { i18n } = useLocale({ messages })
|
|
|
3099
3177
|
| [`ZlAction`](#zlaction) | 主入口 | 0 | 0 | 0 | 0 |
|
|
3100
3178
|
| [`ZlActionList`](#zlactionlist) | 主入口 | 6 | 1 | 1 | 0 |
|
|
3101
3179
|
| [`ZlAddSub`](#zladdsub) | 主入口 | 2 | 1 | 1 | 0 |
|
|
3102
|
-
| [`ZlAppLayout`](#zlapplayout) | 主入口 | 1 | 0 |
|
|
3180
|
+
| [`ZlAppLayout`](#zlapplayout) | 主入口 | 1 | 0 | 8 | 0 |
|
|
3103
3181
|
| [`ZlAppMenu`](#zlappmenu) | 主入口 | 3 | 1 | 0 | 0 |
|
|
3104
3182
|
| [`ZlAppSlogan`](#zlappslogan) | 主入口 | 3 | 0 | 0 | 0 |
|
|
3105
3183
|
| [`ZlAutoTooltip`](#zlautotooltip) | 主入口 | 0 | 0 | 1 | 0 |
|
|
@@ -3118,12 +3196,12 @@ const { i18n } = useLocale({ messages })
|
|
|
3118
3196
|
| [`ZlLogin`](#zllogin) | 主入口 | 2 | 0 | 2 | 0 |
|
|
3119
3197
|
| [`ZlLoginForm`](#zlloginform) | 主入口 | 1 | 0 | 1 | 0 |
|
|
3120
3198
|
| [`ZlEmpty`](#zlempty) | 主入口 | 2 | 0 | 0 | 0 |
|
|
3121
|
-
| [`ZlForm`](#zlform) | 主入口 | 2 | 0 | 3 |
|
|
3199
|
+
| [`ZlForm`](#zlform) | 主入口 | 2 | 0 | 3 | 9 |
|
|
3122
3200
|
| [`ZlFormChild`](#zlformchild) | 主入口 | 1 | 0 | 0 | 0 |
|
|
3123
3201
|
| [`ZlGridItem`](#zlgriditem) | 主入口 | 1 | 0 | 1 | 0 |
|
|
3124
3202
|
| [`ZlGrid`](#zlgrid) | 主入口 | 9 | 0 | 2 | 0 |
|
|
3125
3203
|
| [`ZlHorizontalTable`](#zlhorizontaltable) | 主入口 | 4 | 0 | 1 | 0 |
|
|
3126
|
-
| [`ZlIcon`](#zlicon) | 主入口 |
|
|
3204
|
+
| [`ZlIcon`](#zlicon) | 主入口 | 3 | 0 | 1 | 0 |
|
|
3127
3205
|
| [`ZlI18nProvider`](#zli18nprovider) | 主入口 | 0 | 0 | 1 | 0 |
|
|
3128
3206
|
| [`ZlIconHover`](#zliconhover) | 主入口 | 0 | 0 | 0 | 0 |
|
|
3129
3207
|
| [`ZlIconLabel`](#zliconlabel) | 主入口 | 1 | 1 | 1 | 0 |
|
|
@@ -3138,18 +3216,18 @@ const { i18n } = useLocale({ messages })
|
|
|
3138
3216
|
| [`ZlSection`](#zlsection) | 主入口 | 4 | 0 | 3 | 0 |
|
|
3139
3217
|
| [`ZlSorter`](#zlsorter) | 主入口 | 2 | 2 | 1 | 0 |
|
|
3140
3218
|
| [`ZlSorterList`](#zlsorterlist) | 主入口 | 2 | 1 | 0 | 0 |
|
|
3141
|
-
| [`ZlSwitch`](#zlswitch) | 主入口 |
|
|
3142
|
-
| [`ZlTable`](#zltable) | 主入口 | 6 | 3 | 3 |
|
|
3143
|
-
| [`ZlTabs`](#zltabs) | 主入口 |
|
|
3219
|
+
| [`ZlSwitch`](#zlswitch) | 主入口 | 8 | 2 | 2 | 0 |
|
|
3220
|
+
| [`ZlTable`](#zltable) | 主入口 | 6 | 3 | 3 | 16 |
|
|
3221
|
+
| [`ZlTabs`](#zltabs) | 主入口 | 5 | 1 | 3 | 0 |
|
|
3144
3222
|
| [`ZlTag`](#zltag) | 主入口 | 15 | 4 | 1 | 0 |
|
|
3145
3223
|
| [`ZlText`](#zltext) | 主入口 | 1 | 0 | 1 | 0 |
|
|
3146
3224
|
| [`ZlTitle`](#zltitle) | 主入口 | 5 | 0 | 3 | 0 |
|
|
3147
3225
|
| [`ZlUpload`](#zlupload) | 主入口 | 13 | 1 | 1 | 0 |
|
|
3148
|
-
| [`ZlTree`](#zltree) | 主入口 |
|
|
3226
|
+
| [`ZlTree`](#zltree) | 主入口 | 10 | 2 | 5 | 23 |
|
|
3149
3227
|
| [`ZlTreeSelect`](#zltreeselect) | 主入口 | 6 | 1 | 0 | 0 |
|
|
3150
3228
|
| [`ZlChart`](#zlchart) | 子入口 chart | 2 | 0 | 0 | 1 |
|
|
3151
|
-
| [`ZlEditor`](#zleditor) | 子入口 editor | 3 | 1 | 0 |
|
|
3152
|
-
| [`ZlSqlEditor`](#zlsqleditor) | 子入口 editor | 4 | 1 | 0 |
|
|
3229
|
+
| [`ZlEditor`](#zleditor) | 子入口 editor | 3 | 1 | 0 | 10 |
|
|
3230
|
+
| [`ZlSqlEditor`](#zlsqleditor) | 子入口 editor | 4 | 1 | 0 | 3 |
|
|
3153
3231
|
| [`ZlFilePreview`](#zlfilepreview) | 子入口 file-preview | 1 | 0 | 0 | 0 |
|
|
3154
3232
|
| [`ZlFileViewer`](#zlfileviewer) | 子入口 file-preview | 1 | 0 | 0 | 0 |
|
|
3155
3233
|
|
|
@@ -3216,9 +3294,9 @@ import { ZlActionList } from '@zl-ui-kit/components'
|
|
|
3216
3294
|
|
|
3217
3295
|
**事件（emits）**
|
|
3218
3296
|
|
|
3219
|
-
| 事件 | 参数 | 说明
|
|
3220
|
-
| -------- | ------------------- |
|
|
3221
|
-
| `action` | `ActionItem, any[]` |
|
|
3297
|
+
| 事件 | 参数 | 说明 |
|
|
3298
|
+
| -------- | ------------------- | ---------------------------------------------------------------------------------------------- |
|
|
3299
|
+
| `action` | `ActionItem, any[]` | 点击（或从「更多」下拉选中）某个操作项时触发，参数为被选中的 `ActionItem` 与其后透传的调用参数 |
|
|
3222
3300
|
|
|
3223
3301
|
**插槽（slots）**
|
|
3224
3302
|
|
|
@@ -3265,9 +3343,9 @@ import { ZlAddSub } from '@zl-ui-kit/components'
|
|
|
3265
3343
|
|
|
3266
3344
|
**事件（emits）**
|
|
3267
3345
|
|
|
3268
|
-
| 事件 | 参数 | 说明
|
|
3269
|
-
| -------------- | ------- |
|
|
3270
|
-
| `update:model` | `any[]` |
|
|
3346
|
+
| 事件 | 参数 | 说明 |
|
|
3347
|
+
| -------------- | ------- | ------------------------------------------ |
|
|
3348
|
+
| `update:model` | `any[]` | `v-model:model` 更新，参数为变化后的整组值 |
|
|
3271
3349
|
|
|
3272
3350
|
**插槽（slots）**
|
|
3273
3351
|
|
|
@@ -3279,7 +3357,7 @@ import { ZlAddSub } from '@zl-ui-kit/components'
|
|
|
3279
3357
|
|
|
3280
3358
|
<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlAppLayout/index.vue`</sub>
|
|
3281
3359
|
|
|
3282
|
-
**接口概览**：1 props ·
|
|
3360
|
+
**接口概览**：1 props · 8 插槽
|
|
3283
3361
|
|
|
3284
3362
|
**用法示例**
|
|
3285
3363
|
|
|
@@ -3299,6 +3377,13 @@ import { ZlAppLayout } from '@zl-ui-kit/components'
|
|
|
3299
3377
|
<template>
|
|
3300
3378
|
<ZlAppLayout>
|
|
3301
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>
|
|
3302
3387
|
</ZlAppLayout>
|
|
3303
3388
|
</template>
|
|
3304
3389
|
```
|
|
@@ -3311,12 +3396,20 @@ import { ZlAppLayout } from '@zl-ui-kit/components'
|
|
|
3311
3396
|
|
|
3312
3397
|
> 选项式组件（`defineComponent`），props 定义在 `props: {}` 中
|
|
3313
3398
|
> 把 `$attrs` 透传给内部组件，未列出的属性会继续下传
|
|
3399
|
+
> 本组件是**分发器**：插槽由同目录子组件定义，同名插槽在不同形态下的作用域与是否存在可能不同
|
|
3314
3400
|
|
|
3315
3401
|
**插槽（slots）**
|
|
3316
3402
|
|
|
3317
|
-
| 插槽
|
|
3318
|
-
|
|
|
3319
|
-
| `default`
|
|
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>` | 侧栏底部区（排在内置折叠按钮之后，仅纵向形态有） |
|
|
3320
3413
|
|
|
3321
3414
|
#### `ZlAppMenu`
|
|
3322
3415
|
|
|
@@ -3348,9 +3441,9 @@ import { ZlAppMenu } from '@zl-ui-kit/components'
|
|
|
3348
3441
|
|
|
3349
3442
|
**事件（emits）**
|
|
3350
3443
|
|
|
3351
|
-
| 事件 | 参数 | 说明
|
|
3352
|
-
| ----------------- | ---------- |
|
|
3353
|
-
| `menu-item-click` | `MenuItem` |
|
|
3444
|
+
| 事件 | 参数 | 说明 |
|
|
3445
|
+
| ----------------- | ---------- | ---------------------------------------------------------- |
|
|
3446
|
+
| `menu-item-click` | `MenuItem` | 点击菜单项时触发，参数为被点击的菜单项配置（子项冒泡上来） |
|
|
3354
3447
|
|
|
3355
3448
|
#### `ZlAppSlogan`
|
|
3356
3449
|
|
|
@@ -3574,9 +3667,9 @@ import { ZlCardPage } from '@zl-ui-kit/components'
|
|
|
3574
3667
|
|
|
3575
3668
|
**事件（emits）**
|
|
3576
3669
|
|
|
3577
|
-
| 事件 | 参数 | 说明
|
|
3578
|
-
| -------------- | ---- |
|
|
3579
|
-
| `search-reset` | — |
|
|
3670
|
+
| 事件 | 参数 | 说明 |
|
|
3671
|
+
| -------------- | ---- | ---------------------------------------------------------- |
|
|
3672
|
+
| `search-reset` | — | 查询区重置时触发（此时表单已清空，随后会自动发起一次查询） |
|
|
3580
3673
|
|
|
3581
3674
|
**插槽（slots）**
|
|
3582
3675
|
|
|
@@ -3588,11 +3681,11 @@ import { ZlCardPage } from '@zl-ui-kit/components'
|
|
|
3588
3681
|
|
|
3589
3682
|
**暴露（defineExpose）**
|
|
3590
3683
|
|
|
3591
|
-
| 名称 | 说明
|
|
3592
|
-
| --------- |
|
|
3593
|
-
| `refresh` |
|
|
3594
|
-
| `params` |
|
|
3595
|
-
| `search` | 重新查询并回到第 1 页；消费方可在 useRequest 的 refreshDepsAction 里调用
|
|
3684
|
+
| 名称 | 说明 |
|
|
3685
|
+
| --------- | ------------------------------------------------------------------------------------ |
|
|
3686
|
+
| `refresh` | 原地重查：用最近一次入参重新请求，保持当前页码（区别于 `search()` 会回到第 1 页） |
|
|
3687
|
+
| `params` | 最近一次请求的入参（`{ pageNum, pageSize, ...查询表单 }`），未请求过时为 `undefined` |
|
|
3688
|
+
| `search` | 重新查询并回到第 1 页；消费方可在 useRequest 的 refreshDepsAction 里调用 |
|
|
3596
3689
|
|
|
3597
3690
|
#### `ZlCheckAll`
|
|
3598
3691
|
|
|
@@ -3625,9 +3718,9 @@ import { ZlCheckAll } from '@zl-ui-kit/components'
|
|
|
3625
3718
|
|
|
3626
3719
|
**事件（emits）**
|
|
3627
3720
|
|
|
3628
|
-
| 事件 | 参数 | 说明
|
|
3629
|
-
| -------------- | ------------------------- |
|
|
3630
|
-
| `update:model` | `Array<string \| number>` |
|
|
3721
|
+
| 事件 | 参数 | 说明 |
|
|
3722
|
+
| -------------- | ------------------------- | --------------------------------------------------- |
|
|
3723
|
+
| `update:model` | `Array<string \| number>` | `v-model:model` 更新，参数为当前已勾选的 value 集合 |
|
|
3631
3724
|
|
|
3632
3725
|
#### `ZlCheckboxTag`
|
|
3633
3726
|
|
|
@@ -3844,6 +3937,8 @@ import { ZlDrawer } from '@zl-ui-kit/components'
|
|
|
3844
3937
|
| `readonly` | `boolean` | — | 否 | `readonly` | 只读模式：隐藏取消按钮，只留「关闭」 |
|
|
3845
3938
|
| `loading` | `boolean` | — | 否 | `loading` | 内容区加载态，为 true 时显示遮罩 loading |
|
|
3846
3939
|
|
|
3940
|
+
> 把未声明的入参与事件（`useAttrs()`）透传给 `el-drawer`，未列出的属性会继续下传
|
|
3941
|
+
|
|
3847
3942
|
**事件（emits）**
|
|
3848
3943
|
|
|
3849
3944
|
| 事件 | 参数 | 说明 |
|
|
@@ -3889,10 +3984,10 @@ import { ZlDynamicComponent } from '@zl-ui-kit/components'
|
|
|
3889
3984
|
|
|
3890
3985
|
**事件（emits）**
|
|
3891
3986
|
|
|
3892
|
-
| 事件 | 参数
|
|
3893
|
-
| ------------------- |
|
|
3894
|
-
| `
|
|
3895
|
-
| `
|
|
3987
|
+
| 事件 | 参数 | 说明 |
|
|
3988
|
+
| ------------------- | ----- | ------------------------------------------------------------------------------ |
|
|
3989
|
+
| `input` | `any` | 子组件值变化时触发，参数为新值与其后透传的其余参数（在业务侧自行接管写入时用） |
|
|
3990
|
+
| `update:modelValue` | `any` | `v-model:modelValue` 更新；若 schema 里写了 `model`，会同步写回 `model[model]` |
|
|
3896
3991
|
|
|
3897
3992
|
#### `ZlPdfViewer`
|
|
3898
3993
|
|
|
@@ -4039,7 +4134,9 @@ import { ZlEmpty } from '@zl-ui-kit/components'
|
|
|
4039
4134
|
|
|
4040
4135
|
<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlForm/index.vue`</sub>
|
|
4041
4136
|
|
|
4042
|
-
|
|
4137
|
+
**简介**：表单：`items` schema 驱动，控件由 `component`/`props` 描述； 单字段可用 `#<model>` 插槽整块接管，未声明的入参与事件透传给 `el-form`
|
|
4138
|
+
|
|
4139
|
+
**接口概览**：2 props · 3 插槽 · 9 暴露
|
|
4043
4140
|
|
|
4044
4141
|
**用法示例**
|
|
4045
4142
|
|
|
@@ -4074,6 +4171,7 @@ import { ZlForm } from '@zl-ui-kit/components'
|
|
|
4074
4171
|
| `items` | `FormItem[]` | `() => []` | 否 | `:items="items"` | 表单字段 schema，决定渲染哪些表单项 |
|
|
4075
4172
|
| `model` | `Record<string, any>` | — | 否 | `:model="{}"` | 表单值对象，不传时由组件内部自建 |
|
|
4076
4173
|
|
|
4174
|
+
> 暴露对象是 `Proxy`：下表为显式实现的能力，**未列出的键会运行时下钻到内部实例**（不建议依赖，请用上表的实例 getter 取原生对象）
|
|
4077
4175
|
> 把 `$attrs` 透传给 `el-form`，未列出的属性会继续下传
|
|
4078
4176
|
|
|
4079
4177
|
**插槽（slots）**
|
|
@@ -4084,6 +4182,20 @@ import { ZlForm } from '@zl-ui-kit/components'
|
|
|
4084
4182
|
| `[item.model]` | `model` / `field` | `<template #[item.model]="{ model, field }">…</template>` | 按该项 model 命名，传出 model、field；覆盖默认控件 |
|
|
4085
4183
|
| `default` | — | `<template #default>…</template>` | 追加在末尾的表单内容（如额外区块、按钮） |
|
|
4086
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
|
+
|
|
4087
4199
|
#### `ZlFormChild`
|
|
4088
4200
|
|
|
4089
4201
|
<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlForm/ZlFormChild.vue`</sub>
|
|
@@ -4257,7 +4369,7 @@ import { ZlHorizontalTable } from '@zl-ui-kit/components'
|
|
|
4257
4369
|
|
|
4258
4370
|
<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlIcon/index.vue`</sub>
|
|
4259
4371
|
|
|
4260
|
-
**接口概览**：
|
|
4372
|
+
**接口概览**：3 props · 1 插槽
|
|
4261
4373
|
|
|
4262
4374
|
**用法示例**
|
|
4263
4375
|
|
|
@@ -4283,9 +4395,13 @@ import { ZlIcon } from '@zl-ui-kit/components'
|
|
|
4283
4395
|
|
|
4284
4396
|
**props**
|
|
4285
4397
|
|
|
4286
|
-
| 属性
|
|
4287
|
-
|
|
|
4288
|
-
| `icon`
|
|
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`，未列出的属性会继续下传
|
|
4289
4405
|
|
|
4290
4406
|
**插槽（slots）**
|
|
4291
4407
|
|
|
@@ -4387,9 +4503,9 @@ import { ZlIconLabel } from '@zl-ui-kit/components'
|
|
|
4387
4503
|
|
|
4388
4504
|
**事件（emits）**
|
|
4389
4505
|
|
|
4390
|
-
| 事件 | 参数 | 说明
|
|
4391
|
-
| ------- | ------------ |
|
|
4392
|
-
| `click` | `MouseEvent` |
|
|
4506
|
+
| 事件 | 参数 | 说明 |
|
|
4507
|
+
| ------- | ------------ | ------------------------------------------- |
|
|
4508
|
+
| `click` | `MouseEvent` | 点击图标/文字区域时触发，参数为原生鼠标事件 |
|
|
4393
4509
|
|
|
4394
4510
|
**插槽（slots）**
|
|
4395
4511
|
|
|
@@ -4507,11 +4623,11 @@ import { ZlPagination } from '@zl-ui-kit/components'
|
|
|
4507
4623
|
|
|
4508
4624
|
**事件（emits）**
|
|
4509
4625
|
|
|
4510
|
-
| 事件 | 参数 | 说明
|
|
4511
|
-
| ------------------ | --------------------------------------- |
|
|
4512
|
-
| `change` | `{ pageNum: number; pageSize: number }` |
|
|
4513
|
-
| `page-change` | `number` | 仅页码变化（区别于 pageSize 变化）
|
|
4514
|
-
| `page-size-change` | `number` | 仅每页条数变化
|
|
4626
|
+
| 事件 | 参数 | 说明 |
|
|
4627
|
+
| ------------------ | --------------------------------------- | -------------------------------------------------------- |
|
|
4628
|
+
| `change` | `{ pageNum: number; pageSize: number }` | 页码或每页条数变化后触发，参数为 `{ pageNum, pageSize }` |
|
|
4629
|
+
| `page-change` | `number` | 仅页码变化（区别于 pageSize 变化） |
|
|
4630
|
+
| `page-size-change` | `number` | 仅每页条数变化 |
|
|
4515
4631
|
|
|
4516
4632
|
#### `ZlPermission`
|
|
4517
4633
|
|
|
@@ -4598,10 +4714,10 @@ import { ZlPopconfirm } from '@zl-ui-kit/components'
|
|
|
4598
4714
|
|
|
4599
4715
|
**事件（emits）**
|
|
4600
4716
|
|
|
4601
|
-
| 事件 | 参数 | 说明
|
|
4602
|
-
| --------- | ---- |
|
|
4603
|
-
| `confirm` | — |
|
|
4604
|
-
| `cancel` | — |
|
|
4717
|
+
| 事件 | 参数 | 说明 |
|
|
4718
|
+
| --------- | ---- | ----------------------------------------- |
|
|
4719
|
+
| `confirm` | — | 点击「确定」时触发（不会自动关闭浮层） |
|
|
4720
|
+
| `cancel` | — | 点击「取消」或通过遮罩/按钮关闭浮层时触发 |
|
|
4605
4721
|
|
|
4606
4722
|
**插槽（slots）**
|
|
4607
4723
|
|
|
@@ -4721,11 +4837,11 @@ import { ZlSearch } from '@zl-ui-kit/components'
|
|
|
4721
4837
|
|
|
4722
4838
|
**暴露（defineExpose）**
|
|
4723
4839
|
|
|
4724
|
-
| 名称 | 说明
|
|
4725
|
-
| -------- |
|
|
4726
|
-
| `params` |
|
|
4727
|
-
| `search` |
|
|
4728
|
-
| `reset` |
|
|
4840
|
+
| 名称 | 说明 |
|
|
4841
|
+
| -------- | ---------------------------------------------------------------------------- |
|
|
4842
|
+
| `params` | 当前查询表单值（已按各项 `toParams` 转换），可直接当请求入参 |
|
|
4843
|
+
| `search` | 收起展开态并触发 `search` 事件（本身不做校验，带校验的查询走组件内查询按钮） |
|
|
4844
|
+
| `reset` | 重置表单并清除校验提示，随后触发 `reset` 事件与一次 `search` |
|
|
4729
4845
|
|
|
4730
4846
|
#### `ZlSearchTable`
|
|
4731
4847
|
|
|
@@ -4779,9 +4895,9 @@ import { ZlSearchTable } from '@zl-ui-kit/components'
|
|
|
4779
4895
|
|
|
4780
4896
|
**事件（emits）**
|
|
4781
4897
|
|
|
4782
|
-
| 事件 | 参数 | 说明
|
|
4783
|
-
| -------------- | ---- |
|
|
4784
|
-
| `search-reset` | — |
|
|
4898
|
+
| 事件 | 参数 | 说明 |
|
|
4899
|
+
| -------------- | ---- | ---------------------------------------------------------- |
|
|
4900
|
+
| `search-reset` | — | 查询区重置时触发（此时表单已清空，随后会自动发起一次查询） |
|
|
4785
4901
|
|
|
4786
4902
|
**插槽（slots）**
|
|
4787
4903
|
|
|
@@ -4793,12 +4909,12 @@ import { ZlSearchTable } from '@zl-ui-kit/components'
|
|
|
4793
4909
|
|
|
4794
4910
|
**暴露（defineExpose）**
|
|
4795
4911
|
|
|
4796
|
-
| 名称 | 说明
|
|
4797
|
-
| --------- |
|
|
4798
|
-
| `refresh` |
|
|
4799
|
-
| `params` |
|
|
4800
|
-
| `search` |
|
|
4801
|
-
| `table` |
|
|
4912
|
+
| 名称 | 说明 |
|
|
4913
|
+
| --------- | --------------------------------------------------------------------------------- |
|
|
4914
|
+
| `refresh` | 原地重查：用最近一次入参重新请求，保持当前页码（区别于 `search()` 会回到第 1 页） |
|
|
4915
|
+
| `params` | 最近一次请求的入参（`{ pageNum, pageSize, ...查询表单 }`） |
|
|
4916
|
+
| `search` | 内部 ZlSearch 实例，`params` / `search()` / `reset()` 等可直接调用 |
|
|
4917
|
+
| `table` | 内部 ZlTable 实例，`toggleRowSelection()` / `doLayout()` 等可直接调用 |
|
|
4802
4918
|
|
|
4803
4919
|
#### `ZlSection`
|
|
4804
4920
|
|
|
@@ -4886,10 +5002,10 @@ import { ZlSorter } from '@zl-ui-kit/components'
|
|
|
4886
5002
|
|
|
4887
5003
|
**事件（emits）**
|
|
4888
5004
|
|
|
4889
|
-
| 事件 | 参数 | 说明
|
|
4890
|
-
| ------------------- | ----------------------- |
|
|
4891
|
-
| `update:modelValue` | `'' \| 'asc' \| 'desc'` | `v-model` 更新
|
|
4892
|
-
| `change` | `'' \| 'asc' \| 'desc'` |
|
|
5005
|
+
| 事件 | 参数 | 说明 |
|
|
5006
|
+
| ------------------- | ----------------------- | ---------------------------------------------------- |
|
|
5007
|
+
| `update:modelValue` | `'' \| 'asc' \| 'desc'` | `v-model` 更新 |
|
|
5008
|
+
| `change` | `'' \| 'asc' \| 'desc'` | 排序切换时触发，参数为新的排序值（空串表示取消排序） |
|
|
4893
5009
|
|
|
4894
5010
|
**插槽（slots）**
|
|
4895
5011
|
|
|
@@ -4928,17 +5044,17 @@ import { ZlSorterList } from '@zl-ui-kit/components'
|
|
|
4928
5044
|
|
|
4929
5045
|
**事件（emits）**
|
|
4930
5046
|
|
|
4931
|
-
| 事件 | 参数 | 说明
|
|
4932
|
-
| -------- | ------------------------------------- |
|
|
4933
|
-
| `change` | `Record<string, any>, string, string` |
|
|
5047
|
+
| 事件 | 参数 | 说明 |
|
|
5048
|
+
| -------- | ------------------------------------- | -------------------------------------------------------------- |
|
|
5049
|
+
| `change` | `Record<string, any>, string, string` | 某字段排序变化时触发，参数依次为整份排序对象、字段名、新排序值 |
|
|
4934
5050
|
|
|
4935
5051
|
#### `ZlSwitch`
|
|
4936
5052
|
|
|
4937
5053
|
<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlSwitch/index.vue`</sub>
|
|
4938
5054
|
|
|
4939
|
-
**简介**：开关：值可为 boolean/string/number，支持 checkedText/uncheckedText
|
|
5055
|
+
**简介**：开关：值可为 boolean/string/number，支持 checkedText/uncheckedText 文案； 兼容 `el-switch` 的 `active-value`/`inactive-value` 写法，`disabled`/`loading`/`before-change` 等透传 `el…
|
|
4940
5056
|
|
|
4941
|
-
**接口概览**：
|
|
5057
|
+
**接口概览**：8 props · 2 事件 · 2 插槽
|
|
4942
5058
|
|
|
4943
5059
|
**用法示例**
|
|
4944
5060
|
|
|
@@ -4965,22 +5081,25 @@ import { ZlSwitch } from '@zl-ui-kit/components'
|
|
|
4965
5081
|
|
|
4966
5082
|
**props**
|
|
4967
5083
|
|
|
4968
|
-
| 属性 | 类型 | 默认值 | 必填 | 示例 | 说明
|
|
4969
|
-
| ---------------- | ----------------------------- | ------- | ---- | ----------------------------------- |
|
|
4970
|
-
| `modelValue` | `boolean \| string \| number` | — | 否 | `v-model="value"` | 当前开关值，支持受控双向绑定
|
|
4971
|
-
| `defaultChecked` | `boolean` | `false` | 否 | `default-checked` | 非受控模式下的初始选中状态
|
|
4972
|
-
| `checkedValue` | `boolean \| string \| number` |
|
|
4973
|
-
| `uncheckedValue` | `boolean \| string \| number` |
|
|
4974
|
-
| `
|
|
4975
|
-
| `
|
|
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="关"` | 未选中时显示的文案 |
|
|
4976
5094
|
|
|
4977
5095
|
> 把 `$attrs` 透传给 `el-switch`，未列出的属性会继续下传
|
|
4978
5096
|
|
|
4979
5097
|
**事件（emits）**
|
|
4980
5098
|
|
|
4981
|
-
| 事件 | 参数 | 说明
|
|
4982
|
-
| ------------------- | ----------------------------- |
|
|
4983
|
-
| `update:modelValue` | `boolean \| string \| number` |
|
|
5099
|
+
| 事件 | 参数 | 说明 |
|
|
5100
|
+
| ------------------- | ----------------------------- | ------------------------------------------------------------------------------------ |
|
|
5101
|
+
| `update:modelValue` | `boolean \| string \| number` | v-model 更新 |
|
|
5102
|
+
| `change` | `boolean \| string \| number` | 开关值变化后触发，参数为业务值（即 `checked-value`/`unchecked-value`，不是内部布尔） |
|
|
4984
5103
|
|
|
4985
5104
|
**插槽（slots）**
|
|
4986
5105
|
|
|
@@ -4993,7 +5112,9 @@ import { ZlSwitch } from '@zl-ui-kit/components'
|
|
|
4993
5112
|
|
|
4994
5113
|
<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlTable/index.vue`</sub>
|
|
4995
5114
|
|
|
4996
|
-
|
|
5115
|
+
**简介**：表格：`columns` schema 驱动 + 内置分页；单元格可用 `#<slot>` 接管（作用域含 `row`/`column`/`$index`）， 未声明的入参与事件透传给 `el-table`
|
|
5116
|
+
|
|
5117
|
+
**接口概览**：6 props · 3 事件 · 3 插槽 · 16 暴露
|
|
4997
5118
|
|
|
4998
5119
|
**用法示例**
|
|
4999
5120
|
|
|
@@ -5032,15 +5153,16 @@ import { ZlTable } from '@zl-ui-kit/components'
|
|
|
5032
5153
|
| `pagination` | `Record<string, any> \| boolean` | — | 否 | `:pagination="{}"` | 分页配置，设为 false 时隐藏分页 |
|
|
5033
5154
|
| `loading` | `boolean` | `false` | 否 | `loading` | 表格 loading（作用于表格区） |
|
|
5034
5155
|
|
|
5156
|
+
> 暴露对象是 `Proxy`：下表为显式实现的能力，**未列出的键会运行时下钻到内部实例**（不建议依赖，请用上表的实例 getter 取原生对象）
|
|
5035
5157
|
> 把 `$attrs` 透传给 `el-table`，未列出的属性会继续下传
|
|
5036
5158
|
|
|
5037
5159
|
**事件（emits）**
|
|
5038
5160
|
|
|
5039
|
-
| 事件 | 参数 | 说明
|
|
5040
|
-
| ------------------- | --------------------------------------- |
|
|
5041
|
-
| `pagination-change` | `{ pageNum: number; pageSize: number }` |
|
|
5042
|
-
| `page-change` | `number` |
|
|
5043
|
-
| `page-size-change` | `number` |
|
|
5161
|
+
| 事件 | 参数 | 说明 |
|
|
5162
|
+
| ------------------- | --------------------------------------- | -------------------------------------------------- |
|
|
5163
|
+
| `pagination-change` | `{ pageNum: number; pageSize: number }` | 分页状态变化时触发，参数为 `{ pageNum, pageSize }` |
|
|
5164
|
+
| `page-change` | `number` | 仅页码变化时触发 |
|
|
5165
|
+
| `page-size-change` | `number` | 仅每页条数变化时触发 |
|
|
5044
5166
|
|
|
5045
5167
|
**插槽（slots）**
|
|
5046
5168
|
|
|
@@ -5050,11 +5172,32 @@ import { ZlTable } from '@zl-ui-kit/components'
|
|
|
5050
5172
|
| `[column.headerSlotName]` | `v-bind="scope"` 展开 | `<template #[column.headerSlotName]="scope">…</template>` | 按列字段生成 header-* 名，参数为列上下文 |
|
|
5051
5173
|
| `[column.slotName]` | `v-bind="scope"` 展开 | `<template #[column.slotName]="scope">…</template>` | 按 slot 或字段名生成，参数为单元格上下文 |
|
|
5052
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
|
+
|
|
5053
5196
|
#### `ZlTabs`
|
|
5054
5197
|
|
|
5055
5198
|
<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlTabs/index.vue`</sub>
|
|
5056
5199
|
|
|
5057
|
-
**接口概览**：
|
|
5200
|
+
**接口概览**：5 props · 1 事件 · 3 插槽
|
|
5058
5201
|
|
|
5059
5202
|
**用法示例**
|
|
5060
5203
|
|
|
@@ -5087,16 +5230,23 @@ import { ZlTabs } from '@zl-ui-kit/components'
|
|
|
5087
5230
|
|
|
5088
5231
|
**props**
|
|
5089
5232
|
|
|
5090
|
-
| 属性
|
|
5091
|
-
|
|
|
5092
|
-
| `tabs`
|
|
5093
|
-
| `
|
|
5094
|
-
| `
|
|
5095
|
-
| `
|
|
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"` | 是否启用导航背景色，默认启用 |
|
|
5096
5240
|
|
|
5097
5241
|
> 选项式组件（`defineComponent`），props 定义在 `props: {}` 中
|
|
5098
5242
|
> 把 `$attrs` 透传给内部组件，未列出的属性会继续下传
|
|
5099
5243
|
|
|
5244
|
+
**事件（emits）**
|
|
5245
|
+
|
|
5246
|
+
| 事件 | 参数 | 说明 |
|
|
5247
|
+
| ------------------- | ------------------------------- | ---------------------------------------------------------- |
|
|
5248
|
+
| `update:modelValue` | `string \| number \| undefined` | 点击页签切换后触发，参数为新激活页签的 key（v-model 更新） |
|
|
5249
|
+
|
|
5100
5250
|
**插槽（slots）**
|
|
5101
5251
|
|
|
5102
5252
|
| 插槽 | 作用域参数 | 示例 | 说明 |
|
|
@@ -5155,12 +5305,12 @@ import { ZlTag } from '@zl-ui-kit/components'
|
|
|
5155
5305
|
|
|
5156
5306
|
**事件（emits）**
|
|
5157
5307
|
|
|
5158
|
-
| 事件 | 参数 | 说明
|
|
5159
|
-
| ----------------- | ------------ |
|
|
5160
|
-
| `close` | `MouseEvent` |
|
|
5161
|
-
| `update:visible` | `boolean` |
|
|
5162
|
-
| `update:selected` | `boolean` |
|
|
5163
|
-
| `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` 开启时有效） |
|
|
5164
5314
|
|
|
5165
5315
|
**插槽（slots）**
|
|
5166
5316
|
|
|
@@ -5322,7 +5472,9 @@ import { ZlUpload } from '@zl-ui-kit/components'
|
|
|
5322
5472
|
|
|
5323
5473
|
<sub>入口 `@zl-ui-kit/components` · 源码 `packages/components/src/components/ZlTree/index.vue`</sub>
|
|
5324
5474
|
|
|
5325
|
-
|
|
5475
|
+
**简介**：树形控件：内置搜索框、节点图标与超长省略；复选框多选可用 `v-model:checked-keys` 受控， 字段映射走 `fieldNames`（arco 兼容），`el-tree` 其余属性与事件（懒加载 / 拖拽 / `@node-click`）原样透传。
|
|
5476
|
+
|
|
5477
|
+
**接口概览**：10 props · 2 事件 · 5 插槽 · 23 暴露
|
|
5326
5478
|
|
|
5327
5479
|
**用法示例**
|
|
5328
5480
|
|
|
@@ -5332,11 +5484,17 @@ import { ZlTree } from '@zl-ui-kit/components'
|
|
|
5332
5484
|
</script>
|
|
5333
5485
|
|
|
5334
5486
|
<template>
|
|
5335
|
-
<ZlTree
|
|
5487
|
+
<ZlTree
|
|
5488
|
+
:ref="treeInstance"
|
|
5489
|
+
:data="checkableTreeData"
|
|
5490
|
+
:field-names="fieldNames"
|
|
5491
|
+
v-model:checked-keys="value"
|
|
5492
|
+
show-checkbox
|
|
5493
|
+
/>
|
|
5336
5494
|
</template>
|
|
5337
5495
|
```
|
|
5338
5496
|
|
|
5339
|
-
> 示例中的 `data`、`fieldNames` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
|
|
5497
|
+
> 示例中的 `ref`、`data`、`fieldNames` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
|
|
5340
5498
|
|
|
5341
5499
|
**插槽用法**
|
|
5342
5500
|
|
|
@@ -5344,7 +5502,9 @@ import { ZlTree } from '@zl-ui-kit/components'
|
|
|
5344
5502
|
<template>
|
|
5345
5503
|
<ZlTree>
|
|
5346
5504
|
<template #search-extra>…</template>
|
|
5505
|
+
<template #default="{ node, data }">…</template>
|
|
5347
5506
|
<template #title="{ node, data }">…</template>
|
|
5507
|
+
<template #icon="{ node, data }">…</template>
|
|
5348
5508
|
<!-- 动态插槽：名字运行时取自 slot -->
|
|
5349
5509
|
</ZlTree>
|
|
5350
5510
|
</template>
|
|
@@ -5352,21 +5512,65 @@ import { ZlTree } from '@zl-ui-kit/components'
|
|
|
5352
5512
|
|
|
5353
5513
|
**props**
|
|
5354
5514
|
|
|
5355
|
-
| 属性 | 类型
|
|
5356
|
-
| ------------------ |
|
|
5357
|
-
| `
|
|
5358
|
-
| `
|
|
5359
|
-
| `
|
|
5360
|
-
| `
|
|
5361
|
-
| `
|
|
5515
|
+
| 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
|
|
5516
|
+
| ------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---- | ----------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
5517
|
+
| `checkedKeys` | `ZlTreeKey[]` | — | 否 | `v-model:checked-keys="value"` | 勾选节点 key 数组（受控：传了就用外部值管理勾选态，勿再传 `default-checked-keys`） |
|
|
5518
|
+
| `halfCheckedKeys` | `ZlTreeKey[]` | — | 否 | `v-model:half-checked-keys="value"` | 半选节点 key 数组（父子联动下“部分子节点被勾选”的父节点，提交时用来判断半选状态） |
|
|
5519
|
+
| `fieldNames` | `{ key?: string; title?: string; children?: string; disabled?: string; isLeaf?: string }` | `() => ({ key: 'key', title: 'title', children: 'children' })` | 否 | `:field-names="{}"` | 字段映射（arco fieldNames 兼容：title→label、children；disabled/isLeaf 填数据里的布尔字段名） |
|
|
5520
|
+
| `inputSearchProps` | `Record<string, any>` | — | 否 | `:input-search-props="{}"` | 搜索框透传（el-input 属性） |
|
|
5521
|
+
| `filterTreeNode` | `(value: string, data: any) => boolean` | — | 否 | `:filter-tree-node="() => {}"` | 自定义过滤函数（缺省按 title 包含匹配） |
|
|
5522
|
+
| `disableFilter` | `boolean` | — | 否 | `disable-filter` | 关闭搜索框 |
|
|
5523
|
+
| `loading` | `boolean` | — | 否 | `loading` | 是否显示树区域加载状态 |
|
|
5524
|
+
| `showCheckbox` | `boolean` | `false` | 否 | `show-checkbox` | 显示复选框（多选），取值可用 `v-model:checked-keys` 或 `getCheckedKeys()` |
|
|
5525
|
+
| `checkStrictly` | `boolean` | `false` | 否 | `check-strictly` | 勾选时父子不关联（每个节点独立勾选） |
|
|
5526
|
+
| `checkDescendants` | `boolean` | `false` | 否 | `check-descendants` | 勾选父节点时联动勾选全部子孙（懒加载未展开的层级需要展开后才纳入） |
|
|
5527
|
+
|
|
5528
|
+
> 把未声明的入参与事件（`useAttrs()`）透传给 `el-tree`，未列出的属性会继续下传
|
|
5529
|
+
|
|
5530
|
+
**事件（emits）**
|
|
5531
|
+
|
|
5532
|
+
| 事件 | 参数 | 说明 |
|
|
5533
|
+
| ------------------------ | ------------- | -------------- |
|
|
5534
|
+
| `update:checkedKeys` | `ZlTreeKey[]` | `v-model` 更新 |
|
|
5535
|
+
| `update:halfCheckedKeys` | `ZlTreeKey[]` | `v-model` 更新 |
|
|
5362
5536
|
|
|
5363
5537
|
**插槽（slots）**
|
|
5364
5538
|
|
|
5365
|
-
| 插槽 | 作用域参数 | 示例
|
|
5366
|
-
| -------------- | ------------------------------ |
|
|
5367
|
-
| `search-extra` | — | `<template #search-extra>…</template>`
|
|
5368
|
-
| `
|
|
5369
|
-
| `
|
|
5539
|
+
| 插槽 | 作用域参数 | 示例 | 说明 |
|
|
5540
|
+
| -------------- | ------------------------------ | -------------------------------------------------- | --------------------------------------------------------------------- |
|
|
5541
|
+
| `search-extra` | — | `<template #search-extra>…</template>` | 搜索框右侧附加内容 |
|
|
5542
|
+
| `default` | `node` / `data` | `<template #default="{ node, data }">…</template>` | 自定义整个节点内容（同 el-tree 的 #default，会替掉内置图标与省略号） |
|
|
5543
|
+
| `title` | `v-bind="{ node, data }"` 展开 | `<template #title="{ node, data }">…</template>` | 自定义节点标题，参数为 node 和 data |
|
|
5544
|
+
| `icon` | `v-bind="{ node, data }"` 展开 | `<template #icon="{ node, data }">…</template>` | 自定义节点图标（叶子/分支默认用 zl:document-color / zl:folder-color） |
|
|
5545
|
+
| `[slot]` | `v-bind="scope"` 展开 | `<template #[slot]="scope">…</template>` | 按自定义插槽列表生成名称，参数为树插槽上下文 |
|
|
5546
|
+
|
|
5547
|
+
**暴露（defineExpose）**
|
|
5548
|
+
|
|
5549
|
+
| 名称 | 说明 |
|
|
5550
|
+
| --------------------- | --------------------------------------------------------------------------------------- |
|
|
5551
|
+
| `elTree` | 内部 `el-tree` 实例：下面未列出的原生能力（`store` 等）从这里取 |
|
|
5552
|
+
| `getCheckedKeys` | 勾选节点的 key 数组；`getCheckedKeys(true)` 只取叶子节点 |
|
|
5553
|
+
| `getCheckedNodes` | 勾选节点的数据数组；`leafOnly` 只要叶子，`includeHalfChecked` 连半选节点一起返回 |
|
|
5554
|
+
| `getHalfCheckedKeys` | 半选节点的 key 数组（父子联动下部分勾选的父节点） |
|
|
5555
|
+
| `getHalfCheckedNodes` | 半选节点的数据数组 |
|
|
5556
|
+
| `setCheckedKeys` | 按 key 数组设置勾选；`leafOnly` 表示这些 key 只对应叶子节点（父节点由联动推导） |
|
|
5557
|
+
| `setChecked` | 设置单个节点勾选态：`data` 传 key 或节点数据，`deep=false` 表示不联动父子 |
|
|
5558
|
+
| `setAllChecked` | 全选 / 取消全选（跳过 `props.disabled` 命中的节点；懒加载未展开层级需先 `expandAll()`） |
|
|
5559
|
+
| `clearChecked` | 清空所有勾选与半选 |
|
|
5560
|
+
| `getCurrentKey` | 当前高亮（选中）节点的 key，无选中返回 `null` |
|
|
5561
|
+
| `getCurrentNode` | 当前高亮节点的数据，无选中返回 `null` |
|
|
5562
|
+
| `setCurrentKey` | 设置高亮节点：传 `null` 取消高亮，`expandParent` 是否自动展开父级 |
|
|
5563
|
+
| `setCurrentNode` | 按节点实例设置高亮 |
|
|
5564
|
+
| `filter` | 按值过滤节点（配合 `filterTreeNode`；传空串恢复全量显示） |
|
|
5565
|
+
| `expandAll` | 展开全部已加载节点 |
|
|
5566
|
+
| `collapseAll` | 收起全部节点 |
|
|
5567
|
+
| `getNode` | 取节点实例（可读 `node.checked` / `node.expanded` / `node.level` 等内部状态） |
|
|
5568
|
+
| `getNodePath` | 取从根到该节点的完整路径数据（面包屑、级联回显用） |
|
|
5569
|
+
| `updateKeyChildren` | 按 key 替换子节点数据（懒加载接口回来后刷新某一支） |
|
|
5570
|
+
| `append` | 在父节点下追加子节点：`parentData` 传 key / 数据 / 节点实例，缺省追加到根 |
|
|
5571
|
+
| `insertBefore` | 在参考节点之前插入兄弟节点 |
|
|
5572
|
+
| `insertAfter` | 在参考节点之后插入兄弟节点 |
|
|
5573
|
+
| `remove` | 删除节点（传 key 或节点数据） |
|
|
5370
5574
|
|
|
5371
5575
|
#### `ZlTreeSelect`
|
|
5372
5576
|
|
|
@@ -5438,15 +5642,15 @@ import { ZlChart } from '@zl-ui-kit/components/chart'
|
|
|
5438
5642
|
|
|
5439
5643
|
**暴露（defineExpose）**
|
|
5440
5644
|
|
|
5441
|
-
| 名称 | 说明
|
|
5442
|
-
| ------- |
|
|
5443
|
-
| `clear` |
|
|
5645
|
+
| 名称 | 说明 |
|
|
5646
|
+
| ------- | ----------------------------------------------------------------- |
|
|
5647
|
+
| `clear` | 清空图表内容（保留 echarts 实例，后续 `option` 变化仍可继续渲染） |
|
|
5444
5648
|
|
|
5445
5649
|
#### `ZlEditor`
|
|
5446
5650
|
|
|
5447
5651
|
<sub>入口 `@zl-ui-kit/components/editor` · 源码 `packages/components/src/components/ZlEditor/index.vue` · ⚠️ 不在主入口，需从子路径 import，并自行安装对应 peer 依赖</sub>
|
|
5448
5652
|
|
|
5449
|
-
**接口概览**：3 props · 1 事件
|
|
5653
|
+
**接口概览**：3 props · 1 事件 · 10 暴露
|
|
5450
5654
|
|
|
5451
5655
|
**用法示例**
|
|
5452
5656
|
|
|
@@ -5468,17 +5672,34 @@ import { ZlEditor } from '@zl-ui-kit/components/editor'
|
|
|
5468
5672
|
| `language` | `string` | `'javascript'` | 否 | `language="javascript"` | 语法高亮所用语言 id，默认 javascript |
|
|
5469
5673
|
| `options` | `Record<string, any>` | `() => ({})` | 否 | `:options="{}"` | monaco 编辑器配置，覆盖内置默认项 |
|
|
5470
5674
|
|
|
5675
|
+
> 暴露对象是 `Proxy`：下表为显式实现的能力，**未列出的键会运行时下钻到内部实例**（不建议依赖，请用上表的实例 getter 取原生对象）
|
|
5676
|
+
|
|
5471
5677
|
**事件（emits）**
|
|
5472
5678
|
|
|
5473
5679
|
| 事件 | 参数 | 说明 |
|
|
5474
5680
|
| ------------------- | -------- | -------------- |
|
|
5475
5681
|
| `update:modelValue` | `string` | `v-model` 更新 |
|
|
5476
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
|
+
|
|
5477
5698
|
#### `ZlSqlEditor`
|
|
5478
5699
|
|
|
5479
5700
|
<sub>入口 `@zl-ui-kit/components/editor` · 源码 `packages/components/src/components/ZlEditor/ZlSqlEditor.vue` · ⚠️ 不在主入口，需从子路径 import，并自行安装对应 peer 依赖</sub>
|
|
5480
5701
|
|
|
5481
|
-
**接口概览**：4 props · 1 事件
|
|
5702
|
+
**接口概览**：4 props · 1 事件 · 3 暴露
|
|
5482
5703
|
|
|
5483
5704
|
**用法示例**
|
|
5484
5705
|
|
|
@@ -5501,6 +5722,7 @@ import { ZlSqlEditor } from '@zl-ui-kit/components/editor'
|
|
|
5501
5722
|
| `customKeywords` | `string[]` | `() => []` | 否 | `:custom-keywords="[]"` | 追加到内置保留字表的自定义关键字 |
|
|
5502
5723
|
| `customFunctions` | `string[]` | `() => []` | 否 | `:custom-functions="[]"` | 参与补全提示的自定义函数名 |
|
|
5503
5724
|
|
|
5725
|
+
> 暴露对象是 `Proxy`：下表为显式实现的能力，**未列出的键会运行时下钻到内部实例**（不建议依赖，请用上表的实例 getter 取原生对象）
|
|
5504
5726
|
> 把 `$attrs` 透传给 `ZlEditor`，未列出的属性会继续下传
|
|
5505
5727
|
|
|
5506
5728
|
**事件（emits）**
|
|
@@ -5509,6 +5731,14 @@ import { ZlSqlEditor } from '@zl-ui-kit/components/editor'
|
|
|
5509
5731
|
| ------------------- | -------- | -------------- |
|
|
5510
5732
|
| `update:modelValue` | `string` | `v-model` 更新 |
|
|
5511
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
|
+
|
|
5512
5742
|
#### `ZlFilePreview`
|
|
5513
5743
|
|
|
5514
5744
|
<sub>入口 `@zl-ui-kit/components/file-preview` · 源码 `packages/components/src/components/ZlFilePreview/index.vue` · ⚠️ 不在主入口，需从子路径 import，并自行安装对应 peer 依赖</sub>
|
|
@@ -5722,36 +5952,41 @@ ZlGrid 子项 schema
|
|
|
5722
5952
|
10. **列表页操作按钮归位**：使用 `ZlSearchTable` 或 `ZlCardPage` 替换的列表页，其「新增 / 导入 / 导出」等操作按钮统一放进对应组件的 `search-actions` 插槽（亦兼容 camelCase `searchActions`）。
|
|
5723
5953
|
11. **其余 Element Plus 组件**：剩余 `el-` 开头的 Element Plus 组件，均按 §3 组件总览的命名对应关系替换为对应的 Zl 组件（如 `el-tree`→`ZlTree`、`el-upload`→`ZlUpload`、`el-tag`→`ZlTag`、`el-tabs`→`ZlTabs` 等）。
|
|
5724
5954
|
12. **工具方法复用**：宿主项目里使用的工具类方法，需先与 `@zl-ui-kit/utils` 中的工具方法比对（完整清单见 §12.2，精确签名见 §12.3）；若存在**最终效果一致**的实现，统一使用 `@zl-ui-kit/utils` 的方法替换，避免重复实现与行为不一致。
|
|
5955
|
+
13. **先读透传契约**：动手替换前读完 [§15.5 迁移行为差异与透传契约](#155-迁移行为差异与透传契约必读)——未列在 props 表的属性与事件大多直接透传给内部 `el-*`，而少数默认值 / 入参语义与 EP 不等价，需逐条核对。
|
|
5725
5956
|
|
|
5726
5957
|
### 15.2 常用 el-* → Zl-* 对照表（持续补充）
|
|
5727
5958
|
|
|
5728
|
-
| Element Plus 组件
|
|
5729
|
-
|
|
|
5730
|
-
| `el-table`（普通 / 分页列表）
|
|
5731
|
-
| `el-table`（卡片分页列表）
|
|
5732
|
-
| `el-table`（纯表格，无查询）
|
|
5733
|
-
| `el-dialog` / `el-drawer`
|
|
5734
|
-
| `el-form`
|
|
5735
|
-
| `el-card`
|
|
5736
|
-
| `el-button`（操作栏 / 卡片内）
|
|
5737
|
-
| `el-tooltip`（超长省略）
|
|
5738
|
-
| `el-icon`
|
|
5739
|
-
| `el-tree`
|
|
5740
|
-
| `el-upload`
|
|
5741
|
-
| `el-tag`
|
|
5742
|
-
| `el-tabs`
|
|
5743
|
-
| `el-radio`（标签式）
|
|
5744
|
-
| `el-checkbox`（标签式）
|
|
5745
|
-
| `el-
|
|
5746
|
-
| `el-
|
|
5747
|
-
| `el-
|
|
5748
|
-
| `el-
|
|
5749
|
-
| `el-
|
|
5750
|
-
| `el-
|
|
5751
|
-
| `el-
|
|
5752
|
-
| `el-
|
|
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` | |
|
|
5753
5987
|
|
|
5754
5988
|
> 未在上表中的 `el-*` 组件，请对照 §3 组件总览的命名与用途选择对应 Zl 组件；若暂无对应实现，暂保留 `el-*`，并在本规范登记为待补充项。
|
|
5989
|
+
> 替换前请先读 **[§15.5 迁移行为差异与透传契约](#155-迁移行为差异与透传契约必读)**：哪些属性默认直接透传、哪些行为与 EP 不等价。
|
|
5755
5990
|
|
|
5756
5991
|
### 15.3 列表页操作按钮归位（search-actions 插槽）
|
|
5757
5992
|
|
|
@@ -5807,3 +6042,33 @@ ZlGrid 子项 schema
|
|
|
5807
6042
|
> 比对原则：**先看最终效果是否一致，再决定替换**——若宿主实现带特殊业务分支（如特定容错、字段命名差异），替换后需回归验证；
|
|
5808
6043
|
> 无法确认一致时暂保留宿主实现，并在本表登记为待补充项。
|
|
5809
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。修复方向以“**不破坏已有写法**”为序。
|