!!! 该库已迁移至 Cruda，本仓库不再维护 !!!

CRUD-vue

基于 Vue 的通用 CRUD 视图模型库；提供对常用 CRUD 场景的视图与操作托管，通过不同适配器可以实现对主流 UI 库的自动适配。

概念图

介绍

在所有存在列表展示的业务系统中，无论使用何种 UI 库都存在大量 CRUD 场景。CRUD-vue 为使用者抽象通用行为并内建数据模型统一调度相关操作。通过标准 REST 接口对接服务端，并通过适配器对接不同 UI 库，实现低成本、配置化的界面托管。

基本特性

数据托管

<!-- $crud.query 托管搜索数据 -->
<el-input v-model="$crud.query.xxx">
  <!-- $crud.table.data 托管表格数据 -->
  <el-table v-model="$crud.table.data">
    <!-- $crud.form 托管表单数据 -->
    <el-form :model="$crud.form">
      <!-- $crud.table.data 托管tree(表单数据) -->
      <el-tree :model="$crud.table.data"> </el-tree></el-form></el-table
></el-input>

操作托管

$crud.submit(formEl) //提交表单
$crud.reload() //刷新列表数据
$crud.cancel() //设置表单状态为取消

状态托管

<!-- 下面的例子实现了一个点击查询时锁定按钮的场景 -->
<button class="..." :loading="$crud.loading.query" @click="$crud.reload()">
  查询
</button>

过程封装

/*调用查询方法时，系统会执行
1. 设置表单与查询按钮的loading状态为true
2. 自动封装查询参数(query、分页、排序、...)
3. 触发钩子
4. 异常捕获
5. ...
*/
$crud.toQuery()

RESTful HTTP Method

$crud.toQuery() //GET
$crud.toDelete() //DELETE
$crud.doUpdate() //PUT

安装

从 NPM 安装

npm i @holyhigh/crud-vue

然后选择对应 ui 库并安装适配器

如何使用

1. 安装适配器

element-ui

// 安装CRUD
import request from 'axios'
import CRUD from '@holyhigh/crud-vue/element-ui'
//通常request总是会使用封装后的axios实例
Vue.use(CRUD, { request: request })

element-plus

// 安装CRUD
import request from 'axios'
import CRUD from '@holyhigh/crud-vue/element-plus'
//通常request总是会使用封装后的axios实例
createApp(App).use(CRUD, { request: request })

2. 激活

element-ui

//在vue对象的根属性中标记crud/cruds(多实例)属性
export default {
  crud: 'auth/users',
  // crud: {url:'auth/users'} 对象方式
  mounted() {
    // 激活后业务组件会被注入一个名为“$crud”的CRUD实例
    this.$crud.reload()
    // 以及一个入口标识。标识可以用于区分入口或自定义组件
    this.$isCrudEntry
  }
  ...
}

通过对象方式激活 CRUD 时，可以传递除 url 外的其他自定义参数。比如

export default {
  crud: {url:'auth/users',permission:'a_b_c'}
  ...
}

之后可通过 VM 属性params(read only)来获取激活参数

this.$crud.params.permission

params 参数在创建自定义 CRUD 组件时非常有用，比如通过 permission 参数可以实现组件自动权限管理，控制组件视图展示

v1.1+

//element-ui 也可以使用useCrud动态创建crud实例
const $crud = useCrud(vm, restURLMap)

element-plus

<script lang="ts" setup>
  import { useCrud } from '@holyhigh/crud-vue/element-plus'
  //通过useCrud函数获取$crud实例
  //对象方式激活时与element-ui行为一致
  const $crud = useCrud('/api/single')

  //自动加载
  onMounted(() => {
    $crud.reload()
  })
</script>

3. 多实例

element-ui

//在一个页面上需要同时处理多CRUD业务时可以通过修改激活方式来处理
export default {
  cruds: {//注意，激活标识与单实例不同，多了一个 "s"
    user: '/api/users',// user: {url:'/api/users'} 对象方式
    log: '/api/logs'
  },
  mounted() {
    // 多实例激活时注入变量会变成“$cruds”,且必须通过明确的实例标识来调用API
    this.$cruds.user.reload()
  }
  ...
}

v1.1+

//element-ui 也可以使用userCruds动态创建cruds实例
const $cruds = useCruds(vm, restURL)

element-plus

<script lang="ts" setup>
  import { useCruds } from '@holyhigh/crud-vue/element-plus'
  //通过useCruds函数获取$cruds实例
  const $cruds = useCruds({
    t1: '/api/single',
    t2: {
      url: '/api/multiple',
    },
  })

  //自动加载t1
  onMounted(() => {
    $cruds.t1.reload()
  })
