@zl-ui-kit/components 0.10.0 → 0.10.2
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
CHANGED
|
@@ -614,20 +614,24 @@ presetIconifyIcon(icons)
|
|
|
614
614
|
经 `useDict(dictKey)` 解析独立字典 store（`useDictStore`，Vue3 状态管理缓存，不依赖全局数据）。**支持三种数据注入方式**（详见第 12.1.3 节与第 6.3 节 ⑤）：
|
|
615
615
|
|
|
616
616
|
```vue
|
|
617
|
+
<!-- 直传 dict 时用专属 dictKey：直传会覆盖全局同名 key 的字典缓存 -->
|
|
617
618
|
<ZlDictTag
|
|
618
|
-
dict-key="
|
|
619
|
-
:value="row.
|
|
619
|
+
dict-key="gender"
|
|
620
|
+
:value="row.gender"
|
|
620
621
|
:dict="[
|
|
621
|
-
{ label: '
|
|
622
|
-
{ label: '
|
|
622
|
+
{ label: '男', value: '1', color: 'primary', icon: 'zl:user' },
|
|
623
|
+
{ label: '女', value: '2', color: 'pinkpurple' },
|
|
623
624
|
]"
|
|
624
625
|
/>
|
|
625
626
|
|
|
627
|
+
<!-- 靠全局 setDictSource 注册的字典翻译 -->
|
|
626
628
|
<ZlDictTag dict-key="resourceType" :value="row.type" />
|
|
627
|
-
<ZlDictTag dict-key="
|
|
629
|
+
<ZlDictTag dict-key="resourceStatus" :value="String(row.status)" simple />
|
|
628
630
|
```
|
|
629
631
|
|
|
630
|
-
|
|
632
|
+
字典项字段：`label` / `value`（都是字符串，与 `:value` 做 `===` 比较）/ `icon`（须是 `@zl-ui-kit/icons` 里真实存在的图标名）/
|
|
633
|
+
`color`（主题色名，如 `primary` / `success` / `warning` / `danger` / `gray`，不是 CSS 颜色值）；
|
|
634
|
+
`type` 为旧写法兜底（`color` 优先，`info` 自动映射为 `gray`）。详见第 6.3 节 ⑤。
|
|
631
635
|
|
|
632
636
|
### ZlCard / ZlPagination — 卡片与分页的视觉约定
|
|
633
637
|
|
|
@@ -843,16 +847,26 @@ function onSearch(params) {
|
|
|
843
847
|
**A. 组件级直传（最轻量，推荐一次性/局部使用）**
|
|
844
848
|
|
|
845
849
|
```vue
|
|
850
|
+
<!-- ⚠️ 直传 `dict` 会覆盖全局同名 key 的字典缓存：用专属 dictKey，别在列表里逐行传不同的 `dict` -->
|
|
846
851
|
<ZlDictTag
|
|
847
|
-
dict-key="
|
|
848
|
-
:value="row.
|
|
852
|
+
dict-key="gender"
|
|
853
|
+
:value="row.gender"
|
|
849
854
|
:dict="[
|
|
850
|
-
{ label: '
|
|
851
|
-
{ label: '
|
|
855
|
+
{ label: '男', value: '1', color: 'primary', icon: 'zl:user' },
|
|
856
|
+
{ label: '女', value: '2', color: 'pinkpurple' },
|
|
852
857
|
]"
|
|
853
858
|
/>
|
|
854
859
|
```
|
|
855
860
|
|
|
861
|
+
字典项字段（`DictItem`）：`label` / `value` / `icon?`（图标名）/ `color?`（主题色名）/ `type?`（旧写法，等价 `color`，同传时 `color` 优先）。
|
|
862
|
+
三个容易踩的点：
|
|
863
|
+
|
|
864
|
+
- `color` 只认**色名**（`primary` / `success` / `warning` / `danger` / `gray` / `red` / `purple` / `cyan` …，
|
|
865
|
+
即 theme 发出的 `--zl-<色名>-*` 那一组，见 §10 变量速查），不是 CSS 颜色值——
|
|
866
|
+
传 `#67C23A` 会拼出非法 class 而静默无样式；本库没有 `info` 色名，EP 习惯的 `type: 'info'` 会自动映射为 `gray`。
|
|
867
|
+
- `value` 是字符串且与 `:value` 做 `===` 比较：后端返回数字状态码（`status: 1`）时要先 `String()` 归一，否则匹配不到且不报错，直接原样显示。
|
|
868
|
+
- 图标名须在 `@zl-ui-kit/icons` 里真实存在（可用 `pnpm --filter @zl-ui-kit/icons` 的清单或 icons.json 查），未注册则渲染空白。
|
|
869
|
+
|
|
856
870
|
**B. 全局注册数据源（应用入口注册一次，全项目共享，适配不同项目）**
|
|
857
871
|
|
|
858
872
|
```ts
|
|
@@ -972,7 +986,9 @@ req.cancel() // 取消进行中请求
|
|
|
972
986
|
|
|
973
987
|
3. **`ZlChart` 传参**：用 `series` prop + 其余 attrs 透传（推荐 `v-bind` 传整个 option），勿只传 `:option`。
|
|
974
988
|
4. **图标名必须存在**：字典/组件 `icon` 用的名字须在 `icons.json` 真实存在。
|
|
975
|
-
5.
|
|
989
|
+
5. **字典上色只认色名，且直传会污染全局缓存**：`color`（或旧写法 `type`）传 CSS 颜色值 / `info` 这类色板外的名字会静默无样式；
|
|
990
|
+
`ZlDictTag` 的 `:dict` 直传是写进全局 `dictStore[dictKey]` 的，在列表里逐行传不同字典会互相覆盖（用专属 key）。
|
|
991
|
+
6. **分页键名对齐**：后端用 `current/pageSize/list` 而非 `pageNum/pageSize/rows` 时，用 `pagination` 选项或 `setGlobalOptions` 覆盖。
|
|
976
992
|
|
|
977
993
|
---
|
|
978
994
|
|
|
@@ -1422,7 +1438,7 @@ g.resetUser() // 登出：清 user / roles / permissions / token
|
|
|
1422
1438
|
#### 12.1.3 字典与国际化
|
|
1423
1439
|
|
|
1424
1440
|
- `useDictStore`（全局字典 store，基于 Vue3 `createGlobalState` 单例）：`dictStore`（缓存 `Record<key, DictItem[]>`）、`loadingKeys`、`setDictSource(source|null)`、`getDictSource()`、`ensureDict(key, localSource?)`。同一 key 仅在缓存未命中且未在加载时触发一次加载，结果缓存复用。
|
|
1425
|
-
- `useDict(key, options?)` → `ComputedRef<DictItem[]>`（附带 `.label: Record<value,label>`）：读 `useDictStore` 并解析。数据解析优先级：组件级 `options.data` → 局部 `useDictProvider({ source })` → 全局 `setDictSource(source)`。`DictItem = { label, value, icon?, type? }`（亦可用 `type DictItem`
|
|
1441
|
+
- `useDict(key, options?)` → `ComputedRef<DictItem[]>`（附带 `.label: Record<value,label>`）：读 `useDictStore` 并解析。数据解析优先级：组件级 `options.data` → 局部 `useDictProvider({ source })` → 全局 `setDictSource(source)`。`DictItem = { label, value, icon?, color?, type? }`（亦可用 `type DictItem` 导入；`value` 为字符串且与业务值做 `===` 比较，`color` 只认色名，`type` 为旧写法兜底）。
|
|
1426
1442
|
- `setDictSource(source | null)`：全局注册字典数据源（应用入口调用一次）。`source` 为静态表 `Record<string, DictItem[]>` 或函数 `(key) => DictItem[] | Promise<DictItem[]>`；传 `null` 清空。`getDictSource()` 可读取当前值。
|
|
1427
1443
|
- `useDictProvider(source)`：子树根提供局部字典数据源（覆盖全局）。
|
|
1428
1444
|
- `useLocale(options?, loader?)` → `{ i18n, locale, isI18nKeyVisible }`：创建与全局语言联动的 vue-i18n 实例；`loader(locale)` 按需返回 `{ localeMessages, elLocaleMessages }`（业务包 + Element Plus locale）。`elLocaleMessages` 写入全局数据后，**必须**由 `ZlI18nProvider` 经 `<el-config-provider>` 挂载到 Element Plus 才生效（分页 / 日期选择器等内置组件才本地化）。详见第 13 章。
|
|
@@ -2911,12 +2927,13 @@ setupRequest(request: AxiosInstance, onRequest?: (config: AxiosRequestConfig) =>
|
|
|
2911
2927
|
|
|
2912
2928
|
> 字典项
|
|
2913
2929
|
|
|
2914
|
-
| 字段
|
|
2915
|
-
|
|
|
2916
|
-
| `label`
|
|
2917
|
-
| `value`
|
|
2918
|
-
| `icon?`
|
|
2919
|
-
| `
|
|
2930
|
+
| 字段 | 类型 | 必填 | 说明 |
|
|
2931
|
+
| -------- | -------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
2932
|
+
| `label` | `string` | 必填 | — |
|
|
2933
|
+
| `value` | `string` | 必填 | 字典值。与业务侧传入的 `value` 做**严格相等**比较， 业务数据是数字码（如 `status: 1`）时必须先 `String()` 归一，否则匹配不到。 |
|
|
2934
|
+
| `icon?` | `string` | 可选 | 标签前置图标名，须是 `@zl-ui-kit/icons` 里真实存在的名字（未注册则渲染空白） |
|
|
2935
|
+
| `color?` | `string` | 可选 | 标签主题色名。作用于 `ZlTag` 的 `color`，只认**色名**（`primary` / `success` / `warning` / `danger` / `gray` / `red` …），不是 CSS 颜色值；传 `#67C23A` 会拼成非法 class 而静默无样式。 |
|
|
2936
|
+
| `type?` | `string` | 可选 | 兼容 Element Plus / arco 写法的语义色名，等价于 `color`（两者同传时 `color` 优先）。 其中 `info` 在本库色板里没有对应色名，会映射为 `gray`。 |
|
|
2920
2937
|
|
|
2921
2938
|
##### `RelativeRect`
|
|
2922
2939
|
|
|
@@ -3877,7 +3894,7 @@ import { ZlDictTag } from '@zl-ui-kit/components'
|
|
|
3877
3894
|
</script>
|
|
3878
3895
|
|
|
3879
3896
|
<template>
|
|
3880
|
-
<ZlDictTag dict-key="
|
|
3897
|
+
<ZlDictTag dict-key="dictTagDemo" value="1" :dict="dict" />
|
|
3881
3898
|
</template>
|
|
3882
3899
|
```
|
|
3883
3900
|
|
|
@@ -3885,15 +3902,15 @@ import { ZlDictTag } from '@zl-ui-kit/components'
|
|
|
3885
3902
|
|
|
3886
3903
|
**props**
|
|
3887
3904
|
|
|
3888
|
-
| 属性 | 类型 | 默认值 | 必填 | 示例 | 说明
|
|
3889
|
-
| ------------- | ------------------------------------------------------------------------- | ----------- | ---- | ------------------- |
|
|
3890
|
-
| `dictKey` | `string` | — | 是 | `dict-key="gender"` |
|
|
3891
|
-
| `dict` | `DictItem[]` | — | 否 | `:dict="dict"` | 外部直传字典数据：无需依赖全局数据源即可翻译。格式同 DictItem[]
|
|
3892
|
-
| `corner` | `boolean \| 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `false` | 否 | `corner="top-left"` | 是否渲染成角标并指定方位，true 时为右上角
|
|
3893
|
-
| `value` | `string` | — | 否 | `value="1"` |
|
|
3894
|
-
| `simple` | `boolean` | — | 否 | `simple` | 忽略字典项自带的颜色，改用标签默认配色
|
|
3895
|
-
| `iconVisible` | `boolean` | `undefined` | 否 | `icon-visible` | 是否展示字典项图标（默认 true）
|
|
3896
|
-
| `hideIcon` | `boolean` | `undefined` | 否 | `hide-icon` | 已废弃，请用 `iconVisible` 控制图标显隐
|
|
3905
|
+
| 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
|
|
3906
|
+
| ------------- | ------------------------------------------------------------------------- | ----------- | ---- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
3907
|
+
| `dictKey` | `string` | — | 是 | `dict-key="gender"` | 字典键（对应全局字典缓存的键；外部直传数据也以该键写入共享缓存）。 ⚠️ 直传 `dict` 会**覆盖全局同名 key**，不要在列表里逐行传不同的 `dict`（最后一行会污染全站）， 行级字典请用独立 key（如 `` `resourceType.${row.id}` ``）。 |
|
|
3908
|
+
| `dict` | `DictItem[]` | — | 否 | `:dict="dict"` | 外部直传字典数据：无需依赖全局数据源即可翻译。格式同 `DictItem[]`（`{ label, value, icon?, color?, type? }`） |
|
|
3909
|
+
| `corner` | `boolean \| 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `false` | 否 | `corner="top-left"` | 是否渲染成角标并指定方位，true 时为右上角 |
|
|
3910
|
+
| `value` | `string` | — | 否 | `value="1"` | 待翻译的字典值，匹配不到时原样展示。 与字典项的 `value` 做**严格相等**比较，后端返回数字状态码时要先转成字符串 （`:value="String(row.status)"`，或在字典数据源里归一）。 |
|
|
3911
|
+
| `simple` | `boolean` | — | 否 | `simple` | 忽略字典项自带的颜色，改用标签默认配色 |
|
|
3912
|
+
| `iconVisible` | `boolean` | `undefined` | 否 | `icon-visible` | 是否展示字典项图标（默认 true） |
|
|
3913
|
+
| `hideIcon` | `boolean` | `undefined` | 否 | `hide-icon` | 已废弃，请用 `iconVisible` 控制图标显隐 |
|
|
3897
3914
|
|
|
3898
3915
|
> 把 `$attrs` 透传给 `zl-corner-tag`，未列出的属性会继续下传
|
|
3899
3916
|
|
|
@@ -4184,17 +4201,17 @@ import { ZlForm } from '@zl-ui-kit/components'
|
|
|
4184
4201
|
|
|
4185
4202
|
**暴露（defineExpose）**
|
|
4186
4203
|
|
|
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 实例，未列出的能力兜底用
|
|
4204
|
+
| 名称 | 说明 |
|
|
4205
|
+
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
|
|
4206
|
+
| `validate` | 校验整个表单；同 `el-form.validate()`（无回调时失败会 reject 错误字段集合；0.9.0 及更早成功时返回 `undefined`） |
|
|
4207
|
+
| `validateField` | 校验指定字段（字段名或数组），语义同 `validate()` |
|
|
4208
|
+
| `resetFields` | 重置字段并清除校验结果；不传参重置全部 |
|
|
4209
|
+
| `clearValidate` | 清除校验提示；不传参清除全部 |
|
|
4210
|
+
| `scrollToField` | 滚动到指定字段 |
|
|
4211
|
+
| `getField` | 取单个表单项上下文（含 `resetField`/`clearValidate`/`validateMessage` 等） |
|
|
4212
|
+
| `fields` | 全部表单项上下文（含 `prop`/`value`/`validateState` 等） |
|
|
4213
|
+
| `setInitialValues` | 写入字段初始值（`resetFields` 会回到这些值） |
|
|
4214
|
+
| `elForm` | 内部 ElForm 实例，未列出的能力兜底用 |
|
|
4198
4215
|
|
|
4199
4216
|
#### `ZlFormChild`
|
|
4200
4217
|
|
|
@@ -5936,7 +5953,7 @@ ZlGrid 子项 schema
|
|
|
5936
5953
|
## 15. 组件替换规范（Element Plus → Zl-*）
|
|
5937
5954
|
|
|
5938
5955
|
> 本规范约定：宿主项目引入本组件库后，**优先使用 Zl 系列组件替代对应的 Element Plus 组件**，并**复用 `@zl-ui-kit/utils` 的工具方法替代重复实现**，以保证主题、国际化、字典、权限与交互体验统一。
|
|
5939
|
-
> 规范持续补充中——新增替换项请追加到 §15.2（组件）/ §15.4
|
|
5956
|
+
> 规范持续补充中——新增替换项请追加到 §15.2（组件）/ §15.4（工具方法）对照表，hooks 类替换补进 §15.1 规则，并在对应规则处补充示例。各组件的具体 props / 插槽 / 事件以 §14 组件 API 参考与 playground 示例为准。
|
|
5940
5957
|
|
|
5941
5958
|
### 15.1 核心替换规则
|
|
5942
5959
|
|
|
@@ -5952,38 +5969,42 @@ ZlGrid 子项 schema
|
|
|
5952
5969
|
10. **列表页操作按钮归位**：使用 `ZlSearchTable` 或 `ZlCardPage` 替换的列表页，其「新增 / 导入 / 导出」等操作按钮统一放进对应组件的 `search-actions` 插槽（亦兼容 camelCase `searchActions`）。
|
|
5953
5970
|
11. **其余 Element Plus 组件**：剩余 `el-` 开头的 Element Plus 组件，均按 §3 组件总览的命名对应关系替换为对应的 Zl 组件（如 `el-tree`→`ZlTree`、`el-upload`→`ZlUpload`、`el-tag`→`ZlTag`、`el-tabs`→`ZlTabs` 等）。
|
|
5954
5971
|
12. **工具方法复用**：宿主项目里使用的工具类方法，需先与 `@zl-ui-kit/utils` 中的工具方法比对（完整清单见 §12.2，精确签名见 §12.3）；若存在**最终效果一致**的实现，统一使用 `@zl-ui-kit/utils` 的方法替换，避免重复实现与行为不一致。
|
|
5955
|
-
13.
|
|
5972
|
+
13. **字典加载与翻译**：宿主页面里「请求字典接口 → 存成选项数组 → 再用 `Record<value, label>` 把码值转中文」的自建逻辑，统一换成 `useDict` + `ZlDictTag` —— 应用入口用 `setDictSource(...)` 注册**一次**数据源（静态表，或 `(key) => api.getDict(key)` 异步加载），页面内用 `useDict(key)` 取字典项与 `value → label` 映射（`useDict(key).value` 是 `DictItem[]`，`useDict(key).label.value[code]` 是中文）供下拉 / 单选等选项使用，表格与详情里的字典列直接用 `<ZlDictTag :dict-key="key" :value="row.xxx" />` 渲染；**不要在页面里各自请求字典接口，也不要再维护 label 常量表**（同一字典被多处重复请求、各处文案不一致，正是这类自建逻辑的典型副作用）。两个易踩点：`dictKey` 是**全局缓存键**（同一 key 只加载一次、跨组件复用），列表里**不要逐行直传不同的 `:dict`**（会覆盖全局同名缓存、最后一行赢，行级字典请用专属 key）；`DictItem.value` 是字符串且与业务值做**严格相等**比较，后端返回数字码时要先 `String()`。详见 §6.3 ⑤ 与 §12.1.3。
|
|
5973
|
+
14. **提示消息**：页面里的 `ElMessage` / `ElMessageBox` / `ElNotification`（含 `ElMessage.success(...)`、`ElMessageBox.confirm(...)`、`ElNotification({...})` 等写法）统一改用 `useGlobalMessage()` 取实例 —— `const { Message, Modal, Notification } = useGlobalMessage()`；其中 `Modal` 在 `ElMessageBox` 之上扩展了 `confirmPromise(config, onOk, onCancel)`，需要「二次确认 + 执行异步操作（如删除）」时优先用它：返回 `'Ok' | 'Cancel' | false`，由它统一处理关闭时机与 `onOk` 抛错（`throwOnOk` / `throwOnCancel` 可控），不必每处各写一遍 `.then/.catch`；同时保证与组件库走**同一份 element-plus 实例**（peer 依赖），而不是再引入一套 EP。详见 §12.1.4。
|
|
5974
|
+
15. **先读透传契约**：动手替换前读完 [§15.5 迁移行为差异与透传契约](#155-迁移行为差异与透传契约必读)——未列在 props 表的属性与事件大多直接透传给内部 `el-*`，而少数默认值 / 入参语义与 EP 不等价，需逐条核对。
|
|
5956
5975
|
|
|
5957
5976
|
### 15.2 常用 el-* → Zl-* 对照表（持续补充）
|
|
5958
5977
|
|
|
5959
|
-
| Element Plus 组件 | 替换为
|
|
5960
|
-
| ------------------------------------------------- |
|
|
5961
|
-
| `el-table`（普通 / 分页列表） | `ZlSearchTable`
|
|
5962
|
-
| `el-table`（卡片分页列表） | `ZlCardPage`
|
|
5963
|
-
| `el-table`（纯表格，无查询） | `ZlTable`
|
|
5964
|
-
| `el-dialog` / `el-drawer` | `ZlDrawer`
|
|
5965
|
-
| `el-form` | `ZlForm`
|
|
5966
|
-
| `el-card` | `ZlCard`
|
|
5967
|
-
| `el-button`（操作栏 / 卡片内） | `ZlAction`
|
|
5968
|
-
| `el-tooltip`（超长省略） | `ZlAutoTooltip`
|
|
5969
|
-
| `el-icon` | `ZlIcon`
|
|
5970
|
-
| `el-tree` | `ZlTree`
|
|
5971
|
-
| `el-upload` | `ZlUpload`
|
|
5972
|
-
| `el-tag` | `ZlTag`
|
|
5973
|
-
| `el-tabs` | `ZlTabs`
|
|
5974
|
-
| `el-radio`（标签式） | `ZlRadioTag`
|
|
5975
|
-
| `el-checkbox`（标签式） | `ZlCheckboxTag`
|
|
5976
|
-
| `el-checkbox`（全选 / 半选） | `ZlCheckAll`
|
|
5977
|
-
| `el-radio` / `el-checkbox`（普通单选框 / 复选框） | —（**有意不封装**）
|
|
5978
|
-
| `el-radio-group` / `el-checkbox-group` | —（**有意不封装**）
|
|
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`
|
|
5978
|
+
| Element Plus 组件 | 替换为 | 说明 |
|
|
5979
|
+
| ------------------------------------------------- | -------------------- | ------------------------------------------------------------------ |
|
|
5980
|
+
| `el-table`（普通 / 分页列表） | `ZlSearchTable` | 自带查询条、分页、loading |
|
|
5981
|
+
| `el-table`（卡片分页列表） | `ZlCardPage` | 卡片式分页列表 |
|
|
5982
|
+
| `el-table`（纯表格，无查询） | `ZlTable` | 普通表格展示 |
|
|
5983
|
+
| `el-dialog` / `el-drawer` | `ZlDrawer` | 所有弹窗统一为抽屉 |
|
|
5984
|
+
| `el-form` | `ZlForm` | 弹窗内新增 / 编辑 / 详情表单（schema 驱动） |
|
|
5985
|
+
| `el-card` | `ZlCard` | 卡片容器 |
|
|
5986
|
+
| `el-button`（操作栏 / 卡片内） | `ZlAction` | 操作列与卡片按钮；页面级独立按钮仍可用 `el-button` |
|
|
5987
|
+
| `el-tooltip`（超长省略） | `ZlAutoTooltip` | 文字溢出时自动提示 |
|
|
5988
|
+
| `el-icon` | `ZlIcon` | 需先注册图标集（§4.1） |
|
|
5989
|
+
| `el-tree` | `ZlTree` | 勾选多选 / 字段映射 / 暴露方法见 §7 › ZlTree |
|
|
5990
|
+
| `el-upload` | `ZlUpload` | |
|
|
5991
|
+
| `el-tag` | `ZlTag` | |
|
|
5992
|
+
| `el-tabs` | `ZlTabs` | 页签内容默认懒挂载，差异见 §15.5 |
|
|
5993
|
+
| `el-radio`（标签式） | `ZlRadioTag` | 仅此形态封装 |
|
|
5994
|
+
| `el-checkbox`（标签式） | `ZlCheckboxTag` | 仅此形态封装 |
|
|
5995
|
+
| `el-checkbox`（全选 / 半选） | `ZlCheckAll` | 自带半选态，可替代表头全选勾选框 |
|
|
5996
|
+
| `el-radio` / `el-checkbox`（普通单选框 / 复选框） | —（**有意不封装**） | 继续用 `el-*`，库内无对应物（见 §15.5） |
|
|
5997
|
+
| `el-radio-group` / `el-checkbox-group` | —（**有意不封装**） | 继续用 `el-*`，组内选项自行渲染 |
|
|
5998
|
+
| `el-switch` | `ZlSwitch` | |
|
|
5999
|
+
| `el-popconfirm` | `ZlPopconfirm` | |
|
|
6000
|
+
| `el-empty` | `ZlEmpty` | |
|
|
6001
|
+
| `el-avatar` | `ZlAvatar` | |
|
|
6002
|
+
| `el-descriptions` | `ZlDescription` | |
|
|
6003
|
+
| `el-text` | `ZlText` | |
|
|
6004
|
+
| `el-pagination` | `ZlPagination` | |
|
|
6005
|
+
| `el-select`（树形） | `ZlTreeSelect` | |
|
|
6006
|
+
| `ElMessage` / `ElNotification`（提示消息） | `useGlobalMessage()` | 非组件，用 hook 取 `Message` / `Notification` 实例（§12.1.4） |
|
|
6007
|
+
| `ElMessageBox`（确认框） | `useGlobalMessage()` | 取 `Modal`（扩展 `confirmPromise`），二次确认 + 异步操作统一在这里 |
|
|
5987
6008
|
|
|
5988
6009
|
> 未在上表中的 `el-*` 组件，请对照 §3 组件总览的命名与用途选择对应 Zl 组件；若暂无对应实现，暂保留 `el-*`，并在本规范登记为待补充项。
|
|
5989
6010
|
> 替换前请先读 **[§15.5 迁移行为差异与透传契约](#155-迁移行为差异与透传契约必读)**：哪些属性默认直接透传、哪些行为与 EP 不等价。
|
|
@@ -6057,18 +6078,19 @@ ZlGrid 子项 schema
|
|
|
6057
6078
|
|
|
6058
6079
|
#### 与 Element Plus 不等价 / 需注意事项
|
|
6059
6080
|
|
|
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` |
|
|
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
|
-
|
|
|
6081
|
+
| 组件 | 差异 | 迁移注意 |
|
|
6082
|
+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
6083
|
+
| `ZlDrawer` | `width` 映射到内部 `size`（默认 `600`）；`destroy-on-close` **默认 `true`**（EP 默认 `false`）；自带底部取消 / 确定按钮区 | 抽屉内容**关闭即销毁**，内部状态不保留；需保留状态时显式传 `:destroy-on-close="false"` |
|
|
6084
|
+
| `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` |
|
|
6085
|
+
| `ZlTable` | 列插槽按 `prop` 名命名，作用域含 `{ row, column, $index }`；暴露 `el-table` 的 15 个公开方法 + `elTable` getter | `tableRef.toggleRowSelection(row)` 等均有类型提示；其余方法走 `tableRef.elTable` |
|
|
6086
|
+
| `ZlSwitch` | 主名 `checked-value` / `unchecked-value`，同时**兼容 EP 的 `active-value` / `inactive-value` 别名**（同传时主名优先）；`@change` 参数是**业务值**而非内部布尔 | 直搬 `:active-value="'1'"` 可用；从 `el-switch` 迁移时注意 `@change` 入参含义已变 |
|
|
6087
|
+
| `ZlTabs` | schema 驱动：`tab.key`→`name`、`tab.title`→`label`；页签内容**默认懒挂载**（`lazy` / `lazyLoad` 默认 `true`）；内容写在以 key 命名的插槽里 | 需挂载时就初始化的页签要显式 `lazyLoad: false`；`type` / `tab-click` 等透传 `el-tabs` |
|
|
6088
|
+
| `ZlIcon` | 单色图标：尺寸走 `size`（作用在 `font-size`），颜色走 `color` / `currentColor`；`spin` / `rotate` 等仅 `zl:` 前缀（iconify）分支生效 | 图标名未注册或拼错时**不报错、不告警、只渲染空白**；迁移前用 `@zl-ui-kit/icons` 核名（见 §4.1） |
|
|
6089
|
+
| `ZlTree` | 勾选多选 / 字段映射 / 暴露方法的完整说明见 §7 › ZlTree | 从 `el-tree` 直搬时先核对 `node-key` 与字段映射 |
|
|
6090
|
+
| `ZlEditor` / `ZlSqlEditor` | 暴露对象是 `Proxy`：§14 列的是显式能力，未列出的 monaco 原生 API 靠运行时下钻（旧行为，**不算契约**）；`ZlSqlEditor.validate()` 不通过时 **`throw diagnostics`** | 需要原生能力时用 `editorRef.value.monacoEditor`（SQL 编辑器用 `.zlEditor`）；`format()` 内部会先校验 |
|
|
6091
|
+
| `ZlAppLayout` | 只声明 `layout`（`horizontal` / `vertical`）；插槽由同目录形态子组件定义（`footer` 仅 vertical，`logo` / `menu` 在 vertical 下带 `{ collapsed }`） | 菜单数据传给 `#menu` 里的 `ZlAppMenu`，**不要写 `:menus="…"` 给 `ZlAppLayout`**（未声明的 prop 会落到 DOM） |
|
|
6092
|
+
| `ZlDictTag` | 字典项的 `type` 从 **0.10.1** 起参与上色（`color ?? type`，`info` → `gray`）；更早版本只读 `color`，传 `type` 一律默认配色 | 升级后原来“无色”的标签会变有色（预期修正，属视觉变更，需回归）；直传 `:dict` 会覆盖全局同名 `dictKey` 缓存 |
|
|
6093
|
+
| 普通单选 / 复选框 | **有意不封装**：库内只有标签式的 `ZlRadioTag` / `ZlCheckboxTag` 与自带半选的 `ZlCheckAll` | `el-radio` / `el-checkbox` / `el-radio-group` / `el-checkbox-group` **继续用 `el-*`**，不要找 Zl 对应物；表头全选 / 半选场景可直接用 `ZlCheckAll` |
|
|
6072
6094
|
|
|
6073
6095
|
> 发现**文档与实现不一致**（包括本节未覆盖的组件）：先以源码与 playground 实跑为准，并在宿主侧登记；
|
|
6074
6096
|
> 属组件缺陷的回到本仓库修复（优先把契约补齐到与 EP 等价），属文档错误的直接修正本文件与 §14。修复方向以“**不破坏已有写法**”为序。
|
|
@@ -1,12 +1,20 @@
|
|
|
1
1
|
import { DictItem } from '@zl-ui-kit/composables';
|
|
2
2
|
type __VLS_Props = {
|
|
3
|
-
/**
|
|
3
|
+
/**
|
|
4
|
+
* 字典键（对应全局字典缓存的键；外部直传数据也以该键写入共享缓存）。
|
|
5
|
+
* ⚠️ 直传 `dict` 会**覆盖全局同名 key**，不要在列表里逐行传不同的 `dict`（最后一行会污染全站），
|
|
6
|
+
* 行级字典请用独立 key（如 `` `resourceType.${row.id}` ``）。
|
|
7
|
+
*/
|
|
4
8
|
dictKey: string;
|
|
5
|
-
/** 外部直传字典数据：无需依赖全局数据源即可翻译。格式同 DictItem[]
|
|
9
|
+
/** 外部直传字典数据：无需依赖全局数据源即可翻译。格式同 `DictItem[]`（`{ label, value, icon?, color?, type? }`） */
|
|
6
10
|
dict?: DictItem[];
|
|
7
11
|
/** 是否渲染成角标并指定方位，true 时为右上角 */
|
|
8
12
|
corner?: boolean | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
|
|
9
|
-
/**
|
|
13
|
+
/**
|
|
14
|
+
* 待翻译的字典值，匹配不到时原样展示。
|
|
15
|
+
* 与字典项的 `value` 做**严格相等**比较，后端返回数字状态码时要先转成字符串
|
|
16
|
+
* （`:value="String(row.status)"`，或在字典数据源里归一）。
|
|
17
|
+
*/
|
|
10
18
|
value?: string;
|
|
11
19
|
/** 忽略字典项自带的颜色，改用标签默认配色 */
|
|
12
20
|
simple?: boolean;
|
|
@@ -1,10 +1,10 @@
|
|
|
1
|
-
import { defineComponent as
|
|
2
|
-
import { useDict as
|
|
3
|
-
import
|
|
1
|
+
import { defineComponent as g, watch as _, computed as n, openBlock as l, createBlock as s, mergeProps as u, withCtx as d, createTextVNode as p, toDisplayString as f } from "vue";
|
|
2
|
+
import { useDict as h, useDictStore as B } from "@zl-ui-kit/composables";
|
|
3
|
+
import S from "../ZlTag/ZlCornerTag.vue.mjs";
|
|
4
4
|
import '../ZlTag/index.css';import '../ZlTag/ZlCornerTag.css';/* empty css */
|
|
5
|
-
import
|
|
5
|
+
import b from "../ZlTag/index.vue.mjs";
|
|
6
6
|
/* empty css */
|
|
7
|
-
const
|
|
7
|
+
const I = /* @__PURE__ */ g({
|
|
8
8
|
name: "ZlDictTag",
|
|
9
9
|
__name: "index",
|
|
10
10
|
props: {
|
|
@@ -17,41 +17,50 @@ const K = /* @__PURE__ */ f({
|
|
|
17
17
|
hideIcon: { type: Boolean, default: void 0 }
|
|
18
18
|
},
|
|
19
19
|
setup(i) {
|
|
20
|
-
const
|
|
21
|
-
|
|
22
|
-
() =>
|
|
23
|
-
(
|
|
24
|
-
if (
|
|
25
|
-
const { dictStore:
|
|
26
|
-
|
|
20
|
+
const t = i, m = h(t.dictKey, { data: t.dict });
|
|
21
|
+
_(
|
|
22
|
+
() => t.dict,
|
|
23
|
+
(e) => {
|
|
24
|
+
if (e?.length) {
|
|
25
|
+
const { dictStore: o } = B();
|
|
26
|
+
o.value = { ...o.value, [t.dictKey]: e };
|
|
27
27
|
}
|
|
28
28
|
},
|
|
29
29
|
{ deep: !1 }
|
|
30
30
|
);
|
|
31
|
-
const
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
31
|
+
const r = n(() => m.value.find((e) => e.value === t.value)), v = { info: "gray" };
|
|
32
|
+
function y(e) {
|
|
33
|
+
const o = e.color ?? e.type;
|
|
34
|
+
if (o)
|
|
35
|
+
return v[o] ?? o;
|
|
36
|
+
}
|
|
37
|
+
const a = n(() => {
|
|
38
|
+
const e = r.value;
|
|
39
|
+
return e ? {
|
|
40
|
+
color: t.simple ? void 0 : y(e),
|
|
41
|
+
icon: t.iconVisible ?? !t.hideIcon ? e.icon : void 0
|
|
42
|
+
} : {};
|
|
43
|
+
}), c = n(() => t.corner === !0 ? "top-right" : t.corner);
|
|
44
|
+
return (e, o) => c.value ? (l(), s(S, u({
|
|
36
45
|
key: 0,
|
|
37
46
|
class: "zl-dict-corner-tag"
|
|
38
|
-
}, { ...
|
|
47
|
+
}, { ...a.value, ...e.$attrs }, { position: c.value }), {
|
|
39
48
|
default: d(() => [
|
|
40
|
-
p(
|
|
49
|
+
p(f(r.value?.label || i.value), 1)
|
|
41
50
|
]),
|
|
42
51
|
_: 1
|
|
43
|
-
}, 16, ["position"])) : (
|
|
52
|
+
}, 16, ["position"])) : (l(), s(b, u({
|
|
44
53
|
key: 1,
|
|
45
54
|
class: "zl-dict-tag"
|
|
46
|
-
}, { ...
|
|
55
|
+
}, { ...a.value, ...e.$attrs }), {
|
|
47
56
|
default: d(() => [
|
|
48
|
-
p(
|
|
57
|
+
p(f(r.value?.label || i.value), 1)
|
|
49
58
|
]),
|
|
50
59
|
_: 1
|
|
51
60
|
}, 16));
|
|
52
61
|
}
|
|
53
62
|
});
|
|
54
63
|
export {
|
|
55
|
-
|
|
64
|
+
I as default
|
|
56
65
|
};
|
|
57
66
|
//# sourceMappingURL=index.vue.mjs.map
|
|
@@ -13,6 +13,8 @@ type FieldNames = string | string[];
|
|
|
13
13
|
* 校验整个表单，语义与 `el-form.validate()` 完全一致：
|
|
14
14
|
* 不传 callback 时返回 Promise（通过 `resolve(true)`，失败 `reject(错误字段集合)`）；
|
|
15
15
|
* 传 callback 时改为回调式（`callback(true)` / `callback(false, fields)`），不会抛错。
|
|
16
|
+
* 版本分界：**0.10.0 起**成功时返回 `true`；0.9.0 及更早的签名为 `Promise<void>`，
|
|
17
|
+
* 成功时 `resolve(undefined)`，`await validate()` 直接当布尔用会被误判为失败。
|
|
16
18
|
*/
|
|
17
19
|
declare function validate(callback?: ValidateCallback): Promise<boolean>;
|
|
18
20
|
/** 校验指定字段，语义同 `validate()` */
|
|
@@ -54,7 +56,7 @@ declare function __VLS_template(): {
|
|
|
54
56
|
};
|
|
55
57
|
type __VLS_TemplateResult = ReturnType<typeof __VLS_template>;
|
|
56
58
|
declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {
|
|
57
|
-
/** 校验整个表单；同 `el-form.validate()`（无回调时失败会 reject
|
|
59
|
+
/** 校验整个表单；同 `el-form.validate()`（无回调时失败会 reject 错误字段集合；0.9.0 及更早成功时返回 `undefined`） */
|
|
58
60
|
validate: typeof validate;
|
|
59
61
|
/** 校验指定字段（字段名或数组），语义同 `validate()` */
|
|
60
62
|
validateField: typeof validateField;
|
|
@@ -61,7 +61,7 @@ const G = { class: "zl-form-item-label" }, g = "onUpdate:modelValue", Q = /* @__
|
|
|
61
61
|
return await t.value?.validateField(e, l) ?? !0;
|
|
62
62
|
}
|
|
63
63
|
return y({
|
|
64
|
-
/** 校验整个表单；同 `el-form.validate()`（无回调时失败会 reject
|
|
64
|
+
/** 校验整个表单；同 `el-form.validate()`（无回调时失败会 reject 错误字段集合；0.9.0 及更早成功时返回 `undefined`） */
|
|
65
65
|
validate: $,
|
|
66
66
|
/** 校验指定字段（字段名或数组），语义同 `validate()` */
|
|
67
67
|
validateField: N,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zl-ui-kit/components",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "ZL UI 业务组件库（Element Plus 体系，Zl 前缀）——首批：Icon/AutoTooltip/Tag/CornerTag/Text/Title/Copy/Empty/Pagination/DictTag",
|
|
6
6
|
"license": "MIT",
|
|
@@ -39,9 +39,9 @@
|
|
|
39
39
|
"file-type": "^20.4.1",
|
|
40
40
|
"dt-sql-parser": "^4.3.1",
|
|
41
41
|
"sql-formatter": "^15.4.2",
|
|
42
|
-
"@zl-ui-kit/
|
|
43
|
-
"@zl-ui-kit/icons": "0.10.
|
|
44
|
-
"@zl-ui-kit/
|
|
42
|
+
"@zl-ui-kit/utils": "0.10.2",
|
|
43
|
+
"@zl-ui-kit/icons": "0.10.2",
|
|
44
|
+
"@zl-ui-kit/composables": "0.10.2"
|
|
45
45
|
},
|
|
46
46
|
"peerDependencies": {
|
|
47
47
|
"@vueuse/core": "^12.3.0",
|
|
@@ -98,10 +98,10 @@
|
|
|
98
98
|
"@vue-office/pdf": "^2.0.10",
|
|
99
99
|
"@vue-office/pptx": "1.0.1",
|
|
100
100
|
"echarts": "^5.6.0",
|
|
101
|
-
"@jichuang/eslint-config": "1.0.0",
|
|
102
101
|
"@jichuang/vite-config": "1.0.0",
|
|
103
102
|
"@jichuang/tsconfig": "1.0.0",
|
|
104
|
-
"@zl-ui-kit/theme": "0.10.
|
|
103
|
+
"@zl-ui-kit/theme": "0.10.2",
|
|
104
|
+
"@jichuang/eslint-config": "1.0.0"
|
|
105
105
|
},
|
|
106
106
|
"repository": {
|
|
107
107
|
"type": "git",
|