跳转至

设计时 widget 分组管理（PageWidgetGroupController）

首页 widget 分组（PageWidgetGroup）的设计时管理：分组的列表查询、详情获取、新建、更新与批量删除；用于组织首页小工具所属的分组容器。

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

公共说明

  • 鉴权：是（需 designerToken）。控制器继承自 AbstractDesignTimeController（基类为 @RestController），通过 Security.getDesignerIdFromToken(request) 从 designerToken JWT 中解析设计器用户。鉴权机制详见 index.md「鉴权说明」。
  • 路径变量：{applicationId}、{widgetGroupId} 均为**明文设计时 ID**。
  • 响应：统一 Resource（见 ../index.md「统一响应结构」）。成功 errcode=0；异常默认 errcode=500；保存校验失败（名称重复）捕获 OBPMValidateException，返回 errcode=40001，errmsg="名称已经存在！"。
  • HTTP 方法：受 CommonSecurityFilter 限制，仅允许 GET/POST/HEAD/OPTIONS。
  • 请求体约定：POST/PUT 接收原始 JSON 字符串（@RequestBody String content），由服务端用 JSONObject.fromObject 解析后 json2obj 转 PageWidgetGroup；DELETE 同样接收 JSON 字符串（@RequestBody String content），但由 JsonPath 解析为 List<String>（与同模块其他控制器接收 String[] 不同）。
  • 隶属关系：新建时 parentId 固定设为 applicationId。
  • 更新语义：更新时先按 widgetGroupId 查询旧对象并克隆（BeanUtils.cloneBean），仅应用请求体的 name 并清空 uri，校验后 update。
  • 更新接口的 HTTP 状态码：源码标注为 201（CREATED），实际语义为「更新成功」，调用方应按 201 处理。

1. 获取 widget 分组列表

分页获取指定应用下的 widget 分组列表，可按名称关键字查询。

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

请求参数

参数名 位置 类型 必填 说明
applicationId path string 是 应用Id
name query string 否 按名称查询关键字（@RequestParam(required=false)）
pageNo query int 否 页码（@RequestParam(required=false, defaultValue="1")）
linesPerPage query int 否 每页条数（@RequestParam(required=false, defaultValue="10")）

请求示例

GET /api/designtime/applications/{applicationId}/widgetgroups?name=&pageNo=1&linesPerPage=10 HTTP/1.1

响应

结构：统一 Resource（见 ../index.md「统一响应结构」）。 data：DataPackage<PageWidgetGroup>（含分页字段与 datas）。

成功示例： 

{
  "errcode": 0,
  "errmsg": "ok",
  "data": {
    "linesPerPage": 10,
    "pageNo": 1,
    "pageCount": 1,
    "rowCount": 1,
    "datas": [
      { "id": "...", "name": "分组名", "...": "..." }
    ]
  },
  "errors": null
}
失败示例： 
{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

2. 获取 widget 分组详情

按分组Id获取完整 widget 分组对象。

  • 接口类型：REST 资源
  • 请求方式：GET
  • 请求路径：/{applicationId}/widgetgroups/{widgetGroupId}
  • 鉴权：是（需 designerToken）
  • Tag：设计时-widget 分组模块

请求参数

参数名 位置 类型 必填 说明
applicationId path string 是 应用Id
widgetGroupId path string 是 widget 分组Id

响应

data：PageWidgetGroup 完整对象。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "...", "name": "...", "...": "..." }, "errors": null }
失败示例： 
{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }

3. 新建 widget 分组

在指定应用下新建 widget 分组。请求体解析为 PageWidgetGroup 后强制覆盖 applicationid/parentId（均设为 applicationId）；保存前调用 doSaveValidate 校验名称不重复（按 id 是否为空区分新建/更新校验路径）。HTTP 状态码 201。

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

请求参数

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

请求体

对应 PageWidgetGroup 对象 JSON（name 等）。 

{ "name": "<分组名>" }

响应

data：JSONObject，含 id（分组Id，源自请求体或服务端保存结果）。

{ "errcode": 0, "errmsg": "ok", "data": { "id": "<分组Id>" }, "errors": null }
失败示例（名称重复）： 
{ "errcode": 40001, "errmsg": "名称已经存在！", "data": null, "errors": null }

4. 更新 widget 分组

按分组Id更新 widget 分组。先按 widgetGroupId 查询旧对象并克隆，仅应用请求体的 name 并清空 uri，校验名称不重复后 update。HTTP 状态码源码标注为 201（CREATED），实际语义为「更新成功」。

  • 接口类型：REST 资源
  • 请求方式：PUT
  • 请求路径：/{applicationId}/widgetgroups/{widgetGroupId}
  • 鉴权：是（需 designerToken）
  • Tag：设计时-widget 分组模块

请求参数

参数名 位置 类型 必填 说明
applicationId path string 是 应用Id
widgetGroupId path string 是 widget 分组Id
content body string(JSON) 是 widget 分组对象 JSON（仅取 name）

请求体

{ "name": "<分组名>" }

响应

data：null（成功）。

{ "errcode": 0, "errmsg": "ok", "data": null, "errors": null }
失败示例（名称重复）： 
{ "errcode": 40001, "errmsg": "名称已经存在！", "data": null, "errors": null }

5. 删除 widget 分组（可批量）

按分组Id数组批量删除 widget 分组（含路径信息收集）。请求体为 JSON 字符串，由 JsonPath 解析为 List<String> 后转数组删除。

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

请求参数

参数名 位置 类型 必填 说明
applicationId path string 是 应用Id
content body string(JSON) 是 分组Id数组（JSON 数组字符串，由 JsonPath 解析为 List<String>）

请求体

["<widgetGroupId1>", "<widgetGroupId2>"]

响应

data：String，固定为 "删除成功"。

{ "errcode": 0, "errmsg": "ok", "data": "删除成功", "errors": null }
失败示例： 
{ "errcode": 500, "errmsg": "<异常信息>", "data": null, "errors": null }