</script>

4. HOOK

element-ui

//CRUD提供多种回调钩子以满足不同的业务场景
import CRUD from '@holyhigh/crud-vue'

export default {
  crud: '/api/users',
  methods:{
    [CRUD.HOOK.AFTER_QUERY](crud, rs) {
	  //根据查询结果设置分页值与表格数据
      crud.pagination.total = rs.data.total
      crud.table.data = rs.data.records || []
    }
  }
  ...
}

element-plus

<script lang="ts" setup>
  import CRUD, { onHook } from '@holyhigh/crud-vue/element-plus'

  const $crud = useCrud()

  //使用onHook函数进行钩子注册
  onHook(CRUD.HOOK.AFTER_SUBMIT, (crud) => {
    ElNotification.success('提交成功')
    crud.toQuery()
  })
</script>

5. 自定义组件

element-ui
自定义组件的核心逻辑是封装 crud 页面的数据及操作，比如 crudTable，而前提就是获取$crud实例。通过lookUpCrud方法可以拿到页面入口的$crud 实例。下面以一个查询框为例展示自定义组件需要关注的几个方面

<!--
   通过$crud.view控制视图显示/隐藏
   通过$crud.loading控制按钮/视图的锁定
   通过$crud.query/table/form/pagination/...实现视图映射
   通过内置API实现UI交互
-->
<template>
  <div v-show="$crud.view.queryShow" class="...">
    <slot />
    <el-button
      class="..."
      :loading="$crud.loading.query"
      @click="$crud.reload()"
      >查询</el-button
    >
    <el-button v-if="$crud.view.queryReset" class="..." @click="reset()"
      >重置</el-button
    >
  </div>
</template>
<script>
  import CRUD, { lookUpCrud } from '@holyhigh/crud-vue/element-ui'
  import { each } from '@holyhigh/func.js/collection'

  export default {
    beforeCreate() {
      //通过lookUpCrud方法获取组件所在crud入口页面的$crud实例
      //如果启用了多实例，必须指定第二个参数`crudName`
      this.$crud = lookUpCrud(this)
    },
    methods: {
      reset() {
        each(this.$crud.query, (v, k) => {
          this.$crud.query[k] = this.$crud.defaults.query[k]
          this.$crud.reload()
        })
      },
    },
  }
</script>

element-plus

<template>
  <el-table :data="$crud.table.data" @sort-change="(o) => $crud.changeSort(o)">
    <el-table-column prop="uname" label="uname" width="180" />
    <el-table-column prop="email" label="email" width="180" sortable="custom" />
    <el-table-column prop="ip" label="ip" />
    <el-table-column align="right">
      <template #default="{ row }">
        <el-button size="small" @click="$crud.toEdit(row)">Edit</el-button>
        <el-button size="small" type="danger" @click="toDelete(row)"
          >Delete</el-button
        >
      </template>
    </el-table-column>
  </el-table>
</template>
<script lang="ts" setup>
  import { lookUpCrud } from '@holyhigh/crud-vue/element-plus'
  //element-plus的lookUpCrud函数只有一个可选入参`crudName`
  const $crud = lookUpCrud()

  //自定义组件封装删除逻辑
  function toDelete(row: Record<string, any>) {
    ElMessageBox.confirm('确认删除?').then(() => {
      $crud.toDelete(row)
    })
  }
</script>

6. URL 参数

element-ui
CRUD 激活时，REST 地址支持 URL 参数来动态构建。通过 :varName 来声明变量，如下例

//user实例的地址使用了orgId参数
export default {
  cruds: {
    org: '/api/orgs',
    user: '/api/orgs/:orgId/users'
  },
  ...
  methods:{
    //切换org时调用该方法
    setOrg(orgId){
      this.$cruds.user.setURLParams({orgId})
      this.$cruds.user.toQuery()
    }
  }
}

如你所见，动态 URL 最典型的使用场景就是关联业务(当然，非动态 URL 也可实现相同功能)。通过setURLParams方法可以动态修改请求地址，之后进行 C/R/U/D 操作

element-plus
逻辑与 element-ui 相同

7. defaults

可以为 CRUD 指定全局 defaults 属性

// 如果项目返回值统一格式就可以设置全局HOOK实现查询结果赋值
CRUD.defaults[CRUD.HOOK.AFTER_QUERY] = function (crud, rs) {
  crud.pagination.total = rs.data.total
  crud.table.data = rs.data.records || []
}
// 可以设置默认的全局分页数
CRUD.defaults.pagination.pageSize = 10
// 可以设置默认的按钮显示状态
CRUD.defaults.view.queryReset = true
// 可以设置默认的列表数据主键key
CRUD.defaults.table.rowKey = 'id'

