设计时视图管理（ViewController）

视图设计时资源管理：视图、视图列、视图操作（按钮 Activity）、视图事件（Event）的增删改查，以及复制、一键生成、列排序、数据来源字段、系统筛选字段、作用域查询等辅助接口。

• 接口类型：REST 资源
• 基址：${myapps.context-path.designer:}/api/designtime/applications（类级 @RequestMapping，produces = APPLICATION_JSON_VALUE）
• Tag：设计时-视图模块

公共说明

• 鉴权：是（需 designerToken）。所有端点继承自 AbstractDesignTimeController（基类为 @RestController），通过 Security.getDesignerIdFromToken(request) 从 designerToken JWT 中解析设计器用户。鉴权机制详见 index.md「鉴权说明」。
• 路径变量：{applicationId}、{moduleId}、{viewId}、{columnId}、{activityId}、{eventId}、{formId}、{authField} 等均为**明文设计时 ID**（不像 runtime 的 DES 加密密文，designer 控制器直接将原始字符串传入设计时服务）。
• 响应：统一 Resource（见 ../index.md「统一响应结构」）。成功 errcode=0；失败 errcode=500，errmsg 为异常信息。所有写操作（POST/PUT/DELETE）的成功响应通常 data 为 null 或仅含新构建的 id。
• 分页字段：仅「获取视图列表」端点（### 1）返回分页结构，字段为 pageNo/linesPerPage/rowCount/pageCount/datas（注意：与 runtime 视图的 page/page_lines/row_count 不同，据源码）。
• 请求体约定：多数 POST/PUT/DELETE 接收原始 JSON 字符串（@RequestBody String content），由服务端用 JSONObject.fromObject/JSONArray.fromObject/JsonPath 解析。

---

1. 获取视图列表

分页获取指定模块下的视图列表，可按名称/描述关键字查询、按视图类型过滤。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/{moduleId}/views（完整：{designer-context}/api/designtime/applications/{applicationId}/modules/{moduleId}/views）
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
moduleId	path	string	是	模块Id
searchword	query	string	否	查询关键字（按名称或描述匹配）
filterType	query	string	否	过滤视图类型（多个以逗号分隔；命中的类型**被排除**）
pageNo	query	string	否	当前页数（默认 1）
linesPerPage	query	string	否	每页行数（默认 10）

请求示例

GET /api/designtime/applications/{applicationId}/modules/{moduleId}/views?pageNo=1&linesPerPage=10&searchword= HTTP/1.1

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：JSONObject，含分页字段与 datas（视图精简数组，每项 {id, name, description, type}）。

成功示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "linesPerPage": 10,
    "rowCount": 25,
    "pageNo": 1,
    "pageCount": 3,
    "datas": [
      { "id": "...", "name": "视图名称", "description": "视图描述", "type": 1 }
    ]
  },
  "errors": null
}

失败示例：

{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

---

2. 获取视图详情

按视图Id获取完整视图对象（含列、操作、事件、链接等完整定义）。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/views/{viewId}
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
viewId	path	string	是	视图Id

响应

data：AbstractView 完整对象（ListView/TreeView/CalendarView/CardView/MapView/GanttView/CollapsibleView/SheetView 等具体子类）。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "...", "name": "...", "viewTypeImpl": 1, "...": "..." }, "errors": null }

---

3. 复制视图

按视图Id列表批量复制视图到同一应用下。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/modules/views/copy
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
content	body	string(JSON)	是	视图Id数组（JSON 数组字符串）

请求体

["<viewId1>", "<viewId2>"]

响应

data：null（成功）。

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

---

4. 新建视图

按视图类型在指定模块下新建视图，自动重名校验。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/modules/{moduleId}/views
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
moduleId	path	string	是	模块Id
viewType	query	int	是	视图类型常量（见下表）
content	body	string(JSON)	是	视图对象 JSON

视图类型常量（来自 ViewConstant）：

值（十六进制）	常量	实现类
0x0000001	VIEW_TYPE_NORMAL	ListView
0x0000010	VIEW_TYPE_CALENDAR	CalendarView
0x0000011	VIEW_TYPE_TREE	TreeView
0x0000012	VIEW_TYPE_MAP	MapView
0x0000013	VIEW_TYPE_GANTT	GanttView
0x0000014	VIEW_TYPE_COLLAPSIBLE	CollapsibleView
0x0000015	VIEW_TYPE_SHEET	SheetView
0x0000016	VIEW_TYPE_CARD	CardView

请求体

对应视图实现类的完整 JSON（包含 name、columns、activities、events、openRule 等）。

响应

data：JSONObject，仅含 id（新建视图Id）。重名时返回错误 {*[viewExist]*}。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "<新视图Id>" }, "errors": null }

---

5. 更新视图

