element-engin

element-engin

基于 Element Plus 的页面搭建引擎：通过 TypeScript / JavaScript 页面配置（definePage）驱动，自动生成具备 增删改查（CRUD） 能力的后台管理页面。

• 声明式配置：表格、搜索、表单、分页、接口
• RESTful 默认 + 单操作自定义覆盖
• 生命周期钩子：before* / after* / onError
• 默认提交 Loading、成功/失败 Notification
• 完整 TypeScript 类型

安装

npm install element-engin
npm install vue element-plus   # peerDependencies

在入口引入 Element Plus 样式：

import 'element-plus/dist/index.css'
import 'element-engin/style.css'

快速开始

1. 定义页面配置

// pages/user.ts
import { definePage } from 'element-engin'

export const userPage = definePage({
  page: { title: '用户管理' },
  columns: [
    { prop: 'name', label: '姓名', width: 120 },
    { prop: 'email', label: '邮箱' },
  ],
  search: [
    { prop: 'name', label: '姓名', component: 'Input' },
  ],
  form: {
    create: {
      fields: [
        { prop: 'name', label: '姓名', component: 'Input', required: true },
        { prop: 'email', label: '邮箱', component: 'Input', required: true },
      ],
    },
  },
  apis: {
    resource: '/api/users', // RESTful 自动生成 list/create/update/delete/detail
  },
})

2. 挂载 PageEngine

<script setup lang="ts">
import { PageEngine } from 'element-engin'
import { userPage } from './pages/user'
</script>

<template>
  <PageEngine :config="userPage" />
</template>

3. 本地演示

仓库内置完整 Demo（Mock API + 钩子 + 自定义接口）：

npm run demo

详见 examples/demo。

RESTful 接口规范

配置 apis.resource 后，未单独声明的操作按 RESTful 默认推导：

• 主键默认字段名 id，通过 apis.idField 修改；URL 中 :id 自动替换为行数据对应字段值
• 任意操作可 单独覆盖，不影响其他操作：

apis: {
  resource: '/api/users',
  create: {
    url: '/api/custom/create-user',
    method: 'POST',
    transformParams: ({ formData }) => ({ ...formData }),
  },
}

未配置且无 resource 可推导的接口，对应 UI 能力自动隐藏（如无 delete 则不显示删除按钮）。

transformParams

为单个 CRUD 接口配置入参转换函数，在请求发出前执行：

apis: {
  resource: '/api/users',
  list: {
    transformParams: ({ search, pagination }) => ({
      ...search,
      page: pagination?.page,
      pageSize: pagination?.pageSize,
    }),
  },
  update: {
    transformParams: ({ formData, row }) => ({
      id: row?.id,
      ...formData,
    }),
  },
}

上下文 TransformParamsContext：

未配置 transformParams 时引擎使用内置默认：list 合并 search + 分页；create/update 使用 formData。

responseMapping

从接口响应中提取数据，路径以 . 分隔：

apis: {
  resource: '/api/users',
  list: {
    responseMapping: { list: 'data.list', total: 'data.total' },
  },
  detail: {
    responseMapping: { detail: 'data' },
  },
}

未配置时的兜底：list → data.list / 响应数组；detail → 响应体本身。

生命周期钩子

在 hooks 中定义，按操作类型在请求各阶段触发：

hooks: {
  afterList: ({ response, engine }) => {
    console.log('列表加载完成', response)
  },
  beforeDelete: ({ row }) => {
    return row?.status !== 'locked' // false 阻止删除
  },
  afterDelete: ({ row, engine }) => {
    engine.showMessage({ type: 'success', message: `已删除 ${row?.name}` })
  },
  onError: ({ action, error }) => {
    console.error(action, error)
  },
}

错误提示职责：

• create / update 失败：默认走 form.*.notification.error（6.10），onError 做日志/埋点等副作用
• list / delete / detail 失败：默认 error Notification 由 onError 路径统一展示，可通过 notification.list.error 等配置

HookContext 常用字段： action、params、response、row、formData、error、engine

EngineInstance

钩子与 transformParams 中通过 ctx.engine 调用：

页面配置字段说明

顶层 PageConfig

columns 列配置

search / form.fields 字段配置

form.create / form.update

notification 优先级

表单提交成功/失败：form.create|update.notification > notification.create|update > notification 全局 > 内置默认文案。

列表/删除/详情失败：notification.list|delete|detail.error > notification.error > 内置默认。

注入 HTTP 客户端

默认使用内置 axios 实例。宿主项目可注入自己的实例（复用拦截器、baseURL）：

import axios from 'axios'
import { setHttpClient } from 'element-engin'

const client = axios.create({ baseURL: '/api' })
setHttpClient(client)

在挂载 PageEngine 之前调用。

导出 API

import {
  definePage,
  PageEngine,
  resolveApis,
  resolvePageVisibility,
  validatePageConfig,
  setHttpClient,
  getHttpClient,
} from 'element-engin'

import type { PageConfig, HookContext, EngineInstance } from 'element-engin'

开发

npm install
npm run typecheck   # 类型检查
npm run test        # 单元测试（157+）
npm run build       # 构建 dist（ESM + CJS + d.ts）
npm run verify:build # 验证 exports / types / ESM / CJS 产物
npm run build:verify # build + verify 一键执行
npm run demo        # 启动示例

License

MIT