支持默认值设置的属性可在 VM 中查看

8. RESTAPI

RESTAPI 用来构建资源请求地址。默认 C/R/U/D 的资源标识符都为空，如果服务器有不同模式可以修改 API 地址。

CRUD.RESTAPI = {
  QUERY: '', //R
  EXPORT: '/export',
  ADD: '', //C
  UPDATE: '', //U
  DELETE: '', //D
  IMPORT: '/import',
  SORT: '/sort'
}

注意，C/R/U/D 对应的 HTTP Method 不会变更

VM

view ✅
业务组件通过 view 来控制 UI
- queryShow 查询框显示开关
- queryReset 查询框重置按钮显示开关
- opAdd 新增按钮显示开关
- opEdit 编辑按钮显示开关
- opDel 删除按钮显示开关
- opExport 导出按钮显示开关
- opSort 排序按钮显示开关
loading
通过 loading 控制锁定状态
- query 查询按钮锁定开关
- table 表格锁定开关
- del 删除按钮锁定开关
- export 导出按钮锁定开关
- submit 提交按钮锁定开关
- form 表单加载锁定开关
- sort 排序加载锁定开关
query

托管查询条件的容器
sortation

托管排序结果的容器
table
表格容器托管当前 crud 实例的列表/tree 数据及显示状态
- data 表格数据
- selection 当前选中行
- allColumns 表格所有列，用于动态展示
- orders 排序列表，会传递给 GET 请求
- rowKey✅ 表格行的 id key，默认为'id'。通常由适配器自动设置
pagination
分页容器托管当前 crud 实例的列表分页状态
- pageSize✅ 每页记录数
- currentPage 当前页号
- total 总记录数
form

表单容器托管当前 crud 实例的表单数据
formStatus

表单当前状态 0：默认；1：新增；2：编辑；3：查看
vm

crud 的入口 vue 实例
params

crud 激活参数，通过对象方式构造 crud 时可以注入。可用于自定义组件中进行附加操作，比如附加 CRUD 权限控制
error

crud 错误信息{name，message，status}。可以用于监控并作出合适的反馈，比如网络超时提示

✅ 表示支持全局默认值

APIs

toQuery() : Promise

启动 crud 实例的查询。向指定 REST 地址发送 GET 请求
toDelete(rows) : Promise

启动 crud 实例的删除。向指定 REST 地址发送 DELETE 请求
toExport() : Promise

启动 crud 实例的导出。向指定 REST 地址发送 GET 请求
toImport(file/s) : Promise

启动 crud 实例的导入。向指定 REST 地址发送 POST 请求
toAdd(...args)

设置 form 状态为新增。
toEdit(row) : Promise

设置 form 状态为编辑。向指定 REST 地址发送 GET 请求
toView(row) : Promise

设置 form 状态为查看。向指定 REST 地址发送 GET 请求
toSort()

触发
submitSort() : Promise

启动 crud 实例的排序。向指定 REST 地址发送 PUT 请求
cancel()

设置 form 状态为取消。
submit(formEl) : Promise

会调用 formEl 的 validate 方法，并在成功后执行 doAdd(POST)/doEdit(PUT)操作。对于验证错误，catch 中会返回 invalidFields
submitSort() : Promise

提交排序结果
reload() : Promise

重置分页信息并执行一次 toQuery()
getRestURL()

获取 crud 实例的服务地址。通常用于 crud 内部
setURLParams(paramObj)

设置服务地址中的参数表
getDetails(rowId)

获取行信息。通常用于 crud 内部
changeSelection(selection: Record<string, any>[])

用在 table 的 selection-change 事件中，记录 table 当前已选记录
changeOrder(orderData: { column: Record<string, any> prop: string order: string | null })

用在 table 的 sort-change 事件，会自动管理排序信息并触发查询

HOOKs

BEFORE_QUERY(crud,params,orders,cancel)

查询前回调，可以修改请求参数(params)，比如分页名称等，可取消。取消后不会触发 AFTER_QUERY
注意 ,params 为提交接口的实际对象（包含 query、pagination)，此处修改 crud.query/pagination 的内容不会提交到接口
AFTER_QUERY(crud,rs)

查询后回调，可以获取查询结果，设置表格
BEFORE_DELETE(crud,rows,cancel)

删除前调用，可取消。取消后不会触发 AFTER_DELETE
AFTER_DELETE(crud,rs,rows)

