EP-Hub-Skill/.agents/skills/dingtalk-aitable/references/aitable/aitable-view-config.md

视图配置（view get/update ）

按属性局部读/写视图配置。每个属性独立子命令，typed flag 友好，agent 不必拼 JSON。 向后兼容：view update --config '{...}' 一次多属性入口仍可用。

viewType × 支持矩阵

viewType	card	timebar	aggregate	filter / sort / group	visible-fields	field-widths	name
Grid			✅	✅	✅	✅	✅
Kanban	✅			✅	✅		✅
Gallery	✅			✅	✅		✅
Gantt		✅		✅	✅		✅
Calendar				✅	✅		✅
FormDesigner	（走 form 系列命令）

card 在 Kanban 走 kanbanCard，在 Gallery 走 galleryCard，CLI 自动按 viewType dispatch（preflight 1 次 get_views）。timebar 仅 Gantt 支持；Calendar 服务端未暴露任何 timebar 配置。

Gantt 视图必须两步创建：view create --view-type Gantt 只创建空壳（ganttTimebar: {}），必须紧跟 view update timebar --start-field <日期字段ID> 绑定时间轴字段，否则视图打开是空白。view create --config 不接受 ganttTimebar，请在创建后使用专属子命令。

创建：view create

--view-type 支持 Grid、Kanban、Gantt、Calendar、Gallery、FormDesigner。创建时通过 --config JSON 设置可见字段：

# --config JSON：可同时配置可见字段、筛选、排序和分组；主字段必须排第一
dws aitable view create --base-id BASE_ID --table-id TABLE_ID \
  --view-type Grid --name "任务视图" \
  --config '{"visibleFieldIds":["fldPrimary","fldStatus","fldOwner"],"sort":[{"fieldId":"fldStatus","direction":"asc"}]}'

创建阶段的 --config 是 JSON 对象，并且只接受以下 4 个 key：

key	类型	说明
visibleFieldIds	string[]	fieldId 数组，不接受字段名；至少一个，主字段必须排第一
filter	object[]	筛选规则数组；兼容单个 object，CLI 会自动包装为数组
sort	object[]	排序规则数组；兼容单个 object，CLI 会自动包装为数组
group	object[]	分组规则数组；兼容单个 object，CLI 会自动包装为数组

描述使用独立的 --desc '{"content":[]}'；description、fieldWidths、aggregate、kanbanCard、ganttTimebar、galleryCard 等其他 key 会在调用服务端前被拒绝，并提示对应的 view update 子命令。

读取：view get

所有 view get <attr> 共用 --base-id / --table-id / --view-id，输出是该属性子块的 JSON（不存在时输出 {}）。viewType 不匹配会报错并指明应该选哪种视图。

dws aitable view get card --view-id VIEW_ID --format json            # Kanban / Gallery
dws aitable view get timebar --view-id VIEW_ID --format json         # Gantt
dws aitable view get aggregate --view-id VIEW_ID --format json       # Grid
dws aitable view get filter --view-id VIEW_ID --format json          # 所有
dws aitable view get sort --view-id VIEW_ID --format json
dws aitable view get group --view-id VIEW_ID --format json
dws aitable view get visible-fields --view-id VIEW_ID --format json
dws aitable view get field-widths --view-id VIEW_ID --format json    # Grid

写入：view update

所有 view update <attr> 共用 --base-id / --table-id / --view-id。 typed flag + --json 可混用；冲突时 typed flag 优先并 stderr 提示。 card / timebar / aggregate 三类写入有 viewType 校验（preflight 1 次 get_views）。

view update card（Kanban / Gallery）

服务端按 viewType 分发到 kanbanCard 或 galleryCard。typed flag 共享。

