数据表格
1. 命名规范
数据表格描述文件是以 小写英文字母 命名的 JSON 文本文件 <name>.tab.json
| 文件夹 (相对应用模型根目录) | 文件名 | 表格名称 | API 路由地址 |
|---|---|---|---|
| / | name.tab.json | name | /api/xiang/table/name/管理接口 |
| /group/ | name.tab.json | gorup.name | /api/xiang/table/group.name/管理接口 |
| /group1/group2/ | name.tab.json | gorup1.gorup2.name | /api/xiang/table/group1.group2.name/管理接口 |
2. 文档结构
数据表格文档,由表格基础信息、数据模型绑定、业务结构映射表、字段映射表、过滤器映射表、列表页、编辑页、批量插入页和详情页构成。
{
"name": "云服务库",
"version": "1.0.0",
"bind": {},
"apis": {},
"columns": {},
"filters": {},
"list": {},
"edit": {},
"view": {},
"insert": {}
}| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| name | String | 数据表格名称 | 是 |
| version | String | 版本号,用于依赖关系校验和开发平台呈现 | 是 |
| bind | Object 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 的配置信息,覆盖自动生成的关联组件信息。 | 否 |
| list | Object Page | 列表页设置。 | 是 |
| edit | Object Page | 编辑页设置。 | 是 |
| view | Object Page | 查看页设置。 | 否 |
| insert | Object Page | 批量录入页设置。 | 否 |
2.1 基础信息
{
"name": "用户",
"title": "可信云云服务库 | 数据管理",
"decription": "可信云云服务库"
}| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| name | String | 数据表格名称, 可用于开发平台中呈现 | 是 |
| title | String | 打开数据表格页面时,浏览器栏呈现的页面标题 | 否 |
| decription | String | 数据表格介绍, 可用于开发平台中呈现 | 否 |
2.2 绑定数据模型 bind
可以通过设置 model 和 withs, 实现数据表格与数据模型绑定。绑定后,应用引擎将根据数据模型定义,生成 apis, columns 和 fliters 配置,如需要特殊声明,添加同 key 的特殊配置信息即可。也可在 columns, fliters 新增字段用于各页面呈现。
{
"bind": {
"model": "service",
"withs": {
"manu": {
"query": {
"select": ["id", "name", "short_name", "status"]
}
},
"kind": {
"query": {
"select": ["id", "name"]
}
}
}
}
}| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| model | String | 绑定数据模型名称 | 是 |
| withs | [key:String]:Object With | 数据模型关联查询设置. | 否 |
2.3 数据表格管理接口 apis
数据表格将提供增删改查等接口,通过这些接口完成数据管理操作。如设置绑定数据模型,自动根据模型信息生成数据管理 API, 可通过设置同 key 的配置信息,覆盖自动生成的 API, API 输入输出数据结构需与原接口保持一致。
Object API 数据结构
{
"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": []
}
}
}| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| process | String | 绑定处理器 (process) 输入输出数据结构需与原接口保持一致 | 是 |
| guard | String | 接口鉴权中间件, 多个用 , 分割, 设置为 - 不设置鉴权中间件, 不设置继承默认鉴权方式。 | 否 |
| default | Array<Any> | 参数表默认值, 如没有默认值可以设置为 null, 如 [null, null, 15] | 否 |
接口列表
管理接口(key) | 请求方式 | 路由(相对) | 说明 |
|---|---|---|---|
| search | GET | /search | 按条件查询, 分页。 |
| find | GET | /find | 按主键查询单条记录。 |
| save | POST | /save | 保存单条记录,存在更新,不存在创建。 |
| delete | POST | /delete | 按主键删除单条记录。 |
| insert | POST | /insert | 批量新增记录。 |
| delete-where | POST | /delete/where | 批量删除符合条件的记录。 |
| delete-in | POST | /delete/in | 批量删除指定一组主键的的数据记录。 |
| update-where | POST | /update/where | 批量更新符合条件的记录。 |
| update-in | POST | /update/in | 批量更新指定一组主键的的数据记录。 |
| quicksave | POST | /quicksave | 保存多条记录,存在更新,不存在创建。 |
| setting | GET | /setting | 读取数据表格配置信息, 用于前端界面渲染 |
2.4 字段呈现方式 columns
可以对字段设定在列表呈现 (view)、列表编辑 (edit)和编辑表单(form)中的呈现方式, 字段自由添加,可在各页面呈现设置中使用。如设置绑定数据模型,自动根据数据模型字段名称、字段类型生成对应呈现, 可通过设置同 key 的配置信息,覆盖自动生成的呈现信息。字段呈现方式映射表,可从 setting 接口中读取。
{
"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 数据结构
| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| label | String | 字段呈现的字段名称 | 是 |
| view | Object Render | 列表或查看页面,阅读状态时的使用的组件及属性, 默认为 label | 否 |
| edit | Object Render | 列表或查看页面,编辑状态时的使用的组件及属性 , 默认为 input | 否 |
| form | Object Render | 编辑页面,使用的组件及属性,默认为 input | 否 |
2.5 查询过滤器 fliters
可以通过设置查询过滤器,添加数据查询条件呈现。 查询过滤器自由添加,可在列表页面呈现设置中使用。如设置绑定数据模型,自动根据数据模型索引名称、字段信息生成对应配置, 可通过设置同 key 的配置信息,覆盖自动生成的配置信息。查询过滤器映射表,可从 setting 接口中读取。
{
"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 数据结构
| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| label | String | 过滤器显示名称 | 是 |
| bind | String | 绑定的查询条件 URL Query String 字段名称, 如 where.manu_id.in (用作 search API 查询参数) | 是 |
| input | Object Render | 查询内容输入组件, 默认为 input | 否 |
2.6 列表页 list
{
"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)
| 字段 | 类型 | 说明 |
|---|---|---|
columns | Array<Object ColumnInstance | String > | 数据列表可呈现的列 |
filters | Array<Object FilterInstance | String > | 可呈现的查询过滤器 |
Object ColumnInstance 数据结构
| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| name | String | 字段名称。必须已在字段呈现方式(columns)中定义。 | 是 |
| width | Integer | 列宽度。使用栅格系统,有效值 1-24。默认值为 6 | 否 |
Object FilterInstance 数据结构
| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| name | String | 字段名称。必须已在查询过滤器方式(filters)中定义。 | 是 |
| width | Integer | 列宽度。使用栅格系统,有效值 1-24。默认值为 6 | 否 |
功能 (actions)
| 名称 | 说明 |
|---|---|
create | 新建数据记录按钮 |
view | 查看数据记录详情按钮 |
edit | 修改数据记录表单按钮 |
import | 导入数据记录按钮 |
export | 导出数据记录按钮 |
update | 更新单条字段按钮 |
delete | 删除单条记录按钮 |
insert | 批量插入按钮 |
deleteWhere | 按条件批量删除按钮 |
updateWhere | 按条件批量更新按钮 |
deleteSelect | 批量删除选中数据记录按钮 |
updateSelect | 批量更新选中数据记录按钮 |
pagination | 分页器 |
setting | 数据表配置按钮 |
2.7 编辑页 edit
{
"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)
| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
groups | Array<Object Group> | 编辑表单字段分组列表 | 是 |
Object Group 数据结构
| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
title | String | 分组名称 | 否 |
description | String | 分组介绍 | 否 |
columns | Array<Object ColumnInstance | String > | 数据列表可呈现的列 | 是 |
功能 (actions)
| 名称 | 说明 |
|---|---|
cancel | 取消编辑按钮 |
save | 保存数据按钮 |
delete | 删除数据按钮 |
2.8 查看页 view
本版不做实现
2.9 批量录入页 insert
本版不做实现
3. Object Render 数据结构
{
"type": "select",
"props": {
"value": "{{manu_id}}",
"searchable": true,
"remote": {
"api": "/api/manu/get",
"query": {
"select": ["id", "name"],
"keyword": "where.name.like"
}
}
}
}| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| type | String | 使用的组件名称 | 是 |
| props | Object<Any> | 组件属性,具体查看对应组件文档。属性参数中可以使用 字符串、数字 和 变量。 | 否 |
| components | Array<Any> | 复合组件,引用原子组件名称或描述。 ["计费方式", "行业覆盖", {"name":"姓名", "props":{}}] | 否 |
在属性(props) 中使用变量
可以在属性(props)中可以使用 {{字段名称}} 或 :字段名称 引用当前记录数据,支持使用 . 访问 Object 或 Array 类型数据,如 {{字段名称.foo.bar}}、{{字段名称.0.foo}}、:字段名称.foo.bar、:字段名称.0.foo
4. Object Page 数据结构
{
"edit": {
"primary": "id",
"layout": {
"groups": [
{
"title": "数据标签",
"description": "",
"columns": ["服务领域", "计费方式", "行业覆盖"]
}
]
},
"actions": {
"cancel": {},
"save": {
"type": "button",
"props": {
"label": "保存"
}
},
"delete": {}
}
}
}| 字段 | 类型 | 说明 | 必填项 |
|---|---|---|---|
| primary | String | 主键字段名称 | 是 |
| layout | [key:String]:Any | 页面布局可选配置项,每个页面不同,在具体页面中定义。 | 是 |
| actions | [key:String]:[key:String]:Object Render | 页面可用功能呈现方式映射表,每个页面不同,在具体页面中定义。 | 否 |
| option | [key:String]:Any | 页面配置信息,根据需要自由定义。API Setting 原样返回。 | 否 |
5. 完整示例
完整示例保存在 examples 目录
{
"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": {}
}