Admate

中后台 CRUD 前端元框架，极致简洁的基础上不向灵活性妥协，
致力于攻克「页面重复度高，提取公共代码却难以兼顾定制化需求」的痛点。

特性

• Vue 2.6/2.7/3 一体通用
• 符合直觉的行为抽象
• 贴心却不武断的数据与状态管理
• 保姆级收尾工作，无后顾之忧

对比中后台模板

中后台模板如 vue-pure-admin、vue-vben-admin、yudao-ui-admin-vue3 等的定位是中后台一整套解决方案，跟 UI 框架、CSS 框架高度耦合。

视图层面的技术百家争鸣、日新月异，但 CRUD 逻辑是亘古不变的，这正是 Admate 的发力点。

Admate 专注逻辑层面，轻量化、侵入性低，可独立使用，也支持跟任意中后台模板搭配使用。

安装

1npm i admate

外置依赖

• vue
• @vue/composition-api：仅 Vue 2.6 或更早版本需要

阶梯式的配置作用域

全局配置

1. 建立全局适配层

   示例: src/utils/useAdmateAdapter.js

   • 量身打造生命周期行为
   • 列表筛选参数重置 & 参数校验
   • 支持 URL 传参指定筛选项默认值
   • 支持动态生成筛选项默认值，使用场景举例：日期/时间类的参数，如果其默认值为当前最新时刻，重置筛选项时会重置到已过期的时刻

2. 在页面中导入使用

   示例: src/views/Page.vue

模块级配置

1. 按模块拆分适配层，每个模块拥有自己的适配层

   比如:

   • src/views/system/useAdmateAdapter.js
   • src/views/infra/useAdmateAdapter.js

2. 在页面中导入对应模块的适配层

页面级配置

1const { list, listFilterRef, form, faFormDialogRef } = useAdmateAdapter({
2  // ...Admate 配置
3}, {
4  // ...Admate 适配层配置
5})

接口级配置

示例: 接口级请求配置

请求配置

axios

1useAdmate({
2  // Axios 或 Axios 实例
3  // 用于调用接口
4  axios,
5})

axiosConfig

1useAdmate({
2  // Axios 配置
3  axiosConfig: {
4    // 各接口的 URL 前缀
5    urlPrefix: `${import.meta.env.VITE_BASE_URL}/module`,
6    // 列表相关接口
7    list: {
8      // 读取列表
9      read: {},
10    },
11    // 表单相关接口
12    form: {
13      // 新增
14      create: {},
15      // 读取
16      read: {},
17      // 编辑
18      update: {},
19      // 删除
20      delete: {},
21      // 切换状态
22      switch: {},
23    },
24  },
25})

1// 示例: URL 前缀不统一
2
3useAdmate({
4  axiosConfig: {
5    urlPrefix: 'module1',
6    list: {
7      read: {
8        // 如果某个接口的前缀不是 'somepage'，可以在 URL 前面加斜线，即可忽略该前缀
9        url: '/module2/selectOne',
10      }
11    }
12  }
13})

全局请求配置

1// src/http/index.js
2
3const axiosInstance = axios.create({
4  headers: {
5    xxx: 'xxx',
6  },
7})

页面级请求配置

1const headers = {
2  xxx: 'xxx',
3}
4
5const { list, listFilterRef, form, faFormDialogRef } = useAdmateAdapter({
6  axiosConfig: {
7    urlPrefix,
8    list: {
9      read: {
10        url: 'page',
11        headers,
12      },
13    },
14    form: {
15      create: {
16        url: 'create',
17        headers,
18      },
19      read: {
20        url: 'get',
21        headers,
22      },
23      update: {
24        url: 'update',
25        headers,
26      },
27      delete: {
28        url: 'delete',
29        headers,
30      },
31    },
32  },
33})

接口级请求配置

1const { list, listFilterRef, form, faFormDialogRef } = useAdmateAdapter({
2  axiosConfig: {
3    urlPrefix,
4    form: {
5      create: {
6        url: 'create',
7        headers: {
8          xxx: 'xxx',
9        },
10      },
11    },
12  },
13})

RESTful

如果接口地址需要进行动态拼接

1// 配置
2const { list, form } = useAdmate({
3  axiosConfig: {
4    urlPrefix: `${import.meta.env.VITE_BASE_URL}/module`,
5  }
6})
7
8// 使用
9form.open({ method: 'GET', url: id }, 'config')
10form.read({ method: 'GET', url: id }, 'config')
11form.update({ method: 'PUT', url: id }, 'config')
12form.delete({ method: 'DELETE', url: id }, 'config')
13form.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 类型

1<!-- 示例: 局部配置 -->
2
3<script setup>
4import useAdmateAdapter from '@/utils/useAdmateAdapter'
5
6// 过滤 list.value.filter 并转换为 FormData 格式
7FormData.from = (json) => {
8  const formData = new FormData()
9  for (const k in json) {
10    if (![Number.NaN, null, undefined].includes(json[k])) {
11      formData.append(k, json[k])
12    }
13  }
14  return formData
15}
16
17useAdmateAdapter({
18  list: {
19    proxy: {
20      read(readList, trigger) {
21        readList(FormData.from(list.value.filter))
22      },
23    }
24  }
25})
26
27const FormData = window.FormData
28</script>
29
30<template>
31  <el-table>
32    <el-table-column label="操作">
33      <template #default="{ row: { id } }">
34        <el-button @click="form.read(FormData.from({ id }))">
35          查看
36        </el-button>
37        <el-button @click="form.update(FormData.from({ id }))">
38          编辑
39        </el-button>
40        <el-button @click="form.delete(FormData.from({ id }))">
41          删除
42        </el-button>
43      </template>
44    </el-table-column>
45  </el-table>
46
47  <el-dialog>
48    <template #footer>
49      <el-button @click="() => form.submit(FormData.from(form.data))">
50        确 定
51      </el-button>
52    </template>
53  </el-dialog>
54</template>

列表

筛选参数

list.filter

1useAdmate({
2  list: {
3    // 页码的参数名称或路径，必填
4    // 支持属性名，如 `'pageNo'`
5    // 支持属性路径，如 `'page.pageNo'`
6    pageNumberAt: undefined,
7
8    // 可以在这里提供筛选参数的默认值
9    filter: {
10      'pageNumberAt 生成的页码参数名称': 1
11    },
12  },
13})

触发读取

• 点击专用的读取按钮触发
  • ✗ 操作相对繁琐。
  • ✗ 列表数据与筛选条件可能是无关的。可能产生 “当前的列表数据是否基于筛选项？” 的顾虑，导致徒增点击读取按钮的次数。
  • ✓ 想同时设置多个筛选条件时，只调用一次接口，不浪费服务器资源。

1useAdmate({
2  list: {
3    watchFilter: false,
4  }
5})

---

• 改变筛选条件后即时触发
  • ✓ 操作相对简便。
  • ✓ 列表数据与筛选条件即时绑定。
  • ✓ 想同时设置多个筛选条件时，接口会被多次调用，浪费服务器资源 (Admate 已优化)。

1useAdmate({
2  list: {
3    watchFilter: true, // 默认值
4
5    // 防抖间隔，单位毫秒
6    // 如果筛选参数不含 input 类型，可以设置为 0，即不防抖
7    // 翻页不会触发防抖
8    // watchFilter 开启时有效
9    debounce: 300, // 默认值
10  }
11})

列表数据

list.data

1useAdmate({
2  list: {
3    // 列表数据
4    data: [],
5
6    // 指定接口返回值中列表数据的位置
7    // 支持属性名，如 `'data'`
8    // 支持属性路径，如 `'data[0].records'`
9    // 支持 symbol 类型的属性名
10    // 支持 Function，如 `response => response.data`
11    dataAt: undefined,
12
13    // 指定接口返回值中记录总数的位置
14    // 支持属性名，如 `'total'`
15    // 支持属性路径，如 `'data[0].total'`
16    // 支持 symbol 类型的属性名
17    // 支持 Function，如 `response => response.total`
18    totalAt: undefined,
19  }
20})

