Skip to content

数据表格

1. 命名规范

数据表格描述文件是以 小写英文字母 命名的 JSON 文本文件 <name>.tab.json

文件夹 (相对应用模型根目录)文件名表格名称API 路由地址
/name.tab.jsonname/api/xiang/table/name/管理接口
/group/name.tab.jsongorup.name/api/xiang/table/group.name/管理接口
/group1/group2/name.tab.jsongorup1.gorup2.name/api/xiang/table/group1.group2.name/管理接口

2. 文档结构

数据表格文档,由表格基础信息、数据模型绑定、业务结构映射表、字段映射表、过滤器映射表、列表页、编辑页、批量插入页和详情页构成。

json
{
  "name": "云服务库",
  "version": "1.0.0",
  "bind": {},
  "apis": {},
  "columns": {},
  "filters": {},
  "list": {},
  "edit": {},
  "view": {},
  "insert": {}
}
字段类型说明必填项
nameString数据表格名称
versionString版本号,用于依赖关系校验和开发平台呈现
bindObject Bind绑定数据模型。
hooks[key:String]:String数据表格 Hook
apis[key:String]:Object API数据管理 API 设置。如设置绑定数据模型,自动根据模型信息生成数据管理 API, 可通过设置同 key 的配置信息,覆盖自动生成的 API。
columns[key:String]:Object Column字段呈现方式设置。 如设置绑定数据模型,自动根据字段类型信息设置关联组件,可通过设置同 key 的配置信息,覆盖自动生成的关联组件信息。
filters[key:String]:Object Filter查询过滤器设置。 如设置绑定数据模型,自动根据索引和字段信息设置关联组件,可通过设置同 key 的配置信息,覆盖自动生成的关联组件信息。
listObject Page列表页设置。
editObject Page编辑页设置。
viewObject Page查看页设置。
insertObject Page批量录入页设置。

2.1 基础信息

json
{
  "name": "用户",
  "title": "可信云云服务库 | 数据管理",
  "decription": "可信云云服务库"
}
字段类型说明必填项
nameString数据表格名称, 可用于开发平台中呈现
titleString打开数据表格页面时,浏览器栏呈现的页面标题
decriptionString数据表格介绍, 可用于开发平台中呈现

2.2 绑定数据模型 bind

可以通过设置 modelwiths, 实现数据表格与数据模型绑定。绑定后,应用引擎将根据数据模型定义,生成 apis, columnsfliters 配置,如需要特殊声明,添加同 key 的特殊配置信息即可。也可在 columns, fliters 新增字段用于各页面呈现。

json
{
  "bind": {
    "model": "service",
    "withs": {
      "manu": {
        "query": {
          "select": ["id", "name", "short_name", "status"]
        }
      },
      "kind": {
        "query": {
          "select": ["id", "name"]
        }
      }
    }
  }
}
字段类型说明必填项
modelString绑定数据模型名称
withs[key:String]:Object With数据模型关联查询设置.

2.3 数据表格管理接口 apis

数据表格将提供增删改查等接口,通过这些接口完成数据管理操作。如设置绑定数据模型,自动根据模型信息生成数据管理 API, 可通过设置同 key 的配置信息,覆盖自动生成的 API, API 输入输出数据结构需与原接口保持一致。

Object API 数据结构

json
{
  "apis": {
    "search": {
      "process": "models.service.Paginate",
      "guard": "bearer-jwt",
      "default": [
        {
          "withs": {
            "manu": {
              "query": {
                "select": ["id", "name", "short_name", "status"]
              }
            }
          }
        },
        null,
        15
      ]
    },
    "find": {
      "process": "models.service.Find",
      "default": [
        null,
        {
          "withs": {
            "manu": {
              "query": {
                "select": ["id", "name", "short_name", "status"]
              }
            }
          }
        }
      ]
    },
    "管理接口(key) ": {
      "process": "处理器名称",
      "guard": "-",
      "default": []
    }
  }
}
字段类型说明必填项
processString绑定处理器 (process) 输入输出数据结构需与原接口保持一致
guardString接口鉴权中间件, 多个用 , 分割, 设置为 - 不设置鉴权中间件, 不设置继承默认鉴权方式。
defaultArray<Any>参数表默认值, 如没有默认值可以设置为 null, 如 [null, null, 15]

接口列表

