@aspire-ui/element-component-pro 1.0.26 → 1.0.27

package/docs/ProTableForm.md

@@ -0,0 +1,207 @@
+# ProTableForm 对比表表单
+
+用于在统一指标列下录入多个行信息，支持**内置组件**（input / 千分位数字 / select / switch 等）、**列级插槽**与**操作列完全由外部实现**。
+
+## 数据模型（v-model）
+
+`modelValue` 直接为数组：
+
+```ts
+[
+  { [col.key]: ..., [col.key]: ... },
+  { [col.key]: ..., [col.key]: ... },
+]
+```
+
+## 列配置 `columns`
+
+`columns` 为 `ProTableFormColumn[]` 类型，支持多级表头（通过 `children` 嵌套）。
+
+### `ProTableFormColumn` 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `key` | `string` | 字段名，对应 model 中对象字段名 |
+| `title` | `string` | 表头文字 |
+| `required` | `boolean` | 是否必填（自动生成必填规则） |
+| `component` | `ProTableFormBuiltInComponent` | 单元格渲染方式，见下方内置组件列表 |
+| `componentProps` | `Record<string, unknown>` | 透传给单元格组件的配置参数 |
+| `slotName` | `string` | `component === 'slot'` 时必填，对应父组件插槽 **`#cell-{slotName}`** |
+| `render` | `ProTableFormColumnRender` | 自定义渲染函数，返回 string（文本展示，参与校验）或 VNode（自定义组件，直接渲染） |
+| `rules` | `unknown[]` | 覆盖该列默认必填规则（Element 表单 rules） |
+| `minWidth` / `width` | `number` | 列宽 |
+| `align` | `'left' \| 'center' \| 'right'` | 单元格对齐 |
+| `headerAlign` | `'left' \| 'center' \| 'right'` | 表头对齐 |
+| `fixed` | `boolean \| 'left' \| 'right'` | 固定列 |
+| `cellStyle` | `Record<string, string \| number>` | 单元格样式 |
+| `headerCellStyle` | `Record<string, string \| number>` | 表头单元格样式 |
+| `cellClassName` | `string` | 单元格 className |
+| `headerCellClassName` | `string` | 表头单元格 className |
+| `sortable` | `boolean` | 是否可排序 |
+| `resizable` | `boolean` | 是否可拖拽调整宽度（默认 true） |
+| `hideInTable` | `boolean` | 是否隐藏该列 |
+| `children` | `ProTableFormColumn[]` | 多级表头子列 |
+
+### `ProTableFormBuiltInComponent` 内置组件类型
+
+| component 值 | 渲染组件 | 特殊说明 |
+|---|---|---|
+| `input` | `el-input` | 默认，可不写 |
+| `input-number` | `el-input-number` | - |
+| `formatted-number` | `FormattedNumberInput` | 千分位数字，默认整数位 5、小数位 6、舍入 round、inputLimit true；可通过 `componentProps` 覆盖 |
+| `select` | `el-select` | `componentProps.options` 传入选项数组 `Array<{ label, value }>` |
+| `checkbox` | `el-checkbox-group` | `componentProps.options` 传入选项数组，多选 |
+| `radio` | `el-radio-group` | `componentProps.options` 传入选项数组，单选 |
+| `date-picker` | `el-date-picker` | - |
+| `date-range` | `el-date-picker[type=range]` | 默认 format `yyyy-MM-dd`，默认占位符「开始日期」/「结束日期」 |
+| `switch` | `el-switch` | - |
+| `cascader` | `el-cascader` | `componentProps.options` 传入树形选项数组 |
+| `api-select` | `ApiSelect` | 远程 API 加载选项，`componentProps` 支持 `api`、`labelField`、`valueField` |
+| `tree-select` | `TreeSelect` | 树形下拉，`componentProps` 支持 `data`、`props` |
+| `slot` | 自定义插槽 | 配合 `slotName`，通过 `#cell-{slotName}` 插槽完全自定义单元格内容 |
+
+> `select` / `checkbox` / `radio` 的选项统一通过 `componentProps.options` 传入：
+> ```ts
+> componentProps: {
+>   options: [
+>     { label: '启用', value: 1 },
+>     { label: '禁用', value: 0 },
+>   ],
+> }
+> ```
+
+## 表头插槽（按列）
+
+- **`#header-{column.key}`**：自定义某一列表头，作用域参数 `{ column }`。
+- 不传则使用默认标题与必填星号。
+
+## 自定义单元格插槽（`component: 'slot'`）
+
+插槽名：**`cell-{slotName}`**
+
+作用域参数：
+
+| 属性 | 说明 |
+|------|------|
+| `column` | 当前列配置 |
+| `row` | 当前行（`_index: number`） |
+| `index` | 行索引 |
+| `value` | 当前单元格值 |
+| `updateValue` | `(v: unknown) => void` 写回表单 |
+
+## 操作列
+
+操作列完全由外部通过 **`#action`** 作用域插槽实现，ProTableForm 不内置任何操作列 UI。
+
+作用域参数：
+
+| 属性 | 说明 |
+|------|------|
+| `addRow` | 新增一行 |
+| `removeRow` | 删除指定行，签名 `(index: number) => void` |
+
+```vue
+<ProTableForm>
+  <template #action="{ addRow, removeRow }">
+    <el-table-column width="120" fixed="right" align="center">
+      <template #header>
+        <el-button type="text" @click="addRow">+新增</el-button>
+      </template>
+      <template #default="slotProps">
+        <el-button type="text" size="small" @click="removeRow(slotProps.$index)">删除</el-button>
+      </template>
+    </el-table-column>
+  </template>
+</ProTableForm>
+```
+
+## 校验规则
+
+ProTableForm 复用 `el-form` 的校验体系，支持三种配置方式，优先级：**列级 `rules` > 列级 `required` > 全局 `rules` > 表单级 rules**。
+
+### 三种配置方式
+
+**方式一：`required: true`（最常用）**
+
+自动生成必填规则，无需手动编写：
+
+```ts
+{ key: 'name', title: '名称', required: true }
+```
+
+**方式二：列级 `rules`（覆盖 `required` 默认规则）**
+
+传入 Element UI 标准 rules 数组，支持正则、数值范围、自定义 validator 等：
+
+```ts
+{
+  key: 'email',
+  title: '邮箱',
+  required: true,
+  rules: [
+    { required: true, message: '请输入邮箱' },
+    { pattern: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/, message: '邮箱格式不正确' },
+  ],
+}
+```
+
+```ts
+// 数值范围示例
+{
+  key: 'price',
+  title: '价格',
+  component: 'input-number',
+  rules: [
+    { required: true, message: '请输入价格' },
+    { type: 'number', min: 0, message: '价格不能为负数' },
+  ],
+}
+```
+
+**方式三：全局 `rules`（统一规则，适用于所有同名 key）**
+
+```ts
+<ProTableForm
+  :columns="columns"
+  :rules="{
+    inputNumber: [{ type: 'number', min: 0, message: '数量不能为负数' }],
+  }"
+/>
+```
+
+## 组件实例 `defineExpose`
+
+| 方法/属性 | 说明 |
+|------|------|
+| `validate()` | 表单校验，返回 Promise\<boolean\> |
+| `clearValidate(props?)` | 清除校验 |
+| `addRow()` | 新增一行 |
+| `removeRow(index)` | 删除指定行 |
+| `getRows()` | 获取行数组 |
+| `getRowCount()` | 获取行数 |
+| `getTable()` | 获取 el-table 实例 |
+| `getModelValue()` | 获取整个 modelValue |
+| `setModelValue(val)` | 设置整个 modelValue |
+| `getFormRef()` | 获取 el-form 实例 |
+
+## 其它 Props
+
+- **rules**：合并进 `el-form` 的全局规则。
+- **metricPlaceholder**：指标列（默认 `input`）的 placeholder，默认 `"请输入"`
+- **minRows**：最少行数，初始化时自动补足
+- **bordered**：是否显示边框，默认 `true`
+- **stripe**：是否斑马纹，默认 `false`
+- **size**：单元格尺寸，默认 `medium`
+
+## 示例
+
+| 示例 | 说明 |
+|------|------|
+| `examples/pages/ProTableFormPage/Basic.vue` | 基础用法 + 自定义操作列 |
+| `examples/pages/ProTableFormPage/BuiltInComponents.vue` | 全部 12 种内置组件一览 |
+| `examples/pages/ProTableFormPage/Rules.vue` | 三种校验规则配置方式 |
+| `examples/pages/ProTableFormPage/MultiHeader.vue` | 多级表头（children 嵌套） |
+| `examples/pages/ProTableFormPage/MixedData.vue` | 混用：展示列（render） + 可编辑列 |
+| `examples/pages/ProTableFormPage/Combo.vue` | 与 `el-form` 组合提交分段校验 |
+
+示例站：`/protable?tab=basic`、`/protable?tab=builtIn`、`/protable?tab=rules`、`/protable?tab=multiHeader`、`/protable?tab=mixed`、`/protable?tab=combo`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspire-ui/element-component-pro",
-  "version": "1.0.26",
+  "version": "1.0.27",
   "description": "Element UI 二次封装组件库，基于 Vue 2.7 + TypeScript + setup 语法糖，实现 VbenAdmin 风格的 Pro 组件",
   "type": "module",
   "main": "./dist/element-component-pro.umd.js",
