yida-form-view git:20261105.1793c9eA

Immutable. This exact content never changes and is served at /api/v1/blob/c40220355b72bcce.

---
name: yida-form-view
description: 宜搭原生数据管理视图配置。读取视图，配置列、筛选和表格操作列，新建、重命名和排序视图。
---

# 原生表单视图

用于原生数据管理页的配置；仅换颜色、边框和密度用 `yida-data-manage-ui`，修改表单字段用 `yida-create-form-page`，查询记录用 `yida-data-management`。

## 步骤

1. 按根技能核验登录和 app/form 上下文，复用已有表单。不要创建同名表单或用自定义页面替换原生列表。
2. 执行 `openyida form-view list <appType> <formUuid> --with-config --json`，读取全部视图及 `staticConfig/defaultConfig`。选择返回的真实 `viewUuid`，不要猜测或把 `formUuid` 当作视图 ID。
3. 执行 `openyida form-view inspect <appType> <formUuid> <viewUuid> --json`。消费 `fields[].id/operatorMap`、`config` 和 `configHash`；需要业务字段身份时同时使用 `get-schema --compact --resolve-fields`。操作符大小写与平台返回一致，不猜测 `eq/EQ`。
4. 将本轮最小配置写到项目缓存 JSON 文件；执行 `openyida form-view save <appType> <formUuid> <viewUuid> --config <file> --expected-hash <configHash> --json`。CLI 先备份，再保存并回读；仅 `readbackVerified=true` 为配置成功。
5. 打开真实数据管理页，验证列顺序、宽度、冻结、筛选、横向滚动及记录。个人浏览器视图偏好可能覆盖管理员默认配置，不能仅凭 API 回读宣称浏览器验收通过。

## 配置映射

| 配置 | 原生字段 |
| --- | --- |
| 默认显示列及顺序 | `defaultConfig.showFields`，真实字段 ID 数组；`"all"` 为全部；不能传空数组 |
| 列宽 | `defaultConfig.widths`，字段 ID 到正数像素宽度的对象；`null` 清空宽度设置 |
| 冻结列 | `defaultConfig.lockFieldIds`，已显示字段 ID 数组；`[]` 取消冻结 |
| 默认筛选 | `defaultConfig.filter`，`values/operationValues/conditionType` 原生对象；`{}` 清空 |
| 默认排序 | `defaultConfig.sort`，`[{"id":"真实字段ID","isAsc":"y"}]`；`n` 降序 |
| 可用字段 | `staticConfig.columnFilter`，字段 ID 数组，平台 `['all']` 表示全部；它不是数据权限 |
| 视图数据范围 | `staticConfig.dataRange`，使用现有原生规则结构；`{}` 清空，验收实际查询结果 |

示例（必须替换为 inspect 返回的真实字段 ID）：

```json
{
  "defaultConfig": {
    "showFields": ["textField_REAL", "selectField_REAL"],
    "widths": {"textField_REAL": 280, "selectField_REAL": 160},
    "lockFieldIds": ["textField_REAL"]
  }
}
```

对象递归合并，数组替换；`filter` 和 `dataRange` 整体替换。未指定的配置保留；不要提交从空对象重造的整套设置。服务端自动更新 `latestUpdateTime`，不能把它当成用户配置。

## 新建表单的默认列顺序

`create-form create`、`batch` 的新建步骤及 `resume` 会自动保存第一个原生表格视图的服务端默认显示列，将已显示的实例标题（`processInstanceTitle` 或 `formInstanceTitle`）排到最后一个数据列。其他列的显隐、相对顺序及筛选、排序、宽度、冻结等配置保留。默认列为 `"all"` 或未设置时，沿用平台可展示字段及 `showOrder`，保留可展示子表字段，排除平台不支持的组件。

创建回执中的 `defaultView` 返回真实 `viewUuid`、`showFields`、`changed` 和 `readbackVerified`。只有服务端保存并回读通过才返回创建成功；这项默认行为不依赖 Agent 额外执行命令，也不写浏览器本地偏好。视图配置失败时保留已创建的 `formUuid`，用原 ID 执行 `create-form resume` 恢复，不重复新建表单。

用户明确指定显示列或列顺序时，在创建成功后用 `form-view save` 保存用户配置并回读。已有表单及批量计划中明确复用的 `formUuid` 不自动调整，按本轮要求操作。浏览器已有的个人偏好可能覆盖服务端默认值，页面验收需区分两者。

## 多视图

```bash
openyida form-view create <appType> <formUuid> --name "待处理订单" --json
openyida form-view order <appType> <formUuid> --config <order.json> --json
openyida form-view rename <appType> <formUuid> <viewUuid> --name "待处理订单" --json
```

create 只新建 table 视图，成功后复用返回 UUID 再配置。order 文件是包含当前全部视图 UUID 的数组（包括 form 视图），每项恰好一次，首项为默认入口。rename 使用平台返回的视图 UUID，名称去除首尾空格后限 20 字符，用于中文、英文和日文显示。save 写配置支持 table 视图。

## 向表格操作列添加按钮

用 `custom-button list` 查找数据所属表单的按钮 UUID。需要新按钮时，先用 `use_skill("yida-custom-button", "创建并回读表单自定义按钮")` 创建定义。再将该按钮追加到目标表格视图的操作列：

```bash
openyida form-view add-button <appType> <formUuid> <viewUuid> --button <buttonUuid> --expected-hash <configHash> --json
```

hash 来自目标视图的 inspect。已有同一引用时返回 `changed=false`。按钮按现有顺序追加，空按钮清单使用平台面板的系统按钮顺序。检查 `readbackVerified=true`，再在目标表格的操作列核对显示。

## 输出

重命名回读 `view.name`。添加按钮回读 `config.staticConfig.buttonList`。新增写入时保留 `backupPath`，用 `changed` 区分本次实际写入和已经生效的配置。

## 失败与恢复

- `FORM_VIEW_CONFLICT`：重新 inspect 后合并本轮修改；平台没有原子条件写入，避免多人同时编辑。
- 平台版本或权限拒绝：保留平台错误，停止写入；不修改版本、授权或额度。
- 写入传输错误或回读不一致时，保留 `backupPath`，先用 list 或 inspect 核对线上结果再决定是否重试。
- save 的备份文件包含原配置 `config.staticConfig/defaultConfig`。恢复时提取这两个对象写入恢复文件，重新 inspect 后使用 `save --replace --expected-hash <当前哈希>`；全量恢复必须提供两个完整配置对象，删除备份后新增的设置；其他资源和记录不在视图备份范围内。