管理接口(key)请求方式路由(相对)说明
searchGET/search按条件查询, 分页。
findGET/find按主键查询单条记录。
savePOST/save保存单条记录,存在更新,不存在创建。
deletePOST/delete按主键删除单条记录。
insertPOST/insert批量新增记录。
delete-wherePOST/delete/where批量删除符合条件的记录。
delete-inPOST/delete/in批量删除指定一组主键的的数据记录。
update-wherePOST/update/where批量更新符合条件的记录。
update-inPOST/update/in批量更新指定一组主键的的数据记录。
quicksavePOST/quicksave保存多条记录,存在更新,不存在创建。
settingGET/setting读取数据表格配置信息, 用于前端界面渲染

2.4 字段呈现方式 columns

可以对字段设定在列表呈现 (view)、列表编辑 (edit)和编辑表单(form)中的呈现方式, 字段自由添加,可在各页面呈现设置中使用。如设置绑定数据模型,自动根据数据模型字段名称、字段类型生成对应呈现, 可通过设置同 key 的配置信息,覆盖自动生成的呈现信息。字段呈现方式映射表,可从 setting 接口中读取。

json
{
  "columns": {
    "name": {
      "label": "服务名称",
      "view": {
        "type": "label",
        "props": {
          "value": ":name"
        }
      },
      "edit": {
        "type": "input",
        "props": {
          "value": ":name"
        }
      },
      "form": {
        "type": "input",
        "props": {
          "value": ":name"
        }
      }
    },
    "manu.name": {
      "label": "厂商名称",
      "view": {
        "type": "label",
        "props": {
          "value": ":manu.name"
        }
      }
    },
    "所属厂商": {
      "label": "所属厂商",
      "view": {
        "name": "label",
        "props": {
          "value": ":manu.short_name"
        }
      },
      "edit": {
        "type": "select",
        "props": {
          "value": ":manu.id",
          "searchable": true,
          "remote": {
            "api": "/api/manu/get",
            "query": {
              "select": ["id", "name"],
              "keyword": "where_name_like"
            }
          }
        }
      }
    }
  }
}

Object Column 数据结构

字段类型说明必填项
labelString字段呈现的字段名称
viewObject Render列表或查看页面,阅读状态时的使用的组件及属性, 默认为 label
editObject Render列表或查看页面,编辑状态时的使用的组件及属性 , 默认为 input
formObject Render编辑页面,使用的组件及属性,默认为 input

2.5 查询过滤器 fliters

可以通过设置查询过滤器,添加数据查询条件呈现。 查询过滤器自由添加,可在列表页面呈现设置中使用。如设置绑定数据模型,自动根据数据模型索引名称、字段信息生成对应配置, 可通过设置同 key 的配置信息,覆盖自动生成的配置信息。查询过滤器映射表,可从 setting 接口中读取。

json
{
  "filters": {
    "关键词": {
      "label": "关键词",
      "bind": "where.name.like",
      "input": {
        "type": "input",
        "props": {
          "placeholder": "请输入关键词"
        }
      }
    },
    "所属厂商": {
      "label": "厂商",
      "bind": "where.manu_id.in",
      "input": {
        "type": "select",
        "props": {
          "searchable": true,
          "multiple": true,
          "placeholder": "请选择所属厂商",
          "remote": {
            "api": "/api/manu/get",
            "query": {
              "select": ["id", "name"],
              "keyword": "where.name.like",
              "limit": 500
            }
          }
        }
      }
    }
  }
}

Object Filter 数据结构

字段类型说明必填项
labelString过滤器显示名称
bindString绑定的查询条件 URL Query String 字段名称, 如 where.manu_id.in (用作 search API 查询参数)
inputObject Render查询内容输入组件, 默认为 input

2.6 列表页 list

json
{
  "list": {
    "primary": "id",
    "layout": {
      "columns": [
        { "name": "服务名称", "width": 6 },
        { "name": "所属厂商", "width": 6 },
        { "name": "服务类型", "width": 4 }
      ],
      "filters": [
        { "name": "关键词", "width": 6 },
        { "name": "所属厂商", "width": 6 }
      ]
    },
    "actions": {
      "create": {
        "type": "button",
        "props": {
          "label": "新建服务"
        }
      },
      "view": {},
      "edit": {},
      "import": {},
      "update": {},
      "delete": {},
      "insert": {},
      "updateWhere": {},
      "deleteWhere": {},
      "updateSelect": {},
      "deleteSelect": {},
      "pagination": {
        "type": "",
        "props": {
          "pages": true,
          "prev": true,
          "next": true
        }
      },
      "setting": {}
    }
  }
}

