更新视图

局部更新单张视图的属性。

鉴权方式

AppKey + Sign 是应用密钥鉴权，由管理员创建，用于以应用管理员身份访问应用数据。

版本

请求地址

PATCH

Path 参数

名称	类型	必填	描述
`worksheet_id`	`string`	是	工作表 ID 或别名示例值：`"worksheet_id"`
`view_id`	`string`	是	视图 ID 示例值：`"view_id"`

Header 参数

名称	类型	必填	描述
`HAP-Appkey`	`string`	是	HAP应用密钥
`HAP-Sign`	`string`	是	HAP签名

Body 参数

名称	类型	必填	描述
`name`	`string`	否	视图名称
`type`	`string`	否	视图类型可选值： `"table""kanban""gallery""calendar""hierarchy""gantt""resource""detail""map"`
`config`	`object`	否	视图专有配置，字段含义同批量新建视图；省略时保留原配置，传入时按子属性合并，并校验合并后的配置。
`config.groupField`	`string`	否	kanban: 作为分组依据的关联字段或单选字典字段（传字段 alias 或字段 ID）
`config.locationField`	`string`	否	map: 定位字段（传字段 alias 或字段 ID）
`config.relationField`	`string`	否	hierarchy: 树形层级依赖的关联字段（传字段 alias 或字段 ID）
`config.dates`	`object[]`	否	calendar: 包含 startField 和 endField
`config.dates.startField`	`string`	否	开始时间字段（传字段 alias 或字段 ID）
`config.dates.endField`	`string`	否	结束时间字段（传字段 alias 或字段 ID）
`config.startField`	`string`	否	gantt/resource 的开始时间字段（传字段 alias 或字段 ID）
`config.endField`	`string`	否	gantt/resource 的结束时间字段（传字段 alias 或字段 ID）
`config.resourceField`	`string`	否	resource: 负责人字段（传字段 alias 或字段 ID）
`config.mode`	`string`	否	detail 専用。all=左侧显示记录列表（默认）；first=不显示列表，直接显示第一条记录详情，适用于参数配置页可选值： `"all""first"`
`filter`	`object`	否	视图筛选条件；省略时保留，传空对象清空，非空条件的根节点使用 group。
`filter.type`	`string`	否	— 可选值： `"group""condition"`
`filter.logic`	`string`	否	— 可选值： `"AND""OR"`
`filter.children`	`object[]`	否	—
`filter.field`	`string`	否	必须传入Field ID，注意：当字段结构来自 Markdown 格式时，如果字段 ID 或中包含 '(isTitle)'，该标记仅用于表示此字段是标题字段，不属于字段 ID 的一部分。在传参时应移除 '(isTitle)'，仅保留真实字段 ID。
`filter.operator`	`string`	否	支持的筛选运算符：比较运算符： eq：等于，例如 `"Beijing"` 或 `["<targetid>"]` ne：不等于，例如 `"London"` 或 `["<targetid>"]` gt：大于，例如 20 或 "2025-02-06 00:00:00" ge：大于等于，例如 10 lt：小于，例如 20 le：小于等于，例如 100 in：是其中一个，例如 ["value1", "value2"] notin：不是任意一个，例如 ["value1", "value2"] contains：包含，例如 "Ch" 或 ["销售部", "市场部"] notcontains：不包含，例如 "Ch" 或 ["销售部", "市场部"] concurrent：同时包含，例如 `["<id1>", "<id2>"]` belongsto：属于，例如 `["<departmentid>"]` notbelongsto：不属于，例如 `["<departmentid>"]` startswith：开头是，例如 "张" notstartswith：开头不是，例如 "李" endswith：结尾是，例如 "公司" notendswith：结尾不是，例如 "有限公司" between：在范围内，例如 ["2025-01-01", "2025-01-31"] notbetween：不在范围内，例如 ["10", "20"] 为空运算符： isempty：为空，不需要 value isnotempty：不为空，不需要 value 可选值： `"eq""ne""gt""ge""lt""le""in""notin""contains""notcontains""concurrent""belongsto""notbelongsto""startswith""notstartswith""endswith""notendswith""between""notbetween""isempty""isnotempty"`
`filter.value`	`object`	否	筛选值。根据运算符不同，可传字符串、数字或数组。标量示例："Beijing"、20、"2025-02-06 00:00:00" 数组示例：["value1", "value2"]、["2025-01-01", "2025-01-31"] isempty / isnotempty：不需要传 value 特殊 AccountID（适用于 Collaborator 等成员字段筛选）： user-self：当前用户 user-sub：下属 user-workflow：工作流 user-api：API
`sort`	`object[]`	否	排序规则列表。支持多个排序字段，数组顺序表示排序优先级。非必填。
`sort.fieldId`	`string`	是	排序字段 alias 或字段 ID。
`sort.sortType`	`string`	是	排序方式：1 或 asc 表示升序，2 或 desc 表示降序；详情统一返回 asc 或 desc。可选值： `"1""2""asc""desc"`
`color`	`object`	否	记录颜色配置，只配置用于着色的字段。
`color.fieldId`	`string`	否	用于着色的字段引用，传字段 alias或字段 ID。仅支持 fieldType=9、11 且已开启选项标签颜色的单选字段。
`quickFilters`	`object[]`	否	快速筛选字段列表。数组顺序即显示顺序。仅支持 fieldType=2、4、7、32、33、6、8、31、9、10、11、26、27、28、29、35、36、15、16。建议选择 2-4 个最常用筛选维度；除选项字段 fieldType=9、10、11 可配置 selectionType 和 displayType 外，其他 UI 配置均由接口使用默认值。
`quickFilters.fieldId`	`string`	是	快速筛选字段 alias 或字段 ID。
`quickFilters.selectionType`	`string`	否	选项字段的筛选值数量，仅适用于 fieldType=9、10、11。single=单选，multiple=多选。可选值： `"single""multiple"`
`quickFilters.displayType`	`string`	否	选项字段的显示方式，仅适用于 fieldType=9、10、11。dropdown=下拉框，tile=平铺。可选值： `"dropdown""tile"`
`hiddenFields`	`string[]`	否	在此视图中隐藏的字段列表，对记录详情生效。
`tableFields`	`string[]`	否	表格形态（table、gantt）中显示的字段列表。不填则显示全部字段。
`filterList`	`object`	否	侧边栏筛选列表配置。设置后在视图左侧以该字段的选项值为维度显示筛选入口。
`filterList.filterField`	`string`	否	用于侧边筛选的字段 alias 或字段 ID（不能传 name）
`card`	`object`	否	卡片显示配置，适用于 kanban / gallery / hierarchy 以及 calendar、gantt、map、resource hover 时的卡片。所有字段均传 alias 或字段 ID，不能传 name。
`card.titleField`	`string`	否	卡片标题字段（所有文本类字段均可）
`card.summaryField`	`string`	否	卡片摘要字段（Text / RichText 类型）
`card.coverField`	`string`	否	卡片封面字段（仅支持附件类型字段）
`card.coverDirection`	`string`	否	封面位置。top=顶部（默认），left=左侧，right=右侧。gallery 推荐 top；detail/kanban 左右均可可选值： `"top""left""right"`
`card.coverDisplayMode`	`string`	否	封面显示模式。full=铺满（默认），square=方形裁切，circle=圆形裁切。人员头像场景用 circle，产品图用 full 或 square 可选值： `"full""square""circle"`
`card.displayFields`	`string[]`	否	卡片中额外展示的字段列表，推荐 1-4 个
`actions`	`object`	否	视图中显示的操作按钮配置。需要先调用 batch_create_custom_actions 获取自定义动作 ID，再在此引用。
`actions.detailActions`	`string[]`	否	打开记录详情后显示的操作按钮（自定义动作 ID 数组）
`actions.quickActions`	`object[]`	否	表格行/卡片上直接显示的快捷操作按钮列表
`actions.quickActions.type`	`string`	是	系统操作固定传: copy / print / delete / share；自定义动作传 action
`actions.quickActions.id`	`string`	否	type=action 时传自定义动作 ID；系统操作不传
`group`	`object`	否	分组配置。table / gallery / kanban 视图支持按指定字段分组显示记录。
`group.groupField`	`string`	否	分组依据字段的 alias 或字段 ID