flag	类型	说明
--cover-field-id	string	封面字段 ID（Kanban / Gallery 通用），与 --no-cover 互斥
--no-cover	bool	清除封面（等价 coverFieldId="NONE"）
--cover-resize-mode	string	cover / contain / stretch
--hidden-field-title	bool	隐藏字段名标题（仅 Kanban 生效）
--cover-mode	string	none / auto / custom（仅 Gallery 生效）
--display-field-name	bool	是否显示字段名（仅 Gallery 生效）
--json	JSON	完整 card 子块对象

dws aitable view update card --view-id KANBAN_ID --cover-field-id fldAttachment --cover-resize-mode contain
dws aitable view update card --view-id KANBAN_ID --no-cover
dws aitable view update card --view-id GALLERY_ID --cover-mode auto
dws aitable view update card --view-id GALLERY_ID --json '{"coverMode":"custom","coverFieldId":"fldX","displayFieldName":true}'

view update timebar（仅 Gantt）

flag	类型	说明
--start-field	string (date fieldId)	开始日期字段
--end-field	string (date fieldId)	结束日期字段
--display-field-id	string	时间条上显示的标题字段
--timeline-scale	string	year / quarter / month / weeks
--color-configs	JSON 数组	颜色配置数组（结构由下游协议定义；清空传 []）
--official-holiday	bool	是否标注法定节假日
--json	JSON	完整 ganttTimebar 子块

dws aitable view update timebar --view-id GANTT_ID --start-field fldStart --end-field fldEnd --timeline-scale month
dws aitable view update timebar --view-id GANTT_ID --official-holiday=true

view update aggregate（仅 Grid）

值是 map[fieldId]→AggregateAction string；传 null 清除某个字段聚合。

flag	类型	说明
--field-id	string	配合 --action 设置单字段聚合
--action	string	SUM/AVG/MAX/MIN/MEDIAN/RANGE/TOTAL/DISTINCT/EXIST/UN_EXIST/CHECKED/EARLIEST_DATE 等（按字段类型可用）
--clear-field-id	string (CSV)	一/多个字段 ID，清除其聚合
--json	JSON	完整 aggregate map

dws aitable view update aggregate --view-id GRID_ID --field-id fldX --action SUM
dws aitable view update aggregate --view-id GRID_ID --clear-field-id fldA,fldB
dws aitable view update aggregate --view-id GRID_ID --json '{"fldX":"AVG","fldY":null}'

view update field-widths（仅 Grid）

flag	类型
--field-id + --width	string + int（单字段）
--json	{fldId: width, ...}

dws aitable view update field-widths --view-id GRID_ID --field-id fldX --width 200
dws aitable view update field-widths --view-id GRID_ID --json '{"fldA":120,"fldB":200}'

view update visible-fields（通用）

整组替换可见字段列表与顺序。field get 返回的第一个字段是系统行索引/主字段；无论它显示为 text 还是 primaryDoc，都必须保留在数组第一位，且不能隐藏。不要仅凭字段类型猜主字段。

⚠️ 注意：服务端只接受 reorder，不接受真"隐藏字段"——如果传入的列表比当前 columns 短，缺失的字段不会被隐藏。需要真正隐藏字段请到 AI 表格 Web UI。

flag	类型
--field-ids	string (CSV)
--json	string 数组 JSON（与 --field-ids 同传时 --json 优先）

dws aitable view update visible-fields --view-id VIEW_ID --field-ids fldPrimary,fldA,fldB
dws aitable view update visible-fields --view-id VIEW_ID --json '["fldPrimary","fldA","fldB"]'

列顺序最短闭环

用户说“客户名称最左、状态在金额前”时，不要用通用 +view-update --config 探索：

1. dws aitable field get --base-id <B> --table-id <T> --format json 取字段有序列表；第一个 fieldId 固定为数组第 1 项。目标 viewId 从真实上下文或 view get 返回中取得。
2. dws aitable view get visible-fields ... 取当前完整列数组；必须保留全部现有字段，因为该接口只支持 reorder，不是真隐藏。
3. 只重排目标：[主字段, 客户名称, ..., 状态, 金额, ...]，其他字段保持相对顺序；一次执行 view update visible-fields。
4. 再次 view get visible-fields，数组完全一致才算完成。遇到 PRIMARY_FIELD_CANNOT_BE_MOVED/HIDDEN 立即停止，重新按步骤 1 构造一次；禁止继续猜排列。

