el-plus 0.0.84 → 0.0.86-beta.0

package/docs/components/form.md

@@ -0,0 +1,186 @@
+# EpForm 表单容器
+
+基于 el-form 封装，支持通过配置生成表单。
+
+## 基本用法
+
+```vue
+<template>
+  <EpForm
+    ref="epForm"
+    v-model="formData"
+    :formItemList="formItemList"
+  />
+</template>
+
+<script setup lang="tsx">
+import { reactive, ref, useTemplateRef } from 'vue'
+import type { FormProps } from 'el-plus'
+
+const epForm = useTemplateRef('epForm')
+const formData = reactive({
+  name: '',
+  type: '',
+})
+
+const formItemList = ref<FormProps['formItemList']>([
+  {
+    prop: 'name',
+    label: '名称',
+  },
+  {
+    prop: 'type',
+    label: '类型',
+    type: 'EpSelect',
+    props: {
+      options: [
+        { label: '类型1', value: '1' },
+        { label: '类型2', value: '2' },
+      ],
+    },
+  },
+])
+</script>
+```
+
+## Props
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| v-model | 表单数据 | `Record<string, any>` | `{}` |
+| formItemList | 表单项配置 | [`FormItemProps[]`](#formitemprops-配置) | `[]` |
+| col | 每行列数 | `number` | `4` |
+| isShowFold | 是否显示折叠 | `boolean` | `false` |
+| showFieldCount | 折叠时显示数量 | `number` | `8` |
+| labelWidth | 标签宽度 ^el^ | `string \| number` | `100` |
+| labelPosition | 标签位置 ^el^ | `'left' \| 'right' \| 'top'` | - |
+| size | 表单尺寸 ^el^ | `'large' \| 'default' \| 'small'` | `'small'` |
+| scrollIntoViewOptions | 滚动到错误项配置 ^el^ | `object` | `{ inline: 'center' }` |
+
+> ^el^ 表示继承自 [el-form](https://element-plus.org/zh-CN/component/form.html) 的属性
+
+## FormItemProps 配置
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| type | 组件类型 | `string` | `'EpInput'` |
+| prop | 字段名 | `string` | - |
+| label | 标签文本 | `string` | - |
+| col | 占用列数 | `number` | - |
+| disabled | 是否禁用 | `boolean` | `false` |
+| visible | 是否显示 | `boolean` | `true` |
+| required | 是否必填 | `boolean` | `false` |
+| rules | 校验规则 | `FormItemRule[]` | - |
+| props | 传递给组件的属性 | `object` | - |
+| render | 自定义渲染 | `() => VNode` | - |
+| labelRender | 自定义标签渲染 | `({ label }) => VNode` | - |
+| isShowLabel | 是否显示标签 | `boolean` | `true` |
+| class | 样式类名 | `string` | - |
+| style | 行内样式 | `string \| CSSProperties` | - |
+| onChange | 值变化事件 | `(val, item?) => void` | - |
+
+> **注意**：在 EpTable 的 columns 中使用表单项时，`type` 不能省略，否则会显示为普通文本。
+> ```json
+> // ❌ 错误：表格列中省略 type，会显示为文本
+> { "prop": "quantity", "label": "数量" }
+> // ✅ 正确：表格列中必须指定 type
+> { "prop": "quantity", "label": "数量", "type": "EpInput" }
+> ```
+
+## Expose 方法
+
+| 方法 | 说明 | 类型 |
+|------|------|------|
+| validate | 表单验证 | `() => Promise<boolean>` |
+| resetFields | 重置表单 | `() => void` |
+| clearValidate | 清除验证 | `(props?: string[]) => void` |
+| getFormItemRenderRef | 获取表单项组件 ref | `(ref: string) => any` |
+
+## 组件自由组合示例
+
+在 formItemList 中可自由组合其他组件：
+- type：组件名字，优先使用 Ep 前缀的组件，如 EpInput、EpSelect 等，其次使用 Element Plus 的组件，如 ElInput、ElSelect 等。
+- 外层: EpFormItem的属性
+- props：传递给组件的属性
+- 事件：组件的事件，以 `on` 开头，如 onClick、onChange 等
+
+
+```tsx
+const formItemList = computed<FormProps['formItemList']>(() => [
+  // 标题分组
+  {
+    col: 24,
+    type: 'EpTitle',
+    props: {
+      title: '基本信息',
+    },
+  },
+  // 输入框
+  {
+    prop: 'name',
+    label: '名称',
+  },
+  // 下拉选择
+  {
+    prop: 'type',
+    label: '类型',
+    type: 'EpSelect',
+    props: {
+      options: [],
+    },
+  },
+  // 日期范围
+  {
+    prop: 'orderDate',
+    label: '日期范围',
+    type: 'EpDatePickerRange',
+    props: {
+      start: formData.orderDateStart,
+      end: formData.orderDateEnd,
+    },
+    'onUpdate:start': (val) => {
+      formData.orderDateStart = val
+    },
+    'onUpdate:end': (val) => {
+      formData.orderDateEnd = val
+    },
+  },
+  // 表格嵌套
+  {
+    col: 24,
+    type: 'EpTable',
+    props: {
+      ref: 'detailTable',
+      data: formData.detailList,
+      columns: [],
+    },
+  },
+  // 附件
+  {
+    col: 24,
+    type: 'EpAttachment',
+    props: {
+      modelValue: formData.fileList,
+    },
+  },
+])
+```
+
+## 验证示例
+
+```ts
+const handleSave = async () => {
+  const valid = await epForm.value?.validate()
+  if (valid) {
+    // 验证通过，提交数据
+  }
+}
+```
+
+## 获取嵌套组件 ref
+
+```ts
+// 获取 formItemList 中 props.ref='detailTable' 的组件
+const table = epForm.value?.getFormItemRenderRef('detailTable')
+const rows = table?.getSelectionRows()
+```

package/docs/components/header.md

@@ -0,0 +1,89 @@
+# EpHeader 顶部操作栏
+
+详情页顶部操作栏组件，支持返回、按钮组、附件等功能。
+
+## 基本用法
+
+```vue
+<template>
+  <EpHeader
+    :buttons="headerButtons"
+    is-show-attachment-button
+    :file-list="formData.fileList"
+  />
+</template>
+
+<script setup lang="tsx">
+import type { HeaderProps } from 'el-plus'
+
+// 只放非内置的自定义按钮
+const headerButtons: HeaderProps['buttons'] = [
+  { name: '提交审批', onClick: () => {} },
+  { name: '取消审批', onClick: () => {} },
+  { name: '作废',  onClick: () => {} },
+]
+</script>
+```
+
+## Props
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| buttons | 自定义按钮列表 | [`ButtonProps[]`](./buttons.md#buttonprops-配置) | `[]` |
+| defaultButtons | 显示的默认按钮 | `('edit' \| 'save' \| 'cancel' \| 'refresh' \| 'auditLog')[]` | `['edit', 'save', 'cancel', 'refresh', 'auditLog']` |
+| mode | 页面模式 | `'add' \| 'edit' \| 'browse'` | - |
+| allowBack | 是否允许返回 | `boolean` | `true` |
+| name | 权限前缀 | `string` | - |
+| workflowId | 工作流ID，有值则显示审批日志按钮 | `string` | - |
+| isShowAttachmentButton | 显示附件按钮 | `boolean` | `false` |
+| fileList | 附件列表 | `Record<string, any>[]` | `[]` |
+| attachmentProps | 附件组件属性 | [`AttachmentProps`](./attachment.md#props) | `{}` |
+
+> **注意**：`defaultButtons` 默认为全部按钮，无需显式设置。只有需要自定义显示的按钮时才需设置。
+> ```json
+> // ❌ 错误：无需设置默认值属性
+> { "type": "EpHeader", "props": { "defaultButtons": ["edit", "save", "cancel", "refresh", "auditLog"] } }
+> // ✅ 正确：使用默认值
+> { "type": "EpHeader" }
+> // ✅ 正确：自定义显示的按钮
+> { "type": "EpHeader", "props": { "defaultButtons": ["edit", "save"] } }
+> ```
+
+## 默认按钮说明
+
+| 按钮 | 说明 |
+|------|------|
+| edit | 编辑按钮 |
+| save | 保存按钮 |
+| cancel | 取消按钮 |
+| refresh | 刷新按钮 |
+| auditLog | 审批日志按钮 |
+
+## 带附件按钮
+
+```vue
+<template>
+  <EpHeader
+    :buttons="headerButtons"
+    is-show-attachment-button
+    :file-list="formData.fileList"
+    :attachment-props="attachmentProps"
+  />
+</template>
+
+<script setup>
+const attachmentProps = {
+  formatColumns: [
+    {
+      prop: 'type',
+      props: {
+        options: [
+          { label: '图片', value: 0 },
+          { label: '附件', value: 2 },
+        ],
+      },
+    },
+  ],
+}
+</script>
+```

package/docs/components/index.md

@@ -0,0 +1,23 @@
+# 组件文档索引
+
+所有组件可自由组合到 Form 中，配置时请参考各组件文档：
+
+| 组件 | 文档 | 说明 |
+|------|------|------|
+| EpSearchListPage | [search-list-page.md](./search-list-page.md) | 搜索列表页容器 |
+| EpForm | [form.md](./form.md) | 表单容器 |
+| EpHeader | [header.md](./header.md) | 顶部操作栏 |
+| EpTitle | [title.md](./title.md) | 标题分组 |
+| EpDialog | [dialog.md](./dialog.md) | 对话框 |
+| useFormDialog | [use-form-dialog.md](./use-form-dialog.md) | 表单对话框 Hook |
+| useConfirmDialog | [use-confirm-dialog.md](./use-confirm-dialog.md) | 确认对话框 Hook |
+| useChooseDialog | [use-choose-dialog.md](./use-choose-dialog.md) | 选择对话框 Hook |
+| EpInput | [input.md](./input.md) | 输入框 |
+| EpSelect | [select.md](./select.md) | 下拉选择 |
+| EpDatePickerRange | [date-picker-range.md](./date-picker-range.md) | 日期范围选择 |
+| EpTable | [table.md](./table.md) | 数据表格 |
+| EpCustomColumn | [custom-column.md](./custom-column.md) | 自定义列配置 |
+| EpLink | [link.md](./link.md) | 链接 |
+| EpButtons | [buttons.md](./buttons.md) | 按钮组 |
+| EpAttachment | [attachment.md](./attachment.md) | 附件管理 |
+| EpFooterInfo | [footer-info.md](./footer-info.md) | 底部信息 |

package/docs/components/input.md

@@ -0,0 +1,109 @@
+# EpInput 输入框
+
+基于 el-input 封装，增加数字格式化等功能。
+
+## 基本用法
+
+```vue
+<template>
+  <EpInput v-model="value" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const value = ref('')
+</script>
+```
+
+## Props
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| v-model | 绑定值 ^el^ | `string \| number` | - |
+| placeholder | 占位文本 ^el^ | `string` | '请输入' |
+| clearable | 是否可清空 ^el^ | `boolean` | `true` |
+| max | 最大值（数字模式） | `number` | - |
+| min | 最小值（数字模式） | `number` | - |
+| radix | 小数位数 | `number` | - |
+| nonzero | 不允许为零 | `boolean` | `false` |
+| thousand | 千分位格式化 | `boolean` | `true` |
+
+> ^el^ 表示继承自 [el-input](https://element-plus.org/zh-CN/component/input.html) 的属性
+
+> **注意**：
+> - `clearable` 默认为 `true`，无需显式设置。只有需要 `clearable: false` 时才需设置。
+> - `thousand` 默认为 `true`，无需显式设置。
+> - 数值相关属性（`max`、`min`、`radix`、`nonzero`）默认不设置，只有明确需要时才添加。
+> ```json
+> // ❌ 错误：无需设置默认值属性
+> { "prop": "name", "type": "EpInput", "props": { "clearable": true } }
+> // ✅ 正确：使用默认值
+> { "prop": "name" }
+> // ❌ 错误：数值文本框默认不加数字属性
+> { "prop": "amount", "label": "金额", "props": { "thousand": true } }
+> // ✅ 正确：数值文本框无需设置默认值属性
+> { "prop": "amount", "label": "金额" }
+> // ✅ 正确：有特殊需求时才设置
+> { "prop": "amount", "label": "金额", "props": { "radix": 2, "max": 999999 } }
+> ```
+
+## 在 Form 中使用
+
+```tsx
+const formItemList = [
+  {
+    prop: 'name',
+    label: '名称',
+    // type 默认为 EpInput
+  },
+  {
+    prop: 'number',
+    label: '数字',
+    // type 默认为 EpInput
+  },
+  {
+    prop: 'remark',
+    label: '备注',
+    col: 24,
+    props: {
+      type: 'textarea',
+      rows: 4,
+      maxlength: 200,
+      showWordLimit: true,
+    },
+  },
+]
+```
+
+## 数字输入
+
+```tsx
+const formItemList = [
+  {
+    prop: 'amount',
+    label: '金额',
+    props: {
+      max: 999999,
+      min: 0,
+      radix: 2, // 保留2位小数
+      thousand: true, // 千分位
+    },
+  },
+]
+```
+
+## 格式化显示
+
+通过 `formatter` 属性自定义显示格式：
+
+```tsx
+{
+  prop: 'value',
+  label: '值',
+  disabled: true,
+  props: {
+    formatter: (value) => `${value} 元`,
+  },
+}
+```

package/docs/components/link.md

@@ -0,0 +1,63 @@
+# EpLink 链接
+
+基于 el-link 封装的链接组件。
+
+## 基本用法
+
+```vue
+<template>
+  <EpLink content="查看详情" @click="handleClick" />
+</template>
+
+<script setup>
+const handleClick = () => {
+  console.log('点击')
+}
+</script>
+```
+
+## Props
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| content | 链接文本 | `string` | - |
+| type | 类型 ^el^ | `'primary' \| 'success' \| 'warning' \| 'danger' \| 'info'` | `'primary'` |
+| underline | 下划线 ^el^ | `'always' \| 'hover' \| 'never'` | `'never'` |
+| disabled | 是否禁用 ^el^ | `boolean` | `false` |
+| href | 链接地址 ^el^ | `string` | - |
+
+> ^el^ 表示继承自 [el-link](https://element-plus.org/zh-CN/component/link.html) 的属性
+
+## 在表格中使用
+
+```tsx
+const columns = [
+  {
+    prop: 'orderNo',
+    label: '订单号',
+    type: 'EpLink',
+    props: {
+      onClick: (row) => {
+        // 跳转详情
+      },
+    },
+  },
+]
+```
+
+## 在 Form 中使用
+
+```tsx
+const formItemList = [
+  {
+    prop: 'relatedNo',
+    label: '关联单号',
+    type: 'EpLink',
+    props: {
+      onClick: () => {
+        // 跳转关联单据
+      },
+    },
+  },
+]
+```

package/docs/components/search-list-page.md

@@ -0,0 +1,81 @@
+# EpSearchListPage 搜索列表页
+
+集成搜索表单和数据表格的列表页容器组件。
+
+## 基本用法
+
+```vue
+<template>
+  <EpSearchListPage
+    :form-item-list="formItemList"
+    :form-data="formData"
+    :columns="columns"
+    :left-buttons="leftButtons"
+    api="/api/list/page"
+    :add="handleAdd"
+    show-selection-col
+    :action-buttons="actionButtons"
+  />
+</template>
+
+<script setup lang="tsx">
+import { ref, reactive } from 'vue'
+import type { SearchListPageProps } from 'el-plus'
+
+const formData = reactive({})
+
+const formItemList = ref<SearchListPageProps['formItemList']>([
+  { prop: 'name', label: '名称' },
+  { prop: 'status', label: '状态', type: 'EpSelect', props: { options: [] } },
+])
+// 如果有自定义列，就不需要定义 columns
+const columns = [
+  { prop: 'name', label: '名称' },
+  { prop: 'status', label: '状态' },
+]
+
+const leftButtons = ref<SearchListPageProps['leftButtons']>([
+  { name: '删除', prop: 'delete', type: 'danger' },
+])
+
+const actionButtons = ref<SearchListPageProps['actionButtons']>([
+  { name: '编辑', prop: 'edit', onClick: (row) => {} },
+  { name: '删除', prop: 'delete', onClick: (row) => {} },
+])
+
+const handleAdd = () => {}
+</script>
+```
+
+## Props
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| api | 列表接口地址 | `string \| (reqData) => Promise` | - |
+| method | 请求方法 | `string` | `'post'` |
+| reqData | 请求体数据 | `object` | `{}` |
+| reqParams | URL 参数 | `object` | `{}` |
+| reqBefore | 请求前处理 | `(reqData) => reqData` | - |
+| reqAfter | 响应后处理 | `(res) => data` | - |
+| formData | 表单数据 | `object` | `{}` |
+| formItemList | 搜索表单配置 | [`FormItemProps[]`](./form.md#formitemprops-配置) | `[]` |
+| columns | 表格列配置（有customColumnModule就不需要定义列） | [`TableColumn[]`](./table.md#tablecolumn-配置) | `[]` |
+| leftButtons | 左侧按钮 | [`ButtonProps[]`](./buttons.md#buttonprops-配置) | `[]` |
+| actionButtons | 操作列按钮 | [`ButtonProps[]`](./buttons.md#buttonprops-配置) | `[]` |
+| add | 新增按钮回调 | `Function` | - |
+| showSelectionCol | 显示多选列 | `boolean` | `false` |
+| showSingleSelectionCol | 显示单选列 | `boolean` | `false` |
+| showIndexCol | 显示序号列 | `boolean` | `true` |
+| showOperationColumn | 显示操作列 | `boolean` | - |
+| minWidth | 列最小宽度 | `number \| string` | - |
+| actionColWidth | 操作列宽度 | `number \| string` | `200` |
+| formatColumns | 格式化列配置 | [`TableColumn[]`](./table.md#tablecolumn-配置) | `[]` |
+| offsetTop | 表格额外距离 | `number` | `0` |
+| isInitSearch | 是否初始化加载 | `boolean` | `true` |
+| tableProps | 表格额外属性 | `object` | - |
+| formProps | 表单额外属性 | `object` | - |
+| buttonsProps | 按钮组额外属性 | `object` | - |
+| name | 权限前缀 | `string` | - |
+| customColumnModule | 自定义列模块 | `string \| number` | - |
+| customColumnApi | 自定义列接口 | `string` | - |
+| customColumnSaveApi | 自定义列保存接口 | `string` | - |