响应参数

200Successful response

名称	类型	描述
`success`	`boolean`	请求是否成功
`error_code`	`integer`	错误码，成功为 1
`error_msg`	`string`	错误描述，成功时为空字符串
`data`	`object`	—
`data.id`	`string`	视图 ID
`data.name`	`string`	视图名称

curl -X PATCH "https://example.com/v3/app/worksheets/worksheet_id/views/view_id" \  -H "HAP-Appkey: {{HAP-Appkey}}" \  -H "HAP-Sign: {{HAP-Sign}}" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "type": "gallery",    "filter": {      "type": "group",      "logic": "AND",      "children": [        {          "type": "condition",          "field": "string",          "operator": "eq",          "value": "string"        }      ]    },    "sort": [      {        "fieldId": "string",        "sortType": "asc"      }    ],    "color": {      "fieldId": "string"    },    "quickFilters": [      {        "fieldId": "string",        "selectionType": "single",        "displayType": "dropdown"      }    ],    "hiddenFields": [      "string"    ],    "tableFields": [      "string"    ],    "filterList": {      "filterField": "string"    },    "card": {      "titleField": "string",      "summaryField": "string",      "coverField": "string",      "coverDirection": "top",      "coverDisplayMode": "full",      "displayFields": [        "string"      ]    },    "actions": {      "detailActions": [        "string"      ],      "quickActions": [        {          "type": "action",          "id": "string"        }      ]    },    "group": {      "groupField": "string"    }  }'

