EP-Hub-Skill/.agents/skills/dingtalk-misc/references/sheet/sheet-chart.md

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 不得当作成功。