{ "schema_version": "3", "flags": { "+batch-update": { "operations": { "type": "array", "description": "要批量执行的 CLI shortcut 操作列表，按声明顺序串行执行；任一失败立即中断。", "items": { "type": "object", "required": [ "shortcut", "input" ], "properties": { "shortcut": { "type": "string", "enum": [ "+cells-set", "+cells-set-style", "+cells-clear", "+cells-merge", "+cells-unmerge", "+cells-replace", "+csv-put", "+dropdown-set", "+dim-insert", "+dim-delete", "+dim-hide", "+dim-unhide", "+dim-freeze", "+dim-group", "+dim-ungroup", "+rows-resize", "+cols-resize", "+range-move", "+range-copy", "+range-fill", "+range-sort", "+sheet-create", "+sheet-delete", "+sheet-rename", "+sheet-move", "+sheet-copy", "+sheet-hide", "+sheet-unhide", "+sheet-set-tab-color", "+sheet-show-gridline", "+sheet-hide-gridline", "+chart-create", "+chart-update", "+chart-delete", "+pivot-create", "+pivot-update", "+pivot-delete", "+cond-format-create", "+cond-format-update", "+cond-format-delete", "+filter-create", "+filter-update", "+filter-delete", "+filter-view-create", "+filter-view-update", "+filter-view-delete", "+sparkline-create", "+sparkline-update", "+sparkline-delete", "+float-image-create", "+float-image-update", "+float-image-delete" ], "description": "CLI shortcut 名（不是底层 MCP tool 名）。+dim-move 不在表中——它走 legacy v2 endpoint，无法批；+cells-set-image / +workbook-create 也不在——前者含多步图片上传，后者是新建工作簿，都不属于 atomic batch 范畴；所有读操作、fan-out wrapper（+batch-update 自身 / +cells-batch-set-style / +cells-batch-clear / +dropdown-{update,delete}）一律禁。" }, "input": { "type": "object", "description": "该 shortcut 的入参集——含子表定位 sheet_id（或 sheet_name），但不含 spreadsheet token/url（后者只在顶层 --url/--spreadsheet-token 给一次；+batch-update 顶层没有 --sheet-id）；input 的键是该 shortcut 的 flag 展平成 JSON、不是再套一层嵌套。基础 flag 跑 `lark-cli sheets --help`，复合 JSON flag 跑 `--print-schema --flag-name `。不要手填 `operation`（动作由 shortcut 名表达）。" } } } } }, "+cells-batch-set-style": { "border-styles": { "type": "object", "description": "单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top）。", "properties": { "top": { "type": "object", "properties": { "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" ] }, "weight": { "description": "边框粗细/线宽", "type": "string", "enum": [ "thin", "medium", "thick" ] }, "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } } }, "bottom": { "type": "object", "properties": { "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" ] }, "weight": { "description": "边框粗细/线宽", "type": "string", "enum": [ "thin", "medium", "thick" ] }, "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } } }, "left": { "type": "object", "properties": { "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" ] }, "weight": { "description": "边框粗细/线宽", "type": "string", "enum": [ "thin", "medium", "thick" ] }, "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } } }, "right": { "type": "object", "properties": { "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" ] }, "weight": { "description": "边框粗细/线宽", "type": "string", "enum": [ "thin", "medium", "thick" ] }, "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } } } } } }, "+cells-set": { "cells": { "description": "【维度】行列数必须与 range 完全一致：'A1:C2'→[[_,_,_],[_,_,_]]（2行×3列），'B5:B7'→[[_],[_],[_]]（3行×1列），'A1'→[[_]]（1×1）。不修改的单元格填 {}。【内容字段，只能选一个】value（普通值）/ formula（公式，以 = 开头）/ rich_text（富文本）/ multiple_values（多值）。【可叠加字段，可与内容字段自由组合】cell_styles、border_styles、note、data_validation。【增量】所有字段均为增量更新，未传字段保留原值不变。", "type": "array", "items": { "type": "array", "items": { "type": "object", "properties": { "value": { "description": "静态单元格值（文本、数字、布尔）。公式请优先使用 'formula' 字段；如果误把以 '=' 开头的公式字符串写到这里，工具会按 Excel 语义自动识别为公式入库，但仍应按 'formula' 字段的契约传参。", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "formula": { "description": "以 '=' 开头的单元格公式（例如：'=SUM(A1:A10)'）。公式必须写在此字段，而不是 'value'。", "type": "string" }, "note": { "description": "单元格批注/备注。设为 null 可清除已有的批注。", "type": "string", "nullable": true }, "cell_styles": { "type": "object", "properties": { "font_color": { "description": "字体颜色（十六进制，例如 \"#000000\"）", "type": "string" }, "font_size": { "description": "字体大小（单位：px/像素，例如 10、12、14）", "type": "number" }, "font_weight": { "description": "字重", "type": "string", "enum": [ "normal", "bold" ] }, "font_style": { "description": "字体样式", "type": "string", "enum": [ "normal", "italic" ] }, "font_line": { "description": "字体线条样式", "type": "string", "enum": [ "none", "underline", "line-through" ] }, "background_color": { "description": "背景颜色（十六进制，例如 \"#ffffff\"）", "type": "string" }, "horizontal_alignment": { "description": "水平对齐方式", "type": "string", "enum": [ "left", "center", "right" ] }, "vertical_alignment": { "description": "垂直对齐方式", "type": "string", "enum": [ "top", "middle", "bottom" ] }, "number_format": { "description": "数字格式（例如：文本用 \"@\"、数字用 \"0.00\"、货币用 \"$#,##0.00\"、日期用 \"mm/dd/yyyy\"）", "type": "string" }, "word_wrap": { "description": "是否自动换行，默认溢出，可选自动换行或裁剪。", "type": "string", "enum": [ "overflow", "auto-wrap", "word-clip" ] } }, "description": "单元格样式属性，包括字体、颜色、对齐方式和数字格式" }, "border_styles": { "type": "object", "description": "单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top）。", "properties": { "top": { "type": "object", "properties": { "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" ] }, "weight": { "description": "边框粗细/线宽", "type": "string", "enum": [ "thin", "medium", "thick" ] }, "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } } }, "bottom": { "type": "object", "properties": { "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" ] }, "weight": { "description": "边框粗细/线宽", "type": "string", "enum": [ "thin", "medium", "thick" ] }, "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } } }, "left": { "type": "object", "properties": { "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" ] }, "weight": { "description": "边框粗细/线宽", "type": "string", "enum": [ "thin", "medium", "thick" ] }, "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } } }, "right": { "type": "object", "properties": { "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" ] }, "weight": { "description": "边框粗细/线宽", "type": "string", "enum": [ "thin", "medium", "thick" ] }, "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } } } } }, "rich_text": { "description": "富文本内容。设置后会忽略 value 字段。可包含带样式的文本段 text、超链接 link、@提及 mention、单元格图片 embed-image、附件 attachment。", "type": "array", "items": { "type": "object", "properties": { "type": { "description": "段类型", "type": "string", "enum": [ "text", "link", "mention", "embed-image", "attachment" ] }, "text": { "description": "显示文本", "type": "string" }, "style": { "description": "文本段样式（仅 type='text' 时生效），结构同 cell_styles", "type": "object" }, "link": { "description": "超链接地址（type='link' 时必填）；@文档 mention（mention_type 非 0）时也必填，传文档 URL（如搜索结果里的文档链接），否则卡片不可点。@人（mention_type=0）不需要传", "type": "string" }, "mention_token": { "description": "@提及目标的 token，如 userId 或 fileId（仅 type='mention' 时必填）", "type": "string" }, "mention_type": { "description": "@提及类型编号（仅 type='mention' 时可选）。0 或不填=@用户；@文件时按类型取：1=文档 3=电子表格 8=多维表格 11=思维笔记 12=文件 15=旧版幻灯片 16=知识库 22=新版文档 30=幻灯片 38=画板", "type": "number", "enum": [ 0, 1, 3, 8, 11, 12, 15, 16, 22, 30, 38 ] }, "notify": { "description": "是否发送通知（仅 type='mention' 时可选，默认 true）", "type": "boolean" }, "image_width": { "description": "图片宽度（像素，仅 type='embed-image' 时使用）", "type": "number" }, "image_height": { "description": "图片高度（像素，仅 type='embed-image' 时使用）", "type": "number" }, "image_name": { "description": "图片名称（仅 type='embed-image' 时使用，创建新图片时必填）", "type": "string" }, "image_uri": { "description": "图片文件 reference_id（仅 type='embed-image' 时使用，与 image_token 二选一，如`<|image|>:abcdef` 或者 `<|superscript|>:abcdef-<|image|>:abcdef`，其中 `abcdef` 为实际的对象 ID，占位符仅用于示意）", "type": "string" }, "image_token": { "description": "图片文件 token（仅 type='embed-image' 时可选，修改已有图片时可从 get_cell_range 获取）", "type": "string" }, "attachment_token": { "description": "附件文件 token，通过飞书 Drive 上传获取（仅 type='attachment' 时可选，修改已有附件时可从 get_cell_range 获取）", "type": "string" }, "attachment_uri": { "description": "附件文件 reference_id（仅 type='attachment' 时使用，与 attachment_token 二选一，如`<|attachment|>:abcdef` 或者 `<|superscript|>:abcdef-<|attachment|>:abcdef`，其中 `abcdef` 为实际的对象 ID，占位符仅用于示意）", "type": "string" }, "attachment_name": { "description": "附件文件名称（仅 type='attachment' 时使用，配合 attachment_reference_id 使用，创建新附件时必填）", "type": "string" }, "mime_type": { "description": "附件 MIME 类型（仅 type='attachment' 时使用，例如 'application/pdf'）", "type": "string" }, "file_size": { "description": "附件文件大小（字节，仅 type='attachment' 时使用）", "type": "number" } }, "required": [ "type", "text" ] } }, "multiple_values": { "description": "多值内容，用于支持多选的列表验证单元格。设置后会忽略 value 和 rich_text 字段。", "type": "array", "items": { "type": "object", "properties": { "value": { "description": "值（文本、数字、布尔）", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "format": { "description": "可选的数字格式（例如 '$#,##0.00'）", "type": "string" } }, "required": [ "value" ] } }, "data_validation": { "description": "数据验证配置。设为 null 可清除已有的数据验证。", "type": "object", "nullable": true, "properties": { "type": { "description": "数据验证类型：list（下拉列表）、listFromRange（引用范围下拉列表）、number（数字）、date（日期）、textLength（文本长度）、checkbox（复选框）", "type": "string", "enum": [ "list", "listFromRange", "number", "date", "textLength", "checkbox" ] }, "items": { "description": "列表选项", "type": "array", "items": { "type": "string" } }, "range": { "description": "源数据区域（type='listFromRange' 时必填，格式：'SheetName!A1:A10'）", "type": "string" }, "operator": { "description": "比较运算符（type='number'/'date'/'textLength' 时必填）", "type": "string", "enum": [ "equal", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "between", "notBetween" ] }, "values": { "description": "比较值（operator 为 'between'/'notBetween' 时需要两个值，其它运算符需要一个值）", "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } }, "support_multiple_values": { "description": "列表验证是否支持多选（type='list'/'listFromRange' 时可选，默认 false）", "type": "boolean" }, "help_text": { "description": "验证失败时显示的提示文本", "type": "string" }, "enable_highlight": { "description": "是否开启下拉选项的胶囊背景色高亮，仅 type='list'/'listFromRange' 生效。默认 true，自动按内置 10 色色板循环上色。仅当用户明确要求纯色下拉时才传 false。当用户要求按下拉项分别染色时，用本字段 + highlight_colors 一步搞定即可，不要走条件格式（条件格式是染整格背景，语义不符）。", "type": "boolean" }, "highlight_colors": { "description": "下拉选项的胶囊背景色数组（十六进制，例如 [\"#FFE699\",\"#bff7d9\",\"#ffb3b3\"]）。按顺序对应（type='list' 对应 items；type='listFromRange' 按 range 内单元格行优先顺序，如 A1:A10 对应第 1-10 项；A1:B2 顺序为 A1,B1,A2,B2）。长度可以短于但不能长于；未指定项及不提供该字段时按内置 10 色色板循环补色。当 enable_highlight=false 时本字段被忽略。", "type": "array", "items": { "type": "string" } } }, "required": [ "type" ] } } } } } }, "+cells-set-style": { "border-styles": { "type": "object", "description": "单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top）。", "properties": { "top": { "type": "object", "properties": { "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" ] }, "weight": { "description": "边框粗细/线宽", "type": "string", "enum": [ "thin", "medium", "thick" ] }, "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } } }, "bottom": { "type": "object", "properties": { "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" ] }, "weight": { "description": "边框粗细/线宽", "type": "string", "enum": [ "thin", "medium", "thick" ] }, "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } } }, "left": { "type": "object", "properties": { "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" ] }, "weight": { "description": "边框粗细/线宽", "type": "string", "enum": [ "thin", "medium", "thick" ] }, "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } } }, "right": { "type": "object", "properties": { "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" ] }, "weight": { "description": "边框粗细/线宽", "type": "string", "enum": [ "thin", "medium", "thick" ] }, "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } } } } } }, "+chart-create": { "properties": { "description": "创建/更新的图表属性。", "type": "object", "properties": { "position": { "type": "object", "description": "必填。图表在表格中的单元格位置。注意：选择位置时应避免覆盖已有数据的单元格，并确保图表不超出当前表格的行列范围。", "properties": { "row": { "type": "number", "minimum": 0, "description": "行索引（0-based）" }, "col": { "type": "string", "description": "列索引，例如 \"A\"、\"B\"" } }, "required": [ "row", "col" ] }, "offset": { "type": "object", "description": "可选。图表在位置基础上的偏移量（像素）。", "properties": { "row_offset": { "type": "number", "description": "行偏移量（像素）" }, "col_offset": { "type": "number", "description": "列偏移量（像素）" } } }, "size": { "type": "object", "description": "必填。图表大小（像素）。注意：设定大小时应确保图表不超出当前表格的行列范围，并避免覆盖已有数据的单元格。", "properties": { "width": { "type": "number", "minimum": 10, "description": "宽度（像素）" }, "height": { "type": "number", "minimum": 10, "description": "高度（像素）" } }, "required": [ "width", "height" ] }, "snapshot": { "type": "object", "description": "图表快照配置。更新图表时必须传入完整的图表属性定义，不能只传修改的部分。应先通过 get_chart_objects 获取当前图表快照，修改需要变更的字段后，将完整快照传入。", "properties": { "title": { "type": "object", "description": "图表标题配置", "properties": { "text": { "type": "string", "description": "标题文本" }, "textAlign": { "type": "string", "description": "标题对齐方式", "enum": [ "left", "center", "right" ] }, "fontSize": { "type": "number", "description": "字体大小" }, "bold": { "type": "boolean", "description": "是否加粗" }, "italic": { "type": "boolean", "description": "是否斜体" }, "underline": { "type": "boolean", "description": "是否下划线" }, "strikethrough": { "type": "boolean", "description": "是否删除线" }, "color": { "type": "string", "description": "字体颜色，格式为 #RRGGBB" } }, "required": [ "text" ] }, "subTitle": { "type": "object", "description": "图表副标题配置", "properties": { "text": { "type": "string", "description": "副标题文本" }, "textAlign": { "type": "string", "description": "副标题对齐方式", "enum": [ "left", "center", "right" ] }, "fontSize": { "type": "number", "description": "字体大小" }, "bold": { "type": "boolean", "description": "是否加粗" }, "italic": { "type": "boolean", "description": "是否斜体" }, "underline": { "type": "boolean", "description": "是否下划线" }, "strikethrough": { "type": "boolean", "description": "是否删除线" }, "color": { "type": "string", "description": "字体颜色，格式为 #RRGGBB" } }, "required": [ "text" ] }, "style": { "type": "object", "description": "图表样式配置", "properties": { "background": { "type": "object", "description": "背景配置", "properties": { "color": { "type": "string", "description": "背景颜色，格式为 #RRGGBB" } } }, "font": { "type": "object", "description": "字体配置", "properties": { "size": { "type": "number", "description": "字体大小" }, "color": { "type": "string", "description": "字体颜色，格式为 #RRGGBB" } } }, "border": { "type": "object", "description": "边框配置", "properties": { "color": { "type": "string", "description": "边框颜色，格式为 #RRGGBB" }, "width": { "type": "number", "description": "边框宽度" }, "style": { "type": "string", "description": "边框样式", "enum": [ "solid", "dashed", "dotted" ] }, "radius": { "type": "number", "description": "边框圆角" } } }, "colorTheme": { "type": "array", "description": "颜色主题配置。支持两种模式：1. 仅传一个预设主题名称（字符串数组，长度为1）；2. 传多个自定义十六进制颜色字符串。预设主题：brandColorSeries@v2、rainbowColorSeries@v2、complementaryColorSeries@v2、converseColorSeries@v2、primaryColorSeries@v2、singleColorSeries-B-@v2、singleColorSeries-W-@v2、singleColorSeries-G-@v2、singleColorSeries-Y-@v2、singleColorSeries-O-@v2、singleColorSeries-R-@v2、singleColorSeries-D-@v2。十六进制格式：#RRGGBB", "oneOf": [ { "minItems": 1, "maxItems": 1, "items": { "type": "string", "enum": [ "brandColorSeries@v2", "rainbowColorSeries@v2", "complementaryColorSeries@v2", "converseColorSeries@v2", "primaryColorSeries@v2", "singleColorSeries-B-@v2", "singleColorSeries-W-@v2", "singleColorSeries-G-@v2", "singleColorSeries-Y-@v2", "singleColorSeries-O-@v2", "singleColorSeries-R-@v2", "singleColorSeries-D-@v2" ] } }, { "minItems": 2, "items": { "type": "string", "description": "颜色字符串，十六进制格式：#RRGGBB" } } ] }, "colorGradient": { "type": "boolean", "description": "是否启用颜色渐变" } } }, "legend": { "oneOf": [ { "type": "object", "description": "图例配置", "properties": { "position": { "type": "string", "description": "图例位置", "enum": [ "top", "bottom", "left", "right" ] }, "fontSize": { "type": "number", "description": "字体大小" }, "bold": { "type": "boolean", "description": "是否加粗" }, "italic": { "type": "boolean", "description": "是否斜体" }, "underline": { "type": "boolean", "description": "是否下划线" }, "strikethrough": { "type": "boolean", "description": "是否删除线" }, "color": { "type": "string", "description": "字体颜色，格式为 #RRGGBB" } } }, { "type": "boolean", "description": "false 表示隐藏图例" } ] }, "plotArea": { "type": "object", "description": "绘图区域配置", "properties": { "plot": { "type": "object", "description": "绘图配置", "properties": { "type": { "type": "string", "description": "图表类型", "enum": [ "bar", "column", "line", "area", "combo", "pie", "radar", "scatter" ] }, "comboType": { "type": "string", "description": "组合图表默认类型", "enum": [ "column", "line", "area" ] }, "yAxisPosition": { "type": "string", "description": "Y轴位置", "enum": [ "left", "right" ] }, "extra": { "type": "object", "description": "额外配置", "properties": { "smooth": { "type": "boolean", "description": "是否平滑曲线" }, "step": { "type": "boolean", "description": "是否阶梯图" }, "stack": { "type": "object", "description": "堆叠配置", "properties": { "percentage": { "type": "boolean", "description": "是否百分比堆叠" } } }, "radar": { "type": "object", "description": "雷达图配置", "properties": { "shape": { "type": "string", "description": "雷达图形状", "enum": [ "polygon", "circle" ] }, "area": { "type": "boolean", "description": "是否填充区域" } } } } }, "points": { "type": "object", "description": "全系列数据点配置，折线图、面积图、雷达图、散点图、组合图生效。", "properties": { "color": { "type": "string", "description": "数据点颜色" }, "shape": { "type": "string", "description": "数据点形状", "enum": [ "circle", "triangle", "rect", "diamond", "square" ] }, "size": { "type": "number", "description": "数据点大小" }, "point": { "type": "array", "description": "单个数据点配置数组", "items": { "type": "object", "properties": { "index": { "type": "number", "description": "数据点索引" }, "color": { "type": "string", "description": "颜色" }, "shape": { "type": "string", "description": "形状" }, "size": { "type": "number", "description": "大小" } }, "required": [ "index" ] } } } }, "lines": { "type": "object", "description": "全系列线条配置，折线图、面积图、雷达图、组合图生效。", "properties": { "color": { "type": "string", "description": "线条颜色" }, "width": { "type": "number", "description": "线条宽度" }, "style": { "type": "string", "description": "线条样式", "enum": [ "solid", "dashed", "dotted" ] }, "invalidType": { "type": "string", "description": "无效值处理方式", "enum": [ "break", "zero", "link" ] } } }, "areas": { "type": "object", "description": "全系列面积填充配置，面积图、雷达图、组合图生效。", "properties": { "color": { "type": "string", "description": "区域填充颜色" } } }, "bars": { "type": "object", "description": "全系列柱状图、条形图、组合图生效。", "properties": { "color": { "type": "string", "description": "柱子颜色" }, "borderColor": { "type": "string", "description": "边框颜色" }, "borderWidth": { "type": "number", "description": "边框宽度" }, "borderStyle": { "type": "string", "description": "边框样式", "enum": [ "solid", "dashed", "dotted" ] }, "width": { "type": "number", "description": "柱子宽度" }, "gap": { "type": "number", "description": "柱子间距比例，0-1之间" }, "backgroundColor": { "type": "string", "description": "背景颜色" }, "bar": { "type": "array", "description": "单个柱子配置数组", "items": { "type": "object", "properties": { "index": { "type": "number", "description": "柱子索引" }, "color": { "type": "string", "description": "颜色" }, "borderColor": { "type": "string", "description": "边框颜色" }, "borderWidth": { "type": "number", "description": "边框宽度" }, "borderStyle": { "type": "string", "description": "边框样式" } }, "required": [ "index" ] } } } }, "labels": { "type": "object", "description": "数据标签配置", "properties": { "position": { "type": "string", "description": "标签位置", "enum": [ "auto", "top", "bottom", "left", "right", "center", "inside", "outside" ] }, "series": { "type": "boolean", "description": "是否显示系列名" }, "category": { "type": "boolean", "description": "是否显示类别名" }, "value": { "type": "boolean", "description": "是否显示值" }, "percentage": { "type": "boolean", "description": "是否显示百分比" }, "fontSize": { "type": "number", "description": "字体大小" }, "bold": { "type": "boolean", "description": "是否加粗" }, "italic": { "type": "boolean", "description": "是否斜体" }, "underline": { "type": "boolean", "description": "是否下划线" }, "strikethrough": { "type": "boolean", "description": "是否删除线" }, "color": { "type": "string", "description": "字体颜色" } } }, "series": { "type": "array", "description": "单个系列配置数组", "items": { "type": "object", "description": "系列配置", "properties": { "index": { "type": "number", "description": "数据列索引，与 dim2.series[].index 值一致，从 1 开始（1 通常对应首列标签维度，2+ 对应后续数据维度列）" }, "comboType": { "type": "string", "description": "组合图下该系列的图表类型，仅在 type 为 combo 时生效", "enum": [ "column", "line", "area" ] }, "yAxisPosition": { "type": "string", "description": "Y轴位置", "enum": [ "left", "right" ] }, "points": { "type": "object", "description": "数据点配置，配置项同 plotArea.points" }, "line": { "type": "object", "description": "线条配置，配置项同 plotArea.lines" }, "area": { "type": "object", "description": "区域填充配置，配置项同 plotArea.areas" }, "bars": { "type": "object", "description": "柱状图配置，配置项同 plotArea.bars" }, "labels": { "type": "object", "description": "数据标签配置" }, "sectors": { "type": "object", "description": "扇区配置（饼图）", "properties": { "borderColor": { "type": "string", "description": "边框颜色" }, "innerRadius": { "type": "number", "description": "内半径比例，0-1之间" }, "offsetRadius": { "type": "number", "description": "偏移半径比例" }, "startAngle": { "type": "number", "description": "起始角度，0-359" }, "sector": { "type": "array", "description": "单个扇区配置数组", "items": { "type": "object", "properties": { "index": { "type": "number", "description": "扇区索引" }, "borderColor": { "type": "string", "description": "边框颜色" }, "offsetRadius": { "type": "number", "description": "偏移半径" }, "color": { "type": "string", "description": "颜色" } }, "required": [ "index" ] } } } } }, "required": [ "index" ] } } }, "required": [ "type" ] }, "axes": { "type": "array", "description": "坐标轴配置数组", "items": { "type": "object", "description": "坐标轴配置", "properties": { "type": { "type": "string", "description": "坐标轴类型", "enum": [ "x", "y", "angle", "radius" ] }, "position": { "type": "string", "description": "坐标轴位置", "enum": [ "left", "right", "bottom" ] }, "max": { "type": "number", "description": "最大值" }, "min": { "type": "number", "description": "最小值" }, "valueType": { "type": "string", "description": "是否将横轴数字视为文本，linear 表示将数字视为数值, ordinal 表示将数字视为文本", "enum": [ "ordinal", "linear" ] }, "title": { "type": "object", "description": "坐标轴标题配置", "properties": { "text": { "type": "string", "description": "标题文本" }, "fontSize": { "type": "number", "description": "字体大小" }, "bold": { "type": "boolean", "description": "是否加粗" }, "italic": { "type": "boolean", "description": "是否斜体" }, "underline": { "type": "boolean", "description": "是否下划线" }, "strikethrough": { "type": "boolean", "description": "是否删除线" }, "color": { "type": "string", "description": "字体颜色" } }, "required": [ "text" ] }, "label": { "type": "object", "description": "坐标轴标签配置", "properties": { "angle": { "type": "number", "description": "旋转角度，可选值：-90, -45, 0, 45, 90" }, "fontSize": { "type": "number", "description": "字体大小" }, "bold": { "type": "boolean", "description": "是否加粗" }, "italic": { "type": "boolean", "description": "是否斜体" }, "underline": { "type": "boolean", "description": "是否下划线" }, "strikethrough": { "type": "boolean", "description": "是否删除线" }, "color": { "type": "string", "description": "字体颜色" } } }, "axisLine": { "type": "boolean", "description": "是否显示轴线" }, "gridLine": { "oneOf": [ { "type": "object", "description": "网格线配置", "properties": { "width": { "type": "number", "description": "网格线宽度" }, "color": { "type": "string", "description": "网格线颜色" } } }, { "type": "boolean", "description": "false 表示隐藏网格线" } ] } }, "required": [ "type" ] } } }, "required": [ "plot" ] }, "data": { "type": "object", "description": "图表数据配置", "properties": { "isStaticData": { "type": "boolean", "description": "是否为静态数据" }, "includeHiddenOrFilter": { "type": "boolean", "description": "是否包含隐藏或过滤的数据" }, "direction": { "type": "string", "description": "数据方向，可选值：row（行方向）或column（列方向），常用值为column", "enum": [ "row", "column" ] }, "headerMode": { "type": "string", "description": "表头模式。inline 表示 refs 首行/首列就是表头；detached 表示 refs 仅覆盖实际数据范围，维度名和系列名需通过 nameRef 显式指定。", "enum": [ "inline", "detached" ] }, "refs": { "type": "array", "description": "数据源引用范围数组", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "图表数据源范围，格式为 'SheetName!A1:D100' 的连续区域" } }, "required": [ "value" ] } }, "dim1": { "type": "object", "description": "维度1配置（类别维度）", "properties": { "serie": { "type": "object", "description": "系列配置（非静态数据时传此参数）", "properties": { "index": { "type": "number", "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引" }, "aggregate": { "type": "boolean", "description": "是否汇总相同的类别，默认为true，true 情况下 aggregateType 才生效" }, "nameRef": { "type": "string", "description": "可选。维度名称的单元格引用（A1 表示法，如 'Sheet1!A1'）。当维度名称不直接来自 refs 首行/首列时，可通过此字段把维度名显式指向目标表头单元格，图表会以该单元格当前值作为类别维度名展示。" } }, "required": [ "index" ] }, "field": { "type": "object", "description": "字段配置（静态数据时传此参数）", "properties": { "valueType": { "type": "string", "description": "值类型", "enum": [ "number", "string" ] }, "name": { "type": "string", "description": "字段名称" }, "text": { "type": "string", "description": "字段文本数据" } }, "required": [ "text" ] } } }, "dim2": { "type": "object", "description": "维度2配置（值维度）", "properties": { "series": { "type": "array", "description": "系列配置数组（非静态数据时传此参数）", "items": { "type": "object", "properties": { "index": { "type": "number", "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引" }, "aggregateType": { "type": "string", "description": "汇总方式，默认为'sum'，仅在 aggregate 为 true 时生效。count 只统计数值单元格；counta 统计所有非空单元格（含文本），按文本/分类列统计出现次数（如各类别的数量、频次分布）时用 counta。", "enum": [ "sum", "average", "count", "counta", "min", "max", "median" ] }, "nameRef": { "type": "string", "description": "可选。系列名称的单元格引用（A1 表示法，如 'Sheet1!C1'）。当系列名称不直接来自 refs 首行/首列时，可通过此字段把系列名显式指向目标表头单元格，图表会以该单元格当前值作为系列名（图例/tooltip）展示。" } }, "required": [ "index" ] } }, "fields": { "type": "array", "description": "字段配置数组（静态数据时传此参数）", "items": { "type": "object", "properties": { "valueType": { "type": "string", "description": "值类型", "enum": [ "number" ] }, "name": { "type": "string", "description": "字段名称" }, "text": { "type": "string", "description": "字段文本数据" } }, "required": [ "text" ] } } } } } } }, "required": [ "plotArea", "data" ] } } } }, "+chart-update": { "properties": { "description": "创建/更新的图表属性。", "type": "object", "properties": { "position": { "type": "object", "description": "必填。图表在表格中的单元格位置。注意：选择位置时应避免覆盖已有数据的单元格，并确保图表不超出当前表格的行列范围。", "properties": { "row": { "type": "number", "minimum": 0, "description": "行索引（0-based）" }, "col": { "type": "string", "description": "列索引，例如 \"A\"、\"B\"" } }, "required": [ "row", "col" ] }, "offset": { "type": "object", "description": "可选。图表在位置基础上的偏移量（像素）。", "properties": { "row_offset": { "type": "number", "description": "行偏移量（像素）" }, "col_offset": { "type": "number", "description": "列偏移量（像素）" } } }, "size": { "type": "object", "description": "必填。图表大小（像素）。注意：设定大小时应确保图表不超出当前表格的行列范围，并避免覆盖已有数据的单元格。", "properties": { "width": { "type": "number", "minimum": 10, "description": "宽度（像素）" }, "height": { "type": "number", "minimum": 10, "description": "高度（像素）" } }, "required": [ "width", "height" ] }, "snapshot": { "type": "object", "description": "图表快照配置。更新图表时必须传入完整的图表属性定义，不能只传修改的部分。应先通过 get_chart_objects 获取当前图表快照，修改需要变更的字段后，将完整快照传入。", "properties": { "title": { "type": "object", "description": "图表标题配置", "properties": { "text": { "type": "string", "description": "标题文本" }, "textAlign": { "type": "string", "description": "标题对齐方式", "enum": [ "left", "center", "right" ] }, "fontSize": { "type": "number", "description": "字体大小" }, "bold": { "type": "boolean", "description": "是否加粗" }, "italic": { "type": "boolean", "description": "是否斜体" }, "underline": { "type": "boolean", "description": "是否下划线" }, "strikethrough": { "type": "boolean", "description": "是否删除线" }, "color": { "type": "string", "description": "字体颜色，格式为 #RRGGBB" } }, "required": [ "text" ] }, "subTitle": { "type": "object", "description": "图表副标题配置", "properties": { "text": { "type": "string", "description": "副标题文本" }, "textAlign": { "type": "string", "description": "副标题对齐方式", "enum": [ "left", "center", "right" ] }, "fontSize": { "type": "number", "description": "字体大小" }, "bold": { "type": "boolean", "description": "是否加粗" }, "italic": { "type": "boolean", "description": "是否斜体" }, "underline": { "type": "boolean", "description": "是否下划线" }, "strikethrough": { "type": "boolean", "description": "是否删除线" }, "color": { "type": "string", "description": "字体颜色，格式为 #RRGGBB" } }, "required": [ "text" ] }, "style": { "type": "object", "description": "图表样式配置", "properties": { "background": { "type": "object", "description": "背景配置", "properties": { "color": { "type": "string", "description": "背景颜色，格式为 #RRGGBB" } } }, "font": { "type": "object", "description": "字体配置", "properties": { "size": { "type": "number", "description": "字体大小" }, "color": { "type": "string", "description": "字体颜色，格式为 #RRGGBB" } } }, "border": { "type": "object", "description": "边框配置", "properties": { "color": { "type": "string", "description": "边框颜色，格式为 #RRGGBB" }, "width": { "type": "number", "description": "边框宽度" }, "style": { "type": "string", "description": "边框样式", "enum": [ "solid", "dashed", "dotted" ] }, "radius": { "type": "number", "description": "边框圆角" } } }, "colorTheme": { "type": "array", "description": "颜色主题配置。支持两种模式：1. 仅传一个预设主题名称（字符串数组，长度为1）；2. 传多个自定义十六进制颜色字符串。预设主题：brandColorSeries@v2、rainbowColorSeries@v2、complementaryColorSeries@v2、converseColorSeries@v2、primaryColorSeries@v2、singleColorSeries-B-@v2、singleColorSeries-W-@v2、singleColorSeries-G-@v2、singleColorSeries-Y-@v2、singleColorSeries-O-@v2、singleColorSeries-R-@v2、singleColorSeries-D-@v2。十六进制格式：#RRGGBB", "oneOf": [ { "minItems": 1, "maxItems": 1, "items": { "type": "string", "enum": [ "brandColorSeries@v2", "rainbowColorSeries@v2", "complementaryColorSeries@v2", "converseColorSeries@v2", "primaryColorSeries@v2", "singleColorSeries-B-@v2", "singleColorSeries-W-@v2", "singleColorSeries-G-@v2", "singleColorSeries-Y-@v2", "singleColorSeries-O-@v2", "singleColorSeries-R-@v2", "singleColorSeries-D-@v2" ] } }, { "minItems": 2, "items": { "type": "string", "description": "颜色字符串，十六进制格式：#RRGGBB" } } ] }, "colorGradient": { "type": "boolean", "description": "是否启用颜色渐变" } } }, "legend": { "oneOf": [ { "type": "object", "description": "图例配置", "properties": { "position": { "type": "string", "description": "图例位置", "enum": [ "top", "bottom", "left", "right" ] }, "fontSize": { "type": "number", "description": "字体大小" }, "bold": { "type": "boolean", "description": "是否加粗" }, "italic": { "type": "boolean", "description": "是否斜体" }, "underline": { "type": "boolean", "description": "是否下划线" }, "strikethrough": { "type": "boolean", "description": "是否删除线" }, "color": { "type": "string", "description": "字体颜色，格式为 #RRGGBB" } } }, { "type": "boolean", "description": "false 表示隐藏图例" } ] }, "plotArea": { "type": "object", "description": "绘图区域配置", "properties": { "plot": { "type": "object", "description": "绘图配置", "properties": { "type": { "type": "string", "description": "图表类型", "enum": [ "bar", "column", "line", "area", "combo", "pie", "radar", "scatter" ] }, "comboType": { "type": "string", "description": "组合图表默认类型", "enum": [ "column", "line", "area" ] }, "yAxisPosition": { "type": "string", "description": "Y轴位置", "enum": [ "left", "right" ] }, "extra": { "type": "object", "description": "额外配置", "properties": { "smooth": { "type": "boolean", "description": "是否平滑曲线" }, "step": { "type": "boolean", "description": "是否阶梯图" }, "stack": { "type": "object", "description": "堆叠配置", "properties": { "percentage": { "type": "boolean", "description": "是否百分比堆叠" } } }, "radar": { "type": "object", "description": "雷达图配置", "properties": { "shape": { "type": "string", "description": "雷达图形状", "enum": [ "polygon", "circle" ] }, "area": { "type": "boolean", "description": "是否填充区域" } } } } }, "points": { "type": "object", "description": "全系列数据点配置，折线图、面积图、雷达图、散点图、组合图生效。", "properties": { "color": { "type": "string", "description": "数据点颜色" }, "shape": { "type": "string", "description": "数据点形状", "enum": [ "circle", "triangle", "rect", "diamond", "square" ] }, "size": { "type": "number", "description": "数据点大小" }, "point": { "type": "array", "description": "单个数据点配置数组", "items": { "type": "object", "properties": { "index": { "type": "number", "description": "数据点索引" }, "color": { "type": "string", "description": "颜色" }, "shape": { "type": "string", "description": "形状" }, "size": { "type": "number", "description": "大小" } }, "required": [ "index" ] } } } }, "lines": { "type": "object", "description": "全系列线条配置，折线图、面积图、雷达图、组合图生效。", "properties": { "color": { "type": "string", "description": "线条颜色" }, "width": { "type": "number", "description": "线条宽度" }, "style": { "type": "string", "description": "线条样式", "enum": [ "solid", "dashed", "dotted" ] }, "invalidType": { "type": "string", "description": "无效值处理方式", "enum": [ "break", "zero", "link" ] } } }, "areas": { "type": "object", "description": "全系列面积填充配置，面积图、雷达图、组合图生效。", "properties": { "color": { "type": "string", "description": "区域填充颜色" } } }, "bars": { "type": "object", "description": "全系列柱状图、条形图、组合图生效。", "properties": { "color": { "type": "string", "description": "柱子颜色" }, "borderColor": { "type": "string", "description": "边框颜色" }, "borderWidth": { "type": "number", "description": "边框宽度" }, "borderStyle": { "type": "string", "description": "边框样式", "enum": [ "solid", "dashed", "dotted" ] }, "width": { "type": "number", "description": "柱子宽度" }, "gap": { "type": "number", "description": "柱子间距比例，0-1之间" }, "backgroundColor": { "type": "string", "description": "背景颜色" }, "bar": { "type": "array", "description": "单个柱子配置数组", "items": { "type": "object", "properties": { "index": { "type": "number", "description": "柱子索引" }, "color": { "type": "string", "description": "颜色" }, "borderColor": { "type": "string", "description": "边框颜色" }, "borderWidth": { "type": "number", "description": "边框宽度" }, "borderStyle": { "type": "string", "description": "边框样式" } }, "required": [ "index" ] } } } }, "labels": { "type": "object", "description": "数据标签配置", "properties": { "position": { "type": "string", "description": "标签位置", "enum": [ "auto", "top", "bottom", "left", "right", "center", "inside", "outside" ] }, "series": { "type": "boolean", "description": "是否显示系列名" }, "category": { "type": "boolean", "description": "是否显示类别名" }, "value": { "type": "boolean", "description": "是否显示值" }, "percentage": { "type": "boolean", "description": "是否显示百分比" }, "fontSize": { "type": "number", "description": "字体大小" }, "bold": { "type": "boolean", "description": "是否加粗" }, "italic": { "type": "boolean", "description": "是否斜体" }, "underline": { "type": "boolean", "description": "是否下划线" }, "strikethrough": { "type": "boolean", "description": "是否删除线" }, "color": { "type": "string", "description": "字体颜色" } } }, "series": { "type": "array", "description": "单个系列配置数组", "items": { "type": "object", "description": "系列配置", "properties": { "index": { "type": "number", "description": "数据列索引，与 dim2.series[].index 值一致，从 1 开始（1 通常对应首列标签维度，2+ 对应后续数据维度列）" }, "comboType": { "type": "string", "description": "组合图下该系列的图表类型，仅在 type 为 combo 时生效", "enum": [ "column", "line", "area" ] }, "yAxisPosition": { "type": "string", "description": "Y轴位置", "enum": [ "left", "right" ] }, "points": { "type": "object", "description": "数据点配置，配置项同 plotArea.points" }, "line": { "type": "object", "description": "线条配置，配置项同 plotArea.lines" }, "area": { "type": "object", "description": "区域填充配置，配置项同 plotArea.areas" }, "bars": { "type": "object", "description": "柱状图配置，配置项同 plotArea.bars" }, "labels": { "type": "object", "description": "数据标签配置" }, "sectors": { "type": "object", "description": "扇区配置（饼图）", "properties": { "borderColor": { "type": "string", "description": "边框颜色" }, "innerRadius": { "type": "number", "description": "内半径比例，0-1之间" }, "offsetRadius": { "type": "number", "description": "偏移半径比例" }, "startAngle": { "type": "number", "description": "起始角度，0-359" }, "sector": { "type": "array", "description": "单个扇区配置数组", "items": { "type": "object", "properties": { "index": { "type": "number", "description": "扇区索引" }, "borderColor": { "type": "string", "description": "边框颜色" }, "offsetRadius": { "type": "number", "description": "偏移半径" }, "color": { "type": "string", "description": "颜色" } }, "required": [ "index" ] } } } } }, "required": [ "index" ] } } }, "required": [ "type" ] }, "axes": { "type": "array", "description": "坐标轴配置数组", "items": { "type": "object", "description": "坐标轴配置", "properties": { "type": { "type": "string", "description": "坐标轴类型", "enum": [ "x", "y", "angle", "radius" ] }, "position": { "type": "string", "description": "坐标轴位置", "enum": [ "left", "right", "bottom" ] }, "max": { "type": "number", "description": "最大值" }, "min": { "type": "number", "description": "最小值" }, "valueType": { "type": "string", "description": "是否将横轴数字视为文本，linear 表示将数字视为数值, ordinal 表示将数字视为文本", "enum": [ "ordinal", "linear" ] }, "title": { "type": "object", "description": "坐标轴标题配置", "properties": { "text": { "type": "string", "description": "标题文本" }, "fontSize": { "type": "number", "description": "字体大小" }, "bold": { "type": "boolean", "description": "是否加粗" }, "italic": { "type": "boolean", "description": "是否斜体" }, "underline": { "type": "boolean", "description": "是否下划线" }, "strikethrough": { "type": "boolean", "description": "是否删除线" }, "color": { "type": "string", "description": "字体颜色" } }, "required": [ "text" ] }, "label": { "type": "object", "description": "坐标轴标签配置", "properties": { "angle": { "type": "number", "description": "旋转角度，可选值：-90, -45, 0, 45, 90" }, "fontSize": { "type": "number", "description": "字体大小" }, "bold": { "type": "boolean", "description": "是否加粗" }, "italic": { "type": "boolean", "description": "是否斜体" }, "underline": { "type": "boolean", "description": "是否下划线" }, "strikethrough": { "type": "boolean", "description": "是否删除线" }, "color": { "type": "string", "description": "字体颜色" } } }, "axisLine": { "type": "boolean", "description": "是否显示轴线" }, "gridLine": { "oneOf": [ { "type": "object", "description": "网格线配置", "properties": { "width": { "type": "number", "description": "网格线宽度" }, "color": { "type": "string", "description": "网格线颜色" } } }, { "type": "boolean", "description": "false 表示隐藏网格线" } ] } }, "required": [ "type" ] } } }, "required": [ "plot" ] }, "data": { "type": "object", "description": "图表数据配置", "properties": { "isStaticData": { "type": "boolean", "description": "是否为静态数据" }, "includeHiddenOrFilter": { "type": "boolean", "description": "是否包含隐藏或过滤的数据" }, "direction": { "type": "string", "description": "数据方向，可选值：row（行方向）或column（列方向），常用值为column", "enum": [ "row", "column" ] }, "headerMode": { "type": "string", "description": "表头模式。inline 表示 refs 首行/首列就是表头；detached 表示 refs 仅覆盖实际数据范围，维度名和系列名需通过 nameRef 显式指定。", "enum": [ "inline", "detached" ] }, "refs": { "type": "array", "description": "数据源引用范围数组", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "图表数据源范围，格式为 'SheetName!A1:D100' 的连续区域" } }, "required": [ "value" ] } }, "dim1": { "type": "object", "description": "维度1配置（类别维度）", "properties": { "serie": { "type": "object", "description": "系列配置（非静态数据时传此参数）", "properties": { "index": { "type": "number", "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引" }, "aggregate": { "type": "boolean", "description": "是否汇总相同的类别，默认为true，true 情况下 aggregateType 才生效" }, "nameRef": { "type": "string", "description": "可选。维度名称的单元格引用（A1 表示法，如 'Sheet1!A1'）。当维度名称不直接来自 refs 首行/首列时，可通过此字段把维度名显式指向目标表头单元格，图表会以该单元格当前值作为类别维度名展示。" } }, "required": [ "index" ] }, "field": { "type": "object", "description": "字段配置（静态数据时传此参数）", "properties": { "valueType": { "type": "string", "description": "值类型", "enum": [ "number", "string" ] }, "name": { "type": "string", "description": "字段名称" }, "text": { "type": "string", "description": "字段文本数据" } }, "required": [ "text" ] } } }, "dim2": { "type": "object", "description": "维度2配置（值维度）", "properties": { "series": { "type": "array", "description": "系列配置数组（非静态数据时传此参数）", "items": { "type": "object", "properties": { "index": { "type": "number", "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引" }, "aggregateType": { "type": "string", "description": "汇总方式，默认为'sum'，仅在 aggregate 为 true 时生效。count 只统计数值单元格；counta 统计所有非空单元格（含文本），按文本/分类列统计出现次数（如各类别的数量、频次分布）时用 counta。", "enum": [ "sum", "average", "count", "counta", "min", "max", "median" ] }, "nameRef": { "type": "string", "description": "可选。系列名称的单元格引用（A1 表示法，如 'Sheet1!C1'）。当系列名称不直接来自 refs 首行/首列时，可通过此字段把系列名显式指向目标表头单元格，图表会以该单元格当前值作为系列名（图例/tooltip）展示。" } }, "required": [ "index" ] } }, "fields": { "type": "array", "description": "字段配置数组（静态数据时传此参数）", "items": { "type": "object", "properties": { "valueType": { "type": "string", "description": "值类型", "enum": [ "number" ] }, "name": { "type": "string", "description": "字段名称" }, "text": { "type": "string", "description": "字段文本数据" } }, "required": [ "text" ] } } } } } } }, "required": [ "plotArea", "data" ] } } } }, "+cond-format-create": { "properties": { "description": "创建/更新的条件格式属性。", "type": "object", "properties": { "rule_type": { "type": "string", "enum": [ "duplicateValues", "uniqueValues", "cellIs", "containsText", "timePeriod", "containsBlanks", "notContainsBlanks", "dataBar", "colorScale", "rank", "aboveAverage", "expression", "iconSet" ], "description": "条件格式规则类型。" }, "ranges": { "type": "array", "description": "应用条件格式的 A1 范围列表。每个元素支持：矩形范围 \"A1:A10\"、整行 \"3:6\"、整列 \"C:C\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。例如 [\"A1:A10\",\"C:C\"]。", "items": { "type": "string" } }, "style": { "type": "object", "description": "命中规则时应用的单元格样式。", "properties": { "back_color": { "type": "string", "description": "背景色，CSS 十六进制表示，例如 \"#FF0000\"。" }, "fore_color": { "type": "string", "description": "前景色/字体颜色。" }, "text_decoration": { "type": "string", "enum": [ "none", "underline", "strikethrough", "underline_strikethrough" ], "description": "文字装饰：none=无，underline=下划线，strikethrough=删除线，underline_strikethrough=下划线+删除线。" }, "font": { "type": "string", "enum": [ "bold", "italic", "bold italic" ], "description": "字体样式：\"bold\"=加粗，\"italic\"=斜体，\"bold italic\"=加粗+斜体。" } } }, "attrs": { "type": "array", "description": "规则参数列表。不同 rule_type 下取值结构不同。当 rule_type 为 dataBar 时，attrs 必须包含两个对象，分别定义正值和负值的数据条颜色。", "items": { "oneOf": [ { "type": "object", "description": "数值比较类规则参数。", "properties": { "compare_type": { "type": "string", "enum": [ "equal", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "between", "notBetween" ], "description": "比较运算符。" }, "value": { "type": "string", "description": "用于比较的值，例如 \"100\"、\"hello\"。between/notBetween 时用逗号分隔两个值。" } }, "required": [ "compare_type", "value" ] }, { "type": "object", "description": "文本包含类规则参数。", "properties": { "text": { "type": "string", "description": "用于匹配的文本内容。" }, "compare_type": { "type": "string", "enum": [ "beginsWith", "endsWith", "containsText", "notContains", "is" ], "description": "文本匹配方式。" } }, "required": [ "compare_type", "text" ] }, { "type": "object", "description": "时间段类规则参数。", "properties": { "operator": { "type": "string", "enum": [ "before", "is", "after" ], "description": "与指定时间段的比较关系。" }, "time_period": { "type": "string", "enum": [ "today", "yesterday", "tomorrow", "last7Days", "thisMonth", "lastMonth", "nextMonth", "thisWeek", "lastWeek", "nextWeek" ], "description": "时间段类型。" } }, "required": [ "operator", "time_period" ] }, { "type": "object", "description": "数据条规则参数。", "properties": { "gradient": { "type": "boolean", "description": "是否使用渐变色数据条。" }, "value": { "type": "number", "description": "阈值或比例值，含义由 value_type 决定。" }, "color": { "type": "string", "description": "主颜色，例如 \"#63BE7B\"。" }, "hide_value": { "type": "boolean", "description": "是否隐藏单元格中的原始值，仅显示数据条。" }, "value_type": { "type": "string", "enum": [ "minValue", "maxValue", "num", "percentile", "percent", "formula", "auto" ], "description": "阈值类型。" } }, "required": [ "color", "value_type" ] }, { "type": "object", "description": "色阶规则中的单个分段。ColorScaleAttrs 由 2 或 3 个该对象组成，分别表示最小值/中间值/最大值。", "properties": { "value_type": { "type": "string", "enum": [ "minValue", "maxValue", "num", "percentile", "percent", "formula", "auto" ], "description": "阈值类型。" }, "value": { "type": "number", "description": "阈值数值，例如百分位或具体数值。" }, "color": { "type": "string", "description": "该分段对应的颜色。" } }, "required": [ "value_type", "color" ] }, { "type": "object", "description": "前 N/后 N 规则参数。", "properties": { "is_bottom": { "type": "boolean", "description": "是否选取最后 N 个。true 表示最后 N 个，false 表示前 N 个。" }, "value_type": { "type": "string", "enum": [ "percent", "sort" ], "description": "排名方式：percent 表示百分比，sort 表示按条目数。" }, "value": { "type": "number", "description": "N 或百分比数值。" } }, "required": [ "is_bottom", "value_type" ] }, { "type": "object", "description": "平均值规则参数。", "properties": { "operator": { "type": "string", "enum": [ "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual" ], "description": "与平均值的比较关系。" } }, "required": [ "operator" ] }, { "type": "object", "description": "自定义公式规则参数。", "properties": { "formula": { "type": "array", "items": { "type": "string" }, "description": "条件公式列表，例如 [\"=A1>0\"]。" } }, "required": [ "formula" ] }, { "type": "object", "description": "图标集规则参数。", "properties": { "icon_type": { "type": "string", "enum": [ "3Arrows", "3ArrowsGray", "3Triangles", "4ArrowsGray", "4Arrows", "5ArrowsGray", "5Arrows", "3Circles", "3MultiGraphics", "4Circles", "5Circles", "2Status", "3Status", "2CommentStatus", "3Flags", "3Stars", "3HeartShaped", "3Mood", "5CirclesRatio" ], "description": "图标集类型。其中 3Circles/4Circles/5Circles 为不同颜色的实心圆（如红、黄、绿），用于表示状态等级；5CirclesRatio 为不同填充比例的圆（从空心◯到半圆◑到满圆●），用于表示完成度、进度、比例。当涉及半圆、满圆、空心圆、填充比例、进度等场景时，应选择 5CirclesRatio。" }, "hide_value": { "type": "boolean", "description": "是否隐藏单元格原始值，仅显示图标。" }, "value_type": { "type": "string", "enum": [ "minValue", "maxValue", "num", "percentile", "percent", "formula", "auto" ], "description": "阈值类型。" }, "operator": { "type": "string", "enum": [ "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual" ], "description": "与阈值的比较关系。" }, "value": { "type": "number", "description": "用于比较的数值，含义由 value_type 决定。" }, "reverse_icons": { "type": "boolean", "description": "是否反转图标顺序。" } }, "required": [ "icon_type", "value_type", "operator" ] } ] } }, "has_ref": { "type": "boolean", "description": "可选。是否存在引用，用于标记规则是否依赖其他对象。" } }, "required": [ "rule_type", "ranges", "style" ] } }, "+cond-format-update": { "properties": { "description": "创建/更新的条件格式属性。", "type": "object", "properties": { "rule_type": { "type": "string", "enum": [ "duplicateValues", "uniqueValues", "cellIs", "containsText", "timePeriod", "containsBlanks", "notContainsBlanks", "dataBar", "colorScale", "rank", "aboveAverage", "expression", "iconSet" ], "description": "条件格式规则类型。" }, "ranges": { "type": "array", "description": "应用条件格式的 A1 范围列表。每个元素支持：矩形范围 \"A1:A10\"、整行 \"3:6\"、整列 \"C:C\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。例如 [\"A1:A10\",\"C:C\"]。", "items": { "type": "string" } }, "style": { "type": "object", "description": "命中规则时应用的单元格样式。", "properties": { "back_color": { "type": "string", "description": "背景色，CSS 十六进制表示，例如 \"#FF0000\"。" }, "fore_color": { "type": "string", "description": "前景色/字体颜色。" }, "text_decoration": { "type": "string", "enum": [ "none", "underline", "strikethrough", "underline_strikethrough" ], "description": "文字装饰：none=无，underline=下划线，strikethrough=删除线，underline_strikethrough=下划线+删除线。" }, "font": { "type": "string", "enum": [ "bold", "italic", "bold italic" ], "description": "字体样式：\"bold\"=加粗，\"italic\"=斜体，\"bold italic\"=加粗+斜体。" } } }, "attrs": { "type": "array", "description": "规则参数列表。不同 rule_type 下取值结构不同。当 rule_type 为 dataBar 时，attrs 必须包含两个对象，分别定义正值和负值的数据条颜色。", "items": { "oneOf": [ { "type": "object", "description": "数值比较类规则参数。", "properties": { "compare_type": { "type": "string", "enum": [ "equal", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "between", "notBetween" ], "description": "比较运算符。" }, "value": { "type": "string", "description": "用于比较的值，例如 \"100\"、\"hello\"。between/notBetween 时用逗号分隔两个值。" } }, "required": [ "compare_type", "value" ] }, { "type": "object", "description": "文本包含类规则参数。", "properties": { "text": { "type": "string", "description": "用于匹配的文本内容。" }, "compare_type": { "type": "string", "enum": [ "beginsWith", "endsWith", "containsText", "notContains", "is" ], "description": "文本匹配方式。" } }, "required": [ "compare_type", "text" ] }, { "type": "object", "description": "时间段类规则参数。", "properties": { "operator": { "type": "string", "enum": [ "before", "is", "after" ], "description": "与指定时间段的比较关系。" }, "time_period": { "type": "string", "enum": [ "today", "yesterday", "tomorrow", "last7Days", "thisMonth", "lastMonth", "nextMonth", "thisWeek", "lastWeek", "nextWeek" ], "description": "时间段类型。" } }, "required": [ "operator", "time_period" ] }, { "type": "object", "description": "数据条规则参数。", "properties": { "gradient": { "type": "boolean", "description": "是否使用渐变色数据条。" }, "value": { "type": "number", "description": "阈值或比例值，含义由 value_type 决定。" }, "color": { "type": "string", "description": "主颜色，例如 \"#63BE7B\"。" }, "hide_value": { "type": "boolean", "description": "是否隐藏单元格中的原始值，仅显示数据条。" }, "value_type": { "type": "string", "enum": [ "minValue", "maxValue", "num", "percentile", "percent", "formula", "auto" ], "description": "阈值类型。" } }, "required": [ "color", "value_type" ] }, { "type": "object", "description": "色阶规则中的单个分段。ColorScaleAttrs 由 2 或 3 个该对象组成，分别表示最小值/中间值/最大值。", "properties": { "value_type": { "type": "string", "enum": [ "minValue", "maxValue", "num", "percentile", "percent", "formula", "auto" ], "description": "阈值类型。" }, "value": { "type": "number", "description": "阈值数值，例如百分位或具体数值。" }, "color": { "type": "string", "description": "该分段对应的颜色。" } }, "required": [ "value_type", "color" ] }, { "type": "object", "description": "前 N/后 N 规则参数。", "properties": { "is_bottom": { "type": "boolean", "description": "是否选取最后 N 个。true 表示最后 N 个，false 表示前 N 个。" }, "value_type": { "type": "string", "enum": [ "percent", "sort" ], "description": "排名方式：percent 表示百分比，sort 表示按条目数。" }, "value": { "type": "number", "description": "N 或百分比数值。" } }, "required": [ "is_bottom", "value_type" ] }, { "type": "object", "description": "平均值规则参数。", "properties": { "operator": { "type": "string", "enum": [ "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual" ], "description": "与平均值的比较关系。" } }, "required": [ "operator" ] }, { "type": "object", "description": "自定义公式规则参数。", "properties": { "formula": { "type": "array", "items": { "type": "string" }, "description": "条件公式列表，例如 [\"=A1>0\"]。" } }, "required": [ "formula" ] }, { "type": "object", "description": "图标集规则参数。", "properties": { "icon_type": { "type": "string", "enum": [ "3Arrows", "3ArrowsGray", "3Triangles", "4ArrowsGray", "4Arrows", "5ArrowsGray", "5Arrows", "3Circles", "3MultiGraphics", "4Circles", "5Circles", "2Status", "3Status", "2CommentStatus", "3Flags", "3Stars", "3HeartShaped", "3Mood", "5CirclesRatio" ], "description": "图标集类型。其中 3Circles/4Circles/5Circles 为不同颜色的实心圆（如红、黄、绿），用于表示状态等级；5CirclesRatio 为不同填充比例的圆（从空心◯到半圆◑到满圆●），用于表示完成度、进度、比例。当涉及半圆、满圆、空心圆、填充比例、进度等场景时，应选择 5CirclesRatio。" }, "hide_value": { "type": "boolean", "description": "是否隐藏单元格原始值，仅显示图标。" }, "value_type": { "type": "string", "enum": [ "minValue", "maxValue", "num", "percentile", "percent", "formula", "auto" ], "description": "阈值类型。" }, "operator": { "type": "string", "enum": [ "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual" ], "description": "与阈值的比较关系。" }, "value": { "type": "number", "description": "用于比较的数值，含义由 value_type 决定。" }, "reverse_icons": { "type": "boolean", "description": "是否反转图标顺序。" } }, "required": [ "icon_type", "value_type", "operator" ] } ] } }, "has_ref": { "type": "boolean", "description": "可选。是否存在引用，用于标记规则是否依赖其他对象。" } }, "required": [ "rule_type", "ranges", "style" ] } }, "+dropdown-set": { "options": { "description": "列表选项", "type": "array", "items": { "type": "string" } } }, "+dropdown-update": { "options": { "description": "列表选项", "type": "array", "items": { "type": "string" } } }, "+filter-create": { "properties": { "description": "创建/更新的筛选器属性。", "type": "object", "properties": { "range": { "type": "string", "description": "筛选对象作用的单元格范围（A1 表示法）。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。" }, "rules": { "type": "array", "description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。update 为整组覆盖（PUT 语义）：传入的 rules 即更新后的完整规则集，会先清空所有现有列的旧规则再应用，未列出的列其旧规则会被清除（不与旧规则合并）；传空数组 [] 即清空所有列的规则。", "items": { "type": "object", "description": "单列筛选规则。", "properties": { "column_index": { "type": "string", "description": "作用的列索引，例如 \"A\"、\"B\"。" }, "conditions": { "type": "array", "description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。", "items": { "oneOf": [ { "type": "object", "description": "文本条件筛选。", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "条件类型固定为 \"text\"。" }, "compare_type": { "type": "string", "enum": [ "beginsWith", "doesNotBeginWith", "endsWith", "doesNotEndWith", "contains", "doesNotContain", "equals", "notEquals" ], "description": "文本比较方式：beginsWith=以指定文本开头，doesNotBeginWith=不以指定文本开头，endsWith=以指定文本结尾，doesNotEndWith=不以指定文本结尾，contains=包含，doesNotContain=不包含，equals=等于，notEquals=不等于。" }, "values": { "type": "array", "description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。", "items": { "type": "string" } } }, "required": [ "type", "compare_type" ] }, { "type": "object", "description": "数值条件筛选。", "properties": { "type": { "type": "string", "enum": [ "number" ], "description": "条件类型固定为 \"number\"。" }, "compare_type": { "type": "string", "enum": [ "equal", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "between", "notBetween" ], "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。" }, "values": { "type": "array", "description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。", "items": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } } }, "required": [ "type", "compare_type" ] }, { "type": "object", "description": "颜色条件筛选。", "properties": { "type": { "type": "string", "enum": [ "color" ], "description": "条件类型固定为 \"color\"。" }, "compare_type": { "type": "string", "enum": [ "backgroundColor", "foregroundColor" ], "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。" }, "value": { "type": "string", "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。" } }, "required": [ "type", "compare_type" ] }, { "type": "object", "description": "多值条件筛选。", "properties": { "type": { "type": "string", "enum": [ "multiValue" ], "description": "条件类型固定为 \"multiValue\"。" }, "compare_type": { "type": "string", "enum": [ "equal", "notEqual" ], "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。" }, "values": { "type": "array", "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", "items": { "type": "string" } }, "date_groups": { "type": "array", "description": "可选。年月日等聚合筛选信息。", "items": { "type": "object", "properties": { "year": { "type": "number" }, "month": { "type": "number" }, "day": { "type": "number" }, "hour": { "type": "number" }, "minute": { "type": "number" }, "second": { "type": "number" }, "date_time_grouping": { "type": "string", "enum": [ "year", "month", "day", "hour", "minute", "second" ] } } } } }, "required": [ "type", "compare_type" ] } ] } }, "filtered_rows": { "type": "array", "description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。", "items": { "type": "number" } } }, "required": [ "column_index", "conditions" ] } }, "filtered_columns": { "type": "array", "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", "items": { "type": "string" } } }, "required": [ "range", "rules" ] } }, "+filter-update": { "properties": { "description": "创建/更新的筛选器属性。", "type": "object", "properties": { "range": { "type": "string", "description": "筛选对象作用的单元格范围（A1 表示法）。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。" }, "rules": { "type": "array", "description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。update 为整组覆盖（PUT 语义）：传入的 rules 即更新后的完整规则集，会先清空所有现有列的旧规则再应用，未列出的列其旧规则会被清除（不与旧规则合并）；传空数组 [] 即清空所有列的规则。", "items": { "type": "object", "description": "单列筛选规则。", "properties": { "column_index": { "type": "string", "description": "作用的列索引，例如 \"A\"、\"B\"。" }, "conditions": { "type": "array", "description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。", "items": { "oneOf": [ { "type": "object", "description": "文本条件筛选。", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "条件类型固定为 \"text\"。" }, "compare_type": { "type": "string", "enum": [ "beginsWith", "doesNotBeginWith", "endsWith", "doesNotEndWith", "contains", "doesNotContain", "equals", "notEquals" ], "description": "文本比较方式：beginsWith=以指定文本开头，doesNotBeginWith=不以指定文本开头，endsWith=以指定文本结尾，doesNotEndWith=不以指定文本结尾，contains=包含，doesNotContain=不包含，equals=等于，notEquals=不等于。" }, "values": { "type": "array", "description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。", "items": { "type": "string" } } }, "required": [ "type", "compare_type" ] }, { "type": "object", "description": "数值条件筛选。", "properties": { "type": { "type": "string", "enum": [ "number" ], "description": "条件类型固定为 \"number\"。" }, "compare_type": { "type": "string", "enum": [ "equal", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "between", "notBetween" ], "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。" }, "values": { "type": "array", "description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。", "items": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } } }, "required": [ "type", "compare_type" ] }, { "type": "object", "description": "颜色条件筛选。", "properties": { "type": { "type": "string", "enum": [ "color" ], "description": "条件类型固定为 \"color\"。" }, "compare_type": { "type": "string", "enum": [ "backgroundColor", "foregroundColor" ], "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。" }, "value": { "type": "string", "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。" } }, "required": [ "type", "compare_type" ] }, { "type": "object", "description": "多值条件筛选。", "properties": { "type": { "type": "string", "enum": [ "multiValue" ], "description": "条件类型固定为 \"multiValue\"。" }, "compare_type": { "type": "string", "enum": [ "equal", "notEqual" ], "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。" }, "values": { "type": "array", "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", "items": { "type": "string" } }, "date_groups": { "type": "array", "description": "可选。年月日等聚合筛选信息。", "items": { "type": "object", "properties": { "year": { "type": "number" }, "month": { "type": "number" }, "day": { "type": "number" }, "hour": { "type": "number" }, "minute": { "type": "number" }, "second": { "type": "number" }, "date_time_grouping": { "type": "string", "enum": [ "year", "month", "day", "hour", "minute", "second" ] } } } } }, "required": [ "type", "compare_type" ] } ] } }, "filtered_rows": { "type": "array", "description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。", "items": { "type": "number" } } }, "required": [ "column_index", "conditions" ] } }, "filtered_columns": { "type": "array", "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", "items": { "type": "string" } } }, "required": [ "range", "rules" ] } }, "+filter-view-create": { "properties": { "description": "create / update 的视图属性。create 必须传 range；update 至少传 view_name / range / rules 之一。delete 禁止传该字段。", "type": "object", "properties": { "view_name": { "type": "string", "description": "可选。视图名称。create 不传时系统自动分配；create / update 传入时若与现有视图重名，会自动以后缀避让，不会抛错。" }, "range": { "type": "string", "description": "视图作用的单元格范围（A1 表示法）。create 必填；update 可选——未提供时沿用视图当前 range。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。" }, "rules": { "type": "array", "description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。结构与 manage_filter_object.properties.rules 完全一致。update 同样为整组覆盖（PUT 语义）：传入的 rules 整组替换该视图所有列的规则，未列出的列其旧规则会被清除（不与旧规则合并），传空数组 [] 即清空全部。", "items": { "type": "object", "description": "单列筛选规则。", "properties": { "column_index": { "type": "string", "description": "作用的列索引，例如 \"A\"、\"B\"。" }, "conditions": { "type": "array", "description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。", "items": { "oneOf": [ { "type": "object", "description": "文本条件筛选。", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "条件类型固定为 \"text\"。" }, "compare_type": { "type": "string", "enum": [ "beginsWith", "doesNotBeginWith", "endsWith", "doesNotEndWith", "contains", "doesNotContain", "equals", "notEquals" ], "description": "文本比较方式:beginsWith=以指定文本开头,doesNotBeginWith=不以指定文本开头,endsWith=以指定文本结尾,doesNotEndWith=不以指定文本结尾,contains=包含,doesNotContain=不包含,equals=等于,notEquals=不等于。" }, "values": { "type": "array", "description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。", "items": { "type": "string" } } }, "required": [ "type", "compare_type" ] }, { "type": "object", "description": "数值条件筛选。", "properties": { "type": { "type": "string", "enum": [ "number" ], "description": "条件类型固定为 \"number\"。" }, "compare_type": { "type": "string", "enum": [ "equal", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "between", "notBetween" ], "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。" }, "values": { "type": "array", "description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。", "items": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } } }, "required": [ "type", "compare_type" ] }, { "type": "object", "description": "颜色条件筛选。", "properties": { "type": { "type": "string", "enum": [ "color" ], "description": "条件类型固定为 \"color\"。" }, "compare_type": { "type": "string", "enum": [ "backgroundColor", "foregroundColor" ], "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。" }, "value": { "type": "string", "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。" } }, "required": [ "type", "compare_type" ] }, { "type": "object", "description": "多值条件筛选。", "properties": { "type": { "type": "string", "enum": [ "multiValue" ], "description": "条件类型固定为 \"multiValue\"。" }, "compare_type": { "type": "string", "enum": [ "equal", "notEqual" ], "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。" }, "values": { "type": "array", "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", "items": { "type": "string" } }, "date_groups": { "type": "array", "description": "可选。年月日等聚合筛选信息。", "items": { "type": "object", "properties": { "year": { "type": "number" }, "month": { "type": "number" }, "day": { "type": "number" }, "hour": { "type": "number" }, "minute": { "type": "number" }, "second": { "type": "number" }, "date_time_grouping": { "type": "string", "enum": [ "year", "month", "day", "hour", "minute", "second" ] } } } } }, "required": [ "type", "compare_type" ] } ] } }, "filtered_rows": { "type": "array", "description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。", "items": { "type": "number" } } }, "required": [ "column_index", "conditions" ] } }, "filtered_columns": { "type": "array", "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", "items": { "type": "string" } } } } }, "+filter-view-update": { "properties": { "description": "create / update 的视图属性。create 必须传 range；update 至少传 view_name / range / rules 之一。delete 禁止传该字段。", "type": "object", "properties": { "view_name": { "type": "string", "description": "可选。视图名称。create 不传时系统自动分配；create / update 传入时若与现有视图重名，会自动以后缀避让，不会抛错。" }, "range": { "type": "string", "description": "视图作用的单元格范围（A1 表示法）。create 必填；update 可选——未提供时沿用视图当前 range。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。" }, "rules": { "type": "array", "description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。结构与 manage_filter_object.properties.rules 完全一致。update 同样为整组覆盖（PUT 语义）：传入的 rules 整组替换该视图所有列的规则，未列出的列其旧规则会被清除（不与旧规则合并），传空数组 [] 即清空全部。", "items": { "type": "object", "description": "单列筛选规则。", "properties": { "column_index": { "type": "string", "description": "作用的列索引，例如 \"A\"、\"B\"。" }, "conditions": { "type": "array", "description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。", "items": { "oneOf": [ { "type": "object", "description": "文本条件筛选。", "properties": { "type": { "type": "string", "enum": [ "text" ], "description": "条件类型固定为 \"text\"。" }, "compare_type": { "type": "string", "enum": [ "beginsWith", "doesNotBeginWith", "endsWith", "doesNotEndWith", "contains", "doesNotContain", "equals", "notEquals" ], "description": "文本比较方式:beginsWith=以指定文本开头,doesNotBeginWith=不以指定文本开头,endsWith=以指定文本结尾,doesNotEndWith=不以指定文本结尾,contains=包含,doesNotContain=不包含,equals=等于,notEquals=不等于。" }, "values": { "type": "array", "description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。", "items": { "type": "string" } } }, "required": [ "type", "compare_type" ] }, { "type": "object", "description": "数值条件筛选。", "properties": { "type": { "type": "string", "enum": [ "number" ], "description": "条件类型固定为 \"number\"。" }, "compare_type": { "type": "string", "enum": [ "equal", "notEqual", "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual", "between", "notBetween" ], "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。" }, "values": { "type": "array", "description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。", "items": { "oneOf": [ { "type": "number" }, { "type": "string" } ] } } }, "required": [ "type", "compare_type" ] }, { "type": "object", "description": "颜色条件筛选。", "properties": { "type": { "type": "string", "enum": [ "color" ], "description": "条件类型固定为 \"color\"。" }, "compare_type": { "type": "string", "enum": [ "backgroundColor", "foregroundColor" ], "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。" }, "value": { "type": "string", "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。" } }, "required": [ "type", "compare_type" ] }, { "type": "object", "description": "多值条件筛选。", "properties": { "type": { "type": "string", "enum": [ "multiValue" ], "description": "条件类型固定为 \"multiValue\"。" }, "compare_type": { "type": "string", "enum": [ "equal", "notEqual" ], "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。" }, "values": { "type": "array", "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", "items": { "type": "string" } }, "date_groups": { "type": "array", "description": "可选。年月日等聚合筛选信息。", "items": { "type": "object", "properties": { "year": { "type": "number" }, "month": { "type": "number" }, "day": { "type": "number" }, "hour": { "type": "number" }, "minute": { "type": "number" }, "second": { "type": "number" }, "date_time_grouping": { "type": "string", "enum": [ "year", "month", "day", "hour", "minute", "second" ] } } } } }, "required": [ "type", "compare_type" ] } ] } }, "filtered_rows": { "type": "array", "description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。", "items": { "type": "number" } } }, "required": [ "column_index", "conditions" ] } }, "filtered_columns": { "type": "array", "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", "items": { "type": "string" } } } } }, "+pivot-create": { "properties": { "description": "创建/更新的透视表属性。", "type": "object", "properties": { "range": { "type": "string", "description": "放置透视表的左上角单元格 A1 地址（例如：'F1'）（仅 create 时有效）。可省略——省略后透视表放在新建子表的 A1 位置。" }, "source": { "type": "string", "description": "源数据区域地址，格式为 'SheetName!StartCell:EndCell'（例如：'Sheet1!A1:D100'）。create 时必填；update 时提供则切换数据源。" }, "rows": { "description": "纵向分组字段（行字段）", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "源数据中的字段名（OOXML 字段引用）" }, "display_name": { "type": "string", "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用；否则保持源字段原名，透视表产物已足够清晰。" }, "sort": { "type": "object", "description": "排序配置", "properties": { "order": { "type": "string", "enum": [ "asc", "desc" ], "description": "排序方向" }, "by": { "type": "string", "enum": [ "label", "value" ], "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序" }, "value_field": { "type": "string", "description": "by='value' 时必填，指定按哪个值字段排序" } }, "required": [ "order" ] }, "filter": { "type": "object", "description": "快速筛选：只显示指定的项目", "properties": { "items": { "type": "array", "items": { "type": "string" }, "description": "要显示的项目列表（其余项目被隐藏）" } }, "required": [ "items" ] }, "condition_filter": { "type": "object", "description": "条件筛选：按文本/数值/日期条件筛选", "properties": { "type": { "type": "string", "enum": [ "text", "number", "date" ], "description": "条件类型" }, "operator": { "type": "string", "description": "text: equals|notEquals|contains|notContains|beginsWith|notBeginsWith|endsWith|notEndsWith|empty|notEmpty; number: equals|notEquals|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual|between|notBetween; date: equals|notEquals|earlierThan|earlierThanOrEqual|laterThan|laterThanOrEqual|between|notBetween|today|yesterday|tomorrow|thisWeek|lastWeek|nextWeek|thisMonth|lastMonth|nextMonth|thisQuarter|lastQuarter|nextQuarter|thisYear|lastYear|nextYear|yearToDate|quarter|month" }, "value": { "description": "比较值" }, "value2": { "description": "'between'/'notBetween' 的第二个边界值" } }, "required": [ "type", "operator" ] }, "group": { "type": "object", "description": "分组配置", "properties": { "type": { "type": "string", "enum": [ "date", "number", "element" ], "description": "分组类型" }, "date_group_by": { "type": "string", "enum": [ "year", "yearMonth", "yearQuarter", "yearMonthDate", "quarter", "month", "monthDate", "date", "hour", "hourMinute", "minute" ], "description": "日期分组粒度（type='date' 时必填）" }, "interval": { "type": "number", "description": "数值分组间隔（type='number' 时必填）" }, "start": { "type": "number", "description": "数值分组起始值" }, "end": { "type": "number", "description": "数值分组结束值" }, "groups": { "type": "object", "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "type" ] } }, "required": [ "field" ] } }, "columns": { "description": "横向分组字段（列字段）", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "源数据中的字段名（OOXML 字段引用）" }, "display_name": { "type": "string", "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。" }, "sort": { "type": "object", "description": "排序配置", "properties": { "order": { "type": "string", "enum": [ "asc", "desc" ], "description": "排序方向" }, "by": { "type": "string", "enum": [ "label", "value" ], "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序" }, "value_field": { "type": "string", "description": "by='value' 时必填，指定按哪个值字段排序" } }, "required": [ "order" ] }, "filter": { "type": "object", "description": "快速筛选：只显示指定的项目", "properties": { "items": { "type": "array", "items": { "type": "string" }, "description": "要显示的项目列表（其余项目被隐藏）" } }, "required": [ "items" ] }, "condition_filter": { "type": "object", "description": "条件筛选：按文本/数值/日期条件筛选", "properties": { "type": { "type": "string", "enum": [ "text", "number", "date" ], "description": "条件类型" }, "operator": { "type": "string", "description": "text: equals|notEquals|contains|notContains|beginsWith|notBeginsWith|endsWith|notEndsWith|empty|notEmpty; number: equals|notEquals|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual|between|notBetween; date: equals|notEquals|earlierThan|earlierThanOrEqual|laterThan|laterThanOrEqual|between|notBetween|today|yesterday|tomorrow|thisWeek|lastWeek|nextWeek|thisMonth|lastMonth|nextMonth|thisQuarter|lastQuarter|nextQuarter|thisYear|lastYear|nextYear|yearToDate|quarter|month" }, "value": { "description": "比较值" }, "value2": { "description": "'between'/'notBetween' 的第二个边界值" } }, "required": [ "type", "operator" ] }, "group": { "type": "object", "description": "分组配置", "properties": { "type": { "type": "string", "enum": [ "date", "number", "element" ], "description": "分组类型" }, "date_group_by": { "type": "string", "enum": [ "year", "yearMonth", "yearQuarter", "yearMonthDate", "quarter", "month", "monthDate", "date", "hour", "hourMinute", "minute" ], "description": "日期分组粒度（type='date' 时必填）" }, "interval": { "type": "number", "description": "数值分组间隔（type='number' 时必填）" }, "start": { "type": "number", "description": "数值分组起始值" }, "end": { "type": "number", "description": "数值分组结束值" }, "groups": { "type": "object", "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "type" ] } }, "required": [ "field" ] } }, "filters": { "description": "筛选区域字段（页字段）", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "源数据中的字段名（OOXML 字段引用）" }, "display_name": { "type": "string", "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。" }, "filter": { "type": "object", "description": "快速筛选：只显示指定的项目", "properties": { "items": { "type": "array", "items": { "type": "string" }, "description": "要显示的项目列表（其余项目被隐藏）" } }, "required": [ "items" ] }, "condition_filter": { "type": "object", "description": "条件筛选：按文本/数值/日期条件筛选", "properties": { "type": { "type": "string", "enum": [ "text", "number", "date" ], "description": "条件类型" }, "operator": { "type": "string", "description": "text: equals|notEquals|contains|notContains|beginsWith|notBeginsWith|endsWith|notEndsWith|empty|notEmpty; number: equals|notEquals|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual|between|notBetween; date: equals|notEquals|earlierThan|earlierThanOrEqual|laterThan|laterThanOrEqual|between|notBetween|today|yesterday|tomorrow|thisWeek|lastWeek|nextWeek|thisMonth|lastMonth|nextMonth|thisQuarter|lastQuarter|nextQuarter|thisYear|lastYear|nextYear|yearToDate|quarter|month" }, "value": { "description": "比较值" }, "value2": { "description": "'between'/'notBetween' 的第二个边界值" } }, "required": [ "type", "operator" ] }, "group": { "type": "object", "description": "分组配置", "properties": { "type": { "type": "string", "enum": [ "date", "number", "element" ], "description": "分组类型" }, "date_group_by": { "type": "string", "enum": [ "year", "yearMonth", "yearQuarter", "yearMonthDate", "quarter", "month", "monthDate", "date", "hour", "hourMinute", "minute" ], "description": "日期分组粒度（type='date' 时必填）" }, "interval": { "type": "number", "description": "数值分组间隔（type='number' 时必填）" }, "start": { "type": "number", "description": "数值分组起始值" }, "end": { "type": "number", "description": "数值分组结束值" }, "groups": { "type": "object", "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "type" ] } }, "required": [ "field" ] } }, "values": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "要汇总的源数据字段名" }, "display_name": { "type": "string", "description": "字段在透视表中的显示名（典型场景：把 count(销售额) 的值列头显示为 'GMV'）。不传则使用源字段原名。仅在用户明确要求重命名时使用。" }, "summarize_by": { "default": "sum", "description": "汇总函数", "type": "string", "enum": [ "sum", "count", "average", "max", "min", "product", "countNums", "stdDev", "stdDevp", "var", "varp", "distinct", "median" ] }, "show_data_as": { "type": "string", "description": "值显示方式（默认 'normal'）", "enum": [ "normal", "percentOfTotal", "percentOfCol", "percentOfRow", "percentOfParentRow", "percentOfParentCol", "index" ] }, "base_field": { "type": "string", "description": "show_data_as 需要基准字段时的字段名" } }, "required": [ "field" ] }, "description": "要汇总的字段（至少需要 1 个）" }, "auto_fit_col": { "type": "boolean", "description": "是否自动调整列宽以适应内容" }, "show_row_grand_total": { "type": "boolean", "description": "是否显示行总计（默认 true）" }, "show_col_grand_total": { "type": "boolean", "description": "是否显示列总计（默认 true）" }, "show_subtotals": { "type": "boolean", "description": "是否显示分类小计（默认 true，应用于所有字段）" }, "repeat_row_labels": { "type": "boolean", "description": "是否显示重复项标签" }, "calculated_fields": { "type": "array", "description": "计算字段列表", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "计算字段的显示名称" }, "formula": { "type": "string", "description": "公式表达式，引用其他字段名，例如 \"'Sales' + 'Tax'\"" }, "summarize_by": { "type": "string", "default": "sum", "description": "计算字段汇总方式（默认 'sum'，仅支持 sum/custom 两种）：'sum' 表示先对 formula 中引用的各源字段分别求和后再代入公式（formula 是逐字段求和后的标量表达式，例如 \"'Sales'+'Tax'\" 等价于 SUM(Sales)+SUM(Tax)）；'custom' 表示数组直接传给 formula，要求 formula 自带聚合函数（例如 \"SUM('Sales')+SUM('Tax')\" 或 \"AVERAGE('Sales')\"）。需要 count/average/max/min 等其他聚合方式时，请改用 values[] 字段对源字段直接聚合，calculated_fields 不适用。", "enum": [ "sum", "custom" ] } }, "required": [ "name", "formula" ] } }, "collapse": { "type": "object", "description": "行字段展开/折叠状态：字段名 -> 要折叠的项目列表", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } }, "+pivot-update": { "properties": { "description": "创建/更新的透视表属性。", "type": "object", "properties": { "range": { "type": "string", "description": "放置透视表的左上角单元格 A1 地址（例如：'F1'）（仅 create 时有效）。可省略——省略后透视表放在新建子表的 A1 位置。" }, "source": { "type": "string", "description": "源数据区域地址，格式为 'SheetName!StartCell:EndCell'（例如：'Sheet1!A1:D100'）。create 时必填；update 时提供则切换数据源。" }, "rows": { "description": "纵向分组字段（行字段）", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "源数据中的字段名（OOXML 字段引用）" }, "display_name": { "type": "string", "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用；否则保持源字段原名，透视表产物已足够清晰。" }, "sort": { "type": "object", "description": "排序配置", "properties": { "order": { "type": "string", "enum": [ "asc", "desc" ], "description": "排序方向" }, "by": { "type": "string", "enum": [ "label", "value" ], "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序" }, "value_field": { "type": "string", "description": "by='value' 时必填，指定按哪个值字段排序" } }, "required": [ "order" ] }, "filter": { "type": "object", "description": "快速筛选：只显示指定的项目", "properties": { "items": { "type": "array", "items": { "type": "string" }, "description": "要显示的项目列表（其余项目被隐藏）" } }, "required": [ "items" ] }, "condition_filter": { "type": "object", "description": "条件筛选：按文本/数值/日期条件筛选", "properties": { "type": { "type": "string", "enum": [ "text", "number", "date" ], "description": "条件类型" }, "operator": { "type": "string", "description": "text: equals|notEquals|contains|notContains|beginsWith|notBeginsWith|endsWith|notEndsWith|empty|notEmpty; number: equals|notEquals|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual|between|notBetween; date: equals|notEquals|earlierThan|earlierThanOrEqual|laterThan|laterThanOrEqual|between|notBetween|today|yesterday|tomorrow|thisWeek|lastWeek|nextWeek|thisMonth|lastMonth|nextMonth|thisQuarter|lastQuarter|nextQuarter|thisYear|lastYear|nextYear|yearToDate|quarter|month" }, "value": { "description": "比较值" }, "value2": { "description": "'between'/'notBetween' 的第二个边界值" } }, "required": [ "type", "operator" ] }, "group": { "type": "object", "description": "分组配置", "properties": { "type": { "type": "string", "enum": [ "date", "number", "element" ], "description": "分组类型" }, "date_group_by": { "type": "string", "enum": [ "year", "yearMonth", "yearQuarter", "yearMonthDate", "quarter", "month", "monthDate", "date", "hour", "hourMinute", "minute" ], "description": "日期分组粒度（type='date' 时必填）" }, "interval": { "type": "number", "description": "数值分组间隔（type='number' 时必填）" }, "start": { "type": "number", "description": "数值分组起始值" }, "end": { "type": "number", "description": "数值分组结束值" }, "groups": { "type": "object", "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "type" ] } }, "required": [ "field" ] } }, "columns": { "description": "横向分组字段（列字段）", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "源数据中的字段名（OOXML 字段引用）" }, "display_name": { "type": "string", "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。" }, "sort": { "type": "object", "description": "排序配置", "properties": { "order": { "type": "string", "enum": [ "asc", "desc" ], "description": "排序方向" }, "by": { "type": "string", "enum": [ "label", "value" ], "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序" }, "value_field": { "type": "string", "description": "by='value' 时必填，指定按哪个值字段排序" } }, "required": [ "order" ] }, "filter": { "type": "object", "description": "快速筛选：只显示指定的项目", "properties": { "items": { "type": "array", "items": { "type": "string" }, "description": "要显示的项目列表（其余项目被隐藏）" } }, "required": [ "items" ] }, "condition_filter": { "type": "object", "description": "条件筛选：按文本/数值/日期条件筛选", "properties": { "type": { "type": "string", "enum": [ "text", "number", "date" ], "description": "条件类型" }, "operator": { "type": "string", "description": "text: equals|notEquals|contains|notContains|beginsWith|notBeginsWith|endsWith|notEndsWith|empty|notEmpty; number: equals|notEquals|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual|between|notBetween; date: equals|notEquals|earlierThan|earlierThanOrEqual|laterThan|laterThanOrEqual|between|notBetween|today|yesterday|tomorrow|thisWeek|lastWeek|nextWeek|thisMonth|lastMonth|nextMonth|thisQuarter|lastQuarter|nextQuarter|thisYear|lastYear|nextYear|yearToDate|quarter|month" }, "value": { "description": "比较值" }, "value2": { "description": "'between'/'notBetween' 的第二个边界值" } }, "required": [ "type", "operator" ] }, "group": { "type": "object", "description": "分组配置", "properties": { "type": { "type": "string", "enum": [ "date", "number", "element" ], "description": "分组类型" }, "date_group_by": { "type": "string", "enum": [ "year", "yearMonth", "yearQuarter", "yearMonthDate", "quarter", "month", "monthDate", "date", "hour", "hourMinute", "minute" ], "description": "日期分组粒度（type='date' 时必填）" }, "interval": { "type": "number", "description": "数值分组间隔（type='number' 时必填）" }, "start": { "type": "number", "description": "数值分组起始值" }, "end": { "type": "number", "description": "数值分组结束值" }, "groups": { "type": "object", "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "type" ] } }, "required": [ "field" ] } }, "filters": { "description": "筛选区域字段（页字段）", "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "源数据中的字段名（OOXML 字段引用）" }, "display_name": { "type": "string", "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。" }, "filter": { "type": "object", "description": "快速筛选：只显示指定的项目", "properties": { "items": { "type": "array", "items": { "type": "string" }, "description": "要显示的项目列表（其余项目被隐藏）" } }, "required": [ "items" ] }, "condition_filter": { "type": "object", "description": "条件筛选：按文本/数值/日期条件筛选", "properties": { "type": { "type": "string", "enum": [ "text", "number", "date" ], "description": "条件类型" }, "operator": { "type": "string", "description": "text: equals|notEquals|contains|notContains|beginsWith|notBeginsWith|endsWith|notEndsWith|empty|notEmpty; number: equals|notEquals|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual|between|notBetween; date: equals|notEquals|earlierThan|earlierThanOrEqual|laterThan|laterThanOrEqual|between|notBetween|today|yesterday|tomorrow|thisWeek|lastWeek|nextWeek|thisMonth|lastMonth|nextMonth|thisQuarter|lastQuarter|nextQuarter|thisYear|lastYear|nextYear|yearToDate|quarter|month" }, "value": { "description": "比较值" }, "value2": { "description": "'between'/'notBetween' 的第二个边界值" } }, "required": [ "type", "operator" ] }, "group": { "type": "object", "description": "分组配置", "properties": { "type": { "type": "string", "enum": [ "date", "number", "element" ], "description": "分组类型" }, "date_group_by": { "type": "string", "enum": [ "year", "yearMonth", "yearQuarter", "yearMonthDate", "quarter", "month", "monthDate", "date", "hour", "hourMinute", "minute" ], "description": "日期分组粒度（type='date' 时必填）" }, "interval": { "type": "number", "description": "数值分组间隔（type='number' 时必填）" }, "start": { "type": "number", "description": "数值分组起始值" }, "end": { "type": "number", "description": "数值分组结束值" }, "groups": { "type": "object", "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "type" ] } }, "required": [ "field" ] } }, "values": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "要汇总的源数据字段名" }, "display_name": { "type": "string", "description": "字段在透视表中的显示名（典型场景：把 count(销售额) 的值列头显示为 'GMV'）。不传则使用源字段原名。仅在用户明确要求重命名时使用。" }, "summarize_by": { "default": "sum", "description": "汇总函数", "type": "string", "enum": [ "sum", "count", "average", "max", "min", "product", "countNums", "stdDev", "stdDevp", "var", "varp", "distinct", "median" ] }, "show_data_as": { "type": "string", "description": "值显示方式（默认 'normal'）", "enum": [ "normal", "percentOfTotal", "percentOfCol", "percentOfRow", "percentOfParentRow", "percentOfParentCol", "index" ] }, "base_field": { "type": "string", "description": "show_data_as 需要基准字段时的字段名" } }, "required": [ "field" ] }, "description": "要汇总的字段（至少需要 1 个）" }, "auto_fit_col": { "type": "boolean", "description": "是否自动调整列宽以适应内容" }, "show_row_grand_total": { "type": "boolean", "description": "是否显示行总计（默认 true）" }, "show_col_grand_total": { "type": "boolean", "description": "是否显示列总计（默认 true）" }, "show_subtotals": { "type": "boolean", "description": "是否显示分类小计（默认 true，应用于所有字段）" }, "repeat_row_labels": { "type": "boolean", "description": "是否显示重复项标签" }, "calculated_fields": { "type": "array", "description": "计算字段列表", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "计算字段的显示名称" }, "formula": { "type": "string", "description": "公式表达式，引用其他字段名，例如 \"'Sales' + 'Tax'\"" }, "summarize_by": { "type": "string", "default": "sum", "description": "计算字段汇总方式（默认 'sum'，仅支持 sum/custom 两种）：'sum' 表示先对 formula 中引用的各源字段分别求和后再代入公式（formula 是逐字段求和后的标量表达式，例如 \"'Sales'+'Tax'\" 等价于 SUM(Sales)+SUM(Tax)）；'custom' 表示数组直接传给 formula，要求 formula 自带聚合函数（例如 \"SUM('Sales')+SUM('Tax')\" 或 \"AVERAGE('Sales')\"）。需要 count/average/max/min 等其他聚合方式时，请改用 values[] 字段对源字段直接聚合，calculated_fields 不适用。", "enum": [ "sum", "custom" ] } }, "required": [ "name", "formula" ] } }, "collapse": { "type": "object", "description": "行字段展开/折叠状态：字段名 -> 要折叠的项目列表", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } }, "+range-sort": { "sort-keys": { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "string", "description": "排序依据的列字母（如 \"C\"、\"D\"），必须在 range 范围内" }, "ascending": { "type": "boolean", "description": "是否升序排序" } }, "required": [ "column", "ascending" ] }, "description": "排序条件列表（仅 sort 操作）。支持多级排序，靠前的条件优先级更高。" } }, "+sparkline-create": { "properties": { "description": "创建/更新/部分删除的迷你图属性。delete 时不传 sparklines 即删整组，传则删指定项。", "type": "object", "properties": { "config": { "type": "object", "description": "迷你图样式配置, 相同 groupId 的迷你图共享相同的样式。", "properties": { "theme_type": { "type": "string", "enum": [ "pro", "light", "soft", "brand", "fresh" ], "description": "主题类型：pro、light、soft、brand、fresh。" }, "non_num_show_as": { "type": "string", "enum": [ "zero", "gap", "average" ], "description": "非数字单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。" }, "empty_show_as": { "type": "string", "enum": [ "zero", "gap", "average" ], "description": "空单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。" }, "contain_hidden_cells": { "type": "boolean", "description": "隐藏的单元格数据是否参与绘制。" }, "series_color": { "type": "string", "description": "主系列颜色，例如 \"#4472C4\"。" }, "points": { "type": "object", "description": "特殊点样式配置，包含高点、低点、标记点、首点、尾点、负点。", "properties": { "last_point": { "type": "object", "description": "尾点配置，最后一个数据点的样式。", "properties": { "color": { "type": "string", "description": "点的颜色。" }, "visible": { "type": "boolean", "description": "是否显示该点。" } } }, "negative_point": { "type": "object", "description": "负点配置，负数点的样式。", "properties": { "color": { "type": "string", "description": "点的颜色。" }, "visible": { "type": "boolean", "description": "是否显示该点。" } } }, "markers_point": { "type": "object", "description": "标记点配置，所有标记点的样式。", "properties": { "color": { "type": "string", "description": "点的颜色。" }, "visible": { "type": "boolean", "description": "是否显示该点。" } } }, "first_point": { "type": "object", "description": "首点配置，第一个数据点的样式。", "properties": { "color": { "type": "string", "description": "点的颜色。" }, "visible": { "type": "boolean", "description": "是否显示该点。" } } }, "high_point": { "type": "object", "description": "高点配置，最高点的样式。", "properties": { "color": { "type": "string", "description": "点的颜色。" }, "visible": { "type": "boolean", "description": "是否显示该点。" } } }, "low_point": { "type": "object", "description": "低点配置，最低点的样式。", "properties": { "color": { "type": "string", "description": "点的颜色。" }, "visible": { "type": "boolean", "description": "是否显示该点。" } } } } }, "line_width": { "type": "number", "enum": [ 1, 2, 3, 4 ], "description": "折线图线宽，可选值：1=1px，2=2px，3=3px，4=4px。" }, "type": { "type": "string", "enum": [ "line", "column", "win_loss" ], "description": "迷你图类型，可选值：line=折线图，column=柱形图，win_loss=盈亏图。" }, "axis": { "type": "object", "description": "坐标轴配置，包含坐标轴颜色、是否翻转、是否显示坐标轴。", "properties": { "color": { "type": "string", "description": "坐标轴颜色。" }, "reverse": { "type": "boolean", "description": "是否翻转坐标轴方向。" }, "visible": { "type": "boolean", "description": "是否显示坐标轴。" } } }, "show_gradient": { "type": "boolean", "description": "是否显示渐变效果。" }, "show_radius": { "type": "boolean", "description": "是否显示圆角，仅对柱形图和盈亏图生效。" }, "extremum_max": { "type": "object", "description": "最大极值配置，包含极值类型、极值。", "properties": { "type": { "type": "string", "enum": [ "individual", "group", "custom" ], "description": "极值类型，可选值：individual=单个迷你图极值，group=同组内极值，custom=自定义。" }, "value": { "type": "number", "description": "当 type='custom' 时生效的具体数值。" } }, "required": [ "type" ] }, "extremum_min": { "type": "object", "description": "最小极值配置，包含极值类型、极值。", "properties": { "type": { "type": "string", "enum": [ "individual", "group", "custom" ], "description": "极值类型：individual=单个迷你图极值，group=同组内极值，custom=自定义。" }, "value": { "type": "number", "description": "当 type='custom' 时生效的具体数值。" } }, "required": [ "type" ] } } }, "sparklines": { "type": "array", "description": "迷你图项列表。create 时为待创建项（每项需 position + source/source_range）；update 时为待变更/新增项（每项需 sparkline_id；upsert=true 新增时需 position + source）；delete 时为待删除项（每项需 sparkline_id）。", "items": { "type": "object", "description": "单个迷你图项。", "properties": { "sparkline_id": { "type": "string", "description": "迷你图 reference_id。create 时可选（不传系统生成）；update / delete 时必填。" }, "position": { "type": "object", "description": "迷你图位置。create / update 时必填；delete 时省略。", "properties": { "row": { "type": "number", "minimum": 0, "description": "行索引（0-based）" }, "col": { "type": "string", "description": "列索引，例如 \"A\"、\"B\"" } }, "required": [ "row", "col" ] }, "source": { "type": "string", "description": "A1 范围字符串，表示数据来源，例如 \"Sheet1!A2:A10\"。create 必填（与 source_range 二选一）；update 仅在改源时传；delete 时省略。" }, "source_range": { "type": "object", "description": "结构化数据源范围（与 source 等价）。", "properties": { "range": { "type": "string", "description": "数据源的 A1 引用区域" } }, "required": [ "range" ] } } } } } } }, "+sparkline-update": { "properties": { "description": "创建/更新/部分删除的迷你图属性。delete 时不传 sparklines 即删整组，传则删指定项。", "type": "object", "properties": { "config": { "type": "object", "description": "迷你图样式配置, 相同 groupId 的迷你图共享相同的样式。", "properties": { "theme_type": { "type": "string", "enum": [ "pro", "light", "soft", "brand", "fresh" ], "description": "主题类型：pro、light、soft、brand、fresh。" }, "non_num_show_as": { "type": "string", "enum": [ "zero", "gap", "average" ], "description": "非数字单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。" }, "empty_show_as": { "type": "string", "enum": [ "zero", "gap", "average" ], "description": "空单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。" }, "contain_hidden_cells": { "type": "boolean", "description": "隐藏的单元格数据是否参与绘制。" }, "series_color": { "type": "string", "description": "主系列颜色，例如 \"#4472C4\"。" }, "points": { "type": "object", "description": "特殊点样式配置，包含高点、低点、标记点、首点、尾点、负点。", "properties": { "last_point": { "type": "object", "description": "尾点配置，最后一个数据点的样式。", "properties": { "color": { "type": "string", "description": "点的颜色。" }, "visible": { "type": "boolean", "description": "是否显示该点。" } } }, "negative_point": { "type": "object", "description": "负点配置，负数点的样式。", "properties": { "color": { "type": "string", "description": "点的颜色。" }, "visible": { "type": "boolean", "description": "是否显示该点。" } } }, "markers_point": { "type": "object", "description": "标记点配置，所有标记点的样式。", "properties": { "color": { "type": "string", "description": "点的颜色。" }, "visible": { "type": "boolean", "description": "是否显示该点。" } } }, "first_point": { "type": "object", "description": "首点配置，第一个数据点的样式。", "properties": { "color": { "type": "string", "description": "点的颜色。" }, "visible": { "type": "boolean", "description": "是否显示该点。" } } }, "high_point": { "type": "object", "description": "高点配置，最高点的样式。", "properties": { "color": { "type": "string", "description": "点的颜色。" }, "visible": { "type": "boolean", "description": "是否显示该点。" } } }, "low_point": { "type": "object", "description": "低点配置，最低点的样式。", "properties": { "color": { "type": "string", "description": "点的颜色。" }, "visible": { "type": "boolean", "description": "是否显示该点。" } } } } }, "line_width": { "type": "number", "enum": [ 1, 2, 3, 4 ], "description": "折线图线宽，可选值：1=1px，2=2px，3=3px，4=4px。" }, "type": { "type": "string", "enum": [ "line", "column", "win_loss" ], "description": "迷你图类型，可选值：line=折线图，column=柱形图，win_loss=盈亏图。" }, "axis": { "type": "object", "description": "坐标轴配置，包含坐标轴颜色、是否翻转、是否显示坐标轴。", "properties": { "color": { "type": "string", "description": "坐标轴颜色。" }, "reverse": { "type": "boolean", "description": "是否翻转坐标轴方向。" }, "visible": { "type": "boolean", "description": "是否显示坐标轴。" } } }, "show_gradient": { "type": "boolean", "description": "是否显示渐变效果。" }, "show_radius": { "type": "boolean", "description": "是否显示圆角，仅对柱形图和盈亏图生效。" }, "extremum_max": { "type": "object", "description": "最大极值配置，包含极值类型、极值。", "properties": { "type": { "type": "string", "enum": [ "individual", "group", "custom" ], "description": "极值类型，可选值：individual=单个迷你图极值，group=同组内极值，custom=自定义。" }, "value": { "type": "number", "description": "当 type='custom' 时生效的具体数值。" } }, "required": [ "type" ] }, "extremum_min": { "type": "object", "description": "最小极值配置，包含极值类型、极值。", "properties": { "type": { "type": "string", "enum": [ "individual", "group", "custom" ], "description": "极值类型：individual=单个迷你图极值，group=同组内极值，custom=自定义。" }, "value": { "type": "number", "description": "当 type='custom' 时生效的具体数值。" } }, "required": [ "type" ] } } }, "sparklines": { "type": "array", "description": "迷你图项列表。create 时为待创建项（每项需 position + source/source_range）；update 时为待变更/新增项（每项需 sparkline_id；upsert=true 新增时需 position + source）；delete 时为待删除项（每项需 sparkline_id）。", "items": { "type": "object", "description": "单个迷你图项。", "properties": { "sparkline_id": { "type": "string", "description": "迷你图 reference_id。create 时可选（不传系统生成）；update / delete 时必填。" }, "position": { "type": "object", "description": "迷你图位置。create / update 时必填；delete 时省略。", "properties": { "row": { "type": "number", "minimum": 0, "description": "行索引（0-based）" }, "col": { "type": "string", "description": "列索引，例如 \"A\"、\"B\"" } }, "required": [ "row", "col" ] }, "source": { "type": "string", "description": "A1 范围字符串，表示数据来源，例如 \"Sheet1!A2:A10\"。create 必填（与 source_range 二选一）；update 仅在改源时传；delete 时省略。" }, "source_range": { "type": "object", "description": "结构化数据源范围（与 source 等价）。", "properties": { "range": { "type": "string", "description": "数据源的 A1 引用区域" } }, "required": [ "range" ] } } } } } } }, "+table-put": { "sheets": { "type": "array", "minItems": 1, "description": "一个或多个子表的 typed 数据，每个数组元素写入一张子表；支持多 DataFrame → 多子表一次写入。每个数组项的形状对齐 pandas `df.to_json(orient=\"split\")`：列名走 `columns`、二维取值走 `data`、每列的 pandas dtype 走 `dtypes`、可选的展示格式走 `formats`，并显式带上目标子表名 `name`。pandas 来源直接用 `scripts/sheets_df.py` 的 `df_to_sheet(df, name)` 生成一项，再把 list 包到 `{\"sheets\":[...]}`。", "items": { "type": "object", "required": [ "name", "columns", "data" ], "properties": { "name": { "type": "string", "description": "目标子表名。按名匹配已有子表；不存在则新建该子表。同一次调用内子表名不可重复。" }, "start_cell": { "type": "string", "default": "A1", "description": "写入起点单元格（A1 记法，如 \"B2\"），默认 \"A1\"。mode=append 时忽略其行号、仅沿用其列。" }, "mode": { "type": "string", "enum": [ "overwrite", "append" ], "default": "overwrite", "description": "overwrite（默认）：从 start_cell 起写「表头 + 数据」块；append：把数据追加到子表已有数据下方（默认不重复表头）。" }, "header": { "type": "boolean", "description": "是否写一行列名表头。省略时按 mode 取默认:overwrite→true、append→false（避免在已有表头下重复）；显式给值可覆盖。" }, "allow_overwrite": { "type": "boolean", "default": true, "description": "为 false 时，若写入会落在非空单元格则拒写以保护原数据（返回 partial_success）。默认 true。" }, "columns": { "type": "array", "minItems": 1, "description": "列名字符串数组，顺序与 `data` 中每行取值一一对应。同一子表内列名不可重复。", "items": { "type": "string" } }, "data": { "type": "array", "description": "数据行；每行是一个数组，长度必须等于 `columns` 数。元素按 `dtypes` 推得的列类型取值（date 列写 ISO yyyy-mm-dd 字符串、number 列写数值、bool 列写布尔、其余写文本），null 表示空单元格。", "items": { "type": "array", "items": { "type": [ "string", "number", "boolean", "null" ], "description": "单元格值：date→ISO yyyy-mm-dd 字符串；number→数值（json.Number 精度保留）；bool→布尔；string→文本；null→空单元格。" } } }, "dtypes": { "type": "object", "description": "可选。列名 → pandas dtype 字符串的映射；缺失项默认按 object（string + 文本格式 `@`）处理，所以省略整段时整张表按文本写入（导入 CSV-shaped 数据的最简形态）。dtype 解析规则：`int*` / `uint*` / `Int*` / `UInt*` / `float*` / `Float*` / `complex*` → number（精度保留），`bool` / `boolean` → bool，`datetime64[ns]` / 含时区的 `datetime64[ns, UTC]` 等 → date（默认 `yyyy-mm-dd` 格式），`object` / `string` / `category` / 未识别 → string + 文本格式 `@`（数字样字符串如「00123」不会塌缩成数字）。", "additionalProperties": { "type": "string" } }, "formats": { "type": "object", "description": "可选。列名 → Excel number_format 字符串的映射，覆盖 dtype 自带的默认格式（金额 `#,##0.00`、百分比 `0.0%`、自定义日期 `yyyy-mm` 等）。percent 列的数值尺度由调用方负责（0.0469 配 `0.00%` 显示 4.69%）。", "additionalProperties": { "type": "string" } } } } }, "styles": { "items": { "properties": { "cell_merges": { "description": "单元格合并操作数组；range 使用 A1 单元格范围，merge_type 默认 all。", "items": { "properties": { "merge_type": { "enum": [ "all", "rows", "columns" ], "type": "string" }, "range": { "type": "string" } }, "required": [ "range" ], "type": "object" }, "type": "array" }, "cell_styles": { "description": "单元格样式操作数组；每项用 A1 单元格 range 指定范围，字段名与 +cells-set-style 对齐。", "items": { "properties": { "background_color": { "type": "string" }, "border_styles": { "type": "object", "description": "边框配置，结构同 +cells-set-style --border-styles。", "properties": { "bottom": { "properties": { "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "enum": [ "solid", "dashed", "dotted", "double", "none" ], "type": "string" }, "weight": { "description": "边框粗细/线宽", "enum": [ "thin", "medium", "thick" ], "type": "string" } }, "type": "object" }, "left": { "properties": { "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "enum": [ "solid", "dashed", "dotted", "double", "none" ], "type": "string" }, "weight": { "description": "边框粗细/线宽", "enum": [ "thin", "medium", "thick" ], "type": "string" } }, "type": "object" }, "right": { "properties": { "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "enum": [ "solid", "dashed", "dotted", "double", "none" ], "type": "string" }, "weight": { "description": "边框粗细/线宽", "enum": [ "thin", "medium", "thick" ], "type": "string" } }, "type": "object" }, "top": { "properties": { "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "enum": [ "solid", "dashed", "dotted", "double", "none" ], "type": "string" }, "weight": { "description": "边框粗细/线宽", "enum": [ "thin", "medium", "thick" ], "type": "string" } }, "type": "object" } } }, "font_color": { "type": "string" }, "font_line": { "enum": [ "none", "underline", "line-through" ], "type": "string" }, "font_size": { "type": "number" }, "font_style": { "enum": [ "normal", "italic" ], "type": "string" }, "font_weight": { "enum": [ "normal", "bold" ], "type": "string" }, "horizontal_alignment": { "enum": [ "left", "center", "right" ], "type": "string" }, "number_format": { "type": "string" }, "range": { "description": "A1 单元格范围，必须落在该子表本次写入区域内；例如 A1:B1、B2。", "type": "string" }, "vertical_alignment": { "enum": [ "top", "middle", "bottom" ], "type": "string" }, "word_wrap": { "enum": [ "overflow", "auto-wrap", "word-clip" ], "type": "string" } }, "required": [ "range" ], "type": "object" }, "type": "array" }, "col_sizes": { "description": "列宽操作数组；range 使用列范围如 A:C，type 为 pixel/standard，pixel 需要 size。", "items": { "properties": { "range": { "type": "string" }, "size": { "type": "number" }, "type": { "enum": [ "pixel", "standard" ], "type": "string" } }, "required": [ "range", "type" ], "type": "object" }, "type": "array" }, "name": { "description": "子表名。--sheets 模式下必须与同位置 --sheets.sheets[].name 一致；--values 模式下建议写 Sheet1（其 name 会被忽略）。", "type": "string" }, "row_sizes": { "description": "行高操作数组；range 使用行范围如 1:3，type 为 pixel/standard/auto，pixel 需要 size。", "items": { "properties": { "range": { "type": "string" }, "size": { "type": "number" }, "type": { "enum": [ "pixel", "standard", "auto" ], "type": "string" } }, "required": [ "range", "type" ], "type": "object" }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "type": "array" } }, "+workbook-create": { "sheets": { "type": "array", "minItems": 1, "description": "一个或多个子表的 typed 数据，每个数组元素写入一张子表；支持多 DataFrame → 多子表一次写入。每个数组项的形状对齐 pandas `df.to_json(orient=\"split\")`：列名走 `columns`、二维取值走 `data`、每列的 pandas dtype 走 `dtypes`、可选的展示格式走 `formats`，并显式带上目标子表名 `name`。pandas 来源直接用 `scripts/sheets_df.py` 的 `df_to_sheet(df, name)` 生成一项，再把 list 包到 `{\"sheets\":[...]}`。", "items": { "type": "object", "required": [ "name", "columns", "data" ], "properties": { "name": { "type": "string", "description": "目标子表名。按名匹配已有子表；不存在则新建该子表。同一次调用内子表名不可重复。" }, "start_cell": { "type": "string", "default": "A1", "description": "写入起点单元格（A1 记法，如 \"B2\"），默认 \"A1\"。mode=append 时忽略其行号、仅沿用其列。" }, "mode": { "type": "string", "enum": [ "overwrite", "append" ], "default": "overwrite", "description": "overwrite（默认）：从 start_cell 起写「表头 + 数据」块；append：把数据追加到子表已有数据下方（默认不重复表头）。" }, "header": { "type": "boolean", "description": "是否写一行列名表头。省略时按 mode 取默认:overwrite→true、append→false（避免在已有表头下重复）；显式给值可覆盖。" }, "allow_overwrite": { "type": "boolean", "default": true, "description": "为 false 时，若写入会落在非空单元格则拒写以保护原数据（返回 partial_success）。默认 true。" }, "columns": { "type": "array", "minItems": 1, "description": "列名字符串数组，顺序与 `data` 中每行取值一一对应。同一子表内列名不可重复。", "items": { "type": "string" } }, "data": { "type": "array", "description": "数据行；每行是一个数组，长度必须等于 `columns` 数。元素按 `dtypes` 推得的列类型取值（date 列写 ISO yyyy-mm-dd 字符串、number 列写数值、bool 列写布尔、其余写文本），null 表示空单元格。", "items": { "type": "array", "items": { "type": [ "string", "number", "boolean", "null" ], "description": "单元格值：date→ISO yyyy-mm-dd 字符串；number→数值（json.Number 精度保留）；bool→布尔；string→文本；null→空单元格。" } } }, "dtypes": { "type": "object", "description": "可选。列名 → pandas dtype 字符串的映射；缺失项默认按 object（string + 文本格式 `@`）处理，所以省略整段时整张表按文本写入（导入 CSV-shaped 数据的最简形态）。dtype 解析规则：`int*` / `uint*` / `Int*` / `UInt*` / `float*` / `Float*` / `complex*` → number（精度保留），`bool` / `boolean` → bool，`datetime64[ns]` / 含时区的 `datetime64[ns, UTC]` 等 → date（默认 `yyyy-mm-dd` 格式），`object` / `string` / `category` / 未识别 → string + 文本格式 `@`（数字样字符串如「00123」不会塌缩成数字）。", "additionalProperties": { "type": "string" } }, "formats": { "type": "object", "description": "可选。列名 → Excel number_format 字符串的映射，覆盖 dtype 自带的默认格式（金额 `#,##0.00`、百分比 `0.0%`、自定义日期 `yyyy-mm` 等）。percent 列的数值尺度由调用方负责（0.0469 配 `0.00%` 显示 4.69%）。", "additionalProperties": { "type": "string" } } } } }, "styles": { "items": { "properties": { "cell_merges": { "description": "单元格合并操作数组；range 使用 A1 单元格范围，merge_type 默认 all。", "items": { "properties": { "merge_type": { "enum": [ "all", "rows", "columns" ], "type": "string" }, "range": { "type": "string" } }, "required": [ "range" ], "type": "object" }, "type": "array" }, "cell_styles": { "description": "单元格样式操作数组；每项用 A1 单元格 range 指定范围，字段名与 +cells-set-style 对齐。", "items": { "properties": { "background_color": { "type": "string" }, "border_styles": { "type": "object", "description": "边框配置，结构同 +cells-set-style --border-styles。", "properties": { "bottom": { "properties": { "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "enum": [ "solid", "dashed", "dotted", "double", "none" ], "type": "string" }, "weight": { "description": "边框粗细/线宽", "enum": [ "thin", "medium", "thick" ], "type": "string" } }, "type": "object" }, "left": { "properties": { "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "enum": [ "solid", "dashed", "dotted", "double", "none" ], "type": "string" }, "weight": { "description": "边框粗细/线宽", "enum": [ "thin", "medium", "thick" ], "type": "string" } }, "type": "object" }, "right": { "properties": { "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "enum": [ "solid", "dashed", "dotted", "double", "none" ], "type": "string" }, "weight": { "description": "边框粗细/线宽", "enum": [ "thin", "medium", "thick" ], "type": "string" } }, "type": "object" }, "top": { "properties": { "color": { "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", "enum": [ "solid", "dashed", "dotted", "double", "none" ], "type": "string" }, "weight": { "description": "边框粗细/线宽", "enum": [ "thin", "medium", "thick" ], "type": "string" } }, "type": "object" } } }, "font_color": { "type": "string" }, "font_line": { "enum": [ "none", "underline", "line-through" ], "type": "string" }, "font_size": { "type": "number" }, "font_style": { "enum": [ "normal", "italic" ], "type": "string" }, "font_weight": { "enum": [ "normal", "bold" ], "type": "string" }, "horizontal_alignment": { "enum": [ "left", "center", "right" ], "type": "string" }, "number_format": { "type": "string" }, "range": { "description": "A1 单元格范围，必须落在该子表本次写入区域内；例如 A1:B1、B2。", "type": "string" }, "vertical_alignment": { "enum": [ "top", "middle", "bottom" ], "type": "string" }, "word_wrap": { "enum": [ "overflow", "auto-wrap", "word-clip" ], "type": "string" } }, "required": [ "range" ], "type": "object" }, "type": "array" }, "col_sizes": { "description": "列宽操作数组；range 使用列范围如 A:C，type 为 pixel/standard，pixel 需要 size。", "items": { "properties": { "range": { "type": "string" }, "size": { "type": "number" }, "type": { "enum": [ "pixel", "standard" ], "type": "string" } }, "required": [ "range", "type" ], "type": "object" }, "type": "array" }, "name": { "description": "子表名。--sheets 模式下必须与同位置 --sheets.sheets[].name 一致；--values 模式下建议写 Sheet1（其 name 会被忽略）。", "type": "string" }, "row_sizes": { "description": "行高操作数组；range 使用行范围如 1:3，type 为 pixel/standard/auto，pixel 需要 size。", "items": { "properties": { "range": { "type": "string" }, "size": { "type": "number" }, "type": { "enum": [ "pixel", "standard", "auto" ], "type": "string" } }, "required": [ "range", "type" ], "type": "object" }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "type": "array" } } } }