布局 (layout)

字段类型说明
columnsArray<Object ColumnInstance | String >数据列表可呈现的列
filtersArray<Object FilterInstance | String >可呈现的查询过滤器
Object ColumnInstance 数据结构
字段类型说明必填项
nameString字段名称。必须已在字段呈现方式(columns)中定义。
widthInteger列宽度。使用栅格系统,有效值 1-24。默认值为 6
Object FilterInstance 数据结构
字段类型说明必填项
nameString字段名称。必须已在查询过滤器方式(filters)中定义。
widthInteger列宽度。使用栅格系统,有效值 1-24。默认值为 6

功能 (actions)

名称说明
create新建数据记录按钮
view查看数据记录详情按钮
edit修改数据记录表单按钮
import导入数据记录按钮
export导出数据记录按钮
update更新单条字段按钮
delete删除单条记录按钮
insert批量插入按钮
deleteWhere按条件批量删除按钮
updateWhere按条件批量更新按钮
deleteSelect批量删除选中数据记录按钮
updateSelect批量更新选中数据记录按钮
pagination分页器
setting数据表配置按钮

2.7 编辑页 edit

json
{
  "edit": {
    "primary": "id",
    "layout": {
      "groups": [
        {
          "title": "基础信息",
          "description": "",
          "columns": [
            { "name": "服务名称", "width": 6 },
            { "name": "所属厂商", "width": 6 },
            { "name": "服务类型", "width": 6 },
            { "name": "状态", "width": 6 },
            { "name": "rank", "width": 6 }
          ]
        },
        {
          "title": "数据标签",
          "description": "",
          "columns": ["服务领域", "计费方式", "行业覆盖"]
        }
      ]
    },
    "actions": {
      "cancel": {},
      "save": {
        "type": "button",
        "props": {
          "label": "保存"
        }
      },
      "delete": {}
    }
  }
}

布局 (layout)

字段类型说明必填项
groupsArray<Object Group>编辑表单字段分组列表

Object Group 数据结构

字段类型说明必填项
titleString分组名称
descriptionString分组介绍
columnsArray<Object ColumnInstance | String >数据列表可呈现的列

功能 (actions)

名称说明
cancel取消编辑按钮
save保存数据按钮
delete删除数据按钮

2.8 查看页 view

本版不做实现

2.9 批量录入页 insert

本版不做实现

3. Object Render 数据结构

json
{
  "type": "select",
  "props": {
    "value": "{{manu_id}}",
    "searchable": true,
    "remote": {
      "api": "/api/manu/get",
      "query": {
        "select": ["id", "name"],
        "keyword": "where.name.like"
      }
    }
  }
}
字段类型说明必填项
typeString使用的组件名称
propsObject<Any>组件属性,具体查看对应组件文档。属性参数中可以使用 字符串数字变量
componentsArray<Any>复合组件,引用原子组件名称或描述。 ["计费方式", "行业覆盖", {"name":"姓名", "props":{}}]

在属性(props) 中使用变量

可以在属性(props)中可以使用 {{字段名称}}:字段名称 引用当前记录数据,支持使用 . 访问 ObjectArray 类型数据,如 {{字段名称.foo.bar}}{{字段名称.0.foo}}:字段名称.foo.bar:字段名称.0.foo

4. Object Page 数据结构

json
{
  "edit": {
    "primary": "id",
    "layout": {
      "groups": [
        {
          "title": "数据标签",
          "description": "",
          "columns": ["服务领域", "计费方式", "行业覆盖"]
        }
      ]
    },
    "actions": {
      "cancel": {},
      "save": {
        "type": "button",
        "props": {
          "label": "保存"
        }
      },
      "delete": {}
    }
  }
}
字段类型说明必填项
primaryString主键字段名称
layout[key:String]:Any页面布局可选配置项,每个页面不同,在具体页面中定义。
actions[key:String]:[key:String]:Object Render页面可用功能呈现方式映射表,每个页面不同,在具体页面中定义。
option[key:String]:Any页面配置信息,根据需要自由定义。API Setting 原样返回。

5. 完整示例

完整示例保存在 examples 目录