读取列表

list.read

读取列表，在首次进入页面、列表筛选参数改变、单条记录增删查改后会被调用

1const { list } = useAdmate()
2
3/**
4 * PS: 以下为原始函数签名，如果你配置了 list.proxy.read ，则以 list.proxy.read 为准
5 *
6 * @param {any} [payload = list.filter]
7 * @param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途
8 *   'data': 将 payload 用作请求体参数（请求方式为 POST/PATCH/PUT/DELETE 时默认）
9 *   'params': 将 payload 用作 URL 参数（请求方式为 GET/HEAD 时默认）
10 *   'config': 将 payload 用作请求配置（若 axiosConfig 中已存在对应配置，则与其进行浅合并）
11 * @returns {Promise<any>} 接口返回值
12 */
13list.read() // 手动读取

list.search

重置页码后执行 list.read ，用于筛选条件改变后检索列表

1const { list } = useAdmate()
2
3/**
4 * PS: 以下为原始函数签名，如果你配置了 list.proxy.read ，则以 list.proxy.read 为准
5 *
6 * @param {any} [payload = list.filter]
7 * @param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途
8 *   'data': 将 payload 用作请求体参数（请求方式为 POST/PATCH/PUT/DELETE 时默认）
9 *   'params': 将 payload 用作 URL 参数（请求方式为 GET/HEAD 时默认）
10 *   'config': 将 payload 用作请求配置（若 axiosConfig 中已存在对应配置，则与其进行浅合并）
11 * @returns {Promise<any>} 接口返回值
12 */
13list.search() // 手动检索

list.reset

重置筛选条件后执行 list.read

1const { list } = useAdmate()
2
3/**
4 * PS: 以下为原始函数签名，如果你配置了 list.proxy.reset ，则以 list.proxy.reset 为准
5 *
6 * @param {any} [payload = list.filter]
7 * @param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途
8 *   'data': 将 payload 用作请求体参数（请求方式为 POST/PATCH/PUT/DELETE 时默认）
9 *   'params': 将 payload 用作 URL 参数（请求方式为 GET/HEAD 时默认）
10 *   'config': 将 payload 用作请求配置（若 axiosConfig 中已存在对应配置，则与其进行浅合并）
11 * @returns {Promise<any>} 接口返回值
12 */
13list.reset() // 手动重置

list.proxy.read

你可以使用 list.proxy.read 来代理 list.read，以便在 list.read 前后执行一些操作，或改变 list.read 的行为

1useAdmate({
2  list: {
3    proxy: {
4      /**
5       * @param {Function} readList 被代理的原始 readList
6       * @param {string} trigger 调用动机 可能的值：
7       *   'immediate': 初始化立即查询列表
8       *   'pageNumberChange': 页码改变触发查询列表
9       *   'filterChange': 筛选项（含分页大小）改变触发查询列表
10       *   'create': 表单新增触发查询列表
11       *   'update': 表单编辑触发查询列表
12       *   'delete': 表单删除触发查询列表
13       *   'switch': 表单状态变更触发查询列表
14       */
15      read(readList, trigger) {},
16    },
17  },
18})

1// 示例: 读取列表之前，校验参数
2
3useAdmate({
4  list: {
5    proxy: {
6      read(readList, trigger) {
7        if (trigger === 'filterChange') {
8          listFilterRef.value.validate().then(() => {
9            readList()
10          })
11        }
12        else {
13          readList()
14        }
15      },
16    }
17  }
18})

1// 示例: 单条记录操作成功后，弹出提示
2
3useAdmate({
4  list: {
5    proxy: {
6      read(readList, trigger) {
7        readList()
8        if (['create', 'upadte', 'delete', 'switch'].includes(trigger)) {
9          currentInstance.value.$message.success('操作成功')
10        }
11      },
12    }
13  }
14})

