# 视图配置（view get/update <attr>）

按属性局部读/写视图配置。每个属性独立子命令，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 设置可见字段：

```bash
# --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 <attr>

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

```bash
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 <attr>

所有 `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 子块对象 |

```bash
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 子块 |

```bash
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 |

```bash
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, ...}` |

```bash
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` 优先） |

```bash
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）：

```bash
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）

```bash
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](./aitable-filter-sort.md)。

### view update name（重命名）

```bash
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 卡片为啥不显示封面"

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

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

```bash
# 第 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 时间轴改成季度尺度并加节假日

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

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

```bash
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）

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