@zl-ui-kit/components 0.18.0 → 0.18.1

package/README.md

@@ -875,6 +875,36 @@ const { data } = useDataRequest(getChartDataApi, { dataKey: 'data' })
 
 内部用 `usePageableRequest` 驱动分页与查询；`columns` 为 `TableColumn[]`，`queryItems` 为 `SearchItem[]`。
 
+`queryItems` 与 `ZlForm` 的 `items` 是同一套 schema：基础查询项直接 `component` + `props` 配置（不用写模板），
+选项类控件用 EP 的 `options`，字段不是 `label`/`value` 时用 `props` 别名重映射，联动项用 `slot:true` + `#<model>` 接管：
+
+```ts
+const queryItems: SearchItem[] = [
+  {
+    model: 'keyword',
+    label: '名称',
+    component: 'el-input',
+    props: { placeholder: '请输入名称', clearable: true },
+  },
+  {
+    model: 'type',
+    label: '类型',
+    component: 'el-select',
+    props: {
+      options: [
+        { id: 'db', name: '数据库' },
+        { id: 'api', name: 'API' },
+      ],
+      props: { value: 'id', label: 'name' },
+      clearable: true,
+      style: 'width: 100%',
+    },
+    // 条件标签文案 / 查询入参可用 SearchItem 的 toLabel / toParams 转换
+    toLabel: (v) => (v === 'db' ? '数据库' : 'API'),
+  },
+]
+```
+
 #### ② `ZlCardPage` —— 直接传 service
 
 ```vue
@@ -886,6 +916,7 @@ const { data } = useDataRequest(getChartDataApi, { dataKey: 'data' })
 ```
 
 内部组合 `usePageableRequest + ZlSearch + ZlPagination + ZlEmpty`。
+搜索栏直接由 `queryItems: SearchItem[]` 驱动，写法与上面的 `ZlSearchTable` 完全一致（`component` + `props` 配置，选项类用 EP 的 `options`）。
 
 **条件查询 / 页签切换怎么重查**：把变化源放进 `request.options.refreshDeps`（ref / getter 数组），
 依赖变化会自动重查**并回到第 1 页**——卡片页的请求是 `manual` 的（首屏由 `ZlSearch` 触发），