{  "success": true,  "error_code": 1,  "error_msg": "",  "data": {    "id": "view_id",    "name": "新增甘特视图"  }}

获取视图详情

返回该视图的完整配置树模型。

删除视图

视图

更新视图

局部更新单张视图的属性。

鉴权方式

AppKey + Sign 是应用密钥鉴权，由管理员创建，用于以应用管理员身份访问应用数据。

版本

请求地址

PATCH

Path 参数

名称	类型	必填	描述
`worksheet_id`	`string`	是	工作表 ID 或别名示例值：`"worksheet_id"`
`view_id`	`string`	是	视图 ID 示例值：`"view_id"`

Header 参数

名称	类型	必填	描述
`HAP-Appkey`	`string`	是	HAP应用密钥
`HAP-Sign`	`string`	是	HAP签名

Body 参数

名称	类型	必填	描述
`name`	`string`	否	视图名称
`type`	`string`	否	视图类型可选值： `"table""kanban""gallery""calendar""hierarchy""gantt""resource""detail""map"`
`config`	`object`	否	视图专有配置，字段含义同批量新建视图；省略时保留原配置，传入时按子属性合并，并校验合并后的配置。
`config.groupField`	`string`	否	kanban: 作为分组依据的关联字段或单选字典字段（传字段 alias 或字段 ID）
`config.locationField`	`string`	否	map: 定位字段（传字段 alias 或字段 ID）
`config.relationField`	`string`	否	hierarchy: 树形层级依赖的关联字段（传字段 alias 或字段 ID）
`config.dates`	`object[]`	否	calendar: 包含 startField 和 endField
`config.dates.startField`	`string`	否	开始时间字段（传字段 alias 或字段 ID）
`config.dates.endField`	`string`	否	结束时间字段（传字段 alias 或字段 ID）
`config.startField`	`string`	否	gantt/resource 的开始时间字段（传字段 alias 或字段 ID）
`config.endField`	`string`	否	gantt/resource 的结束时间字段（传字段 alias 或字段 ID）
`config.resourceField`	`string`	否	resource: 负责人字段（传字段 alias 或字段 ID）
`config.mode`	`string`	否	detail 専用。all=左侧显示记录列表（默认）；first=不显示列表，直接显示第一条记录详情，适用于参数配置页可选值： `"all""first"`
`filter`	`object`	否	视图筛选条件；省略时保留，传空对象清空，非空条件的根节点使用 group。
`filter.type`	`string`	否	— 可选值： `"group""condition"`
`filter.logic`	`string`	否	— 可选值： `"AND""OR"`
`filter.children`	`object[]`	否	—
`filter.field`	`string`	否	必须传入Field ID，注意：当字段结构来自 Markdown 格式时，如果字段 ID 或中包含 '(isTitle)'，该标记仅用于表示此字段是标题字段，不属于字段 ID 的一部分。在传参时应移除 '(isTitle)'，仅保留真实字段 ID。
`filter.operator`	`string`	否	支持的筛选运算符：比较运算符： eq：等于，例如 `"Beijing"` 或 `["<targetid>"]` ne：不等于，例如 `"London"` 或 `["<targetid>"]` gt：大于，例如 20 或 "2025-02-06 00:00:00" ge：大于等于，例如 10 lt：小于，例如 20 le：小于等于，例如 100 in：是其中一个，例如 ["value1", "value2"] notin：不是任意一个，例如 ["value1", "value2"] contains：包含，例如 "Ch" 或 ["销售部", "市场部"] notcontains：不包含，例如 "Ch" 或 ["销售部", "市场部"] concurrent：同时包含，例如 `["<id1>", "<id2>"]` belongsto：属于，例如 `["<departmentid>"]` notbelongsto：不属于，例如 `["<departmentid>"]` startswith：开头是，例如 "张" notstartswith：开头不是，例如 "李" endswith：结尾是，例如 "公司" notendswith：结尾不是，例如 "有限公司" between：在范围内，例如 ["2025-01-01", "2025-01-31"] notbetween：不在范围内，例如 ["10", "20"] 为空运算符： isempty：为空，不需要 value isnotempty：不为空，不需要 value 可选值： `"eq""ne""gt""ge""lt""le""in""notin""contains""notcontains""concurrent""belongsto""notbelongsto""startswith""notstartswith""endswith""notendswith""between""notbetween""isempty""isnotempty"`
`filter.value`	`object`	否	筛选值。根据运算符不同，可传字符串、数字或数组。标量示例："Beijing"、20、"2025-02-06 00:00:00" 数组示例：["value1", "value2"]、["2025-01-01", "2025-01-31"] isempty / isnotempty：不需要传 value 特殊 AccountID（适用于 Collaborator 等成员字段筛选）： user-self：当前用户 user-sub：下属 user-workflow：工作流 user-api：API
`sort`	`object[]`	否	排序规则列表。支持多个排序字段，数组顺序表示排序优先级。非必填。
`sort.fieldId`	`string`	是	排序字段 alias 或字段 ID。
`sort.sortType`	`string`	是	排序方式：1 或 asc 表示升序，2 或 desc 表示降序；详情统一返回 asc 或 desc。可选值： `"1""2""asc""desc"`
`color`	`object`	否	记录颜色配置，只配置用于着色的字段。
`color.fieldId`	`string`	否	用于着色的字段引用，传字段 alias或字段 ID。仅支持 fieldType=9、11 且已开启选项标签颜色的单选字段。
`quickFilters`	`object[]`	否	快速筛选字段列表。数组顺序即显示顺序。仅支持 fieldType=2、4、7、32、33、6、8、31、9、10、11、26、27、28、29、35、36、15、16。建议选择 2-4 个最常用筛选维度；除选项字段 fieldType=9、10、11 可配置 selectionType 和 displayType 外，其他 UI 配置均由接口使用默认值。
`quickFilters.fieldId`	`string`	是	快速筛选字段 alias 或字段 ID。
`quickFilters.selectionType`	`string`	否	选项字段的筛选值数量，仅适用于 fieldType=9、10、11。single=单选，multiple=多选。可选值： `"single""multiple"`
`quickFilters.displayType`	`string`	否	选项字段的显示方式，仅适用于 fieldType=9、10、11。dropdown=下拉框，tile=平铺。可选值： `"dropdown""tile"`
`hiddenFields`	`string[]`	否	在此视图中隐藏的字段列表，对记录详情生效。
`tableFields`	`string[]`	否	表格形态（table、gantt）中显示的字段列表。不填则显示全部字段。
`filterList`	`object`	否	侧边栏筛选列表配置。设置后在视图左侧以该字段的选项值为维度显示筛选入口。
`filterList.filterField`	`string`	否	用于侧边筛选的字段 alias 或字段 ID（不能传 name）
`card`	`object`	否	卡片显示配置，适用于 kanban / gallery / hierarchy 以及 calendar、gantt、map、resource hover 时的卡片。所有字段均传 alias 或字段 ID，不能传 name。
`card.titleField`	`string`	否	卡片标题字段（所有文本类字段均可）
`card.summaryField`	`string`	否	卡片摘要字段（Text / RichText 类型）
`card.coverField`	`string`	否	卡片封面字段（仅支持附件类型字段）
`card.coverDirection`	`string`	否	封面位置。top=顶部（默认），left=左侧，right=右侧。gallery 推荐 top；detail/kanban 左右均可可选值： `"top""left""right"`
`card.coverDisplayMode`	`string`	否	封面显示模式。full=铺满（默认），square=方形裁切，circle=圆形裁切。人员头像场景用 circle，产品图用 full 或 square 可选值： `"full""square""circle"`
`card.displayFields`	`string[]`	否	卡片中额外展示的字段列表，推荐 1-4 个
`actions`	`object`	否	视图中显示的操作按钮配置。需要先调用 batch_create_custom_actions 获取自定义动作 ID，再在此引用。
`actions.detailActions`	`string[]`	否	打开记录详情后显示的操作按钮（自定义动作 ID 数组）
`actions.quickActions`	`object[]`	否	表格行/卡片上直接显示的快捷操作按钮列表
`actions.quickActions.type`	`string`	是	系统操作固定传: copy / print / delete / share；自定义动作传 action
`actions.quickActions.id`	`string`	否	type=action 时传自定义动作 ID；系统操作不传
`group`	`object`	否	分组配置。table / gallery / kanban 视图支持按指定字段分组显示记录。
`group.groupField`	`string`	否	分组依据字段的 alias 或字段 ID