删除后调用
BEFORE_ADD(crud,...args)

新增前调用，可以用来清空表单或产生 uuid 等
BEFORE_EDIT_QUERY(crud,params,cancel,row)

发出编辑查询前调用，可取消。取消后不会触发 BEFORE_EDIT。如需实现row数据回显，可通过cancel取消远程请求并通过row填充crud.form
BEFORE_EDIT(crud,rs,row)

编辑前调用，可以用来锁定某些字段
BEFORE_VIEW_QUERY(crud,params,cancel,row)

发出查看查询前调用，可取消。取消后不会触发 BEFORE_VIEW。如需实现row数据回显，可通过cancel取消远程请求并通过row填充crud.form
BEFORE_VIEW(crud,rs,row)

查看查询结果返回后调用
BEFORE_SUBMIT(crud,cancel)

提交前调用，可对 form 进行最后加工，可取消。取消后不会触发 AFTER_SUBMIT
AFTER_SUBMIT(crud,rs)

提交后调用，可以用来刷新页面、发送通知或其他操作
BEFORE_EXPORT(crud,params,orders,cancel)

导出前调用，同 BEFORE_QUERY，可取消。取消后不会触发 AFTER_EXPORT
AFTER_EXPORT(crud,rs)

获取导出数据后调用
ON_ERROR(crud,error)

操作发生错误时调用
ON_CANCEL(crud)

表单取消编辑时触发（调用 cancel 后）
BEFORE_IMPORT(crud,params,cancel)

导入文件上传前调用，可在 params 中添加额外参数，可取消。取消后不会触发 AFTER_IMPORT
AFTER_IMPORT(crud,rs)

导入上传完成后调用
BEFORE_SORT(crud,...args)

排序前调用，可用来打开排序框或启动自动排序处理
BEFORE_SUBMIT_SORT(crud,sortation,cancel)

提交排序前调用，可对排序内容进行最后加工，可取消。取消后不会触发 AFTER_SUBMIT_SORT
AFTER_SUBMIT_SORT(crud,rs)

提交排序后调用，可以用来刷新页面、发送通知或其他操作

可导出

import CRUD,{...} from '@holyhigh/crud-vue/element-ui'
import CRUD,{...} from '@holyhigh/crud-vue/element-plus'

CRUD crud 命名空间，可设置全局默认值、调用钩子等

element-ui
- useCrud(vm,restURL) : CRUD
  
  创建一个 crud 单实例入口并绑定指定的 vm(vue 组件)
- useCruds(vm,restURLMap) : Record<string, CRUD>
  
  创建一个 crud 多实例入口并绑定指定的 vm(vue 组件)
- lookUpCrud(vm,crudName?) : CRUD | null
  
  向上查找最近的 crud 实例
element-plus
- useCrud(restURL) : CRUD
  
  创建一个 crud 单实例入口并返回
- useCruds(restURLMap) : Record<string, CRUD>
  
  创建一个 crud 多实例入口并返回
- lookUpCrud(crudName?) : CRUD | null
  
  向上查找最近的 crud 实例
- onHook(hookName,hook) : void
  
  用于注册钩子

错误信息

Must specify 'crudName' when multiple instances detected

多实例时调用 lookUpCrud 方法未指定 crud 标识。解决方法见【6. 自定义组件】
form validation Xxx

表单提交时验证错误信息
Cannot find [request] in the installation options

安装时未指定请求器。解决方法见【1. 安装】
table.rowKey is a blank value 'Xxx', it may cause an error - toDelete/Edit/View()

进行删除/编辑/查看操作时未指定 table.rowKey。可以设置默认/$crud 实例的对应属性

@holyhigh/crud-vue

!!! 该库已迁移至 Cruda，本仓库不再维护 !!!

CRUD-vue

概念图

介绍

基本特性

安装

如何使用

1. 安装适配器

2. 激活

3. 多实例

4. HOOK

5. 自定义组件

6. URL 参数

7. defaults

8. RESTAPI

VM

APIs

HOOKs

可导出

错误信息

Readme

Keywords

Package Sidebar

Install

Repository

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

@holyhigh/crud-vue

!!! 该库已迁移至 Cruda，本仓库不再维护 !!!

CRUD-vue

概念图

介绍

基本特性

安装

如何使用

1. 安装适配器

2. 激活

3. 多实例

4. HOOK

5. 自定义组件

6. URL 参数

7. defaults

8. RESTAPI

VM

APIs

HOOKs

可导出

错误信息

Readme

Keywords

Package Sidebar

Install

Repository

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads