中后台 CRUD 前端元框架,极致简洁的基础上不向灵活性妥协,
致力于攻克「页面重复度高,提取公共代码却难以兼顾定制化需求」的痛点。
特性
- Vue 2.6/2.7/3 一体通用
- 符合直觉的行为抽象
- 贴心却不武断的数据与状态管理
- 保姆级收尾工作,无后顾之忧
对比中后台模板
中后台模板如 vue-pure-admin、vue-vben-admin、yudao-ui-admin-vue3 等的定位是中后台一整套解决方案,跟 UI 框架、CSS 框架高度耦合。
视图层面的技术百家争鸣、日新月异,但 CRUD 逻辑是亘古不变的,这正是 Admate 的发力点。
Admate 专注逻辑层面,轻量化、侵入性低,可独立使用,也支持跟任意中后台模板搭配使用。
安装
npm i admate
外置依赖
- vue
@vue/composition-api:仅 Vue 2.6 或更早版本需要
阶梯式的配置作用域
全局配置
模块级配置
-
按模块拆分适配层,每个模块拥有自己的适配层
比如:
- src/views/system/useAdmateAdapter.js
- src/views/infra/useAdmateAdapter.js
-
在页面中导入对应模块的适配层
页面级配置
const { list, listFilterRef, form, faFormDialogRef } = useAdmateAdapter({
}, {
})
接口级配置
示例: 接口级请求配置
请求配置
axios
useAdmate({
axios,
})
axiosConfig
useAdmate({
axiosConfig: {
urlPrefix: `${import.meta.env.VITE_BASE_URL}/module`,
list: {
read: {},
},
form: {
create: {},
read: {},
update: {},
delete: {},
switch: {},
},
},
})
useAdmate({
axiosConfig: {
urlPrefix: 'module1',
list: {
read: {
url: '/module2/selectOne',
}
}
}
})
全局请求配置
const axiosInstance = axios.create({
headers: {
xxx: 'xxx',
},
})
页面级请求配置
const headers = {
xxx: 'xxx',
}
const { list, listFilterRef, form, faFormDialogRef } = useAdmateAdapter({
axiosConfig: {
urlPrefix,
list: {
read: {
url: 'page',
headers,
},
},
form: {
create: {
url: 'create',
headers,
},
read: {
url: 'get',
headers,
},
update: {
url: 'update',
headers,
},
delete: {
url: 'delete',
headers,
},
},
},
})
接口级请求配置
const { list, listFilterRef, form, faFormDialogRef } = useAdmateAdapter({
axiosConfig: {
urlPrefix,
form: {
create: {
url: 'create',
headers: {
xxx: 'xxx',
},
},
},
},
})
RESTful
如果接口地址需要进行动态拼接
const { list, form } = useAdmate({
axiosConfig: {
urlPrefix: `${import.meta.env.VITE_BASE_URL}/module`,
}
})
form.open({ method: 'GET', url: id }, 'config')
form.read({ method: 'GET', url: id }, 'config')
form.update({ method: 'PUT', url: id }, 'config')
form.delete({ method: 'DELETE', url: id }, 'config')
form.switch({ method: 'PUT', url: id }, 'config')
FormData
Axios
的 data 默认以 application/json
作为 MIME type,如果你需要使用 multipart/form-data
:
给你的 Axios
配置 transformRequest
、headers['Content-Type']
list.read
、list.search
、list.reset
、form.open
、form.delete
、form.switch
、form.submit
的参数 1 均支持 FormData 类型
<!-- 示例: 局部配置 -->
<script setup>
import useAdmateAdapter from '@/utils/useAdmateAdapter'
// 过滤 list.value.filter 并转换为 FormData 格式
FormData.from = (json) => {
const formData = new FormData()
for (const k in json) {
if (![Number.NaN, null, undefined].includes(json[k])) {
formData.append(k, json[k])
}
}
return formData
}
useAdmateAdapter({
list: {
proxy: {
read(readList, trigger) {
readList(FormData.from(list.value.filter))
},
}
}
})
const FormData = window.FormData
</script>
<template>
<el-table>
<el-table-column label="操作">
<template #default="{ row: { id } }">
<el-button @click="form.read(FormData.from({ id }))">
查看
</el-button>
<el-button @click="form.update(FormData.from({ id }))">
编辑
</el-button>
<el-button @click="form.delete(FormData.from({ id }))">
删除
</el-button>
</template>
</el-table-column>
</el-table>
<el-dialog>
<template #footer>
<el-button @click="() => form.submit(FormData.from(form.data))">
确 定
</el-button>
</template>
</el-dialog>
</template>
列表
筛选参数
list.filter
useAdmate({
list: {
pageNumberAt: undefined,
filter: {
'pageNumberAt 生成的页码参数名称': 1
},
},
})
触发读取
- 点击专用的读取按钮触发
- ✗ 操作相对繁琐。
- ✗ 列表数据与筛选条件可能是无关的。可能产生 “当前的列表数据是否基于筛选项?” 的顾虑,导致徒增点击读取按钮的次数。
- ✓ 想同时设置多个筛选条件时,只调用一次接口,不浪费服务器资源。
useAdmate({
list: {
watchFilter: false,
}
})
- 改变筛选条件后即时触发
- ✓ 操作相对简便。
- ✓ 列表数据与筛选条件即时绑定。
- ✓
想同时设置多个筛选条件时,接口会被多次调用,浪费服务器资源 (Admate 已优化)。
useAdmate({
list: {
watchFilter: true,
debounce: 300,
}
})
列表数据
list.data
useAdmate({
list: {
data: [],
dataAt: undefined,
totalAt: undefined,
}
})
读取列表
list.read
读取列表,在首次进入页面、列表筛选参数改变、单条记录增删查改后会被调用
const { list } = useAdmate()
list.read()
list.search
重置页码后执行 list.read
,用于筛选条件改变后检索列表
const { list } = useAdmate()
list.search()
list.reset
重置筛选条件后执行 list.read
const { list } = useAdmate()
list.reset()
list.proxy.read
你可以使用 list.proxy.read
来代理 list.read
,以便在 list.read
前后执行一些操作,或改变 list.read
的行为
useAdmate({
list: {
proxy: {
read(readList, trigger) {},
},
},
})
useAdmate({
list: {
proxy: {
read(readList, trigger) {
if (trigger === 'filterChange') {
listFilterRef.value.validate().then(() => {
readList()
})
}
else {
readList()
}
},
}
}
})
useAdmate({
list: {
proxy: {
read(readList, trigger) {
readList()
if (['create', 'upadte', 'delete', 'switch'].includes(trigger)) {
currentInstance.value.$message.success('操作成功')
}
},
}
}
})
const { list } = useAdmate({
list: {
proxy: {
read(readList, trigger) {
readList().then((response) => {
list.data = response.data?.filter(v => !v.disabled)
})
},
}
}
})
list.proxy.reset
你可以使用 list.proxy.reset
来代理 list.reset
,以便在 list.reset
前后执行一些操作,或改变 list.reset
的行为
useAdmate({
list: {
proxy: {
reset(resetList) {},
},
},
})
useAdmate({
list: {
proxy: {
reset(resetList) {
listFilterElFormRef.value.resetFields()
if (!list.watchFilter) {
list.search()
}
},
}
}
})
读取状态
list.loading
axiosConfig.list.read
被调用时值为 true
,否则为 false
<!-- 示例 -->
<script setup>
import useAdmate from 'admate'
import { getCurrentInstance } from 'vue'
const { proxy } = getCurrentInstance()
const { list } = useAdmate()
function handleTable() {
list.value.loading = true
proxy.$POST('').finally(() => {
list.value.loading = false
})
}
</script>
<template>
<el-table v-loading="list.loading" />
</template>
表单
表单风格
表单默认是对话框/抽屉的风格,但也支持独立页面的风格
对比
- 对话框/抽屉:体验好,割裂感低,表单的开闭不影响父页面状态
- 独立页面:体验较差,从表单返回父页面时,父页面的状态会丢失,比如列表筛选状态
表单显隐
form.show: boolean
[!Tip]
表单关闭时,表单数据自动恢复至初始状态(不是直接清空)
表单数据
form.data
useAdmate({
form: {
data: {},
dataAt: undefined,
mergeData: 'deep',
},
})
mergeData:
'deep'
:深合并 (默认)
'shallow'
:浅合并
(newFormData: any) => any
:自定义合并方式
false
:不合并,直接替换
为什么默认是深合并?
在 Vue 2 中,template 不支持 ?.
语法,要在 template 中判空,代码写起来会非常冗余,通常的做法是在 data 中声明空对象
比如给 form.data 提供默认值:
<script setup>
import useAdmate from 'admate'
const { form } = useAdmate({
form: {
data: {
a: {
b: {}
}
}
}
})
</script>
<template>
{{ form.data.a.b.c }}
</template>
如果 axiosConfig.form.read 的返回值为:
{ a: {} }
如果与默认值浅合并后将得到:
{ a: {} }
—— 默认值中的对象 b 丢失了,引发空指针异常。
如果与默认值深合并后将得到:
{ a: { b: {} } }
—— 代码正常工作。
import { mergeWith } from 'lodash'
function defaultFormData() {
return {
a: {
b: {}
}
}
}
const { form } = useAdmate({
form: {
data: defaultFormData(),
mergeData(
newFormData
) {
form.data = mergeWith(
defaultFormData(),
newFormData,
(oldObj, newObj) => [undefined, null].includes(newObj) ? oldObj : undefined
)
},
},
})
表单形态
form.status: 'create' | 'read' | 'update'
表单标题
form.title: string
import { computed } from 'vue'
const { form } = useAdmate({
form: {
title: computed(() => ({ create: '新增', read: '查看', update: '编辑' }[form.status])),
},
})
新增
打开表单,提交时会调用 axiosConfig.form.create
const { form } = useAdmate()
form.create()
form.status = 'create'
form.open()
复制新增
表单的初始数据不是空白,而是复制一条已有的记录
- 打开表单时,和查看/编辑一样,需要调接口回显
- 提交表单时调用的是新增的接口
const { form } = useAdmate()
form.create(row)
form.status = 'create'
form.open(row)
查看
打开表单,并调用 axiosConfig.form.read
回显表单内容
const { form } = useAdmate()
form.read()
form.status = 'read'
form.open()
编辑
打开表单,并调用 axiosConfig.form.read
回显表单内容,提交时会调用 axiosConfig.form.update
const { form } = useAdmate()
form.update()
form.status = 'update'
form.open()
删除
const { form } = useAdmate()
form.delete()
[!Tip]
删除非首页最后一条记录时,自动切换至上一页
状态变更
状态变更有三种方式:
<script setup>
import useAdmate from 'admate'
const { form } = useAdmate()
/**
* @param {any} [payload]
* @param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途
* 'data': 将 payload 用作请求体参数(请求方式为 POST/PATCH/PUT/DELETE 时默认)
* 'params': 将 payload 用作 URL 参数(请求方式为 GET/HEAD 时默认)
* 'config': 将 payload 用作请求配置(若 axiosConfig 中已存在对应配置,则与其进行浅合并)
* @returns {Promise<any>} axiosConfig.form.switch 的返回值
*/
form.switch()
</script>
<template>
<el-table>
<el-table-column
label="操作"
align="center"
>
<template #default="{ row: { id, status } }">
<el-switch @change="form.switch({ id, status: status ^ 1 })" />
</template>
</el-table-column>
</el-table>
</template>
<script setup>
import useAdmate from 'admate'
const { form } = useAdmate()
/**
* @param {any} [payload]
* @param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途
* 'data': 将 payload 用作请求体参数(请求方式为 POST/PATCH/PUT/DELETE 时默认)
* 'params': 将 payload 用作 URL 参数(请求方式为 GET/HEAD 时默认)
* 'config': 将 payload 用作请求配置(若 axiosConfig 中已存在对应配置,则与其进行浅合并)
* @returns {Promise<any>} axiosConfig.form.switch 的返回值
*/
form.switch()
</script>
<template>
<el-table>
<el-table-column
label="操作"
align="center"
>
<template #default="{ row: { id, status } }">
<el-switch
@change="form.switch({ method: 'PUT', url: `${status === 0 ? 'enable' : `disable`}/${id}` }, 'config')"
/>
</template>
</el-table-column>
</el-table>
</template>
<script setup>
import useAdmate from 'admate'
const { form } = useAdmate({
axiosConfig: {
form: {
update: {
// ...
},
switch: {
// 按编辑接口进行配置
},
}
},
})
/**
* @param {any} [payload]
* @param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途
* 'data': 将 payload 用作请求体参数(请求方式为 POST/PATCH/PUT/DELETE 时默认)
* 'params': 将 payload 用作 URL 参数(请求方式为 GET/HEAD 时默认)
* 'config': 将 payload 用作请求配置(若 axiosConfig 中已存在对应配置,则与其进行浅合并)
* @returns {Promise<any>} axiosConfig.form.switch 的返回值
*/
form.switch()
</script>
<template>
<el-table>
<el-table-column
label="操作"
align="center"
>
<template #default="{ row }">
<el-switch @change="form.switch({ ...row, status: row.status ^ 1 })" />
</template>
</el-table-column>
</el-table>
</template>
打开表单
form.open
打开表单,函数签名要分情况:
form.proxy.open
你可以使用 form.proxy.open
来代理 form.open
,以便在 form.open
前后执行一些操作,或改变 form.open
的行为
useAdmate({
form: {
proxy: {
open(openForm) {},
}
}
})
const { form } = useAdmate({
form: {
proxy: {
open(openForm) {
return new Promise((resolve, reject) => {
openForm()?.then((response) => {
form.data.status = 1
resolve()
}).catch((e) => {
reject(e)
})
})
},
}
}
})
useAdmate({
form: {
proxy: {
open(openForm) {
return new Promise((resolve, reject) => {
openForm()?.finally(() => {
formRef.value.clearValidate()
}).then(() => {
resolve()
}).catch((e) => {
reject(e)
})
})
},
}
}
})
useAdmate({
form: {
proxy: {
open(openForm) {
return new Promise((resolve, reject) => {
openForm().then(() => {
resolve({
loading: false,
})
}).catch(() => {
resolve({
show: false,
loading: false,
})
})
})
}
}
}
})
useAdmate({
form: {
proxy: {
open(openForm) {
return {
loading: false
}
}
}
}
})
读取状态
form.loading
axiosConfig.form.read
被调用时值为 true
,否则为 false
不能将该值当作表单回显结束的标志,因为复用列表数据时不会调用 axiosConfig.r
<!-- 示例 -->
<script setup>
import useAdmate from 'admate'
const { form } = useAdmate()
</script>
<template>
<el-dialog>
<el-form v-loading="form.loading" />
</el-dialog>
</template>
提交表单
form.submit
提交表单,新增时调用 axiosConfig.form.create
,编辑时调用 axiosConfig.form.update
const { form } = useAdmate()
form.submit()
form.proxy.submit
你可以使用 form.proxy.submit
来代理 form.submit
,以便在 form.submit
前后执行一些操作,或改变 form.submit
的行为
useAdmate({
form: {
proxy: {
submit(submitForm) {}
}
}
})
form.submit({
...form.data,
status: 1,
})
useAdmate({
form: {
proxy: {
submit(submitForm) {
return new Promise((resolve, reject) => {
submitForm({
...form.data,
status: 1,
}).then(() => {
resolve()
}).catch((e) => {
reject(e)
})
})
}
}
}
})
useAdmate({
form: {
proxy: {
submit(submitForm) {
return new Promise((resolve, reject) => {
formRef.value.validate().then(() => {
submitForm().then(() => {
resolve()
}).catch((e) => {
reject(e)
})
})
})
}
}
}
})
useAdmate({
form: {
proxy: {
submit(submitForm) {
return new Promise((resolve, reject) => {
formRef.value.validate().then(() => {
submitForm().then(() => {
resolve({
show: false,
submitting: false,
})
}).catch(() => {
resolve({
show: true,
submitting: false,
})
})
})
})
}
}
}
})
useAdmate({
form: {
proxy: {
submit(submitForm) {
return {
show: false,
submitting: false,
}
}
}
}
})
提交状态
form.submitting
axiosConfig.form.create
或 axiosConfig.form.update
被调用时值为 true
,否则为 false
<!-- 示例 -->
<script setup>
import useAdmate from 'admate'
const { form } = useAdmate()
</script>
<template>
<el-dialog>
<template #footer>
<el-button :loading="form.submitting">
确 定
</el-button>
</template>
</el-dialog>
</template>
生命周期
读取列表
useAdmateAdapter({}, {
onListRead(res, trigger) {
}
})
打开 / 读取表单
watch(() => form.value.show, (n) => {
if (n) {
}
})
useAdmateAdapter({}, {
onFormOpened(res) {
}
})
useAdmateAdapter({}, {
onFormRead(res) {
}
})
提交表单
useAdmateAdapter({}, {
onFormSubmit(form) {
}
})
useAdmateAdapter({}, {
onFormSubmitted(res) {
}
})
关闭表单
watch(() => form.value.show, (n) => {
if (!n) {
}
})
场景
表单是子组件
将表单抽离为子组件
示例
表单是独立页面
操作单条记录时,跳转到专用的表单页面,操作完毕后返回
示例
只有表单没有列表
表单默认打开,且无法关闭,通常用于列表中只有一条数据,故列表被省略的场景
示例
嵌套使用
当前页面的对话框也使用 Admate
示例
更新日志
各版本详细改动请参考 release notes