@zl-ui-kit/components 0.10.1 → 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.
Files changed (2) hide show
  1. package/README.md +34 -30
  2. package/package.json +7 -7
package/README.md CHANGED
@@ -5953,7 +5953,7 @@ ZlGrid 子项 schema
5953
5953
  ## 15. 组件替换规范（Element Plus → Zl-*）
5954
5954
 
5955
5955
  > 本规范约定：宿主项目引入本组件库后，**优先使用 Zl 系列组件替代对应的 Element Plus 组件**，并**复用 `@zl-ui-kit/utils` 的工具方法替代重复实现**，以保证主题、国际化、字典、权限与交互体验统一。
5956
- > 规范持续补充中——新增替换项请追加到 §15.2（组件）/ §15.4（工具方法）对照表，并在对应规则处补充示例。各组件的具体 props / 插槽 / 事件以 §14 组件 API 参考与 playground 示例为准。
5956
+ > 规范持续补充中——新增替换项请追加到 §15.2（组件）/ §15.4（工具方法）对照表，hooks 类替换补进 §15.1 规则，并在对应规则处补充示例。各组件的具体 props / 插槽 / 事件以 §14 组件 API 参考与 playground 示例为准。
5957
5957
 
5958
5958
  ### 15.1 核心替换规则
5959
5959
 
@@ -5969,38 +5969,42 @@ ZlGrid 子项 schema
5969
5969
  10. **列表页操作按钮归位**：使用 `ZlSearchTable` 或 `ZlCardPage` 替换的列表页，其「新增 / 导入 / 导出」等操作按钮统一放进对应组件的 `search-actions` 插槽（亦兼容 camelCase `searchActions`）。
5970
5970
  11. **其余 Element Plus 组件**：剩余 `el-` 开头的 Element Plus 组件，均按 §3 组件总览的命名对应关系替换为对应的 Zl 组件（如 `el-tree`→`ZlTree`、`el-upload`→`ZlUpload`、`el-tag`→`ZlTag`、`el-tabs`→`ZlTabs` 等）。
5971
5971
  12. **工具方法复用**：宿主项目里使用的工具类方法，需先与 `@zl-ui-kit/utils` 中的工具方法比对（完整清单见 §12.2，精确签名见 §12.3）；若存在**最终效果一致**的实现，统一使用 `@zl-ui-kit/utils` 的方法替换，避免重复实现与行为不一致。
5972
- 13. **先读透传契约**：动手替换前读完 [§15.5 迁移行为差异与透传契约](#155-迁移行为差异与透传契约必读)——未列在 props 表的属性与事件大多直接透传给内部 `el-*`，而少数默认值 / 入参语义与 EP 不等价，需逐条核对。
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 不等价，需逐条核对。
5973
5975
 
5974
5976
  ### 15.2 常用 el-* → Zl-* 对照表（持续补充）
5975
5977
 
5976
- | Element Plus 组件 | 替换为 | 说明 |
5977
- | ------------------------------------------------- | ------------------- | -------------------------------------------------- |
5978
- | `el-table`（普通 / 分页列表） | `ZlSearchTable` | 自带查询条、分页、loading |
5979
- | `el-table`（卡片分页列表） | `ZlCardPage` | 卡片式分页列表 |
5980
- | `el-table`（纯表格，无查询） | `ZlTable` | 普通表格展示 |
5981
- | `el-dialog` / `el-drawer` | `ZlDrawer` | 所有弹窗统一为抽屉 |
5982
- | `el-form` | `ZlForm` | 弹窗内新增 / 编辑 / 详情表单（schema 驱动） |
5983
- | `el-card` | `ZlCard` | 卡片容器 |
5984
- | `el-button`（操作栏 / 卡片内） | `ZlAction` | 操作列与卡片按钮；页面级独立按钮仍可用 `el-button` |
5985
- | `el-tooltip`（超长省略） | `ZlAutoTooltip` | 文字溢出时自动提示 |
5986
- | `el-icon` | `ZlIcon` | 需先注册图标集（§4.1） |
5987
- | `el-tree` | `ZlTree` | 勾选多选 / 字段映射 / 暴露方法见 §7 › ZlTree |
5988
- | `el-upload` | `ZlUpload` | |
5989
- | `el-tag` | `ZlTag` | |
5990
- | `el-tabs` | `ZlTabs` | 页签内容默认懒挂载，差异见 §15.5 |
5991
- | `el-radio`（标签式） | `ZlRadioTag` | 仅此形态封装 |
5992
- | `el-checkbox`（标签式） | `ZlCheckboxTag` | 仅此形态封装 |
5993
- | `el-checkbox`（全选 / 半选） | `ZlCheckAll` | 自带半选态，可替代表头全选勾选框 |
5994
- | `el-radio` / `el-checkbox`（普通单选框 / 复选框） | —（**有意不封装**） | 继续用 `el-*`，库内无对应物（见 §15.5） |
5995
- | `el-radio-group` / `el-checkbox-group` | —（**有意不封装**） | 继续用 `el-*`，组内选项自行渲染 |
5996
- | `el-switch` | `ZlSwitch` | |
5997
- | `el-popconfirm` | `ZlPopconfirm` | |
5998
- | `el-empty` | `ZlEmpty` | |
5999
- | `el-avatar` | `ZlAvatar` | |
6000
- | `el-descriptions` | `ZlDescription` | |
6001
- | `el-text` | `ZlText` | |
6002
- | `el-pagination` | `ZlPagination` | |
6003
- | `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`），二次确认 + 异步操作统一在这里 |
6004
6008
 
6005
6009
  > 未在上表中的 `el-*` 组件，请对照 §3 组件总览的命名与用途选择对应 Zl 组件；若暂无对应实现，暂保留 `el-*`，并在本规范登记为待补充项。
6006
6010
  > 替换前请先读 **[§15.5 迁移行为差异与透传契约](#155-迁移行为差异与透传契约必读)**：哪些属性默认直接透传、哪些行为与 EP 不等价。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zl-ui-kit/components",
3
- "version": "0.10.1",
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/composables": "0.10.1",
43
- "@zl-ui-kit/utils": "0.10.1",
44
- "@zl-ui-kit/icons": "0.10.1"
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/vite-config": "1.0.0",
101
102
  "@jichuang/tsconfig": "1.0.0",
102
- "@jichuang/eslint-config": "1.0.0",
103
- "@zl-ui-kit/theme": "0.10.1",
104
- "@jichuang/vite-config": "1.0.0"
103
+ "@zl-ui-kit/theme": "0.10.2",
104
+ "@jichuang/eslint-config": "1.0.0"
105
105
  },
106
106
  "repository": {
107
107
  "type": "git",