按视图类型更新整个视图对象（含列字段映射配置校验、重名校验）。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/{applicationId}/modules/{moduleId}/views/{viewId}
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
moduleId	path	string	是	模块Id
viewId	path	string	是	视图Id
viewType	query	int	是	视图类型常量（同 ### 4 视图类型表）
content	body	string(JSON)	是	视图对象 JSON

请求体

对应视图实现类的完整 JSON。更新前会移除 uri 字段。

响应

data：null（成功）。列字段映射配置错误（validate 不通过，例如树形视图列映射少于 3、日历视图少于 1、甘特图少于 4）时返回 "保存失败，列字段映射配置错误"。

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

---

6. 删除视图（可批量）

按视图Id列表批量删除视图（含路径信息收集）。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/{applicationId}/modules/views
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
content	body	string(JSON)	是	视图Id数组（JSON 数组字符串）

请求体

["<viewId1>", "<viewId2>"]

响应

data：null（成功）。

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

---

7. 一键生成视图

根据现有表单一键生成对应的默认视图。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/modules/views
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
formId	query	string	是	数据来源表单Id

请求示例

POST /api/designtime/applications/{applicationId}/modules/views?formId=<formId> HTTP/1.1

响应

data：null（成功）。

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

---

8. 获取视图列列表

获取指定视图下的视图列精简列表。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/views/{viewId}/columns
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
viewId	path	string	是	视图Id

响应

data：JSONArray，每项 {id, name, orderno}。

{ "errcode": 0, "errmsg": "ok", "data": [ { "id": "...", "name": "...", "orderno": 0 } ], "errors": null }

---

9. 获取视图列详情

按视图列Id获取完整视图列对象。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/views/columns/{columnId}
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
columnId	path	string	是	视图列Id

响应

data：Column 完整对象（含 mappingField、customIcon、orderno 等）。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "...", "name": "...", "mappingField": "...", "...": "..." }, "errors": null }

---

10. 新建视图列

在指定视图下新建视图列（自动重名校验，命中返回 "该列名称已存在"）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/modules/views/{viewId}/columns
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
viewId	path	string	是	视图Id
content	body	string(JSON)	是	视图列对象 JSON

响应

data：JSONObject，仅含 id（新建列Id）。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "<新列Id>" }, "errors": null }

---

11. 批量新建视图列

在指定视图下批量新建视图列（不做重名校验）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/modules/views/{viewId}/columns/batch
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
viewId	path	string	是	视图Id
content	body	string(JSON)	是	视图列对象 JSON 数组

请求体

[ { "name": "列1", "...": "..." }, { "name": "列2", "...": "..." } ]

响应

data：JSONArray，每项 {id}（按入参顺序返回新建列Id）。

{ "errcode": 0, "errmsg": "ok", "data": [ { "id": "<新列Id1>" }, { "id": "<新列Id2>" } ], "errors": null }

---

12. 更新视图列

更新指定视图列（重名校验排除自身）。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/{applicationId}/modules/views/{viewId}/columns/{columnId}
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
viewId	path	string	是	视图Id
columnId	path	string	是	视图列Id
content	body	string(JSON)	是	视图列对象 JSON（含 customIcon 字段）

响应

data：null（成功）。重名时返回 "该列名称已存在"。

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

---

13. 删除视图列（可批量）

按列Id列表批量删除视图列。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/{applicationId}/modules/views/columns
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
content	body	string(JSON)	是	列Id数组（JSON 数组字符串）

响应

data：null（成功）。

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

---

14. 获取视图操作列表

获取指定视图下的操作（按钮 Activity）列表。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/views/{viewId}/activitys
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
viewId	path	string	是	视图Id

响应

data：List<Activity>。

{ "errcode": 0, "errmsg": "ok", "data": [ { "id": "...", "name": "...", "...": "..." } ], "errors": null }

---

15. 获取视图操作详情

按操作Id获取完整视图操作（按钮 Activity）对象。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/views/activitys/{activityId}
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
activityId	path	string	是	视图操作Id

响应

data：Activity 完整对象。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "...", "name": "...", "...": "..." }, "errors": null }

---

16. 新建视图操作

在指定视图下新建视图操作（按钮 Activity）。对入参携带 id 时复用其 id；不携带则生成新 id。重名时抛出 "该按钮名称已存在"。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/modules/views/{viewId}/activitys
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
viewId	path	string	是	视图Id
content	body	string(JSON)	是	视图操作对象 JSON

响应

data：JSONObject，含 id（活动Id）。当入参对象为 null 时返回 data: null。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "<activityId>" }, "errors": null }

---

17. 更新视图操作

更新指定视图操作（按钮 Activity）。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/{applicationId}/modules/views/{viewId}/activitys/{activityId}
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
viewId	path	string	是	视图Id
activityId	path	string	是	视图操作Id
content	body	string(JSON)	是	视图操作对象 JSON

响应

data：null（成功）。

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

---

18. 删除视图操作（可批量）