1// 示例: 读取列表后，修改列表数据
2
3const { list } = useAdmate({
4  list: {
5    proxy: {
6      read(readList, trigger) {
7        readList().then((response) => {
8          // response 为 axiosConfig.list.read 的接口返回值
9          list.data = response.data?.filter(v => !v.disabled)
10        })
11      },
12    }
13  }
14})

list.proxy.reset

你可以使用 list.proxy.reset 来代理 list.reset，以便在 list.reset 前后执行一些操作，或改变 list.reset 的行为

1useAdmate({
2  list: {
3    proxy: {
4      /**
5       * @param {Function} resetList 被代理的原始 resetList
6       */
7      reset(resetList) {},
8    },
9  },
10})

1// 示例: 使用 UI 组件库的表单重置函数来重置筛选条件
2
3useAdmate({
4  list: {
5    proxy: {
6      reset(resetList) {
7        listFilterElFormRef.value.resetFields()
8        // 如果分页组件不归属于表单，则表单重置时页码不会被重置，需调用 list.search
9        if (!list.watchFilter) {
10          list.search()
11        }
12      },
13    }
14  }
15})

读取状态

list.loading

axiosConfig.list.read 被调用时值为 true，否则为 false

1<!-- 示例 -->
2
3<script setup>
4import useAdmate from 'admate'
5import { getCurrentInstance } from 'vue'
6
7const { proxy } = getCurrentInstance()
8const { list } = useAdmate()
9
10function handleTable() {
11  list.value.loading = true
12  proxy.$POST('').finally(() => {
13    list.value.loading = false
14  })
15}
16</script>
17
18<template>
19  <el-table v-loading="list.loading" />
20</template>

表单

表单风格

表单默认是对话框/抽屉的风格，但也支持独立页面的风格

对比

• 对话框/抽屉：体验好，割裂感低，表单的开闭不影响父页面状态
• 独立页面：体验较差，从表单返回父页面时，父页面的状态会丢失，比如列表筛选状态

表单显隐

form.show: boolean

[!Tip]

表单关闭时，表单数据自动恢复至初始状态（不是直接清空）

表单数据

form.data

1useAdmate({
2  form: {
3    // 可以在这里提供表单数据的默认值
4    data: {},
5
6    // 在查看、编辑表单时，可能需要调用接口（axiosConfig.form.read）回显表单的数据
7    // dataAt 用于指定接口返回值中表单数据的位置
8    // 支持属性名，如 `'detail'`
9    // 支持属性路径，如 `'data[0].detail'`
10    // 支持 symbol 类型的属性名
11    // 支持 Function，如 `response => response.detail`
12    dataAt: undefined,
13
14    // 接口（axiosConfig.form.read）返回值与 form.data 合并的方式
15    mergeData: 'deep',
16  },
17})

mergeData：

• 'deep'：深合并 (默认)
• 'shallow'：浅合并
• (newFormData: any) => any：自定义合并方式
• false：不合并，直接替换

为什么默认是深合并？

在 Vue 2 中，template 不支持 ?. 语法，要在 template 中判空，代码写起来会非常冗余，通常的做法是在 data 中声明空对象

比如给 form.data 提供默认值：

1<script setup>
2import useAdmate from 'admate'
3
4const { form } = useAdmate({
5  form: {
6    data: {
7      a: {
8        b: {}
9      }
10    }
11  }
12})
13</script>
14
15<template>
16  {{ form.data.a.b.c }}
17</template>

如果 axiosConfig.form.read 的返回值为： { a: {} }

如果与默认值浅合并后将得到： { a: {} } —— 默认值中的对象 b 丢失了，引发空指针异常。

如果与默认值深合并后将得到： { a: { b: {} } } —— 代码正常工作。

