el-plus 0.0.84 → 0.0.86-beta.0

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字段值"
+  },
+}
+```

package/docs/components/table.md

@@ -0,0 +1,133 @@
+# EpTable 数据表格
+
+基于 el-table 封装，支持配置化列、分页、操作列等功能。
+
+## 基本用法
+
+```vue
+<template>
+  <EpTable
+    :data="tableData"
+    :columns="columns"
+    :action-buttons="actionButtons"
+  />
+</template>
+
+<script setup lang="tsx">
+import { ref } from 'vue'
+
+const tableData = ref([])
+
+const columns = [
+  { prop: 'name', label: '名称' },
+  { prop: 'status', label: '状态' },
+]
+
+const actionButtons = [
+  { name: '编辑', onClick: (row) => {} },
+  { name: '删除', onClick: (row) => {} },
+]
+</script>
+```
+
+## Props
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| data | 表格数据 ^el^ | `array` | `[]` |
+| columns | 列配置 | [`TableColumn[]`](#tablecolumn-配置) | `[]` |
+| api | 数据接口 | `string \| (reqData) => Promise` | - |
+| method | 请求方法 | `string` | `'post'` |
+| reqData | 请求体数据 | `object` | `{}` |
+| reqParams | URL 参数 | `object` | `{}` |
+| reqBefore | 请求前处理 | `(reqData) => reqData` | - |
+| reqAfter | 响应后处理 | `(res) => data` | - |
+| size | 表格尺寸 ^el^ | `'large' \| 'default' \| 'small'` | `'default'` |
+| border | 是否带边框 ^el^ | `boolean` | `true` |
+| headerCellStyle | 表头样式 ^el^ | `object` | `{ background: '#EEEFF3', fontSize: '14px', color: '#505050' }` |
+| showSelectionCol | 显示多选列 | `boolean` | `false` |
+| showSingleSelectionCol | 显示单选列 | `boolean` | `false` |
+| showIndexCol | 显示序号列 | `boolean` | `true` |
+| align | 对齐方式 | `'left' \| 'center' \| 'right'` | `'center'` |
+| minWidth | 列最小宽度 | `number \| string` | - |
+| actionColWidth | 操作列宽度 | `number \| string` | `200` |
+| actionButtons | 操作列按钮 | [`ButtonProps[]`](./buttons.md#buttonprops-配置) | `[]` |
+| formatColumns | 格式化列配置 | [`TableColumn[]`](#tablecolumn-配置) | `[]` |
+| showPagination | 显示分页 | `boolean` | `false` |
+| paginationProps | 分页属性 | `object` | `{}` |
+| isFrontPage | 前端分页 | `boolean` | `false` |
+| isInitSearch | 初始化加载 | `boolean` | `true` |
+| disabled | 是否禁用 | `boolean` | `false` |
+| reserveSelection | 保留选择 | `boolean` | `false` |
+| selectable | 可选择函数 | `(row, index) => boolean` | - |
+| indexFormatter | 序号列格式化 | `number \| Function` | - |
+
+> ^el^ 表示继承自 [el-table](https://element-plus.org/zh-CN/component/table.html) 的属性
+
+## TableColumn 配置
+
+| 属性 | 说明 | 类型 |
+|------|------|------|
+| prop | 字段名 | `string` |
+| label | 列标题 | `string` |
+| width | 列宽度 | `number \| string` |
+| minWidth | 最小宽度 | `number \| string` |
+| type | 组件类型 | `string` |
+| props | 组件属性 | `object` |
+| render | 自定义渲染 | `({ row, $index }) => VNode` |
+| headerRender | 自定义表头渲染 | `() => VNode` |
+| required | 是否必填 | `boolean \| () => boolean` |
+| disabled | 是否禁用 | `boolean \| (scope) => boolean` |
+| visible | 是否显示 | `boolean \| () => boolean` |
+| filter | 显示筛选 | `boolean` |
+| editable | 可批量编辑 | `boolean` |
+
+## 在 Form 中使用
+
+```tsx
+const formItemList = [
+  {
+    col: 24,
+    type: 'EpTable',
+    props: {
+      ref: 'detailTable',
+      data: formData.detailList,
+      showSelectionCol: true,
+      columns: [
+        { prop: 'itemCode', label: '编号' },
+        { prop: 'itemName', label: '名称' },
+        {
+          prop: 'quantity',
+          label: '数量',
+          type: 'EpInput',
+          props: { radix: 0 },
+        },
+      ],
+    },
+  },
+]
+```
+
+## 自定义渲染
+
+```tsx
+const columns = [
+  {
+    prop: 'status',
+    label: '状态',
+    render: ({ row }) => (
+      <el-tag type={row.status === 1 ? 'success' : 'danger'}>
+        {row.status === 1 ? '启用' : '禁用'}
+      </el-tag>
+    ),
+  },
+]
+```
+
+## Expose 方法
+
+| 方法 | 说明 |
+|------|------|
+| getSelectionRows | 获取选中行 |
+| clearSelection | 清空选择 |
+| search | 重新加载数据 |

package/docs/components/title.md

@@ -0,0 +1,70 @@
+# EpTitle 标题分组
+
+用于表单分组的标题组件，支持右侧按钮和展开折叠。
+
+## 基本用法
+
+```vue
+<template>
+  <EpTitle title="基本信息" />
+</template>
+```
+
+## Props
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| title | 标题文本 | `string` | - |
+| buttons | 右侧按钮列表 | [`ButtonProps[]`](./buttons.md#buttonprops-配置) | `[]` |
+| showDownUp | 显示展开折叠 | `boolean` | `false` |
+
+## Events
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| toggle | 折叠状态切换 | `(expanded: boolean)` |
+
+## 带按钮
+
+```vue
+<template>
+  <EpTitle title="商品明细" :buttons="buttons" />
+</template>
+
+<script setup>
+const buttons = [
+  {
+    name: '新增',
+    type: 'primary',
+    onClick: () => {},
+  },
+  {
+    name: '删除',
+    type: 'danger',
+    plain: true,
+    onClick: () => {},
+  },
+]
+</script>
+```
+
+## 在 Form 中使用
+
+```tsx
+const formItemList = [
+  {
+    col: 24,
+    type: 'EpTitle',
+    props: {
+      title: '基本信息',
+      buttons: [
+        {
+          name: '操作',
+          onClick: () => {},
+        },
+      ],
+    },
+  },
+  // 其他表单项...
+]
+```

package/docs/components/use-choose-dialog.md

@@ -0,0 +1,115 @@
+# useChooseDialog 选择对话框
+
+基于 useDialog 实现的选择对话框，集成 EpSearchListPage 组件，支持单选和多选。
+
+## 基本用法
+
+```vue
+<template>
+  <el-button @click="handleChoose">选择用户</el-button>
+  <ChooseDialog />
+</template>
+
+<script setup lang="tsx">
+import { useChooseDialog } from 'el-plus'
+
+const ChooseDialog = useChooseDialog({
+  title: '选择用户',
+  multiple: false, // 单选模式
+  dialogProps: {
+    destroyOnClose: true, // 关闭时销毁对话框内容
+  },
+  formItemList: [
+    { prop: 'name', label: '姓名' },
+  ],
+  columns: [
+    { prop: 'name', label: '姓名' },
+    { prop: 'dept', label: '部门' },
+  ],
+  api: getUserList, // 列表接口
+})
+
+const handleChoose = async () => {
+  try {
+    const selection = await ChooseDialog.start()
+    console.log('选中', selection)
+  } catch (e) {
+    console.log('取消')
+  }
+}
+</script>
+```
+
+## Options
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| title | 对话框标题 | `string` | - |
+| dialogProps | 对话框属性，继承自 useDialog | `DialogOptions` | - |
+| multiple | 是否多选 | `boolean` | `false` |
+| formItemList | 搜索表单项配置，参考 [EpForm](./form.md) | `FormItemProps[]` | - |
+| columns | 表格列配置，参考 [EpTable](./table.md) | `TableColumn[]` | - |
+| api | 列表数据接口 | `(params) => Promise` | - |
+| formData | 搜索表单数据 | `object` | - |
+| formProps | 表单属性，参考 [EpForm](./form.md) | `FormProps` | `{ col: 3 }` |
+| tableProps | 表格属性，参考 [EpTable](./table.md) | `TableProps` | `{ height: 300 }` |
+
+## 多选模式
+
+```tsx
+const ChooseDialog = useChooseDialog({
+  title: '选择用户',
+  multiple: true, // 多选模式
+  formItemList: [
+    { prop: 'name', label: '姓名' },
+  ],
+  columns: [
+    { prop: 'name', label: '姓名' },
+    { prop: 'dept', label: '部门' },
+  ],
+  api: getUserList,
+})
+```
+
+多选模式下，底部会显示已选数量，确认后返回选中的行数据数组。
+
+## 单选模式
+
+```tsx
+const ChooseDialog = useChooseDialog({
+  title: '选择用户',
+  multiple: false, // 单选模式（默认）
+  columns: [
+    { prop: 'name', label: '姓名' },
+  ],
+  api: getUserList,
+})
+```
+
+单选模式下，点击行即可选中并关闭对话框，返回选中的行数据对象。
+
+## 自定义表格高度
+
+```tsx
+const ChooseDialog = useChooseDialog({
+  title: '选择用户',
+  tableProps: {
+    height: 500, // 自定义表格高度
+  },
+  columns: [...],
+  api: getUserList,
+})
+```
+
+## 返回值
+
+- **单选模式**: 返回选中的行数据对象
+- **多选模式**: 返回选中的行数据数组
+
+## 方法
+
+| 方法 | 说明 | 类型 |
+|------|------|------|
+| start | 打开对话框并返回 Promise | `() => Promise<Selection>` |
+| open | 打开对话框 | `() => void` |
+| close | 关闭对话框 | `() => void` |

package/docs/components/use-confirm-dialog.md

@@ -0,0 +1,87 @@
+# useConfirmDialog 确认对话框
+
+基于 useFormDialog 实现的确认对话框，内置 textarea 输入框，适用于审批意见、备注填写等场景。
+
+## 基本用法
+
+```vue
+<template>
+  <el-button @click="handleConfirm">审批</el-button>
+  <ConfirmDialog />
+</template>
+
+<script setup lang="tsx">
+import { useConfirmDialog } from 'el-plus'
+
+const ConfirmDialog = useConfirmDialog({
+  title: '审批确认',
+  placeholder: '请输入审批意见',
+})
+
+const handleConfirm = async () => {
+  try {
+    const result = await ConfirmDialog.start()
+    console.log '确认，意见：', result.value)
+  } catch (e) {
+    console.log('取消')
+  }
+}
+</script>
+```
+
+## Options
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| title | 对话框标题 | `string` | - |
+| width | 对话框宽度 | `string` | `'50%'` |
+| dialogProps | 对话框属性，继承自 useDialog | `DialogOptions` | - |
+| rows | textarea 行数 | `number` | `5` |
+| maxlength | 最大输入长度 | `number` | `500` |
+| minlength | 最小输入长度 | `number` | - |
+| showWordLimit | 显示字数统计 | `boolean` | `true` |
+| placeholder | 输入框占位符 | `string` | - |
+| rules | 表单验证规则 | `FormItemProps['rules']` | - |
+| required | 是否必填 | `boolean` | `true` |
+
+## 自定义验证
+
+```tsx
+const ConfirmDialog = useConfirmDialog({
+  title: '驳回原因',
+  required: true,
+  rules: [
+    { required: true, message: '请输入驳回原因', trigger: 'blur' },
+    { min: 10, message: '驳回原因不能少于10个字', trigger: 'blur' },
+  ],
+  placeholder: '请输入驳回原因（不少于10个字）',
+})
+```
+
+## 非必填确认
+
+```tsx
+const ConfirmDialog = useConfirmDialog({
+  title: '备注',
+  required: false, // 非必填
+  placeholder: '请输入备注（选填）',
+})
+```
+
+## 返回值
+
+确认时返回表单数据对象：
+
+```ts
+{
+  value: string // textarea 输入的内容
+}
+```
+
+## 方法
+
+| 方法 | 说明 | 类型 |
+|------|------|------|
+| start | 打开对话框并返回 Promise | `() => Promise<{ value: string }>` |
+| open | 打开对话框 | `() => void` |
+| close | 关闭对话框 | `() => void` |

package/docs/components/use-form-dialog.md

@@ -0,0 +1,87 @@
+# useFormDialog 表单对话框
+
+基于 useDialog 实现的表单对话框，集成 EpForm 组件，支持表单验证。
+
+## 基本用法
+
+```vue
+<template>
+  <el-button @click="openDialog">打开表单对话框</el-button>
+  <FormDialog />
+</template>
+
+<script setup lang="tsx">
+import { useFormDialog } from 'el-plus'
+
+const formItemList = [
+  { prop: 'name', label: '姓名', required: true },
+  { prop: 'age', label: '年龄' },
+]
+
+const FormDialog = useFormDialog({
+  title: '用户信息',
+  formItemList,
+  dialogProps: {
+    destroyOnClose: true, // 关闭时销毁对话框内容
+  },
+})
+
+const openDialog = async () => {
+  try {
+    const formData = await FormDialog.start()
+    console.log('表单数据', formData)
+  } catch (e) {
+    console.log('取消')
+  }
+}
+</script>
+```
+
+## Options
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| title | 对话框标题 | `string` | - |
+| width | 对话框宽度 | `string` | `'80%'` |
+| dialogProps | 对话框属性，继承自 useDialog | `DialogOptions` | - |
+| formData | 表单数据对象 | `object` | - |
+| formItemList | 表单项配置，参考 [EpForm](./form.md) | `FormItemProps[]` | - |
+| onBeforeConfirm | 确认前回调，可用于额外处理 | `(formData, resolve) => Promise<void>` | - |
+| onBeforeCancel | 取消前回调 | `(formData, resolve) => Promise<void>` | - |
+
+## 自定义表单数据
+
+```tsx
+const formData = reactive({
+  name: '',
+  age: '',
+})
+
+const FormDialog = useFormDialog({
+  title: '编辑用户',
+  formData, // 传入外部表单数据
+  formItemList,
+})
+```
+
+## 确认前处理
+
+```tsx
+const FormDialog = useFormDialog({
+  title: '提交表单',
+  formItemList,
+  onBeforeConfirm: async (formData, resolve) => {
+    // 可以在此处进行额外的异步操作
+    await api.submit(formData)
+    resolve(formData)
+  },
+})
+```
+
+## 方法
+
+| 方法 | 说明 | 类型 |
+|------|------|------|
+| start | 打开对话框并返回 Promise | `() => Promise<FormData>` |
+| open | 打开对话框 | `() => void` |
+| close | 关闭对话框 | `() => void` |