按操作Id数组批量删除视图操作。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/{applicationId}/modules/views/activitys
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
content	body	string	是	操作Id字符串数组（JSON 数组反序列化为 String[]）

请求体

["<activityId1>", "<activityId2>"]

响应

data：null（成功）。

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

---

19. 获取视图事件列表

获取指定视图下的事件（Event）列表。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/views/{viewId}/events
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
viewId	path	string	是	视图Id

响应

data：List<Event>。

{ "errcode": 0, "errmsg": "ok", "data": [ { "id": "...", "name": "...", "...": "..." } ], "errors": null }

---

20. 获取视图事件详情

按事件Id获取完整视图事件（Event）对象。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/modules/views/events/{eventId}
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
eventId	path	string	是	视图事件Id

响应

data：Event 完整对象。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "...", "name": "...", "...": "..." }, "errors": null }

注：源码中该方法签名第二个 @PathVariable 形参名为 activityId（与路径变量 {eventId} 不同名），实际值仍取自路径中的 {eventId} 段。

---

21. 新建视图事件

在指定视图下新建视图事件（Event）。重名时抛出 "该按钮名称已存在"（源码沿用按钮校验文案）。

• 接口类型：REST 资源
• 请求方式：POST
• 请求路径：/{applicationId}/modules/views/{viewId}/events
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
viewId	path	string	是	视图Id
content	body	string(JSON)	是	视图事件对象 JSON

响应

data：JSONObject，含 id（事件Id）。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "<eventId>" }, "errors": null }

---

22. 更新视图事件

更新指定视图事件（Event）。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/{applicationId}/modules/views/{viewId}/events/{eventId}
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
viewId	path	string	是	视图Id
eventId	path	string	是	视图事件Id
content	body	string(JSON)	是	视图事件对象 JSON

响应

data：null（成功）。

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

---

23. 删除视图事件（可批量）

按事件Id数组批量删除视图事件。

• 接口类型：REST 资源
• 请求方式：DELETE
• 请求路径：/{applicationId}/modules/views/events
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
content	body	string	是	事件Id字符串数组（JSON 数组反序列化为 String[]）

请求体

["<eventId1>", "<eventId2>"]

响应

data：null（成功）。

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }

---

24. 获取数据来源表单字段（包含系统变量）

获取指定表单可用于列字段映射存储的所有字段（含系统变量），返回 字段名 → 字段描述 映射。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/forms/{formId}/valuestorefields
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
formId	path	string	是	数据来源表单Id

响应

data：Map<String, String>（字段名 → 描述）。

{ "errcode": 0, "errmsg": "ok", "data": { "字段名1": "字段描述1", "字段名2": "字段描述2" }, "errors": null }

---

25. 视图获取系统筛选字段

获取指定表单可作为系统筛选字段的可选项映射。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/{applicationId}/forms/{formId}/systemscreeningfields
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
formId	path	string	是	数据来源表单Id

响应

data：Map<String, String>（字段名 → 描述，按 LinkedHashMap 保持插入顺序）。异常被吞掉，仅返回空 map。

{ "errcode": 0, "errmsg": "ok", "data": { "字段名": "字段描述" }, "errors": null }

---

26. 根据筛选字段获取作用域

按选中的筛选字段返回该字段可用的作用域映射（用于权限作用域配置）。注意该端点路径下不含 {applicationId} 段。

• 接口类型：REST 资源
• 请求方式：GET
• 请求路径：/getScopeByField/{authField}（完整：{designer-context}/api/designtime/applications/getScopeByField/{authField}）
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
authField	path	string	是	选中的筛选字段

响应

data：Map<String, String>（作用域键 → 描述，LinkedHashMap 保持顺序）。异常被吞掉，仅返回空 map。

{ "errcode": 0, "errmsg": "ok", "data": { "作用域1": "描述1" }, "errors": null }

---

27. 视图列排序修改

修改视图列的排序号，支持两种模式：传入完整列Id数组（按数组下标重排 orderno），或仅传入两个互换列Id（oId/nId）交换 orderno（同序号时先重置全部 orderno）。

• 接口类型：REST 资源
• 请求方式：PUT
• 请求路径：/{applicationId}/views/column/order
• 鉴权：是（需 designerToken）
• Tag：设计时-视图模块

请求参数

参数名	位置	类型	必填	说明
applicationId	path	string	是	应用Id
oId	query	string	否	选中的列Id（互换模式）
nId	query	string	否	互换的列Id（互换模式）
ids	body	string	否	列Id数组（数组模式，按下标重排 orderno）

模式判定：ids 非空走数组模式；为空走 oId/nId 互换模式。

请求体（数组模式）

["<columnId1>", "<columnId2>", "<columnId3>"]

响应

data：String，固定文案 "修改成功"。

{ "errcode": 0, "errmsg": "ok", "data": "修改成功", "errors": null }

---