@@ -1395,23 +1426,99 @@ function cardActions(data: any) {
 
 ### ZlForm —— schema 驱动
 
+基础表单项**不用写模板**：`component` 直接写 EP 组件名（`el-input` / `el-select` / `el-radio-group` …）或组件对象，
+`props` 原样透传给该控件，并自动包装 `update:modelValue` 回写 `model`（不必自己接 `v-model`）。
+
 ```ts
+const form = reactive<Record<string, any>>({})
+const contractOptions = ref([{ id: 'c1', name: '合约 A' }])
+const envOptions = ref([
+  { label: '生产', value: 'prod' },
+  { label: '测试', value: 'test' },
+])
+
 const items: FormItem[] = [
-  { model: 'name', label: '名称', component: 'el-input', props: { placeholder: '请输入' }, rules: [{ required: true }] },
-  { model: 'type', label: '类型', component: 'el-select', props: { options: [...] } },
+  // 选项类：用 EP 的 options；数据字段不是 label/value 时用 props 别名重映射（props 里嵌 props）
+  {
+    model: 'contractId',
+    label: '合约名称',
+    component: 'el-select',
+    props: {
+      options: contractOptions.value,
+      props: { value: 'id', label: 'name' },
+      clearable: true,
+      filterable: true,
+      style: 'width: 100%',
+    },
+    // rules 属于 el-form-item → 放 formItemProps，不要平铺在 item 上
+    formItemProps: { rules: [{ required: true, message: '请选择合约名称', trigger: 'change' }] },
+  },
+  // 动态禁用：在生成 schema 时算进 options（computed 随依赖变化重算整表）
+  {
+    model: 'env',
+    label: '计算环境',
+    component: 'el-radio-group',
+    props: { options: envOptions.value.map((i) => ({ ...i, disabled: i.disabled })) },
+  },
+  // 输入类：placeholder / maxlength / 多行（type/rows/showWordLimit）全走 props
+  {
+    model: 'name',
+    label: '任务名称',
+    component: 'el-input',
+    props: { placeholder: '请输入', maxlength: 30 },
+  },
   { model: 'enable', label: '启用', component: 'ZlSwitch' },
+  // 联动 / 复合控件（多选表格、树选择）不硬塞 props，用 slot:true + #<model> 插槽整块接管
+  { model: 'productIds', label: '数据产品', slot: true },
 ]
 ```
 
 ```vue
-<ZlForm :model="form" :items="items" label-width="auto" />
+<ZlForm :model="form" :items="items" label-width="auto">
+  <template #productIds="{ model }">…</template>
+</ZlForm>
 ```
 
-`FormItem` 关键字段：`model`(必填) / `label` / `component`(组件名或组件) / `props`(自动包装 `update:modelValue` 回写) / `slots` / `rules` / `defaultValue` / `visible`(布尔或函数) / `tooltip`(label 后帮助图标 + tooltip)。
+`FormItem` 关键字段：`model`(必填) / `label` / `component`(组件名或组件) / `props`(控件入参，自动包装 `update:modelValue` 回写) /
+`slots`(控件插槽) / `formItemProps`(`el-form-item` 属性，如 `rules`) / `defaultValue` / `visible`(布尔或函数) / `tooltip`(label 后帮助图标) / `slot`(启用 `#<model>` 插槽)。
+
+> `rules` 必须写在 `formItemProps` 里：item 上除上述字段外的键会被当作**控件 props** 透传给控件，写错不会报错、但校验不生效。
 
 ### ZlSearch —— 查询条
 
-见 6.3 ④。`items: SearchItem[]`，`SearchItem` 继承 `FormItem` 并扩展 `toLabel`(值→条件标签) 与 `toParams`(值→查询参数合并)。
+`items: SearchItem[]`，与 `ZlForm` 的 `items` **同一套 schema**：基础查询项直接 `component` + `props` 配置（不用写模板），
+选项类用 EP 的 `options`（字段不是 `label`/`value` 时用 `props` 别名重映射），联动 / 复合项用 `slot:true` + `#<model>` 插槽接管。
+`SearchItem` 在 `FormItem` 之上扩展了 `toLabel`(值→条件标签文案) 与 `toParams`(值→查询参数合并)。
+
+```ts
+const items: SearchItem[] = [
+  {
+    model: 'keyword',
+    label: '名称',
+    component: 'el-input',
+    props: { placeholder: '请输入名称', clearable: true },
+  },
+  {
+    model: 'type',
+    label: '类型',
+    component: 'el-select',
+    props: {
+      options: [
+        { id: 'db', name: '数据库' },
+        { id: 'api', name: 'API' },
+      ],
+      props: { value: 'id', label: 'name' },
+      clearable: true,
+      style: 'width: 100%',
+    },
+    toLabel: (v) => (v === 'db' ? '数据库' : 'API'),
+  },
+]
+```
+
+```vue
+<ZlSearch :items="items" @search="onSearch" />
+```
 
 **自适应溢出**（`useSearchFormOverflow`，移植自源组件逻辑，非按项数猜）：
 
@@ -4142,11 +4249,11 @@ import { ZlCardPage } from '@zl-ui-kit/components'
 </script>
 
 <template>
-  <ZlCardPage :request="mockPageRequest" card-min-width="200px" />
+  <ZlCardPage :request="mockPageRequest" card-min-width="200px" :query-items="queryItems" />
 </template>
 ```
 
-> 示例中的 `request` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
+> 示例中的 `request`、`queryItems` 是数组 / 对象 / 函数等非字面量入参，由调用方提供数据；其余属性写法可直接照搬。
 
 **插槽用法**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zl-ui-kit/components",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "type": "module",
   "description": "ZL UI 业务组件库（Element Plus 体系，Zl 前缀）——首批：Icon/AutoTooltip/Tag/CornerTag/Text/Title/Copy/Empty/Pagination/DictTag",
   "license": "MIT",
@@ -39,9 +39,9 @@
     "file-type": "^20.4.1",
     "dt-sql-parser": "^4.3.1",
     "sql-formatter": "^15.4.2",
-    "@zl-ui-kit/composables": "0.18.0",
-    "@zl-ui-kit/utils": "0.18.0",
-    "@zl-ui-kit/icons": "0.18.0"
+    "@zl-ui-kit/composables": "0.18.1",
+    "@zl-ui-kit/icons": "0.18.1",
+    "@zl-ui-kit/utils": "0.18.1"
   },
   "peerDependencies": {
     "@vueuse/core": "^12.3.0 || ^13.0.0 || ^14.0.0 || ^15.0.0",
@@ -98,10 +98,10 @@
     "@vue-office/pdf": "^2.0.10",
     "@vue-office/pptx": "1.0.1",
     "echarts": "^5.6.0",
-    "@zl-ui-kit/theme": "0.18.0",
-    "@jichuang/eslint-config": "1.0.0",
     "@jichuang/tsconfig": "1.0.0",
-    "@jichuang/vite-config": "1.0.0"
+    "@jichuang/eslint-config": "1.0.0",
+    "@jichuang/vite-config": "1.0.0",
+    "@zl-ui-kit/theme": "0.18.1"
   },
   "repository": {
     "type": "git",