1// 示例: 自定义合并方式
2
3import { mergeWith } from 'lodash'
4
5function defaultFormData() {
6  return {
7    a: {
8      b: {}
9    }
10  }
11}
12
13const { form } = useAdmate({
14  form: {
15    data: defaultFormData(),
16    // 接口返回值中嵌套的对象可能为 null，会覆盖默认值中的空对象
17    mergeData(
18      // 接口返回值在通过 form.dataAt 计算过后的值
19      newFormData
20    ) {
21      // Vue 3 中不需要赋值，mergeWith 的改动是响应式的
22      form.data = mergeWith(
23        defaultFormData(),
24        newFormData,
25        (oldObj, newObj) => [undefined, null].includes(newObj) ? oldObj : undefined
26      )
27    },
28  },
29})

表单形态

form.status: 'create' | 'read' | 'update'

表单标题

form.title: string

1// 示例: 根据表态形态生成对应的标题
2
3import { computed } from 'vue'
4
5const { form } = useAdmate({
6  form: {
7    title: computed(() => ({ create: '新增', read: '查看', update: '编辑' }[form.status])),
8  },
9})

新增

打开表单，提交时会调用 axiosConfig.form.create

1const { form } = useAdmate()
2
3form.create()
4
5// 等价于：将表单形态设置为“新增”，然后打开表单
6form.status = 'create'
7form.open()

复制新增

表单的初始数据不是空白，而是复制一条已有的记录

1. 打开表单时，和查看/编辑一样，需要调接口回显
2. 提交表单时调用的是新增的接口

1const { form } = useAdmate()
2
3form.create(row)
4
5// 等价于：将表单形态设置为“新增”，然后打开表单并传参
6form.status = 'create'
7form.open(row)

查看

打开表单，并调用 axiosConfig.form.read 回显表单内容

1const { form } = useAdmate()
2
3form.read()
4
5// 等价于：将表单形态设置为“查看”，然后打开表单
6form.status = 'read'
7/**
8 * PS: 以下为原始 openForm 的函数签名，如果你配置了 form.proxy.open ，则以 form.proxy.open 为准
9 *
10 * @param {any} [payload] 如果 payload 不为空，则会调用 axiosConfig.form.read
11 * @param {'data'|'params'|'config'|'cache'} [payloadAs] 指定 payload 的用途
12 *   'data': 将 payload 用作请求体参数（请求方式为 POST/PATCH/PUT/DELETE 时默认）
13 *   'params': 将 payload 用作 URL 参数（请求方式为 GET/HEAD 时默认）
14 *   'config': 将 payload 用作请求配置（若 axiosConfig 中已存在对应配置，则与其进行浅合并）
15 *   'cache': 将 payload 直接用作表单数据（不调用读取单条记录的接口）
16 * @returns {Promise<any>} axiosConfig.form.read 的返回值
17 */
18form.open()

编辑

打开表单，并调用 axiosConfig.form.read 回显表单内容，提交时会调用 axiosConfig.form.update

1const { form } = useAdmate()
2
3form.update()
4
5// 等价于：将表单形态设置为“编辑”，然后打开表单
6form.status = 'update'
7/**
8 * PS: 以下为原始 form.open 的函数签名，如果你配置了 form.proxy.open ，则以 form.proxy.open 为准
9 *
10 * @param {any} [payload] 如果 payload 不为空，则会调用 axiosConfig.form.read
11 * @param {'data'|'params'|'config'|'cache'} [payloadAs] 指定 payload 的用途
12 *   'data': 将 payload 用作请求配置的 `data` 参数（请求方式为 POST / PATCH / PUT / DELETE 时默认）
13 *   'params': 将 payload 用作请求配置的 `params` 参数（请求方式为 GET / HEAD 时默认）
14 *   'config': 将 payload 仅用于构建请求配置（详见 RESTful 章节）
15 *   'cache': 将 payload 直接用作表单数据（不调用读取单条记录的接口）
16 * @returns {Promise<any>} axiosConfig.form.read 的返回值
17 */
18form.open()

删除

1const { form } = useAdmate()
2
3/**
4 * @param {any} [payload]
5 * @param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途
6 *   'data': 将 payload 用作请求体参数（请求方式为 POST/PATCH/PUT/DELETE 时默认）
7 *   'params': 将 payload 用作 URL 参数（请求方式为 GET/HEAD 时默认）
8 *   'config': 将 payload 用作请求配置（若 axiosConfig 中已存在对应配置，则与其进行浅合并）
9 * @returns {Promise<any>} axiosConfig.form.delete 的返回值
10 */
11form.delete()

[!Tip]

删除非首页最后一条记录时，自动切换至上一页

状态变更

状态变更有三种方式：

1. 后端提供一个统一的接口，传参指定新的状态

1<script setup>
2import useAdmate from 'admate'
3
4const { form } = useAdmate()
5
6/**
7 * @param {any} [payload]
8 * @param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途
9 *   'data': 将 payload 用作请求体参数（请求方式为 POST/PATCH/PUT/DELETE 时默认）
10 *   'params': 将 payload 用作 URL 参数（请求方式为 GET/HEAD 时默认）
11 *   'config': 将 payload 用作请求配置（若 axiosConfig 中已存在对应配置，则与其进行浅合并）
12 * @returns {Promise<any>} axiosConfig.form.switch 的返回值
13 */
14form.switch()
15</script>
16
17<template>
18  <el-table>
19    <el-table-column
20      label="操作"
21      align="center"
22    >
23      <template #default="{ row: { id, status } }">
24        <el-switch @change="form.switch({ id, status: status ^ 1 })" />
25      </template>
26    </el-table-column>
27  </el-table>
28</template>

2. 后端提供启用和停用两个接口

1<script setup>
2import useAdmate from 'admate'
3
4const { form } = useAdmate()
5
6/**
7 * @param {any} [payload]
8 * @param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途
9 *   'data': 将 payload 用作请求体参数（请求方式为 POST/PATCH/PUT/DELETE 时默认）
10 *   'params': 将 payload 用作 URL 参数（请求方式为 GET/HEAD 时默认）
11 *   'config': 将 payload 用作请求配置（若 axiosConfig 中已存在对应配置，则与其进行浅合并）
12 * @returns {Promise<any>} axiosConfig.form.switch 的返回值
13 */
14form.switch()
15</script>
16
17<template>
18  <el-table>
19    <el-table-column
20      label="操作"
21      align="center"
22    >
23      <template #default="{ row: { id, status } }">
24        <el-switch
25          @change="form.switch({ method: 'PUT', url: `${status === 0 ? 'enable' : `disable`}/${id}` }, 'config')"
26        />
27      </template>
28    </el-table-column>
29  </el-table>
30</template>

3. 后端未提供独立的接口，使用编辑接口改变状态

1<script setup>
2import useAdmate from 'admate'
3
4const { form } = useAdmate({
5  axiosConfig: {
6    form: {
7      update: {
8        // ...
9      },
10      switch: {
11        // 按编辑接口进行配置
12      },
13    }
14  },
15})
16
17/**
18 * @param {any} [payload]
19 * @param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途
20 *   'data': 将 payload 用作请求体参数（请求方式为 POST/PATCH/PUT/DELETE 时默认）
21 *   'params': 将 payload 用作 URL 参数（请求方式为 GET/HEAD 时默认）
22 *   'config': 将 payload 用作请求配置（若 axiosConfig 中已存在对应配置，则与其进行浅合并）
23 * @returns {Promise<any>} axiosConfig.form.switch 的返回值
24 */
25form.switch()
26</script>
27
28<template>
29  <el-table>
30    <el-table-column
31      label="操作"
32      align="center"
33    >
34      <template #default="{ row }">
35        <el-switch @change="form.switch({ ...row, status: row.status ^ 1 })" />
36      </template>
37    </el-table-column>
38  </el-table>
39</template>

打开表单

form.open

打开表单，函数签名要分情况：

