@zl-ui-kit/components 0.8.1 → 0.8.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 (87) hide show
  1. package/README.md +357 -359
  2. package/dist/components/ZlAction/List.vue.d.ts +5 -0
  3. package/dist/components/ZlAddSub/index.css +1 -1
  4. package/dist/components/ZlAddSub/index.vue.d.ts +1 -0
  5. package/dist/components/ZlAddSub/index.vue.mjs +2 -2
  6. package/dist/components/ZlAppLayout/index.vue.d.ts +2 -0
  7. package/dist/components/ZlAppLayout/index.vue.mjs +1 -0
  8. package/dist/components/ZlAppMenu/AppMenu.vue.d.ts +2 -0
  9. package/dist/components/ZlAppSlogan/index.vue.d.ts +3 -0
  10. package/dist/components/ZlAutoTooltip/index.css +1 -1
  11. package/dist/components/ZlAutoTooltip/index.vue.mjs +2 -2
  12. package/dist/components/ZlAvatar/Group.css +1 -1
  13. package/dist/components/ZlAvatar/Group.vue.d.ts +2 -0
  14. package/dist/components/ZlAvatar/Group.vue.mjs +2 -2
  15. package/dist/components/ZlAvatar/index.css +1 -1
  16. package/dist/components/ZlAvatar/index.vue.d.ts +2 -0
  17. package/dist/components/ZlAvatar/index.vue.mjs +2 -2
  18. package/dist/components/ZlCard/index.vue.d.ts +1 -0
  19. package/dist/components/ZlCardPage/index.vue.d.ts +5 -0
  20. package/dist/components/ZlCheckAll/index.css +1 -1
  21. package/dist/components/ZlCheckAll/index.vue.d.ts +2 -0
  22. package/dist/components/ZlCheckAll/index.vue.mjs +2 -2
  23. package/dist/components/ZlCheckboxTag/index.vue.d.ts +5 -0
  24. package/dist/components/ZlCopy/index.css +1 -1
  25. package/dist/components/ZlCopy/index.vue.d.ts +2 -0
  26. package/dist/components/ZlCopy/index.vue.mjs +2 -2
  27. package/dist/components/ZlDescription/index.vue.d.ts +4 -0
  28. package/dist/components/ZlDictTag/index.vue.d.ts +7 -1
  29. package/dist/components/ZlDrawer/index.vue.d.ts +5 -0
  30. package/dist/components/ZlDynamicComponent/index.vue.d.ts +6 -0
  31. package/dist/components/ZlDynamicComponent/index.vue.mjs +3 -0
  32. package/dist/components/ZlEditor/ZlSqlEditor.vue.d.ts +2 -0
  33. package/dist/components/ZlEditor/index.vue.d.ts +2 -0
  34. package/dist/components/ZlFilePreview/index.vue.d.ts +1 -0
  35. package/dist/components/ZlFileViewer/index.css +1 -1
  36. package/dist/components/ZlFileViewer/index.vue.d.ts +1 -0
  37. package/dist/components/ZlFileViewer/index.vue.mjs +2 -2
  38. package/dist/components/ZlForm/ZlFormChild.vue.d.ts +2 -0
  39. package/dist/components/ZlForm/ZlFormChild.vue.mjs +4 -1
  40. package/dist/components/ZlForm/index.vue.d.ts +2 -0
  41. package/dist/components/ZlGrid/ZlGridItem.vue.d.ts +1 -0
  42. package/dist/components/ZlGrid/index.vue.d.ts +8 -0
  43. package/dist/components/ZlHorizontalTable/index.css +1 -1
  44. package/dist/components/ZlHorizontalTable/index.vue.d.ts +4 -0
  45. package/dist/components/ZlHorizontalTable/index.vue.mjs +2 -2
  46. package/dist/components/ZlIcon/index.css +1 -1
  47. package/dist/components/ZlIcon/index.vue.mjs +2 -2
  48. package/dist/components/ZlLayoutSwitch/index.css +1 -1
  49. package/dist/components/ZlLayoutSwitch/index.vue.d.ts +1 -0
  50. package/dist/components/ZlLayoutSwitch/index.vue.mjs +2 -2
  51. package/dist/components/ZlLogin/components/LoginForm.css +1 -1
  52. package/dist/components/ZlLogin/components/LoginForm.vue.d.ts +1 -0
  53. package/dist/components/ZlLogin/components/LoginForm.vue.mjs +1 -1
  54. package/dist/components/ZlLogin/index.vue.d.ts +2 -0
  55. package/dist/components/ZlPdfViewer/index.vue.d.ts +2 -0
  56. package/dist/components/ZlPopconfirm/index.vue.d.ts +4 -0
  57. package/dist/components/ZlRadioTag/index.vue.d.ts +2 -0
  58. package/dist/components/ZlSearch/index.vue.d.ts +5 -1
  59. package/dist/components/ZlSearchTable/index.vue.d.ts +4 -0
  60. package/dist/components/ZlSection/index.vue.d.ts +1 -0
  61. package/dist/components/ZlSorter/ZlSorterList.css +1 -1
  62. package/dist/components/ZlSorter/ZlSorterList.vue.d.ts +2 -0
  63. package/dist/components/ZlSorter/ZlSorterList.vue.mjs +2 -2
  64. package/dist/components/ZlSorter/index.css +1 -1
  65. package/dist/components/ZlSorter/index.vue.d.ts +1 -0
  66. package/dist/components/ZlSorter/index.vue.mjs +1 -1
  67. package/dist/components/ZlSwitch/index.vue.d.ts +6 -0
  68. package/dist/components/ZlTable/index.vue.d.ts +6 -0
  69. package/dist/components/ZlTabs/index.vue.d.ts +8 -0
  70. package/dist/components/ZlTabs/index.vue.mjs +6 -0
  71. package/dist/components/ZlTag/ZlCornerTag.vue.d.ts +3 -0
  72. package/dist/components/ZlTag/index.vue.d.ts +30 -0
  73. package/dist/components/ZlTag/index.vue.mjs +15 -0
  74. package/dist/components/ZlText/index.css +1 -1
  75. package/dist/components/ZlText/index.vue.d.ts +1 -0
  76. package/dist/components/ZlText/index.vue.mjs +2 -2
  77. package/dist/components/ZlTitle/index.css +1 -1
  78. package/dist/components/ZlTitle/index.vue.d.ts +5 -0
  79. package/dist/components/ZlTitle/index.vue.mjs +2 -2
  80. package/dist/components/ZlTree/index.vue.d.ts +1 -0
  81. package/dist/components/ZlTreeSelect/index.css +1 -1
  82. package/dist/components/ZlTreeSelect/index.vue.d.ts +1 -0
  83. package/dist/components/ZlTreeSelect/index.vue.mjs +3 -3
  84. package/dist/components/ZlUpload/index.css +1 -1
  85. package/dist/components/ZlUpload/index.vue.d.ts +5 -2
  86. package/dist/components/ZlUpload/index.vue.mjs +2 -2
  87. package/package.json +6 -6