json
{
  "name": "云服务库",
  "version": "1.0.0",
  "decription": "可信云云服务库",
  "bind": {
    "model": "service",
    "withs": {
      "manu": {
        "query": {
          "select": ["id", "name", "short_name", "status"]
        }
      },
      "kind": {
        "query": {
          "select": ["id", "name"]
        }
      }
    }
  },
  "apis": {
    "search": {
      "process": "models.service.Paginate",
      "default": [
        {
          "withs": {
            "manu": {
              "query": {
                "select": ["id", "name", "short_name", "status"]
              }
            },
            "kind": {
              "query": {
                "select": ["id", "name"]
              }
            }
          },
          "wheres": [{ "column": "status", "value": "enabled" }]
        },
        null,
        15
      ]
    },
    "find": {
      "process": "models.service.Find",
      "default": [
        null,
        {
          "withs": {
            "manu": {
              "query": {
                "select": ["id", "name", "short_name", "status"]
              }
            },
            "kind": {
              "query": {
                "select": ["id", "name"]
              }
            }
          }
        }
      ]
    }
  },
  "columns": {
    "服务名称": {
      "label": "服务名称",
      "view": {
        "type": "label",
        "props": {
          "value": ":name"
        }
      },
      "edit": {
        "type": "input",
        "props": {
          "value": ":name"
        }
      }
    },
    "所属厂商": {
      "label": "所属厂商",
      "view": {
        "name": "label",
        "props": {
          "value": ":manu.short_name"
        }
      },
      "edit": {
        "type": "select",
        "props": {
          "value": ":manu.id",
          "searchable": true,
          "remote": {
            "api": "/api/manu/get",
            "query": {
              "select": ["id", "name"],
              "keyword": "where_name_like"
            }
          }
        }
      }
    },
    "服务类型": {
      "label": "服务类型",
      "view": {
        "name": "label",
        "props": {
          "value": ":kind.name"
        }
      },
      "edit": {
        "type": "select",
        "props": {
          "value": ":kind.id",
          "tree": true,
          "searchable": true,
          "remote": {
            "api": "/api/kind/tree",
            "query": {
              "select": ["id", "name"],
              "keyword": "where_name_like"
            }
          }
        }
      }
    },
    "服务领域": {
      "label": "服务领域",
      "view": {
        "name": "tags",
        "props": {
          "value": ":fields"
        }
      },
      "edit": {
        "type": "select",
        "props": {
          "value": ":fields",
          "searchable": true,
          "inputable": true,
          "multiple": true,
          "options": [
            { "label": "视频会议", "value": "视频会议" },
            { "label": "即时通信", "value": "即时通信" },
            { "label": "客服管理", "value": "客服管理" },
            { "label": "财务管理", "value": "财务管理" },
            { "label": "客户关系管理", "value": "客户关系管理" },
            { "label": "营销管理", "value": "营销管理" },
            { "label": "办公自动化", "value": "办公自动化" },
            { "label": "ERP", "value": "ERP" },
            { "label": "人力", "value": "人力" },
            { "label": "采购", "value": "采购" },
            { "label": "供应链", "value": "供应链" },
            { "label": "企业网盘", "value": "企业网盘" },
            { "label": "邮件服务", "value": "邮件服务" },
            { "label": "电子合同", "value": "电子合同" },
            { "label": "安全工具", "value": "安全工具" },
            { "label": "舆情分析", "value": "舆情分析" },
            { "label": "行业应用", "value": "行业应用" },
            { "label": "其他", "value": "其他" }
          ]
        }
      }
    },
    "计费方式": {
      "label": "计费方式",
      "view": {
        "name": "tags",
        "props": {
          "value": ":fields"
        }
      },
      "edit": {
        "type": "select",
        "props": {
          "value": ":price_options",
          "multiple": true,
          "options": [
            { "label": "按年订阅", "value": "按年订阅" },
            { "label": "按月订阅", "value": "按月订阅" },
            { "label": "按量计费", "value": "按量计费" },
            { "label": "私有化部署", "value": "私有化部署" },
            { "label": "其他", "value": "其他" }
          ]
        }
      }
    },
    "行业覆盖": {
      "label": "行业覆盖",
      "view": {
        "name": "tags",
        "props": {
          "value": ":industries"
        }
      },
      "edit": {
        "type": "select",
        "props": {
          "value": ":industries",
          "inputable": true,
          "multiple": true,
          "options": [
            { "label": "房地产", "value": "房地产" },
            { "label": "旅游", "value": "旅游" },
            { "label": "教育", "value": "教育" },
            { "label": "互联网", "value": "互联网" },
            { "label": "其他", "value": "其他" }
          ]
        }
      }
    },
    "状态": {
      "label": "状态",
      "view": {
        "name": "tags",
        "props": {
          "value": ":status",
          "options": [
            { "label": "开启", "value": "enabled", "color": "primary" },
            { "label": "关闭", "value": "disabled", "color": "danger" }
          ]
        }
      },
      "edit": {
        "type": "select",
        "props": {
          "value": ":status",
          "options": [
            { "label": "开启", "value": "enabled" },
            { "label": "关闭", "value": "disabled" }
          ]
        }
      }
    },
    "创建时间": {
      "label": "创建时间",
      "view": {
        "name": "label",
        "props": {
          "value": ":created_at",
          "datetime-format": "YYYY年MM月DD日 @hh:mm:ss"
        }
      }
    },
    "更新时间": {
      "label": "更新时间",
      "view": {
        "name": "label",
        "props": {
          "value": ":update_at",
          "datetime-format": "YYYY年MM月DD日 @hh:mm:ss"
        }
      }
    },
    "查询排序": {
      "label": "查询排序",
      "view": {
        "type": "label",
        "props": {
          "value": ":rank"
        }
      },
      "edit": {
        "type": "input",
        "props": {
          "value": ":rank",
          "type": "number"
        }
      }
    }
  },
  "filters": {
    "关键词": {
      "label": "关键词",
      "bind": "where.name.like",
      "input": {
        "type": "input",
        "props": {
          "placeholder": "请输入关键词"
        }
      }
    },
    "所属厂商": {
      "label": "厂商",
      "bind": "where.manu_id.in",
      "input": {
        "type": "select",
        "props": {
          "searchable": true,
          "multiple": true,
          "placeholder": "请选择所属厂商",
          "remote": {
            "api": "/api/manu/get",
            "query": {
              "select": ["id", "name"],
              "keyword": "where_name_like"
            }
          }
        }
      }
    },
    "服务类型": {
      "label": "类型",
      "bind": "where.kind_id.in",
      "input": {
        "type": "select",
        "props": {
          "tree": true,
          "searchable": true,
          "multiple": true,
          "placeholder": "请选择所属类型",
          "remote": {
            "api": "/api/kind/tree",
            "query": {
              "select": ["id", "name"],
              "keyword": "where_name_like"
            }
          }
        }
      }
    }
  },
  "list": {
    "primary": "id",
    "layout": {
      "columns": [
        { "name": "服务名称", "width": 6 },
        { "name": "所属厂商", "width": 6 },
        { "name": "服务类型", "width": 4 },
        { "name": "状态", "width": 4 },
        { "name": "服务领域", "width": 4 },
        { "name": "计费方式", "width": 4 },
        { "name": "创建时间", "width": 6 },
        { "name": "更新时间", "width": 6 }
      ],
      "filters": [
        { "name": "关键词", "width": 6 },
        { "name": "所属厂商", "width": 6 },
        { "name": "服务类型", "width": 4 }
      ]
    },
    "actions": {
      "create": {
        "type": "button",
        "props": {
          "label": "新建服务",
          "icon": "fas fa-plus"
        }
      },
      "view": {},
      "edit": {},
      "import": {},
      "update": {},
      "delete": {},
      "insert": {},
      "updateWhere": {},
      "deleteWhere": {},
      "updateSelect": {},
      "deleteSelect": {},
      "pagination": ["pages", "prev", "next"],
      "setting": {}
    }
  },
  "edit": {
    "primary": "id",
    "layout": {
      "fieldset": [
        {
          "title": "基础信息",
          "description": "",
          "columns": [
            { "name": "服务名称", "width": 6 },
            { "name": "所属厂商", "width": 6 },
            { "name": "服务类型", "width": 6 },
            { "name": "状态", "width": 6 },
            { "name": "rank", "width": 6 }
          ]
        },
        {
          "title": "数据标签",
          "description": "",
          "columns": ["服务领域", "计费方式", "行业覆盖"]
        }
      ]
    },
    "actions": {
      "cancel": {},
      "save": {
        "type": "button",
        "props": {
          "label": "保存"
        }
      },
      "delete": {}
    }
  },
  "insert": {},
  "view": {}
}