• 新增时
• 查看时
• 编辑时

form.proxy.open

你可以使用 form.proxy.open 来代理 form.open，以便在 form.open 前后执行一些操作，或改变 form.open 的行为

1useAdmate({
2  form: {
3    proxy: {
4      /**
5       * @param {Function} openForm 被代理的原始 openForm
6       * @returns {Promise<object> | object | void} object 为打开表单后 form 的终态
7       */
8      open(openForm) {},
9    }
10  }
11})

1// 示例: 回显表单后，修改表单数据
2
3const { form } = useAdmate({
4  form: {
5    proxy: {
6      open(openForm) {
7        // 新增时 openForm 没有返回值
8        return new Promise((resolve, reject) => {
9          openForm()?.then((response) => {
10            // response 为 axiosConfig.r 的接口返回值
11            // 修改表单数据
12            form.data.status = 1
13            resolve()
14          }).catch((e) => {
15            reject(e)
16          })
17        })
18      },
19    }
20  }
21})

1// 示例: 回显表单后，清除校验
2
3useAdmate({
4  form: {
5    proxy: {
6      open(openForm) {
7        return new Promise((resolve, reject) => {
8          openForm()?.finally(() => {
9            formRef.value.clearValidate()
10          }).then(() => {
11            resolve()
12          }).catch((e) => {
13            reject(e)
14          })
15        })
16      },
17    }
18  }
19})

1// 示例: 回显表单后，自定义表单的开闭和读取状态
2useAdmate({
3  form: {
4    proxy: {
5      open(openForm) {
6        return new Promise((resolve, reject) => {
7          // 可以在 finally 中 resolve
8          openForm().then(() => {
9            // 回显成功后，默认停止加载
10            resolve({
11              loading: false,
12            })
13          }).catch(() => {
14            // 回显失败后，默认关闭表单并停止加载
15            resolve({
16              show: false,
17              loading: false,
18            })
19          })
20        })
21      }
22    }
23  }
24})
25
26// 也可以返回一个对象（如果没有异步操作）
27useAdmate({
28  form: {
29    proxy: {
30      open(openForm) {
31        return {
32          loading: false
33        }
34      }
35    }
36  }
37})

读取状态

form.loading

axiosConfig.form.read 被调用时值为 true，否则为 false

不能将该值当作表单回显结束的标志，因为复用列表数据时不会调用 axiosConfig.r

1<!-- 示例 -->
2
3<script setup>
4import useAdmate from 'admate'
5
6const { form } = useAdmate()
7</script>
8
9<template>
10  <el-dialog>
11    <el-form v-loading="form.loading" />
12  </el-dialog>
13</template>

提交表单

form.submit

提交表单，新增时调用 axiosConfig.form.create，编辑时调用 axiosConfig.form.update

1const { form } = useAdmate()
2
3/**
4 * PS: 以下为原始 form.submit 的函数签名，如果你配置了 form.proxy.submit ，则以 form.proxy.submit 为准
5 *
6 * @param {any} [payload = form.data]
7 * @param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途
8 *   'data': 将 payload 用作请求体参数（请求方式为 POST/PATCH/PUT/DELETE 时默认）
9 *   'params': 将 payload 用作 URL 参数（请求方式为 GET/HEAD 时默认）
10 *   'config': 将 payload 用作请求配置（若 axiosConfig 中已存在对应配置，则与其进行浅合并）
11 * @returns {Promise<any>} 接口返回值
12 */
13form.submit()

form.proxy.submit

你可以使用 form.proxy.submit 来代理 form.submit ，以便在 form.submit 前后执行一些操作，或改变 form.submit 的行为

1useAdmate({
2  form: {
3    proxy: {
4      /**
5       * @param {Function} submitForm 被代理的原始 submitForm
6       * @returns {Promise<object> | object | void} object 为提交表单后 form 的终态
7       */
8      submit(submitForm) {}
9    }
10  }
11})