@@ -16,7 +16,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs"
   ],
   "scripts": {
     "dev": "vite",

package/src/CollapseContainer/CollapseContainer.vue

@@ -173,7 +173,7 @@ defineExpose({
 })
 </script>
 
-<style scoped>
+<style>
 .ecp-collapse-container {
   background: #fff;
   border-radius: 14px;

package/src/ProDescriptions/ProDescriptions.vue

@@ -333,7 +333,7 @@ watch(() => effectiveProps.value.collapseOptions?.defaultExpand, (value) => {
 })
 </script>
 
-<style scoped>
+<style>
 .ecp-pro-descriptions {
   width: 100%;
   box-sizing: border-box;

package/src/ProForm/FormActions.vue

@@ -58,7 +58,7 @@ defineEmits<{
 }>()
 </script>
 
-<style scoped>
+<style>
 /* .ecp-form-actions {
 } */
 .ecp-form-actions {

package/src/ProForm/ProForm.vue

@@ -494,7 +494,7 @@ watch(() => controlledModelValue.value, (value) => {
 watch(() => [props.schemas, props.initialValues], syncSchemas, { deep: true })
 </script>
 
-<style scoped>
+<style>
 .ecp-pro-form {
   padding: 16px;
   position: relative;

package/src/ProForm/ProFormItem.vue

@@ -331,7 +331,7 @@ const renderComponent = computed(() => {
 })
 </script>
 
-<style scoped>
+<style>
 .ecp-pro-form-item__colon {
   margin-right: 2px;
 }

package/src/ProForm/TreeSelect.vue

@@ -241,7 +241,7 @@ watch(() => props.params, () => {
 }, { deep: true })
 </script>
 
-<style scoped>
+<style>
 .ecp-tree-select {
   position: relative;
   width: 100%;

package/src/ProTable/ProTable.vue

@@ -706,7 +706,7 @@ watch(() => props.dataSource, () => {
 watch(() => props.loading, (v) => { loading.value = v ?? false })
 </script>
 
-<style scoped>
+<style>
 .ecp-pro-table {
   padding: 16px;
   background: #fff;

package/src/ProTable/TableAction.vue

@@ -175,7 +175,7 @@ const handleDropdownCommand = (index: number | string) => {
 }
 </script>
 
-<style scoped>
+<style>
 .ecp-table-action {
   display: inline-flex;
   align-items: center;

package/src/ProTableForm/CellEditor.vue

@@ -5,7 +5,7 @@
     :value="value"
     v-bind="cellBind"
     :placeholder="placeholder"
-    v-on="mergedEvents('change')"
+    v-on="mergedEvents('change', 'clear')"
   >
     <el-option
       v-for="opt in options"
@@ -85,7 +85,7 @@ import { computed } from 'vue'
 import ApiSelect from '../ProForm/ApiSelect.vue'
 import TreeSelect from '../ProForm/TreeSelect.vue'
 import FormattedNumberInput from '../ProForm/FormattedNumberInput.vue'
-import type { ProTableFormColumn, ProTableFormColumnChild } from '../types'
+import type { ProTableFormColumn, ProTableFormColumnChild, ProTableFormActionType } from '../types'
 
 const props = defineProps<{
   col: ProTableFormColumn | ProTableFormColumnChild
@@ -94,6 +94,8 @@ const props = defineProps<{
   row?: Record<string, unknown>
   size?: 'medium' | 'small' | 'large'
   placeholder?: string
+  /** ProTableForm 操作实例 */
+  action?: ProTableFormActionType
 }>()
 
 const emit = defineEmits<{ (e: 'update', v: unknown): void }>()
@@ -124,7 +126,7 @@ const cellBind = computed<Record<string, unknown>>(() => {
 
   const cp = props.col.componentProps
   if (typeof cp === 'function') {
-    dynamicProps = cp({ row: props.row ?? {}, value: props.value, column: props.col as any })
+    dynamicProps = cp({ row: props.row ?? {}, value: props.value, column: props.col as any, action: props.action as any })
   } else {
     staticProps = cp ?? {}
   }
@@ -156,7 +158,7 @@ const cellEvents = computed<Record<string, (...args: unknown[]) => unknown>>(()
 
   const cp = props.col.componentProps
   if (typeof cp === 'function') {
-    dynamicProps = cp({ row: props.row ?? {}, value: props.value, column: props.col as any })
+    dynamicProps = cp({ row: props.row ?? {}, value: props.value, column: props.col as any, action: props.action as any })
   } else {
     staticProps = cp ?? {}
   }
@@ -174,15 +176,17 @@ const cellEvents = computed<Record<string, (...args: unknown[]) => unknown>>(()
 /**
  * Merges cellEvents (from componentProps) with the internal emit bridge.
  * componentProps listeners fire first, then emit('update') updates the row value.
+ * clear 事件特殊处理：用户 handler 先执行，再 emit(undefined) 清空值。
  */
-const mergedEvents = (internalEvent: 'input' | 'change') => {
-  const userHandler = cellEvents.value[internalEvent]
-  return {
-    ...cellEvents.value,
-    [internalEvent]: (arg: unknown) => {
+const mergedEvents = (...internalEvents: Array<'input' | 'change' | 'clear'>) => {
+  const handlers: Record<string, (...args: unknown[]) => void> = {}
+  for (const internalEvent of internalEvents) {
+    const userHandler = cellEvents.value[internalEvent]
+    handlers[internalEvent] = (arg: unknown) => {
       if (userHandler) userHandler(arg)
-      emit('update', arg)
-    },
+      emit('update', internalEvent === 'clear' ? undefined : arg)
+    }
   }
+  return handlers
 }
 </script>

package/src/ProTableForm/ProTableForm.vue

@@ -4,7 +4,6 @@
       ref="formRef"
       :model="formModelRef"
       :rules="mergedRules"
-      :validate-on-rule-change="false"
       :label-width="labelWidth"
       :size="formSize"
       :label-position="labelPosition"
@@ -127,6 +126,7 @@
                       :row="slotProps.row"
                       :size="size"
                       :placeholder="col.placeholder || metricPlaceholder"
+                      :action="action"
                       @update="setCellValue(slotProps.row, col, child.key, $event)"
                     />
                   </el-form-item>
@@ -205,6 +205,7 @@
                   :row="slotProps.row"
                   :size="size"
                   :placeholder="col.placeholder || metricPlaceholder"
+                  :action="action"
                   @update="setCellValue(slotProps.row, col, undefined, $event)"
                 />
               </el-form-item>
@@ -417,7 +418,7 @@ defineExpose(action)
 emit('register', action)
 </script>
 
-<style scoped>
+<style>
 .ecp-pro-table-form__form :deep(.el-form-item) {
   margin-bottom: 0;
 }

package/src/types/index.ts

@@ -347,11 +347,12 @@ export interface ProTableFormColumn {
    * `integerDigits`、`decimalPlaces`、`rounding`、`inputLimit` 等（与 FormattedNumberInput 一致）。
    * 支持函数形式，参数为 { row, value, column }，返回要合并到组件上的属性。
    */
-  componentProps?: Record<string, unknown> | ((params: {
-    row: Record<string, unknown>
-    value: unknown
-    column: ProTableFormColumn
-  }) => Record<string, unknown>)
+  /**
+   * 透传给单元格组件。`component === 'formatted-number'` 时在此传入
+   * `integerDigits`、`decimalPlaces`、`rounding`、`inputLimit` 等。
+   * 支持函数形式，参数为 { row, value, column, action }，返回要合并到组件上的属性。
+   */
+  componentProps?: Record<string, unknown> | ((params: CellComponentPropsParams) => Record<string, unknown>)
   /** 动态校验规则 */
   dynamicRules?: unknown[] | ((params: {
     row: Record<string, unknown>
@@ -406,13 +407,9 @@ export interface ProTableFormColumnChild {
   /**
    * 透传给单元格组件。`component === 'formatted-number'` 时在此传入
    * `integerDigits`、`decimalPlaces`、`rounding`、`inputLimit` 等。
-   * 支持函数形式，参数为 { row, value, column }，返回要合并到组件上的属性。
+   * 支持函数形式，参数为 { row, value, column, action }，返回要合并到组件上的属性。
    */
-  componentProps?: Record<string, unknown> | ((params: {
-    row: Record<string, unknown>
-    value: unknown
-    column: ProTableFormColumnChild
-  }) => Record<string, unknown>)
+  componentProps?: Record<string, unknown> | ((params: CellComponentPropsParams) => Record<string, unknown>)
   rules?: unknown[]
   /** 动态校验规则 */
   dynamicRules?: unknown[] | ((params: {
@@ -520,3 +517,12 @@ export interface ProTableFormActionType {
   getFormRef: () => FormInstance | null
 }
 
+/** componentProps 函数的参数类型 */
+export interface CellComponentPropsParams {
+  row: Record<string, unknown>
+  value: unknown
+  column: ProTableFormColumn | ProTableFormColumnChild
+  /** ProTableForm 操作实例，可调用 validate、addRow、removeRow 等 */
+  action: ProTableFormActionType
+}
+