Admate

特性

对比中后台模板

安装

npm i admate

外置依赖

阶梯式的配置作用域

全局配置

模块级配置

页面级配置

const{ list, listFilterRef, form, faFormDialogRef}=useAdmateAdapter({// ...Admate 配置},{// ...Admate 适配层配置})

接口级配置

请求配置

axios

useAdmate({// Axios 或 Axios 实例// 用于调用接口  axios,})

axiosConfig

useAdmate({// Axios 配置axiosConfig:{// 各接口的 URL 前缀urlPrefix:`${import.meta.env.VITE_BASE_URL}/module`,// 列表相关接口list:{// 读取列表read:{},},// 表单相关接口form:{// 新增create:{},// 读取read:{},// 编辑update:{},// 删除delete:{},// 切换状态switch:{},},},})

// 示例: URL 前缀不统一useAdmate({axiosConfig:{urlPrefix:'module1',list:{read:{// 如果某个接口的前缀不是 'somepage'，可以在 URL 前面加斜线，即可忽略该前缀url:'/module2/selectOne',}}}})

全局请求配置

// src/http/index.jsconstaxiosInstance=axios.create({headers:{xxx:'xxx',},})

页面级请求配置

constheaders={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:{read:({ id})=>({method:'GET',url:id,}),update:({ id})=>({method:'PUT',url:id,}),delete:({ id})=>({method:'DELETE',url:id,}),switch:({ id})=>({method:'PUT',url:id,}),},}})// 使用form.open({id:1},'config')form.read({id:1},'config')form.update({id:1},'config')form.delete({id:1},'config')form.switch({id:1},'config')

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>

列表

筛选参数

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

触发读取

useAdmate({list:{watchFilter:false,}})

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

列表数据

useAdmate({list:{// 列表数据data:[],// 指定接口返回值中列表数据的位置// 支持属性名，如 `'data'`// 支持属性路径，如 `'data[0].records'`// 支持 symbol 类型的属性名// 支持 Function，如 `response => response.data`dataAt:undefined,// 指定接口返回值中记录总数的位置// 支持属性名，如 `'total'`// 支持属性路径，如 `'data[0].total'`// 支持 symbol 类型的属性名// 支持 Function，如 `response => response.total`totalAt:undefined,}})

读取列表

list.read

const{ list}=useAdmate()/** * PS: 以下为原始函数签名，如果你配置了 list.proxy.read ，则以 list.proxy.read 为准 * *@param {any} [payload = list.filter] *@param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途 *@returns {Promise<any>} 接口返回值 */list.read()// 手动读取

list.search

const{ list}=useAdmate()/** * PS: 以下为原始函数签名，如果你配置了 list.proxy.read ，则以 list.proxy.read 为准 * *@param {any} [payload = list.filter] *@param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途 *@returns {Promise<any>} 接口返回值 */list.search()// 手动检索

list.reset

const{ list}=useAdmate()/** * PS: 以下为原始函数签名，如果你配置了 list.proxy.reset ，则以 list.proxy.reset 为准 * *@param {any} [payload = list.filter] *@param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途 *@returns {Promise<any>} 接口返回值 */list.reset()// 手动重置

list.proxy.read

useAdmate({list:{proxy:{/**       *@param {Function} readList 被代理的原始 readList       *@param {string} trigger 调用动机 可能的值：       *   'immediate': 初始化立即查询列表       *   'pageNumberChange': 页码改变触发查询列表       *   'filterChange': 筛选项（含分页大小）改变触发查询列表       *   'create': 表单新增触发查询列表       *   'update': 表单编辑触发查询列表       *   'delete': 表单删除触发查询列表       *   'switch': 表单状态变更触发查询列表       */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)=>{// response 为 axiosConfig.list.read 的接口返回值list.data=response.data?.filter(v=>!v.disabled)})},}}})

list.proxy.reset

useAdmate({list:{proxy:{/**       *@param {Function} resetList 被代理的原始 resetList       */reset(resetList){},},},})

// 示例: 使用 UI 组件库的表单重置函数来重置筛选条件useAdmate({list:{proxy:{reset(resetList){listFilterElFormRef.value.resetFields()// 如果分页组件不归属于表单，则表单重置时页码不会被重置，需调用 list.searchif(!list.watchFilter){list.search()}},}}})

读取状态

<!-- 示例 --><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>

表单

表单风格

表单显隐

Tip

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

表单数据

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

<script setup>importuseAdmatefrom'admate'const {form }=useAdmate({  form: {    data: {      a: {        b: {}      }    }  }})</script><template>  {{ form.data.a.b.c }}</template>

// 示例: 自定义合并方式import{mergeWith}from'lodash'functiondefaultFormData(){return{a:{b:{}}}}const{ form}=useAdmate({form:{data:defaultFormData(),// 接口返回值中嵌套的对象可能为 null，会覆盖默认值中的空对象mergeData(// 接口返回值在通过 form.dataAt 计算过后的值newFormData){// Vue 3 中不需要赋值，mergeWith 的改动是响应式的form.data=mergeWith(defaultFormData(),newFormData,(oldObj,newObj)=>[undefined,null].includes(newObj) ?oldObj :undefined)},},})

表单形态

表单标题

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

新增

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

复制新增

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

查看

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

编辑

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

删除

const{ form}=useAdmate()/** *@param {any} [payload] *@param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途 *   'data': 将 payload 用作请求配置的 `data` 参数（请求方式为 POST / PATCH / PUT / DELETE 时默认） *   'params': 将 payload 用作请求配置的 `params` 参数（请求方式为 GET / HEAD 时默认） *   'config': 将 payload 仅用于构建请求配置（详见 RESTful 章节） *@returns {Promise<any>} axiosConfig.form.delete 的返回值 */form.delete()

Tip

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

状态变更

<script setup>importuseAdmatefrom'admate'const {form }=useAdmate()/** *@param{any}[payload] *@param{'data'|'params'|'config'}[payloadAs] 指定 payload 的用途 *   'data': 将 payload 用作请求配置的 `data` 参数（请求方式为 POST / PATCH / PUT / DELETE 时默认） *   'params': 将 payload 用作请求配置的 `params` 参数（请求方式为 GET / HEAD 时默认） *   'config': 将 payload 仅用于构建请求配置（详见 RESTful 章节） *@returns{Promise<any>} axiosConfig.form.switch 的返回值*/form.switch()</script><template>  <el-table>    <el-table-columnlabel="操作"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>importuseAdmatefrom'admate'const {form }=useAdmate({  axiosConfig: {    form: {switch: ({ id, status })=> ({        method:'PUT',        url:`${status===1?'enable':`disable`}/${id}`,      }),    }  },})/** *@param{any}[payload] *@param{'data'|'params'|'config'}[payloadAs] 指定 payload 的用途 *   'data': 将 payload 用作请求配置的 `data` 参数（请求方式为 POST / PATCH / PUT / DELETE 时默认） *   'params': 将 payload 用作请求配置的 `params` 参数（请求方式为 GET / HEAD 时默认） *   'config': 将 payload 仅用于构建请求配置（详见 RESTful 章节） *@returns{Promise<any>} axiosConfig.form.switch 的返回值*/form.switch()</script><template>  <el-table>    <el-table-columnlabel="操作"align="center"    >      <template #default="{ row: {id,status } }">        <el-switch@change="form.switch({ id, status: status ^ 1 }, 'config')" />      </template>    </el-table-column>  </el-table></template>

<script setup>importuseAdmatefrom'admate'const {form }=useAdmate({  axiosConfig: {    form: {      update: {// ...      },switch: {// 按编辑接口进行配置      },    }  },})/** *@param{any}[payload] *@param{'data'|'params'|'config'}[payloadAs] 指定 payload 的用途 *   'data': 将 payload 用作请求配置的 `data` 参数（请求方式为 POST / PATCH / PUT / DELETE 时默 认） *   'params': 将 payload 用作请求配置的 `params` 参数（请求方式为 GET / HEAD 时默认） *   'config': 将 payload 仅用于构建请求配置（详见 RESTful 章节） *@returns{Promise<any>} axiosConfig.form.switch 的返回值*/form.switch()</script><template>  <el-table>    <el-table-columnlabel="操作"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

useAdmate({form:{proxy:{/**       *@param {Function} openForm 被代理的原始 openForm       *@returns {Promise<object> | object | void} object 为打开表单后 form 的终态       */open(openForm){},}}})

// 示例: 回显表单后，修改表单数据const{ form}=useAdmate({form:{proxy:{open(openForm){// 新增时 openForm 没有返回值returnnewPromise((resolve,reject)=>{openForm()?.then((response)=>{// response 为 axiosConfig.r 的接口返回值// 修改表单数据form.data.status=1resolve()}).catch((e)=>{reject(e)})})},}}})

// 示例: 回显表单后，清除校验useAdmate({form:{proxy:{open(openForm){returnnewPromise((resolve,reject)=>{openForm()?.finally(()=>{formRef.value.clearValidate()}).then(()=>{resolve()}).catch((e)=>{reject(e)})})},}}})

// 示例: 回显表单后，自定义表单的开闭和读取状态useAdmate({form:{proxy:{open(openForm){returnnewPromise((resolve,reject)=>{// 可以在 finally 中 resolveopenForm().then(()=>{// 回显成功后，默认停止加载resolve({loading:false,})}).catch(()=>{// 回显失败后，默认关闭表单并停止加载resolve({show:false,loading:false,})})})}}}})// 也可以返回一个对象（如果没有异步操作）useAdmate({form:{proxy:{open(openForm){return{loading:false}}}}})

读取状态

<!-- 示例 --><script setup>import useAdmate from 'admate'const { form } = useAdmate()</script><template>  <el-dialog>    <el-form v-loading="form.loading" />  </el-dialog></template>

提交表单

form.submit

const{ form}=useAdmate()/** * PS: 以下为原始 form.submit 的函数签名，如果你配置了 form.proxy.submit ，则以 form.proxy.submit 为准 * *@param {any} [payload = form.data] *@param {'data'|'params'|'config'} [payloadAs] 指定 payload 的用途 *@returns {Promise<any>} 接口返回值 */form.submit()

form.proxy.submit

useAdmate({form:{proxy:{/**       *@param {Function} submitForm 被代理的原始 submitForm       *@returns {Promise<object> | object | void} object 为提交表单后 form 的终态       */submit(submitForm){}}}})

// 示例: 指定提交参数form.submit({  ...form.data,status:1,})// form.submit 被代理时useAdmate({form:{proxy:{submit(submitForm){returnnewPromise((resolve,reject)=>{submitForm({            ...form.data,status:1,}).then(()=>{resolve()}).catch((e)=>{reject(e)})})}}}})

// 示例: 提交前校验表单useAdmate({form:{proxy:{submit(submitForm){returnnewPromise((resolve,reject)=>{formRef.value.validate().then(()=>{submitForm().then(()=>{resolve()}).catch((e)=>{reject(e)})})})}}}})

// 示例: 提交表单后，自定义表单的开闭和提交状态// 返回一个 promiseuseAdmate({form:{proxy:{submit(submitForm){returnnewPromise((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,}}}}})

提交状态

<!-- 示例 --><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){// res 为接口返回值，trigger 为调用动机// 可访问 this（组件实例）}})

打开 / 读取表单

watch(()=>form.value.show,(n)=>{if(n){// 打开表单}})

// 示例: 适配层提供 onFormOpeneduseAdmateAdapter({},{onFormOpened(res){// res 为接口返回值（新增时为空）// 可访问 this（组件实例）}})

// 示例: 适配层提供 onFormReaduseAdmateAdapter({},{onFormRead(res){// res 为接口返回值// 可访问 this（组件实例）}})

提交表单

useAdmateAdapter({},{onFormSubmit(form){// 可访问 this（组件实例）}})

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

关闭表单

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

场景

表单是子组件

表单是独立页面

只有表单没有列表

嵌套使用

更新日志