1// 示例: 指定提交参数
2
3form.submit({
4  ...form.data,
5  status: 1,
6})
7
8// form.submit 被代理时
9useAdmate({
10  form: {
11    proxy: {
12      submit(submitForm) {
13        return new Promise((resolve, reject) => {
14          submitForm({
15            ...form.data,
16            status: 1,
17          }).then(() => {
18            resolve()
19          }).catch((e) => {
20            reject(e)
21          })
22        })
23      }
24    }
25  }
26})

1// 示例: 提交前校验表单
2
3useAdmate({
4  form: {
5    proxy: {
6      submit(submitForm) {
7        return new Promise((resolve, reject) => {
8          formRef.value.validate().then(() => {
9            submitForm().then(() => {
10              resolve()
11            }).catch((e) => {
12              reject(e)
13            })
14          })
15        })
16      }
17    }
18  }
19})

1// 示例: 提交表单后，自定义表单的开闭和提交状态
2
3// 返回一个 promise
4useAdmate({
5  form: {
6    proxy: {
7      submit(submitForm) {
8        return new Promise((resolve, reject) => {
9          formRef.value.validate().then(() => {
10            submitForm().then(() => {
11              // 提交成功后，默认关闭表单，并停止加载
12              resolve({
13                show: false,
14                submitting: false,
15              })
16            }).catch(() => {
17              // 提交失败后，默认仅停止加载
18              resolve({
19                show: true,
20                submitting: false,
21              })
22            })
23          })
24        })
25      }
26    }
27  }
28})
29
30// 也可以返回一个对象（如果没有异步操作）
31useAdmate({
32  form: {
33    proxy: {
34      submit(submitForm) {
35        return {
36          show: false,
37          submitting: false,
38        }
39      }
40    }
41  }
42})

提交状态

form.submitting

axiosConfig.form.create 或 axiosConfig.form.update 被调用时值为 true，否则为 false

1<!-- 示例 -->
2
3<script setup>
4import useAdmate from 'admate'
5
6const { form } = useAdmate()
7</script>
8
9<template>
10  <el-dialog>
11    <template #footer>
12      <el-button :loading="form.submitting">
13        确 定
14      </el-button>
15    </template>
16  </el-dialog>
17</template>

生命周期

读取列表

1useAdmateAdapter({}, {
2  onListRead(res, trigger) {
3    // res 为接口返回值，trigger 为调用动机
4    // 可访问 this（组件实例）
5  }
6})

打开 / 读取表单

• 读取表单前

1watch(() => form.value.show, (n) => {
2  if (n) {
3    // 打开表单
4  }
5})

• 读取表单后

1// 示例: 适配层提供 onFormOpened
2
3useAdmateAdapter({}, {
4  onFormOpened(res) {
5    // res 为接口返回值（新增时为空）
6    // 可访问 this（组件实例）
7  }
8})

• 读取表单后 (不含新增)

1// 示例: 适配层提供 onFormRead
2
3useAdmateAdapter({}, {
4  onFormRead(res) {
5    // res 为接口返回值
6    // 可访问 this（组件实例）
7  }
8})

提交表单

• 提交表单前

1useAdmateAdapter({}, {
2  onFormSubmit(form) {
3    // 可访问 this（组件实例）
4  }
5})

• 提交表单后

1useAdmateAdapter({}, {
2  onFormSubmitted(res) {
3    // res 为接口返回值
4    // 可访问 this（组件实例）
5  }
6})

关闭表单

1watch(() => form.value.show, (n) => {
2  if (!n) {
3    // 关闭表单
4  }
5})

场景

表单是子组件

将表单抽离为子组件

示例

表单是独立页面

操作单条记录时，跳转到专用的表单页面，操作完毕后返回

示例

只有表单没有列表

表单默认打开，且无法关闭，通常用于列表中只有一条数据，故列表被省略的场景

示例

嵌套使用

当前页面的对话框也使用 Admate

示例

更新日志

各版本详细改动请参考 release notes