el-plus 0.0.84 → 0.0.85

package/docs/components/form.md

@@ -0,0 +1,178 @@
+# 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` | - |
+
+## 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,80 @@
+# EpHeader 顶部操作栏
+
+详情页顶部操作栏组件，支持返回、按钮组、附件等功能。
+
+## 基本用法
+
+```vue
+<template>
+  <EpHeader
+    :buttons="headerButtons"
+  />
+</template>
+
+<script setup lang="tsx">
+import { computed } from 'vue'
+import type { HeaderProps } from 'el-plus'
+
+const headerButtons:HeaderProps['buttons']= [
+  {
+    name: '提交',
+    prop: 'submit',
+    type: 'primary',
+    onClick: () => {},
+  },
+]
+</script>
+```
+
+## Props
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| buttons | 自定义按钮列表 | [`ButtonProps[]`](./buttons.md#buttonprops-配置) | `[]` |
+| defaultButtons | 显示的默认按钮 | `('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) | `{}` |
+
+## 默认按钮说明
+
+| 按钮 | 说明 |
+|------|------|
+| 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,87 @@
+# 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) 的属性
+
+## 在 Form 中使用
+
+```tsx
+const formItemList = [
+  {
+    prop: 'name',
+    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,84 @@
+# 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({
+  name: '',
+  status: '',
+})
+
+const formItemList = ref<SearchListPageProps['formItemList']>([
+  { prop: 'name', label: '名称' },
+  { prop: 'status', label: '状态', type: 'EpSelect', props: { options: [] } },
+])
+
+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 | 表格列配置 | [`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` | - |

package/docs/components/select.md

@@ -0,0 +1,163 @@
+# EpSelect 下拉选择
+
+基于 el-select 封装，支持接口获取选项、自定义 label 等功能。
+
+## 基本用法
+
+```vue
+<template>
+  <EpSelect v-model="value" :options="options" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const value = ref('')
+const options = [
+  { label: '选项1', value: '1' },
+  { label: '选项2', value: '2' },
+]
+</script>
+```
+
+## Props
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| v-model | 绑定值 ^el^ | `string \| number \| array` | - |
+| options | 选项列表 ^el^ | `array` | `[]` |
+| api | 选项接口地址 | `string \| (reqData) => Promise` | - |
+| method | 请求方法 | `string` | `'post'` |
+| reqData | 请求体数据 | `object` | `{}` |
+| reqParams | URL 参数 | `object` | `{}` |
+| reqBefore | 请求前处理 | `(reqData) => reqData` | - |
+| reqAfter | 响应后处理 | `(res) => options` | - |
+| labelKey | label 字段名 | `string` | `'label'` |
+| valueKey | value 字段名 | `string` | `'value'` |
+| formatLabel | 自定义 label 格式化 | `(item) => string` | - |
+| disabledOption | 禁用选项判断 | `(item) => boolean` | - |
+| lazy | 延迟加载（api模式） | `boolean` | `false` |
+| codeInLabel | 下拉label 中显示 code ,当为boolean默认是valueKey| `boolean \| string` | - |
+| clearable | 是否可清空 ^el^ | `boolean` | `true` |
+
+> ^el^ 表示继承自 [el-select](https://element-plus.org/zh-CN/component/select.html#select-attributes) 的属性
+
+## 在 Form 中使用
+
+```tsx
+const formItemList = [
+  {
+    prop: 'status',
+    label: '状态',
+    type: 'EpSelect',
+    props: {
+      options: [
+        { label: '启用', value: 1 },
+        { label: '禁用', value: 0 },
+      ],
+    },
+  },
+]
+```
+
+## 接口获取选项
+
+```tsx
+{
+  prop: 'companyCode',
+  label: '公司',
+  type: 'EpSelect',
+  props: {
+    api: '/api/company/list',
+    valueKey: 'code',
+    labelKey: 'name',
+  },
+}
+```
+
+## 远程搜索
+```tsx
+{
+  prop: 'companyCode',
+  label: '公司',
+  type: 'EpSelect',
+  props: {
+    api: '/api/company/list',
+    valueKey: 'code',
+    labelKey: 'name',
+    remote: true,
+    filterable: true,
+  },
+}
+
+```
+
+## 带描述
+- 适用于有code，但配置为remote/lazy，导致没有name的情况
+```tsx
+{
+  prop: 'companyCode',
+  label: '公司',
+  type: 'EpSelect',
+  props: {
+    api: '/api/company/list',
+    valueKey: 'code',
+    labelKey: 'name',
+    lazy: true,
+    desc: '描述信息'
+  },
+}
+```
+
+## 自定义 label 格式
+
+```tsx
+{
+  prop: 'companyCode',
+  label: '公司',
+  type: 'EpSelect',
+  props: {
+    api: '/api/company/list',
+    valueKey: 'code',
+    labelKey: 'name',
+    formatLabel: (item) => `${item.name} (${item.code})`,
+  },
+}
+```
+
+## 监听变化
+
+```tsx
+{
+  prop: 'companyCode',
+  label: '公司',
+  type: 'EpSelect',
+  props: {
+    options: [],
+  },
+  onChange: (value, item) => {
+    // value: 选中的值
+    // item: 选中的选项对象
+    formData.companyName = item?.name
+  },
+}
+```
+
+## codeInLabel 模式
+
+下拉同时显示 code 和 label：
+
+```tsx
+{
+  prop: 'itemCode',
+  label: '商品',
+  type: 'EpSelect',
+  props: {
+    api: '/api/item/list',
+    valueKey: 'code',
+    labelKey: 'name',
+    codeInLabel: true, // 显示为 "name code"
+    // codeInLabel: 'itemCode', // 显示为 "name itemCode字段值"
+  },
+}
+```