package/README.md CHANGED
@@ -1659,8 +1659,6 @@ const { i18n } = useLocale({ messages })
1659
1659
  | [`ZlFilePreview`](#zlfilepreview) | 子入口 file-preview | 1 | 0 | 0 | 0 |
1660
1660
  | [`ZlFileViewer`](#zlfileviewer) | 子入口 file-preview | 1 | 0 | 0 | 0 |
1661
1661
 
1662
- > 说明列为 `—` 表示该属性在源码里没写 `/** */` 注释（当前 134/194 个）；补完注释重跑 `pnpm docs:api` 即可同步。
1663
-
1664
1662
  ### 14.1 主入口组件（`@zl-ui-kit/components`）
1665
1663
 
1666
1664
  #### `ZlAction`
@@ -1719,14 +1717,14 @@ import { ZlActionList } from '@zl-ui-kit/components'
1719
1717
 
1720
1718
  **props**
1721
1719
 
1722
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1723
- | ------------- | -------------------------------- | ---------- | ---- | ----------------------- | ------------------------------------ |
1724
- | `actions` | `ActionItem[]` | `() => []` | 否 | `:actions="actions"` | — |
1725
- | `actionArgs` | `any[]` | `() => []` | 否 | `:action-args="[]"` | — |
1726
- | `visibleArgs` | `any[]` | `() => []` | 否 | `:visible-args="[]"` | — |
1727
- | `listCount` | `number` | `2` | 否 | `:list-count="1"` | 直接展示的操作数，超出收入"更多"下拉 |
1728
- | `iconMore` | `boolean \| Record<string, any>` | — | 否 | `:icon-more="iconMore"` | — |
1729
- | `separator` | `boolean` | — | 否 | `separator` | — |
1720
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1721
+ | ------------- | -------------------------------- | ---------- | ---- | ----------------------- | ------------------------------------------------ |
1722
+ | `actions` | `ActionItem[]` | `() => []` | 否 | `:actions="actions"` | 操作项配置，按顺序渲染为文字或图标按钮 |
1723
+ | `actionArgs` | `any[]` | `() => []` | 否 | `:action-args="[]"` | 点击时透传给 `action` 事件与 handler 的参数 |
1724
+ | `visibleArgs` | `any[]` | `() => []` | 否 | `:visible-args="[]"` | 传给每项 `visible` 判定函数的参数 |
1725
+ | `listCount` | `number` | `2` | 否 | `:list-count="1"` | 直接展示的操作数，超出收入"更多"下拉 |
1726
+ | `iconMore` | `boolean \| Record<string, any>` | — | 否 | `:icon-more="iconMore"` | 为 true 时把"更多"换成图标，对象则作为图标 props |
1727
+ | `separator` | `boolean` | — | 否 | `separator` | 各操作之间是否插入竖线分隔符 |
1730
1728
 
1731
1729
  **事件（emits）**
1732
1730
 
@@ -1736,9 +1734,9 @@ import { ZlActionList } from '@zl-ui-kit/components'
1736
1734
 
1737
1735
  **插槽（slots）**
1738
1736
 
1739
- | 插槽 | 作用域参数 | 示例 | 说明 |
1740
- | ------ | ---------- | ------------------------------ | ---- |
1741
- | `more` | — | `<template #more>…</template>` | — |
1737
+ | 插槽 | 作用域参数 | 示例 | 说明 |
1738
+ | ------ | ---------- | ------------------------------ | ---------------------------------------------- |
1739
+ | `more` | — | `<template #more>…</template>` | "更多"下拉的触发区域，默认显示图标或"更多"文案 |
1742
1740
 
1743
1741
  **完整示例**：见 §7 表单与交互组件 › ZlAction / ZlActionList —— 操作列与操作列表
1744
1742
 
@@ -1774,10 +1772,10 @@ import { ZlAddSub } from '@zl-ui-kit/components'
1774
1772
 
1775
1773
  **props**
1776
1774
 
1777
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1778
- | ------------ | ----------------- | ---------- | ---- | --------------------------- | -------------- |
1779
- | `model` | `any[]` | `() => []` | 否 | `v-model:model="value"` | — |
1780
- | `defaultVal` | `any[] \| string` | `() => []` | 否 | `:default-val="defaultVal"` | 新增项的默认值 |
1775
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1776
+ | ------------ | ----------------- | ---------- | ---- | --------------------------- | ---------------------------------------------- |
1777
+ | `model` | `any[]` | `() => []` | 否 | `v-model:model="value"` | 列表数据（`v-model:model` 绑定），决定渲染几行 |
1778
+ | `defaultVal` | `any[] \| string` | `() => []` | 否 | `:default-val="defaultVal"` | 新增项的默认值 |
1781
1779
 
1782
1780
  **事件（emits）**
1783
1781
 
@@ -1787,9 +1785,9 @@ import { ZlAddSub } from '@zl-ui-kit/components'
1787
1785
 
1788
1786
  **插槽（slots）**
1789
1787
 
1790
- | 插槽 | 作用域参数 | 示例 | 说明 |
1791
- | ----- | ---------- | ----------------------------------------- | ---- |
1792
- | `add` | `index` | `<template #add="{ index }">…</template>` | — |
1788
+ | 插槽 | 作用域参数 | 示例 | 说明 |
1789
+ | ----- | ---------- | ----------------------------------------- | --------------------------------------------- |
1790
+ | `add` | `index` | `<template #add="{ index }">…</template>` | 每一行的自定义内容，作用域参数 index 为行下标 |
1793
1791
 
1794
1792
  **完整示例**：见 §7 表单与交互组件 › ZlRadioTag / ZlCheckboxTag / ZlCheckAll / ZlSorter / ZlAddSub / ZlLayoutSwitch
1795
1793
 
@@ -1825,9 +1823,9 @@ import { ZlAppLayout } from '@zl-ui-kit/components'
1825
1823
 
1826
1824
  **props**
1827
1825
 
1828
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1829
- | -------- | ---------------------------- | -------------- | ---- | --------------------- | ---- |
1830
- | `layout` | `'horizontal' \| 'vertical'` | `'horizontal'` | 否 | `layout="horizontal"` | — |
1826
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1827
+ | -------- | ---------------------------- | -------------- | ---- | --------------------- | ---------------------------------------- |
1828
+ | `layout` | `'horizontal' \| 'vertical'` | `'horizontal'` | 否 | `layout="horizontal"` | 布局方向：横向用顶部菜单，纵向用侧边菜单 |
1831
1829
 
1832
1830
  > 选项式组件（`defineComponent`），props 定义在 `props: {}` 中
1833
1831
  > 把 `$attrs` 透传给内部组件，未列出的属性会继续下传
@@ -1866,9 +1864,9 @@ import { ZlAppMenu } from '@zl-ui-kit/components'
1866
1864
 
1867
1865
  | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1868
1866
  | ----------- | ---------------------------- | ------------ | ---- | ------------------- | ----------------------------------- |
1869
- | `collapsed` | `boolean` | `false` | 否 | `collapsed` | — |
1867
+ | `collapsed` | `boolean` | `false` | 否 | `collapsed` | 菜单是否收起为图标，侧栏折叠时用 |
1870
1868
  | `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | 否 | `layout="vertical"` | el-menu 模式：vertical / horizontal |
1871
- | `menus` | `MenuItem[]` | `() => []` | 否 | `:menus="menus"` | — |
1869
+ | `menus` | `MenuItem[]` | `() => []` | 否 | `:menus="menus"` | 菜单树数据，递归渲染为多级菜单项 |
1872
1870
 
1873
1871
  **事件（emits）**
1874
1872
 
@@ -1900,11 +1898,11 @@ import { ZlAppSlogan } from '@zl-ui-kit/components'
1900
1898
 
1901
1899
  **props**
1902
1900
 
1903
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1904
- | ----------- | --------- | ------ | ---- | ------------------------------------- | ---- |
1905
- | `collapsed` | `boolean` | — | 否 | `collapsed` | — |
1906
- | `logo` | `string` | — | 否 | `logo="https://example.com/logo.png"` | — |
1907
- | `title` | `string` | — | 否 | `title="标题"` | — |
1901
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1902
+ | ----------- | --------- | ------ | ---- | ------------------------------------- | ------------------------------- |
1903
+ | `collapsed` | `boolean` | — | 否 | `collapsed` | 为 true 时只显示 Logo，隐藏标题 |
1904
+ | `logo` | `string` | — | 否 | `logo="https://example.com/logo.png"` | 品牌 Logo 的图片地址 |
1905
+ | `title` | `string` | — | 否 | `title="标题"` | 应用标题文案，折叠时隐藏 |
1908
1906
 
1909
1907
  #### `ZlAutoTooltip`
1910
1908
 
@@ -1938,9 +1936,9 @@ import { ZlAutoTooltip } from '@zl-ui-kit/components'
1938
1936
 
1939
1937
  **插槽（slots）**
1940
1938
 
1941
- | 插槽 | 作用域参数 | 示例 | 说明 |
1942
- | --------- | ---------- | --------------------------------- | ---- |
1943
- | `default` | — | `<template #default>…</template>` | — |
1939
+ | 插槽 | 作用域参数 | 示例 | 说明 |
1940
+ | --------- | ---------- | --------------------------------- | -------------------------------- |
1941
+ | `default` | — | `<template #default>…</template>` | 需要省略并在溢出时提示的文本内容 |
1944
1942
 
1945
1943
  #### `ZlAvatar`
1946
1944
 
@@ -1962,11 +1960,11 @@ import { ZlAvatar } from '@zl-ui-kit/components'
1962
1960
 
1963
1961
  **props**
1964
1962
 
1965
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1966
- | ---------- | -------- | -------- | ---- | -------------------------------------------- | ---------------- |
1967
- | `imageUrl` | `string` | — | 否 | `image-url="https://example.com/avatar.png"` | — |
1968
- | `label` | `string` | — | 否 | `label="标签"` | — |
1969
- | `size` | `string` | `'20px'` | 否 | `size="24px"` | 尺寸（CSS 长度） |
1963
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1964
+ | ---------- | -------- | -------- | ---- | -------------------------------------------- | ------------------------------------------ |
1965
+ | `imageUrl` | `string` | — | 否 | `image-url="https://example.com/avatar.png"` | 头像图片地址，加载成功后显示图片 |
1966
+ | `label` | `string` | — | 否 | `label="标签"` | 图片未加载时显示的首字，同时作为悬浮 title |
1967
+ | `size` | `string` | `'20px'` | 否 | `size="24px"` | 尺寸（CSS 长度） |
1970
1968
 
1971
1969
  #### `ZlAvatarGroup`
1972
1970
 
@@ -1990,11 +1988,11 @@ import { ZlAvatarGroup } from '@zl-ui-kit/components'
1990
1988
 
1991
1989
  **props**
1992
1990
 
1993
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1994
- | ------- | --------------------------------------- | -------------------------------------------------- | ---- | -------------- | ----------------------------------- |
1995
- | `list` | `Array<Record<string, any>>` | — | 是 | `:list="list"` | — |
1996
- | `props` | `{ imageUrl?: string; label?: string }` | `() => ({ imageUrl: 'imageUrl', label: 'label' })` | 否 | `:props="{}"` | 字段映射（imageUrl/label 的取值键） |
1997
- | `size` | `string` | — | 否 | `size="24px"` | — |
1991
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
1992
+ | ------- | --------------------------------------- | -------------------------------------------------- | ---- | -------------- | ------------------------------------ |
1993
+ | `list` | `Array<Record<string, any>>` | — | 是 | `:list="list"` | 头像数据列表，首项单独展示，其余层叠 |
1994
+ | `props` | `{ imageUrl?: string; label?: string }` | `() => ({ imageUrl: 'imageUrl', label: 'label' })` | 否 | `:props="{}"` | 字段映射（imageUrl/label 的取值键） |
1995
+ | `size` | `string` | — | 否 | `size="24px"` | 每个头像的尺寸（CSS 长度） |
1998
1996
 
1999
1997
  #### `ZlCard`
2000
1998
 
@@ -2038,22 +2036,22 @@ import { ZlCard } from '@zl-ui-kit/components'
2038
2036
 
2039
2037
  **props**
2040
2038
 
2041
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2042
- | ----------- | --------- | ------ | ---- | -------------------- | ---- |
2043
- | `hoverable` | `boolean` | `true` | 否 | `:hoverable="false"` | — |
2039
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2040
+ | ----------- | --------- | ------ | ---- | -------------------- | -------------------------------- |
2041
+ | `hoverable` | `boolean` | `true` | 否 | `:hoverable="false"` | 鼠标悬停时是否高亮边框并加深阴影 |
2044
2042
 
2045
2043
  **插槽（slots）**
2046
2044
 
2047
- | 插槽 | 作用域参数 | 示例 | 说明 |
2048
- | ---------------- | ---------- | ---------------------------------------- | ---- |
2049
- | `icon` | — | `<template #icon>…</template>` | — |
2050
- | `title` | — | `<template #title>…</template>` | — |
2051
- | `title-append` | — | `<template #title-append>…</template>` | — |
2052
- | `subtitle` | — | `<template #subtitle>…</template>` | — |
2053
- | `default` | — | `<template #default>…</template>` | — |
2054
- | `footer-prepend` | — | `<template #footer-prepend>…</template>` | — |
2055
- | `footer` | — | `<template #footer>…</template>` | — |
2056
- | `extra` | — | `<template #extra>…</template>` | — |
2045
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2046
+ | ---------------- | ---------- | ---------------------------------------- | ---------------------------------- |
2047
+ | `icon` | — | `<template #icon>…</template>` | 卡片头部左侧的图标区 |
2048
+ | `title` | — | `<template #title>…</template>` | 卡片标题文案 |
2049
+ | `title-append` | — | `<template #title-append>…</template>` | 标题右侧的附加内容 |
2050
+ | `subtitle` | — | `<template #subtitle>…</template>` | 标题下方的副标题 |
2051
+ | `default` | — | `<template #default>…</template>` | 卡片主体内容，有内容才渲染该区域 |
2052
+ | `footer-prepend` | — | `<template #footer-prepend>…</template>` | 卡片底部左侧内容 |
2053
+ | `footer` | — | `<template #footer>…</template>` | 卡片底部右侧内容 |
2054
+ | `extra` | — | `<template #extra>…</template>` | 卡片主体之外的自由区域，如展开面板 |
2057
2055
 
2058
2056
  **完整示例**：见 §5 通用展示组件 › ZlCard / ZlPagination — 卡片与分页的视觉约定
2059
2057
 
@@ -2095,12 +2093,12 @@ import { ZlCardPage } from '@zl-ui-kit/components'
2095
2093
 
2096
2094
  | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2097
2095
  | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ---- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2098
- | `immediate` | `boolean` | `true` | 否 | `:immediate="false"` | — |
2096
+ | `immediate` | `boolean` | `true` | 否 | `:immediate="false"` | 无查询条件时是否立即发起首次请求 |
2099
2097
  | `request` | `\| ((...args: any[]) => Promise<any>) \| { service: (...args: any[]) => Promise<any>; options?: Record<string, any> } \| UseRequestInstance` | — | 是 | `:request="async () => {}"` | 请求来源，三种形态任一： 1. 请求函数 `(...args) => Promise` 2. `{ service, options }` 对象（ZlCardPage 内部再包一层 usePageableRequest） 3. `useRequest` / `usePageableRequest` 实例（消费方自行创建，便于接管 loading/refresh） |
2100
- | `queryItems` | `SearchItem[]` | `() => []` | 否 | `:query-items="queryItems"` | — |
2101
- | `pagination` | `Record<string, any> \| boolean` | `true` | 否 | `:pagination="{}"` | — |
2102
- | `itemKey` | `string` | `'id'` | 否 | `item-key="id"` | — |
2103
- | `cardMinWidth` | `string` | — | 否 | `card-min-width="280px"` | — |
2098
+ | `queryItems` | `SearchItem[]` | `() => []` | 否 | `:query-items="queryItems"` | 搜索表单项配置，为空则不渲染搜索栏 |
2099
+ | `pagination` | `Record<string, any> \| boolean` | `true` | 否 | `:pagination="{}"` | 分页配置，false 关闭分页，对象则透传 |
2100
+ | `itemKey` | `string` | `'id'` | 否 | `item-key="id"` | 卡片数据的唯一键字段名，默认 id |
2101
+ | `cardMinWidth` | `string` | — | 否 | `card-min-width="280px"` | 卡片最小宽度，决定单行能放几列 |
2104
2102
 
2105
2103
  **事件（emits）**
2106
2104
 
@@ -2110,11 +2108,11 @@ import { ZlCardPage } from '@zl-ui-kit/components'
2110
2108
 
2111
2109
  **插槽（slots）**
2112
2110
 
2113
- | 插槽 | 作用域参数 | 示例 | 说明 |
2114
- | ------------------ | ------------------------------ | -------------------------------------------------- | ---------------------------- |
2115
- | `search-actions` | — | `<template #search-actions>…</template>` | — |
2116
- | `[search-${slot}]` | `v-bind="scope"` 展开 | `<template #[search-${slot}]="scope">…</template>` | 动态插槽：名字由该表达式决定 |
2117
- | `default` | `v-bind="{ data: item }"` 展开 | `<template #default="{ data }">…</template>` | — |
2111
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2112
+ | ------------------ | ------------------------------ | -------------------------------------------------- | ------------------------------------------ |
2113
+ | `search-actions` | — | `<template #search-actions>…</template>` | 搜索栏右侧的操作按钮区 |
2114
+ | `[search-${slot}]` | `v-bind="scope"` 展开 | `<template #[search-${slot}]="scope">…</template>` | 自定义搜索项，插槽名 search- 加字段名 |
2115
+ | `default` | `v-bind="{ data: item }"` 展开 | `<template #default="{ data }">…</template>` | 单个卡片内容，作用域参数 data 为当前项数据 |
2118
2116
 
2119
2117
  **暴露（defineExpose）**
2120
2118
 
@@ -2150,10 +2148,10 @@ import { ZlCheckAll } from '@zl-ui-kit/components'
2150
2148
 
2151
2149
  **props**
2152
2150
 
2153
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2154
- | --------- | ------------------------- | ---------- | ---- | ----------------------- | ---- |
2155
- | `options` | `CheckAllOption[]` | `() => []` | 否 | `:options="options"` | — |
2156
- | `model` | `Array<string \| number>` | `() => []` | 否 | `v-model:model="value"` | — |
2151
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2152
+ | --------- | ------------------------- | ---------- | ---- | ----------------------- | ---------------------------------------- |
2153
+ | `options` | `CheckAllOption[]` | `() => []` | 否 | `:options="options"` | 全选管理的可选项，每项渲染成一个复选框 |
2154
+ | `model` | `Array<string \| number>` | `() => []` | 否 | `v-model:model="value"` | 已勾选的 value 集合，用 v-model 双向绑定 |
2157
2155
 
2158
2156
  **事件（emits）**
2159
2157
 
@@ -2196,12 +2194,12 @@ import { ZlCheckboxTag } from '@zl-ui-kit/components'
2196
2194
  | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2197
2195
  | ------------ | ------------------------------- | ---------- | ---- | -------------------- | -------------------------------------------- |
2198
2196
  | `modelValue` | `any` | — | 否 | `v-model="value"` | `v-model` 绑定的值（`defineModel` 隐式声明） |
2199
- | `options` | `CheckboxTagOption[]` | `() => []` | 否 | `:options="options"` | — |
2197
+ | `options` | `CheckboxTagOption[]` | `() => []` | 否 | `:options="options"` | 标签候选列表，每项可配图标与互斥组 |
2200
2198
  | `single` | `boolean` | — | 否 | `single` | 单选模式（值为单值） |
2201
- | `rounded` | `boolean` | `true` | 否 | `:rounded="false"` | — |
2202
- | `bordered` | `boolean` | `true` | 否 | `:bordered="false"` | — |
2203
- | `fill` | `boolean` | `true` | 否 | `:fill="false"` | — |
2204
- | `size` | `'mini' \| 'small' \| 'medium'` | `'small'` | 否 | `size="mini"` | — |
2199
+ | `rounded` | `boolean` | `true` | 否 | `:rounded="false"` | 是否圆角显示，默认开启 |
2200
+ | `bordered` | `boolean` | `true` | 否 | `:bordered="false"` | 选中时是否显示边框，默认开启 |
2201
+ | `fill` | `boolean` | `true` | 否 | `:fill="false"` | 是否填充背景色，默认开启 |
2202
+ | `size` | `'mini' \| 'small' \| 'medium'` | `'small'` | 否 | `size="mini"` | 标签尺寸档位，默认 small |
2205
2203
 
2206
2204
  **事件（emits）**
2207
2205
 
@@ -2211,9 +2209,9 @@ import { ZlCheckboxTag } from '@zl-ui-kit/components'
2211
2209
 
2212
2210
  **插槽（slots）**
2213
2211
 
2214
- | 插槽 | 作用域参数 | 示例 | 说明 |
2215
- | --------- | ------------------------------------------------------------- | ----------------------------------------------------- | ---- |
2216
- | `default` | `v-bind="{ item, checked: checkedSet.has(item.value) }"` 展开 | `<template #default="{ item, checked }">…</template>` | — |
2212
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2213
+ | --------- | ------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------- |
2214
+ | `default` | `v-bind="{ item, checked: checkedSet.has(item.value) }"` 展开 | `<template #default="{ item, checked }">…</template>` | 单个标签的展示内容，默认取该选项的 label |
2217
2215
 
2218
2216
  **完整示例**：见 §7 表单与交互组件 › ZlRadioTag / ZlCheckboxTag / ZlCheckAll / ZlSorter / ZlAddSub / ZlLayoutSwitch
2219
2217
 
@@ -2250,17 +2248,17 @@ import { ZlCopy } from '@zl-ui-kit/components'
2250
2248
 
2251
2249
  **props**
2252
2250
 
2253
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2254
- | ---------- | -------- | ------ | ---- | ---------------------- | ---- |
2255
- | `text` | `string` | — | 否 | `text="文本"` | — |
2256
- | `copyText` | `string` | — | 否 | `copy-text="复制内容"` | — |
2251
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2252
+ | ---------- | -------- | ------ | ---- | ---------------------- | -------------------------------------------- |
2253
+ | `text` | `string` | — | 否 | `text="文本"` | 展示的文本，未传 copyText 时点击复制的就是它 |
2254
+ | `copyText` | `string` | — | 否 | `copy-text="复制内容"` | 实际写入剪贴板的内容，优先级高于 text |
2257
2255
 
2258
2256
  **插槽（slots）**
2259
2257
 
2260
- | 插槽 | 作用域参数 | 示例 | 说明 |
2261
- | --------- | ---------- | -------------------------------------------- | ---- |
2262
- | `default` | — | `<template #default>…</template>` | — |
2263
- | `trigger` | `copy` | `<template #trigger="{ copy }">…</template>` | — |
2258
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2259
+ | --------- | ---------- | -------------------------------------------- | -------------------------------------- |
2260
+ | `default` | — | `<template #default>…</template>` | 复制内容展示区，缺省渲染 text |
2261
+ | `trigger` | `copy` | `<template #trigger="{ copy }">…</template>` | 自定义复制触发器，作用域提供 copy 方法 |
2264
2262
 
2265
2263
  **完整示例**：见 §5 通用展示组件 › ZlCopy — 一键复制
2266
2264
 
@@ -2298,17 +2296,17 @@ import { ZlDescription } from '@zl-ui-kit/components'
2298
2296
 
2299
2297
  | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2300
2298
  | -------------- | ----------------------------------------------------------------- | -------------------------------------- | ---- | --------------------------- | -------------------------------------------------------------------- |
2301
- | `items` | `DescriptionItem[]` | — | 是 | `:items="items"` | — |
2302
- | `data` | `Record<string, any>` | `() => ({})` | 否 | `:data="{}"` | — |
2303
- | `emptyChecker` | `(value: any, key: string, data: Record<string, any>) => boolean` | `(val: any) => !val && !isNumber(val)` | 否 | `:empty-checker="() => {}"` | — |
2299
+ | `items` | `DescriptionItem[]` | — | 是 | `:items="items"` | 展示项列表，决定字段顺序、取值与显隐 |
2300
+ | `data` | `Record<string, any>` | `() => ({})` | 否 | `:data="{}"` | 取值来源对象，缺省按各项 key 取字段 |
2301
+ | `emptyChecker` | `(value: any, key: string, data: Record<string, any>) => boolean` | `(val: any) => !val && !isNumber(val)` | 否 | `:empty-checker="() => {}"` | 判断值是否为空，为空时改显示占位文案 |
2304
2302
  | `emptyText` | `string` | — | 否 | `empty-text="暂无数据"` | 空值占位文案（缺省走 i18n zl.description.empty，未接入时兜底"暂无"） |
2305
- | `secondary` | `boolean` | — | 否 | `secondary` | — |
2303
+ | `secondary` | `boolean` | — | 否 | `secondary` | 次要形态：灰底并显示字段间分隔线 |
2306
2304
 
2307
2305
  **插槽（slots）**
2308
2306
 
2309
- | 插槽 | 作用域参数 | 示例 | 说明 |
2310
- | ------------ | ---------- | ------------------------------------ | ---------------------------- |
2311
- | `[item.key]` | — | `<template #[item.key]>…</template>` | 动态插槽：名字由该表达式决定 |
2307
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2308
+ | ------------ | ---------- | ------------------------------------ | -------------------------------------------- |
2309
+ | `[item.key]` | — | `<template #[item.key]>…</template>` | 按 item.key 命名，仅在该项开启 slot 时才渲染 |
2312
2310
 
2313
2311
  #### `ZlDictTag`
2314
2312
 
@@ -2338,11 +2336,11 @@ import { ZlDictTag } from '@zl-ui-kit/components'
2338
2336
  | ------------- | ------------------------------------------------------------------------- | ----------- | ---- | ------------------- | ------------------------------------------------------------------------------------------------- |
2339
2337
  | `dictKey` | `string` | — | 是 | `dict-key="gender"` | 字典键（对应全局字典缓存的键；外部直传数据也以该键写入共享缓存） |
2340
2338
  | `dict` | `DictItem[]` | — | 否 | `:dict="dict"` | 外部直传字典数据：无需依赖全局数据源即可翻译。格式同 DictItem[]（{ label, value, icon?, type? }） |
2341
- | `corner` | `boolean \| 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `false` | 否 | `corner="top-left"` | — |
2342
- | `value` | `string` | — | 否 | `value="1"` | — |
2343
- | `simple` | `boolean` | — | 否 | `simple` | — |
2339
+ | `corner` | `boolean \| 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `false` | 否 | `corner="top-left"` | 是否渲染成角标并指定方位，true 时为右上角 |
2340
+ | `value` | `string` | — | 否 | `value="1"` | 待翻译的字典值，匹配不到时原样展示 |
2341
+ | `simple` | `boolean` | — | 否 | `simple` | 忽略字典项自带的颜色，改用标签默认配色 |
2344
2342
  | `iconVisible` | `boolean` | `undefined` | 否 | `icon-visible` | 是否展示字典项图标（默认 true） |
2345
- | `hideIcon` | `boolean` | `undefined` | 否 | `hide-icon` | — |
2343
+ | `hideIcon` | `boolean` | `undefined` | 否 | `hide-icon` | 已废弃，请用 `iconVisible` 控制图标显隐 |
2346
2344
 
2347
2345
  > 把 `$attrs` 透传给 `zl-corner-tag`，未列出的属性会继续下传
2348
2346
 
@@ -2382,11 +2380,11 @@ import { ZlDrawer } from '@zl-ui-kit/components'
2382
2380
  | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2383
2381
  | ----------------------- | --------------------------------------------------- | ------- | ---- | ----------------------------------- | -------------------------------------------- |
2384
2382
  | `visible` | `boolean` | `false` | 否 | `v-model:visible="value"` | `v-model` 绑定的值（`defineModel` 隐式声明） |
2385
- | `onCancel` | `() => boolean \| void \| Promise<boolean \| void>` | — | 否 | `:on-cancel="async () => {}"` | — |
2386
- | `onOk` | `() => void \| Promise<void>` | — | 否 | `:on-ok="async () => {}"` | — |
2387
- | `autoCloseAfterConfirm` | `boolean` | `true` | 否 | `:auto-close-after-confirm="false"` | — |
2388
- | `readonly` | `boolean` | — | 否 | `readonly` | — |
2389
- | `loading` | `boolean` | — | 否 | `loading` | — |
2383
+ | `onCancel` | `() => boolean \| void \| Promise<boolean \| void>` | — | 否 | `:on-cancel="async () => {}"` | 关闭前触发，返回 true 才会真正关闭 |
2384
+ | `onOk` | `() => void \| Promise<void>` | — | 否 | `:on-ok="async () => {}"` | 点击确定的回调，异步期间按钮保持 loading |
2385
+ | `autoCloseAfterConfirm` | `boolean` | `true` | 否 | `:auto-close-after-confirm="false"` | 确定回调结束后是否自动关闭抽屉，默认 true |
2386
+ | `readonly` | `boolean` | — | 否 | `readonly` | 只读模式：隐藏取消按钮，只留「关闭」 |
2387
+ | `loading` | `boolean` | — | 否 | `loading` | 内容区加载态，为 true 时显示遮罩 loading |
2390
2388
 
2391
2389
  **事件（emits）**
2392
2390
 
@@ -2396,10 +2394,10 @@ import { ZlDrawer } from '@zl-ui-kit/components'
2396
2394
 
2397
2395
  **插槽（slots）**
2398
2396
 
2399
- | 插槽 | 作用域参数 | 示例 | 说明 |
2400
- | --------- | ---------- | --------------------------------- | ---- |
2401
- | `default` | — | `<template #default>…</template>` | — |
2402
- | `footer` | — | `<template #footer>…</template>` | — |
2397
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2398
+ | --------- | ---------- | --------------------------------- | ----------------------------------- |
2399
+ | `default` | — | `<template #default>…</template>` | 抽屉正文内容，位于底部按钮区之上 |
2400
+ | `footer` | — | `<template #footer>…</template>` | 自定义底部按钮区，缺省渲染取消/确定 |
2403
2401
 
2404
2402
  **完整示例**：见 §7 表单与交互组件 › ZlDrawer / ZlPopconfirm / ZlSwitch
2405
2403
 
@@ -2425,11 +2423,11 @@ import { ZlDynamicComponent } from '@zl-ui-kit/components'
2425
2423
 
2426
2424
  **props**
2427
2425
 
2428
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2429
- | ----------- | ---------------------------------- | ----------------------------------- | ---- | ----------------- | ---- |
2430
- | `model` | `Record<string, any>` | `() => ({})` | 否 | `:model="{}"` | — |
2431
- | `value` | `[String, Number, Array, Boolean]` | `null` | 否 | `:value="value"` | — |
2432
- | `component` | `Record<string, any>` | `() => ({ component: 'el-input' })` | 否 | `:component="{}"` | — |
2426
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2427
+ | ----------- | ---------------------------------- | ----------------------------------- | ---- | ----------------- | ------------------------------------------- |
2428
+ | `model` | `Record<string, any>` | `() => ({})` | 否 | `:model="{}"` | 共享的数据对象，子组件按 model 字段读写值 |
2429
+ | `value` | `[String, Number, Array, Boolean]` | `null` | 否 | `:value="value"` | type 为 vModel 时透传给子组件的值 |
2430
+ | `component` | `Record<string, any>` | `() => ({ component: 'el-input' })` | 否 | `:component="{}"` | 待渲染组件的 schema 描述，缺省渲染 el-input |
2433
2431
 
2434
2432
  > 选项式组件（`defineComponent`），props 定义在 `props: {}` 中
2435
2433
 
@@ -2464,10 +2462,10 @@ import { ZlPdfViewer } from '@zl-ui-kit/components'
2464
2462
 
2465
2463
  **props**
2466
2464
 
2467
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2468
- | ------- | ------------------ | ------ | ---- | ------------------------------------ | ---- |
2469
- | `url` | `string` | — | 否 | `url="https://example.com/file.pdf"` | — |
2470
- | `width` | `number \| string` | — | 否 | `:width="width"` | — |
2465
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2466
+ | ------- | ------------------ | ------ | ---- | ------------------------------------ | -------------------------------------- |
2467
+ | `url` | `string` | — | 否 | `url="https://example.com/file.pdf"` | PDF 文件地址，渲染时自动隐藏内置工具栏 |
2468
+ | `width` | `number \| string` | — | 否 | `:width="width"` | 预览区宽度，直接透传给 object 元素 |
2471
2469
 
2472
2470
  #### `ZlLogin`
2473
2471
 
@@ -2502,17 +2500,17 @@ import { ZlLogin } from '@zl-ui-kit/components'
2502
2500
 
2503
2501
  **props**
2504
2502
 
2505
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2506
- | ---------- | ------------------------------------------------------ | ------------ | ---- | ----------------------------- | ---- |
2507
- | `onSubmit` | `(form: Record<string, any>) => Promise<void> \| void` | — | 否 | `:on-submit="async () => {}"` | — |
2508
- | `config` | `ZlLoginConfig` | `() => ({})` | 否 | `:config="config"` | — |
2503
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2504
+ | ---------- | ------------------------------------------------------ | ------------ | ---- | ----------------------------- | -------------------------------------- |
2505
+ | `onSubmit` | `(form: Record<string, any>) => Promise<void> \| void` | — | 否 | `:on-submit="async () => {}"` | 表单提交回调，接收用户填写的登录信息 |
2506
+ | `config` | `ZlLoginConfig` | `() => ({})` | 否 | `:config="config"` | 标题、背景（图片或视频）与整体布局形态 |
2509
2507
 
2510
2508
  **插槽（slots）**
2511
2509
 
2512
- | 插槽 | 作用域参数 | 示例 | 说明 |
2513
- | --------- | ---------- | --------------------------------- | ---- |
2514
- | `slogan` | — | `<template #slogan>…</template>` | — |
2515
- | `default` | — | `<template #default>…</template>` | — |
2510
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2511
+ | --------- | ---------- | --------------------------------- | ---------------------------------- |
2512
+ | `slogan` | — | `<template #slogan>…</template>` | 左上角的标语/品牌区 |
2513
+ | `default` | — | `<template #default>…</template>` | 登录主体内容，缺省渲染内置登录表单 |
2516
2514
 
2517
2515
  #### `ZlLoginForm`
2518
2516
 
@@ -2548,15 +2546,15 @@ import { ZlLoginForm } from '@zl-ui-kit/components'
2548
2546
 
2549
2547
  **props**
2550
2548
 
2551
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2552
- | ---------- | ------------------------------------------------------ | ------ | ---- | ----------------------------- | ---- |
2553
- | `onSubmit` | `(form: Record<string, any>) => Promise<void> \| void` | — | 否 | `:on-submit="async () => {}"` | — |
2549
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2550
+ | ---------- | ------------------------------------------------------ | ------ | ---- | ----------------------------- | ---------------------------------------- |
2551
+ | `onSubmit` | `(form: Record<string, any>) => Promise<void> \| void` | — | 否 | `:on-submit="async () => {}"` | 校验通过后触发，回传用户名与密码等表单值 |
2554
2552
 
2555
2553
  **插槽（slots）**
2556
2554
 
2557
- | 插槽 | 作用域参数 | 示例 | 说明 |
2558
- | -------- | ---------- | -------------------------------- | ---- |
2559
- | `action` | — | `<template #action>…</template>` | — |
2555
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2556
+ | -------- | ---------- | -------------------------------- | ------------------------ |
2557
+ | `action` | — | `<template #action>…</template>` | 登录按钮下方的扩展操作区 |
2560
2558
 
2561
2559
  #### `ZlEmpty`
2562
2560
 
@@ -2623,20 +2621,20 @@ import { ZlForm } from '@zl-ui-kit/components'
2623
2621
 
2624
2622
  **props**
2625
2623
 
2626
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2627
- | ------- | --------------------- | ---------- | ---- | ---------------- | ---- |
2628
- | `items` | `FormItem[]` | `() => []` | 否 | `:items="items"` | — |
2629
- | `model` | `Record<string, any>` | — | 否 | `:model="{}"` | — |
2624
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2625
+ | ------- | --------------------- | ---------- | ---- | ---------------- | ----------------------------------- |
2626
+ | `items` | `FormItem[]` | `() => []` | 否 | `:items="items"` | 表单字段 schema，决定渲染哪些表单项 |
2627
+ | `model` | `Record<string, any>` | — | 否 | `:model="{}"` | 表单值对象，不传时由组件内部自建 |
2630
2628
 
2631
2629
  > 把 `$attrs` 透传给 `el-form`，未列出的属性会继续下传
2632
2630
 
2633
2631
  **插槽（slots）**
2634
2632
 
2635
- | 插槽 | 作用域参数 | 示例 | 说明 |
2636
- | -------------- | ------------------------------------------- | --------------------------------------------------------- | ---------------------------- |
2637
- | `label` | `v-bind="{ label: item.label, item }"` 展开 | `<template #label="{ label, item }">…</template>` | — |
2638
- | `[item.model]` | `model` / `field` | `<template #[item.model]="{ model, field }">…</template>` | 动态插槽：名字由该表达式决定 |
2639
- | `default` | — | `<template #default>…</template>` | — |
2633
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2634
+ | -------------- | ------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------- |
2635
+ | `label` | `v-bind="{ label: item.label, item }"` 展开 | `<template #label="{ label, item }">…</template>` | 自定义表单项标签的渲染内容 |
2636
+ | `[item.model]` | `model` / `field` | `<template #[item.model]="{ model, field }">…</template>` | 按该项 model 命名，传出 model、field；覆盖默认控件 |
2637
+ | `default` | — | `<template #default>…</template>` | 追加在末尾的表单内容（如额外区块、按钮） |
2640
2638
 
2641
2639
  **完整示例**：见 §7 表单与交互组件 › ZlForm —— schema 驱动
2642
2640
 
@@ -2662,9 +2660,9 @@ import { ZlFormChild } from '@zl-ui-kit/components'
2662
2660
 
2663
2661
  **props**
2664
2662
 
2665
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2666
- | ------ | --------------------- | ------ | ---- | ------------ | ---- |
2667
- | `item` | `Record<string, any>` | — | 是 | `:item="{}"` | — |
2663
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2664
+ | ------ | --------------------- | ------ | ---- | ------------ | ---------------------------------------- |
2665
+ | `item` | `Record<string, any>` | — | 是 | `:item="{}"` | 由 ZlForm 传入：描述要渲染的控件及其入参 |
2668
2666
 
2669
2667
  > 选项式组件（`defineComponent`），props 定义在 `props: {}` 中
2670
2668
 
@@ -2702,15 +2700,15 @@ import { ZlGridItem } from '@zl-ui-kit/components'
2702
2700
 
2703
2701
  **props**
2704
2702
 
2705
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2706
- | ------ | --------------------------------------------------------------------------------- | ------ | ---- | -------------- | ---- |
2707
- | `item` | `IGridItem & { text?: any; size?: number \| 'auto'; dict?: Record<string, any> }` | — | 是 | `:item="item"` | — |
2703
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2704
+ | ------ | --------------------------------------------------------------------------------- | ------ | ---- | -------------- | ------------------------------------ |
2705
+ | `item` | `IGridItem & { text?: any; size?: number \| 'auto'; dict?: Record<string, any> }` | — | 是 | `:item="item"` | 单个描述项配置：标签、取值与渲染方式 |
2708
2706
 
2709
2707
  **插槽（slots）**
2710
2708
 
2711
- | 插槽 | 作用域参数 | 示例 | 说明 |
2712
- | --------- | ---------- | --------------------------------- | ---- |
2713
- | `default` | — | `<template #default>…</template>` | — |
2709
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2710
+ | --------- | ---------- | --------------------------------- | ------------------------------------ |
2711
+ | `default` | — | `<template #default>…</template>` | 自定义该描述项的取值内容，替代纯文本 |
2714
2712
 
2715
2713
  #### `ZlGrid`
2716
2714
 
@@ -2747,22 +2745,22 @@ import { ZlGrid } from '@zl-ui-kit/components'
2747
2745
 
2748
2746
  | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2749
2747
  | --------------- | ----------------------------------------------------------------- | ------------ | ---- | --------------------------- | ------------------------------------------------------------- |
2750
- | `data` | `Record<string, any>` | `() => ({})` | 否 | `:data="{}"` | — |
2751
- | `grid` | `IGridItem[]` | `() => []` | 否 | `:grid="grid"` | — |
2752
- | `cols` | `number` | `3` | 否 | `:cols="1"` | — |
2753
- | `border` | `boolean` | — | 否 | `border` | — |
2754
- | `emptyChecker` | `(value: any, key: string, data: Record<string, any>) => boolean` | — | 否 | `:empty-checker="() => {}"` | — |
2755
- | `labelWidth` | `string \| number` | `'auto'` | 否 | `:label-width="labelWidth"` | — |
2756
- | `labelSuffix` | `string` | — | 否 | `label-suffix="："` | — |
2757
- | `labelPosition` | `'left' \| 'top' \| 'right'` | `'left'` | 否 | `label-position="left"` | — |
2748
+ | `data` | `Record<string, any>` | `() => ({})` | 否 | `:data="{}"` | 数据源对象，每项按 key 或 getValue 取值 |
2749
+ | `grid` | `IGridItem[]` | `() => []` | 否 | `:grid="grid"` | 描述项 schema：决定展示哪些字段与顺序 |
2750
+ | `cols` | `number` | `3` | 否 | `:cols="1"` | 每行显示的描述项列数，默认 3 |
2751
+ | `border` | `boolean` | — | 否 | `border` | 是否显示边框，呈表格式的网格线 |
2752
+ | `emptyChecker` | `(value: any, key: string, data: Record<string, any>) => boolean` | — | 否 | `:empty-checker="() => {}"` | 自定义空值判定；默认 0 以外的假值都算空 |
2753
+ | `labelWidth` | `string \| number` | `'auto'` | 否 | `:label-width="labelWidth"` | 标签列宽度；auto 时按实测最宽标签对齐 |
2754
+ | `labelSuffix` | `string` | — | 否 | `label-suffix="："` | 标签后缀，如冒号或空格 |
2755
+ | `labelPosition` | `'left' \| 'top' \| 'right'` | `'left'` | 否 | `label-position="left"` | 标签位置；top 时标签与值上下堆叠 |
2758
2756
  | `emptyText` | `string` | — | 否 | `empty-text="暂无数据"` | 空值占位文案（缺省走 i18n zl.grid.empty，未接入时兜底"暂无"） |
2759
2757
 
2760
2758
  **插槽（slots）**
2761
2759
 
2762
- | 插槽 | 作用域参数 | 示例 | 说明 |
2763
- | ------------ | ---------- | ------------------------------------ | ---------------------------- |
2764
- | `[item.key]` | — | `<template #[item.key]>…</template>` | 动态插槽：名字由该表达式决定 |
2765
- | `default` | — | `<template #default>…</template>` | — |
2760
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2761
+ | ------------ | ---------- | ------------------------------------ | ----------------------------------------- |
2762
+ | `[item.key]` | — | `<template #[item.key]>…</template>` | 按描述项的 key 命名，自定义该项的取值内容 |
2763
+ | `default` | — | `<template #default>…</template>` | 追加在所有描述项之后的自定义内容 |
2766
2764
 
2767
2765
  **完整示例**：见 §7 表单与交互组件 › ZlTabs / ZlDynamicComponent / ZlGrid
2768
2766
 
@@ -2798,18 +2796,18 @@ import { ZlHorizontalTable } from '@zl-ui-kit/components'
2798
2796
 
2799
2797
  **props**
2800
2798
 
2801
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2802
- | ------------ | ----------------------- | ---------- | ---- | --------------------- | ---- |
2803
- | `items` | `HorizontalTableItem[]` | `() => []` | 否 | `:items="items"` | — |
2804
- | `span` | `number \| string` | `24` | 否 | `:span="span"` | — |
2805
- | `labelWidth` | `string` | `'88px'` | 否 | `label-width="100px"` | — |
2806
- | `labelAlign` | `string` | `'center'` | 否 | `label-align="left"` | — |
2799
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2800
+ | ------------ | ----------------------- | ---------- | ---- | --------------------- | --------------------------------------------- |
2801
+ | `items` | `HorizontalTableItem[]` | `() => []` | 否 | `:items="items"` | 单元格配置列表：标签、取值与跨列 |
2802
+ | `span` | `number \| string` | `24` | 否 | `:span="span"` | 统一的栅格跨度，默认 24（可被单项 span 覆盖） |
2803
+ | `labelWidth` | `string` | `'88px'` | 否 | `label-width="100px"` | 标签单元格宽度，默认 88px |
2804
+ | `labelAlign` | `string` | `'center'` | 否 | `label-align="left"` | 标签文案的水平对齐方式，默认居中 |
2807
2805
 
2808
2806
  **插槽（slots）**
2809
2807
 
2810
- | 插槽 | 作用域参数 | 示例 | 说明 |
2811
- | ------------- | -------------------- | -------------------------------------------- | ---------------------------- |
2812
- | `[item.slot]` | `v-bind="item"` 展开 | `<template #[item.slot]="item">…</template>` | 动态插槽：名字由该表达式决定 |
2808
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2809
+ | ------------- | -------------------- | -------------------------------------------- | ------------------------------------ |
2810
+ | `[item.slot]` | `v-bind="item"` 展开 | `<template #[item.slot]="item">…</template>` | 名字取自 item.slot，传出该项完整配置 |
2813
2811
 
2814
2812
  **完整示例**：见 §8 布局与权限 › ZlHorizontalTable
2815
2813
 
@@ -2849,9 +2847,9 @@ import { ZlIcon } from '@zl-ui-kit/components'
2849
2847
 
2850
2848
  **插槽（slots）**
2851
2849
 
2852
- | 插槽 | 作用域参数 | 示例 | 说明 |
2853
- | --------- | ---------- | --------------------------------- | ---- |
2854
- | `default` | — | `<template #default>…</template>` | — |
2850
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2851
+ | --------- | ---------- | --------------------------------- | ------------------------------------ |
2852
+ | `default` | — | `<template #default>…</template>` | 自定义图标内容，覆盖 icon 的自动渲染 |
2855
2853
 
2856
2854
  #### `ZlI18nProvider`
2857
2855
 
@@ -2885,9 +2883,9 @@ import { ZlI18nProvider } from '@zl-ui-kit/components'
2885
2883
 
2886
2884
  **插槽（slots）**
2887
2885
 
2888
- | 插槽 | 作用域参数 | 示例 | 说明 |
2889
- | --------- | ---------- | --------------------------------- | ---- |
2890
- | `default` | — | `<template #default>…</template>` | — |
2886
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2887
+ | --------- | ---------- | --------------------------------- | -------------------------------------------- |
2888
+ | `default` | — | `<template #default>…</template>` | 被包住的应用内容，继承 Element Plus 当前语言 |
2891
2889
 
2892
2890
  **完整示例**：见 §1 简介与包结构 › 1.2.2 App.vue：根组件包一层 ZlI18nProvider
2893
2891
 
@@ -2955,9 +2953,9 @@ import { ZlIconLabel } from '@zl-ui-kit/components'
2955
2953
 
2956
2954
  **插槽（slots）**
2957
2955
 
2958
- | 插槽 | 作用域参数 | 示例 | 说明 |
2959
- | --------- | ---------- | --------------------------------- | ---- |
2960
- | `default` | — | `<template #default>…</template>` | — |
2956
+ | 插槽 | 作用域参数 | 示例 | 说明 |
2957
+ | --------- | ---------- | --------------------------------- | ------------------------------------ |
2958
+ | `default` | — | `<template #default>…</template>` | 图标后的文案；不传时退化为纯图标按钮 |
2961
2959
 
2962
2960
  #### `ZlCornerTag`
2963
2961
 
@@ -2991,17 +2989,17 @@ import { ZlCornerTag } from '@zl-ui-kit/components'
2991
2989
 
2992
2990
  **props**
2993
2991
 
2994
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2995
- | ---------- | -------------------------------------------------------------- | ------------- | ---- | --------------------- | ---- |
2996
- | `icon` | `string` | — | 否 | `icon="zl:search"` | — |
2997
- | `color` | `string` | — | 否 | `color="#409eff"` | — |
2998
- | `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'top-right'` | 否 | `position="top-left"` | — |
2992
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
2993
+ | ---------- | -------------------------------------------------------------- | ------------- | ---- | --------------------- | ------------------------------ |
2994
+ | `icon` | `string` | — | 否 | `icon="zl:search"` | 文案前的图标名，走 ZlIcon 渲染 |
2995
+ | `color` | `string` | — | 否 | `color="#409eff"` | 背景渐变的主色，取内置主题色名 |
2996
+ | `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'top-right'` | 否 | `position="top-left"` | 贴在容器的哪个角，默认右上角 |
2999
2997
 
3000
2998
  **插槽（slots）**
3001
2999
 
3002
- | 插槽 | 作用域参数 | 示例 | 说明 |
3003
- | --------- | ---------- | --------------------------------- | ---- |
3004
- | `default` | — | `<template #default>…</template>` | — |
3000
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3001
+ | --------- | ---------- | --------------------------------- | ------------------------ |
3002
+ | `default` | — | `<template #default>…</template>` | 标签文案，显示在图标之后 |
3005
3003
 
3006
3004
  #### `ZlLayoutSwitch`
3007
3005
 
@@ -3025,10 +3023,10 @@ import { ZlLayoutSwitch } from '@zl-ui-kit/components'
3025
3023
 
3026
3024
  **props**
3027
3025
 
3028
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3029
- | ------------ | ------------------- | -------- | ---- | ----------------- | -------------------------------------------- |
3030
- | `modelValue` | `'grid' \| 'table'` | — | 否 | `v-model="value"` | `v-model` 绑定的值（`defineModel` 隐式声明） |
3031
- | `value` | `'grid' \| 'table'` | `'grid'` | 否 | `value="grid"` | — |
3026
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3027
+ | ------------ | ------------------- | -------- | ---- | ----------------- | ------------------------------------------------------- |
3028
+ | `modelValue` | `'grid' \| 'table'` | — | 否 | `v-model="value"` | 当前布局，`v-model` 绑定；未绑定时回落 `value` |
3029
+ | `value` | `'grid' \| 'table'` | `'grid'` | 否 | `value="grid"` | 已废弃，请用 `modelValue`；仅在未双向绑定时作为当前布局 |
3032
3030
 
3033
3031
  **事件（emits）**
3034
3032
 
@@ -3115,9 +3113,9 @@ import { ZlPermission } from '@zl-ui-kit/components'
3115
3113
 
3116
3114
  **插槽（slots）**
3117
3115
 
3118
- | 插槽 | 作用域参数 | 示例 | 说明 |
3119
- | --------- | ---------- | --------------------------------- | ---- |
3120
- | `default` | — | `<template #default>…</template>` | — |
3116
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3117
+ | --------- | ---------- | --------------------------------- | ---------------------- |
3118
+ | `default` | — | `<template #default>…</template>` | 权限命中时才渲染的内容 |
3121
3119
 
3122
3120
  **完整示例**：见 §8 布局与权限 › ZlPermission
3123
3121
 
@@ -3155,12 +3153,12 @@ import { ZlPopconfirm } from '@zl-ui-kit/components'
3155
3153
 
3156
3154
  **props**
3157
3155
 
3158
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3159
- | ------------------- | -------- | ------ | ---- | -------------------------------------- | ---- |
3160
- | `title` | `string` | — | 否 | `title="标题"` | — |
3161
- | `content` | `string` | — | 否 | `content="删除后不可恢复，是否继续？"` | — |
3162
- | `confirmButtonText` | `string` | — | 否 | `confirm-button-text="确定"` | — |
3163
- | `cancelButtonText` | `string` | — | 否 | `cancel-button-text="取消"` | — |
3156
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3157
+ | ------------------- | -------- | ------ | ---- | -------------------------------------- | ----------------------------------------------- |
3158
+ | `title` | `string` | — | 否 | `title="标题"` | 气泡标题文案；不传且无 title 插槽时不渲染标题行 |
3159
+ | `content` | `string` | — | 否 | `content="删除后不可恢复，是否继续？"` | 气泡正文文案，说明该操作的后果 |
3160
+ | `confirmButtonText` | `string` | — | 否 | `confirm-button-text="确定"` | 确认按钮文案；不传时取 i18n 默认值 |
3161
+ | `cancelButtonText` | `string` | — | 否 | `cancel-button-text="取消"` | 取消按钮文案；不传时取 i18n 默认值 |
3164
3162
 
3165
3163
  > 把 `$attrs` 透传给 `el-popover`，未列出的属性会继续下传
3166
3164
 
@@ -3173,11 +3171,11 @@ import { ZlPopconfirm } from '@zl-ui-kit/components'
3173
3171
 
3174
3172
  **插槽（slots）**
3175
3173
 
3176
- | 插槽 | 作用域参数 | 示例 | 说明 |
3177
- | --------- | ---------- | --------------------------------- | ---- |
3178
- | `default` | — | `<template #default>…</template>` | — |
3179
- | `title` | — | `<template #title>…</template>` | — |
3180
- | `content` | — | `<template #content>…</template>` | — |
3174
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3175
+ | --------- | ---------- | --------------------------------- | ------------------------------------- |
3176
+ | `default` | — | `<template #default>…</template>` | 触发气泡的元素，点击它才会弹出 |
3177
+ | `title` | — | `<template #title>…</template>` | 自定义标题行内容，缺省渲染 title 文案 |
3178
+ | `content` | — | `<template #content>…</template>` | 自定义正文内容，缺省渲染 content 文案 |
3181
3179
 
3182
3180
  **完整示例**：见 §7 表单与交互组件 › ZlDrawer / ZlPopconfirm / ZlSwitch
3183
3181
 
@@ -3213,11 +3211,11 @@ import { ZlRadioTag } from '@zl-ui-kit/components'
3213
3211
 
3214
3212
  **props**
3215
3213
 
3216
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3217
- | ------------ | ------------------------------- | ---------- | ---- | -------------------- | -------------------------------------------- |
3218
- | `modelValue` | `string \| number \| undefined` | — | 否 | `v-model="value"` | `v-model` 绑定的值（`defineModel` 隐式声明） |
3219
- | `options` | `RadioTagOption[]` | `() => []` | 否 | `:options="options"` | — |
3220
- | `size` | `'mini' \| 'small' \| 'medium'` | `'small'` | 否 | `size="mini"` | — |
3214
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3215
+ | ------------ | ------------------------------- | ---------- | ---- | -------------------- | -------------------------------- |
3216
+ | `modelValue` | `string \| number \| undefined` | — | 否 | `v-model="value"` | 选中项的 value，`v-model` 绑定 |
3217
+ | `options` | `RadioTagOption[]` | `() => []` | 否 | `:options="options"` | 标签选项列表，`value` 作为选中值 |
3218
+ | `size` | `'mini' \| 'small' \| 'medium'` | `'small'` | 否 | `size="mini"` | 标签尺寸，默认 small |
3221
3219
 
3222
3220
  **事件（emits）**
3223
3221
 
@@ -3227,9 +3225,9 @@ import { ZlRadioTag } from '@zl-ui-kit/components'
3227
3225
 
3228
3226
  **插槽（slots）**
3229
3227
 
3230
- | 插槽 | 作用域参数 | 示例 | 说明 |
3231
- | --------- | ------------------------------------------------------- | ----------------------------------------------------- | ---- |
3232
- | `default` | `v-bind="{ item, checked: model === item.value }"` 展开 | `<template #default="{ item, checked }">…</template>` | — |
3228
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3229
+ | --------- | ------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------ |
3230
+ | `default` | `v-bind="{ item, checked: model === item.value }"` 展开 | `<template #default="{ item, checked }">…</template>` | 单个标签的内容，可用 item / checked 自定义 |
3233
3231
 
3234
3232
  **完整示例**：见 §7 表单与交互组件 › ZlRadioTag / ZlCheckboxTag / ZlCheckAll / ZlSorter / ZlAddSub / ZlLayoutSwitch
3235
3233
 
@@ -3275,7 +3273,7 @@ import { ZlSearch } from '@zl-ui-kit/components'
3275
3273
  | `immediate` | `boolean` | `true` | 否 | `:immediate="false"` | 挂载后立即执行一次查询（默认 true） |
3276
3274
  | `disabled` | `boolean` | `false` | 否 | `disabled` | 禁用全部查询项 |
3277
3275
  | `labelsVisible` | `boolean` | `undefined` | 否 | `labels-visible` | 是否展示「筛选条件」标签行；不传时按「是否发生溢出」自动判定 |
3278
- | `showLabels` | `boolean` | `undefined` | 否 | `show-labels` | — |
3276
+ | `showLabels` | `boolean` | `undefined` | 否 | `show-labels` | 已废弃，请用 `labelsVisible` |
3279
3277
 
3280
3278
  **事件（emits）**
3281
3279
 
@@ -3286,10 +3284,10 @@ import { ZlSearch } from '@zl-ui-kit/components'
3286
3284
 
3287
3285
  **插槽（slots）**
3288
3286
 
3289
- | 插槽 | 作用域参数 | 示例 | 说明 |
3290
- | --------- | --------------------- | ---------------------------------------- | ---------------------------- |
3291
- | `[slot]` | `v-bind="scope"` 展开 | `<template #[slot]="scope">…</template>` | 动态插槽：名字由该表达式决定 |
3292
- | `actions` | — | `<template #actions>…</template>` | — |
3287
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3288
+ | --------- | --------------------- | ---------------------------------------- | ------------------------------------------------- |
3289
+ | `[slot]` | `v-bind="scope"` 展开 | `<template #[slot]="scope">…</template>` | 动态插槽：按查询项的 model 命名，替换该项默认控件 |
3290
+ | `actions` | — | `<template #actions>…</template>` | 查询条下方的自定义操作区 |
3293
3291
 
3294
3292
  **暴露（defineExpose）**
3295
3293
 
@@ -3345,11 +3343,11 @@ import { ZlSearchTable } from '@zl-ui-kit/components'
3345
3343
 
3346
3344
  | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3347
3345
  | ------------ | ----------------------------------------------------------------------------------------------------------------------------- | ---------- | ---- | --------------------------- | --------------------------------------------------------------- |
3348
- | `immediate` | `boolean` | `true` | 否 | `:immediate="false"` | — |
3346
+ | `immediate` | `boolean` | `true` | 否 | `:immediate="false"` | 挂载后立即请求首屏数据，默认 true |
3349
3347
  | `request` | `\| ((...args: any[]) => Promise<any>) \| { service: (...args: any[]) => Promise<any>; options?: Record<string, any> }` | — | 是 | `:request="async () => {}"` | 请求函数，或 { service, options }（usePageableRequest options） |
3350
- | `columns` | `TableColumn[]` | `() => []` | 否 | `:columns="columns"` | — |
3351
- | `queryItems` | `SearchItem[]` | `() => []` | 否 | `:query-items="queryItems"` | — |
3352
- | `pagination` | `Record<string, any> \| boolean` | — | 否 | `:pagination="{}"` | — |
3348
+ | `columns` | `TableColumn[]` | `() => []` | 否 | `:columns="columns"` | 表格列定义，决定有哪些列及其渲染方式 |
3349
+ | `queryItems` | `SearchItem[]` | `() => []` | 否 | `:query-items="queryItems"` | 查询区的表单项；为空且不传 search-actions 插槽时不渲染查询条 |
3350
+ | `pagination` | `Record<string, any> \| boolean` | — | 否 | `:pagination="{}"` | 分页配置；传 false 关闭分页 |
3353
3351
 
3354
3352
  > 把 `$attrs` 透传给 `ZlTable`，未列出的属性会继续下传
3355
3353
 
@@ -3361,11 +3359,11 @@ import { ZlSearchTable } from '@zl-ui-kit/components'
3361
3359
 
3362
3360
  **插槽（slots）**
3363
3361
 
3364
- | 插槽 | 作用域参数 | 示例 | 说明 |
3365
- | ---------------- | --------------------- | --------------------------------------------- | ---------------------------- |
3366
- | `search-actions` | — | `<template #search-actions>…</template>` | — |
3367
- | `[slot.slot]` | `v-bind="scope"` 展开 | `<template #[slot.slot]="scope">…</template>` | 动态插槽：名字由该表达式决定 |
3368
- | `[slot]` | `v-bind="scope"` 展开 | `<template #[slot]="scope">…</template>` | 动态插槽：名字由该表达式决定 |
3362
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3363
+ | ---------------- | --------------------- | --------------------------------------------- | ---------------------------------------------------- |
3364
+ | `search-actions` | — | `<template #search-actions>…</template>` | 查询条右侧的操作区，转发给 ZlSearch 的 actions |
3365
+ | `[slot.slot]` | `v-bind="scope"` 展开 | `<template #[slot.slot]="scope">…</template>` | 动态插槽：search- 前缀的插槽去前缀后透传给 ZlSearch |
3366
+ | `[slot]` | `v-bind="scope"` 展开 | `<template #[slot]="scope">…</template>` | 动态插槽：其余插槽按原名透传给 ZlTable，可作为列插槽 |
3369
3367
 
3370
3368
  **暴露（defineExpose）**
3371
3369
 
@@ -3410,20 +3408,20 @@ import { ZlSection } from '@zl-ui-kit/components'
3410
3408
 
3411
3409
  **props**
3412
3410
 
3413
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3414
- | ------------- | --------- | ------ | ---- | ------------------ | ------------------------------ |
3415
- | `icon` | `string` | — | 否 | `icon="zl:search"` | 标题图标名（zl: 前缀自动补全） |
3416
- | `title` | `string` | — | 否 | `title="标题"` | — |
3417
- | `block` | `boolean` | — | 否 | `block` | 块状布局（内容区滚动） |
3418
- | `blockHidden` | `boolean` | — | 否 | `block-hidden` | 块状布局且隐藏溢出 |
3411
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3412
+ | ------------- | --------- | ------ | ---- | ------------------ | ------------------------------------------- |
3413
+ | `icon` | `string` | — | 否 | `icon="zl:search"` | 标题图标名（zl: 前缀自动补全） |
3414
+ | `title` | `string` | — | 否 | `title="标题"` | 标题文案；不传且无 actions 插槽时不渲染头部 |
3415
+ | `block` | `boolean` | — | 否 | `block` | 块状布局（内容区滚动） |
3416
+ | `blockHidden` | `boolean` | — | 否 | `block-hidden` | 块状布局且隐藏溢出 |
3419
3417
 
3420
3418
  **插槽（slots）**
3421
3419
 
3422
- | 插槽 | 作用域参数 | 示例 | 说明 |
3423
- | --------------- | ---------- | --------------------------------------- | ---- |
3424
- | `title-prepend` | — | `<template #title-prepend>…</template>` | — |
3425
- | `actions` | — | `<template #actions>…</template>` | — |
3426
- | `default` | — | `<template #default>…</template>` | — |
3420
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3421
+ | --------------- | ---------- | --------------------------------------- | ---------------------------------------------- |
3422
+ | `title-prepend` | — | `<template #title-prepend>…</template>` | 标题文字之后的附加内容，如数量、角标 |
3423
+ | `actions` | — | `<template #actions>…</template>` | 头部右侧的操作区；传了它即使无标题也会渲染头部 |
3424
+ | `default` | — | `<template #default>…</template>` | 区块主体内容 |
3427
3425
 
3428
3426
  #### `ZlSorter`
3429
3427
 
@@ -3457,10 +3455,10 @@ import { ZlSorter } from '@zl-ui-kit/components'
3457
3455
 
3458
3456
  **props**
3459
3457
 
3460
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3461
- | ------------ | ----------------------- | ------ | ---- | ----------------- | -------------------------------------------- |
3462
- | `modelValue` | `'' \| 'asc' \| 'desc'` | — | 否 | `v-model="value"` | `v-model` 绑定的值（`defineModel` 隐式声明） |
3463
- | `label` | `string` | — | 否 | `label="标签"` | — |
3458
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3459
+ | ------------ | ----------------------- | ------ | ---- | ----------------- | ----------------------------------------- |
3460
+ | `modelValue` | `'' \| 'asc' \| 'desc'` | — | 否 | `v-model="value"` | 当前排序状态，空串表示不排序（`v-model`） |
3461
+ | `label` | `string` | — | 否 | `label="标签"` | 字段文案；可被默认插槽覆盖 |
3464
3462
 
3465
3463
  **事件（emits）**
3466
3464
 
@@ -3471,9 +3469,9 @@ import { ZlSorter } from '@zl-ui-kit/components'
3471
3469
 
3472
3470
  **插槽（slots）**
3473
3471
 
3474
- | 插槽 | 作用域参数 | 示例 | 说明 |
3475
- | --------- | ---------- | --------------------------------- | ---- |
3476
- | `default` | — | `<template #default>…</template>` | — |
3472
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3473
+ | --------- | ---------- | --------------------------------- | ------------------------------ |
3474
+ | `default` | — | `<template #default>…</template>` | 自定义字段文案，缺省显示 label |
3477
3475
 
3478
3476
  **完整示例**：见 §7 表单与交互组件 › ZlRadioTag / ZlCheckboxTag / ZlCheckAll / ZlSorter / ZlAddSub / ZlLayoutSwitch
3479
3477
 
@@ -3501,10 +3499,10 @@ import { ZlSorterList } from '@zl-ui-kit/components'
3501
3499
 
3502
3500
  **props**
3503
3501
 
3504
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3505
- | ---------- | -------------- | ---------- | ---- | -------------------- | ---- |
3506
- | `sorters` | `SorterItem[]` | `() => []` | 否 | `:sorters="sorters"` | — |
3507
- | `multiple` | `boolean` | `false` | 否 | `multiple` | — |
3502
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3503
+ | ---------- | -------------- | ---------- | ---- | -------------------- | ---------------------------------------------- |
3504
+ | `sorters` | `SorterItem[]` | `() => []` | 否 | `:sorters="sorters"` | 可排序字段列表，model 为字段名 |
3505
+ | `multiple` | `boolean` | `false` | 否 | `multiple` | 允许多字段同时排序；关闭时只保留最后点击的字段 |
3508
3506
 
3509
3507
  **事件（emits）**
3510
3508
 
@@ -3545,14 +3543,14 @@ import { ZlSwitch } from '@zl-ui-kit/components'
3545
3543
 
3546
3544
  **props**
3547
3545
 
3548
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3549
- | ---------------- | ----------------------------- | ------- | ---- | ----------------------------------- | ---- |
3550
- | `modelValue` | `boolean \| string \| number` | — | 否 | `v-model="value"` | — |
3551
- | `defaultChecked` | `boolean` | `false` | 否 | `default-checked` | — |
3552
- | `checkedValue` | `boolean \| string \| number` | `true` | 否 | `:checked-value="checkedValue"` | — |
3553
- | `uncheckedValue` | `boolean \| string \| number` | `false` | 否 | `:unchecked-value="uncheckedValue"` | — |
3554
- | `checkedText` | `string` | — | 否 | `checked-text="开"` | — |
3555
- | `uncheckedText` | `string` | — | 否 | `unchecked-text="关"` | — |
3546
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3547
+ | ---------------- | ----------------------------- | ------- | ---- | ----------------------------------- | ---------------------------- |
3548
+ | `modelValue` | `boolean \| string \| number` | — | 否 | `v-model="value"` | 当前开关值，支持受控双向绑定 |
3549
+ | `defaultChecked` | `boolean` | `false` | 否 | `default-checked` | 非受控模式下的初始选中状态 |
3550
+ | `checkedValue` | `boolean \| string \| number` | `true` | 否 | `:checked-value="checkedValue"` | 选中状态对应的提交值 |
3551
+ | `uncheckedValue` | `boolean \| string \| number` | `false` | 否 | `:unchecked-value="uncheckedValue"` | 未选中状态对应的提交值 |
3552
+ | `checkedText` | `string` | — | 否 | `checked-text="开"` | 选中时显示的文案 |
3553
+ | `uncheckedText` | `string` | — | 否 | `unchecked-text="关"` | 未选中时显示的文案 |
3556
3554
 
3557
3555
  > 把 `$attrs` 透传给 `el-switch`，未列出的属性会继续下传
3558
3556
 
@@ -3564,10 +3562,10 @@ import { ZlSwitch } from '@zl-ui-kit/components'
3564
3562
 
3565
3563
  **插槽（slots）**
3566
3564
 
3567
- | 插槽 | 作用域参数 | 示例 | 说明 |
3568
- | ----------- | ---------- | ----------------------------------- | ---- |
3569
- | `checked` | — | `<template #checked>…</template>` | — |
3570
- | `unchecked` | — | `<template #unchecked>…</template>` | — |
3565
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3566
+ | ----------- | ---------- | ----------------------------------- | ---------------------- |
3567
+ | `checked` | — | `<template #checked>…</template>` | 选中状态的自定义文案 |
3568
+ | `unchecked` | — | `<template #unchecked>…</template>` | 未选中状态的自定义文案 |
3571
3569
 
3572
3570
  **完整示例**：见 §7 表单与交互组件 › ZlDrawer / ZlPopconfirm / ZlSwitch
3573
3571
 
@@ -3609,11 +3607,11 @@ import { ZlTable } from '@zl-ui-kit/components'
3609
3607
 
3610
3608
  | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3611
3609
  | -------------- | -------------------------------- | -------- | ---- | -------------------- | ---------------------------------------------------------------------------- |
3612
- | `columns` | `TableColumn[]` | — | 是 | `:columns="columns"` | — |
3610
+ | `columns` | `TableColumn[]` | — | 是 | `:columns="columns"` | 表格列配置，定义字段、标题与渲染方式 |
3613
3611
  | `data` | `any[] \| Record<string, any>` | — | 是 | `:data="data"` | 数组（本地数据）或 { [dataKey]: rows, pageNum, pageSize, total }（分页数据） |
3614
- | `dataKey` | `string` | `'rows'` | 否 | `data-key="rows"` | — |
3612
+ | `dataKey` | `string` | `'rows'` | 否 | `data-key="rows"` | 分页数据中的行数组字段名 |
3615
3613
  | `expandAction` | `boolean` | `false` | 否 | `expand-action` | actions 列宽加宽（参考实现 expandAction 语义） |
3616
- | `pagination` | `Record<string, any> \| boolean` | — | 否 | `:pagination="{}"` | — |
3614
+ | `pagination` | `Record<string, any> \| boolean` | — | 否 | `:pagination="{}"` | 分页配置，设为 false 时隐藏分页 |
3617
3615
  | `loading` | `boolean` | `false` | 否 | `loading` | 表格 loading（作用于表格区） |
3618
3616
 
3619
3617
  > 把 `$attrs` 透传给 `el-table`，未列出的属性会继续下传
@@ -3628,11 +3626,11 @@ import { ZlTable } from '@zl-ui-kit/components'
3628
3626
 
3629
3627
  **插槽（slots）**
3630
3628
 
3631
- | 插槽 | 作用域参数 | 示例 | 说明 |
3632
- | ------------------------- | --------------------- | --------------------------------------------------------- | ---------------------------- |
3633
- | `expand` | `v-bind="scope"` 展开 | `<template #expand="scope">…</template>` | — |
3634
- | `[column.headerSlotName]` | `v-bind="scope"` 展开 | `<template #[column.headerSlotName]="scope">…</template>` | 动态插槽：名字由该表达式决定 |
3635
- | `[column.slotName]` | `v-bind="scope"` 展开 | `<template #[column.slotName]="scope">…</template>` | 动态插槽：名字由该表达式决定 |
3629
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3630
+ | ------------------------- | --------------------- | --------------------------------------------------------- | ---------------------------------------- |
3631
+ | `expand` | `v-bind="scope"` 展开 | `<template #expand="scope">…</template>` | 展开行内容，参数为表格行上下文 |
3632
+ | `[column.headerSlotName]` | `v-bind="scope"` 展开 | `<template #[column.headerSlotName]="scope">…</template>` | 按列字段生成 header-* 名，参数为列上下文 |
3633
+ | `[column.slotName]` | `v-bind="scope"` 展开 | `<template #[column.slotName]="scope">…</template>` | 按 slot 或字段名生成，参数为单元格上下文 |
3636
3634
 
3637
3635
  **完整示例**：见 §6 数据型组件 + useRequest 体系（核心） › ③ ZlTable + ZlPagination —— 自行 usePaginationRequest
3638
3636
 
@@ -3673,23 +3671,23 @@ import { ZlTabs } from '@zl-ui-kit/components'
3673
3671
 
3674
3672
  **props**
3675
3673
 
3676
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3677
- | --------- | --------- | ---------- | ---- | ------------------- | ---- |
3678
- | `tabs` | `any[]` | `() => []` | 否 | `:tabs="[]"` | — |
3679
- | `border` | `boolean` | `true` | 否 | `:border="false"` | — |
3680
- | `fit` | `boolean` | — | 否 | `fit` | — |
3681
- | `darkNav` | `boolean` | `true` | 否 | `:dark-nav="false"` | — |
3674
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3675
+ | --------- | --------- | ---------- | ---- | ------------------- | --------------------------------- |
3676
+ | `tabs` | `any[]` | `() => []` | 否 | `:tabs="[]"` | 页签配置列表，以 key 关联内容插槽 |
3677
+ | `border` | `boolean` | `true` | 否 | `:border="false"` | 是否显示页签导航分隔线，默认显示 |
3678
+ | `fit` | `boolean` | — | 否 | `fit` | 是否撑满容器并让内容区滚动 |
3679
+ | `darkNav` | `boolean` | `true` | 否 | `:dark-nav="false"` | 是否启用导航背景色，默认启用 |
3682
3680
 
3683
3681
  > 选项式组件（`defineComponent`），props 定义在 `props: {}` 中
3684
3682
  > 把 `$attrs` 透传给内部组件，未列出的属性会继续下传
3685
3683
 
3686
3684
  **插槽（slots）**
3687
3685
 
3688
- | 插槽 | 作用域参数 | 示例 | 说明 |
3689
- | --------- | ---------- | --------------------------------- | ---------------------------- |
3690
- | `[key]` | — | `<template #[key]>…</template>` | 动态插槽：名字由该表达式决定 |
3691
- | `default` | — | `<template #default>…</template>` | — |
3692
- | `extra` | — | `<template #extra>…</template>` | — |
3686
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3687
+ | --------- | ---------- | --------------------------------- | ----------------------------------------------------------- |
3688
+ | `[key]` | — | `<template #[key]>…</template>` | 会对返回值调用 .some()，拿到单个 vnode 会直接抛 TypeError。 |
3689
+ | `default` | — | `<template #default>…</template>` | 追加在页签列表之后的内容（不在任何 ElTabPane 内） |
3690
+ | `extra` | — | `<template #extra>…</template>` | 页签栏右侧的附加操作区 |
3693
3691
 
3694
3692
  **完整示例**：见 §7 表单与交互组件 › ZlTabs / ZlDynamicComponent / ZlGrid
3695
3693
 
@@ -3725,23 +3723,23 @@ import { ZlTag } from '@zl-ui-kit/components'
3725
3723
 
3726
3724
  **props**
3727
3725
 
3728
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3729
- | ----------------- | ------------------------------- | ----------- | ---- | -------------------------- | ---- |
3730
- | `size` | `'mini' \| 'small' \| 'medium'` | `undefined` | 否 | `size="mini"` | — |
3731
- | `color` | `string` | `undefined` | 否 | `color="#409eff"` | — |
3732
- | `bordered` | `boolean` | `false` | 否 | `bordered` | — |
3733
- | `fill` | `boolean` | `false` | 否 | `fill` | — |
3734
- | `disabled` | `boolean` | `false` | 否 | `disabled` | — |
3735
- | `icon` | `string` | `undefined` | 否 | `icon="zl:search"` | — |
3736
- | `dotIcon` | `boolean` | `false` | 否 | `dot-icon` | — |
3737
- | `iconColor` | `string` | `undefined` | 否 | `icon-color="#409eff"` | — |
3738
- | `closable` | `boolean` | `false` | 否 | `closable` | — |
3739
- | `visible` | `boolean \| undefined` | `undefined` | 否 | `v-model:visible="value"` | — |
3740
- | `defaultVisible` | `boolean` | `true` | 否 | `:default-visible="false"` | — |
3741
- | `selectable` | `boolean` | `false` | 否 | `selectable` | — |
3742
- | `selected` | `boolean \| undefined` | `undefined` | 否 | `v-model:selected="value"` | — |
3743
- | `defaultSelected` | `boolean` | `false` | 否 | `default-selected` | — |
3744
- | `rounded` | `boolean` | `false` | 否 | `rounded` | — |
3726
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3727
+ | ----------------- | ------------------------------- | ----------- | ---- | -------------------------- | -------------------------------- |
3728
+ | `size` | `'mini' \| 'small' \| 'medium'` | `undefined` | 否 | `size="mini"` | 标签尺寸档位，默认 small |
3729
+ | `color` | `string` | `undefined` | 否 | `color="#409eff"` | 标签主题色名称 |
3730
+ | `bordered` | `boolean` | `false` | 否 | `bordered` | 是否显示标签边框 |
3731
+ | `fill` | `boolean` | `false` | 否 | `fill` | 是否显示填充背景，选择模式下无效 |
3732
+ | `disabled` | `boolean` | `false` | 否 | `disabled` | 是否应用禁用样式并隐藏关闭按钮 |
3733
+ | `icon` | `string` | `undefined` | 否 | `icon="zl:search"` | 标签前置图标名称 |
3734
+ | `dotIcon` | `boolean` | `false` | 否 | `dot-icon` | 是否使用圆点图标 |
3735
+ | `iconColor` | `string` | `undefined` | 否 | `icon-color="#409eff"` | 前置图标主题色名称 |
3736
+ | `closable` | `boolean` | `false` | 否 | `closable` | 是否显示关闭按钮 |
3737
+ | `visible` | `boolean \| undefined` | `undefined` | 否 | `v-model:visible="value"` | 受控模式下的显示状态 |
3738
+ | `defaultVisible` | `boolean` | `true` | 否 | `:default-visible="false"` | 非受控模式下的初始显示状态 |
3739
+ | `selectable` | `boolean` | `false` | 否 | `selectable` | 是否启用点击选择 |
3740
+ | `selected` | `boolean \| undefined` | `undefined` | 否 | `v-model:selected="value"` | 受控模式下的选中状态 |
3741
+ | `defaultSelected` | `boolean` | `false` | 否 | `default-selected` | 非受控模式下的初始选中状态 |
3742
+ | `rounded` | `boolean` | `false` | 否 | `rounded` | 是否使用全圆角样式 |
3745
3743
 
3746
3744
  **事件（emits）**
3747
3745
 
@@ -3754,9 +3752,9 @@ import { ZlTag } from '@zl-ui-kit/components'
3754
3752
 
3755
3753
  **插槽（slots）**
3756
3754
 
3757
- | 插槽 | 作用域参数 | 示例 | 说明 |
3758
- | --------- | ---------- | --------------------------------- | ---- |
3759
- | `default` | — | `<template #default>…</template>` | — |
3755
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3756
+ | --------- | ---------- | --------------------------------- | ------------ |
3757
+ | `default` | — | `<template #default>…</template>` | 标签文本内容 |
3760
3758
 
3761
3759
  **完整示例**：见 §5 通用展示组件 › ZlTag — 标签
3762
3760
 
@@ -3792,15 +3790,15 @@ import { ZlText } from '@zl-ui-kit/components'
3792
3790
 
3793
3791
  **props**
3794
3792
 
3795
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3796
- | ------------ | ----------------------------- | ------ | ---- | --------------------------- | ---- |
3797
- | `modelValue` | `string \| number \| boolean` | — | 否 | `:model-value="modelValue"` | — |
3793
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3794
+ | ------------ | ----------------------------- | ------ | ---- | --------------------------- | ------------------------ |
3795
+ | `modelValue` | `string \| number \| boolean` | — | 否 | `:model-value="modelValue"` | 未使用插槽时显示的文本值 |
3798
3796
 
3799
3797
  **插槽（slots）**
3800
3798
 
3801
- | 插槽 | 作用域参数 | 示例 | 说明 |
3802
- | --------- | ---------- | --------------------------------- | ---- |
3803
- | `default` | — | `<template #default>…</template>` | — |
3799
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3800
+ | --------- | ---------- | --------------------------------- | ------------------------------- |
3801
+ | `default` | — | `<template #default>…</template>` | 自定义文本内容，覆盖 modelValue |
3804
3802
 
3805
3803
  #### `ZlTitle`
3806
3804
 
@@ -3836,21 +3834,21 @@ import { ZlTitle } from '@zl-ui-kit/components'
3836
3834
 
3837
3835
  **props**
3838
3836
 
3839
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3840
- | ------------- | -------------------------------- | ------ | ---- | ---------------------- | ---- |
3841
- | `title` | `string` | — | 否 | `title="标题"` | — |
3842
- | `description` | `string` | — | 否 | `description="副标题"` | — |
3843
- | `marker` | `boolean` | `true` | 否 | `:marker="false"` | — |
3844
- | `tooltip` | `string` | — | 否 | `tooltip="提示内容"` | — |
3845
- | `size` | `'small' \| 'medium' \| 'large'` | — | 否 | `size="small"` | — |
3837
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3838
+ | ------------- | -------------------------------- | ------ | ---- | ---------------------- | ------------------------------ |
3839
+ | `title` | `string` | — | 否 | `title="标题"` | 默认标题文本 |
3840
+ | `description` | `string` | — | 否 | `description="副标题"` | 标题后的描述文本 |
3841
+ | `marker` | `boolean` | `true` | 否 | `:marker="false"` | 是否显示标题左侧标记，默认显示 |
3842
+ | `tooltip` | `string` | — | 否 | `tooltip="提示内容"` | 标题旁帮助图标的提示内容 |
3843
+ | `size` | `'small' \| 'medium' \| 'large'` | — | 否 | `size="small"` | 标题文字尺寸档位 |
3846
3844
 
3847
3845
  **插槽（slots）**
3848
3846
 
3849
- | 插槽 | 作用域参数 | 示例 | 说明 |
3850
- | ------------- | ---------- | ------------------------------------- | ---- |
3851
- | `default` | — | `<template #default>…</template>` | — |
3852
- | `description` | — | `<template #description>…</template>` | — |
3853
- | `extra` | — | `<template #extra>…</template>` | — |
3847
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3848
+ | ------------- | ---------- | ------------------------------------- | ---------------------------------- |
3849
+ | `default` | — | `<template #default>…</template>` | 自定义标题内容，覆盖 title |
3850
+ | `description` | — | `<template #description>…</template>` | 自定义描述内容，需设置 description |
3851
+ | `extra` | — | `<template #extra>…</template>` | 标题右侧附加内容 |
3854
3852
 
3855
3853
  **完整示例**：见 §5 通用展示组件 › ZlTitle — 区块标题
3856
3854
 
@@ -3888,21 +3886,21 @@ import { ZlUpload } from '@zl-ui-kit/components'
3888
3886
 
3889
3887
  **props**
3890
3888
 
3891
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3892
- | ----------------------- | --------------------------------------------------------------- | ----------- | ---- | ----------------------------------------- | -------------------------------------------- |
3893
- | `request` | `(form: FormData, config: Record<string, any>) => Promise<any>` | — | 否 | `:request="async () => {}"` | 自定义上传函数（form, config）→ Promise |
3894
- | `modelValue` | `string \| any[]` | `''` | 否 | `v-model="value"` | `v-model` 绑定的值（`defineModel` 隐式声明） |
3895
- | `accept` | `string` | — | 否 | `accept=".png,.jpg,.pdf"` | — |
3896
- | `maxSize` | `number` | — | 否 | `:max-size="1"` | 单文件大小上限（MB） |
3897
- | `limit` | `number` | — | 否 | `:limit="1"` | — |
3898
- | `tip` | `string` | — | 否 | `tip="支持批量上传，单个文件不超过 10MB"` | — |
3899
- | `separator` | `string` | `';'` | 否 | `separator=","` | 多路径分隔符（modelValue 为字符串时） |
3900
- | `responseUrlKey` | `string` | `'meta'` | 否 | `response-url-key="url"` | 响应中文件地址的取值键 |
3901
- | `downloadButtonVisible` | `boolean` | `undefined` | 否 | `download-button-visible` | 是否展示「下载」按钮（默认 true） |
3902
- | `tipVisible` | `boolean` | `undefined` | 否 | `tip-visible` | 是否展示提示文案（默认 true） |
3903
- | `showDownloadButton` | `boolean` | `undefined` | 否 | `show-download-button` | — |
3904
- | `showTip` | `boolean` | `undefined` | 否 | `show-tip` | — |
3905
- | `verifySpace` | `boolean` | `false` | 否 | `verify-space` | 校验文件名不得含空格 |
3889
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3890
+ | ----------------------- | --------------------------------------------------------------- | ----------- | ---- | ----------------------------------------- | ----------------------------------------- |
3891
+ | `request` | `(form: FormData, config: Record<string, any>) => Promise<any>` | — | 否 | `:request="async () => {}"` | 自定义上传函数（form, config）→ Promise |
3892
+ | `modelValue` | `string \| any[]` | `''` | 否 | `v-model="value"` | 已上传文件路径或文件列表 |
3893
+ | `accept` | `string` | — | 否 | `accept=".png,.jpg,.pdf"` | 允许上传的文件格式 |
3894
+ | `maxSize` | `number` | — | 否 | `:max-size="1"` | 单文件大小上限（MB） |
3895
+ | `limit` | `number` | — | 否 | `:limit="1"` | 最多允许上传的文件数量 |
3896
+ | `tip` | `string` | — | 否 | `tip="支持批量上传，单个文件不超过 10MB"` | 上传区域下方的自定义提示 |
3897
+ | `separator` | `string` | `';'` | 否 | `separator=","` | 多路径分隔符（modelValue 为字符串时） |
3898
+ | `responseUrlKey` | `string` | `'meta'` | 否 | `response-url-key="url"` | 响应中文件地址的取值键 |
3899
+ | `downloadButtonVisible` | `boolean` | `undefined` | 否 | `download-button-visible` | 是否展示「下载」按钮（默认 true） |
3900
+ | `tipVisible` | `boolean` | `undefined` | 否 | `tip-visible` | 是否展示提示文案（默认 true） |
3901
+ | `showDownloadButton` | `boolean` | `undefined` | 否 | `show-download-button` | 已废弃，请用 `downloadButtonVisible` 代替 |
3902
+ | `showTip` | `boolean` | `undefined` | 否 | `show-tip` | 已废弃，请用 `tipVisible` 代替 |
3903
+ | `verifySpace` | `boolean` | `false` | 否 | `verify-space` | 校验文件名不得含空格 |
3906
3904
 
3907
3905
  **事件（emits）**
3908
3906
 
@@ -3912,9 +3910,9 @@ import { ZlUpload } from '@zl-ui-kit/components'
3912
3910
 
3913
3911
  **插槽（slots）**
3914
3912
 
3915
- | 插槽 | 作用域参数 | 示例 | 说明 |
3916
- | --------- | ---------- | --------------------------------- | ---- |
3917
- | `default` | — | `<template #default>…</template>` | — |
3913
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3914
+ | --------- | ---------- | --------------------------------- | -------------------- |
3915
+ | `default` | — | `<template #default>…</template>` | 自定义上传触发器内容 |
3918
3916
 
3919
3917
  **完整示例**：见 §6 数据型组件 + useRequest 体系（核心） › ⑥ ZlUpload —— 传上传 service
3920
3918
 
@@ -3960,15 +3958,15 @@ import { ZlTree } from '@zl-ui-kit/components'
3960
3958
  | `inputSearchProps` | `Record<string, any>` | — | 否 | `:input-search-props="{}"` | 搜索框透传（el-input 属性） |
3961
3959
  | `filterTreeNode` | `(value: string, data: any) => boolean` | — | 否 | `:filter-tree-node="() => {}"` | 自定义过滤函数（缺省按 title 包含匹配） |
3962
3960
  | `disableFilter` | `boolean` | — | 否 | `disable-filter` | 关闭搜索框 |
3963
- | `loading` | `boolean` | — | 否 | `loading` | — |
3961
+ | `loading` | `boolean` | — | 否 | `loading` | 是否显示树区域加载状态 |
3964
3962
 
3965
3963
  **插槽（slots）**
3966
3964
 
3967
- | 插槽 | 作用域参数 | 示例 | 说明 |
3968
- | -------------- | ------------------------------ | ------------------------------------------------ | ---------------------------- |
3969
- | `search-extra` | — | `<template #search-extra>…</template>` | — |
3970
- | `title` | `v-bind="{ node, data }"` 展开 | `<template #title="{ node, data }">…</template>` | — |
3971
- | `[slot]` | `v-bind="scope"` 展开 | `<template #[slot]="scope">…</template>` | 动态插槽：名字由该表达式决定 |
3965
+ | 插槽 | 作用域参数 | 示例 | 说明 |
3966
+ | -------------- | ------------------------------ | ------------------------------------------------ | -------------------------------------------- |
3967
+ | `search-extra` | — | `<template #search-extra>…</template>` | 搜索框右侧附加内容 |
3968
+ | `title` | `v-bind="{ node, data }"` 展开 | `<template #title="{ node, data }">…</template>` | 自定义节点标题，参数为 node 和 data |
3969
+ | `[slot]` | `v-bind="scope"` 展开 | `<template #[slot]="scope">…</template>` | 按自定义插槽列表生成名称，参数为树插槽上下文 |
3972
3970
 
3973
3971
  **完整示例**：见 §6 数据型组件 + useRequest 体系（核心） › ⑦ ZlTree —— useRequest 绑定 data
3974
3972
 
@@ -3996,11 +3994,11 @@ import { ZlTreeSelect } from '@zl-ui-kit/components'
3996
3994
 
3997
3995
  | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
3998
3996
  | ------------------- | ----------------------------------------------------- | -------------------------------------------------------------- | ---- | ------------------------ | ------------------------------------------------ |
3999
- | `modelValue` | `any` | — | 否 | `v-model="value"` | `v-model` 绑定的值（`defineModel` 隐式声明） |
3997
+ | `modelValue` | `any` | — | 否 | `v-model="value"` | 当前选中节点键值或标签值列表 |
4000
3998
  | `originTreeData` | `any[]` | — | 是 | `:origin-tree-data="[]"` | 树数据 |
4001
3999
  | `allName` | `string` | — | 否 | `all-name="全部"` | "全部"节点名（启用全选控制条） |
4002
4000
  | `labelInValue` | `boolean` | `false` | 否 | `label-in-value` | 返回 {label, value} 对象数组（缺省返回键值数组） |
4003
- | `fieldNames` | `{ key?: string; title?: string; children?: string }` | `() => ({ key: 'key', title: 'title', children: 'children' })` | 否 | `:field-names="{}"` | — |
4001
+ | `fieldNames` | `{ key?: string; title?: string; children?: string }` | `() => ({ key: 'key', title: 'title', children: 'children' })` | 否 | `:field-names="{}"` | 树节点键名、标题与子级字段映射 |
4004
4002
  | `treeCheckStrictly` | `boolean` | `false` | 否 | `tree-check-strictly` | 父子不关联 |
4005
4003
 
4006
4004
  > 把 `$attrs` 透传给 `el-tree-select`，未列出的属性会继续下传
@@ -4072,11 +4070,11 @@ import { ZlEditor } from '@zl-ui-kit/components/editor'
4072
4070
 
4073
4071
  **props**
4074
4072
 
4075
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4076
- | ------------ | --------------------- | -------------- | ---- | ----------------------- | -------------------------------------------- |
4077
- | `modelValue` | `string` | `''` | 否 | `v-model="value"` | `v-model` 绑定的值（`defineModel` 隐式声明） |
4078
- | `language` | `string` | `'javascript'` | 否 | `language="javascript"` | — |
4079
- | `options` | `Record<string, any>` | `() => ({})` | 否 | `:options="{}"` | — |
4073
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4074
+ | ------------ | --------------------- | -------------- | ---- | ----------------------- | ------------------------------------ |
4075
+ | `modelValue` | `string` | `''` | 否 | `v-model="value"` | 编辑器文本内容，v-model 双向同步 |
4076
+ | `language` | `string` | `'javascript'` | 否 | `language="javascript"` | 语法高亮所用语言 id，默认 javascript |
4077
+ | `options` | `Record<string, any>` | `() => ({})` | 否 | `:options="{}"` | monaco 编辑器配置，覆盖内置默认项 |
4080
4078
 
4081
4079
  **事件（emits）**
4082
4080
 
@@ -4106,12 +4104,12 @@ import { ZlSqlEditor } from '@zl-ui-kit/components/editor'
4106
4104
 
4107
4105
  **props**
4108
4106
 
4109
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4110
- | ----------------- | ------------------ | ---------- | ---- | ------------------------------- | -------------------------------------------- |
4111
- | `modelValue` | `string` | — | 否 | `v-model="value"` | `v-model` 绑定的值（`defineModel` 隐式声明） |
4112
- | `tableSchemas` | `SqlTableSchema[]` | `() => []` | 否 | `:table-schemas="tableSchemas"` | 表结构（补全提示） |
4113
- | `customKeywords` | `string[]` | `() => []` | 否 | `:custom-keywords="[]"` | — |
4114
- | `customFunctions` | `string[]` | `() => []` | 否 | `:custom-functions="[]"` | — |
4107
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4108
+ | ----------------- | ------------------ | ---------- | ---- | ------------------------------- | -------------------------------- |
4109
+ | `modelValue` | `string` | — | 否 | `v-model="value"` | SQL 文本内容，v-model 双向同步 |
4110
+ | `tableSchemas` | `SqlTableSchema[]` | `() => []` | 否 | `:table-schemas="tableSchemas"` | 表结构（补全提示） |
4111
+ | `customKeywords` | `string[]` | `() => []` | 否 | `:custom-keywords="[]"` | 追加到内置保留字表的自定义关键字 |
4112
+ | `customFunctions` | `string[]` | `() => []` | 否 | `:custom-functions="[]"` | 参与补全提示的自定义函数名 |
4115
4113
 
4116
4114
  > 把 `$attrs` 透传给 `ZlEditor`，未列出的属性会继续下传
4117
4115
 
@@ -4145,9 +4143,9 @@ import { ZlFilePreview } from '@zl-ui-kit/components/file-preview'
4145
4143
 
4146
4144
  **props**
4147
4145
 
4148
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4149
- | ----- | -------- | ------ | ---- | ------------------------------------ | ---- |
4150
- | `url` | `string` | — | 否 | `url="https://example.com/file.pdf"` | — |
4146
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4147
+ | ----- | -------- | ------ | ---- | ------------------------------------ | -------------------------------------- |
4148
+ | `url` | `string` | — | 否 | `url="https://example.com/file.pdf"` | 文件地址，变更后自动重新拉取并识别类型 |
4151
4149
 
4152
4150
  **完整示例**：见 §3 组件总览（47 个业务组件） › ZlFileFetchError —— 文件获取失败占位（供 ZlFilePreview 内部渲染）
4153
4151
 
@@ -4173,9 +4171,9 @@ import { ZlFileViewer } from '@zl-ui-kit/components/file-preview'
4173
4171
 
4174
4172
  **props**
4175
4173
 
4176
- | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4177
- | ---------- | ------------------------------------------------ | -------- | ---- | ------------------ | ---- |
4178
- | `fileType` | `'word' \| 'pdf' \| 'excel' \| 'ppt' \| 'image'` | `'word'` | 否 | `file-type="word"` | — |
4174
+ | 属性 | 类型 | 默认值 | 必填 | 示例 | 说明 |
4175
+ | ---------- | ------------------------------------------------ | -------- | ---- | ------------------ | ------------------------- |
4176
+ | `fileType` | `'word' \| 'pdf' \| 'excel' \| 'ppt' \| 'image'` | `'word'` | 否 | `file-type="word"` | 指定渲染器类型，默认 word |
4179
4177
 
4180
4178
  > 把 `$attrs` 透传给 `VueOfficePdf`，未列出的属性会继续下传
4181
4179