70 lines
3.9 KiB
Markdown
70 lines
3.9 KiB
Markdown
# Sheet 浮动图表
|
||
|
||
## 真对象约束
|
||
|
||
用户要求图表时必须创建 Sheet chart 对象，不能用单元格字符、静态图片或本地绘图冒充。chartId 必须来自本任务 create/list；所有操作复用真实 nodeId、sheetId。
|
||
|
||
常见映射：分类比较用 column/bar，趋势用 line，构成用 pie/doughnut，两个连续变量关系用 scatter。当前支持的精确类型只有：column、bar、columnStacked、barStacked、line、lineStacked、area、areaStacked、areaPercentStacked、pie、doughnut、scatter、radar。
|
||
|
||
当前不支持 combo/组合图或双轴组合图。用户要求此类图表时不得发送 `type:"combo"`，也不能谎称已经创建；应说明限制，并在用户接受时改为两个受支持的独立图表。用户已指定其他受支持类型时不擅自替换。
|
||
|
||
## 创建前
|
||
|
||
1. csv-get 读取数据范围，确认表头、类别列和系列列。
|
||
2. info 查看已用行列与结构。
|
||
3. 选择不遮挡数据的 position；宽高为正数。
|
||
4. 每个 series/category 的 A1 引用必须位于同一工作表上下文，范围长度匹配。
|
||
|
||
## 创建与查询
|
||
|
||
dws sheet chart create --node <NODE_ID> --sheet-id <SHEET_ID> --properties '{
|
||
"position":{"row":12,"col":"A"},
|
||
"dimensions":{"width":600,"height":400},
|
||
"chart":{
|
||
"type":"column",
|
||
"series":[{"name":"B1","value":["B2:B10"]}],
|
||
"category":["A2:A10"],
|
||
"title":{"show":true,"text":"销售数据"}
|
||
}
|
||
}' --format json
|
||
|
||
properties 顶层必须同时包含 position、dimensions、chart，可选 offset。硬约束：
|
||
|
||
- position.row 和 position.col 都必填；row 是 0-based 锚点行，col 必须是列字母（如 A、AA），不支持数字列号。
|
||
- dimensions.width/height 都必填且为正数。
|
||
- chart.type 必须取上面的支持枚举。
|
||
- chart.series 必须是非空数组；每项都必须有非空的 value 范围数组。series.name 可引用表头格，category 是类别范围数组。
|
||
- series/name/category 使用 A1 表示法；不带工作表前缀时使用 `--sheet-id` 对应工作表。引用跨表数据时显式带工作表前缀，不从当前名称猜测。
|
||
|
||
复杂轴、图例、颜色等字段只在用户需要时加入，不确定时读取 chart create 的 compact Schema；不得从其他表格产品照搬字段。当前常用配置面：
|
||
|
||
| 对象 | 已知字段与枚举 |
|
||
|---|---|
|
||
| `title` | `show:boolean`、`text:string` |
|
||
| `legend` | `show:boolean`；`pos` 仅为 `t` / `b` / `l` / `r` / `none` |
|
||
| `catAx` / `valAx` | `show:boolean`、`pos:l/t/b/r`、`titleConfig:{show,title}`、`axisMin` / `axisMax` 为 `number` / `null`、`splitLine:boolean`、`minorSplitLine:boolean`、`axisLabel:boolean`、`axisLine:boolean` |
|
||
|
||
未列出的字段或枚举以精确 leaf Schema 为准，不猜测；更新时仍须先读完整对象再整体回写。
|
||
|
||
创建后保存返回 chartId，并验证：
|
||
|
||
dws sheet chart list --node <NODE_ID> --sheet-id <SHEET_ID> --chart-id <CHART_ID> --format json
|
||
|
||
检查类型、数据范围、标题、位置和尺寸。列表成功但找不到刚创建 ID，不能称为完成。
|
||
|
||
## 更新是 PUT
|
||
|
||
chart update 的 properties 为整体覆盖，不是 patch。必须先 list 单个 chart，保留完整 position/dimensions/chart，在本地只改目标字段后整体回写：
|
||
|
||
dws sheet chart update --node <NODE_ID> --sheet-id <SHEET_ID> --chart-id <CHART_ID> --properties '<完整_PROPERTIES_JSON>' --format json
|
||
|
||
只提交局部配置会把未传字段恢复默认或删除。更新后再次 list 单个对象并比较关键字段。
|
||
|
||
## 删除
|
||
|
||
删除不可恢复。先 list 获取名称、chartId、数据范围和位置，展示摘要并获得明确同意，然后：
|
||
|
||
dws sheet chart delete --node <NODE_ID> --sheet-id <SHEET_ID> --chart-id <CHART_ID> --yes --format json
|
||
|
||
最后 list 验证对象消失。非零、坏 JSON、缺失对象或错误 ID 不得当作成功。
|