“固定/冻结左侧列”与“放到最左边”不是同一操作。只有 Grid 支持冻结；若要冻结主字段后的目标列，需要冻结前 N 列（例如目标位于第 2 列则 count=2）：

dws aitable +view-set-frozen-cols --base-id <B> --table-id <T> --view-id <V> --count <N>
dws aitable +view-get-frozen-cols --base-id <B> --table-id <T> --view-id <V>

Kanban/Gallery 等视图只调整列顺序，不尝试冻结。

view update filter / sort / group（通用，纯 --json）

dws aitable view update filter --view-id VIEW_ID --json '[{"operator":"and","operands":[{"operator":"eq","operands":["fldX","value"]}]}]'
dws aitable view update sort   --view-id VIEW_ID --json '[{"fieldId":"fldX","direction":"asc"}]'
dws aitable view update group  --view-id VIEW_ID --json '[{"fieldId":"fldX","direction":"asc"}]'

filter/sort/group 入参格式与 record query --filters（对象格式）不同：view config 这边外层必须是数组。传对象 CLI 会自动 wrap，建议直接用数组。详见 aitable-filter-sort.md。

view update name（重命名）

dws aitable view update name --view-id VIEW_ID --name "新视图名"

等价于 dws aitable view update --view-id VIEW_ID --name "新视图名"，无 config 参数。

服务端字段速查（与 dws CLI 关系）

dws 子命令	服务端 update_view.config 子键	服务端 Java 模型
view update card（Kanban）	kanbanCard	KanbanCardUpdateInput
view update card（Gallery）	galleryCard	GalleryCardUpdateInput
view update timebar	ganttTimebar	GanttTimebarUpdateInput
view update aggregate	aggregate	Map<fieldId, AggregateAction>
view update visible-fields	visibleFieldIds	List<String>
view update filter / sort / group	filter / sort / group	List<Object>
view update field-widths	fieldWidths	Map<String, Object>
view update name	（不在 config 内）newViewName 顶层	—

典型工作流

排查"Kanban 卡片为啥不显示封面"

dws aitable view get card --view-id KANBAN_ID --format json
# → 看 coverFieldId 是不是 "NONE" 或缺失；不是再看 coverResizeMode 是不是 contain 导致裁掉

创建可用的 Gantt 视图（必须两步）

# 第 1 步：创建 Gantt 视图
dws aitable view create --base-id BASE_ID --table-id TABLE_ID \
  --view-type Gantt --name "项目甘特图" -f json
# → 记录返回的 viewId

# 第 2 步（必须）：绑定日期字段，否则视图为空
dws aitable view update timebar --base-id BASE_ID --table-id TABLE_ID \
  --view-id VIEW_ID --start-field fldDateStart
# 可选：加结束日期、标题字段、时间尺度
#   --end-field fldDateEnd --display-field-id fldName --timeline-scale month

把 Gantt 时间轴改成季度尺度并加节假日

dws aitable view update timebar --view-id GANTT_ID \
  --timeline-scale quarter --official-holiday=true

用 dws 脚本批量替换 Kanban 封面字段

for v in viw1 viw2 viw3; do
  dws aitable view update card --view-id $v --cover-field-id fldNewCover --cover-resize-mode cover --format json | jq .status
done

一次性多属性更新（仍走 legacy --config）

dws aitable view update --view-id VIEW_ID --config '{
  "visibleFieldIds":["fldPrimary","fldA","fldB"],
  "filter":[{"operator":"and","operands":[]}],
  "kanbanCard":{"coverFieldId":"fldImg","coverResizeMode":"contain"}
}'