响应参数

200Successful response

名称	类型	描述
`success`	`boolean`	请求是否成功
`error_code`	`integer`	错误码，成功为 1
`error_msg`	`string`	错误描述，成功时为空字符串
`data`	`object`	—
`data.id`	`string`	视图 ID
`data.name`	`string`	视图名称

curl -X PATCH "https://example.com/v3/app/worksheets/worksheet_id/views/view_id" \  -H "HAP-Appkey: {{HAP-Appkey}}" \  -H "HAP-Sign: {{HAP-Sign}}" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "type": "gallery",    "filter": {      "type": "group",      "logic": "AND",      "children": [        {          "type": "condition",          "field": "string",          "operator": "eq",          "value": "string"        }      ]    },    "sort": [      {        "fieldId": "string",        "sortType": "asc"      }    ],    "color": {      "fieldId": "string"    },    "quickFilters": [      {        "fieldId": "string",        "selectionType": "single",        "displayType": "dropdown"      }    ],    "hiddenFields": [      "string"    ],    "tableFields": [      "string"    ],    "filterList": {      "filterField": "string"    },    "card": {      "titleField": "string",      "summaryField": "string",      "coverField": "string",      "coverDirection": "top",      "coverDisplayMode": "full",      "displayFields": [        "string"      ]    },    "actions": {      "detailActions": [        "string"      ],      "quickActions": [        {          "type": "action",          "id": "string"        }      ]    },    "group": {      "groupField": "string"    }  }'

{  "success": true,  "error_code": 1,  "error_msg": "",  "data": {    "id": "view_id",    "name": "新增甘特视图"  }}

获取视图详情

返回该视图的完整配置树模型。

删除视图