244 lines
12 KiB
Markdown
244 lines
12 KiB
Markdown
# 视图配置（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"}
|
||
}'
|
||
```
|