@aspire-ui/element-component-pro 1.0.1 → 1.0.3

package/src/ProTable/TableAction.vue

@@ -0,0 +1,193 @@
+<template>
+  <div class="ecp-table-action">
+    <!-- 主操作按钮组 -->
+    <span
+      v-for="(action, index) in visibleActions"
+      :key="`action-${index}`"
+      class="ecp-table-action__item"
+    >
+      <!-- 气泡确认 -->
+      <el-popconfirm
+        v-if="action.popConfirm"
+        :title="action.popConfirm.title"
+        :confirm-button-text="action.popConfirm.okText || '确定'"
+        :cancel-button-text="action.popConfirm.cancelText || '取消'"
+        @confirm="(e) => handlePopConfirm(action, 'confirm', e)"
+        @cancel="(e) => handlePopConfirm(action, 'cancel', e)"
+      >
+        <span slot="reference">
+          <component
+            :is="action.tooltip ? 'el-tooltip' : 'span'"
+            v-bind="action.tooltip ? normalizeTooltip(action.tooltip) : {}"
+          >
+            <el-button
+              :type="getButtonType(action)"
+              size="small"
+              :disabled="action.disabled"
+              v-bind="action.props"
+              @click="(e) => handleClick(action, e)"
+            >
+              <i v-if="action.icon" :class="['ecp-table-action__icon', action.icon]" />
+              <span>{{ action.label }}</span>
+            </el-button>
+          </component>
+        </span>
+      </el-popconfirm>
+
+      <!-- 普通按钮 -->
+      <component
+        v-else
+        :is="action.tooltip ? 'el-tooltip' : 'span'"
+        v-bind="action.tooltip ? normalizeTooltip(action.tooltip) : {}"
+      >
+        <el-button
+          :type="getButtonType(action)"
+          size="small"
+          :disabled="action.disabled"
+          v-bind="action.props"
+          @click="(e) => handleClick(action, e)"
+        >
+          <i v-if="action.icon" :class="['ecp-table-action__icon', action.icon]" />
+          <span>{{ action.label }}</span>
+        </el-button>
+      </component>
+
+      <el-divider v-if="action.divider" direction="vertical" />
+    </span>
+
+    <!-- 下拉更多操作 -->
+    <el-dropdown v-if="visibleDropDownActions.length" trigger="click" @command="handleDropdownCommand">
+      <span class="ecp-table-action__more">
+        <el-button type="text" size="small">
+          更多<i class="el-icon-arrow-down el-icon--right" />
+        </el-button>
+      </span>
+      <el-dropdown-menu slot="dropdown">
+        <el-dropdown-item
+          v-for="(action, index) in visibleDropDownActions"
+          :key="`dropdown-${index}`"
+          :command="index"
+          :disabled="action.disabled"
+          :divided="!!action.divider"
+        >
+          <span class="ecp-table-action__dropdown-item">
+            <i v-if="action.icon" :class="['ecp-table-action__icon', action.icon]" />
+            <span>{{ action.label }}</span>
+          </span>
+        </el-dropdown-item>
+      </el-dropdown-menu>
+    </el-dropdown>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { MessageBox } from 'element-ui'
+import type { TableActionItem } from './types'
+
+const props = withDefaults(
+  defineProps<{
+    actions?: TableActionItem[]
+    dropDownActions?: TableActionItem[]
+    /** 是否阻止按钮 click 冒泡，参考 VbenAdmin stopButtonPropagation */
+    stopButtonPropagation?: boolean
+  }>(),
+  {
+    actions: () => [],
+    dropDownActions: () => [],
+    stopButtonPropagation: false,
+  }
+)
+
+const normalizeTooltip = (tooltip?: TableActionItem['tooltip']) => {
+  if (!tooltip) return {}
+  if (typeof tooltip === 'string') {
+    return { content: tooltip }
+  }
+  return tooltip as Record<string, unknown>
+}
+
+const getButtonType = (action: TableActionItem) => {
+  if (action.type) return action.type
+  if (action.color === 'error') return 'danger'
+  if (action.color === 'success') return 'success'
+  if (action.color === 'warning') return 'warning'
+  return 'text'
+}
+
+const filterVisible = (list: TableActionItem[]) =>
+  list.filter((item) => {
+    const { ifShow } = item
+    if (typeof ifShow === 'boolean') return ifShow
+    if (typeof ifShow === 'function') return ifShow(item)
+    return true
+  })
+
+const visibleActions = computed(() => filterVisible(props.actions || []))
+const visibleDropDownActions = computed(() => filterVisible(props.dropDownActions || []))
+
+const handleClick = (action: TableActionItem, e: MouseEvent) => {
+  if (props.stopButtonPropagation) {
+    e.stopPropagation()
+  }
+  action.onClick?.(e)
+}
+
+const handlePopConfirm = (action: TableActionItem, type: 'confirm' | 'cancel', e: MouseEvent) => {
+  if (props.stopButtonPropagation) {
+    e.stopPropagation()
+  }
+  if (!action.popConfirm) return
+  if (type === 'confirm') {
+    action.popConfirm.confirm?.()
+  } else {
+    action.popConfirm.cancel?.()
+  }
+}
+
+const handleDropdownCommand = (index: number | string) => {
+  const idx = Number(index)
+  const action = visibleDropDownActions.value[idx]
+  if (!action || action.disabled) return
+  if (action.popConfirm) {
+    const title = action.popConfirm.title
+    const okText = action.popConfirm.okText || '确定'
+    const cancelText = action.popConfirm.cancelText || '取消'
+    MessageBox.confirm(title, '提示', {
+      confirmButtonText: okText,
+      cancelButtonText: cancelText,
+      type: 'warning',
+    })
+      .then(() => action.popConfirm?.confirm?.())
+      .catch(() => action.popConfirm?.cancel?.())
+    return
+  }
+  action.onClick?.({} as MouseEvent)
+}
+</script>
+
+<style scoped>
+.ecp-table-action {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+.ecp-table-action__item {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+.ecp-table-action__icon {
+  margin-right: 4px;
+}
+.ecp-table-action__more {
+  display: inline-flex;
+  align-items: center;
+}
+.ecp-table-action__dropdown-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+</style>
+

package/src/ProTable/index.ts

@@ -0,0 +1,20 @@
+import ProTable from './ProTable.vue'
+import TableAction from './TableAction.vue'
+import { useProTable } from './useProTable'
+
+export { ProTable, useProTable, TableAction }
+export type { UseProTableReturn, UseProTablePropsReactive } from './useProTable'
+export type {
+  ProColumn,
+  ProTableProps,
+  TableActionType,
+  FetchSetting,
+  FetchParams,
+  ProTableToolBarConfig,
+  SpanMethodParams,
+  SpanMethodResult,
+  TreeProps,
+  TableActionItem,
+  TableActionProps,
+} from './types'
+export default ProTable

package/src/ProTable/types/index.ts

@@ -0,0 +1,236 @@
+import type { VNode } from 'vue'
+
+/** ProTable 列配置 */
+export interface ProColumn {
+  /** 列唯一标识 */
+  key?: string
+  /** 列标题 */
+  title: string
+  /** 数据字段名 */
+  dataIndex: string
+  /** 列宽度：number 为比例（如 1、2、3 表示 1:2:3），string 为 px */
+  width?: number | string
+  /** 最小宽度（参考 VbenAdmin，比例列和固定列均生效） */
+  minWidth?: number | string
+  /** 最大宽度（参考 VbenAdmin，用于限制列宽上限） */
+  maxWidth?: number | string
+  /** 固定列 */
+  fixed?: 'left' | 'right'
+  /** 是否可排序 */
+  sortable?: boolean
+  /** 对齐方式 */
+  align?: 'left' | 'center' | 'right'
+  /** 是否可调整宽度 */
+  resizable?: boolean
+  /** 内容超出时是否省略并显示 tooltip，默认继承表格 ellipsis */
+  ellipsis?: boolean
+  /** 是否隐藏 */
+  hideInTable?: boolean
+  /** 默认隐藏，可在列设置中显示（参考 VbenAdmin defaultHidden） */
+  defaultHidden?: boolean
+  /** 列头右侧帮助文本（参考 VbenAdmin helpMessage） */
+  helpMessage?: string | string[]
+  /** 值类型 */
+  valueType?: 'text' | 'date' | 'dateTime' | 'option' | 'select' | 'index'
+  /** 枚举值映射 */
+  valueEnum?: Record<string | number, { text: string; status?: string }>
+  /** 自定义渲染 */
+  customRender?: (params: { text: unknown; record: Record<string, unknown>; index: number }) => VNode | string
+  /** Element UI formatter */
+  formatter?: (row: Record<string, unknown>, column: unknown, cellValue: unknown) => string
+  /** 根据业务控制列是否显示 */
+  ifShow?: boolean | ((params: { column: ProColumn }) => boolean)
+  /** 表单项配置（用于搜索） */
+  fieldProps?: Record<string, unknown>
+  /** 表单项占位符 */
+  placeholder?: string
+}
+
+/** 接口请求配置 */
+export interface FetchSetting {
+  pageField?: string
+  sizeField?: string
+  listField?: string
+  totalField?: string
+}
+
+/** reload 请求参数（参考 VbenAdmin FetchParams） */
+export interface FetchParams {
+  page?: number
+  pageSize?: number
+  searchInfo?: Record<string, unknown>
+}
+
+/** 合并单元格回调参数 */
+export interface SpanMethodParams {
+  row: Record<string, unknown>
+  column: Record<string, unknown>
+  rowIndex: number
+  columnIndex: number
+}
+
+/** 合并单元格返回值 */
+export type SpanMethodResult = [number, number] | { rowspan: number; colspan: number }
+
+/** 树形表格配置 */
+export interface TreeProps {
+  /** 是否有子节点字段名 */
+  hasChildren?: string
+  /** 子节点字段名 */
+  children?: string
+}
+
+/** ProTable Props */
+export interface ProTableProps {
+  columns?: ProColumn[]
+  dataSource?: Record<string, unknown>[]
+  api?: (params: Record<string, unknown>) => Promise<unknown>
+  rowKey?: string
+  title?: string
+  titleHelpMessage?: string | string[]
+  bordered?: boolean
+  striped?: boolean
+  size?: 'medium' | 'small' | 'large'
+  loading?: boolean
+  maxHeight?: number | string
+  height?: number | string
+  ellipsis?: boolean
+  showIndexColumn?: boolean
+  indexColumnProps?: Partial<ProColumn>
+  actionColumn?: Partial<ProColumn>
+  /** 选择列配置（参考 VbenAdmin，通过自定义列实现，不使用 type="selection"） */
+  rowSelection?: {
+    type?: 'checkbox' | 'radio'
+    width?: number
+    fixed?: 'left' | 'right'
+    /** 多选时禁用某行的勾选，(record) => { disabled?: boolean } */
+    getCheckboxProps?: (record: Record<string, unknown>) => { disabled?: boolean }
+    /** 单选时禁用某行的选择，(record) => { disabled?: boolean } */
+    getRadioProps?: (record: Record<string, unknown>) => { disabled?: boolean }
+  }
+  /** 切换页码时是否清空勾选，默认 false 即支持跨分页选择 */
+  clearSelectOnPageChange?: boolean
+  pagination?: false | Record<string, unknown>
+  fetchSetting?: FetchSetting
+  beforeFetch?: (params: Record<string, unknown>) => Record<string, unknown>
+  afterFetch?: (data: unknown) => unknown
+  immediate?: boolean
+  searchInfo?: Record<string, unknown>
+  /** 合并行或列的方法 */
+  spanMethod?: (params: SpanMethodParams) => SpanMethodResult
+  /** 树形表格配置 */
+  treeProps?: TreeProps
+  /** 是否默认展开所有行（树形表格） */
+  defaultExpandAll?: boolean
+  /** 展开的行（树形表格），需配合 rowKey 使用 */
+  expandRowKeys?: (string | number)[]
+  /** 是否懒加载子节点（树形表格） */
+  lazy?: boolean
+  /** 懒加载子节点的方法（树形表格） */
+  load?: (row: Record<string, unknown>, treeNode: { level: number; expanded: boolean; loaded: boolean }, resolve: (data: Record<string, unknown>[]) => void) => void
+}
+
+/** 行选择配置（与 ProTableProps.rowSelection 一致，供 getRowSelection 返回） */
+export type TableRowSelection = ProTableProps['rowSelection']
+
+/** TableAction 气泡确认配置（参考 VbenAdmin PopConfirm） */
+export interface TableActionPopConfirm {
+  title: string
+  okText?: string
+  cancelText?: string
+  confirm: () => void | Promise<void>
+  cancel?: () => void | Promise<void>
+  icon?: string
+}
+
+/** TableAction 单个操作项（参考 VbenAdmin ActionItem） */
+export interface TableActionItem {
+  /** 按钮文本 */
+  label: string
+  /** 是否禁用 */
+  disabled?: boolean
+  /** 按钮颜色（内部会映射到 Element UI 按钮类型） */
+  color?: 'success' | 'error' | 'warning'
+  /** 按钮类型，直接透传给 Element UI Button 的 type */
+  type?: string
+  /** 额外的按钮 props，直接透传给 Element UI Button */
+  props?: Record<string, unknown>
+  /** 图标 class（例如 element-ui 图标或自定义 iconfont） */
+  icon?: string
+  /** 气泡确认配置 */
+  popConfirm?: TableActionPopConfirm
+  /** 是否显示分隔线（垂直 Divider） */
+  divider?: boolean
+  /** 权限标识，具体含义由业务自行约定 */
+  auth?: string | string[]
+  /** 是否显示当前操作项，可为布尔值或函数 */
+  ifShow?: boolean | ((action: TableActionItem) => boolean)
+  /** 点击回调 */
+  onClick?: (e: MouseEvent) => void
+  /** Tooltip 配置：字符串或 Element UI Tooltip 的 props */
+  tooltip?: string | Record<string, unknown>
+}
+
+/** TableAction 组件 Props（参考 VbenAdmin TableAction） */
+export interface TableActionProps {
+  actions?: TableActionItem[]
+  dropDownActions?: TableActionItem[]
+  /** 是否阻止按钮 click 冒泡 */
+  stopButtonPropagation?: boolean
+}
+
+/** ProTable 操作类型（参考 Vben Admin TableActionType） */
+export interface TableActionType {
+  setProps: (props: Partial<ProTableProps>) => void
+  reload: (opt?: FetchParams) => Promise<void>
+  /** 重新计算表格高度/布局（参考 VbenAdmin redoHeight） */
+  redoHeight: () => void
+  setLoading: (loading: boolean) => void
+  getDataSource: () => Record<string, unknown>[]
+  /** 获取接口原始返回数据（参考 VbenAdmin getRawDataSource） */
+  getRawDataSource: () => Record<string, unknown>
+  setTableData: (data: Record<string, unknown>[]) => void
+  getColumns: () => ProColumn[]
+  /** 设置列配置，支持列数组或列 key 列表（参考 VbenAdmin setColumns） */
+  setColumns: (columns: ProColumn[] | string[]) => void
+  setPagination: (info: Partial<{ page: number; pageSize: number; total: number }>) => void
+  getSelectRowKeys: () => (string | number)[]
+  getSelectRows: () => Record<string, unknown>[]
+  clearSelectedRowKeys: () => void
+  /** 设置选中行（参考 VbenAdmin setSelectedRowKeys） */
+  setSelectedRowKeys: (keys: (string | number)[]) => void
+  /** 按 key 取消选中（参考 VbenAdmin deleteSelectRowByKey） */
+  deleteSelectRowByKey: (key: string | number) => void
+  /** 按行索引和字段名更新单格数据（参考 VbenAdmin updateTableData） */
+  updateTableData: (index: number, key: string, value: unknown) => void
+  /** 根据 rowKey 更新指定行（参考 VbenAdmin updateTableDataRecord） */
+  updateTableDataRecord: (rowKey: string | number, record: Record<string, unknown>) => Record<string, unknown> | void
+  /** 根据 rowKey 删除指定行（参考 VbenAdmin deleteTableDataRecord） */
+  deleteTableDataRecord: (rowKey: string | number | (string | number)[]) => void
+  /** 插入行（参考 VbenAdmin insertTableDataRecord） */
+  insertTableDataRecord: (record: Record<string, unknown>, index?: number) => Record<string, unknown> | void
+  /** 获取分页信息（参考 VbenAdmin getPaginationRef） */
+  getPaginationRef: () => { page: number; pageSize: number; total: number } | false
+  /** 是否显示分页 */
+  getShowPagination: () => boolean
+  /** 设置是否显示分页（参考 VbenAdmin，返回 Promise） */
+  setShowPagination: (show: boolean) => void | Promise<void>
+  /** 获取当前行选择配置（参考 VbenAdmin getRowSelection） */
+  getRowSelection: () => TableRowSelection
+  /** 展开树形表格所有行 */
+  expandAll?: () => void
+  /** 折叠树形表格所有行 */
+  collapseAll?: () => void
+}
+
+/** ProTable 工具栏配置 */
+export interface ProTableToolBarConfig {
+  /** 是否显示刷新按钮 */
+  reload?: boolean
+  /** 是否显示密度切换 */
+  density?: boolean
+  /** 是否显示列设置 */
+  columnSetting?: boolean
+  /** 是否显示全屏 */
+  fullScreen?: boolean
+}

package/src/ProTable/useProTable.ts

@@ -0,0 +1,79 @@
+import { ref, watch, unref, type Ref } from 'vue'
+import type { ProTableProps, TableActionType } from './types'
+
+export type UseProTableReturn = [
+  (instance: TableActionType) => void,
+  TableActionType
+]
+
+/** 支持 ref/computed 的 props */
+export type UseProTablePropsReactive = ProTableProps | Ref<ProTableProps | undefined>
+
+/**
+ * 用于 ProTable 的 useProTable，支持通过 ref 调用表格方法
+ * @param props ProTable 的 props 配置，传入后会通过 setProps 同步到表格（支持 ref/computed 响应式更新）
+ */
+export function useProTable(props?: UseProTablePropsReactive): UseProTableReturn {
+  const tableActionRef = ref<TableActionType | null>(null)
+
+  const getTableProps = (): ProTableProps | undefined =>
+    (props ? unref(props as Ref<ProTableProps | undefined>) : undefined) as ProTableProps | undefined
+
+  const getTableAction = (): TableActionType => {
+    const action = unref(tableActionRef)
+    if (!action) {
+      throw new Error('ProTable instance has not been registered')
+    }
+    return action
+  }
+
+  const register = (instance: TableActionType) => {
+    tableActionRef.value = instance
+    const tableProps = getTableProps()
+    if (tableProps && Object.keys(tableProps).length > 0) {
+      instance.setProps(tableProps)
+    }
+  }
+
+  if (props) {
+    watch(
+      () => getTableProps(),
+      (tableProps) => {
+        if (tableProps && tableActionRef.value) {
+          tableActionRef.value.setProps(tableProps)
+        }
+      },
+      { deep: true }
+    )
+  }
+
+  const tableActions: UseProTableReturn[1] = {
+    setProps: (p) => getTableAction().setProps(p),
+    reload: (opt) => getTableAction().reload(opt),
+    redoHeight: () => getTableAction().redoHeight(),
+    setLoading: (v) => getTableAction().setLoading(v),
+    getDataSource: () => getTableAction().getDataSource(),
+    getRawDataSource: () => getTableAction().getRawDataSource(),
+    setTableData: (data) => getTableAction().setTableData(data),
+    getColumns: () => getTableAction().getColumns(),
+    setColumns: (cols) => getTableAction().setColumns(cols),
+    setPagination: (info) => getTableAction().setPagination(info),
+    getSelectRowKeys: () => getTableAction().getSelectRowKeys(),
+    getSelectRows: () => getTableAction().getSelectRows(),
+    clearSelectedRowKeys: () => getTableAction().clearSelectedRowKeys(),
+    setSelectedRowKeys: (keys) => getTableAction().setSelectedRowKeys(keys),
+    deleteSelectRowByKey: (key) => getTableAction().deleteSelectRowByKey(key),
+    updateTableData: (index, key, value) => getTableAction().updateTableData(index, key, value),
+    updateTableDataRecord: (rowKey, record) => getTableAction().updateTableDataRecord(rowKey, record),
+    deleteTableDataRecord: (rowKey) => getTableAction().deleteTableDataRecord(rowKey),
+    insertTableDataRecord: (record, index) => getTableAction().insertTableDataRecord(record, index),
+    getPaginationRef: () => getTableAction().getPaginationRef(),
+    getShowPagination: () => getTableAction().getShowPagination(),
+    setShowPagination: (show) => getTableAction().setShowPagination(show),
+    getRowSelection: () => getTableAction().getRowSelection(),
+    expandAll: () => getTableAction().expandAll?.(),
+    collapseAll: () => getTableAction().collapseAll?.(),
+  }
+
+  return [register, tableActions]
+}

package/src/index.ts

@@ -1,20 +1,24 @@
 import type { VueConstructor } from 'vue'
-// import ProTable from './ProTable'
+import ProTable, { TableAction } from './ProTable'
 import ProForm, { ProFormItem, FormActions } from './ProForm'
-// import ProCard from './ProCard'
-// import ProDescriptions from './ProDescriptions'
 import { useForm } from './ProForm/useForm'
+import { useProTable } from './ProTable/useProTable'
+import { useComponentSetting } from './useComponentSetting'
 
 export { ProForm, ProFormItem, FormActions, useForm }
+export { ProTable, useProTable, TableAction }
+export { useComponentSetting }
+export type { UseComponentSettingReturn } from './useComponentSetting'
+export type { UseProTableReturn, UseProTablePropsReactive } from './ProTable/useProTable'
+export * from './ProTable/types'
 export * from './types'
 
 const components = [
-  // { name: 'ProTable', component: ProTable },
+  { name: 'ProTable', component: ProTable },
+  { name: 'TableAction', component: TableAction },
   { name: 'ProForm', component: ProForm },
   { name: 'ProFormItem', component: ProFormItem },
-  { name: 'FormActions', component: FormActions }
-  // { name: 'ProCard', component: ProCard },
-  // { name: 'ProDescriptions', component: ProDescriptions },
+  { name: 'FormActions', component: FormActions },
 ]
 
 export function install(Vue: VueConstructor) {
@@ -25,8 +29,7 @@ export function install(Vue: VueConstructor) {
 
 export default {
   install,
-  // ProTable,
+  ProTable,
   ProForm,
-  // ProCard,
-  // ProDescriptions,
+  TableAction,
 }

package/src/types/index.ts

@@ -1,49 +1,5 @@
 import type { VNode } from 'vue'
 
-/** ProTable 列配置 */
-export interface ProColumn {
-  /** 列标题 */
-  title: string
-  /** 数据字段名 */
-  dataIndex: string
-  /** 列宽度 */
-  width?: number | string
-  /** 最小宽度 */
-  minWidth?: number | string
-  /** 固定列 */
-  fixed?: 'left' | 'right'
-  /** 是否可排序 */
-  sortable?: boolean
-  /** 对齐方式 */
-  align?: 'left' | 'center' | 'right'
-  /** 是否可调整宽度 */
-  resizable?: boolean
-  /** 是否隐藏 */
-  hideInTable?: boolean
-  /** 值类型 */
-  valueType?: 'text' | 'date' | 'dateTime' | 'option' | 'select' | 'index'
-  /** 枚举值映射 */
-  valueEnum?: Record<string | number, { text: string; status?: string }>
-  /** 自定义渲染 */
-  customRender?: (params: { text: unknown; record: Record<string, unknown>; index: number }) => VNode | string
-  /** 表单项配置（用于搜索） */
-  fieldProps?: Record<string, unknown>
-  /** 表单项占位符 */
-  placeholder?: string
-}
-
-/** ProTable 工具栏配置 */
-export interface ProTableToolBarConfig {
-  /** 是否显示刷新按钮 */
-  reload?: boolean
-  /** 是否显示密度切换 */
-  density?: boolean
-  /** 是否显示列设置 */
-  columnSetting?: boolean
-  /** 是否显示全屏 */
-  fullScreen?: boolean
-}
-
 /** 栅格配置 */
 export interface ColEx {
   span?: number
@@ -122,16 +78,40 @@ export interface ProFormProps {
   fieldMapToTime?: FieldMapToTime[]
   /** 透传给 el-form 的事件监听器 */
   formListeners?: FormListeners
+  /** 自定义组件映射（组件名 -> 组件定义），供 schema.component 使用 */
+  components?: Record<string, unknown>
 }
 
+/** ProForm 内置表单项组件类型 */
+export type ProFormBuiltInComponent =
+  | 'input'
+  | 'select'
+  | 'api-select'
+  | 'tree-select'
+  | 'date-picker'
+  | 'date-range'
+  | 'input-number'
+  | 'switch'
+  | 'cascader'
+  | 'checkbox'
+  | 'radio'
+
+/** 自定义组件：组件名（string）或 Vue 组件选项/构造函数（object | Function） */
+export type ProFormCustomComponent = string | object | ((...args: unknown[]) => unknown)
+
 /** ProForm 表单项配置 */
 export interface ProFormSchema {
   /** 字段名 */
   field: string
   /** 标签 */
   label: string
-  /** 组件类型 */
-  component?: 'input' | 'select' | 'date-picker' | 'date-range' | 'input-number' | 'switch' | 'cascader' | 'checkbox' | 'radio'
+  /**
+   * 组件类型：
+   * - 内置：'input' | 'select' | 'date-picker' | 'date-range' | 'input-number' | 'switch' | 'cascader' | 'checkbox' | 'radio'
+   * - 自定义组件名：任意字符串，对应全局或 ProForm 传入的 components 中注册的组件
+   * - 内联组件：直接传入 Vue 组件选项对象或构造函数
+   */
+  component?: ProFormBuiltInComponent | ProFormCustomComponent
   /** 组件属性，支持函数 */
   componentProps?: Record<string, unknown> | ((params: RenderCallbackParams & { formActionType?: FormActionType }) => Record<string, unknown>)
   /** 占位符 */