From 556b2292c703631d9d9548726bb17e045b42e2bd Mon Sep 17 00:00:00 2001 From: zhengzhijie Date: Fri, 22 May 2026 11:37:35 +0800 Subject: [PATCH 01/11] fix(sheets): align +workbook-create, +dropdown-*, +dim-move, +range-sort with server schema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Five separate E2E failures in shortcuts/sheets/ that all trace back to a CLI ↔ server contract mismatch. Each is independently scoped; bundling them because they share the test-report citation and the same one-line fix shape in most cases. buildInitialFillInput sent {"sheet_id": ""} on the secondary set_cell_range call after creating the workbook. The empty value was a holdover from "...otherwise server picks first sheet" — but set_cell_range rejects an empty selector with "sheet_id or sheet_name is required" rather than falling back to the default sheet. Use sheet_name "Sheet1" instead. POST /sheets/v3/spreadsheets always creates that sheet on workbook creation, and set_cell_range accepts sheet_name as an equivalent selector — saves an extra get_workbook_structure round-trip just to learn the auto-generated id. buildDropdownValidation emitted four fields that don't exist in the canonical set_cell_range.data_validation schema: - "values" (options list) → renamed to "items" - "multiple_values" → renamed to "support_multiple_values" - "colors" (per-option color) → removed (not in schema; flag also removed from data/flag-defs.json for +dropdown-set / -update) - "highlight_options" → removed (not in schema; flag also removed) The canonical schema lives at sheet-skill-spec/canonical-spec/tool- schemas/mcp-tools.json (set_cell_range tool, data_validation property); the colors / highlight knobs were CLI inventions the server never accepted, so removing the flags is correct (renaming would leave the flags broken). Skill reference docs (write-cells.md, batch-update.md) synced. validateDropdownOptionsColors lost its colors check; renamed to validateDropdownOptions to reflect the narrower contract. dropdownGetInput sent "Sheet1!C2:C6" verbatim as a ranges[] entry. get_cell_ranges expects sheet_id / sheet_name as separate fields and ranges entries without the sheet prefix; the server bounced with "sheet not found, sheetId:" (empty). Use the existing splitSheetPrefixedRange helper (declared in lark_sheet_batch_update.go) to break "Sheet1!C2:C6" into ("Sheet1", "C2:C6"), then thread the sheet name through sheetSelectorForToolInput exactly like +cells-get does. The shortcut was POSTing to /sheets/v2/spreadsheets/{token}/dimension_ range, which is the v2 insert-dimension endpoint and requires a top- level {"dimension": {...}} body. Move uses a separate endpoint: POST /sheets/v2/spreadsheets/{token}/move_dimension body: { "source": {...}, "destination_index": N } (camelCase "destinationIndex" → snake_case "destination_index" to match the v2 contract.) Both DryRun and Execute updated, plus the TestDimMove_DryRun and TestExecute_DimMove assertions. transform_range.sort_conditions[i] requires both `column` (string) and `ascending` (bool); rangeSortInput passed the --sort-keys array through to the server unvalidated, so missing fields surfaced as opaque "required property X missing" errors with no per-item context. Walk the parsed array client-side, reject with item-pointing messages. Test fixtures and a contract-test fixture switched from the historical {col, order} vocabulary (which the server has never accepted) to the correct {column, ascending}. Server-schema citations and test-report case mapping in this branch's plan file. --- shortcuts/sheets/batch_op_contract_test.go | 4 +- shortcuts/sheets/data/flag-defs.json | 36 --------------- shortcuts/sheets/helpers.go | 2 +- shortcuts/sheets/lark_sheet_batch_update.go | 2 +- .../sheets/lark_sheet_batch_update_test.go | 8 +++- .../sheets/lark_sheet_range_operations.go | 17 +++++++ .../lark_sheet_range_operations_test.go | 41 +++++++++++++++-- shortcuts/sheets/lark_sheet_read_data.go | 17 +++++-- shortcuts/sheets/lark_sheet_read_data_test.go | 3 +- shortcuts/sheets/lark_sheet_workbook_test.go | 9 ++++ shortcuts/sheets/lark_sheet_write_cells.go | 44 ++++++------------- .../sheets/lark_sheet_write_cells_test.go | 13 ++++-- .../references/lark-sheets-batch-update.md | 2 - .../references/lark-sheets-write-cells.md | 2 - 14 files changed, 113 insertions(+), 87 deletions(-) diff --git a/shortcuts/sheets/batch_op_contract_test.go b/shortcuts/sheets/batch_op_contract_test.go index 3f178006f..58d1d7847 100644 --- a/shortcuts/sheets/batch_op_contract_test.go +++ b/shortcuts/sheets/batch_op_contract_test.go @@ -132,8 +132,8 @@ func TestBatchOp_BodyMatchesStandalone(t *testing.T) { { shortcut: "+range-sort", sc: RangeSort, - args: []string{"--sheet-id", "sh1", "--range", "A1:D10", "--sort-keys", `[{"col":"B","order":"asc"}]`, "--has-header"}, - subInput: `{"sheet-id":"sh1","range":"A1:D10","sort-keys":[{"col":"B","order":"asc"}],"has-header":true}`, + args: []string{"--sheet-id", "sh1", "--range", "A1:D10", "--sort-keys", `[{"column":"B","ascending":true}]`, "--has-header"}, + subInput: `{"sheet-id":"sh1","range":"A1:D10","sort-keys":[{"column":"B","ascending":true}],"has-header":true}`, }, { shortcut: "+sheet-create", diff --git a/shortcuts/sheets/data/flag-defs.json b/shortcuts/sheets/data/flag-defs.json index d8687e227..b1000009e 100644 --- a/shortcuts/sheets/data/flag-defs.json +++ b/shortcuts/sheets/data/flag-defs.json @@ -1874,17 +1874,6 @@ "stdin" ] }, - { - "name": "colors", - "kind": "own", - "type": "string", - "required": "optional", - "desc": "RGB hex color array (e.g. `[\"#1FB6C1\",\"#F006C2\"]`); length must equal `--options`", - "input": [ - "file", - "stdin" - ] - }, { "name": "multiple", "kind": "own", @@ -1892,13 +1881,6 @@ "required": "optional", "desc": "Enable multi-select; default `false`" }, - { - "name": "highlight", - "kind": "own", - "type": "bool", - "required": "optional", - "desc": "Color-highlight options; default `false`" - }, { "name": "dry-run", "kind": "system", @@ -2802,17 +2784,6 @@ "stdin" ] }, - { - "name": "colors", - "kind": "own", - "type": "string", - "required": "optional", - "desc": "Color array (same length as `--options`)", - "input": [ - "file", - "stdin" - ] - }, { "name": "multiple", "kind": "own", @@ -2820,13 +2791,6 @@ "required": "optional", "desc": "Enable multi-select" }, - { - "name": "highlight", - "kind": "own", - "type": "bool", - "required": "optional", - "desc": "Color-highlight options" - }, { "name": "dry-run", "kind": "system", diff --git a/shortcuts/sheets/helpers.go b/shortcuts/sheets/helpers.go index 64206b9e2..79b7223a3 100644 --- a/shortcuts/sheets/helpers.go +++ b/shortcuts/sheets/helpers.go @@ -156,7 +156,7 @@ func sheetSelectorPlaceholder(sheetID, sheetName string) string { // parseJSONFlag parses a JSON string from a flag value. Returns nil when the // flag is empty (caller decides if that's acceptable). Used by --data / -// --style / --options / --ranges / --colors and friends. +// --style / --options / --ranges / --properties and friends. func parseJSONFlag(runtime flagView, name string) (interface{}, error) { raw := strings.TrimSpace(runtime.Str(name)) if raw == "" { diff --git a/shortcuts/sheets/lark_sheet_batch_update.go b/shortcuts/sheets/lark_sheet_batch_update.go index d6591bb52..abf51868c 100644 --- a/shortcuts/sheets/lark_sheet_batch_update.go +++ b/shortcuts/sheets/lark_sheet_batch_update.go @@ -332,7 +332,7 @@ var DropdownUpdate = common.Shortcut{ if _, err := validateDropdownRanges(runtime); err != nil { return err } - if _, err := validateDropdownOptionsColors(runtime); err != nil { + if _, err := validateDropdownOptions(runtime); err != nil { return err } return nil diff --git a/shortcuts/sheets/lark_sheet_batch_update_test.go b/shortcuts/sheets/lark_sheet_batch_update_test.go index 26220ff2a..e7885ab5c 100644 --- a/shortcuts/sheets/lark_sheet_batch_update_test.go +++ b/shortcuts/sheets/lark_sheet_batch_update_test.go @@ -215,8 +215,12 @@ func TestDropdownUpdate_BatchPayload(t *testing.T) { if dv == nil || dv["type"] != "list" { t.Errorf("op[%d] missing data_validation list: %#v", i, cell) } - if dv["multiple_values"] != true { - t.Errorf("op[%d] multiple_values = %v, want true", i, dv["multiple_values"]) + items, _ := dv["items"].([]interface{}) + if len(items) != 3 { + t.Errorf("op[%d] data_validation.items length = %d, want 3", i, len(items)) + } + if dv["support_multiple_values"] != true { + t.Errorf("op[%d] support_multiple_values = %v, want true", i, dv["support_multiple_values"]) } } } diff --git a/shortcuts/sheets/lark_sheet_range_operations.go b/shortcuts/sheets/lark_sheet_range_operations.go index e30b9666c..2e00c11d5 100644 --- a/shortcuts/sheets/lark_sheet_range_operations.go +++ b/shortcuts/sheets/lark_sheet_range_operations.go @@ -598,6 +598,23 @@ func rangeSortInput(runtime flagView, token, sheetID, sheetName string) (map[str if err != nil { return nil, err } + // transform_range.sort_conditions[i] requires both `column` (string) + // and `ascending` (bool); the server's own validation surfaces a + // terse "required property X is missing" with no per-item context. + // Pre-check here so the user sees which entry is malformed. + for i, raw := range keys { + item, ok := raw.(map[string]interface{}) + if !ok { + return nil, common.FlagErrorf("--sort-keys[%d] must be an object {column, ascending}; got %T", i, raw) + } + col, _ := item["column"].(string) + if strings.TrimSpace(col) == "" { + return nil, common.FlagErrorf("--sort-keys[%d] missing required string field `column` (the column letter to sort by, e.g. \"C\")", i) + } + if _, ok := item["ascending"].(bool); !ok { + return nil, common.FlagErrorf("--sort-keys[%d] missing required bool field `ascending`", i) + } + } input := map[string]interface{}{ "excel_id": token, "operation": "sort", diff --git a/shortcuts/sheets/lark_sheet_range_operations_test.go b/shortcuts/sheets/lark_sheet_range_operations_test.go index 73930f697..8bc3c171d 100644 --- a/shortcuts/sheets/lark_sheet_range_operations_test.go +++ b/shortcuts/sheets/lark_sheet_range_operations_test.go @@ -185,7 +185,7 @@ func TestRangeOperationsShortcuts_DryRun(t *testing.T) { { name: "+range-sort multi-key with header", sc: RangeSort, - args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "A1:E100", "--has-header", "--sort-keys", `[{"col":"B","order":"asc"},{"col":"D","order":"desc"}]`}, + args: []string{"--url", testURL, "--sheet-id", testSheetID, "--range", "A1:E100", "--has-header", "--sort-keys", `[{"column":"B","ascending":true},{"column":"D","ascending":false}]`}, toolName: "transform_range", wantInput: map[string]interface{}{ "excel_id": testToken, @@ -194,8 +194,8 @@ func TestRangeOperationsShortcuts_DryRun(t *testing.T) { "range": "A1:E100", "has_header": true, "sort_conditions": []interface{}{ - map[string]interface{}{"col": "B", "order": "asc"}, - map[string]interface{}{"col": "D", "order": "desc"}, + map[string]interface{}{"column": "B", "ascending": true}, + map[string]interface{}{"column": "D", "ascending": false}, }, }, }, @@ -211,6 +211,41 @@ func TestRangeOperationsShortcuts_DryRun(t *testing.T) { } } +// TestRangeSort_RejectsMalformedKeys verifies the pre-check that each +// --sort-keys entry has both `column` (string) and `ascending` (bool); +// previously the CLI passed any JSON through and the server bounced +// with a terse "required property X missing" that didn't name the bad +// entry. +func TestRangeSort_RejectsMalformedKeys(t *testing.T) { + t.Parallel() + cases := []struct { + name string + keys string + want string + }{ + {"missing column", `[{"ascending":true}]`, "missing required string field `column`"}, + {"missing ascending", `[{"column":"B"}]`, "missing required bool field `ascending`"}, + {"old vocab col/order", `[{"col":"B","order":"asc"}]`, "missing required string field `column`"}, + {"non-object item", `["B"]`, "must be an object"}, + } + for _, c := range cases { + c := c + t.Run(c.name, func(t *testing.T) { + t.Parallel() + stdout, stderr, err := runShortcutCapturingErr(t, RangeSort, []string{ + "--url", testURL, "--sheet-id", testSheetID, + "--range", "A1:E10", "--sort-keys", c.keys, "--dry-run", + }) + if err == nil { + t.Fatalf("expected validation error; stdout=%s stderr=%s", stdout, stderr) + } + if !strings.Contains(stdout+stderr+err.Error(), c.want) { + t.Errorf("want substring %q in error; got stdout=%s stderr=%s err=%v", c.want, stdout, stderr, err) + } + }) + } +} + func TestResize_TypeAndSizeGuards(t *testing.T) { t.Parallel() cases := []struct { diff --git a/shortcuts/sheets/lark_sheet_read_data.go b/shortcuts/sheets/lark_sheet_read_data.go index 7c036ac3e..89a4b49db 100644 --- a/shortcuts/sheets/lark_sheet_read_data.go +++ b/shortcuts/sheets/lark_sheet_read_data.go @@ -215,8 +215,12 @@ func stripRowPrefixFromCsvOutput(out interface{}) interface{} { } // DropdownGet wraps get_cell_ranges scoped to data_validation: read the -// dropdown configuration on a range. The range carries its own sheet prefix -// (e.g. "sheet1!A2:A100"), so no separate --sheet-id / --sheet-name is needed. +// dropdown configuration on a range. The CLI accepts the range in the +// sheet-prefixed form (e.g. "sheet1!A2:A100") for convenience; the +// prefix is split client-side into sheet_name + bare A1 because the +// get_cell_ranges tool wants sheet selector and ranges as separate +// fields (ranges with the "sheet!" prefix gets the empty-sheet_id +// rejection from the server). var DropdownGet = common.Shortcut{ Service: "sheets", Command: "+dropdown-get", @@ -257,10 +261,15 @@ var DropdownGet = common.Shortcut{ } func dropdownGetInput(runtime *common.RuntimeContext, token string) map[string]interface{} { - return map[string]interface{}{ + // Validate already enforced the "Sheet!range" prefix, so the + // split error path can't be reached here in practice. + sheetName, bareRange, _ := splitSheetPrefixedRange(strings.TrimSpace(runtime.Str("range"))) + input := map[string]interface{}{ "excel_id": token, - "ranges": []string{strings.TrimSpace(runtime.Str("range"))}, + "ranges": []string{bareRange}, "include_styles": false, "value_render_option": "formatted_value", } + sheetSelectorForToolInput(input, "", sheetName) + return input } diff --git a/shortcuts/sheets/lark_sheet_read_data_test.go b/shortcuts/sheets/lark_sheet_read_data_test.go index 30a9a1a55..78233f795 100644 --- a/shortcuts/sheets/lark_sheet_read_data_test.go +++ b/shortcuts/sheets/lark_sheet_read_data_test.go @@ -54,7 +54,8 @@ func TestReadDataShortcuts_DryRun(t *testing.T) { toolName: "get_cell_ranges", wantInput: map[string]interface{}{ "excel_id": testToken, - "ranges": []interface{}{"sheet1!A2:A100"}, + "sheet_name": "sheet1", + "ranges": []interface{}{"A2:A100"}, "include_styles": false, "value_render_option": "formatted_value", }, diff --git a/shortcuts/sheets/lark_sheet_workbook_test.go b/shortcuts/sheets/lark_sheet_workbook_test.go index f7b257fc2..5298d41c0 100644 --- a/shortcuts/sheets/lark_sheet_workbook_test.go +++ b/shortcuts/sheets/lark_sheet_workbook_test.go @@ -317,6 +317,15 @@ func TestWorkbookCreate_DryRun(t *testing.T) { if input["range"] != "A1:B3" { t.Errorf("fill range = %v, want A1:B3 (1 header + 2 data rows × 2 cols)", input["range"]) } + // New workbook → fill targets the default sheet by name (no + // extra get_workbook_structure call is needed to learn the + // auto-generated sheet_id). + if input["sheet_name"] != "Sheet1" { + t.Errorf("fill sheet_name = %v, want Sheet1", input["sheet_name"]) + } + if _, hasID := input["sheet_id"]; hasID { + t.Errorf("fill sheet_id should be omitted (server rejects empty); got %v", input["sheet_id"]) + } }) } diff --git a/shortcuts/sheets/lark_sheet_write_cells.go b/shortcuts/sheets/lark_sheet_write_cells.go index 3693129de..671fd673d 100644 --- a/shortcuts/sheets/lark_sheet_write_cells.go +++ b/shortcuts/sheets/lark_sheet_write_cells.go @@ -331,52 +331,36 @@ func dropdownSetInput(runtime flagView, token, sheetID, sheetName string) (map[s // ─── shared dropdown helpers ────────────────────────────────────────── -// buildDropdownValidation packs --options / --colors / --multiple / --highlight -// into the data_validation block expected by set_cell_range. +// buildDropdownValidation packs --options / --multiple into the +// data_validation block expected by set_cell_range. Field names match +// the canonical schema: items (not values) for the option list, and +// support_multiple_values (not multiple_values) for multi-select. +// Earlier CLI builds also emitted `colors` and `highlight_options`, +// neither of which exists in the server schema for set_cell_range; both +// were rejected as "unexpected property". The --colors / --highlight +// flags have been removed; only --options + --multiple remain. func buildDropdownValidation(runtime flagView) (map[string]interface{}, error) { options, err := requireJSONArray(runtime, "options") if err != nil { return nil, err } dv := map[string]interface{}{ - "type": "list", - "values": options, - } - if runtime.Str("colors") != "" { - colors, err := requireJSONArray(runtime, "colors") - if err != nil { - return nil, err - } - if len(colors) != len(options) { - return nil, common.FlagErrorf("--colors length (%d) must equal --options length (%d)", len(colors), len(options)) - } - dv["colors"] = colors + "type": "list", + "items": options, } if runtime.Bool("multiple") { - dv["multiple_values"] = true - } - if runtime.Bool("highlight") { - dv["highlight_options"] = true + dv["support_multiple_values"] = true } return dv, nil } -// validateDropdownOptionsColors validates --options is a JSON array and that -// --colors (when set) has matching length. Used by +dropdown-update Validate. -func validateDropdownOptionsColors(runtime flagView) (int, error) { +// validateDropdownOptions checks that --options parses as a JSON array +// and returns its length so callers can size their cells matrix. +func validateDropdownOptions(runtime flagView) (int, error) { options, err := requireJSONArray(runtime, "options") if err != nil { return 0, err } - if runtime.Str("colors") != "" { - colors, err := requireJSONArray(runtime, "colors") - if err != nil { - return 0, err - } - if len(colors) != len(options) { - return 0, common.FlagErrorf("--colors length (%d) must equal --options length (%d)", len(colors), len(options)) - } - } return len(options), nil } diff --git a/shortcuts/sheets/lark_sheet_write_cells_test.go b/shortcuts/sheets/lark_sheet_write_cells_test.go index e9a0b289e..2e3543bb9 100644 --- a/shortcuts/sheets/lark_sheet_write_cells_test.go +++ b/shortcuts/sheets/lark_sheet_write_cells_test.go @@ -95,7 +95,7 @@ func TestWriteCellsShortcuts_DryRun(t *testing.T) { "--url", testURL, "--sheet-id", testSheetID, "--range", "A2:A4", "--options", `["a","b"]`, - "--multiple", "--highlight", + "--multiple", }, toolName: "set_cell_range", wantInput: map[string]interface{}{ @@ -143,8 +143,15 @@ func TestDropdownSet_CellsShape(t *testing.T) { if dv["type"] != "list" { t.Errorf("row %d data_validation.type = %v, want list", i, dv["type"]) } - if dv["multiple_values"] != true { - t.Errorf("row %d data_validation.multiple_values = %v, want true", i, dv["multiple_values"]) + items, _ := dv["items"].([]interface{}) + if len(items) != 2 || items[0] != "a" || items[1] != "b" { + t.Errorf("row %d data_validation.items = %#v, want [\"a\",\"b\"]", i, dv["items"]) + } + if dv["support_multiple_values"] != true { + t.Errorf("row %d data_validation.support_multiple_values = %v, want true", i, dv["support_multiple_values"]) + } + if _, hasLegacy := dv["multiple_values"]; hasLegacy { + t.Errorf("row %d data_validation should not emit legacy `multiple_values`", i) } } } diff --git a/skills/lark-sheets/references/lark-sheets-batch-update.md b/skills/lark-sheets/references/lark-sheets-batch-update.md index ba3160e0b..7b04905a1 100644 --- a/skills/lark-sheets/references/lark-sheets-batch-update.md +++ b/skills/lark-sheets/references/lark-sheets-batch-update.md @@ -70,9 +70,7 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_ | --- | --- | --- | --- | | `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（如 `["sheet1!A2:A100"]`），每项必须带 sheet 前缀 | | `--options` | string + File + Stdin（复合 JSON） | required | 选项 JSON 数组（如 `["opt1","opt2"]`） | -| `--colors` | string + File + Stdin（简单 JSON） | optional | 颜色数组（与 `--options` 等长） | | `--multiple` | bool | optional | 启用多选 | -| `--highlight` | bool | optional | 选项配色 | ### `+dropdown-delete` diff --git a/skills/lark-sheets/references/lark-sheets-write-cells.md b/skills/lark-sheets/references/lark-sheets-write-cells.md index 6e1887031..6ebe2b154 100644 --- a/skills/lark-sheets/references/lark-sheets-write-cells.md +++ b/skills/lark-sheets/references/lark-sheets-write-cells.md @@ -199,9 +199,7 @@ _公共四件套 · 系统：`--dry-run`_ | --- | --- | --- | --- | | `--range` | string | required | 目标范围（A1 格式，如 `A2:A100`） | | `--options` | string + File + Stdin（复合 JSON） | required | 选项 JSON 数组 `["opt1","opt2"]`；最多 500 项，每项 ≤100 字符，不含逗号 | -| `--colors` | string + File + Stdin（简单 JSON） | optional | RGB hex 颜色数组（如 `["#1FB6C1","#F006C2"]`），长度必须与 `--options` 一致 | | `--multiple` | bool | optional | 启用多选；默认 `false` | -| `--highlight` | bool | optional | 选项配色显示；默认 `false` | ### `+csv-put` From 5926e89ce33c2b9ccd7affc97f0b3fc206b9c4d4 Mon Sep 17 00:00:00 2001 From: zhengzhijie Date: Fri, 22 May 2026 11:42:36 +0800 Subject: [PATCH 02/11] =?UTF-8?q?revert(sheets):=20drop=20direct=20flag-de?= =?UTF-8?q?fs.json=20edits=20=E2=80=94=20generated=20from=20spec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit data/flag-defs.json is regenerated from the upstream sheet-skill-spec canonical-spec; editing it here gets clobbered on the next sync. The schema realignment for +dropdown-set / -update --colors / --highlight removal needs to land on the base table first, then flow back through sheet-skill-spec → larksuite-cli sync, not via a direct CLI-side edit. Restore the previous flag entries verbatim. The Go-side change in buildDropdownValidation still drops the wire fields, so: - users passing --colors / --highlight today see the flag accepted silently (no effect on the wire) until the upstream removal lands; - after upstream removal + sync, both the flag declarations and the Go-side handling will be in sync. Functional fixes (#1 workbook-create, #3 dropdown-get, #4 dim-move, #5 range-sort) and dropdown wire-shape rename (#2) are unaffected. --- shortcuts/sheets/data/flag-defs.json | 36 ++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/shortcuts/sheets/data/flag-defs.json b/shortcuts/sheets/data/flag-defs.json index b1000009e..d8687e227 100644 --- a/shortcuts/sheets/data/flag-defs.json +++ b/shortcuts/sheets/data/flag-defs.json @@ -1874,6 +1874,17 @@ "stdin" ] }, + { + "name": "colors", + "kind": "own", + "type": "string", + "required": "optional", + "desc": "RGB hex color array (e.g. `[\"#1FB6C1\",\"#F006C2\"]`); length must equal `--options`", + "input": [ + "file", + "stdin" + ] + }, { "name": "multiple", "kind": "own", @@ -1881,6 +1892,13 @@ "required": "optional", "desc": "Enable multi-select; default `false`" }, + { + "name": "highlight", + "kind": "own", + "type": "bool", + "required": "optional", + "desc": "Color-highlight options; default `false`" + }, { "name": "dry-run", "kind": "system", @@ -2784,6 +2802,17 @@ "stdin" ] }, + { + "name": "colors", + "kind": "own", + "type": "string", + "required": "optional", + "desc": "Color array (same length as `--options`)", + "input": [ + "file", + "stdin" + ] + }, { "name": "multiple", "kind": "own", @@ -2791,6 +2820,13 @@ "required": "optional", "desc": "Enable multi-select" }, + { + "name": "highlight", + "kind": "own", + "type": "bool", + "required": "optional", + "desc": "Color-highlight options" + }, { "name": "dry-run", "kind": "system", From 9d06652aa929f5f1c254570199f29c0b2ba7410b Mon Sep 17 00:00:00 2001 From: zhengzhijie Date: Fri, 22 May 2026 12:25:27 +0800 Subject: [PATCH 03/11] revert(sheets): drop direct edits to skills/lark-sheets/references/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These md files are sync targets generated from sheet-skill-spec; editing them here gets clobbered on the next sync, same as data/flag-defs.json. The --colors / --highlight row removals belong on the upstream base table → canonical-spec sync, not here. Restore the previous --colors / --highlight rows in both lark-sheets-write-cells.md (+dropdown-set) and lark-sheets-batch-update.md (+dropdown-update). The Go-side change in buildDropdownValidation still drops the wire fields, so: - users passing --colors / --highlight today see the flag accepted silently (no effect on the wire) until upstream removes the flag; - after upstream removal + sync, both flag declarations, ref docs, and Go-side handling will be in sync. Functional fixes (#1 workbook-create, #3 dropdown-get, #4 dim-move, #5 range-sort) and dropdown wire-shape rename (#2) are unaffected. --- skills/lark-sheets/references/lark-sheets-batch-update.md | 2 ++ skills/lark-sheets/references/lark-sheets-write-cells.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/skills/lark-sheets/references/lark-sheets-batch-update.md b/skills/lark-sheets/references/lark-sheets-batch-update.md index 7b04905a1..ba3160e0b 100644 --- a/skills/lark-sheets/references/lark-sheets-batch-update.md +++ b/skills/lark-sheets/references/lark-sheets-batch-update.md @@ -70,7 +70,9 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_ | --- | --- | --- | --- | | `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（如 `["sheet1!A2:A100"]`），每项必须带 sheet 前缀 | | `--options` | string + File + Stdin（复合 JSON） | required | 选项 JSON 数组（如 `["opt1","opt2"]`） | +| `--colors` | string + File + Stdin（简单 JSON） | optional | 颜色数组（与 `--options` 等长） | | `--multiple` | bool | optional | 启用多选 | +| `--highlight` | bool | optional | 选项配色 | ### `+dropdown-delete` diff --git a/skills/lark-sheets/references/lark-sheets-write-cells.md b/skills/lark-sheets/references/lark-sheets-write-cells.md index 6ebe2b154..6e1887031 100644 --- a/skills/lark-sheets/references/lark-sheets-write-cells.md +++ b/skills/lark-sheets/references/lark-sheets-write-cells.md @@ -199,7 +199,9 @@ _公共四件套 · 系统：`--dry-run`_ | --- | --- | --- | --- | | `--range` | string | required | 目标范围（A1 格式，如 `A2:A100`） | | `--options` | string + File + Stdin（复合 JSON） | required | 选项 JSON 数组 `["opt1","opt2"]`；最多 500 项，每项 ≤100 字符，不含逗号 | +| `--colors` | string + File + Stdin（简单 JSON） | optional | RGB hex 颜色数组（如 `["#1FB6C1","#F006C2"]`），长度必须与 `--options` 一致 | | `--multiple` | bool | optional | 启用多选；默认 `false` | +| `--highlight` | bool | optional | 选项配色显示；默认 `false` | ### `+csv-put` From 101c572d6489d42d5e86563d4490c6d9b644c37b Mon Sep 17 00:00:00 2001 From: zhengzhijie Date: Fri, 22 May 2026 15:41:57 +0800 Subject: [PATCH 04/11] =?UTF-8?q?docs(sheets):=20sync=20from=20sheet-skill?= =?UTF-8?q?-spec=20=E2=80=94=20remove=20dropdown=20--colors=20/=20--highli?= =?UTF-8?q?ght?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Upstream sheet-skill-spec base table deleted the --colors and --highlight flags on +dropdown-set / +dropdown-update (the corresponding wire fields data_validation.colors / .highlight_options were never accepted by the server schema; see prior fix in this branch). Re-running the sync from canonical-spec brings the CLI flag-defs and skill reference docs back in line with the Go-side handling that already drops these fields. Generated by `npm run sync:cli` in sheet-skill-spec @ ac7acef. --- shortcuts/sheets/data/flag-defs.json | 36 ------------------- .../references/lark-sheets-batch-update.md | 2 -- .../references/lark-sheets-write-cells.md | 2 -- 3 files changed, 40 deletions(-) diff --git a/shortcuts/sheets/data/flag-defs.json b/shortcuts/sheets/data/flag-defs.json index d8687e227..b1000009e 100644 --- a/shortcuts/sheets/data/flag-defs.json +++ b/shortcuts/sheets/data/flag-defs.json @@ -1874,17 +1874,6 @@ "stdin" ] }, - { - "name": "colors", - "kind": "own", - "type": "string", - "required": "optional", - "desc": "RGB hex color array (e.g. `[\"#1FB6C1\",\"#F006C2\"]`); length must equal `--options`", - "input": [ - "file", - "stdin" - ] - }, { "name": "multiple", "kind": "own", @@ -1892,13 +1881,6 @@ "required": "optional", "desc": "Enable multi-select; default `false`" }, - { - "name": "highlight", - "kind": "own", - "type": "bool", - "required": "optional", - "desc": "Color-highlight options; default `false`" - }, { "name": "dry-run", "kind": "system", @@ -2802,17 +2784,6 @@ "stdin" ] }, - { - "name": "colors", - "kind": "own", - "type": "string", - "required": "optional", - "desc": "Color array (same length as `--options`)", - "input": [ - "file", - "stdin" - ] - }, { "name": "multiple", "kind": "own", @@ -2820,13 +2791,6 @@ "required": "optional", "desc": "Enable multi-select" }, - { - "name": "highlight", - "kind": "own", - "type": "bool", - "required": "optional", - "desc": "Color-highlight options" - }, { "name": "dry-run", "kind": "system", diff --git a/skills/lark-sheets/references/lark-sheets-batch-update.md b/skills/lark-sheets/references/lark-sheets-batch-update.md index ba3160e0b..7b04905a1 100644 --- a/skills/lark-sheets/references/lark-sheets-batch-update.md +++ b/skills/lark-sheets/references/lark-sheets-batch-update.md @@ -70,9 +70,7 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_ | --- | --- | --- | --- | | `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（如 `["sheet1!A2:A100"]`），每项必须带 sheet 前缀 | | `--options` | string + File + Stdin（复合 JSON） | required | 选项 JSON 数组（如 `["opt1","opt2"]`） | -| `--colors` | string + File + Stdin（简单 JSON） | optional | 颜色数组（与 `--options` 等长） | | `--multiple` | bool | optional | 启用多选 | -| `--highlight` | bool | optional | 选项配色 | ### `+dropdown-delete` diff --git a/skills/lark-sheets/references/lark-sheets-write-cells.md b/skills/lark-sheets/references/lark-sheets-write-cells.md index 6e1887031..6ebe2b154 100644 --- a/skills/lark-sheets/references/lark-sheets-write-cells.md +++ b/skills/lark-sheets/references/lark-sheets-write-cells.md @@ -199,9 +199,7 @@ _公共四件套 · 系统：`--dry-run`_ | --- | --- | --- | --- | | `--range` | string | required | 目标范围（A1 格式，如 `A2:A100`） | | `--options` | string + File + Stdin（复合 JSON） | required | 选项 JSON 数组 `["opt1","opt2"]`；最多 500 项，每项 ≤100 字符，不含逗号 | -| `--colors` | string + File + Stdin（简单 JSON） | optional | RGB hex 颜色数组（如 `["#1FB6C1","#F006C2"]`），长度必须与 `--options` 一致 | | `--multiple` | bool | optional | 启用多选；默认 `false` | -| `--highlight` | bool | optional | 选项配色显示；默认 `false` | ### `+csv-put` From 96c338735ae7d23b277f76f616fb87e2a8e3742c Mon Sep 17 00:00:00 2001 From: zhengzhijie Date: Fri, 22 May 2026 18:06:50 +0800 Subject: [PATCH 05/11] fix(sheets): restore +dropdown --colors / --highlight, map to canonical fields MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reverses the --colors / --highlight removal from 7932ab2 (item #2 of the batch-1 schema-alignment commit). That commit dropped both flags after the test report flagged data_validation.colors / highlight_options as "unexpected property" — at the time the canonical set_cell_range.data_validation schema listed only help_text / items / operator / range / support_multiple_values / type / values, so the flags had no server-side target and the removal was correct. Since then, set_cell_range.data_validation has gained two fields explicitly modelling the dropdown highlight UI (mcp-tools.json in sheet-skill-spec 2026-05-22 base sync): enable_highlight (bool) — show pill backgrounds highlight_colors (string[]) — hex pill colors, length must match items So the flags are back, but rewired: --colors -> data_validation.highlight_colors (was: colors) --highlight -> data_validation.enable_highlight (was: highlight_options) --options -> items and --multiple -> support_multiple_values renames from 7932ab2 are kept. Changes: - buildDropdownValidation: re-add --colors / --highlight handling against the new field names; --colors length check stays inline (so dropdownSetInput Validate path catches it via validateViaInput, no separate guard needed). - validateDropdownOptions -> validateDropdownOptionsColors: restore the Validate-time --colors length check on +dropdown-update / +dropdown-delete (called from lark_sheet_batch_update.go). - TestDropdownSet_CellsShape: extend to assert highlight_colors / enable_highlight emitted; assert legacy `colors` / `highlight_options` absent. - TestDropdownSet_ColorsLengthMismatch: new — covers the early Validate error path. - TestDropdownUpdate_BatchPayload: extend to cover dropdownBatchInput propagation of --colors / --highlight through batch_update. - skills/lark-sheets/references/lark-sheets-{write-cells,batch-update}.md, shortcuts/sheets/data/flag-defs.json, flag-schemas.json: synced from sheet-skill-spec generate output (MR !7). --- shortcuts/sheets/data/flag-defs.json | 36 + shortcuts/sheets/data/flag-schemas.json | 7721 +++++++++-------- shortcuts/sheets/lark_sheet_batch_update.go | 2 +- .../sheets/lark_sheet_batch_update_test.go | 13 +- shortcuts/sheets/lark_sheet_write_cells.go | 47 +- .../sheets/lark_sheet_write_cells_test.go | 36 + .../references/lark-sheets-batch-update.md | 2 + .../references/lark-sheets-write-cells.md | 116 +- 8 files changed, 4057 insertions(+), 3916 deletions(-) diff --git a/shortcuts/sheets/data/flag-defs.json b/shortcuts/sheets/data/flag-defs.json index b1000009e..d8687e227 100644 --- a/shortcuts/sheets/data/flag-defs.json +++ b/shortcuts/sheets/data/flag-defs.json @@ -1874,6 +1874,17 @@ "stdin" ] }, + { + "name": "colors", + "kind": "own", + "type": "string", + "required": "optional", + "desc": "RGB hex color array (e.g. `[\"#1FB6C1\",\"#F006C2\"]`); length must equal `--options`", + "input": [ + "file", + "stdin" + ] + }, { "name": "multiple", "kind": "own", @@ -1881,6 +1892,13 @@ "required": "optional", "desc": "Enable multi-select; default `false`" }, + { + "name": "highlight", + "kind": "own", + "type": "bool", + "required": "optional", + "desc": "Color-highlight options; default `false`" + }, { "name": "dry-run", "kind": "system", @@ -2784,6 +2802,17 @@ "stdin" ] }, + { + "name": "colors", + "kind": "own", + "type": "string", + "required": "optional", + "desc": "Color array (same length as `--options`)", + "input": [ + "file", + "stdin" + ] + }, { "name": "multiple", "kind": "own", @@ -2791,6 +2820,13 @@ "required": "optional", "desc": "Enable multi-select" }, + { + "name": "highlight", + "kind": "own", + "type": "bool", + "required": "optional", + "desc": "Color-highlight options" + }, { "name": "dry-run", "kind": "system", diff --git a/shortcuts/sheets/data/flag-schemas.json b/shortcuts/sheets/data/flag-schemas.json index 8135bd147..3d377a1db 100644 --- a/shortcuts/sheets/data/flag-schemas.json +++ b/shortcuts/sheets/data/flag-schemas.json @@ -79,498 +79,354 @@ }, "+cells-batch-set-style": { "border-styles": { - "type": "object", "description": "单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top）。", "properties": { - "top": { - "type": "object", + "bottom": { "properties": { + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", + "type": "string" + }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", - "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ] + ], + "type": "string" }, "weight": { "description": "边框粗细/线宽", - "type": "string", "enum": [ "thin", "medium", "thick" - ] - }, - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", + ], "type": "string" } - } + }, + "type": "object" }, - "bottom": { - "type": "object", + "left": { "properties": { + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", + "type": "string" + }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", - "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ] + ], + "type": "string" }, "weight": { "description": "边框粗细/线宽", - "type": "string", "enum": [ "thin", "medium", "thick" - ] - }, - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", + ], "type": "string" } - } + }, + "type": "object" }, - "left": { - "type": "object", + "right": { "properties": { + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", + "type": "string" + }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", - "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ] + ], + "type": "string" }, "weight": { "description": "边框粗细/线宽", - "type": "string", "enum": [ "thin", "medium", "thick" - ] - }, - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", + ], "type": "string" } - } + }, + "type": "object" }, - "right": { - "type": "object", + "top": { "properties": { + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", + "type": "string" + }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", - "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ] + ], + "type": "string" }, "weight": { "description": "边框粗细/线宽", - "type": "string", "enum": [ "thin", "medium", "thick" - ] - }, - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", + ], "type": "string" } - } + }, + "type": "object" } - } + }, + "type": "object" } }, "+cells-set": { "cells": { - "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": "单元格批注/备注", - "type": "string" - }, - "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", + "bottom": { "properties": { + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", + "type": "string" + }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", - "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ] + ], + "type": "string" }, "weight": { "description": "边框粗细/线宽", - "type": "string", "enum": [ "thin", "medium", "thick" - ] - }, - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", + ], "type": "string" } - } + }, + "type": "object" }, - "bottom": { - "type": "object", + "left": { "properties": { + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", + "type": "string" + }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", - "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ] + ], + "type": "string" }, "weight": { "description": "边框粗细/线宽", - "type": "string", "enum": [ "thin", "medium", "thick" - ] - }, - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", + ], "type": "string" } - } + }, + "type": "object" }, - "left": { - "type": "object", + "right": { "properties": { + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", + "type": "string" + }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", - "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ] + ], + "type": "string" }, "weight": { "description": "边框粗细/线宽", - "type": "string", "enum": [ "thin", "medium", "thick" - ] - }, - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", + ], "type": "string" } - } + }, + "type": "object" }, - "right": { - "type": "object", + "top": { "properties": { + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", + "type": "string" + }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", - "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ] + ], + "type": "string" }, "weight": { "description": "边框粗细/线宽", - "type": "string", "enum": [ "thin", "medium", "thick" - ] - }, - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", + ], "type": "string" } - } + }, + "type": "object" } - } + }, + "type": "object" }, - "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' 时必填）", - "type": "string" - }, - "mention_token": { - "description": "@提及目标的 token，如 userId 或 fileId（仅 type='mention' 时必填）", - "type": "string" - }, - "mention_type": { - "description": "@提及类型编号（仅 type='mention' 时可选）", - "type": "number" - }, - "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" - } + "cell_styles": { + "description": "单元格样式属性，包括字体、颜色、对齐方式和数字格式", + "properties": { + "background_color": { + "description": "背景颜色（十六进制，例如 \"#ffffff\"）", + "type": "string" }, - "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" - } + "font_color": { + "description": "字体颜色（十六进制，例如 \"#000000\"）", + "type": "string" }, - "required": [ - "value" - ] - } + "font_line": { + "description": "字体线条样式", + "enum": [ + "none", + "underline", + "line-through" + ], + "type": "string" + }, + "font_size": { + "description": "字体大小（单位：px/像素，例如 10、12、14）", + "type": "number" + }, + "font_style": { + "description": "字体样式", + "enum": [ + "normal", + "italic" + ], + "type": "string" + }, + "font_weight": { + "description": "字重", + "enum": [ + "normal", + "bold" + ], + "type": "string" + }, + "horizontal_alignment": { + "description": "水平对齐方式", + "enum": [ + "left", + "center", + "right" + ], + "type": "string" + }, + "number_format": { + "description": "数字格式（例如：文本用 \"@\"、数字用 \"0.00\"、货币用 \"$#,##0.00\"、日期用 \"mm/dd/yyyy\"）", + "type": "string" + }, + "vertical_alignment": { + "description": "垂直对齐方式", + "enum": [ + "top", + "middle", + "bottom" + ], + "type": "string" + }, + "word_wrap": { + "description": "是否自动换行，默认溢出，可选自动换行或裁剪。", + "enum": [ + "overflow", + "auto-wrap", + "word-clip" + ], + "type": "string" + } + }, + "type": "object" }, "data_validation": { "description": "数据验证配置。设为 null 可清除已有的数据验证。", - "type": "object", "properties": { - "type": { - "description": "数据验证类型：list（下拉列表）、listFromRange（引用范围下拉列表）、number（数字）、date（日期）、textLength（文本长度）、checkbox（复选框）", - "type": "string", - "enum": [ - "list", - "listFromRange", - "number", - "date", - "textLength", - "checkbox" - ] + "enable_highlight": { + "description": "是否开启下拉选项的胶囊背景色高亮，仅 type='list'/'listFromRange' 生效，默认 false。", + "type": "boolean" }, - "items": { - "description": "列表选项", - "type": "array", + "help_text": { + "description": "验证失败时显示的提示文本", + "type": "string" + }, + "highlight_colors": { + "description": "下拉选项的胶囊背景色数组（十六进制，例如 [\"#FFE699\",\"#bff7d9\",\"#ffb3b3\"]），仅当 enable_highlight=true 时生效。如提供，长度必须严格匹配：type='list' 时等于 items 长度；type='listFromRange' 时等于 range 内单元格数（行优先顺序，如 A1:A10 对应第 1-10 项；A1:B2 顺序为 A1,B1,A2,B2）。长度不匹配工具会报错。不提供时所有选项使用默认色 #bacefd。", "items": { "type": "string" - } + }, + "type": "array" }, - "range": { - "description": "源数据区域（type='listFromRange' 时必填，格式：'SheetName!A1:A10'）", - "type": "string" + "items": { + "description": "列表选项（type='list' 时必填）", + "items": { + "type": "string" + }, + "type": "array" }, "operator": { "description": "比较运算符（type='number'/'date'/'textLength' 时必填）", - "type": "string", "enum": [ "equal", "notEqual", @@ -580,11 +436,31 @@ "lessThanOrEqual", "between", "notBetween" - ] + ], + "type": "string" + }, + "range": { + "description": "源数据区域（type='listFromRange' 时必填，格式：'SheetName!A1:A10'）", + "type": "string" + }, + "support_multiple_values": { + "description": "列表验证是否支持多选（type='list'/'listFromRange' 时可选，默认 false）", + "type": "boolean" + }, + "type": { + "description": "数据验证类型：list（下拉列表）、listFromRange（引用范围下拉列表）、number（数字）、date（日期）、textLength（文本长度）、checkbox（复选框）", + "enum": [ + "list", + "listFromRange", + "number", + "date", + "textLength", + "checkbox" + ], + "type": "string" }, "values": { "description": "比较值（operator 为 'between'/'notBetween' 时需要两个值，其它运算符需要一个值）", - "type": "array", "items": { "oneOf": [ { @@ -594,2284 +470,2350 @@ "type": "number" } ] - } - }, - "support_multiple_values": { - "description": "列表验证是否支持多选（type='list'/'listFromRange' 时可选，默认 false）", - "type": "boolean" - }, - "help_text": { - "description": "验证失败时显示的提示文本", - "type": "string" + }, + "type": "array" } }, "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" - } - } + ], + "type": "object" }, - "bottom": { - "type": "object", - "properties": { - "style": { - "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", - "type": "string", - "enum": [ - "solid", - "dashed", - "dotted", - "double", - "none" - ] - }, - "weight": { - "description": "边框粗细/线宽", - "type": "string", - "enum": [ - "thin", - "medium", - "thick" - ] + "formula": { + "description": "以 '=' 开头的单元格公式（例如：'=SUM(A1:A10)'）。公式必须写在此字段，而不是 'value'。", + "type": "string" + }, + "multiple_values": { + "description": "多值内容，用于支持多选的列表验证单元格。设置后会忽略 value 和 rich_text 字段。", + "items": { + "properties": { + "format": { + "description": "可选的数字格式（例如 '$#,##0.00'）", + "type": "string" + }, + "value": { + "description": "值（文本、数字、布尔）", + "oneOf": [ + { + "type": "string" + }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + }, + "required": [ + "value" + ], + "type": "object" + }, + "type": "array" + }, + "note": { + "description": "单元格批注/备注", + "type": "string" + }, + "rich_text": { + "description": "富文本内容。设置后会忽略 value 字段。可包含带样式的文本段 text、超链接 link、@提及 mention、单元格图片 embed-image、附件 attachment。", + "items": { + "properties": { + "attachment_name": { + "description": "附件文件名称（仅 type='attachment' 时使用，配合 attachment_reference_id 使用，创建新附件时必填）", + "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" + }, + "file_size": { + "description": "附件文件大小（字节，仅 type='attachment' 时使用）", + "type": "number" + }, + "image_height": { + "description": "图片高度（像素，仅 type='embed-image' 时使用）", + "type": "number" + }, + "image_name": { + "description": "图片名称（仅 type='embed-image' 时使用，创建新图片时必填）", + "type": "string" + }, + "image_token": { + "description": "图片文件 token（仅 type='embed-image' 时可选，修改已有图片时可从 get_cell_range 获取）", + "type": "string" + }, + "image_uri": { + "description": "图片文件 reference_id（仅 type='embed-image' 时使用，与 image_token 二选一，如`<|image|>:abcdef` 或者 `<|superscript|>:abcdef-<|image|>:abcdef`，其中 `abcdef` 为实际的对象 ID，占位符仅用于示意）", + "type": "string" + }, + "image_width": { + "description": "图片宽度（像素，仅 type='embed-image' 时使用）", + "type": "number" + }, + "link": { + "description": "超链接地址（仅 type='link' 时必填）", + "type": "string" + }, + "mention_token": { + "description": "@提及目标的 token，如 userId 或 fileId（仅 type='mention' 时必填）", + "type": "string" + }, + "mention_type": { + "description": "@提及类型编号（仅 type='mention' 时可选）", + "type": "number" + }, + "mime_type": { + "description": "附件 MIME 类型（仅 type='attachment' 时使用，例如 'application/pdf'）", + "type": "string" + }, + "notify": { + "description": "是否发送通知（仅 type='mention' 时可选，默认 true）", + "type": "boolean" + }, + "style": { + "description": "文本段样式（仅 type='text' 时生效），结构同 cell_styles", + "type": "object" + }, + "text": { + "description": "显示文本", + "type": "string" + }, + "type": { + "description": "段类型", + "enum": [ + "text", + "link", + "mention", + "embed-image", + "attachment" + ], + "type": "string" + } + }, + "required": [ + "type", + "text" + ], + "type": "object" + }, + "type": "array" + }, + "value": { + "description": "静态单元格值（文本、数字、布尔）。公式请优先使用 'formula' 字段；如果误把以 '=' 开头的公式字符串写到这里，工具会按 Excel 语义自动识别为公式入库，但仍应按 'formula' 字段的契约传参。", + "oneOf": [ + { + "type": "string" }, + { + "type": "number" + }, + { + "type": "boolean" + } + ] + } + }, + "type": "object" + } + }, + "+cells-set-style": { + "border-styles": { + "description": "单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top）。", + "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": { - "type": "object", "properties": { + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", + "type": "string" + }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", - "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ] + ], + "type": "string" }, "weight": { "description": "边框粗细/线宽", - "type": "string", "enum": [ "thin", "medium", "thick" - ] - }, - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", + ], "type": "string" } - } + }, + "type": "object" }, "right": { - "type": "object", "properties": { + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", + "type": "string" + }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", - "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ] + ], + "type": "string" }, "weight": { "description": "边框粗细/线宽", - "type": "string", "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" } - } + }, + "type": "object" } }, "+chart-create": { "properties": { + "additionalProperties": {}, "description": "创建/更新的图表属性。", - "type": "object", "properties": { + "offset": { + "additionalProperties": false, + "description": "可选。图表在位置基础上的偏移量（像素）。", + "properties": { + "col_offset": { + "description": "列偏移量（像素）", + "type": "number" + }, + "row_offset": { + "description": "行偏移量（像素）", + "type": "number" + } + }, + "type": "object" + }, "position": { - "type": "object", + "additionalProperties": false, "description": "必填。图表在表格中的单元格位置。注意：选择位置时应避免覆盖已有数据的单元格，并确保图表不超出当前表格的行列范围。", "properties": { + "col": { + "description": "列索引，例如 \"A\"、\"B\"", + "type": "string" + }, "row": { - "type": "number", + "description": "行索引（0-based）", "minimum": 0, - "description": "行索引（0-based）" - }, - "col": { - "type": "string", - "description": "列索引，例如 \"A\"、\"B\"" + "type": "number" } }, "required": [ "row", "col" ], - "additionalProperties": false - }, - "offset": { - "type": "object", - "description": "可选。图表在位置基础上的偏移量（像素）。", - "properties": { - "row_offset": { - "type": "number", - "description": "行偏移量（像素）" - }, - "col_offset": { - "type": "number", - "description": "列偏移量（像素）" - } - }, - "additionalProperties": false + "type": "object" }, "size": { - "type": "object", + "additionalProperties": false, "description": "必填。图表大小（像素）。注意：设定大小时应确保图表不超出当前表格的行列范围，并避免覆盖已有数据的单元格。", "properties": { - "width": { - "type": "number", + "height": { + "description": "高度（像素）", "minimum": 10, - "description": "宽度（像素）" + "type": "number" }, - "height": { - "type": "number", + "width": { + "description": "宽度（像素）", "minimum": 10, - "description": "高度（像素）" + "type": "number" } }, "required": [ "width", "height" ], - "additionalProperties": false + "type": "object" }, "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": "图表样式配置", + "data": { + "description": "图表数据配置", "properties": { - "background": { - "type": "object", - "description": "背景配置", - "properties": { - "color": { - "type": "string", - "description": "背景颜色，格式为 #RRGGBB" - } - } - }, - "font": { - "type": "object", - "description": "字体配置", + "dim1": { + "description": "维度1配置（类别维度）", "properties": { - "size": { - "type": "number", - "description": "字体大小" + "field": { + "description": "字段配置（静态数据时传此参数）", + "properties": { + "name": { + "description": "字段名称", + "type": "string" + }, + "text": { + "description": "字段文本数据", + "type": "string" + }, + "valueType": { + "description": "值类型", + "enum": [ + "number", + "string" + ], + "type": "string" + } + }, + "required": [ + "text" + ], + "type": "object" }, - "color": { - "type": "string", - "description": "字体颜色，格式为 #RRGGBB" + "serie": { + "description": "系列配置（非静态数据时传此参数）", + "properties": { + "aggregate": { + "description": "是否汇总相同的类别，默认为true，true 情况下 aggregateType 才生效", + "type": "boolean" + }, + "index": { + "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引", + "type": "number" + }, + "nameRef": { + "description": "可选。维度名称的单元格引用（A1 表示法，如 'Sheet1!A1'）。当维度名称不直接来自 refs 首行/首列时，可通过此字段把维度名显式指向目标表头单元格，图表会以该单元格当前值作为类别维度名展示。", + "type": "string" + } + }, + "type": "object" } - } + }, + "type": "object" }, - "border": { - "type": "object", - "description": "边框配置", + "dim2": { + "description": "维度2配置（值维度）", "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, + "fields": { + "description": "字段配置数组（静态数据时传此参数）", "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" - ] - } + "properties": { + "name": { + "description": "字段名称", + "type": "string" + }, + "text": { + "description": "字段文本数据", + "type": "string" + }, + "valueType": { + "description": "值类型", + "enum": [ + "number" + ], + "type": "string" + } + }, + "required": [ + "text" + ], + "type": "object" + }, + "type": "array" }, - { - "minItems": 2, + "series": { + "description": "系列配置数组（非静态数据时传此参数）", "items": { - "type": "string", - "description": "颜色字符串，十六进制格式：#RRGGBB" - } + "properties": { + "aggregateType": { + "description": "汇总方式，默认为'sum'，仅在 aggregate 为 true 时生效", + "enum": [ + "sum", + "average", + "count", + "min", + "max", + "median" + ], + "type": "string" + }, + "index": { + "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引", + "type": "number" + }, + "nameRef": { + "description": "可选。系列名称的单元格引用（A1 表示法，如 'Sheet1!C1'）。当系列名称不直接来自 refs 首行/首列时，可通过此字段把系列名显式指向目标表头单元格，图表会以该单元格当前值作为系列名（图例/tooltip）展示。", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" } - ] + }, + "type": "object" }, - "colorGradient": { - "type": "boolean", - "description": "是否启用颜色渐变" + "direction": { + "description": "数据方向，可选值：row（行方向）或column（列方向），常用值为column", + "enum": [ + "row", + "column" + ], + "type": "string" + }, + "headerMode": { + "description": "表头模式。inline 表示 refs 首行/首列就是表头；detached 表示 refs 仅覆盖实际数据范围，维度名和系列名需通过 nameRef 显式指定。", + "enum": [ + "inline", + "detached" + ], + "type": "string" + }, + "includeHiddenOrFilter": { + "description": "是否包含隐藏或过滤的数据", + "type": "boolean" + }, + "isStaticData": { + "description": "是否为静态数据", + "type": "boolean" + }, + "refs": { + "description": "数据源引用范围数组", + "items": { + "properties": { + "value": { + "description": "图表数据源范围，格式为 'SheetName!A1:D100' 的连续区域", + "type": "string" + } + }, + "required": [ + "value" + ], + "type": "object" + }, + "type": "array" } - } + }, + "type": "object" }, "legend": { "oneOf": [ { - "type": "object", "description": "图例配置", "properties": { + "bold": { + "description": "是否加粗", + "type": "boolean" + }, + "color": { + "description": "字体颜色，格式为 #RRGGBB", + "type": "string" + }, + "fontSize": { + "description": "字体大小", + "type": "number" + }, + "italic": { + "description": "是否斜体", + "type": "boolean" + }, "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": "是否下划线" + ], + "type": "string" }, "strikethrough": { - "type": "boolean", - "description": "是否删除线" + "description": "是否删除线", + "type": "boolean" }, - "color": { - "type": "string", - "description": "字体颜色，格式为 #RRGGBB" + "underline": { + "description": "是否下划线", + "type": "boolean" } - } + }, + "type": "object" }, { - "type": "boolean", - "description": "false 表示隐藏图例" + "description": "false 表示隐藏图例", + "type": "boolean" } ] }, "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", + "axes": { + "description": "坐标轴配置数组", + "items": { + "description": "坐标轴配置", + "properties": { + "axisLine": { + "description": "是否显示轴线", + "type": "boolean" + }, + "gridLine": { + "oneOf": [ + { + "description": "网格线配置", "properties": { - "index": { - "type": "number", - "description": "数据点索引" - }, "color": { - "type": "string", - "description": "颜色" - }, - "shape": { - "type": "string", - "description": "形状" + "description": "网格线颜色", + "type": "string" }, - "size": { - "type": "number", - "description": "大小" + "width": { + "description": "网格线宽度", + "type": "number" } }, - "required": [ - "index" - ] + "type": "object" + }, + { + "description": "false 表示隐藏网格线", + "type": "boolean" + } + ] + }, + "label": { + "description": "坐标轴标签配置", + "properties": { + "angle": { + "description": "旋转角度，可选值：-90, -45, 0, 45, 90", + "type": "number" + }, + "bold": { + "description": "是否加粗", + "type": "boolean" + }, + "color": { + "description": "字体颜色", + "type": "string" + }, + "fontSize": { + "description": "字体大小", + "type": "number" + }, + "italic": { + "description": "是否斜体", + "type": "boolean" + }, + "strikethrough": { + "description": "是否删除线", + "type": "boolean" + }, + "underline": { + "description": "是否下划线", + "type": "boolean" } - } - } - }, - "lines": { - "type": "object", - "description": "全系列线条配置，折线图、面积图、雷达图、组合图生效。", - "properties": { - "color": { - "type": "string", - "description": "线条颜色" - }, - "width": { - "type": "number", - "description": "线条宽度" }, - "style": { - "type": "string", - "description": "线条样式", - "enum": [ - "solid", - "dashed", - "dotted" - ] + "type": "object" + }, + "max": { + "description": "最大值", + "type": "number" + }, + "min": { + "description": "最小值", + "type": "number" + }, + "position": { + "description": "坐标轴位置", + "enum": [ + "left", + "right", + "bottom" + ], + "type": "string" + }, + "title": { + "description": "坐标轴标题配置", + "properties": { + "bold": { + "description": "是否加粗", + "type": "boolean" + }, + "color": { + "description": "字体颜色", + "type": "string" + }, + "fontSize": { + "description": "字体大小", + "type": "number" + }, + "italic": { + "description": "是否斜体", + "type": "boolean" + }, + "strikethrough": { + "description": "是否删除线", + "type": "boolean" + }, + "text": { + "description": "标题文本", + "type": "string" + }, + "underline": { + "description": "是否下划线", + "type": "boolean" + } }, - "invalidType": { - "type": "string", - "description": "无效值处理方式", - "enum": [ - "break", - "zero", - "link" - ] - } + "required": [ + "text" + ], + "type": "object" + }, + "type": { + "description": "坐标轴类型", + "enum": [ + "x", + "y", + "angle", + "radius" + ], + "type": "string" + }, + "valueType": { + "description": "是否将横轴数字视为文本，linear 表示将数字视为数值, ordinal 表示将数字视为文本", + "enum": [ + "ordinal", + "linear" + ], + "type": "string" } }, + "required": [ + "type" + ], + "type": "object" + }, + "type": "array" + }, + "plot": { + "description": "绘图配置", + "properties": { "areas": { - "type": "object", "description": "全系列面积填充配置，面积图、雷达图、组合图生效。", "properties": { "color": { - "type": "string", - "description": "区域填充颜色" + "description": "区域填充颜色", + "type": "string" } - } + }, + "type": "object" }, "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": "背景颜色" + "description": "背景颜色", + "type": "string" }, "bar": { - "type": "array", "description": "单个柱子配置数组", "items": { - "type": "object", "properties": { - "index": { - "type": "number", - "description": "柱子索引" - }, - "color": { - "type": "string", - "description": "颜色" - }, "borderColor": { - "type": "string", - "description": "边框颜色" + "description": "边框颜色", + "type": "string" + }, + "borderStyle": { + "description": "边框样式", + "type": "string" }, "borderWidth": { - "type": "number", - "description": "边框宽度" + "description": "边框宽度", + "type": "number" }, - "borderStyle": { - "type": "string", - "description": "边框样式" + "color": { + "description": "颜色", + "type": "string" + }, + "index": { + "description": "柱子索引", + "type": "number" } }, "required": [ "index" - ] - } - } - } - }, - "labels": { - "type": "object", - "description": "数据标签配置", - "properties": { - "position": { - "type": "string", - "description": "标签位置", - "enum": [ - "auto", - "top", - "bottom", - "left", - "right", - "center", - "inside", - "outside" - ] + ], + "type": "object" + }, + "type": "array" }, - "series": { - "type": "boolean", - "description": "是否显示系列名" + "borderColor": { + "description": "边框颜色", + "type": "string" }, - "category": { - "type": "boolean", - "description": "是否显示类别名" + "borderStyle": { + "description": "边框样式", + "enum": [ + "solid", + "dashed", + "dotted" + ], + "type": "string" }, - "value": { - "type": "boolean", - "description": "是否显示值" + "borderWidth": { + "description": "边框宽度", + "type": "number" }, - "percentage": { - "type": "boolean", - "description": "是否显示百分比" + "color": { + "description": "柱子颜色", + "type": "string" }, - "fontSize": { - "type": "number", - "description": "字体大小" + "gap": { + "description": "柱子间距比例，0-1之间", + "type": "number" + }, + "width": { + "description": "柱子宽度", + "type": "number" + } + }, + "type": "object" + }, + "comboType": { + "description": "组合图表默认类型", + "enum": [ + "column", + "line", + "area" + ], + "type": "string" + }, + "extra": { + "description": "额外配置", + "properties": { + "radar": { + "description": "雷达图配置", + "properties": { + "area": { + "description": "是否填充区域", + "type": "boolean" + }, + "shape": { + "description": "雷达图形状", + "enum": [ + "polygon", + "circle" + ], + "type": "string" + } + }, + "type": "object" }, + "smooth": { + "description": "是否平滑曲线", + "type": "boolean" + }, + "stack": { + "description": "堆叠配置", + "properties": { + "percentage": { + "description": "是否百分比堆叠", + "type": "boolean" + } + }, + "type": "object" + }, + "step": { + "description": "是否阶梯图", + "type": "boolean" + } + }, + "type": "object" + }, + "labels": { + "description": "数据标签配置", + "properties": { "bold": { - "type": "boolean", - "description": "是否加粗" + "description": "是否加粗", + "type": "boolean" + }, + "category": { + "description": "是否显示类别名", + "type": "boolean" + }, + "color": { + "description": "字体颜色", + "type": "string" + }, + "fontSize": { + "description": "字体大小", + "type": "number" }, "italic": { - "type": "boolean", - "description": "是否斜体" + "description": "是否斜体", + "type": "boolean" }, - "underline": { - "type": "boolean", - "description": "是否下划线" + "percentage": { + "description": "是否显示百分比", + "type": "boolean" + }, + "position": { + "description": "标签位置", + "enum": [ + "auto", + "top", + "bottom", + "left", + "right", + "center", + "inside", + "outside" + ], + "type": "string" + }, + "series": { + "description": "是否显示系列名", + "type": "boolean" }, "strikethrough": { - "type": "boolean", - "description": "是否删除线" + "description": "是否删除线", + "type": "boolean" + }, + "underline": { + "description": "是否下划线", + "type": "boolean" }, + "value": { + "description": "是否显示值", + "type": "boolean" + } + }, + "type": "object" + }, + "lines": { + "description": "全系列线条配置，折线图、面积图、雷达图、组合图生效。", + "properties": { "color": { - "type": "string", - "description": "字体颜色" + "description": "线条颜色", + "type": "string" + }, + "invalidType": { + "description": "无效值处理方式", + "enum": [ + "break", + "zero", + "link" + ], + "type": "string" + }, + "style": { + "description": "线条样式", + "enum": [ + "solid", + "dashed", + "dotted" + ], + "type": "string" + }, + "width": { + "description": "线条宽度", + "type": "number" } - } + }, + "type": "object" + }, + "points": { + "description": "全系列数据点配置，折线图、面积图、雷达图、散点图、组合图生效。", + "properties": { + "color": { + "description": "数据点颜色", + "type": "string" + }, + "point": { + "description": "单个数据点配置数组", + "items": { + "properties": { + "color": { + "description": "颜色", + "type": "string" + }, + "index": { + "description": "数据点索引", + "type": "number" + }, + "shape": { + "description": "形状", + "type": "string" + }, + "size": { + "description": "大小", + "type": "number" + } + }, + "required": [ + "index" + ], + "type": "object" + }, + "type": "array" + }, + "shape": { + "description": "数据点形状", + "enum": [ + "circle", + "triangle", + "rect", + "diamond", + "square" + ], + "type": "string" + }, + "size": { + "description": "数据点大小", + "type": "number" + } + }, + "type": "object" }, "series": { - "type": "array", "description": "单个系列配置数组", "items": { - "type": "object", "description": "系列配置", "properties": { - "index": { - "type": "number", - "description": "数据列索引，与 dim2.series[].index 值一致，从 1 开始（1 通常对应首列标签维度，2+ 对应后续数据维度列）" + "area": { + "description": "区域填充配置，配置项同 plotArea.areas", + "type": "object" + }, + "bars": { + "description": "柱状图配置，配置项同 plotArea.bars", + "type": "object" }, "comboType": { - "type": "string", "description": "组合图下该系列的图表类型，仅在 type 为 combo 时生效", "enum": [ "column", "line", "area" - ] + ], + "type": "string" }, - "yAxisPosition": { - "type": "string", - "description": "Y轴位置", - "enum": [ - "left", - "right" - ] + "index": { + "description": "数据列索引，与 dim2.series[].index 值一致，从 1 开始（1 通常对应首列标签维度，2+ 对应后续数据维度列）", + "type": "number" }, - "points": { - "type": "object", - "description": "数据点配置，配置项同 plotArea.points" + "labels": { + "description": "数据标签配置", + "type": "object" }, "line": { - "type": "object", - "description": "线条配置，配置项同 plotArea.lines" - }, - "area": { - "type": "object", - "description": "区域填充配置，配置项同 plotArea.areas" - }, - "bars": { - "type": "object", - "description": "柱状图配置，配置项同 plotArea.bars" + "description": "线条配置，配置项同 plotArea.lines", + "type": "object" }, - "labels": { - "type": "object", - "description": "数据标签配置" + "points": { + "description": "数据点配置，配置项同 plotArea.points", + "type": "object" }, "sectors": { - "type": "object", "description": "扇区配置（饼图）", "properties": { "borderColor": { - "type": "string", - "description": "边框颜色" + "description": "边框颜色", + "type": "string" }, "innerRadius": { - "type": "number", - "description": "内半径比例，0-1之间" + "description": "内半径比例，0-1之间", + "type": "number" }, "offsetRadius": { - "type": "number", - "description": "偏移半径比例" - }, - "startAngle": { - "type": "number", - "description": "起始角度，0-359" + "description": "偏移半径比例", + "type": "number" }, "sector": { - "type": "array", "description": "单个扇区配置数组", "items": { - "type": "object", "properties": { - "index": { - "type": "number", - "description": "扇区索引" - }, "borderColor": { - "type": "string", - "description": "边框颜色" - }, - "offsetRadius": { - "type": "number", - "description": "偏移半径" + "description": "边框颜色", + "type": "string" }, "color": { - "type": "string", - "description": "颜色" + "description": "颜色", + "type": "string" + }, + "index": { + "description": "扇区索引", + "type": "number" + }, + "offsetRadius": { + "description": "偏移半径", + "type": "number" } }, "required": [ "index" - ] - } + ], + "type": "object" + }, + "type": "array" + }, + "startAngle": { + "description": "起始角度，0-359", + "type": "number" } - } + }, + "type": "object" + }, + "yAxisPosition": { + "description": "Y轴位置", + "enum": [ + "left", + "right" + ], + "type": "string" } }, "required": [ "index" - ] - } + ], + "type": "object" + }, + "type": "array" + }, + "type": { + "description": "图表类型", + "enum": [ + "bar", + "column", + "line", + "area", + "combo", + "pie", + "radar", + "scatter" + ], + "type": "string" + }, + "yAxisPosition": { + "description": "Y轴位置", + "enum": [ + "left", + "right" + ], + "type": "string" } }, "required": [ "type" - ] + ], + "type": "object" + } + }, + "type": "object" + }, + "style": { + "description": "图表样式配置", + "properties": { + "background": { + "description": "背景配置", + "properties": { + "color": { + "description": "背景颜色，格式为 #RRGGBB", + "type": "string" + } + }, + "type": "object" }, - "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": "字体颜色" - } - } + "border": { + "description": "边框配置", + "properties": { + "color": { + "description": "边框颜色，格式为 #RRGGBB", + "type": "string" + }, + "radius": { + "description": "边框圆角", + "type": "number" + }, + "style": { + "description": "边框样式", + "enum": [ + "solid", + "dashed", + "dotted" + ], + "type": "string" + }, + "width": { + "description": "边框宽度", + "type": "number" + } + }, + "type": "object" + }, + "colorGradient": { + "description": "是否启用颜色渐变", + "type": "boolean" + }, + "colorTheme": { + "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": [ + { + "items": { + "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" + ], + "type": "string" }, - "axisLine": { - "type": "boolean", - "description": "是否显示轴线" + "maxItems": 1, + "minItems": 1 + }, + { + "items": { + "description": "颜色字符串，十六进制格式：#RRGGBB", + "type": "string" }, - "gridLine": { - "oneOf": [ - { - "type": "object", - "description": "网格线配置", - "properties": { - "width": { - "type": "number", - "description": "网格线宽度" - }, - "color": { - "type": "string", - "description": "网格线颜色" - } - } - }, - { - "type": "boolean", - "description": "false 表示隐藏网格线" - } - ] - } + "minItems": 2 + } + ], + "type": "array" + }, + "font": { + "description": "字体配置", + "properties": { + "color": { + "description": "字体颜色，格式为 #RRGGBB", + "type": "string" }, - "required": [ - "type" - ] - } + "size": { + "description": "字体大小", + "type": "number" + } + }, + "type": "object" } - } + }, + "type": "object" }, - "data": { - "type": "object", - "description": "图表数据配置", + "subTitle": { + "description": "图表副标题配置", "properties": { - "isStaticData": { - "type": "boolean", - "description": "是否为静态数据" + "bold": { + "description": "是否加粗", + "type": "boolean" }, - "includeHiddenOrFilter": { - "type": "boolean", - "description": "是否包含隐藏或过滤的数据" + "color": { + "description": "字体颜色，格式为 #RRGGBB", + "type": "string" }, - "direction": { - "type": "string", - "description": "数据方向，可选值：row（行方向）或column（列方向），常用值为column", - "enum": [ - "row", - "column" - ] + "fontSize": { + "description": "字体大小", + "type": "number" }, - "headerMode": { - "type": "string", - "description": "表头模式。inline 表示 refs 首行/首列就是表头；detached 表示 refs 仅覆盖实际数据范围，维度名和系列名需通过 nameRef 显式指定。", + "italic": { + "description": "是否斜体", + "type": "boolean" + }, + "strikethrough": { + "description": "是否删除线", + "type": "boolean" + }, + "text": { + "description": "副标题文本", + "type": "string" + }, + "textAlign": { + "description": "副标题对齐方式", "enum": [ - "inline", - "detached" - ] + "left", + "center", + "right" + ], + "type": "string" }, - "refs": { - "type": "array", - "description": "数据源引用范围数组", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string", - "description": "图表数据源范围，格式为 'SheetName!A1:D100' 的连续区域" - } - }, - "required": [ - "value" - ] - } + "underline": { + "description": "是否下划线", + "type": "boolean" + } + }, + "required": [ + "text" + ], + "type": "object" + }, + "title": { + "description": "图表标题配置", + "properties": { + "bold": { + "description": "是否加粗", + "type": "boolean" }, - "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 首行/首列时，可通过此字段把维度名显式指向目标表头单元格，图表会以该单元格当前值作为类别维度名展示。" - } - } - }, - "field": { - "type": "object", - "description": "字段配置（静态数据时传此参数）", - "properties": { - "valueType": { - "type": "string", - "description": "值类型", - "enum": [ - "number", - "string" - ] - }, - "name": { - "type": "string", - "description": "字段名称" - }, - "text": { - "type": "string", - "description": "字段文本数据" - } - }, - "required": [ - "text" - ] - } - } + "color": { + "description": "字体颜色，格式为 #RRGGBB", + "type": "string" }, - "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 时生效", - "enum": [ - "sum", - "average", - "count", - "min", - "max", - "median" - ] - }, - "nameRef": { - "type": "string", - "description": "可选。系列名称的单元格引用（A1 表示法，如 'Sheet1!C1'）。当系列名称不直接来自 refs 首行/首列时，可通过此字段把系列名显式指向目标表头单元格，图表会以该单元格当前值作为系列名（图例/tooltip）展示。" - } - } - } - }, - "fields": { - "type": "array", - "description": "字段配置数组（静态数据时传此参数）", - "items": { - "type": "object", - "properties": { - "valueType": { - "type": "string", - "description": "值类型", - "enum": [ - "number" - ] - }, - "name": { - "type": "string", - "description": "字段名称" - }, - "text": { - "type": "string", - "description": "字段文本数据" - } - }, - "required": [ - "text" - ] - } - } - } + "fontSize": { + "description": "字体大小", + "type": "number" + }, + "italic": { + "description": "是否斜体", + "type": "boolean" + }, + "strikethrough": { + "description": "是否删除线", + "type": "boolean" + }, + "text": { + "description": "标题文本", + "type": "string" + }, + "textAlign": { + "description": "标题对齐方式", + "enum": [ + "left", + "center", + "right" + ], + "type": "string" + }, + "underline": { + "description": "是否下划线", + "type": "boolean" } - } + }, + "required": [ + "text" + ], + "type": "object" } - } + }, + "type": "object" } }, - "required": [ - "position", - "size" - ], - "additionalProperties": {} + "type": "object" } }, "+chart-update": { "properties": { + "additionalProperties": {}, "description": "创建/更新的图表属性。", - "type": "object", "properties": { + "offset": { + "additionalProperties": false, + "description": "可选。图表在位置基础上的偏移量（像素）。", + "properties": { + "col_offset": { + "description": "列偏移量（像素）", + "type": "number" + }, + "row_offset": { + "description": "行偏移量（像素）", + "type": "number" + } + }, + "type": "object" + }, "position": { - "type": "object", + "additionalProperties": false, "description": "必填。图表在表格中的单元格位置。注意：选择位置时应避免覆盖已有数据的单元格，并确保图表不超出当前表格的行列范围。", "properties": { + "col": { + "description": "列索引，例如 \"A\"、\"B\"", + "type": "string" + }, "row": { - "type": "number", + "description": "行索引（0-based）", "minimum": 0, - "description": "行索引（0-based）" - }, - "col": { - "type": "string", - "description": "列索引，例如 \"A\"、\"B\"" + "type": "number" } }, "required": [ "row", "col" ], - "additionalProperties": false - }, - "offset": { - "type": "object", - "description": "可选。图表在位置基础上的偏移量（像素）。", - "properties": { - "row_offset": { - "type": "number", - "description": "行偏移量（像素）" - }, - "col_offset": { - "type": "number", - "description": "列偏移量（像素）" - } - }, - "additionalProperties": false + "type": "object" }, "size": { - "type": "object", + "additionalProperties": false, "description": "必填。图表大小（像素）。注意：设定大小时应确保图表不超出当前表格的行列范围，并避免覆盖已有数据的单元格。", "properties": { - "width": { - "type": "number", + "height": { + "description": "高度（像素）", "minimum": 10, - "description": "宽度（像素）" + "type": "number" }, - "height": { - "type": "number", + "width": { + "description": "宽度（像素）", "minimum": 10, - "description": "高度（像素）" + "type": "number" } }, "required": [ "width", "height" ], - "additionalProperties": false + "type": "object" }, "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": "图表副标题配置", + "data": { + "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": "是否删除线" + "dim1": { + "description": "维度1配置（类别维度）", + "properties": { + "field": { + "description": "字段配置（静态数据时传此参数）", + "properties": { + "name": { + "description": "字段名称", + "type": "string" + }, + "text": { + "description": "字段文本数据", + "type": "string" + }, + "valueType": { + "description": "值类型", + "enum": [ + "number", + "string" + ], + "type": "string" + } + }, + "required": [ + "text" + ], + "type": "object" + }, + "serie": { + "description": "系列配置（非静态数据时传此参数）", + "properties": { + "aggregate": { + "description": "是否汇总相同的类别，默认为true，true 情况下 aggregateType 才生效", + "type": "boolean" + }, + "index": { + "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引", + "type": "number" + }, + "nameRef": { + "description": "可选。维度名称的单元格引用（A1 表示法，如 'Sheet1!A1'）。当维度名称不直接来自 refs 首行/首列时，可通过此字段把维度名显式指向目标表头单元格，图表会以该单元格当前值作为类别维度名展示。", + "type": "string" + } + }, + "type": "object" + } + }, + "type": "object" }, - "color": { - "type": "string", - "description": "字体颜色，格式为 #RRGGBB" - } - }, - "required": [ - "text" - ] - }, - "style": { - "type": "object", - "description": "图表样式配置", - "properties": { - "background": { - "type": "object", - "description": "背景配置", + "dim2": { + "description": "维度2配置（值维度）", "properties": { - "color": { - "type": "string", - "description": "背景颜色，格式为 #RRGGBB" + "fields": { + "description": "字段配置数组（静态数据时传此参数）", + "items": { + "properties": { + "name": { + "description": "字段名称", + "type": "string" + }, + "text": { + "description": "字段文本数据", + "type": "string" + }, + "valueType": { + "description": "值类型", + "enum": [ + "number" + ], + "type": "string" + } + }, + "required": [ + "text" + ], + "type": "object" + }, + "type": "array" + }, + "series": { + "description": "系列配置数组（非静态数据时传此参数）", + "items": { + "properties": { + "aggregateType": { + "description": "汇总方式，默认为'sum'，仅在 aggregate 为 true 时生效", + "enum": [ + "sum", + "average", + "count", + "min", + "max", + "median" + ], + "type": "string" + }, + "index": { + "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引", + "type": "number" + }, + "nameRef": { + "description": "可选。系列名称的单元格引用（A1 表示法，如 'Sheet1!C1'）。当系列名称不直接来自 refs 首行/首列时，可通过此字段把系列名显式指向目标表头单元格，图表会以该单元格当前值作为系列名（图例/tooltip）展示。", + "type": "string" + } + }, + "type": "object" + }, + "type": "array" } - } + }, + "type": "object" }, - "font": { - "type": "object", - "description": "字体配置", - "properties": { - "size": { - "type": "number", - "description": "字体大小" - }, - "color": { - "type": "string", - "description": "字体颜色，格式为 #RRGGBB" - } - } + "direction": { + "description": "数据方向，可选值：row（行方向）或column（列方向），常用值为column", + "enum": [ + "row", + "column" + ], + "type": "string" }, - "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": "边框圆角" - } - } + "headerMode": { + "description": "表头模式。inline 表示 refs 首行/首列就是表头；detached 表示 refs 仅覆盖实际数据范围，维度名和系列名需通过 nameRef 显式指定。", + "enum": [ + "inline", + "detached" + ], + "type": "string" }, - "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" - ] + "includeHiddenOrFilter": { + "description": "是否包含隐藏或过滤的数据", + "type": "boolean" + }, + "isStaticData": { + "description": "是否为静态数据", + "type": "boolean" + }, + "refs": { + "description": "数据源引用范围数组", + "items": { + "properties": { + "value": { + "description": "图表数据源范围，格式为 'SheetName!A1:D100' 的连续区域", + "type": "string" } }, - { - "minItems": 2, - "items": { - "type": "string", - "description": "颜色字符串，十六进制格式：#RRGGBB" - } - } - ] - }, - "colorGradient": { - "type": "boolean", - "description": "是否启用颜色渐变" + "required": [ + "value" + ], + "type": "object" + }, + "type": "array" } - } + }, + "type": "object" }, "legend": { "oneOf": [ { - "type": "object", "description": "图例配置", "properties": { + "bold": { + "description": "是否加粗", + "type": "boolean" + }, + "color": { + "description": "字体颜色，格式为 #RRGGBB", + "type": "string" + }, + "fontSize": { + "description": "字体大小", + "type": "number" + }, + "italic": { + "description": "是否斜体", + "type": "boolean" + }, "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": "是否下划线" + ], + "type": "string" }, "strikethrough": { - "type": "boolean", - "description": "是否删除线" + "description": "是否删除线", + "type": "boolean" }, - "color": { - "type": "string", - "description": "字体颜色，格式为 #RRGGBB" + "underline": { + "description": "是否下划线", + "type": "boolean" } - } + }, + "type": "object" }, { - "type": "boolean", - "description": "false 表示隐藏图例" + "description": "false 表示隐藏图例", + "type": "boolean" } ] }, "plotArea": { - "type": "object", "description": "绘图区域配置", "properties": { + "axes": { + "description": "坐标轴配置数组", + "items": { + "description": "坐标轴配置", + "properties": { + "axisLine": { + "description": "是否显示轴线", + "type": "boolean" + }, + "gridLine": { + "oneOf": [ + { + "description": "网格线配置", + "properties": { + "color": { + "description": "网格线颜色", + "type": "string" + }, + "width": { + "description": "网格线宽度", + "type": "number" + } + }, + "type": "object" + }, + { + "description": "false 表示隐藏网格线", + "type": "boolean" + } + ] + }, + "label": { + "description": "坐标轴标签配置", + "properties": { + "angle": { + "description": "旋转角度，可选值：-90, -45, 0, 45, 90", + "type": "number" + }, + "bold": { + "description": "是否加粗", + "type": "boolean" + }, + "color": { + "description": "字体颜色", + "type": "string" + }, + "fontSize": { + "description": "字体大小", + "type": "number" + }, + "italic": { + "description": "是否斜体", + "type": "boolean" + }, + "strikethrough": { + "description": "是否删除线", + "type": "boolean" + }, + "underline": { + "description": "是否下划线", + "type": "boolean" + } + }, + "type": "object" + }, + "max": { + "description": "最大值", + "type": "number" + }, + "min": { + "description": "最小值", + "type": "number" + }, + "position": { + "description": "坐标轴位置", + "enum": [ + "left", + "right", + "bottom" + ], + "type": "string" + }, + "title": { + "description": "坐标轴标题配置", + "properties": { + "bold": { + "description": "是否加粗", + "type": "boolean" + }, + "color": { + "description": "字体颜色", + "type": "string" + }, + "fontSize": { + "description": "字体大小", + "type": "number" + }, + "italic": { + "description": "是否斜体", + "type": "boolean" + }, + "strikethrough": { + "description": "是否删除线", + "type": "boolean" + }, + "text": { + "description": "标题文本", + "type": "string" + }, + "underline": { + "description": "是否下划线", + "type": "boolean" + } + }, + "required": [ + "text" + ], + "type": "object" + }, + "type": { + "description": "坐标轴类型", + "enum": [ + "x", + "y", + "angle", + "radius" + ], + "type": "string" + }, + "valueType": { + "description": "是否将横轴数字视为文本，linear 表示将数字视为数值, ordinal 表示将数字视为文本", + "enum": [ + "ordinal", + "linear" + ], + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "type": "array" + }, "plot": { - "type": "object", "description": "绘图配置", "properties": { - "type": { - "type": "string", - "description": "图表类型", - "enum": [ - "bar", - "column", - "line", - "area", - "combo", - "pie", - "radar", - "scatter" - ] + "areas": { + "description": "全系列面积填充配置，面积图、雷达图、组合图生效。", + "properties": { + "color": { + "description": "区域填充颜色", + "type": "string" + } + }, + "type": "object" + }, + "bars": { + "description": "全系列柱状图、条形图、组合图生效。", + "properties": { + "backgroundColor": { + "description": "背景颜色", + "type": "string" + }, + "bar": { + "description": "单个柱子配置数组", + "items": { + "properties": { + "borderColor": { + "description": "边框颜色", + "type": "string" + }, + "borderStyle": { + "description": "边框样式", + "type": "string" + }, + "borderWidth": { + "description": "边框宽度", + "type": "number" + }, + "color": { + "description": "颜色", + "type": "string" + }, + "index": { + "description": "柱子索引", + "type": "number" + } + }, + "required": [ + "index" + ], + "type": "object" + }, + "type": "array" + }, + "borderColor": { + "description": "边框颜色", + "type": "string" + }, + "borderStyle": { + "description": "边框样式", + "enum": [ + "solid", + "dashed", + "dotted" + ], + "type": "string" + }, + "borderWidth": { + "description": "边框宽度", + "type": "number" + }, + "color": { + "description": "柱子颜色", + "type": "string" + }, + "gap": { + "description": "柱子间距比例，0-1之间", + "type": "number" + }, + "width": { + "description": "柱子宽度", + "type": "number" + } + }, + "type": "object" }, "comboType": { - "type": "string", "description": "组合图表默认类型", "enum": [ "column", "line", "area" - ] - }, - "yAxisPosition": { - "type": "string", - "description": "Y轴位置", - "enum": [ - "left", - "right" - ] + ], + "type": "string" }, "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": { + "area": { + "description": "是否填充区域", + "type": "boolean" + }, "shape": { - "type": "string", "description": "雷达图形状", "enum": [ "polygon", "circle" - ] - }, - "area": { - "type": "boolean", - "description": "是否填充区域" + ], + "type": "string" } - } + }, + "type": "object" + }, + "smooth": { + "description": "是否平滑曲线", + "type": "boolean" + }, + "stack": { + "description": "堆叠配置", + "properties": { + "percentage": { + "description": "是否百分比堆叠", + "type": "boolean" + } + }, + "type": "object" + }, + "step": { + "description": "是否阶梯图", + "type": "boolean" } - } + }, + "type": "object" }, - "points": { - "type": "object", - "description": "全系列数据点配置，折线图、面积图、雷达图、散点图、组合图生效。", + "labels": { + "description": "数据标签配置", "properties": { + "bold": { + "description": "是否加粗", + "type": "boolean" + }, + "category": { + "description": "是否显示类别名", + "type": "boolean" + }, "color": { - "type": "string", - "description": "数据点颜色" + "description": "字体颜色", + "type": "string" }, - "shape": { - "type": "string", - "description": "数据点形状", + "fontSize": { + "description": "字体大小", + "type": "number" + }, + "italic": { + "description": "是否斜体", + "type": "boolean" + }, + "percentage": { + "description": "是否显示百分比", + "type": "boolean" + }, + "position": { + "description": "标签位置", "enum": [ - "circle", - "triangle", - "rect", - "diamond", - "square" - ] + "auto", + "top", + "bottom", + "left", + "right", + "center", + "inside", + "outside" + ], + "type": "string" }, - "size": { - "type": "number", - "description": "数据点大小" + "series": { + "description": "是否显示系列名", + "type": "boolean" }, - "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" - ] - } + "strikethrough": { + "description": "是否删除线", + "type": "boolean" + }, + "underline": { + "description": "是否下划线", + "type": "boolean" + }, + "value": { + "description": "是否显示值", + "type": "boolean" } - } + }, + "type": "object" }, "lines": { - "type": "object", "description": "全系列线条配置，折线图、面积图、雷达图、组合图生效。", "properties": { "color": { - "type": "string", - "description": "线条颜色" - }, - "width": { - "type": "number", - "description": "线条宽度" - }, - "style": { - "type": "string", - "description": "线条样式", - "enum": [ - "solid", - "dashed", - "dotted" - ] + "description": "线条颜色", + "type": "string" }, "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": "边框宽度" + ], + "type": "string" }, - "borderStyle": { - "type": "string", - "description": "边框样式", + "style": { + "description": "线条样式", "enum": [ "solid", "dashed", "dotted" - ] + ], + "type": "string" }, "width": { - "type": "number", - "description": "柱子宽度" - }, - "gap": { - "type": "number", - "description": "柱子间距比例，0-1之间" - }, - "backgroundColor": { - "type": "string", - "description": "背景颜色" + "description": "线条宽度", + "type": "number" + } + }, + "type": "object" + }, + "points": { + "description": "全系列数据点配置，折线图、面积图、雷达图、散点图、组合图生效。", + "properties": { + "color": { + "description": "数据点颜色", + "type": "string" }, - "bar": { - "type": "array", - "description": "单个柱子配置数组", + "point": { + "description": "单个数据点配置数组", "items": { - "type": "object", "properties": { - "index": { - "type": "number", - "description": "柱子索引" - }, "color": { - "type": "string", - "description": "颜色" + "description": "颜色", + "type": "string" }, - "borderColor": { - "type": "string", - "description": "边框颜色" + "index": { + "description": "数据点索引", + "type": "number" }, - "borderWidth": { - "type": "number", - "description": "边框宽度" + "shape": { + "description": "形状", + "type": "string" }, - "borderStyle": { - "type": "string", - "description": "边框样式" + "size": { + "description": "大小", + "type": "number" } }, "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": "是否下划线" + ], + "type": "object" + }, + "type": "array" }, - "strikethrough": { - "type": "boolean", - "description": "是否删除线" + "shape": { + "description": "数据点形状", + "enum": [ + "circle", + "triangle", + "rect", + "diamond", + "square" + ], + "type": "string" }, - "color": { - "type": "string", - "description": "字体颜色" + "size": { + "description": "数据点大小", + "type": "number" } - } + }, + "type": "object" }, "series": { - "type": "array", "description": "单个系列配置数组", "items": { - "type": "object", "description": "系列配置", "properties": { - "index": { - "type": "number", - "description": "数据列索引，与 dim2.series[].index 值一致，从 1 开始（1 通常对应首列标签维度，2+ 对应后续数据维度列）" + "area": { + "description": "区域填充配置，配置项同 plotArea.areas", + "type": "object" + }, + "bars": { + "description": "柱状图配置，配置项同 plotArea.bars", + "type": "object" }, "comboType": { - "type": "string", "description": "组合图下该系列的图表类型，仅在 type 为 combo 时生效", "enum": [ "column", "line", "area" - ] + ], + "type": "string" }, - "yAxisPosition": { - "type": "string", - "description": "Y轴位置", - "enum": [ - "left", - "right" - ] + "index": { + "description": "数据列索引，与 dim2.series[].index 值一致，从 1 开始（1 通常对应首列标签维度，2+ 对应后续数据维度列）", + "type": "number" }, - "points": { - "type": "object", - "description": "数据点配置，配置项同 plotArea.points" + "labels": { + "description": "数据标签配置", + "type": "object" }, "line": { - "type": "object", - "description": "线条配置，配置项同 plotArea.lines" - }, - "area": { - "type": "object", - "description": "区域填充配置，配置项同 plotArea.areas" + "description": "线条配置，配置项同 plotArea.lines", + "type": "object" }, - "bars": { - "type": "object", - "description": "柱状图配置，配置项同 plotArea.bars" - }, - "labels": { - "type": "object", - "description": "数据标签配置" + "points": { + "description": "数据点配置，配置项同 plotArea.points", + "type": "object" }, "sectors": { - "type": "object", "description": "扇区配置（饼图）", "properties": { "borderColor": { - "type": "string", - "description": "边框颜色" + "description": "边框颜色", + "type": "string" }, "innerRadius": { - "type": "number", - "description": "内半径比例，0-1之间" + "description": "内半径比例，0-1之间", + "type": "number" }, "offsetRadius": { - "type": "number", - "description": "偏移半径比例" - }, - "startAngle": { - "type": "number", - "description": "起始角度，0-359" + "description": "偏移半径比例", + "type": "number" }, "sector": { - "type": "array", "description": "单个扇区配置数组", "items": { - "type": "object", "properties": { - "index": { - "type": "number", - "description": "扇区索引" - }, "borderColor": { - "type": "string", - "description": "边框颜色" - }, - "offsetRadius": { - "type": "number", - "description": "偏移半径" + "description": "边框颜色", + "type": "string" }, "color": { - "type": "string", - "description": "颜色" + "description": "颜色", + "type": "string" + }, + "index": { + "description": "扇区索引", + "type": "number" + }, + "offsetRadius": { + "description": "偏移半径", + "type": "number" } }, "required": [ "index" - ] - } + ], + "type": "object" + }, + "type": "array" + }, + "startAngle": { + "description": "起始角度，0-359", + "type": "number" } - } + }, + "type": "object" + }, + "yAxisPosition": { + "description": "Y轴位置", + "enum": [ + "left", + "right" + ], + "type": "string" } }, "required": [ "index" - ] - } + ], + "type": "object" + }, + "type": "array" + }, + "type": { + "description": "图表类型", + "enum": [ + "bar", + "column", + "line", + "area", + "combo", + "pie", + "radar", + "scatter" + ], + "type": "string" + }, + "yAxisPosition": { + "description": "Y轴位置", + "enum": [ + "left", + "right" + ], + "type": "string" } }, "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" - ] - } + ], + "type": "object" } - } + }, + "type": "object" }, - "data": { - "type": "object", - "description": "图表数据配置", + "style": { + "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" - ] + "background": { + "description": "背景配置", + "properties": { + "color": { + "description": "背景颜色，格式为 #RRGGBB", + "type": "string" + } + }, + "type": "object" }, - "refs": { - "type": "array", - "description": "数据源引用范围数组", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string", - "description": "图表数据源范围，格式为 'SheetName!A1:D100' 的连续区域" - } + "border": { + "description": "边框配置", + "properties": { + "color": { + "description": "边框颜色，格式为 #RRGGBB", + "type": "string" }, - "required": [ - "value" - ] - } + "radius": { + "description": "边框圆角", + "type": "number" + }, + "style": { + "description": "边框样式", + "enum": [ + "solid", + "dashed", + "dotted" + ], + "type": "string" + }, + "width": { + "description": "边框宽度", + "type": "number" + } + }, + "type": "object" }, - "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 首行/首列时，可通过此字段把维度名显式指向目标表头单元格，图表会以该单元格当前值作为类别维度名展示。" - } - } + "colorGradient": { + "description": "是否启用颜色渐变", + "type": "boolean" + }, + "colorTheme": { + "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": [ + { + "items": { + "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" + ], + "type": "string" + }, + "maxItems": 1, + "minItems": 1 }, - "field": { - "type": "object", - "description": "字段配置（静态数据时传此参数）", - "properties": { - "valueType": { - "type": "string", - "description": "值类型", - "enum": [ - "number", - "string" - ] - }, - "name": { - "type": "string", - "description": "字段名称" - }, - "text": { - "type": "string", - "description": "字段文本数据" - } + { + "items": { + "description": "颜色字符串，十六进制格式：#RRGGBB", + "type": "string" }, - "required": [ - "text" - ] + "minItems": 2 } - } + ], + "type": "array" }, - "dim2": { - "type": "object", - "description": "维度2配置（值维度）", + "font": { + "description": "字体配置", "properties": { - "series": { - "type": "array", - "description": "系列配置数组（非静态数据时传此参数）", - "items": { - "type": "object", - "properties": { - "index": { - "type": "number", - "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引" - }, - "aggregateType": { - "type": "string", - "description": "汇总方式，默认为'sum'，仅在 aggregate 为 true 时生效", - "enum": [ - "sum", - "average", - "count", - "min", - "max", - "median" - ] - }, - "nameRef": { - "type": "string", - "description": "可选。系列名称的单元格引用（A1 表示法，如 'Sheet1!C1'）。当系列名称不直接来自 refs 首行/首列时，可通过此字段把系列名显式指向目标表头单元格，图表会以该单元格当前值作为系列名（图例/tooltip）展示。" - } - } - } + "color": { + "description": "字体颜色，格式为 #RRGGBB", + "type": "string" }, - "fields": { - "type": "array", - "description": "字段配置数组（静态数据时传此参数）", - "items": { - "type": "object", - "properties": { - "valueType": { - "type": "string", - "description": "值类型", - "enum": [ - "number" - ] - }, - "name": { - "type": "string", - "description": "字段名称" - }, - "text": { - "type": "string", - "description": "字段文本数据" - } - }, - "required": [ - "text" - ] - } + "size": { + "description": "字体大小", + "type": "number" } - } + }, + "type": "object" } - } + }, + "type": "object" + }, + "subTitle": { + "description": "图表副标题配置", + "properties": { + "bold": { + "description": "是否加粗", + "type": "boolean" + }, + "color": { + "description": "字体颜色，格式为 #RRGGBB", + "type": "string" + }, + "fontSize": { + "description": "字体大小", + "type": "number" + }, + "italic": { + "description": "是否斜体", + "type": "boolean" + }, + "strikethrough": { + "description": "是否删除线", + "type": "boolean" + }, + "text": { + "description": "副标题文本", + "type": "string" + }, + "textAlign": { + "description": "副标题对齐方式", + "enum": [ + "left", + "center", + "right" + ], + "type": "string" + }, + "underline": { + "description": "是否下划线", + "type": "boolean" + } + }, + "required": [ + "text" + ], + "type": "object" + }, + "title": { + "description": "图表标题配置", + "properties": { + "bold": { + "description": "是否加粗", + "type": "boolean" + }, + "color": { + "description": "字体颜色，格式为 #RRGGBB", + "type": "string" + }, + "fontSize": { + "description": "字体大小", + "type": "number" + }, + "italic": { + "description": "是否斜体", + "type": "boolean" + }, + "strikethrough": { + "description": "是否删除线", + "type": "boolean" + }, + "text": { + "description": "标题文本", + "type": "string" + }, + "textAlign": { + "description": "标题对齐方式", + "enum": [ + "left", + "center", + "right" + ], + "type": "string" + }, + "underline": { + "description": "是否下划线", + "type": "boolean" + } + }, + "required": [ + "text" + ], + "type": "object" } - } + }, + "type": "object" } }, - "required": [ - "position", - "size" - ], - "additionalProperties": {} + "type": "object" } }, "+cond-format-create": { "properties": { + "additionalProperties": false, "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\"=加粗+斜体。" - } - }, - "additionalProperties": false - }, "attrs": { - "type": "array", "description": "规则参数列表。不同 rule_type 下取值结构不同。当 rule_type 为 dataBar 时，attrs 必须包含两个对象，分别定义正值和负值的数据条颜色。", "items": { "oneOf": [ { - "type": "object", + "additionalProperties": false, "description": "数值比较类规则参数。", "properties": { "compare_type": { - "type": "string", + "description": "比较运算符。", "enum": [ "equal", "notEqual", @@ -2882,29 +2824,25 @@ "between", "notBetween" ], - "description": "比较运算符。" + "type": "string" }, "value": { - "type": "string", - "description": "用于比较的值，例如 \"100\"、\"hello\"。between/notBetween 时用逗号分隔两个值。" + "description": "用于比较的值，例如 \"100\"、\"hello\"。between/notBetween 时用逗号分隔两个值。", + "type": "string" } }, "required": [ "compare_type", "value" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "文本包含类规则参数。", "properties": { - "text": { - "type": "string", - "description": "用于匹配的文本内容。" - }, "compare_type": { - "type": "string", + "description": "文本匹配方式。", "enum": [ "beginsWith", "endsWith", @@ -2912,30 +2850,34 @@ "notContains", "is" ], - "description": "文本匹配方式。" + "type": "string" + }, + "text": { + "description": "用于匹配的文本内容。", + "type": "string" } }, "required": [ "compare_type", "text" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "时间段类规则参数。", "properties": { "operator": { - "type": "string", + "description": "与指定时间段的比较关系。", "enum": [ "before", "is", "after" ], - "description": "与指定时间段的比较关系。" + "type": "string" }, "time_period": { - "type": "string", + "description": "时间段类型。", "enum": [ "today", "yesterday", @@ -2948,37 +2890,37 @@ "lastWeek", "nextWeek" ], - "description": "时间段类型。" + "type": "string" } }, "required": [ "operator", "time_period" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "数据条规则参数。", "properties": { - "gradient": { - "type": "boolean", - "description": "是否使用渐变色数据条。" - }, - "value": { - "type": "number", - "description": "阈值或比例值，含义由 value_type 决定。" - }, "color": { - "type": "string", - "description": "主颜色，例如 \"#63BE7B\"。" + "description": "主颜色，例如 \"#63BE7B\"。", + "type": "string" + }, + "gradient": { + "description": "是否使用渐变色数据条。", + "type": "boolean" }, "hide_value": { - "type": "boolean", - "description": "是否隐藏单元格中的原始值，仅显示数据条。" + "description": "是否隐藏单元格中的原始值，仅显示数据条。", + "type": "boolean" + }, + "value": { + "description": "阈值或比例值，含义由 value_type 决定。", + "type": "number" }, "value_type": { - "type": "string", + "description": "阈值类型。", "enum": [ "minValue", "maxValue", @@ -2988,21 +2930,29 @@ "formula", "auto" ], - "description": "阈值类型。" + "type": "string" } }, "required": [ "color", "value_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "色阶规则中的单个分段。ColorScaleAttrs 由 2 或 3 个该对象组成，分别表示最小值/中间值/最大值。", "properties": { + "color": { + "description": "该分段对应的颜色。", + "type": "string" + }, + "value": { + "description": "阈值数值，例如百分位或具体数值。", + "type": "number" + }, "value_type": { - "type": "string", + "description": "阈值类型。", "enum": [ "minValue", "maxValue", @@ -3012,93 +2962,89 @@ "formula", "auto" ], - "description": "阈值类型。" - }, - "value": { - "type": "number", - "description": "阈值数值，例如百分位或具体数值。" - }, - "color": { - "type": "string", - "description": "该分段对应的颜色。" + "type": "string" } }, "required": [ "value_type", "color" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "前 N/后 N 规则参数。", "properties": { "is_bottom": { - "type": "boolean", - "description": "是否选取最后 N 个。true 表示最后 N 个，false 表示前 N 个。" + "description": "是否选取最后 N 个。true 表示最后 N 个，false 表示前 N 个。", + "type": "boolean" + }, + "value": { + "description": "N 或百分比数值。", + "type": "number" }, "value_type": { - "type": "string", + "description": "排名方式：percent 表示百分比，sort 表示按条目数。", "enum": [ "percent", "sort" ], - "description": "排名方式：percent 表示百分比，sort 表示按条目数。" - }, - "value": { - "type": "number", - "description": "N 或百分比数值。" + "type": "string" } }, "required": [ "is_bottom", "value_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "平均值规则参数。", "properties": { "operator": { - "type": "string", + "description": "与平均值的比较关系。", "enum": [ "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual" ], - "description": "与平均值的比较关系。" + "type": "string" } }, "required": [ "operator" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "自定义公式规则参数。", "properties": { "formula": { - "type": "array", + "description": "条件公式列表，例如 [\"=A1>0\"]。", "items": { "type": "string" }, - "description": "条件公式列表，例如 [\"=A1>0\"]。" + "type": "array" } }, "required": [ "formula" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "图标集规则参数。", "properties": { + "hide_value": { + "description": "是否隐藏单元格原始值，仅显示图标。", + "type": "boolean" + }, "icon_type": { - "type": "string", + "description": "图标集类型。其中 3Circles/4Circles/5Circles 为不同颜色的实心圆（如红、黄、绿），用于表示状态等级；5CirclesRatio 为不同填充比例的圆（从空心◯到半圆◑到满圆●），用于表示完成度、进度、比例。当涉及半圆、满圆、空心圆、填充比例、进度等场景时，应选择 5CirclesRatio。", "enum": [ "3Arrows", "3ArrowsGray", @@ -3120,42 +3066,38 @@ "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": "阈值类型。" + "type": "string" }, "operator": { - "type": "string", + "description": "与阈值的比较关系。", "enum": [ "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual" ], - "description": "与阈值的比较关系。" - }, - "value": { - "type": "number", - "description": "用于比较的数值，含义由 value_type 决定。" - }, - "reverse_icons": { - "type": "boolean", - "description": "是否反转图标顺序。" + "type": "string" + }, + "reverse_icons": { + "description": "是否反转图标顺序。", + "type": "boolean" + }, + "value": { + "description": "用于比较的数值，含义由 value_type 决定。", + "type": "number" + }, + "value_type": { + "description": "阈值类型。", + "enum": [ + "minValue", + "maxValue", + "num", + "percentile", + "percent", + "formula", + "auto" + ], + "type": "string" } }, "required": [ @@ -3163,31 +3105,25 @@ "value_type", "operator" ], - "additionalProperties": false + "type": "object" } ] - } + }, + "type": "array" }, "has_ref": { - "type": "boolean", - "description": "可选。是否存在引用，用于标记规则是否依赖其他对象。" - } - }, - "required": [ - "rule_type", - "ranges", - "style" - ], - "additionalProperties": false - } - }, - "+cond-format-update": { - "properties": { - "description": "创建/更新的条件格式属性。", - "type": "object", - "properties": { + "description": "可选。是否存在引用，用于标记规则是否依赖其他对象。", + "type": "boolean" + }, + "ranges": { + "description": "应用条件格式的 A1 范围列表。每个元素支持：矩形范围 \"A1:A10\"、整行 \"3:6\"、整列 \"C:C\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。例如 [\"A1:A10\",\"C:C\"]。", + "items": { + "type": "string" + }, + "type": "array" + }, "rule_type": { - "type": "string", + "description": "条件格式规则类型。", "enum": [ "duplicateValues", "uniqueValues", @@ -3203,60 +3139,66 @@ "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" - } + "type": "string" }, "style": { - "type": "object", + "additionalProperties": false, "description": "命中规则时应用的单元格样式。", "properties": { "back_color": { - "type": "string", - "description": "背景色，CSS 十六进制表示，例如 \"#FF0000\"。" + "description": "背景色，CSS 十六进制表示，例如 \"#FF0000\"。", + "type": "string" + }, + "font": { + "description": "字体样式：\"bold\"=加粗，\"italic\"=斜体，\"bold italic\"=加粗+斜体。", + "enum": [ + "bold", + "italic", + "bold italic" + ], + "type": "string" }, "fore_color": { - "type": "string", - "description": "前景色/字体颜色。" + "description": "前景色/字体颜色。", + "type": "string" }, "text_decoration": { - "type": "string", + "description": "文字装饰：none=无，underline=下划线，strikethrough=删除线，underline_strikethrough=下划线+删除线。", "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\"=加粗+斜体。" + "type": "string" } }, - "additionalProperties": false - }, + "type": "object" + } + }, + "required": [ + "rule_type", + "ranges", + "style" + ], + "type": "object" + } + }, + "+cond-format-update": { + "properties": { + "additionalProperties": false, + "description": "创建/更新的条件格式属性。", + "properties": { "attrs": { - "type": "array", "description": "规则参数列表。不同 rule_type 下取值结构不同。当 rule_type 为 dataBar 时，attrs 必须包含两个对象，分别定义正值和负值的数据条颜色。", "items": { "oneOf": [ { - "type": "object", + "additionalProperties": false, "description": "数值比较类规则参数。", "properties": { "compare_type": { - "type": "string", + "description": "比较运算符。", "enum": [ "equal", "notEqual", @@ -3267,29 +3209,25 @@ "between", "notBetween" ], - "description": "比较运算符。" + "type": "string" }, "value": { - "type": "string", - "description": "用于比较的值，例如 \"100\"、\"hello\"。between/notBetween 时用逗号分隔两个值。" + "description": "用于比较的值，例如 \"100\"、\"hello\"。between/notBetween 时用逗号分隔两个值。", + "type": "string" } }, "required": [ "compare_type", "value" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "文本包含类规则参数。", "properties": { - "text": { - "type": "string", - "description": "用于匹配的文本内容。" - }, "compare_type": { - "type": "string", + "description": "文本匹配方式。", "enum": [ "beginsWith", "endsWith", @@ -3297,30 +3235,34 @@ "notContains", "is" ], - "description": "文本匹配方式。" + "type": "string" + }, + "text": { + "description": "用于匹配的文本内容。", + "type": "string" } }, "required": [ "compare_type", "text" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "时间段类规则参数。", "properties": { "operator": { - "type": "string", + "description": "与指定时间段的比较关系。", "enum": [ "before", "is", "after" ], - "description": "与指定时间段的比较关系。" + "type": "string" }, "time_period": { - "type": "string", + "description": "时间段类型。", "enum": [ "today", "yesterday", @@ -3333,37 +3275,37 @@ "lastWeek", "nextWeek" ], - "description": "时间段类型。" + "type": "string" } }, "required": [ "operator", "time_period" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "数据条规则参数。", "properties": { - "gradient": { - "type": "boolean", - "description": "是否使用渐变色数据条。" - }, - "value": { - "type": "number", - "description": "阈值或比例值，含义由 value_type 决定。" - }, "color": { - "type": "string", - "description": "主颜色，例如 \"#63BE7B\"。" + "description": "主颜色，例如 \"#63BE7B\"。", + "type": "string" + }, + "gradient": { + "description": "是否使用渐变色数据条。", + "type": "boolean" }, "hide_value": { - "type": "boolean", - "description": "是否隐藏单元格中的原始值，仅显示数据条。" + "description": "是否隐藏单元格中的原始值，仅显示数据条。", + "type": "boolean" + }, + "value": { + "description": "阈值或比例值，含义由 value_type 决定。", + "type": "number" }, "value_type": { - "type": "string", + "description": "阈值类型。", "enum": [ "minValue", "maxValue", @@ -3373,21 +3315,29 @@ "formula", "auto" ], - "description": "阈值类型。" + "type": "string" } }, "required": [ "color", "value_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "色阶规则中的单个分段。ColorScaleAttrs 由 2 或 3 个该对象组成，分别表示最小值/中间值/最大值。", "properties": { + "color": { + "description": "该分段对应的颜色。", + "type": "string" + }, + "value": { + "description": "阈值数值，例如百分位或具体数值。", + "type": "number" + }, "value_type": { - "type": "string", + "description": "阈值类型。", "enum": [ "minValue", "maxValue", @@ -3397,93 +3347,89 @@ "formula", "auto" ], - "description": "阈值类型。" - }, - "value": { - "type": "number", - "description": "阈值数值，例如百分位或具体数值。" - }, - "color": { - "type": "string", - "description": "该分段对应的颜色。" + "type": "string" } }, "required": [ "value_type", "color" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "前 N/后 N 规则参数。", "properties": { "is_bottom": { - "type": "boolean", - "description": "是否选取最后 N 个。true 表示最后 N 个，false 表示前 N 个。" + "description": "是否选取最后 N 个。true 表示最后 N 个，false 表示前 N 个。", + "type": "boolean" + }, + "value": { + "description": "N 或百分比数值。", + "type": "number" }, "value_type": { - "type": "string", + "description": "排名方式：percent 表示百分比，sort 表示按条目数。", "enum": [ "percent", "sort" ], - "description": "排名方式：percent 表示百分比，sort 表示按条目数。" - }, - "value": { - "type": "number", - "description": "N 或百分比数值。" + "type": "string" } }, "required": [ "is_bottom", "value_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "平均值规则参数。", "properties": { "operator": { - "type": "string", + "description": "与平均值的比较关系。", "enum": [ "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual" ], - "description": "与平均值的比较关系。" + "type": "string" } }, "required": [ "operator" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "自定义公式规则参数。", "properties": { "formula": { - "type": "array", + "description": "条件公式列表，例如 [\"=A1>0\"]。", "items": { "type": "string" }, - "description": "条件公式列表，例如 [\"=A1>0\"]。" + "type": "array" } }, "required": [ "formula" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "图标集规则参数。", "properties": { + "hide_value": { + "description": "是否隐藏单元格原始值，仅显示图标。", + "type": "boolean" + }, "icon_type": { - "type": "string", + "description": "图标集类型。其中 3Circles/4Circles/5Circles 为不同颜色的实心圆（如红、黄、绿），用于表示状态等级；5CirclesRatio 为不同填充比例的圆（从空心◯到半圆◑到满圆●），用于表示完成度、进度、比例。当涉及半圆、满圆、空心圆、填充比例、进度等场景时，应选择 5CirclesRatio。", "enum": [ "3Arrows", "3ArrowsGray", @@ -3505,14 +3451,28 @@ "3Mood", "5CirclesRatio" ], - "description": "图标集类型。其中 3Circles/4Circles/5Circles 为不同颜色的实心圆（如红、黄、绿），用于表示状态等级；5CirclesRatio 为不同填充比例的圆（从空心◯到半圆◑到满圆●），用于表示完成度、进度、比例。当涉及半圆、满圆、空心圆、填充比例、进度等场景时，应选择 5CirclesRatio。" + "type": "string" }, - "hide_value": { - "type": "boolean", - "description": "是否隐藏单元格原始值，仅显示图标。" + "operator": { + "description": "与阈值的比较关系。", + "enum": [ + "greaterThan", + "greaterThanOrEqual", + "lessThan", + "lessThanOrEqual" + ], + "type": "string" + }, + "reverse_icons": { + "description": "是否反转图标顺序。", + "type": "boolean" + }, + "value": { + "description": "用于比较的数值，含义由 value_type 决定。", + "type": "number" }, "value_type": { - "type": "string", + "description": "阈值类型。", "enum": [ "minValue", "maxValue", @@ -3522,25 +3482,7 @@ "formula", "auto" ], - "description": "阈值类型。" - }, - "operator": { - "type": "string", - "enum": [ - "greaterThan", - "greaterThanOrEqual", - "lessThan", - "lessThanOrEqual" - ], - "description": "与阈值的比较关系。" - }, - "value": { - "type": "number", - "description": "用于比较的数值，含义由 value_type 决定。" - }, - "reverse_icons": { - "type": "boolean", - "description": "是否反转图标顺序。" + "type": "string" } }, "required": [ @@ -3548,14 +3490,75 @@ "value_type", "operator" ], - "additionalProperties": false + "type": "object" } ] - } + }, + "type": "array" }, "has_ref": { - "type": "boolean", - "description": "可选。是否存在引用，用于标记规则是否依赖其他对象。" + "description": "可选。是否存在引用，用于标记规则是否依赖其他对象。", + "type": "boolean" + }, + "ranges": { + "description": "应用条件格式的 A1 范围列表。每个元素支持：矩形范围 \"A1:A10\"、整行 \"3:6\"、整列 \"C:C\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。例如 [\"A1:A10\",\"C:C\"]。", + "items": { + "type": "string" + }, + "type": "array" + }, + "rule_type": { + "description": "条件格式规则类型。", + "enum": [ + "duplicateValues", + "uniqueValues", + "cellIs", + "containsText", + "timePeriod", + "containsBlanks", + "notContainsBlanks", + "dataBar", + "colorScale", + "rank", + "aboveAverage", + "expression", + "iconSet" + ], + "type": "string" + }, + "style": { + "additionalProperties": false, + "description": "命中规则时应用的单元格样式。", + "properties": { + "back_color": { + "description": "背景色，CSS 十六进制表示，例如 \"#FF0000\"。", + "type": "string" + }, + "font": { + "description": "字体样式：\"bold\"=加粗，\"italic\"=斜体，\"bold italic\"=加粗+斜体。", + "enum": [ + "bold", + "italic", + "bold italic" + ], + "type": "string" + }, + "fore_color": { + "description": "前景色/字体颜色。", + "type": "string" + }, + "text_decoration": { + "description": "文字装饰：none=无，underline=下划线，strikethrough=删除线，underline_strikethrough=下划线+删除线。", + "enum": [ + "none", + "underline", + "strikethrough", + "underline_strikethrough" + ], + "type": "string" + } + }, + "type": "object" } }, "required": [ @@ -3563,65 +3566,63 @@ "ranges", "style" ], - "additionalProperties": false + "type": "object" } }, "+dropdown-set": { "options": { - "description": "列表选项", - "type": "array", + "description": "列表选项（type='list' 时必填）", "items": { "type": "string" - } + }, + "type": "array" } }, "+dropdown-update": { "options": { - "description": "列表选项", - "type": "array", + "description": "列表选项（type='list' 时必填）", "items": { "type": "string" - } + }, + "type": "array" } }, "+filter-create": { "properties": { + "additionalProperties": false, "description": "创建/更新的筛选器属性。", - "type": "object", "properties": { + "filtered_columns": { + "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", + "items": { + "type": "string" + }, + "type": "array" + }, "range": { - "type": "string", - "description": "筛选对象作用的单元格范围（A1 表示法）。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。" + "description": "筛选对象作用的单元格范围（A1 表示法）。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。", + "type": "string" }, "rules": { - "type": "array", "description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。update 时传空数组 [] 表示清空所有现有列的规则。", "items": { - "type": "object", + "additionalProperties": false, "description": "单列筛选规则。", "properties": { "column_index": { - "type": "string", - "description": "作用的列索引，例如 \"A\"、\"B\"。" + "description": "作用的列索引，例如 \"A\"、\"B\"。", + "type": "string" }, "conditions": { - "type": "array", "description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。", "items": { "oneOf": [ { - "type": "object", + "additionalProperties": false, "description": "文本条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "text" - ], - "description": "条件类型固定为 \"text\"。" - }, "compare_type": { - "type": "string", + "description": "文本比较方式：beginsWith=以指定文本开头，doesNotBeginWith=不以指定文本开头，endsWith=以指定文本结尾，doesNotEndWith=不以指定文本结尾，contains=包含，doesNotContain=不包含，equals=等于，notEquals=不等于。", "enum": [ "beginsWith", "doesNotBeginWith", @@ -3632,35 +3633,35 @@ "equals", "notEquals" ], - "description": "文本比较方式：beginsWith=以指定文本开头，doesNotBeginWith=不以指定文本开头，endsWith=以指定文本结尾，doesNotEndWith=不以指定文本结尾，contains=包含，doesNotContain=不包含，equals=等于，notEquals=不等于。" + "type": "string" + }, + "type": { + "description": "条件类型固定为 \"text\"。", + "enum": [ + "text" + ], + "type": "string" }, "values": { - "type": "array", "description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。", "items": { "type": "string" - } + }, + "type": "array" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "数值条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "number" - ], - "description": "条件类型固定为 \"number\"。" - }, "compare_type": { - "type": "string", + "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。", "enum": [ "equal", "notEqual", @@ -3671,10 +3672,16 @@ "between", "notBetween" ], - "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。" + "type": "string" + }, + "type": { + "description": "条件类型固定为 \"number\"。", + "enum": [ + "number" + ], + "type": "string" }, "values": { - "type": "array", "description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。", "items": { "oneOf": [ @@ -3685,82 +3692,73 @@ "type": "string" } ] - } + }, + "type": "array" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "颜色条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "color" - ], - "description": "条件类型固定为 \"color\"。" - }, "compare_type": { - "type": "string", + "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。", "enum": [ "backgroundColor", "foregroundColor" ], - "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。" + "type": "string" + }, + "type": { + "description": "条件类型固定为 \"color\"。", + "enum": [ + "color" + ], + "type": "string" }, "value": { - "type": "string", - "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。" + "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。", + "type": "string" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "多值条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "multiValue" - ], - "description": "条件类型固定为 \"multiValue\"。" - }, "compare_type": { - "type": "string", + "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。", "enum": [ "equal", "notEqual" ], - "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。" - }, - "values": { - "type": "array", - "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", - "items": { - "type": "string" - } + "type": "string" }, "date_groups": { - "type": "array", "description": "可选。年月日等聚合筛选信息。", "items": { - "type": "object", + "additionalProperties": false, "properties": { - "year": { - "type": "number" - }, - "month": { - "type": "number" + "date_time_grouping": { + "enum": [ + "year", + "month", + "day", + "hour", + "minute", + "second" + ], + "type": "string" }, "day": { "type": "number" @@ -3771,102 +3769,105 @@ "minute": { "type": "number" }, + "month": { + "type": "number" + }, "second": { "type": "number" }, - "date_time_grouping": { - "type": "string", - "enum": [ - "year", - "month", - "day", - "hour", - "minute", - "second" - ] + "year": { + "type": "number" } }, - "additionalProperties": false - } + "type": "object" + }, + "type": "array" + }, + "type": { + "description": "条件类型固定为 \"multiValue\"。", + "enum": [ + "multiValue" + ], + "type": "string" + }, + "values": { + "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", + "items": { + "type": "string" + }, + "type": "array" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" } ] - } + }, + "type": "array" }, "filtered_rows": { - "type": "array", "description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。", "items": { "type": "number" - } + }, + "type": "array" } }, "required": [ "column_index", "conditions" ], - "additionalProperties": false - } - }, - "filtered_columns": { - "type": "array", - "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", - "items": { - "type": "string" - } + "type": "object" + }, + "type": "array" } }, "required": [ "range", "rules" ], - "additionalProperties": false + "type": "object" } }, "+filter-update": { "properties": { + "additionalProperties": false, "description": "创建/更新的筛选器属性。", - "type": "object", "properties": { + "filtered_columns": { + "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", + "items": { + "type": "string" + }, + "type": "array" + }, "range": { - "type": "string", - "description": "筛选对象作用的单元格范围（A1 表示法）。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。" + "description": "筛选对象作用的单元格范围（A1 表示法）。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。", + "type": "string" }, "rules": { - "type": "array", "description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。update 时传空数组 [] 表示清空所有现有列的规则。", "items": { - "type": "object", + "additionalProperties": false, "description": "单列筛选规则。", "properties": { "column_index": { - "type": "string", - "description": "作用的列索引，例如 \"A\"、\"B\"。" + "description": "作用的列索引，例如 \"A\"、\"B\"。", + "type": "string" }, "conditions": { - "type": "array", "description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。", "items": { "oneOf": [ { - "type": "object", + "additionalProperties": false, "description": "文本条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "text" - ], - "description": "条件类型固定为 \"text\"。" - }, "compare_type": { - "type": "string", + "description": "文本比较方式：beginsWith=以指定文本开头，doesNotBeginWith=不以指定文本开头，endsWith=以指定文本结尾，doesNotEndWith=不以指定文本结尾，contains=包含，doesNotContain=不包含，equals=等于，notEquals=不等于。", "enum": [ "beginsWith", "doesNotBeginWith", @@ -3877,35 +3878,35 @@ "equals", "notEquals" ], - "description": "文本比较方式：beginsWith=以指定文本开头，doesNotBeginWith=不以指定文本开头，endsWith=以指定文本结尾，doesNotEndWith=不以指定文本结尾，contains=包含，doesNotContain=不包含，equals=等于，notEquals=不等于。" + "type": "string" + }, + "type": { + "description": "条件类型固定为 \"text\"。", + "enum": [ + "text" + ], + "type": "string" }, "values": { - "type": "array", "description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。", "items": { "type": "string" - } + }, + "type": "array" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "数值条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "number" - ], - "description": "条件类型固定为 \"number\"。" - }, "compare_type": { - "type": "string", + "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。", "enum": [ "equal", "notEqual", @@ -3916,10 +3917,16 @@ "between", "notBetween" ], - "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。" + "type": "string" + }, + "type": { + "description": "条件类型固定为 \"number\"。", + "enum": [ + "number" + ], + "type": "string" }, "values": { - "type": "array", "description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。", "items": { "oneOf": [ @@ -3930,82 +3937,73 @@ "type": "string" } ] - } + }, + "type": "array" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "颜色条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "color" - ], - "description": "条件类型固定为 \"color\"。" - }, "compare_type": { - "type": "string", + "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。", "enum": [ "backgroundColor", "foregroundColor" ], - "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。" + "type": "string" + }, + "type": { + "description": "条件类型固定为 \"color\"。", + "enum": [ + "color" + ], + "type": "string" }, "value": { - "type": "string", - "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。" + "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。", + "type": "string" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "多值条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "multiValue" - ], - "description": "条件类型固定为 \"multiValue\"。" - }, "compare_type": { - "type": "string", + "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。", "enum": [ "equal", "notEqual" ], - "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。" - }, - "values": { - "type": "array", - "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", - "items": { - "type": "string" - } + "type": "string" }, "date_groups": { - "type": "array", "description": "可选。年月日等聚合筛选信息。", "items": { - "type": "object", + "additionalProperties": false, "properties": { - "year": { - "type": "number" - }, - "month": { - "type": "number" + "date_time_grouping": { + "enum": [ + "year", + "month", + "day", + "hour", + "minute", + "second" + ], + "type": "string" }, "day": { "type": "number" @@ -4016,106 +4014,105 @@ "minute": { "type": "number" }, + "month": { + "type": "number" + }, "second": { "type": "number" }, - "date_time_grouping": { - "type": "string", - "enum": [ - "year", - "month", - "day", - "hour", - "minute", - "second" - ] + "year": { + "type": "number" } }, - "additionalProperties": false - } + "type": "object" + }, + "type": "array" + }, + "type": { + "description": "条件类型固定为 \"multiValue\"。", + "enum": [ + "multiValue" + ], + "type": "string" + }, + "values": { + "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", + "items": { + "type": "string" + }, + "type": "array" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" } ] - } + }, + "type": "array" }, "filtered_rows": { - "type": "array", "description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。", "items": { "type": "number" - } + }, + "type": "array" } }, "required": [ "column_index", "conditions" ], - "additionalProperties": false - } - }, - "filtered_columns": { - "type": "array", - "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", - "items": { - "type": "string" - } + "type": "object" + }, + "type": "array" } }, "required": [ "range", "rules" ], - "additionalProperties": false + "type": "object" } }, "+filter-view-create": { "properties": { + "additionalProperties": false, "description": "create / update 的视图属性。create 必须传 range；update 至少传 view_name / range / rules 之一。delete 禁止传该字段。", - "type": "object", "properties": { - "view_name": { - "type": "string", - "description": "可选。视图名称。create 不传时系统自动分配；create / update 传入时若与现有视图重名，会自动以后缀避让，不会抛错。" + "filtered_columns": { + "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", + "items": { + "type": "string" + }, + "type": "array" }, "range": { - "type": "string", - "description": "视图作用的单元格范围（A1 表示法）。create 必填；update 可选——未提供时沿用视图当前 range。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。" + "description": "视图作用的单元格范围（A1 表示法）。create 必填；update 可选——未提供时沿用视图当前 range。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。", + "type": "string" }, "rules": { - "type": "array", "description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。结构与 manage_filter_object.properties.rules 完全一致。", "items": { - "type": "object", + "additionalProperties": false, "description": "单列筛选规则。", "properties": { "column_index": { - "type": "string", - "description": "作用的列索引，例如 \"A\"、\"B\"。" + "description": "作用的列索引，例如 \"A\"、\"B\"。", + "type": "string" }, "conditions": { - "type": "array", "description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。", "items": { "oneOf": [ { - "type": "object", + "additionalProperties": false, "description": "文本条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "text" - ], - "description": "条件类型固定为 \"text\"。" - }, "compare_type": { - "type": "string", + "description": "文本比较方式:beginsWith=以指定文本开头,doesNotBeginWith=不以指定文本开头,endsWith=以指定文本结尾,doesNotEndWith=不以指定文本结尾,contains=包含,doesNotContain=不包含,equals=等于,notEquals=不等于。", "enum": [ "beginsWith", "doesNotBeginWith", @@ -4126,35 +4123,35 @@ "equals", "notEquals" ], - "description": "文本比较方式:beginsWith=以指定文本开头,doesNotBeginWith=不以指定文本开头,endsWith=以指定文本结尾,doesNotEndWith=不以指定文本结尾,contains=包含,doesNotContain=不包含,equals=等于,notEquals=不等于。" + "type": "string" + }, + "type": { + "description": "条件类型固定为 \"text\"。", + "enum": [ + "text" + ], + "type": "string" }, "values": { - "type": "array", "description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。", "items": { "type": "string" - } + }, + "type": "array" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "数值条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "number" - ], - "description": "条件类型固定为 \"number\"。" - }, "compare_type": { - "type": "string", + "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。", "enum": [ "equal", "notEqual", @@ -4165,10 +4162,16 @@ "between", "notBetween" ], - "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。" + "type": "string" + }, + "type": { + "description": "条件类型固定为 \"number\"。", + "enum": [ + "number" + ], + "type": "string" }, "values": { - "type": "array", "description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。", "items": { "oneOf": [ @@ -4179,82 +4182,73 @@ "type": "string" } ] - } + }, + "type": "array" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "颜色条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "color" - ], - "description": "条件类型固定为 \"color\"。" - }, "compare_type": { - "type": "string", + "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。", "enum": [ "backgroundColor", "foregroundColor" ], - "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。" + "type": "string" + }, + "type": { + "description": "条件类型固定为 \"color\"。", + "enum": [ + "color" + ], + "type": "string" }, "value": { - "type": "string", - "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。" + "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。", + "type": "string" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "多值条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "multiValue" - ], - "description": "条件类型固定为 \"multiValue\"。" - }, "compare_type": { - "type": "string", + "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。", "enum": [ "equal", "notEqual" ], - "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。" - }, - "values": { - "type": "array", - "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", - "items": { - "type": "string" - } + "type": "string" }, "date_groups": { - "type": "array", "description": "可选。年月日等聚合筛选信息。", "items": { - "type": "object", + "additionalProperties": false, "properties": { - "year": { - "type": "number" - }, - "month": { - "type": "number" + "date_time_grouping": { + "enum": [ + "year", + "month", + "day", + "hour", + "minute", + "second" + ], + "type": "string" }, "day": { "type": "number" @@ -4265,102 +4259,105 @@ "minute": { "type": "number" }, + "month": { + "type": "number" + }, "second": { "type": "number" }, - "date_time_grouping": { - "type": "string", - "enum": [ - "year", - "month", - "day", - "hour", - "minute", - "second" - ] + "year": { + "type": "number" } }, - "additionalProperties": false - } + "type": "object" + }, + "type": "array" + }, + "type": { + "description": "条件类型固定为 \"multiValue\"。", + "enum": [ + "multiValue" + ], + "type": "string" + }, + "values": { + "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", + "items": { + "type": "string" + }, + "type": "array" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" } ] - } + }, + "type": "array" }, "filtered_rows": { - "type": "array", "description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。", "items": { "type": "number" - } + }, + "type": "array" } }, "required": [ "column_index", "conditions" ], - "additionalProperties": false - } + "type": "object" + }, + "type": "array" }, - "filtered_columns": { - "type": "array", - "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", - "items": { - "type": "string" - } + "view_name": { + "description": "可选。视图名称。create 不传时系统自动分配；create / update 传入时若与现有视图重名，会自动以后缀避让，不会抛错。", + "type": "string" } }, - "additionalProperties": false + "type": "object" } }, "+filter-view-update": { "properties": { + "additionalProperties": false, "description": "create / update 的视图属性。create 必须传 range；update 至少传 view_name / range / rules 之一。delete 禁止传该字段。", - "type": "object", "properties": { - "view_name": { - "type": "string", - "description": "可选。视图名称。create 不传时系统自动分配；create / update 传入时若与现有视图重名，会自动以后缀避让，不会抛错。" + "filtered_columns": { + "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", + "items": { + "type": "string" + }, + "type": "array" }, "range": { - "type": "string", - "description": "视图作用的单元格范围（A1 表示法）。create 必填；update 可选——未提供时沿用视图当前 range。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。" + "description": "视图作用的单元格范围（A1 表示法）。create 必填；update 可选——未提供时沿用视图当前 range。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。", + "type": "string" }, "rules": { - "type": "array", "description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。结构与 manage_filter_object.properties.rules 完全一致。", "items": { - "type": "object", + "additionalProperties": false, "description": "单列筛选规则。", "properties": { "column_index": { - "type": "string", - "description": "作用的列索引，例如 \"A\"、\"B\"。" + "description": "作用的列索引，例如 \"A\"、\"B\"。", + "type": "string" }, "conditions": { - "type": "array", "description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。", "items": { "oneOf": [ { - "type": "object", + "additionalProperties": false, "description": "文本条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "text" - ], - "description": "条件类型固定为 \"text\"。" - }, "compare_type": { - "type": "string", + "description": "文本比较方式:beginsWith=以指定文本开头,doesNotBeginWith=不以指定文本开头,endsWith=以指定文本结尾,doesNotEndWith=不以指定文本结尾,contains=包含,doesNotContain=不包含,equals=等于,notEquals=不等于。", "enum": [ "beginsWith", "doesNotBeginWith", @@ -4371,35 +4368,35 @@ "equals", "notEquals" ], - "description": "文本比较方式:beginsWith=以指定文本开头,doesNotBeginWith=不以指定文本开头,endsWith=以指定文本结尾,doesNotEndWith=不以指定文本结尾,contains=包含,doesNotContain=不包含,equals=等于,notEquals=不等于。" + "type": "string" + }, + "type": { + "description": "条件类型固定为 \"text\"。", + "enum": [ + "text" + ], + "type": "string" }, "values": { - "type": "array", "description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。", "items": { "type": "string" - } + }, + "type": "array" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "数值条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "number" - ], - "description": "条件类型固定为 \"number\"。" - }, "compare_type": { - "type": "string", + "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。", "enum": [ "equal", "notEqual", @@ -4410,10 +4407,16 @@ "between", "notBetween" ], - "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。" + "type": "string" + }, + "type": { + "description": "条件类型固定为 \"number\"。", + "enum": [ + "number" + ], + "type": "string" }, "values": { - "type": "array", "description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。", "items": { "oneOf": [ @@ -4424,82 +4427,73 @@ "type": "string" } ] - } + }, + "type": "array" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "颜色条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "color" - ], - "description": "条件类型固定为 \"color\"。" - }, "compare_type": { - "type": "string", + "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。", "enum": [ "backgroundColor", "foregroundColor" ], - "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。" + "type": "string" + }, + "type": { + "description": "条件类型固定为 \"color\"。", + "enum": [ + "color" + ], + "type": "string" }, "value": { - "type": "string", - "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。" + "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。", + "type": "string" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" }, { - "type": "object", + "additionalProperties": false, "description": "多值条件筛选。", "properties": { - "type": { - "type": "string", - "enum": [ - "multiValue" - ], - "description": "条件类型固定为 \"multiValue\"。" - }, "compare_type": { - "type": "string", + "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。", "enum": [ "equal", "notEqual" ], - "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。" - }, - "values": { - "type": "array", - "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", - "items": { - "type": "string" - } + "type": "string" }, "date_groups": { - "type": "array", "description": "可选。年月日等聚合筛选信息。", "items": { - "type": "object", + "additionalProperties": false, "properties": { - "year": { - "type": "number" - }, - "month": { - "type": "number" + "date_time_grouping": { + "enum": [ + "year", + "month", + "day", + "hour", + "minute", + "second" + ], + "type": "string" }, "day": { "type": "number" @@ -4510,148 +4504,137 @@ "minute": { "type": "number" }, + "month": { + "type": "number" + }, "second": { "type": "number" }, - "date_time_grouping": { - "type": "string", - "enum": [ - "year", - "month", - "day", - "hour", - "minute", - "second" - ] + "year": { + "type": "number" } }, - "additionalProperties": false - } + "type": "object" + }, + "type": "array" + }, + "type": { + "description": "条件类型固定为 \"multiValue\"。", + "enum": [ + "multiValue" + ], + "type": "string" + }, + "values": { + "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", + "items": { + "type": "string" + }, + "type": "array" } }, "required": [ "type", "compare_type" ], - "additionalProperties": false + "type": "object" } ] - } + }, + "type": "array" }, "filtered_rows": { - "type": "array", "description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。", "items": { "type": "number" - } + }, + "type": "array" } }, "required": [ "column_index", "conditions" ], - "additionalProperties": false - } + "type": "object" + }, + "type": "array" }, - "filtered_columns": { - "type": "array", - "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", - "items": { - "type": "string" - } + "view_name": { + "description": "可选。视图名称。create 不传时系统自动分配；create / update 传入时若与现有视图重名，会自动以后缀避让，不会抛错。", + "type": "string" } }, - "additionalProperties": false + "type": "object" } }, "+pivot-create": { "properties": { + "additionalProperties": {}, "description": "创建/更新的透视表属性。", - "type": "object", "properties": { - "range": { - "type": "string", - "description": "放置透视表的左上角单元格 A1 地址（例如：'F1'）（仅 create 时有效）。可省略——省略后透视表放在新建子表的 A1 位置。" - }, - "source": { - "type": "string", - "description": "源数据区域地址，格式为 'SheetName!StartCell:EndCell'（例如：'Sheet1!A1:D100'）。create 时必填；update 时提供则切换数据源。" + "auto_fit_col": { + "description": "是否自动调整列宽以适应内容", + "type": "boolean" }, - "rows": { - "description": "纵向分组字段（行字段）", - "type": "array", + "calculated_fields": { + "description": "计算字段列表", "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" - ] + "formula": { + "description": "公式表达式，引用其他字段名，例如 \"'Sales' + 'Tax'\"", + "type": "string" }, - "filter": { - "type": "object", - "description": "快速筛选：只显示指定的项目", - "properties": { - "items": { - "type": "array", - "items": { - "type": "string" - }, - "description": "要显示的项目列表（其余项目被隐藏）" - } - }, - "required": [ - "items" - ] + "name": { + "description": "计算字段的显示名称", + "type": "string" }, + "summarize_by": { + "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" + ], + "type": "string" + } + }, + "required": [ + "name", + "formula" + ], + "type": "object" + }, + "type": "array" + }, + "collapse": { + "additionalProperties": { + "items": { + "type": "string" + }, + "type": "array" + }, + "description": "行字段展开/折叠状态：字段名 -> 要折叠的项目列表", + "type": "object" + }, + "columns": { + "description": "横向分组字段（列字段）", + "items": { + "properties": { "condition_filter": { - "type": "object", "description": "条件筛选：按文本/数值/日期条件筛选", "properties": { + "operator": { + "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", + "type": "string" + }, "type": { - "type": "string", + "description": "条件类型", "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" + "type": "string" }, "value": { "description": "比较值" @@ -4663,23 +4646,38 @@ "required": [ "type", "operator" - ] + ], + "type": "object" + }, + "display_name": { + "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。", + "type": "string" + }, + "field": { + "description": "源数据中的字段名（OOXML 字段引用）", + "type": "string" + }, + "filter": { + "description": "快速筛选：只显示指定的项目", + "properties": { + "items": { + "description": "要显示的项目列表（其余项目被隐藏）", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "items" + ], + "type": "object" }, "group": { - "type": "object", "description": "分组配置", "properties": { - "type": { - "type": "string", - "enum": [ - "date", - "number", - "element" - ], - "description": "分组类型" - }, "date_group_by": { - "type": "string", + "description": "日期分组粒度（type='date' 时必填）", "enum": [ "year", "yearMonth", @@ -4693,116 +4691,101 @@ "hourMinute", "minute" ], - "description": "日期分组粒度（type='date' 时必填）" - }, - "interval": { - "type": "number", - "description": "数值分组间隔（type='number' 时必填）" - }, - "start": { - "type": "number", - "description": "数值分组起始值" + "type": "string" }, "end": { - "type": "number", - "description": "数值分组结束值" + "description": "数值分组结束值", + "type": "number" }, "groups": { - "type": "object", - "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { - "type": "array", "items": { "type": "string" - } - } + }, + "type": "array" + }, + "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", + "type": "object" + }, + "interval": { + "description": "数值分组间隔（type='number' 时必填）", + "type": "number" + }, + "start": { + "description": "数值分组起始值", + "type": "number" + }, + "type": { + "description": "分组类型", + "enum": [ + "date", + "number", + "element" + ], + "type": "string" } }, "required": [ "type" - ] - } - }, - "required": [ - "field" - ] - } - }, - "columns": { - "description": "横向分组字段（列字段）", - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string", - "description": "源数据中的字段名（OOXML 字段引用）" - }, - "display_name": { - "type": "string", - "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。" + ], + "type": "object" }, "sort": { - "type": "object", "description": "排序配置", "properties": { - "order": { - "type": "string", - "enum": [ - "asc", - "desc" - ], - "description": "排序方向" - }, "by": { - "type": "string", + "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序", "enum": [ "label", "value" ], - "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序" + "type": "string" + }, + "order": { + "description": "排序方向", + "enum": [ + "asc", + "desc" + ], + "type": "string" }, "value_field": { - "type": "string", - "description": "by='value' 时必填，指定按哪个值字段排序" + "description": "by='value' 时必填，指定按哪个值字段排序", + "type": "string" } }, "required": [ "order" - ] - }, - "filter": { - "type": "object", - "description": "快速筛选：只显示指定的项目", - "properties": { - "items": { - "type": "array", - "items": { - "type": "string" - }, - "description": "要显示的项目列表（其余项目被隐藏）" - } - }, - "required": [ - "items" - ] - }, + ], + "type": "object" + } + }, + "required": [ + "field" + ], + "type": "object" + }, + "type": "array" + }, + "filters": { + "description": "筛选区域字段（页字段）", + "items": { + "properties": { "condition_filter": { - "type": "object", "description": "条件筛选：按文本/数值/日期条件筛选", "properties": { + "operator": { + "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", + "type": "string" + }, "type": { - "type": "string", + "description": "条件类型", "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" + "type": "string" }, "value": { "description": "比较值" @@ -4814,23 +4797,38 @@ "required": [ "type", "operator" - ] + ], + "type": "object" + }, + "display_name": { + "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。", + "type": "string" + }, + "field": { + "description": "源数据中的字段名（OOXML 字段引用）", + "type": "string" + }, + "filter": { + "description": "快速筛选：只显示指定的项目", + "properties": { + "items": { + "description": "要显示的项目列表（其余项目被隐藏）", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "items" + ], + "type": "object" }, "group": { - "type": "object", "description": "分组配置", "properties": { - "type": { - "type": "string", - "enum": [ - "date", - "number", - "element" - ], - "description": "分组类型" - }, "date_group_by": { - "type": "string", + "description": "日期分组粒度（type='date' 时必填）", "enum": [ "year", "yearMonth", @@ -4844,87 +4842,80 @@ "hourMinute", "minute" ], - "description": "日期分组粒度（type='date' 时必填）" - }, - "interval": { - "type": "number", - "description": "数值分组间隔（type='number' 时必填）" - }, - "start": { - "type": "number", - "description": "数值分组起始值" + "type": "string" }, "end": { - "type": "number", - "description": "数值分组结束值" + "description": "数值分组结束值", + "type": "number" }, "groups": { - "type": "object", - "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { - "type": "array", "items": { "type": "string" - } - } + }, + "type": "array" + }, + "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", + "type": "object" + }, + "interval": { + "description": "数值分组间隔（type='number' 时必填）", + "type": "number" + }, + "start": { + "description": "数值分组起始值", + "type": "number" + }, + "type": { + "description": "分组类型", + "enum": [ + "date", + "number", + "element" + ], + "type": "string" } }, "required": [ "type" - ] + ], + "type": "object" } }, "required": [ "field" - ] - } + ], + "type": "object" + }, + "type": "array" }, - "filters": { - "description": "筛选区域字段（页字段）", - "type": "array", + "range": { + "description": "放置透视表的左上角单元格 A1 地址（例如：'F1'）（仅 create 时有效）。可省略——省略后透视表放在新建子表的 A1 位置。", + "type": "string" + }, + "repeat_row_labels": { + "description": "是否显示重复项标签", + "type": "boolean" + }, + "rows": { + "description": "纵向分组字段（行字段）", "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": { + "operator": { + "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", + "type": "string" + }, "type": { - "type": "string", + "description": "条件类型", "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" + "type": "string" }, "value": { "description": "比较值" @@ -4936,23 +4927,38 @@ "required": [ "type", "operator" - ] + ], + "type": "object" + }, + "display_name": { + "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用；否则保持源字段原名，透视表产物已足够清晰。", + "type": "string" + }, + "field": { + "description": "源数据中的字段名（OOXML 字段引用）", + "type": "string" + }, + "filter": { + "description": "快速筛选：只显示指定的项目", + "properties": { + "items": { + "description": "要显示的项目列表（其余项目被隐藏）", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "items" + ], + "type": "object" }, "group": { - "type": "object", "description": "分组配置", "properties": { - "type": { - "type": "string", - "enum": [ - "date", - "number", - "element" - ], - "description": "分组类型" - }, "date_group_by": { - "type": "string", + "description": "日期分组粒度（type='date' 时必填）", "enum": [ "year", "yearMonth", @@ -4966,59 +4972,130 @@ "hourMinute", "minute" ], - "description": "日期分组粒度（type='date' 时必填）" - }, - "interval": { - "type": "number", - "description": "数值分组间隔（type='number' 时必填）" - }, - "start": { - "type": "number", - "description": "数值分组起始值" + "type": "string" }, "end": { - "type": "number", - "description": "数值分组结束值" + "description": "数值分组结束值", + "type": "number" }, "groups": { - "type": "object", - "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { - "type": "array", "items": { "type": "string" - } - } + }, + "type": "array" + }, + "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", + "type": "object" + }, + "interval": { + "description": "数值分组间隔（type='number' 时必填）", + "type": "number" + }, + "start": { + "description": "数值分组起始值", + "type": "number" + }, + "type": { + "description": "分组类型", + "enum": [ + "date", + "number", + "element" + ], + "type": "string" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "sort": { + "description": "排序配置", + "properties": { + "by": { + "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序", + "enum": [ + "label", + "value" + ], + "type": "string" + }, + "order": { + "description": "排序方向", + "enum": [ + "asc", + "desc" + ], + "type": "string" + }, + "value_field": { + "description": "by='value' 时必填，指定按哪个值字段排序", + "type": "string" } }, "required": [ - "type" - ] + "order" + ], + "type": "object" } }, "required": [ "field" - ] - } + ], + "type": "object" + }, + "type": "array" + }, + "show_col_grand_total": { + "description": "是否显示列总计（默认 true）", + "type": "boolean" + }, + "show_row_grand_total": { + "description": "是否显示行总计（默认 true）", + "type": "boolean" + }, + "show_subtotals": { + "description": "是否显示分类小计（默认 true，应用于所有字段）", + "type": "boolean" + }, + "source": { + "description": "源数据区域地址，格式为 'SheetName!StartCell:EndCell'（例如：'Sheet1!A1:D100'）。create 时必填；update 时提供则切换数据源。", + "type": "string" }, "values": { - "minItems": 1, - "type": "array", + "description": "要汇总的字段（至少需要 1 个）", "items": { - "type": "object", "properties": { - "field": { - "type": "string", - "description": "要汇总的源数据字段名" + "base_field": { + "description": "show_data_as 需要基准字段时的字段名", + "type": "string" }, "display_name": { - "type": "string", - "description": "字段在透视表中的显示名（典型场景：把 count(销售额) 的值列头显示为 'GMV'）。不传则使用源字段原名。仅在用户明确要求重命名时使用。" + "description": "字段在透视表中的显示名（典型场景：把 count(销售额) 的值列头显示为 'GMV'）。不传则使用源字段原名。仅在用户明确要求重命名时使用。", + "type": "string" + }, + "field": { + "description": "要汇总的源数据字段名", + "type": "string" + }, + "show_data_as": { + "description": "值显示方式（默认 'normal'）", + "enum": [ + "normal", + "percentOfTotal", + "percentOfCol", + "percentOfRow", + "percentOfParentRow", + "percentOfParentCol", + "index" + ], + "type": "string" }, "summarize_by": { "default": "sum", "description": "汇总函数", - "type": "string", "enum": [ "sum", "count", @@ -5033,184 +5110,90 @@ "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 需要基准字段时的字段名" + ], + "type": "string" } }, "required": [ "field" - ] + ], + "type": "object" }, - "description": "要汇总的字段（至少需要 1 个）" - }, + "minItems": 1, + "type": "array" + } + }, + "type": "object" + } + }, + "+pivot-update": { + "properties": { + "additionalProperties": {}, + "description": "创建/更新的透视表属性。", + "properties": { "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": "是否显示重复项标签" + "description": "是否自动调整列宽以适应内容", + "type": "boolean" }, "calculated_fields": { - "type": "array", "description": "计算字段列表", "items": { - "type": "object", "properties": { - "name": { - "type": "string", - "description": "计算字段的显示名称" - }, "formula": { - "type": "string", - "description": "公式表达式，引用其他字段名，例如 \"'Sales' + 'Tax'\"" + "description": "公式表达式，引用其他字段名，例如 \"'Sales' + 'Tax'\"", + "type": "string" + }, + "name": { + "description": "计算字段的显示名称", + "type": "string" }, "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" - ] + ], + "type": "string" } }, "required": [ "name", "formula" - ] - } + ], + "type": "object" + }, + "type": "array" }, "collapse": { - "type": "object", - "description": "行字段展开/折叠状态：字段名 -> 要折叠的项目列表", "additionalProperties": { - "type": "array", "items": { "type": "string" - } - } - } - }, - "additionalProperties": {} - } - }, - "+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 时提供则切换数据源。" + }, + "type": "array" + }, + "description": "行字段展开/折叠状态：字段名 -> 要折叠的项目列表", + "type": "object" }, - "rows": { - "description": "纵向分组字段（行字段）", - "type": "array", + "columns": { + "description": "横向分组字段（列字段）", "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": { + "operator": { + "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", + "type": "string" + }, "type": { - "type": "string", + "description": "条件类型", "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" + "type": "string" }, "value": { "description": "比较值" @@ -5222,23 +5205,38 @@ "required": [ "type", "operator" - ] + ], + "type": "object" + }, + "display_name": { + "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。", + "type": "string" + }, + "field": { + "description": "源数据中的字段名（OOXML 字段引用）", + "type": "string" + }, + "filter": { + "description": "快速筛选：只显示指定的项目", + "properties": { + "items": { + "description": "要显示的项目列表（其余项目被隐藏）", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "items" + ], + "type": "object" }, "group": { - "type": "object", "description": "分组配置", "properties": { - "type": { - "type": "string", - "enum": [ - "date", - "number", - "element" - ], - "description": "分组类型" - }, "date_group_by": { - "type": "string", + "description": "日期分组粒度（type='date' 时必填）", "enum": [ "year", "yearMonth", @@ -5252,116 +5250,101 @@ "hourMinute", "minute" ], - "description": "日期分组粒度（type='date' 时必填）" - }, - "interval": { - "type": "number", - "description": "数值分组间隔（type='number' 时必填）" - }, - "start": { - "type": "number", - "description": "数值分组起始值" + "type": "string" }, "end": { - "type": "number", - "description": "数值分组结束值" + "description": "数值分组结束值", + "type": "number" }, "groups": { - "type": "object", - "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { - "type": "array", "items": { "type": "string" - } - } + }, + "type": "array" + }, + "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", + "type": "object" + }, + "interval": { + "description": "数值分组间隔（type='number' 时必填）", + "type": "number" + }, + "start": { + "description": "数值分组起始值", + "type": "number" + }, + "type": { + "description": "分组类型", + "enum": [ + "date", + "number", + "element" + ], + "type": "string" } }, "required": [ "type" - ] - } - }, - "required": [ - "field" - ] - } - }, - "columns": { - "description": "横向分组字段（列字段）", - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string", - "description": "源数据中的字段名（OOXML 字段引用）" - }, - "display_name": { - "type": "string", - "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。" + ], + "type": "object" }, "sort": { - "type": "object", "description": "排序配置", "properties": { - "order": { - "type": "string", - "enum": [ - "asc", - "desc" - ], - "description": "排序方向" - }, "by": { - "type": "string", + "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序", "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": "要显示的项目列表（其余项目被隐藏）" + "type": "string" + }, + "order": { + "description": "排序方向", + "enum": [ + "asc", + "desc" + ], + "type": "string" + }, + "value_field": { + "description": "by='value' 时必填，指定按哪个值字段排序", + "type": "string" } }, "required": [ - "items" - ] - }, + "order" + ], + "type": "object" + } + }, + "required": [ + "field" + ], + "type": "object" + }, + "type": "array" + }, + "filters": { + "description": "筛选区域字段（页字段）", + "items": { + "properties": { "condition_filter": { - "type": "object", "description": "条件筛选：按文本/数值/日期条件筛选", "properties": { + "operator": { + "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", + "type": "string" + }, "type": { - "type": "string", + "description": "条件类型", "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" + "type": "string" }, "value": { "description": "比较值" @@ -5373,23 +5356,38 @@ "required": [ "type", "operator" - ] + ], + "type": "object" + }, + "display_name": { + "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。", + "type": "string" + }, + "field": { + "description": "源数据中的字段名（OOXML 字段引用）", + "type": "string" + }, + "filter": { + "description": "快速筛选：只显示指定的项目", + "properties": { + "items": { + "description": "要显示的项目列表（其余项目被隐藏）", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "items" + ], + "type": "object" }, "group": { - "type": "object", "description": "分组配置", "properties": { - "type": { - "type": "string", - "enum": [ - "date", - "number", - "element" - ], - "description": "分组类型" - }, "date_group_by": { - "type": "string", + "description": "日期分组粒度（type='date' 时必填）", "enum": [ "year", "yearMonth", @@ -5403,87 +5401,80 @@ "hourMinute", "minute" ], - "description": "日期分组粒度（type='date' 时必填）" - }, - "interval": { - "type": "number", - "description": "数值分组间隔（type='number' 时必填）" - }, - "start": { - "type": "number", - "description": "数值分组起始值" + "type": "string" }, "end": { - "type": "number", - "description": "数值分组结束值" + "description": "数值分组结束值", + "type": "number" }, "groups": { - "type": "object", - "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { - "type": "array", "items": { "type": "string" - } - } + }, + "type": "array" + }, + "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", + "type": "object" + }, + "interval": { + "description": "数值分组间隔（type='number' 时必填）", + "type": "number" + }, + "start": { + "description": "数值分组起始值", + "type": "number" + }, + "type": { + "description": "分组类型", + "enum": [ + "date", + "number", + "element" + ], + "type": "string" } }, "required": [ "type" - ] + ], + "type": "object" } }, "required": [ "field" - ] - } + ], + "type": "object" + }, + "type": "array" }, - "filters": { - "description": "筛选区域字段（页字段）", - "type": "array", + "range": { + "description": "放置透视表的左上角单元格 A1 地址（例如：'F1'）（仅 create 时有效）。可省略——省略后透视表放在新建子表的 A1 位置。", + "type": "string" + }, + "repeat_row_labels": { + "description": "是否显示重复项标签", + "type": "boolean" + }, + "rows": { + "description": "纵向分组字段（行字段）", "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": { + "operator": { + "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", + "type": "string" + }, "type": { - "type": "string", + "description": "条件类型", "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" + "type": "string" }, "value": { "description": "比较值" @@ -5495,23 +5486,38 @@ "required": [ "type", "operator" - ] + ], + "type": "object" + }, + "display_name": { + "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用；否则保持源字段原名，透视表产物已足够清晰。", + "type": "string" + }, + "field": { + "description": "源数据中的字段名（OOXML 字段引用）", + "type": "string" + }, + "filter": { + "description": "快速筛选：只显示指定的项目", + "properties": { + "items": { + "description": "要显示的项目列表（其余项目被隐藏）", + "items": { + "type": "string" + }, + "type": "array" + } + }, + "required": [ + "items" + ], + "type": "object" }, "group": { - "type": "object", "description": "分组配置", "properties": { - "type": { - "type": "string", - "enum": [ - "date", - "number", - "element" - ], - "description": "分组类型" - }, "date_group_by": { - "type": "string", + "description": "日期分组粒度（type='date' 时必填）", "enum": [ "year", "yearMonth", @@ -5525,774 +5531,771 @@ "hourMinute", "minute" ], - "description": "日期分组粒度（type='date' 时必填）" - }, - "interval": { - "type": "number", - "description": "数值分组间隔（type='number' 时必填）" - }, - "start": { - "type": "number", - "description": "数值分组起始值" + "type": "string" }, "end": { - "type": "number", - "description": "数值分组结束值" + "description": "数值分组结束值", + "type": "number" }, "groups": { - "type": "object", - "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { - "type": "array", "items": { "type": "string" - } - } + }, + "type": "array" + }, + "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", + "type": "object" + }, + "interval": { + "description": "数值分组间隔（type='number' 时必填）", + "type": "number" + }, + "start": { + "description": "数值分组起始值", + "type": "number" + }, + "type": { + "description": "分组类型", + "enum": [ + "date", + "number", + "element" + ], + "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" - ] + ], + "type": "object" }, - "base_field": { - "type": "string", - "description": "show_data_as 需要基准字段时的字段名" + "sort": { + "description": "排序配置", + "properties": { + "by": { + "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序", + "enum": [ + "label", + "value" + ], + "type": "string" + }, + "order": { + "description": "排序方向", + "enum": [ + "asc", + "desc" + ], + "type": "string" + }, + "value_field": { + "description": "by='value' 时必填，指定按哪个值字段排序", + "type": "string" + } + }, + "required": [ + "order" + ], + "type": "object" } }, "required": [ "field" - ] + ], + "type": "object" }, - "description": "要汇总的字段（至少需要 1 个）" + "type": "array" }, - "auto_fit_col": { - "type": "boolean", - "description": "是否自动调整列宽以适应内容" + "show_col_grand_total": { + "description": "是否显示列总计（默认 true）", + "type": "boolean" }, "show_row_grand_total": { - "type": "boolean", - "description": "是否显示行总计（默认 true）" - }, - "show_col_grand_total": { - "type": "boolean", - "description": "是否显示列总计（默认 true）" + "description": "是否显示行总计（默认 true）", + "type": "boolean" }, "show_subtotals": { - "type": "boolean", - "description": "是否显示分类小计（默认 true，应用于所有字段）" + "description": "是否显示分类小计（默认 true，应用于所有字段）", + "type": "boolean" }, - "repeat_row_labels": { - "type": "boolean", - "description": "是否显示重复项标签" + "source": { + "description": "源数据区域地址，格式为 'SheetName!StartCell:EndCell'（例如：'Sheet1!A1:D100'）。create 时必填；update 时提供则切换数据源。", + "type": "string" }, - "calculated_fields": { - "type": "array", - "description": "计算字段列表", + "values": { + "description": "要汇总的字段（至少需要 1 个）", "items": { - "type": "object", "properties": { - "name": { - "type": "string", - "description": "计算字段的显示名称" + "base_field": { + "description": "show_data_as 需要基准字段时的字段名", + "type": "string" }, - "formula": { - "type": "string", - "description": "公式表达式，引用其他字段名，例如 \"'Sales' + 'Tax'\"" + "display_name": { + "description": "字段在透视表中的显示名（典型场景：把 count(销售额) 的值列头显示为 'GMV'）。不传则使用源字段原名。仅在用户明确要求重命名时使用。", + "type": "string" + }, + "field": { + "description": "要汇总的源数据字段名", + "type": "string" + }, + "show_data_as": { + "description": "值显示方式（默认 'normal'）", + "enum": [ + "normal", + "percentOfTotal", + "percentOfCol", + "percentOfRow", + "percentOfParentRow", + "percentOfParentCol", + "index" + ], + "type": "string" }, "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 不适用。", + "description": "汇总函数", "enum": [ "sum", - "custom" - ] + "count", + "average", + "max", + "min", + "product", + "countNums", + "stdDev", + "stdDevp", + "var", + "varp", + "distinct", + "median" + ], + "type": "string" } }, "required": [ - "name", - "formula" - ] - } - }, - "collapse": { - "type": "object", - "description": "行字段展开/折叠状态：字段名 -> 要折叠的项目列表", - "additionalProperties": { - "type": "array", - "items": { - "type": "string" - } - } + "field" + ], + "type": "object" + }, + "minItems": 1, + "type": "array" } }, - "additionalProperties": {} + "type": "object" } }, "+range-sort": { "sort-keys": { - "type": "array", + "description": "排序条件列表（仅 sort 操作）。支持多级排序，靠前的条件优先级更高。", "items": { - "type": "object", "properties": { - "column": { - "type": "string", - "description": "排序依据的列字母（如 \"C\"、\"D\"），必须在 range 范围内" - }, "ascending": { - "type": "boolean", - "description": "是否升序排序" + "description": "是否升序排序", + "type": "boolean" + }, + "column": { + "description": "排序依据的列字母（如 \"C\"、\"D\"），必须在 range 范围内", + "type": "string" } }, "required": [ "column", "ascending" - ] + ], + "type": "object" }, - "description": "排序条件列表（仅 sort 操作）。支持多级排序，靠前的条件优先级更高。" + "type": "array" } }, "+sparkline-create": { "properties": { + "additionalProperties": false, "description": "创建/更新/部分删除的迷你图属性。delete 时不传 sparklines 即删整组，传则删指定项。", - "type": "object", "properties": { "config": { - "type": "object", + "additionalProperties": false, "description": "迷你图样式配置, 相同 groupId 的迷你图共享相同的样式。", "properties": { - "theme_type": { - "type": "string", - "enum": [ - "pro", - "light", - "soft", - "brand", - "fresh" - ], - "description": "主题类型：pro、light、soft、brand、fresh。" + "axis": { + "additionalProperties": false, + "description": "坐标轴配置，包含坐标轴颜色、是否翻转、是否显示坐标轴。", + "properties": { + "color": { + "description": "坐标轴颜色。", + "type": "string" + }, + "reverse": { + "description": "是否翻转坐标轴方向。", + "type": "boolean" + }, + "visible": { + "description": "是否显示坐标轴。", + "type": "boolean" + } + }, + "type": "object" }, - "non_num_show_as": { - "type": "string", + "contain_hidden_cells": { + "description": "隐藏的单元格数据是否参与绘制。", + "type": "boolean" + }, + "empty_show_as": { + "description": "空单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。", "enum": [ "zero", "gap", "average" ], - "description": "非数字单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。" + "type": "string" }, - "empty_show_as": { - "type": "string", + "extremum_max": { + "additionalProperties": false, + "description": "最大极值配置，包含极值类型、极值。", + "properties": { + "type": { + "description": "极值类型，可选值：individual=单个迷你图极值，group=同组内极值，custom=自定义。", + "enum": [ + "individual", + "group", + "custom" + ], + "type": "string" + }, + "value": { + "description": "当 type='custom' 时生效的具体数值。", + "type": "number" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "extremum_min": { + "additionalProperties": false, + "description": "最小极值配置，包含极值类型、极值。", + "properties": { + "type": { + "description": "极值类型：individual=单个迷你图极值，group=同组内极值，custom=自定义。", + "enum": [ + "individual", + "group", + "custom" + ], + "type": "string" + }, + "value": { + "description": "当 type='custom' 时生效的具体数值。", + "type": "number" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "line_width": { + "description": "折线图线宽，可选值：1=1px，2=2px，3=3px，4=4px。", + "enum": [ + 1, + 2, + 3, + 4 + ], + "type": "number" + }, + "non_num_show_as": { + "description": "非数字单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。", "enum": [ "zero", "gap", "average" ], - "description": "空单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。" - }, - "contain_hidden_cells": { - "type": "boolean", - "description": "隐藏的单元格数据是否参与绘制。" - }, - "series_color": { - "type": "string", - "description": "主系列颜色，例如 \"#4472C4\"。" + "type": "string" }, "points": { - "type": "object", + "additionalProperties": false, "description": "特殊点样式配置，包含高点、低点、标记点、首点、尾点、负点。", "properties": { - "last_point": { - "type": "object", - "description": "尾点配置，最后一个数据点的样式。", - "properties": { - "color": { - "type": "string", - "description": "点的颜色。" - }, - "visible": { - "type": "boolean", - "description": "是否显示该点。" - } - }, - "additionalProperties": false - }, - "negative_point": { - "type": "object", - "description": "负点配置，负数点的样式。", + "first_point": { + "additionalProperties": false, + "description": "首点配置，第一个数据点的样式。", "properties": { "color": { - "type": "string", - "description": "点的颜色。" + "description": "点的颜色。", + "type": "string" }, "visible": { - "type": "boolean", - "description": "是否显示该点。" + "description": "是否显示该点。", + "type": "boolean" } }, - "additionalProperties": false + "type": "object" }, - "markers_point": { - "type": "object", - "description": "标记点配置，所有标记点的样式。", + "high_point": { + "additionalProperties": false, + "description": "高点配置，最高点的样式。", "properties": { "color": { - "type": "string", - "description": "点的颜色。" + "description": "点的颜色。", + "type": "string" }, "visible": { - "type": "boolean", - "description": "是否显示该点。" + "description": "是否显示该点。", + "type": "boolean" } }, - "additionalProperties": false + "type": "object" }, - "first_point": { - "type": "object", - "description": "首点配置，第一个数据点的样式。", + "last_point": { + "additionalProperties": false, + "description": "尾点配置，最后一个数据点的样式。", "properties": { "color": { - "type": "string", - "description": "点的颜色。" + "description": "点的颜色。", + "type": "string" }, "visible": { - "type": "boolean", - "description": "是否显示该点。" + "description": "是否显示该点。", + "type": "boolean" } }, - "additionalProperties": false + "type": "object" }, - "high_point": { - "type": "object", - "description": "高点配置，最高点的样式。", + "low_point": { + "additionalProperties": false, + "description": "低点配置，最低点的样式。", "properties": { "color": { - "type": "string", - "description": "点的颜色。" + "description": "点的颜色。", + "type": "string" }, "visible": { - "type": "boolean", - "description": "是否显示该点。" + "description": "是否显示该点。", + "type": "boolean" } }, - "additionalProperties": false + "type": "object" }, - "low_point": { - "type": "object", - "description": "低点配置，最低点的样式。", + "markers_point": { + "additionalProperties": false, + "description": "标记点配置，所有标记点的样式。", "properties": { "color": { - "type": "string", - "description": "点的颜色。" + "description": "点的颜色。", + "type": "string" }, "visible": { - "type": "boolean", - "description": "是否显示该点。" - } - }, - "additionalProperties": false - } - }, - "additionalProperties": false - }, - "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": "是否显示坐标轴。" - } - }, - "additionalProperties": false - }, - "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" - ], - "additionalProperties": false - }, - "extremum_min": { - "type": "object", - "description": "最小极值配置，包含极值类型、极值。", - "properties": { - "type": { - "type": "string", - "enum": [ - "individual", - "group", - "custom" - ], - "description": "极值类型：individual=单个迷你图极值，group=同组内极值，custom=自定义。" + "description": "是否显示该点。", + "type": "boolean" + } + }, + "type": "object" }, - "value": { - "type": "number", - "description": "当 type='custom' 时生效的具体数值。" + "negative_point": { + "additionalProperties": false, + "description": "负点配置，负数点的样式。", + "properties": { + "color": { + "description": "点的颜色。", + "type": "string" + }, + "visible": { + "description": "是否显示该点。", + "type": "boolean" + } + }, + "type": "object" } }, - "required": [ - "type" + "type": "object" + }, + "series_color": { + "description": "主系列颜色，例如 \"#4472C4\"。", + "type": "string" + }, + "show_gradient": { + "description": "是否显示渐变效果。", + "type": "boolean" + }, + "show_radius": { + "description": "是否显示圆角，仅对柱形图和盈亏图生效。", + "type": "boolean" + }, + "theme_type": { + "description": "主题类型：pro、light、soft、brand、fresh。", + "enum": [ + "pro", + "light", + "soft", + "brand", + "fresh" + ], + "type": "string" + }, + "type": { + "description": "迷你图类型，可选值：line=折线图，column=柱形图，win_loss=盈亏图。", + "enum": [ + "line", + "column", + "win_loss" ], - "additionalProperties": false + "type": "string" } }, - "additionalProperties": false + "type": "object" }, "sparklines": { - "type": "array", "description": "迷你图项列表。create 时为待创建项（每项需 position + source/source_range）；update 时为待变更/新增项（每项需 sparkline_id；upsert=true 新增时需 position + source）；delete 时为待删除项（每项需 sparkline_id）。", "items": { - "type": "object", + "additionalProperties": false, "description": "单个迷你图项。", "properties": { - "sparkline_id": { - "type": "string", - "description": "迷你图 reference_id。create 时可选（不传系统生成）；update / delete 时必填。" - }, "position": { - "type": "object", + "additionalProperties": false, "description": "迷你图位置。create / update 时必填；delete 时省略。", "properties": { + "col": { + "description": "列索引，例如 \"A\"、\"B\"", + "type": "string" + }, "row": { - "type": "number", + "description": "行索引（0-based）", "minimum": 0, - "description": "行索引（0-based）" - }, - "col": { - "type": "string", - "description": "列索引，例如 \"A\"、\"B\"" + "type": "number" } }, "required": [ "row", "col" ], - "additionalProperties": false + "type": "object" }, "source": { - "type": "string", - "description": "A1 范围字符串，表示数据来源，例如 \"Sheet1!A2:A10\"。create 必填（与 source_range 二选一）；update 仅在改源时传；delete 时省略。" + "description": "A1 范围字符串，表示数据来源，例如 \"Sheet1!A2:A10\"。create 必填（与 source_range 二选一）；update 仅在改源时传；delete 时省略。", + "type": "string" }, "source_range": { - "type": "object", + "additionalProperties": false, "description": "结构化数据源范围（与 source 等价）。", "properties": { "range": { - "type": "string", - "description": "数据源的 A1 引用区域" + "description": "数据源的 A1 引用区域", + "type": "string" } }, "required": [ "range" ], - "additionalProperties": false + "type": "object" + }, + "sparkline_id": { + "description": "迷你图 reference_id。create 时可选（不传系统生成）；update / delete 时必填。", + "type": "string" } }, - "additionalProperties": false - } + "type": "object" + }, + "type": "array" } }, - "additionalProperties": false + "type": "object" } }, "+sparkline-update": { "properties": { + "additionalProperties": false, "description": "创建/更新/部分删除的迷你图属性。delete 时不传 sparklines 即删整组，传则删指定项。", - "type": "object", "properties": { "config": { - "type": "object", + "additionalProperties": false, "description": "迷你图样式配置, 相同 groupId 的迷你图共享相同的样式。", "properties": { - "theme_type": { - "type": "string", - "enum": [ - "pro", - "light", - "soft", - "brand", - "fresh" - ], - "description": "主题类型：pro、light、soft、brand、fresh。" + "axis": { + "additionalProperties": false, + "description": "坐标轴配置，包含坐标轴颜色、是否翻转、是否显示坐标轴。", + "properties": { + "color": { + "description": "坐标轴颜色。", + "type": "string" + }, + "reverse": { + "description": "是否翻转坐标轴方向。", + "type": "boolean" + }, + "visible": { + "description": "是否显示坐标轴。", + "type": "boolean" + } + }, + "type": "object" }, - "non_num_show_as": { - "type": "string", + "contain_hidden_cells": { + "description": "隐藏的单元格数据是否参与绘制。", + "type": "boolean" + }, + "empty_show_as": { + "description": "空单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。", "enum": [ "zero", "gap", "average" ], - "description": "非数字单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。" + "type": "string" }, - "empty_show_as": { - "type": "string", + "extremum_max": { + "additionalProperties": false, + "description": "最大极值配置，包含极值类型、极值。", + "properties": { + "type": { + "description": "极值类型，可选值：individual=单个迷你图极值，group=同组内极值，custom=自定义。", + "enum": [ + "individual", + "group", + "custom" + ], + "type": "string" + }, + "value": { + "description": "当 type='custom' 时生效的具体数值。", + "type": "number" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "extremum_min": { + "additionalProperties": false, + "description": "最小极值配置，包含极值类型、极值。", + "properties": { + "type": { + "description": "极值类型：individual=单个迷你图极值，group=同组内极值，custom=自定义。", + "enum": [ + "individual", + "group", + "custom" + ], + "type": "string" + }, + "value": { + "description": "当 type='custom' 时生效的具体数值。", + "type": "number" + } + }, + "required": [ + "type" + ], + "type": "object" + }, + "line_width": { + "description": "折线图线宽，可选值：1=1px，2=2px，3=3px，4=4px。", + "enum": [ + 1, + 2, + 3, + 4 + ], + "type": "number" + }, + "non_num_show_as": { + "description": "非数字单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。", "enum": [ "zero", "gap", "average" ], - "description": "空单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。" - }, - "contain_hidden_cells": { - "type": "boolean", - "description": "隐藏的单元格数据是否参与绘制。" - }, - "series_color": { - "type": "string", - "description": "主系列颜色，例如 \"#4472C4\"。" + "type": "string" }, "points": { - "type": "object", + "additionalProperties": false, "description": "特殊点样式配置，包含高点、低点、标记点、首点、尾点、负点。", "properties": { - "last_point": { - "type": "object", - "description": "尾点配置，最后一个数据点的样式。", + "first_point": { + "additionalProperties": false, + "description": "首点配置，第一个数据点的样式。", "properties": { "color": { - "type": "string", - "description": "点的颜色。" + "description": "点的颜色。", + "type": "string" }, "visible": { - "type": "boolean", - "description": "是否显示该点。" + "description": "是否显示该点。", + "type": "boolean" } }, - "additionalProperties": false + "type": "object" }, - "negative_point": { - "type": "object", - "description": "负点配置，负数点的样式。", + "high_point": { + "additionalProperties": false, + "description": "高点配置，最高点的样式。", "properties": { "color": { - "type": "string", - "description": "点的颜色。" + "description": "点的颜色。", + "type": "string" }, "visible": { - "type": "boolean", - "description": "是否显示该点。" + "description": "是否显示该点。", + "type": "boolean" } }, - "additionalProperties": false + "type": "object" }, - "markers_point": { - "type": "object", - "description": "标记点配置，所有标记点的样式。", + "last_point": { + "additionalProperties": false, + "description": "尾点配置，最后一个数据点的样式。", "properties": { "color": { - "type": "string", - "description": "点的颜色。" + "description": "点的颜色。", + "type": "string" }, "visible": { - "type": "boolean", - "description": "是否显示该点。" + "description": "是否显示该点。", + "type": "boolean" } }, - "additionalProperties": false + "type": "object" }, - "first_point": { - "type": "object", - "description": "首点配置，第一个数据点的样式。", + "low_point": { + "additionalProperties": false, + "description": "低点配置，最低点的样式。", "properties": { "color": { - "type": "string", - "description": "点的颜色。" + "description": "点的颜色。", + "type": "string" }, "visible": { - "type": "boolean", - "description": "是否显示该点。" + "description": "是否显示该点。", + "type": "boolean" } }, - "additionalProperties": false + "type": "object" }, - "high_point": { - "type": "object", - "description": "高点配置，最高点的样式。", + "markers_point": { + "additionalProperties": false, + "description": "标记点配置，所有标记点的样式。", "properties": { "color": { - "type": "string", - "description": "点的颜色。" + "description": "点的颜色。", + "type": "string" }, "visible": { - "type": "boolean", - "description": "是否显示该点。" + "description": "是否显示该点。", + "type": "boolean" } }, - "additionalProperties": false + "type": "object" }, - "low_point": { - "type": "object", - "description": "低点配置，最低点的样式。", + "negative_point": { + "additionalProperties": false, + "description": "负点配置，负数点的样式。", "properties": { "color": { - "type": "string", - "description": "点的颜色。" + "description": "点的颜色。", + "type": "string" }, "visible": { - "type": "boolean", - "description": "是否显示该点。" + "description": "是否显示该点。", + "type": "boolean" } }, - "additionalProperties": false + "type": "object" } }, - "additionalProperties": false + "type": "object" }, - "line_width": { - "type": "number", + "series_color": { + "description": "主系列颜色，例如 \"#4472C4\"。", + "type": "string" + }, + "show_gradient": { + "description": "是否显示渐变效果。", + "type": "boolean" + }, + "show_radius": { + "description": "是否显示圆角，仅对柱形图和盈亏图生效。", + "type": "boolean" + }, + "theme_type": { + "description": "主题类型：pro、light、soft、brand、fresh。", "enum": [ - 1, - 2, - 3, - 4 + "pro", + "light", + "soft", + "brand", + "fresh" ], - "description": "折线图线宽，可选值：1=1px，2=2px，3=3px，4=4px。" + "type": "string" }, "type": { - "type": "string", + "description": "迷你图类型，可选值：line=折线图，column=柱形图，win_loss=盈亏图。", "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": "是否显示坐标轴。" - } - }, - "additionalProperties": false - }, - "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" - ], - "additionalProperties": false - }, - "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" - ], - "additionalProperties": false + "type": "string" } }, - "additionalProperties": false + "type": "object" }, "sparklines": { - "type": "array", "description": "迷你图项列表。create 时为待创建项（每项需 position + source/source_range）；update 时为待变更/新增项（每项需 sparkline_id；upsert=true 新增时需 position + source）；delete 时为待删除项（每项需 sparkline_id）。", "items": { - "type": "object", + "additionalProperties": false, "description": "单个迷你图项。", "properties": { - "sparkline_id": { - "type": "string", - "description": "迷你图 reference_id。create 时可选（不传系统生成）；update / delete 时必填。" - }, "position": { - "type": "object", + "additionalProperties": false, "description": "迷你图位置。create / update 时必填；delete 时省略。", "properties": { + "col": { + "description": "列索引，例如 \"A\"、\"B\"", + "type": "string" + }, "row": { - "type": "number", + "description": "行索引（0-based）", "minimum": 0, - "description": "行索引（0-based）" - }, - "col": { - "type": "string", - "description": "列索引，例如 \"A\"、\"B\"" + "type": "number" } }, "required": [ "row", "col" ], - "additionalProperties": false + "type": "object" }, "source": { - "type": "string", - "description": "A1 范围字符串，表示数据来源，例如 \"Sheet1!A2:A10\"。create 必填（与 source_range 二选一）；update 仅在改源时传；delete 时省略。" + "description": "A1 范围字符串，表示数据来源，例如 \"Sheet1!A2:A10\"。create 必填（与 source_range 二选一）；update 仅在改源时传；delete 时省略。", + "type": "string" }, "source_range": { - "type": "object", + "additionalProperties": false, "description": "结构化数据源范围（与 source 等价）。", "properties": { "range": { - "type": "string", - "description": "数据源的 A1 引用区域" + "description": "数据源的 A1 引用区域", + "type": "string" } }, "required": [ "range" ], - "additionalProperties": false + "type": "object" + }, + "sparkline_id": { + "description": "迷你图 reference_id。create 时可选（不传系统生成）；update / delete 时必填。", + "type": "string" } }, - "additionalProperties": false - } + "type": "object" + }, + "type": "array" } }, - "additionalProperties": false + "type": "object" } } } diff --git a/shortcuts/sheets/lark_sheet_batch_update.go b/shortcuts/sheets/lark_sheet_batch_update.go index abf51868c..d6591bb52 100644 --- a/shortcuts/sheets/lark_sheet_batch_update.go +++ b/shortcuts/sheets/lark_sheet_batch_update.go @@ -332,7 +332,7 @@ var DropdownUpdate = common.Shortcut{ if _, err := validateDropdownRanges(runtime); err != nil { return err } - if _, err := validateDropdownOptions(runtime); err != nil { + if _, err := validateDropdownOptionsColors(runtime); err != nil { return err } return nil diff --git a/shortcuts/sheets/lark_sheet_batch_update_test.go b/shortcuts/sheets/lark_sheet_batch_update_test.go index e7885ab5c..f190c8d1e 100644 --- a/shortcuts/sheets/lark_sheet_batch_update_test.go +++ b/shortcuts/sheets/lark_sheet_batch_update_test.go @@ -188,14 +188,16 @@ func TestCellsBatchClear_Guards(t *testing.T) { // TestDropdownUpdate_BatchPayload verifies the multi-range dropdown // update fans out into a single batch_update with one set_cell_range -// op per range. +// op per range. Also covers --colors / --highlight -> highlight_colors +// / enable_highlight propagation through dropdownBatchInput. func TestDropdownUpdate_BatchPayload(t *testing.T) { t.Parallel() body := parseDryRunBody(t, DropdownUpdate, []string{ "--url", testURL, "--ranges", `["sheet1!A2:A5","sheet1!C2:C5"]`, "--options", `["a","b","c"]`, - "--multiple", + "--colors", `["#FFE699","#bff7d9","#ffb3b3"]`, + "--multiple", "--highlight", }) input := decodeToolInput(t, body, "batch_update") ops, _ := input["operations"].([]interface{}) @@ -222,6 +224,13 @@ func TestDropdownUpdate_BatchPayload(t *testing.T) { if dv["support_multiple_values"] != true { t.Errorf("op[%d] support_multiple_values = %v, want true", i, dv["support_multiple_values"]) } + colors, _ := dv["highlight_colors"].([]interface{}) + if len(colors) != 3 { + t.Errorf("op[%d] highlight_colors length = %d, want 3", i, len(colors)) + } + if dv["enable_highlight"] != true { + t.Errorf("op[%d] enable_highlight = %v, want true", i, dv["enable_highlight"]) + } } } diff --git a/shortcuts/sheets/lark_sheet_write_cells.go b/shortcuts/sheets/lark_sheet_write_cells.go index 671fd673d..2cd2eff9a 100644 --- a/shortcuts/sheets/lark_sheet_write_cells.go +++ b/shortcuts/sheets/lark_sheet_write_cells.go @@ -331,14 +331,16 @@ func dropdownSetInput(runtime flagView, token, sheetID, sheetName string) (map[s // ─── shared dropdown helpers ────────────────────────────────────────── -// buildDropdownValidation packs --options / --multiple into the -// data_validation block expected by set_cell_range. Field names match -// the canonical schema: items (not values) for the option list, and -// support_multiple_values (not multiple_values) for multi-select. -// Earlier CLI builds also emitted `colors` and `highlight_options`, -// neither of which exists in the server schema for set_cell_range; both -// were rejected as "unexpected property". The --colors / --highlight -// flags have been removed; only --options + --multiple remain. +// buildDropdownValidation packs --options / --colors / --multiple / --highlight +// into the data_validation block expected by set_cell_range. Field names +// follow the canonical set_cell_range.data_validation schema: +// +// --options -> items (string array) +// --multiple -> support_multiple_values (bool) +// --colors -> highlight_colors (string array, hex) +// --highlight -> enable_highlight (bool) +// +// --colors length must equal --options length when both are set. func buildDropdownValidation(runtime flagView) (map[string]interface{}, error) { options, err := requireJSONArray(runtime, "options") if err != nil { @@ -348,19 +350,42 @@ func buildDropdownValidation(runtime flagView) (map[string]interface{}, error) { "type": "list", "items": options, } + if runtime.Str("colors") != "" { + colors, err := requireJSONArray(runtime, "colors") + if err != nil { + return nil, err + } + if len(colors) != len(options) { + return nil, common.FlagErrorf("--colors length (%d) must equal --options length (%d)", len(colors), len(options)) + } + dv["highlight_colors"] = colors + } if runtime.Bool("multiple") { dv["support_multiple_values"] = true } + if runtime.Bool("highlight") { + dv["enable_highlight"] = true + } return dv, nil } -// validateDropdownOptions checks that --options parses as a JSON array -// and returns its length so callers can size their cells matrix. -func validateDropdownOptions(runtime flagView) (int, error) { +// validateDropdownOptionsColors validates --options is a JSON array and that +// --colors (when set) has matching length. Returns the options length so +// callers can size their cells matrix at Validate time without re-parsing. +func validateDropdownOptionsColors(runtime flagView) (int, error) { options, err := requireJSONArray(runtime, "options") if err != nil { return 0, err } + if runtime.Str("colors") != "" { + colors, err := requireJSONArray(runtime, "colors") + if err != nil { + return 0, err + } + if len(colors) != len(options) { + return 0, common.FlagErrorf("--colors length (%d) must equal --options length (%d)", len(colors), len(options)) + } + } return len(options), nil } diff --git a/shortcuts/sheets/lark_sheet_write_cells_test.go b/shortcuts/sheets/lark_sheet_write_cells_test.go index 2e3543bb9..5e10d1a25 100644 --- a/shortcuts/sheets/lark_sheet_write_cells_test.go +++ b/shortcuts/sheets/lark_sheet_write_cells_test.go @@ -118,11 +118,15 @@ func TestWriteCellsShortcuts_DryRun(t *testing.T) { // TestDropdownSet_CellsShape inspects the 3×1 matrix produced from // --range A2:A4 to confirm the data_validation prototype is replicated. +// Also covers --colors / --highlight emitting the canonical +// `highlight_colors` / `enable_highlight` field names (not the legacy +// `colors` / `highlight_options`). func TestDropdownSet_CellsShape(t *testing.T) { t.Parallel() body := parseDryRunBody(t, DropdownSet, []string{ "--url", testURL, "--sheet-id", testSheetID, "--range", "A2:A4", "--options", `["a","b"]`, "--multiple", + "--colors", `["#FFE699","#bff7d9"]`, "--highlight", }) input := decodeToolInput(t, body, "set_cell_range") cells, _ := input["cells"].([]interface{}) @@ -153,6 +157,38 @@ func TestDropdownSet_CellsShape(t *testing.T) { if _, hasLegacy := dv["multiple_values"]; hasLegacy { t.Errorf("row %d data_validation should not emit legacy `multiple_values`", i) } + colors, _ := dv["highlight_colors"].([]interface{}) + if len(colors) != 2 || colors[0] != "#FFE699" || colors[1] != "#bff7d9" { + t.Errorf("row %d data_validation.highlight_colors = %#v, want [\"#FFE699\",\"#bff7d9\"]", i, dv["highlight_colors"]) + } + if dv["enable_highlight"] != true { + t.Errorf("row %d data_validation.enable_highlight = %v, want true", i, dv["enable_highlight"]) + } + if _, hasLegacy := dv["colors"]; hasLegacy { + t.Errorf("row %d data_validation should not emit legacy `colors`", i) + } + if _, hasLegacy := dv["highlight_options"]; hasLegacy { + t.Errorf("row %d data_validation should not emit legacy `highlight_options`", i) + } + } +} + +// TestDropdownSet_ColorsLengthMismatch checks the early Validate-time +// error when --colors length doesn't match --options. +func TestDropdownSet_ColorsLengthMismatch(t *testing.T) { + t.Parallel() + _, stderr, err := runShortcutCapturingErr(t, DropdownSet, []string{ + "--url", testURL, "--sheet-id", testSheetID, + "--range", "A2:A4", + "--options", `["a","b","c"]`, + "--colors", `["#FFE699","#bff7d9"]`, + "--dry-run", + }) + if err == nil { + t.Fatal("expected --colors length mismatch error, got nil") + } + if !strings.Contains(stderr, "must equal --options length") && !strings.Contains(err.Error(), "must equal --options length") { + t.Errorf("error message missing length-mismatch hint:\nerr=%v\nstderr=%s", err, stderr) } } diff --git a/skills/lark-sheets/references/lark-sheets-batch-update.md b/skills/lark-sheets/references/lark-sheets-batch-update.md index 7b04905a1..ba3160e0b 100644 --- a/skills/lark-sheets/references/lark-sheets-batch-update.md +++ b/skills/lark-sheets/references/lark-sheets-batch-update.md @@ -70,7 +70,9 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_ | --- | --- | --- | --- | | `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（如 `["sheet1!A2:A100"]`），每项必须带 sheet 前缀 | | `--options` | string + File + Stdin（复合 JSON） | required | 选项 JSON 数组（如 `["opt1","opt2"]`） | +| `--colors` | string + File + Stdin（简单 JSON） | optional | 颜色数组（与 `--options` 等长） | | `--multiple` | bool | optional | 启用多选 | +| `--highlight` | bool | optional | 选项配色 | ### `+dropdown-delete` diff --git a/skills/lark-sheets/references/lark-sheets-write-cells.md b/skills/lark-sheets/references/lark-sheets-write-cells.md index 6ebe2b154..a4e32f6b2 100644 --- a/skills/lark-sheets/references/lark-sheets-write-cells.md +++ b/skills/lark-sheets/references/lark-sheets-write-cells.md @@ -4,7 +4,7 @@ 1. **明确写入边界**：写入前必须能回答"目标 range 的起止行列号是多少？是否落在用户授权范围内？"。除用户明示要修改的区域外，禁止扩张到原数据列以外或新建 Sheet。 2. **完整性断言**：批量写入前先把"预期写入条数"硬编码到代码里（如要填 106 条翻译 → `expected = 106`），写完后回读断言 `actual == expected`。少于预期就继续写，禁止交付半成品。 -3. **回读抽样校验**：写完关键值 / 公式后，用 `+csv-get` 或 `+cells-get` 重新读取写入区域，至少抽样 3-5 个代表性单元格（首 / 中 / 末），核对值与预期一致（与本地脚本计算的预期值对照）。公式特定的"先验证模板再 --copy-to-range / 修完再读回"细则见下方相关章节。 +3. **回读抽样校验**：写完关键值 / 公式后，用 `+csv-get` 或 `+cells-get` 重新读取写入区域，至少抽样 3-5 个代表性单元格（首 / 中 / 末），核对值与预期一致（与 本地脚本 计算的预期值对照）。公式特定的"先验证模板再 copy_to_range / 修完再读回"细则见下方相关章节。 ## 新增列 / 新增行的样式继承（防止视觉风格不一致） @@ -17,7 +17,7 @@ 3. `cell_styles.number_format`（小数位 / 千分位 / 百分比 / 日期格式）—— 漏继承会导致同列数值格式混乱 4. `cell_styles.background_color`（背景色） 5. `border_styles`（四边框） -6. **`merged_cells`（合并范围）**——续写场景必查（高频致命错误）：用 `+sheet-info --include merges` 读原数据区域的合并信息。**原行有跨列合并**（如标题行 `A1:G1` 合并）时，新行**必须**用 `+cells-{merge|unmerge}` 工具复制相同合并模式到新行（如续写第 3 个周报块的标题行 `A23:G23` 必须合并）。仅传 cells 数组的 5 类样式不够——合并范围要单独靠 `+cells-{merge|unmerge}` 工具落地（典型反例：续写多周记录表时，新增周次的标题行未合并，视觉上与原前几周风格不一致） +6. **`merged_cells`（合并范围）**——续写场景必查（高频致命错误）：用 `+sheet-info --info_type=merged_cells_infos` 读原数据区域的合并信息。**原行有跨列合并**（如标题行 `A1:G1` 合并）时，新行**必须**用 `+cells-{merge|unmerge}` 工具复制相同合并模式到新行（如续写第 3 个周报块的标题行 `A23:G23` 必须合并）。仅传 cells 数组的 5 类样式不够——合并范围要单独靠 `+cells-{merge|unmerge}` 工具落地（典型反例：续写多周记录表时，新增周次的标题行未合并，视觉上与原前几周风格不一致） **采样模板的正确做法**： - 表头新列 → 读相邻表头单元格（如新加 D1 → 读 A1/B1/C1 任一） @@ -44,56 +44,59 @@ ## 使用场景 -写入。为一块单元格区域设置值、公式、批注/备注和/或格式。也支持通过 `rich_text` 中 `type: "embed-image"` 在单元格内嵌入图片（单元格图片）。关键：数组维度必须严格匹配——`cells` 二维数组必须与 `range` 的行列维度完全一致，range 是闭区间，否则会触发 `InvalidCellRangeError`。计算示例：区域 `A1:D3` = 3 行 × 4 列 = `[[r1c1,r1c2,r1c3,r1c4],[r2c1,r2c2,r2c3,r2c4],[r3c1,r3c2,r3c3,r3c4]]`；区域 `A41:N48` = 8 行 × 14 列 = 8 个数组且每个数组 14 个单元；单个单元格 `A1` = `[[cell]]`；单列区域 `B5:B7` = `[[cell1],[cell2],[cell3]]`。空单元请使用 `{}`。**如果填写的区域存在大量重复内容，务必优先使用 `--copy-to-range` 字段复制，可大幅减少 `cells` 长度。** +写入。为一块单元格区域设置值、公式、批注/备注和/或格式。也支持通过 `rich_text` 中 `type: "embed-image"` 在单元格内嵌入图片（单元格图片）。关键：数组维度必须严格匹配——`cells` 二维数组必须与 `range` 的行列维度完全一致，range 是闭区间，否则会触发 `InvalidCellRangeError`。计算示例：区域 `A1:D3` = 3 行 × 4 列 = `[[r1c1,r1c2,r1c3,r1c4],[r2c1,r2c2,r2c3,r2c4],[r3c1,r3c2,r3c3,r3c4]]`；区域 `A41:N48` = 8 行 × 14 列 = 8 个数组且每个数组 14 个单元；单个单元格 `A1` = `[[cell]]`；单列区域 `B5:B7` = `[[cell1],[cell2],[cell3]]`。空单元请使用 `{}`。**如果填写的区域存在大量重复内容，务必优先使用 `copy_to_range` 字段复制，可大幅减少 `cells` 长度。** > **单元格图片 vs 浮动图片**： > - **单元格图片**（本工具）：图片嵌入在单元格内部，属于单元格内容，随单元格移动。通过 `rich_text` 中 `type: "embed-image"` 写入。 -> - **浮动图片**：图片悬浮在单元格上方，可自由定位和调整大小，不属于单元格内容。→ 使用 lark-sheets-float-image。 +> - **浮动图片**：图片悬浮在单元格上方，可自由定位和调整大小，不属于单元格内容。→ 使用 lark_sheet_float_image Skill。 高频模式（**必须遵守，禁止逐行写入替代**）： -- 整列公式：先在 `H2` 写一个公式，再用 `--copy-to-range "H2:H100"` 或 `--copy-to-range "H:H"` 向下填充。**禁止对每一行单独调用 `+cells-set` 写入相同结构的公式** -- 整列格式：先在 `J1` 写一个带样式的模板单元格，再用 `--copy-to-range "J:J"` -- 首行样式：先在 `A1` 写一个模板单元格，再用 `--copy-to-range "1:1"` -- 用户说”这列 / 整列 / 这行 / 首行 / 向下复制”时，**必须**使用模板单元格 + `--copy-to-range` -- 多区域写入相同格式/公式结构时，优先写一个模板，再用 `--copy-to-range` 复制到所有目标区域 +- 整列公式：先在 `H2` 写一个公式，再用 `copy_to_range: "H2:H100"` 或 `copy_to_range: "H:H"` 向下填充。**禁止对每一行单独调用 `+cells-set` 写入相同结构的公式** +- 整列格式：先在 `J1` 写一个带样式的模板单元格，再用 `copy_to_range: "J:J"` +- 首行样式：先在 `A1` 写一个模板单元格，再用 `copy_to_range: "1:1"` +- 用户说”这列 / 整列 / 这行 / 首行 / 向下复制”时，**必须**使用模板单元格 + `copy_to_range` +- 多区域写入相同格式/公式结构时，优先写一个模板，再用 `copy_to_range` 复制到所有目标区域 -⚠️ **逐行写入公式是常见低效写法**：对每一行单独调用 `+cells-set` 写公式（如 26 次）既慢又易错，且不会自动平移公式引用。正确做法是 1 次模板写入 + 1 次 `--copy-to-range`（公式引用自动平移）。 +⚠️ **逐行写入公式是最常见的致命错误**：对每一行单独调用 `+cells-set` 写入公式（如调用 26 次），会快速耗尽轮次上限导致操作不完整。正确做法是 1 次模板写入 + 1 次 `copy_to_range` = 2 次调用完成。 -💡 **写入公式前先按迁移规则改写**：如果公式来自 Excel 或包含数组场景，先读取并遵循 `lark-sheets-formula-translation` 的规则完成改写，再把最终公式写入 `formula` 字段。 +💡 **写入公式前先按迁移规则改写**：如果公式来自 Excel 或包含数组场景，先读取并遵循 `lark-sheets-formula-translation` skill 的规则完成改写，再把最终公式写入 `formula` 字段。 💡 **内容与样式分离写入（推荐）**：当需要同时写入内容和样式时，`cells` 中每个单元格都带上 `cell_styles` / `border_styles` 会导致入参非常冗长。由于同一区域的样式通常高度重复（如整列统一背景色、统一边框），推荐拆成两步： 1. **先写内容**：`+cells-set` 只传 `value` / `formula`，不带样式，`cells` 入参精简 -2. **再批量刷样式**：对区域中的一个单元格写入目标样式作为模板，再用 `--copy-to-range` 将样式扩展到整列 / 整行 / 整个区域（`--copy-to-range` 会复制值、公式和样式，所以模板单元格应已包含正确的值） +2. **再批量刷样式**：对区域中的一个单元格写入目标样式作为模板，再用 `copy_to_range` 将样式扩展到整列 / 整行 / 整个区域（`copy_to_range` 会复制值、公式和样式，所以模板单元格应已包含正确的值） 示例：要对 A2:A100 写入数据并统一设置蓝色背景 + 边框： ``` Step 1: `+cells-set` — range="A2:A100", cells 只含 value（无样式，入参短） -Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styles（单个模板）, --copy-to-range="A2:A100" +Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styles（单个模板）, copy_to_range="A2:A100" ``` 这比在 99 个单元格中都重复写样式 JSON 高效得多。 -💡 **大批量数据分批写入（推荐）**：当需要写入大量行（如几十行以上）时，不要试图在一次调用中生成全部 `cells` 数据——`cells` 数组过大会让单次生成的内容过长，容易出错或被截断。应将数据拆分为多批，每批 20-50 行，分多次调用 `+cells-set` 逐批生成并写入（如先写 `A2:D21`，再写 `A22:D41`，依此类推）。每次只生成当前批次的数据，控制单次生成量。 +💡 **大批量数据分批写入（推荐）**：当需要写入大量行（如几十行以上）时，不要试图在一次调用中生成全部 `cells` 数据——`cells` 数组过大会导致模型生成内容过长而超时。应将数据拆分为多批，每批 20-50 行，分多次调用 `+cells-set` 逐批生成并写入（如先写 `A2:D21`，再写 `A22:D41`，依此类推）。每次调用只需生成当前批次的数据，控制单次生成量，避免超时。 注意： - 不要把 `cells` 写成字符串化 JSON -- `+cells-set` 默认即覆盖非空 cell（`--allow-overwrite` 默认 true）；若要**保护**非空 cell 不被覆盖，显式传 `--allow-overwrite=false`（遇非空 cell 报错） +- 如果目标区域中已有值、公式或样式需要被覆盖，显式设置 `allow_overwrite=true` - 若目标区域涉及合并单元格，不要向合并区域中的非左上角单元格写入数据；如需写入，应改写合并区域左上角单元格，或先调整/取消合并区域 - **构造 `range` 时行号必须基于逻辑行号**：如果之前通过 `+csv-get` 读取了数据，CSV 中被双引号包裹的多行字段（如 `"2026年3月2日\n星期一"`）是**一个单元格**，不是两行。写入时的行号必须按逻辑记录计算，不能按物理换行符计数，否则 `range` 会整体偏移导致写入到错误位置 -> 用户说"样式和原表一致 / 保持原表格式 / 边框继承"时同理：`cell_styles` 只覆盖字体和对齐、**不含边框**，边框必须用独立 `border_styles` 字段传——完整继承清单见上方「新增列 / 新增行的样式继承」。 +⚠️ **"样式与原表一致"必须包含 `border_styles`（高频致命错误）**：当用户说"样式和原表一致"、"保持原表格式"、"边框继承"等要求时，cells 里的 `cell_styles` **不能只传 `font_size` / `horizontal_alignment` / `vertical_alignment`**——这几项只覆盖字体和对齐，**不包含边框**。边框必须用独立的 `border_styles` 字段传（或在源 cell 用 `+cells-get` 读出来再原样复制）。 +- **反模式**：`cells=[[{cell_styles:{font_size:16, horizontal_alignment:"center", vertical_alignment:"middle"}}]]`（字体+对齐都有，但**新 cell 仍然没边框**，视觉上与原表断裂） +- **正确做法**：`cell_styles` + `border_styles` 一起传，`border_styles` 覆盖 top/bottom/left/right 四条边（或至少 data 区该加的几条），确保视觉连续 +- 特别是**新列/新行**场景，新 cell 底子里本来就没边框，如果不显式传 `border_styles`，copy_to_range 复制的模板也没边框 → 整列/整行无边框 -⚠️ **公式写入必须自己校验结果（后端不会报语法错）**：`+cells-set` 写公式时，即便公式有括号不配对（如 `=IFERROR(VALUE(REGEXEXTRACT(D5, "\d+"))), 0)` 比 IFERROR 多一个 `)`）或用了飞书不支持的函数（如 `GOOGLETRANSLATE` / `CUBEVALUE`），**后端工具也会返回 `updated_cells_count=N, rc=0` 的"成功"**——错误会静默写进单元格显示为 `#VALUE!` / `#NAME?` / `#REF!`。因此： +⚠️ **公式写入必须自己校验结果（后端不会报语法错）**：`+cells-set` 写公式时，即便公式有括号不配对（如 `=IFERROR(VALUE(REGEXEXTRACT(D5, "\d+"))), 0)` 比 IFERROR 多一个 `)`）或函数名拼错（`=UNIQUE(...)` 飞书不支持），**后端工具也会返回 `updated_cells_count=N, rc=0` 的"成功"**——错误会静默写进单元格显示为 `#VALUE!` / `#NAME?` / `#REF!`。因此： 1. **写完立即读回**：`+cells-set` 后紧跟 `+csv-get`（或 `+cells-get`）读目标范围前几行，检查是否出现 `#VALUE!` / `#NAME?` / `#REF!` / `#N/A` / `#DIV/0!` / `#NUM!` -2. **看到 `#` 开头的错误值**立即修公式：`#NAME?` 多半是函数名拼错或用了飞书不支持的函数（如 `GOOGLETRANSLATE` / CUBE 系列；注意 `UNIQUE` / `FILTER` / `SPLIT` 飞书是支持的）；`#VALUE!` 多半是类型不匹配或括号错位；`#REF!` 是引用错误；`~CIRCULAR~REF~` 是循环引用（公式引用了自身或会闭环） -3. **`--copy-to-range` 扩展前先验证模板**：模板单元格公式自己都算错，`--copy-to-range` 复制到 100 行就是 100 个错误 -4. **去重 / 筛选函数**：飞书**支持** `UNIQUE` / `FILTER` / `SPLIT`（原生数组函数，详见 `lark-sheets-formula-translation`），可直接用；`DISTINCT` 不是飞书函数，去重用 `UNIQUE`。大数据量去重 / 分组也可用透视表（`+pivot-{create|update|delete}`，值字段聚合方式选 count） +2. **看到 `#` 开头的错误值**立即修公式：`#NAME?` 多半是函数名拼错或飞书不支持（UNIQUE/DISTINCT 等）；`#VALUE!` 多半是类型不匹配或括号错位；`#REF!` 是引用错误；`~CIRCULAR~REF~` 是循环引用（公式引用了自身或会闭环） +3. **`copy_to_range` 扩展前先验证模板**：模板单元格公式自己都算错，`copy_to_range` 复制到 100 行就是 100 个错误 +4. **飞书不支持的函数**：`UNIQUE` / `DISTINCT` / `FILTER`（部分）—— 对应"去重"场景改用透视表（`+pivot-{create|update|delete}`，值字段聚合方式选 count） 5. **循环引用预检（高频致命错误）**：写聚合公式（SUM / AVERAGE / COUNT 等）前必须明确**引用范围不包含目标单元格自身或其传递依赖**。典型反例：在 C3 写 `=SUMIF(B:B,LEFT(B3,9)&"*",C:C)`，B 列匹配 B3 前 9 位时 C3 自己也命中，导致 C3 自引用 → `~CIRCULAR~REF~`。修法：用辅助列 / 显式排除自身（`SUMIFS(C:C, B:B, ..., A:A, "<>"&A3)`）/ 缩小范围避开自己 -6. **REGEX 模式覆盖率验证**：公式里的 `REGEXEXTRACT` / `REGEXMATCH` / `REGEXREPLACE` 等正则模式落地前必须用本地脚本在源列上跑一遍命中率统计（`df[col].str.contains(pattern).mean()`）；命中率 < 100% 时必须扩展 pattern 或加多分支（IFS / 多个 IFERROR 串联）兜底，**禁止**只覆盖样本前 N 行就交付（典型反例：用 `REGEXEXTRACT(D5,"长(\d+)")` 只匹配带"长"前缀的尺寸文本，对"宽×高"、"×"、"*"等其它分隔符直接漏匹配） +6. **REGEX 模式覆盖率验证**：公式里的 `REGEXEXTRACT` / `REGEXMATCH` / `REGEXREPLACE` 等正则模式落地前必须用 本地脚本 在源列上跑一遍命中率统计（`df[col].str.contains(pattern).mean()`）；命中率 < 100% 时必须扩展 pattern 或加多分支（IFS / 多个 IFERROR 串联）兜底，**禁止**只覆盖样本前 N 行就交付（典型反例：用 `REGEXEXTRACT(D5,"长(\d+)")` 只匹配带"长"前缀的尺寸文本，对"宽×高"、"×"、"*"等其它分隔符直接漏匹配） 7. **公式范围与用户指令字面对齐**：用户说"对 F 至 L 列求和"就必须写 `SUM(F2:L2)` 或 `F2+G2+H2+I2+J2+K2+L2`，**不能漏列、多列、错列**。写完用 `+cells-get` 拿回 `formula` 字符串，与用户原话逐字对照（参与求和的列名一致 / 起止列号一致 / 运算符一致），不一致就是违规 -⚠️ **收到 `formula_errors` 反馈后不要只打补丁（高频致命错误）**：`+cells-set` 返回值里若出现 `formula_errors: [{cell, formula, error_type, detail}]`，说明某些 cell 公式编译失败（`error_type=compile_failed` 通常是函数语法错如 `SPLIT(x)[1]` 的下标取值飞书不支持（SPLIT 本身支持，取第 N 项用 `INDEX(SPLIT(...),N)`）；`non_formula` 是 `=` 开头但解析不通过）。此时**禁止只聚焦修报错点的局部语法**（如仅把 `[1]` 换成 `INDEX(..,1)`），必须： +⚠️ **收到 `formula_errors` 反馈后不要只打补丁（高频致命错误）**：`+cells-set` 返回值里若出现 `formula_errors: [{cell, formula, error_type, detail}]`，说明某些 cell 公式编译失败（`error_type=compile_failed` 通常是函数语法错如 `SPLIT(x)[1]` 飞书不支持；`non_formula` 是 `=` 开头但解析不通过）。此时**禁止只聚焦修报错点的局部语法**（如仅把 `[1]` 换成 `INDEX(..,1)`），必须： 1. **重新审视整条公式的完整性**：被 formula_errors 标出的那一行，公式除了下标语法错，还可能有其他先天缺陷（字符清洗不全、IFERROR 兜底漏条件、引用列写错），修完语法错后立即整体复核 2. **同步对称修复所有相似列**：如果同一任务涉及多列相似处理（如"算 H 列面积"用 D 列尺寸、"算 I 列面积"用 E 列尺寸），**修完一列必须把同样的清洗/兜底逻辑同步到所有相似列**，禁止出现 H 列用 `SUBSTITUTE(长)+SUBSTITUTE(高)+SUBSTITUTE(×)` 而 I 列只用 `SUBSTITUTE(×)` 这种不对称处理——会导致一列编译通过有值、另一列编译通过但 IFERROR 全返回空，用户看到的是"数据为空"而非"公式错" @@ -106,7 +109,7 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl - **语义信号**（二选一）：用户 prompt 含"合计/汇总/总计/统计/各科平均分/最下面加一行算…/底部总计"等意图词；或上下文明确是"表尾追加一行做聚合" - **结构信号**：新行全行都在做聚合（含 `=SUM/AVERAGE/COUNT/MAX/MIN/SUBTOTAL(...)`，支持 IFERROR 包裹），**不是**单个 cell 算个参考值或每行都算的派生列 -满足上述时，**不要在本 skill 里猜样式**，直接去读 `lark-sheets-visual-standards` 的「场景一 → 1A. 添加汇总行 / 表头行」章节，按那里的样式要点配齐 `font.bold / horizontal_alignment / background_color / border_styles`。 +满足上述时，**不要在本 skill 里猜样式**，直接去读 `lark-sheets-visual-standards` 的"汇总行规范"章节，按那里的规则配齐 `font.bold / horizontal_alignment / background_color / border_styles`。 反例（**不是**汇总行，禁止自动加粗）： - 用户说"在 H5 帮我算个 AVERAGE 参考"→ 单 cell 计算 @@ -115,10 +118,35 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl **正确做法**（二选一）： -- **做法 A（推荐）**：按上方「内容与样式分离写入」两步法——先用模板单元格 + `--copy-to-range` 铺**完整样式**（`cell_styles` + `border_styles` 都要，不能只铺 border，否则新行字体 / 对齐 / 背景色全裸奔），再单独 `+cells-set` 写 value / formula。汇总行的 `cell_styles` 要点（bold / 背景色 / 上边框）见 `lark-sheets-visual-standards` 的「场景一 → 1A. 添加汇总行 / 表头行」。 -- **做法 B**：一次写入，但每个 cell（含空白格）都显式带 `cell_styles` + `border_styles`，**不能用 `{}`**。 +**做法 A（推荐）：两步走——先铺样式、再覆内容** -**判断是不是"新行"**：写入 range 超出 `+csv-get` 返回的 `current_region` 右 / 下边界（如 `current_region=A1:H10`、写 `A11:H11`）即新行，必须按上述做法补边框。 +``` +Step 1: 用模板单元格 + copy_to_range 铺"完整样式"（不是只铺 border）到新区域 + `+cells-set` — range="A11", cells=[[{ + border_styles: {...}, + cell_styles: { /* 按行性质填充：数据行继承数据区样式；汇总行见 lark_sheet_visual_standards */ } + }]], copy_to_range="A11:H11" + +Step 2: 再用 `+cells-set` 单独写具体 value/formula（不再传样式，避免覆盖） + `+cells-set` — range="A11", cells=[[{value: "平均分"}]] + `+cells-set` — range="C11:F11", cells=[[{formula: "=AVERAGE(C2:C10)"}, {formula: "=AVERAGE(D2:D10)"}, ...]] +``` + +⚠️ **Step 1 `cell_styles` 禁止留空**：只铺 border、不铺 `cell_styles`，等于新行从格式上"裸奔"——没字体、没对齐、没背景色。如果新行是汇总行，这意味着 bold 丢失，用户感受"没做样式"。Step 1 的 `cell_styles` 要么继承源区块（`+cells-get` 读相邻已有行样式后复用），要么按汇总行规范（见 `lark-sheets-visual-standards`）配齐。 + +**做法 B：一次写入但每个 cell 都显式带样式** + +``` +`+cells-set` — range="A11:H11", cells=[[ + {value: "平均分", cell_styles: {...}, border_styles: {...}}, + {value: "", cell_styles: {...}, border_styles: {...}}, ← B11 不能是 {}，要显式带 border + {formula: "=AVERAGE(C2:C10)", cell_styles: {...}, border_styles: {...}}, + {formula: "=AVERAGE(D2:D10)", cell_styles: {...}, border_styles: {...}}, + ... +]] +``` + +**判断是不是"新行"**：`+csv-get` 返回的 `current_region` 是 `A1:H10`，你要写入的 range 是 `A11:H11`（超出 `current_region` 右/下边界），就是新行——必须按上述做法处理边框。 ## 工具选择 @@ -126,7 +154,7 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl | 场景 | 用这个 shortcut | 原因 | |------|----------------|------| -| 模型手里已经有 CSV 文本（小规模手动构造、从 `+csv-get` 取到后简单加工） | `+csv-put` | 直接传 CSV 文本 + `--start-cell`，不用自己拼二维 cells 数组；必要时自动扩容行列 | +| 模型手里已经有 CSV 文本（小规模手动构造、从 `+csv-get` 取到后简单加工） | `+csv-put` | 直接传 CSV 文本 + start_cell，不用自己拼二维 cells 数组；必要时自动扩容行列 | | 写入含公式、样式、批注、图片、数据校验等任意富写入 | `+cells-set` | 唯一支持完整字段的 shortcut | | 只改已有 cell 的样式，不动 value/formula | `+cells-set-style` | 拍平 10 个样式字段为独立 flag；不触发不必要的值写入 | | 单 cell 嵌入图片 | `+cells-set-image` | 比 `+cells-set` 参数更简短 | @@ -136,7 +164,7 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl ⚠️ `+csv-put` 只写纯值，**不会**携带公式/样式/批注/图片；公式字符串以 `=` 开头会被当作字面量文本落地。如果数据里需要公式或样式，**必须**用 `+cells-set`（或"写值 + 补样式"两步法）。 -⚠️ 大数据回写走"`+csv-get` 按 `--range` 行窗口分批读到本地 + 本地脚本处理 + `+csv-put` 分批回写"。 +⚠️ 大数据回写走"`+csv-get --max-rows N` 分批读到本地 + 本地脚本处理 + `+csv-put` 分批回写"。 ## Shortcuts @@ -159,7 +187,7 @@ _公共四件套 · 系统：`--dry-run`_ | `--range` | string | required | 写入区域（A1 格式） | | `--cells` | string + File + Stdin（复合 JSON） | required | JSON：2D 数组 `[[{cell},...],...]`，维度与 `--range` 完全一致；每个 cell 可含 `value` / `formula` / `cell_styles` / `note` / `rich_text`（含 `type="embed-image"` 单元格嵌图）等，完整字段跑 `--print-schema` | | `--allow-overwrite` | bool | optional | 允许覆盖非空 cell（默认 true）；设为 false 时遇非空 cell 报错 | -| `--max-cells` | int | optional | 防爆，默认 50000（隐藏 flag：不在 `--help` 列出，但可正常传入） | +| `--max-cells` | int | optional | 防爆，默认 50000 | | `--copy-to-range` | string | optional | 复制范围（A1 表示法）：把 --range 中 --cells 写入的内容（值/公式/样式，取决于实际传入字段）复制到该区域，公式引用自动平移（如 C2=B2 → C3=B3）。适合先写一行/一块模板再扩展填充整列/整区域（如 --range A1:G1 写模板、--copy-to-range A1:G100 填充 100 行）。支持整行 3:6、整列 C:E、到列尾 D3:D、到行尾 D3:3；支持英文逗号分隔多个目标区域，如 C1:D2,E5:F6 | ### `+cells-set-style` @@ -199,7 +227,9 @@ _公共四件套 · 系统：`--dry-run`_ | --- | --- | --- | --- | | `--range` | string | required | 目标范围（A1 格式，如 `A2:A100`） | | `--options` | string + File + Stdin（复合 JSON） | required | 选项 JSON 数组 `["opt1","opt2"]`；最多 500 项，每项 ≤100 字符，不含逗号 | +| `--colors` | string + File + Stdin（简单 JSON） | optional | RGB hex 颜色数组（如 `["#1FB6C1","#F006C2"]`），长度必须与 `--options` 一致 | | `--multiple` | bool | optional | 启用多选；默认 `false` | +| `--highlight` | bool | optional | 选项配色显示；默认 `false` | ### `+csv-put` @@ -213,34 +243,34 @@ _公共四件套 · 系统：`--dry-run`_ ## Schemas -> 复合 JSON flag 字段速查（只列顶层 + 一层嵌套）。深层结构看下方 `## Examples`，或用 `--print-schema` 读完整 JSON Schema（用法见 SKILL.md「公共 flag 速查」与「Agent 使用提示」）。 +> 复合 JSON flag（如 `--cells` / `--properties` / `--operations` / `--border-styles` / `--sort-keys`）的字段速查：只列顶层字段 + 一层嵌套结构。深层结构看 `## Examples` 段的真实示例；要拿完整 JSON Schema 跑 `lark-cli sheets --print-schema --flag-name `。先 `--print-schema`（不带 `--flag-name`）会列出该 shortcut 所有可查询的 flag。 ### `+cells-set` `--cells` **顶层字段**： -- `value` (oneOf?) — 静态单元格值（文本、数字、布尔） +- `border_styles` (object?) — 单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top） { bottom?: object, left?: object, right?: object, top?: object } +- `cell_styles` (object?) — 单元格样式属性，包括字体、颜色、对齐方式和数字格式 { background_color?: string, font_color?: string, font_line?: enum, font_size?: number, font_style?: enum, …共 10 项 } +- `data_validation` (object?) — 数据验证配置 { enable_highlight?: boolean, help_text?: string, highlight_colors?: array, items?: array, operator?: enum, …共 9 项 } - `formula` (string?) — 以 '=' 开头的单元格公式（例如：'=SUM(A1:A10)'） +- `multiple_values` (array?) — 多值内容，用于支持多选的列表验证单元格 each: { format?: string, value: oneOf } - `note` (string?) — 单元格批注/备注 -- `cell_styles` (object?) — 单元格样式属性，包括字体、颜色、对齐方式和数字格式 { font_color?: string, font_size?: number, font_weight?: enum, font_style?: enum, font_line?: enum, …共 10 项 } -- `border_styles` (object?) — 单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top） { top?: object, bottom?: object, left?: object, right?: object } -- `rich_text` (array?) — 富文本内容 each: { type: enum, text: string, style?: object, link?: string, mention_token?: string, …共 17 项 } -- `multiple_values` (array?) — 多值内容，用于支持多选的列表验证单元格 each: { value: oneOf, format?: string } -- `data_validation` (object?) — 数据验证配置 { type: enum, items?: array, range?: string, operator?: enum, values?: array, …共 7 项 } +- `rich_text` (array?) — 富文本内容 each: { attachment_name?: string, attachment_token?: string, attachment_uri?: string, file_size?: number, image_height?: number, …共 17 项 } +- `value` (oneOf?) — 静态单元格值（文本、数字、布尔） ### `+cells-set-style` `--border-styles` _单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top）_ **顶层字段**： -- `top` (object?) { style?: enum, weight?: enum, color?: string } -- `bottom` (object?) { style?: enum, weight?: enum, color?: string } -- `left` (object?) { style?: enum, weight?: enum, color?: string } -- `right` (object?) { style?: enum, weight?: enum, color?: string } +- `bottom` (object?) { color?: string, style?: enum, weight?: enum } +- `left` (object?) { color?: string, style?: enum, weight?: enum } +- `right` (object?) { color?: string, style?: enum, weight?: enum } +- `top` (object?) { color?: string, style?: enum, weight?: enum } ### `+dropdown-set` `--options` -_列表选项_ +_列表选项（type='list' 时必填）_ **数组项**（类型 string）： - 标量：string @@ -265,9 +295,9 @@ _列表选项_ 示例： ```bash -# 纯值（数组形态）；默认即覆盖非空 cell，无需显式传 --allow-overwrite +# 纯值（数组形态） lark-cli sheets +cells-set --url "https://example.feishu.cn/sheets/shtXXX" \ - --sheet-name "Sheet1" --range "A1:B2" \ + --sheet-name "Sheet1" --range "A1:B2" --allow-overwrite \ --cells '[[{"value":"name"},{"value":"score"}],[{"value":"alice"},{"value":95}]]' # 富 cell（公式 + 样式，cells 是二维矩阵每元素一个 cell schema） From 2ee2a59dffc9328f4893c93abab55f91dc94bff1 Mon Sep 17 00:00:00 2001 From: zhengzhijie Date: Mon, 25 May 2026 11:24:53 +0800 Subject: [PATCH 06/11] chore(sheets): re-sync from spec + loosen --colors length check MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Catches up to sheet-skill-spec's 2026-05-25 base sync (MR !7) after rebasing onto upstream feat/lark-sheets-refactor (12 new upstream commits including the lark-sheets skill refactor + tools-schema migration). Spec changes flowing in: - highlight_colors description loosened: length may be **shorter than** --options (server cycles remaining slots through a built-in 10-color palette); previously the tool errored on any length mismatch. - shortcuts/sheets/data/flag-schemas.json: mass re-mirror — generator now emits `type` before `properties` and adds explicit `additionalProperties: false` on object schemas (cosmetic, no behavior change). - skills/lark-sheets/references/lark-sheets-{batch-update,chart,write-cells}.md: --options gains the type='list' tag; data_validation inline field-count goes 7 → 9 (catches up the highlight schema in the summary); chart position / size marked optional per upstream. Go-side adjustment: - buildDropdownValidation / validateDropdownOptionsColors: change the --colors length check from strict-equal to "must not exceed --options" to match the relaxed schema. - TestDropdownSet_ColorsLengthMismatch -> TestDropdownSet_ColorsLongerThanOptions (now hits the overflow path with 3 colors vs 2 options). - New TestDropdownSet_ColorsShorterAccepted: 2 colors vs 4 options is legal and forwarded as-is. --- shortcuts/sheets/data/flag-schemas.json | 7674 ++++++++--------- shortcuts/sheets/lark_sheet_write_cells.go | 15 +- .../sheets/lark_sheet_write_cells_test.go | 39 +- .../references/lark-sheets-batch-update.md | 2 +- .../references/lark-sheets-chart.md | 4 +- .../references/lark-sheets-write-cells.md | 112 +- 6 files changed, 3921 insertions(+), 3925 deletions(-) diff --git a/shortcuts/sheets/data/flag-schemas.json b/shortcuts/sheets/data/flag-schemas.json index 3d377a1db..f7646942c 100644 --- a/shortcuts/sheets/data/flag-schemas.json +++ b/shortcuts/sheets/data/flag-schemas.json @@ -79,462 +79,393 @@ }, "+cells-batch-set-style": { "border-styles": { + "type": "object", "description": "单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top）。", "properties": { - "bottom": { + "top": { + "type": "object", "properties": { - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", + "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ], - "type": "string" + ] }, "weight": { "description": "边框粗细/线宽", + "type": "string", "enum": [ "thin", "medium", "thick" - ], + ] + }, + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } - }, - "type": "object" + } }, - "left": { + "bottom": { + "type": "object", "properties": { - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", + "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ], - "type": "string" + ] }, "weight": { "description": "边框粗细/线宽", + "type": "string", "enum": [ "thin", "medium", "thick" - ], + ] + }, + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } - }, - "type": "object" + } }, - "right": { + "left": { + "type": "object", "properties": { - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", + "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ], - "type": "string" + ] }, "weight": { "description": "边框粗细/线宽", + "type": "string", "enum": [ "thin", "medium", "thick" - ], + ] + }, + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } - }, - "type": "object" + } }, - "top": { + "right": { + "type": "object", "properties": { - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", + "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ], - "type": "string" + ] }, "weight": { "description": "边框粗细/线宽", + "type": "string", "enum": [ "thin", "medium", "thick" - ], + ] + }, + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } - }, - "type": "object" + } } - }, - "type": "object" + } } }, "+cells-set": { "cells": { + "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": "单元格批注/备注", + "type": "string" + }, + "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": { - "bottom": { + "top": { + "type": "object", "properties": { - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", + "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ], - "type": "string" + ] }, "weight": { "description": "边框粗细/线宽", + "type": "string", "enum": [ "thin", "medium", "thick" - ], + ] + }, + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } - }, - "type": "object" + } }, - "left": { + "bottom": { + "type": "object", "properties": { - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", + "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ], - "type": "string" + ] }, "weight": { "description": "边框粗细/线宽", + "type": "string", "enum": [ "thin", "medium", "thick" - ], + ] + }, + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } - }, - "type": "object" + } }, - "right": { + "left": { + "type": "object", "properties": { - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", + "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ], - "type": "string" + ] }, "weight": { "description": "边框粗细/线宽", + "type": "string", "enum": [ "thin", "medium", "thick" - ], + ] + }, + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } - }, - "type": "object" + } }, - "top": { + "right": { + "type": "object", "properties": { - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", + "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ], - "type": "string" + ] }, "weight": { "description": "边框粗细/线宽", + "type": "string", "enum": [ "thin", "medium", "thick" - ], + ] + }, + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } - }, - "type": "object" + } } - }, - "type": "object" - }, - "cell_styles": { - "description": "单元格样式属性，包括字体、颜色、对齐方式和数字格式", - "properties": { - "background_color": { - "description": "背景颜色（十六进制，例如 \"#ffffff\"）", - "type": "string" - }, - "font_color": { - "description": "字体颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, - "font_line": { - "description": "字体线条样式", - "enum": [ - "none", - "underline", - "line-through" - ], - "type": "string" - }, - "font_size": { - "description": "字体大小（单位：px/像素，例如 10、12、14）", - "type": "number" - }, - "font_style": { - "description": "字体样式", - "enum": [ - "normal", - "italic" - ], - "type": "string" - }, - "font_weight": { - "description": "字重", - "enum": [ - "normal", - "bold" - ], - "type": "string" - }, - "horizontal_alignment": { - "description": "水平对齐方式", - "enum": [ - "left", - "center", - "right" - ], - "type": "string" - }, - "number_format": { - "description": "数字格式（例如：文本用 \"@\"、数字用 \"0.00\"、货币用 \"$#,##0.00\"、日期用 \"mm/dd/yyyy\"）", - "type": "string" - }, - "vertical_alignment": { - "description": "垂直对齐方式", - "enum": [ - "top", - "middle", - "bottom" - ], - "type": "string" - }, - "word_wrap": { - "description": "是否自动换行，默认溢出，可选自动换行或裁剪。", - "enum": [ - "overflow", - "auto-wrap", - "word-clip" - ], - "type": "string" - } - }, - "type": "object" - }, - "data_validation": { - "description": "数据验证配置。设为 null 可清除已有的数据验证。", - "properties": { - "enable_highlight": { - "description": "是否开启下拉选项的胶囊背景色高亮，仅 type='list'/'listFromRange' 生效，默认 false。", - "type": "boolean" - }, - "help_text": { - "description": "验证失败时显示的提示文本", - "type": "string" - }, - "highlight_colors": { - "description": "下拉选项的胶囊背景色数组（十六进制，例如 [\"#FFE699\",\"#bff7d9\",\"#ffb3b3\"]），仅当 enable_highlight=true 时生效。如提供，长度必须严格匹配：type='list' 时等于 items 长度；type='listFromRange' 时等于 range 内单元格数（行优先顺序，如 A1:A10 对应第 1-10 项；A1:B2 顺序为 A1,B1,A2,B2）。长度不匹配工具会报错。不提供时所有选项使用默认色 #bacefd。", - "items": { - "type": "string" - }, - "type": "array" - }, - "items": { - "description": "列表选项（type='list' 时必填）", - "items": { - "type": "string" - }, - "type": "array" - }, - "operator": { - "description": "比较运算符（type='number'/'date'/'textLength' 时必填）", - "enum": [ - "equal", - "notEqual", - "greaterThan", - "greaterThanOrEqual", - "lessThan", - "lessThanOrEqual", - "between", - "notBetween" - ], - "type": "string" - }, - "range": { - "description": "源数据区域（type='listFromRange' 时必填，格式：'SheetName!A1:A10'）", - "type": "string" - }, - "support_multiple_values": { - "description": "列表验证是否支持多选（type='list'/'listFromRange' 时可选，默认 false）", - "type": "boolean" - }, - "type": { - "description": "数据验证类型：list（下拉列表）、listFromRange（引用范围下拉列表）、number（数字）、date（日期）、textLength（文本长度）、checkbox（复选框）", - "enum": [ - "list", - "listFromRange", - "number", - "date", - "textLength", - "checkbox" - ], - "type": "string" - }, - "values": { - "description": "比较值（operator 为 'between'/'notBetween' 时需要两个值，其它运算符需要一个值）", - "items": { - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - } - ] - }, - "type": "array" - } - }, - "required": [ - "type" - ], - "type": "object" - }, - "formula": { - "description": "以 '=' 开头的单元格公式（例如：'=SUM(A1:A10)'）。公式必须写在此字段，而不是 'value'。", - "type": "string" - }, - "multiple_values": { - "description": "多值内容，用于支持多选的列表验证单元格。设置后会忽略 value 和 rich_text 字段。", - "items": { - "properties": { - "format": { - "description": "可选的数字格式（例如 '$#,##0.00'）", - "type": "string" - }, - "value": { - "description": "值（文本、数字、布尔）", - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - }, - "required": [ - "value" - ], - "type": "object" - }, - "type": "array" - }, - "note": { - "description": "单元格批注/备注", - "type": "string" + } }, "rich_text": { "description": "富文本内容。设置后会忽略 value 字段。可包含带样式的文本段 text、超链接 link、@提及 mention、单元格图片 embed-image、附件 attachment。", + "type": "array", "items": { + "type": "object", "properties": { - "attachment_name": { - "description": "附件文件名称（仅 type='attachment' 时使用，配合 attachment_reference_id 使用，创建新附件时必填）", + "type": { + "description": "段类型", + "type": "string", + "enum": [ + "text", + "link", + "mention", + "embed-image", + "attachment" + ] + }, + "text": { + "description": "显示文本", "type": "string" }, - "attachment_token": { - "description": "附件文件 token，通过飞书 Drive 上传获取（仅 type='attachment' 时可选，修改已有附件时可从 get_cell_range 获取）", + "style": { + "description": "文本段样式（仅 type='text' 时生效），结构同 cell_styles", + "type": "object" + }, + "link": { + "description": "超链接地址（仅 type='link' 时必填）", "type": "string" }, - "attachment_uri": { - "description": "附件文件 reference_id（仅 type='attachment' 时使用，与 attachment_token 二选一，如`<|attachment|>:abcdef` 或者 `<|superscript|>:abcdef-<|attachment|>:abcdef`，其中 `abcdef` 为实际的对象 ID，占位符仅用于示意）", + "mention_token": { + "description": "@提及目标的 token，如 userId 或 fileId（仅 type='mention' 时必填）", "type": "string" }, - "file_size": { - "description": "附件文件大小（字节，仅 type='attachment' 时使用）", + "mention_type": { + "description": "@提及类型编号（仅 type='mention' 时可选）", + "type": "number" + }, + "notify": { + "description": "是否发送通知（仅 type='mention' 时可选，默认 true）", + "type": "boolean" + }, + "image_width": { + "description": "图片宽度（像素，仅 type='embed-image' 时使用）", "type": "number" }, "image_height": { @@ -545,2275 +476,2405 @@ "description": "图片名称（仅 type='embed-image' 时使用，创建新图片时必填）", "type": "string" }, - "image_token": { - "description": "图片文件 token（仅 type='embed-image' 时可选，修改已有图片时可从 get_cell_range 获取）", - "type": "string" - }, "image_uri": { "description": "图片文件 reference_id（仅 type='embed-image' 时使用，与 image_token 二选一，如`<|image|>:abcdef` 或者 `<|superscript|>:abcdef-<|image|>:abcdef`，其中 `abcdef` 为实际的对象 ID，占位符仅用于示意）", "type": "string" }, - "image_width": { - "description": "图片宽度（像素，仅 type='embed-image' 时使用）", - "type": "number" + "image_token": { + "description": "图片文件 token（仅 type='embed-image' 时可选，修改已有图片时可从 get_cell_range 获取）", + "type": "string" }, - "link": { - "description": "超链接地址（仅 type='link' 时必填）", + "attachment_token": { + "description": "附件文件 token，通过飞书 Drive 上传获取（仅 type='attachment' 时可选，修改已有附件时可从 get_cell_range 获取）", "type": "string" }, - "mention_token": { - "description": "@提及目标的 token，如 userId 或 fileId（仅 type='mention' 时必填）", + "attachment_uri": { + "description": "附件文件 reference_id（仅 type='attachment' 时使用，与 attachment_token 二选一，如`<|attachment|>:abcdef` 或者 `<|superscript|>:abcdef-<|attachment|>:abcdef`，其中 `abcdef` 为实际的对象 ID，占位符仅用于示意）", "type": "string" }, - "mention_type": { - "description": "@提及类型编号（仅 type='mention' 时可选）", - "type": "number" + "attachment_name": { + "description": "附件文件名称（仅 type='attachment' 时使用，配合 attachment_reference_id 使用，创建新附件时必填）", + "type": "string" }, "mime_type": { "description": "附件 MIME 类型（仅 type='attachment' 时使用，例如 'application/pdf'）", "type": "string" }, - "notify": { - "description": "是否发送通知（仅 type='mention' 时可选，默认 true）", - "type": "boolean" - }, - "style": { - "description": "文本段样式（仅 type='text' 时生效），结构同 cell_styles", - "type": "object" - }, - "text": { - "description": "显示文本", - "type": "string" - }, - "type": { - "description": "段类型", - "enum": [ - "text", - "link", - "mention", - "embed-image", - "attachment" - ], - "type": "string" + "file_size": { + "description": "附件文件大小（字节，仅 type='attachment' 时使用）", + "type": "number" } }, "required": [ "type", "text" - ], - "type": "object" - }, - "type": "array" + ] + } }, - "value": { - "description": "静态单元格值（文本、数字、布尔）。公式请优先使用 'formula' 字段；如果误把以 '=' 开头的公式字符串写到这里，工具会按 Excel 语义自动识别为公式入库，但仍应按 'formula' 字段的契约传参。", - "oneOf": [ - { - "type": "string" - }, - { - "type": "number" - }, - { - "type": "boolean" - } - ] - } - }, - "type": "object" - } - }, - "+cells-set-style": { + "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", + "properties": { + "type": { + "description": "数据验证类型：list（下拉列表）、listFromRange（引用范围下拉列表）、number（数字）、date（日期）、textLength（文本长度）、checkbox（复选框）", + "type": "string", + "enum": [ + "list", + "listFromRange", + "number", + "date", + "textLength", + "checkbox" + ] + }, + "items": { + "description": "列表选项（type='list' 时必填）", + "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' 生效，默认 false。", + "type": "boolean" + }, + "highlight_colors": { + "description": "下拉选项的胶囊背景色数组（十六进制，例如 [\"#FFE699\",\"#bff7d9\",\"#ffb3b3\"]），仅当 enable_highlight=true 时生效。按顺序对应（type='list' 对应 items；type='listFromRange' 按 range 内单元格行优先顺序，如 A1:A10 对应第 1-10 项；A1:B2 顺序为 A1,B1,A2,B2）。长度可以短于但不能长于；未指定项及不提供该字段时按内置 10 色色板循环补色。", + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "type" + ] + } + } + } + }, + "+cells-set-style": { "border-styles": { + "type": "object", "description": "单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top）。", "properties": { - "bottom": { + "top": { + "type": "object", "properties": { - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", + "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ], - "type": "string" + ] }, "weight": { "description": "边框粗细/线宽", + "type": "string", "enum": [ "thin", "medium", "thick" - ], + ] + }, + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } - }, - "type": "object" + } }, - "left": { + "bottom": { + "type": "object", "properties": { - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", + "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ], - "type": "string" + ] }, "weight": { "description": "边框粗细/线宽", + "type": "string", "enum": [ "thin", "medium", "thick" - ], + ] + }, + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } - }, - "type": "object" + } }, - "right": { + "left": { + "type": "object", "properties": { - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", + "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ], - "type": "string" + ] }, "weight": { "description": "边框粗细/线宽", + "type": "string", "enum": [ "thin", "medium", "thick" - ], + ] + }, + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } - }, - "type": "object" + } }, - "top": { + "right": { + "type": "object", "properties": { - "color": { - "description": "边框颜色（十六进制，例如 \"#000000\"）", - "type": "string" - }, "style": { "description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）", + "type": "string", "enum": [ "solid", "dashed", "dotted", "double", "none" - ], - "type": "string" + ] }, "weight": { "description": "边框粗细/线宽", + "type": "string", "enum": [ "thin", "medium", "thick" - ], + ] + }, + "color": { + "description": "边框颜色（十六进制，例如 \"#000000\"）", "type": "string" } - }, - "type": "object" + } } - }, - "type": "object" + } } }, "+chart-create": { "properties": { - "additionalProperties": {}, "description": "创建/更新的图表属性。", + "type": "object", "properties": { - "offset": { - "additionalProperties": false, - "description": "可选。图表在位置基础上的偏移量（像素）。", - "properties": { - "col_offset": { - "description": "列偏移量（像素）", - "type": "number" - }, - "row_offset": { - "description": "行偏移量（像素）", - "type": "number" - } - }, - "type": "object" - }, "position": { - "additionalProperties": false, + "type": "object", "description": "必填。图表在表格中的单元格位置。注意：选择位置时应避免覆盖已有数据的单元格，并确保图表不超出当前表格的行列范围。", "properties": { - "col": { - "description": "列索引，例如 \"A\"、\"B\"", - "type": "string" - }, "row": { - "description": "行索引（0-based）", + "type": "number", "minimum": 0, - "type": "number" + "description": "行索引（0-based）" + }, + "col": { + "type": "string", + "description": "列索引，例如 \"A\"、\"B\"" } }, "required": [ "row", "col" ], - "type": "object" + "additionalProperties": false + }, + "offset": { + "type": "object", + "description": "可选。图表在位置基础上的偏移量（像素）。", + "properties": { + "row_offset": { + "type": "number", + "description": "行偏移量（像素）" + }, + "col_offset": { + "type": "number", + "description": "列偏移量（像素）" + } + }, + "additionalProperties": false }, "size": { - "additionalProperties": false, + "type": "object", "description": "必填。图表大小（像素）。注意：设定大小时应确保图表不超出当前表格的行列范围，并避免覆盖已有数据的单元格。", "properties": { - "height": { - "description": "高度（像素）", + "width": { + "type": "number", "minimum": 10, - "type": "number" + "description": "宽度（像素）" }, - "width": { - "description": "宽度（像素）", + "height": { + "type": "number", "minimum": 10, - "type": "number" + "description": "高度（像素）" } }, "required": [ "width", "height" ], - "type": "object" + "additionalProperties": false }, "snapshot": { + "type": "object", "description": "图表快照配置。更新图表时必须传入完整的图表属性定义，不能只传修改的部分。应先通过 get_chart_objects 获取当前图表快照，修改需要变更的字段后，将完整快照传入。", "properties": { - "data": { - "description": "图表数据配置", + "title": { + "type": "object", + "description": "图表标题配置", "properties": { - "dim1": { - "description": "维度1配置（类别维度）", - "properties": { - "field": { - "description": "字段配置（静态数据时传此参数）", - "properties": { - "name": { - "description": "字段名称", - "type": "string" - }, - "text": { - "description": "字段文本数据", - "type": "string" - }, - "valueType": { - "description": "值类型", - "enum": [ - "number", - "string" - ], - "type": "string" - } - }, - "required": [ - "text" - ], - "type": "object" - }, - "serie": { - "description": "系列配置（非静态数据时传此参数）", - "properties": { - "aggregate": { - "description": "是否汇总相同的类别，默认为true，true 情况下 aggregateType 才生效", - "type": "boolean" - }, - "index": { - "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引", - "type": "number" - }, - "nameRef": { - "description": "可选。维度名称的单元格引用（A1 表示法，如 'Sheet1!A1'）。当维度名称不直接来自 refs 首行/首列时，可通过此字段把维度名显式指向目标表头单元格，图表会以该单元格当前值作为类别维度名展示。", - "type": "string" - } - }, - "type": "object" - } - }, - "type": "object" + "text": { + "type": "string", + "description": "标题文本" }, - "dim2": { - "description": "维度2配置（值维度）", - "properties": { - "fields": { - "description": "字段配置数组（静态数据时传此参数）", - "items": { - "properties": { - "name": { - "description": "字段名称", - "type": "string" - }, - "text": { - "description": "字段文本数据", - "type": "string" - }, - "valueType": { - "description": "值类型", - "enum": [ - "number" - ], - "type": "string" - } - }, - "required": [ - "text" - ], - "type": "object" - }, - "type": "array" - }, - "series": { - "description": "系列配置数组（非静态数据时传此参数）", - "items": { - "properties": { - "aggregateType": { - "description": "汇总方式，默认为'sum'，仅在 aggregate 为 true 时生效", - "enum": [ - "sum", - "average", - "count", - "min", - "max", - "median" - ], - "type": "string" - }, - "index": { - "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引", - "type": "number" - }, - "nameRef": { - "description": "可选。系列名称的单元格引用（A1 表示法，如 'Sheet1!C1'）。当系列名称不直接来自 refs 首行/首列时，可通过此字段把系列名显式指向目标表头单元格，图表会以该单元格当前值作为系列名（图例/tooltip）展示。", - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - } - }, - "type": "object" - }, - "direction": { - "description": "数据方向，可选值：row（行方向）或column（列方向），常用值为column", + "textAlign": { + "type": "string", + "description": "标题对齐方式", "enum": [ - "row", - "column" - ], - "type": "string" + "left", + "center", + "right" + ] }, - "headerMode": { - "description": "表头模式。inline 表示 refs 首行/首列就是表头；detached 表示 refs 仅覆盖实际数据范围，维度名和系列名需通过 nameRef 显式指定。", + "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": [ - "inline", - "detached" - ], - "type": "string" + "left", + "center", + "right" + ] }, - "includeHiddenOrFilter": { - "description": "是否包含隐藏或过滤的数据", - "type": "boolean" + "fontSize": { + "type": "number", + "description": "字体大小" }, - "isStaticData": { - "description": "是否为静态数据", - "type": "boolean" + "bold": { + "type": "boolean", + "description": "是否加粗" }, - "refs": { - "description": "数据源引用范围数组", - "items": { - "properties": { - "value": { - "description": "图表数据源范围，格式为 'SheetName!A1:D100' 的连续区域", - "type": "string" - } - }, - "required": [ - "value" - ], - "type": "object" - }, - "type": "array" + "italic": { + "type": "boolean", + "description": "是否斜体" + }, + "underline": { + "type": "boolean", + "description": "是否下划线" + }, + "strikethrough": { + "type": "boolean", + "description": "是否删除线" + }, + "color": { + "type": "string", + "description": "字体颜色，格式为 #RRGGBB" } }, - "type": "object" + "required": [ + "text" + ] }, - "legend": { - "oneOf": [ - { - "description": "图例配置", + "style": { + "type": "object", + "description": "图表样式配置", + "properties": { + "background": { + "type": "object", + "description": "背景配置", "properties": { - "bold": { - "description": "是否加粗", - "type": "boolean" + "color": { + "type": "string", + "description": "背景颜色，格式为 #RRGGBB" + } + } + }, + "font": { + "type": "object", + "description": "字体配置", + "properties": { + "size": { + "type": "number", + "description": "字体大小" }, "color": { - "description": "字体颜色，格式为 #RRGGBB", - "type": "string" + "type": "string", + "description": "字体颜色，格式为 #RRGGBB" + } + } + }, + "border": { + "type": "object", + "description": "边框配置", + "properties": { + "color": { + "type": "string", + "description": "边框颜色，格式为 #RRGGBB" }, - "fontSize": { - "description": "字体大小", - "type": "number" + "width": { + "type": "number", + "description": "边框宽度" }, - "italic": { - "description": "是否斜体", - "type": "boolean" + "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" - ], - "type": "string" + ] }, - "strikethrough": { - "description": "是否删除线", - "type": "boolean" + "fontSize": { + "type": "number", + "description": "字体大小" + }, + "bold": { + "type": "boolean", + "description": "是否加粗" + }, + "italic": { + "type": "boolean", + "description": "是否斜体" }, "underline": { - "description": "是否下划线", - "type": "boolean" + "type": "boolean", + "description": "是否下划线" + }, + "strikethrough": { + "type": "boolean", + "description": "是否删除线" + }, + "color": { + "type": "string", + "description": "字体颜色，格式为 #RRGGBB" } - }, - "type": "object" + } }, { - "description": "false 表示隐藏图例", - "type": "boolean" + "type": "boolean", + "description": "false 表示隐藏图例" } ] }, "plotArea": { + "type": "object", "description": "绘图区域配置", "properties": { - "axes": { - "description": "坐标轴配置数组", - "items": { - "description": "坐标轴配置", - "properties": { - "axisLine": { - "description": "是否显示轴线", - "type": "boolean" - }, - "gridLine": { - "oneOf": [ - { - "description": "网格线配置", - "properties": { - "color": { - "description": "网格线颜色", - "type": "string" - }, - "width": { - "description": "网格线宽度", - "type": "number" - } - }, - "type": "object" - }, - { - "description": "false 表示隐藏网格线", - "type": "boolean" - } - ] - }, - "label": { - "description": "坐标轴标签配置", - "properties": { - "angle": { - "description": "旋转角度，可选值：-90, -45, 0, 45, 90", - "type": "number" - }, - "bold": { - "description": "是否加粗", - "type": "boolean" - }, - "color": { - "description": "字体颜色", - "type": "string" - }, - "fontSize": { - "description": "字体大小", - "type": "number" - }, - "italic": { - "description": "是否斜体", - "type": "boolean" - }, - "strikethrough": { - "description": "是否删除线", - "type": "boolean" - }, - "underline": { - "description": "是否下划线", - "type": "boolean" - } - }, - "type": "object" - }, - "max": { - "description": "最大值", - "type": "number" - }, - "min": { - "description": "最小值", - "type": "number" - }, - "position": { - "description": "坐标轴位置", - "enum": [ - "left", - "right", - "bottom" - ], - "type": "string" - }, - "title": { - "description": "坐标轴标题配置", - "properties": { - "bold": { - "description": "是否加粗", - "type": "boolean" - }, - "color": { - "description": "字体颜色", - "type": "string" - }, - "fontSize": { - "description": "字体大小", - "type": "number" - }, - "italic": { - "description": "是否斜体", - "type": "boolean" - }, - "strikethrough": { - "description": "是否删除线", - "type": "boolean" - }, - "text": { - "description": "标题文本", - "type": "string" - }, - "underline": { - "description": "是否下划线", - "type": "boolean" - } - }, - "required": [ - "text" - ], - "type": "object" - }, - "type": { - "description": "坐标轴类型", - "enum": [ - "x", - "y", - "angle", - "radius" - ], - "type": "string" - }, - "valueType": { - "description": "是否将横轴数字视为文本，linear 表示将数字视为数值, ordinal 表示将数字视为文本", - "enum": [ - "ordinal", - "linear" - ], - "type": "string" - } - }, - "required": [ - "type" - ], - "type": "object" - }, - "type": "array" - }, "plot": { + "type": "object", "description": "绘图配置", "properties": { - "areas": { - "description": "全系列面积填充配置，面积图、雷达图、组合图生效。", - "properties": { - "color": { - "description": "区域填充颜色", - "type": "string" - } - }, - "type": "object" - }, - "bars": { - "description": "全系列柱状图、条形图、组合图生效。", - "properties": { - "backgroundColor": { - "description": "背景颜色", - "type": "string" - }, - "bar": { - "description": "单个柱子配置数组", - "items": { - "properties": { - "borderColor": { - "description": "边框颜色", - "type": "string" - }, - "borderStyle": { - "description": "边框样式", - "type": "string" - }, - "borderWidth": { - "description": "边框宽度", - "type": "number" - }, - "color": { - "description": "颜色", - "type": "string" - }, - "index": { - "description": "柱子索引", - "type": "number" - } - }, - "required": [ - "index" - ], - "type": "object" - }, - "type": "array" - }, - "borderColor": { - "description": "边框颜色", - "type": "string" - }, - "borderStyle": { - "description": "边框样式", - "enum": [ - "solid", - "dashed", - "dotted" - ], - "type": "string" - }, - "borderWidth": { - "description": "边框宽度", - "type": "number" - }, - "color": { - "description": "柱子颜色", - "type": "string" - }, - "gap": { - "description": "柱子间距比例，0-1之间", - "type": "number" - }, - "width": { - "description": "柱子宽度", - "type": "number" - } - }, - "type": "object" + "type": { + "type": "string", + "description": "图表类型", + "enum": [ + "bar", + "column", + "line", + "area", + "combo", + "pie", + "radar", + "scatter" + ] }, "comboType": { + "type": "string", "description": "组合图表默认类型", "enum": [ "column", "line", "area" - ], - "type": "string" + ] + }, + "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": { - "area": { - "description": "是否填充区域", - "type": "boolean" - }, "shape": { + "type": "string", "description": "雷达图形状", "enum": [ "polygon", "circle" - ], - "type": "string" - } - }, - "type": "object" - }, - "smooth": { - "description": "是否平滑曲线", - "type": "boolean" - }, - "stack": { - "description": "堆叠配置", - "properties": { - "percentage": { - "description": "是否百分比堆叠", - "type": "boolean" + ] + }, + "area": { + "type": "boolean", + "description": "是否填充区域" } - }, - "type": "object" - }, - "step": { - "description": "是否阶梯图", - "type": "boolean" + } } - }, - "type": "object" + } }, - "labels": { - "description": "数据标签配置", + "points": { + "type": "object", + "description": "全系列数据点配置，折线图、面积图、雷达图、散点图、组合图生效。", "properties": { - "bold": { - "description": "是否加粗", - "type": "boolean" - }, - "category": { - "description": "是否显示类别名", - "type": "boolean" - }, "color": { - "description": "字体颜色", - "type": "string" - }, - "fontSize": { - "description": "字体大小", - "type": "number" - }, - "italic": { - "description": "是否斜体", - "type": "boolean" - }, - "percentage": { - "description": "是否显示百分比", - "type": "boolean" + "type": "string", + "description": "数据点颜色" }, - "position": { - "description": "标签位置", + "shape": { + "type": "string", + "description": "数据点形状", "enum": [ - "auto", - "top", - "bottom", - "left", - "right", - "center", - "inside", - "outside" - ], - "type": "string" - }, - "series": { - "description": "是否显示系列名", - "type": "boolean" - }, - "strikethrough": { - "description": "是否删除线", - "type": "boolean" + "circle", + "triangle", + "rect", + "diamond", + "square" + ] }, - "underline": { - "description": "是否下划线", - "type": "boolean" + "size": { + "type": "number", + "description": "数据点大小" }, - "value": { - "description": "是否显示值", - "type": "boolean" + "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" + ] + } } - }, - "type": "object" + } }, "lines": { + "type": "object", "description": "全系列线条配置，折线图、面积图、雷达图、组合图生效。", "properties": { "color": { - "description": "线条颜色", - "type": "string" + "type": "string", + "description": "线条颜色" + }, + "width": { + "type": "number", + "description": "线条宽度" + }, + "style": { + "type": "string", + "description": "线条样式", + "enum": [ + "solid", + "dashed", + "dotted" + ] }, "invalidType": { + "type": "string", "description": "无效值处理方式", "enum": [ "break", "zero", "link" - ], - "type": "string" + ] + } + } + }, + "areas": { + "type": "object", + "description": "全系列面积填充配置，面积图、雷达图、组合图生效。", + "properties": { + "color": { + "type": "string", + "description": "区域填充颜色" + } + } + }, + "bars": { + "type": "object", + "description": "全系列柱状图、条形图、组合图生效。", + "properties": { + "color": { + "type": "string", + "description": "柱子颜色" }, - "style": { - "description": "线条样式", + "borderColor": { + "type": "string", + "description": "边框颜色" + }, + "borderWidth": { + "type": "number", + "description": "边框宽度" + }, + "borderStyle": { + "type": "string", + "description": "边框样式", "enum": [ "solid", "dashed", "dotted" - ], - "type": "string" + ] }, "width": { - "description": "线条宽度", - "type": "number" - } - }, - "type": "object" - }, - "points": { - "description": "全系列数据点配置，折线图、面积图、雷达图、散点图、组合图生效。", - "properties": { - "color": { - "description": "数据点颜色", - "type": "string" + "type": "number", + "description": "柱子宽度" }, - "point": { - "description": "单个数据点配置数组", + "gap": { + "type": "number", + "description": "柱子间距比例，0-1之间" + }, + "backgroundColor": { + "type": "string", + "description": "背景颜色" + }, + "bar": { + "type": "array", + "description": "单个柱子配置数组", "items": { + "type": "object", "properties": { - "color": { - "description": "颜色", - "type": "string" - }, "index": { - "description": "数据点索引", - "type": "number" + "type": "number", + "description": "柱子索引" }, - "shape": { - "description": "形状", - "type": "string" + "color": { + "type": "string", + "description": "颜色" }, - "size": { - "description": "大小", - "type": "number" + "borderColor": { + "type": "string", + "description": "边框颜色" + }, + "borderWidth": { + "type": "number", + "description": "边框宽度" + }, + "borderStyle": { + "type": "string", + "description": "边框样式" } }, "required": [ "index" - ], - "type": "object" - }, - "type": "array" - }, - "shape": { - "description": "数据点形状", + ] + } + } + } + }, + "labels": { + "type": "object", + "description": "数据标签配置", + "properties": { + "position": { + "type": "string", + "description": "标签位置", "enum": [ - "circle", - "triangle", - "rect", - "diamond", - "square" - ], - "type": "string" + "auto", + "top", + "bottom", + "left", + "right", + "center", + "inside", + "outside" + ] }, - "size": { - "description": "数据点大小", - "type": "number" + "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": "字体颜色" } - }, - "type": "object" + } }, "series": { + "type": "array", "description": "单个系列配置数组", "items": { + "type": "object", "description": "系列配置", "properties": { - "area": { - "description": "区域填充配置，配置项同 plotArea.areas", - "type": "object" - }, - "bars": { - "description": "柱状图配置，配置项同 plotArea.bars", - "type": "object" + "index": { + "type": "number", + "description": "数据列索引，与 dim2.series[].index 值一致，从 1 开始（1 通常对应首列标签维度，2+ 对应后续数据维度列）" }, "comboType": { + "type": "string", "description": "组合图下该系列的图表类型，仅在 type 为 combo 时生效", "enum": [ "column", "line", "area" - ], - "type": "string" + ] }, - "index": { - "description": "数据列索引，与 dim2.series[].index 值一致，从 1 开始（1 通常对应首列标签维度，2+ 对应后续数据维度列）", - "type": "number" + "yAxisPosition": { + "type": "string", + "description": "Y轴位置", + "enum": [ + "left", + "right" + ] }, - "labels": { - "description": "数据标签配置", - "type": "object" + "points": { + "type": "object", + "description": "数据点配置，配置项同 plotArea.points" }, "line": { - "description": "线条配置，配置项同 plotArea.lines", - "type": "object" + "type": "object", + "description": "线条配置，配置项同 plotArea.lines" }, - "points": { - "description": "数据点配置，配置项同 plotArea.points", - "type": "object" + "area": { + "type": "object", + "description": "区域填充配置，配置项同 plotArea.areas" + }, + "bars": { + "type": "object", + "description": "柱状图配置，配置项同 plotArea.bars" + }, + "labels": { + "type": "object", + "description": "数据标签配置" }, "sectors": { + "type": "object", "description": "扇区配置（饼图）", "properties": { "borderColor": { - "description": "边框颜色", - "type": "string" + "type": "string", + "description": "边框颜色" }, "innerRadius": { - "description": "内半径比例，0-1之间", - "type": "number" + "type": "number", + "description": "内半径比例，0-1之间" }, "offsetRadius": { - "description": "偏移半径比例", - "type": "number" + "type": "number", + "description": "偏移半径比例" + }, + "startAngle": { + "type": "number", + "description": "起始角度，0-359" }, "sector": { + "type": "array", "description": "单个扇区配置数组", "items": { + "type": "object", "properties": { - "borderColor": { - "description": "边框颜色", - "type": "string" - }, - "color": { - "description": "颜色", - "type": "string" - }, "index": { - "description": "扇区索引", - "type": "number" + "type": "number", + "description": "扇区索引" + }, + "borderColor": { + "type": "string", + "description": "边框颜色" }, "offsetRadius": { - "description": "偏移半径", - "type": "number" + "type": "number", + "description": "偏移半径" + }, + "color": { + "type": "string", + "description": "颜色" } }, "required": [ "index" - ], - "type": "object" - }, - "type": "array" - }, - "startAngle": { - "description": "起始角度，0-359", - "type": "number" + ] + } } - }, - "type": "object" - }, - "yAxisPosition": { - "description": "Y轴位置", - "enum": [ - "left", - "right" - ], - "type": "string" + } } }, "required": [ "index" - ], - "type": "object" - }, - "type": "array" - }, - "type": { - "description": "图表类型", - "enum": [ - "bar", - "column", - "line", - "area", - "combo", - "pie", - "radar", - "scatter" - ], - "type": "string" - }, - "yAxisPosition": { - "description": "Y轴位置", - "enum": [ - "left", - "right" - ], - "type": "string" + ] + } } }, "required": [ "type" - ], - "type": "object" - } - }, - "type": "object" - }, - "style": { - "description": "图表样式配置", - "properties": { - "background": { - "description": "背景配置", - "properties": { - "color": { - "description": "背景颜色，格式为 #RRGGBB", - "type": "string" - } - }, - "type": "object" - }, - "border": { - "description": "边框配置", - "properties": { - "color": { - "description": "边框颜色，格式为 #RRGGBB", - "type": "string" - }, - "radius": { - "description": "边框圆角", - "type": "number" - }, - "style": { - "description": "边框样式", - "enum": [ - "solid", - "dashed", - "dotted" - ], - "type": "string" - }, - "width": { - "description": "边框宽度", - "type": "number" - } - }, - "type": "object" - }, - "colorGradient": { - "description": "是否启用颜色渐变", - "type": "boolean" + ] }, - "colorTheme": { - "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": [ - { - "items": { + "axes": { + "type": "array", + "description": "坐标轴配置数组", + "items": { + "type": "object", + "description": "坐标轴配置", + "properties": { + "type": { + "type": "string", + "description": "坐标轴类型", "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" - ], - "type": "string" + "x", + "y", + "angle", + "radius" + ] }, - "maxItems": 1, - "minItems": 1 - }, - { - "items": { - "description": "颜色字符串，十六进制格式：#RRGGBB", - "type": "string" + "position": { + "type": "string", + "description": "坐标轴位置", + "enum": [ + "left", + "right", + "bottom" + ] }, - "minItems": 2 - } - ], - "type": "array" - }, - "font": { - "description": "字体配置", - "properties": { - "color": { - "description": "字体颜色，格式为 #RRGGBB", - "type": "string" - }, - "size": { - "description": "字体大小", - "type": "number" - } - }, - "type": "object" - } - }, - "type": "object" - }, - "subTitle": { - "description": "图表副标题配置", - "properties": { - "bold": { - "description": "是否加粗", - "type": "boolean" - }, - "color": { - "description": "字体颜色，格式为 #RRGGBB", - "type": "string" - }, - "fontSize": { - "description": "字体大小", - "type": "number" - }, - "italic": { - "description": "是否斜体", - "type": "boolean" - }, - "strikethrough": { - "description": "是否删除线", - "type": "boolean" - }, - "text": { - "description": "副标题文本", - "type": "string" - }, - "textAlign": { - "description": "副标题对齐方式", - "enum": [ - "left", - "center", - "right" - ], - "type": "string" - }, - "underline": { - "description": "是否下划线", - "type": "boolean" - } - }, - "required": [ - "text" - ], - "type": "object" + "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" + ] + } + } + } }, - "title": { - "description": "图表标题配置", + "data": { + "type": "object", + "description": "图表数据配置", "properties": { - "bold": { - "description": "是否加粗", - "type": "boolean" - }, - "color": { - "description": "字体颜色，格式为 #RRGGBB", - "type": "string" + "isStaticData": { + "type": "boolean", + "description": "是否为静态数据" }, - "fontSize": { - "description": "字体大小", - "type": "number" + "includeHiddenOrFilter": { + "type": "boolean", + "description": "是否包含隐藏或过滤的数据" }, - "italic": { - "description": "是否斜体", - "type": "boolean" + "direction": { + "type": "string", + "description": "数据方向，可选值：row（行方向）或column（列方向），常用值为column", + "enum": [ + "row", + "column" + ] }, - "strikethrough": { - "description": "是否删除线", - "type": "boolean" + "headerMode": { + "type": "string", + "description": "表头模式。inline 表示 refs 首行/首列就是表头；detached 表示 refs 仅覆盖实际数据范围，维度名和系列名需通过 nameRef 显式指定。", + "enum": [ + "inline", + "detached" + ] }, - "text": { - "description": "标题文本", - "type": "string" + "refs": { + "type": "array", + "description": "数据源引用范围数组", + "items": { + "type": "object", + "properties": { + "value": { + "type": "string", + "description": "图表数据源范围，格式为 'SheetName!A1:D100' 的连续区域" + } + }, + "required": [ + "value" + ] + } }, - "textAlign": { - "description": "标题对齐方式", - "enum": [ - "left", - "center", - "right" - ], - "type": "string" + "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 首行/首列时，可通过此字段把维度名显式指向目标表头单元格，图表会以该单元格当前值作为类别维度名展示。" + } + } + }, + "field": { + "type": "object", + "description": "字段配置（静态数据时传此参数）", + "properties": { + "valueType": { + "type": "string", + "description": "值类型", + "enum": [ + "number", + "string" + ] + }, + "name": { + "type": "string", + "description": "字段名称" + }, + "text": { + "type": "string", + "description": "字段文本数据" + } + }, + "required": [ + "text" + ] + } + } }, - "underline": { - "description": "是否下划线", - "type": "boolean" + "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 时生效", + "enum": [ + "sum", + "average", + "count", + "min", + "max", + "median" + ] + }, + "nameRef": { + "type": "string", + "description": "可选。系列名称的单元格引用（A1 表示法，如 'Sheet1!C1'）。当系列名称不直接来自 refs 首行/首列时，可通过此字段把系列名显式指向目标表头单元格，图表会以该单元格当前值作为系列名（图例/tooltip）展示。" + } + } + } + }, + "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": [ - "text" - ], - "type": "object" + } } - }, - "type": "object" + } } }, - "type": "object" + "additionalProperties": {} } }, "+chart-update": { "properties": { - "additionalProperties": {}, "description": "创建/更新的图表属性。", + "type": "object", "properties": { - "offset": { - "additionalProperties": false, - "description": "可选。图表在位置基础上的偏移量（像素）。", - "properties": { - "col_offset": { - "description": "列偏移量（像素）", - "type": "number" - }, - "row_offset": { - "description": "行偏移量（像素）", - "type": "number" - } - }, - "type": "object" - }, "position": { - "additionalProperties": false, + "type": "object", "description": "必填。图表在表格中的单元格位置。注意：选择位置时应避免覆盖已有数据的单元格，并确保图表不超出当前表格的行列范围。", "properties": { - "col": { - "description": "列索引，例如 \"A\"、\"B\"", - "type": "string" - }, "row": { - "description": "行索引（0-based）", + "type": "number", "minimum": 0, - "type": "number" + "description": "行索引（0-based）" + }, + "col": { + "type": "string", + "description": "列索引，例如 \"A\"、\"B\"" } }, "required": [ "row", "col" ], - "type": "object" + "additionalProperties": false + }, + "offset": { + "type": "object", + "description": "可选。图表在位置基础上的偏移量（像素）。", + "properties": { + "row_offset": { + "type": "number", + "description": "行偏移量（像素）" + }, + "col_offset": { + "type": "number", + "description": "列偏移量（像素）" + } + }, + "additionalProperties": false }, "size": { - "additionalProperties": false, + "type": "object", "description": "必填。图表大小（像素）。注意：设定大小时应确保图表不超出当前表格的行列范围，并避免覆盖已有数据的单元格。", "properties": { - "height": { - "description": "高度（像素）", + "width": { + "type": "number", "minimum": 10, - "type": "number" + "description": "宽度（像素）" }, - "width": { - "description": "宽度（像素）", + "height": { + "type": "number", "minimum": 10, - "type": "number" + "description": "高度（像素）" } }, "required": [ "width", "height" ], - "type": "object" + "additionalProperties": false }, "snapshot": { + "type": "object", "description": "图表快照配置。更新图表时必须传入完整的图表属性定义，不能只传修改的部分。应先通过 get_chart_objects 获取当前图表快照，修改需要变更的字段后，将完整快照传入。", "properties": { - "data": { - "description": "图表数据配置", + "title": { + "type": "object", + "description": "图表标题配置", "properties": { - "dim1": { - "description": "维度1配置（类别维度）", - "properties": { - "field": { - "description": "字段配置（静态数据时传此参数）", - "properties": { - "name": { - "description": "字段名称", - "type": "string" - }, - "text": { - "description": "字段文本数据", - "type": "string" - }, - "valueType": { - "description": "值类型", - "enum": [ - "number", - "string" - ], - "type": "string" - } - }, - "required": [ - "text" - ], - "type": "object" - }, - "serie": { - "description": "系列配置（非静态数据时传此参数）", - "properties": { - "aggregate": { - "description": "是否汇总相同的类别，默认为true，true 情况下 aggregateType 才生效", - "type": "boolean" - }, - "index": { - "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引", - "type": "number" - }, - "nameRef": { - "description": "可选。维度名称的单元格引用（A1 表示法，如 'Sheet1!A1'）。当维度名称不直接来自 refs 首行/首列时，可通过此字段把维度名显式指向目标表头单元格，图表会以该单元格当前值作为类别维度名展示。", - "type": "string" - } - }, - "type": "object" - } - }, - "type": "object" - }, - "dim2": { - "description": "维度2配置（值维度）", - "properties": { - "fields": { - "description": "字段配置数组（静态数据时传此参数）", - "items": { - "properties": { - "name": { - "description": "字段名称", - "type": "string" - }, - "text": { - "description": "字段文本数据", - "type": "string" - }, - "valueType": { - "description": "值类型", - "enum": [ - "number" - ], - "type": "string" - } - }, - "required": [ - "text" - ], - "type": "object" - }, - "type": "array" - }, - "series": { - "description": "系列配置数组（非静态数据时传此参数）", - "items": { - "properties": { - "aggregateType": { - "description": "汇总方式，默认为'sum'，仅在 aggregate 为 true 时生效", - "enum": [ - "sum", - "average", - "count", - "min", - "max", - "median" - ], - "type": "string" - }, - "index": { - "description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引", - "type": "number" - }, - "nameRef": { - "description": "可选。系列名称的单元格引用（A1 表示法，如 'Sheet1!C1'）。当系列名称不直接来自 refs 首行/首列时，可通过此字段把系列名显式指向目标表头单元格，图表会以该单元格当前值作为系列名（图例/tooltip）展示。", - "type": "string" - } - }, - "type": "object" - }, - "type": "array" - } - }, - "type": "object" + "text": { + "type": "string", + "description": "标题文本" }, - "direction": { - "description": "数据方向，可选值：row（行方向）或column（列方向），常用值为column", + "textAlign": { + "type": "string", + "description": "标题对齐方式", "enum": [ - "row", - "column" - ], - "type": "string" + "left", + "center", + "right" + ] }, - "headerMode": { - "description": "表头模式。inline 表示 refs 首行/首列就是表头；detached 表示 refs 仅覆盖实际数据范围，维度名和系列名需通过 nameRef 显式指定。", + "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": [ - "inline", - "detached" - ], - "type": "string" + "left", + "center", + "right" + ] }, - "includeHiddenOrFilter": { - "description": "是否包含隐藏或过滤的数据", - "type": "boolean" + "fontSize": { + "type": "number", + "description": "字体大小" }, - "isStaticData": { - "description": "是否为静态数据", - "type": "boolean" + "bold": { + "type": "boolean", + "description": "是否加粗" }, - "refs": { - "description": "数据源引用范围数组", - "items": { - "properties": { - "value": { - "description": "图表数据源范围，格式为 'SheetName!A1:D100' 的连续区域", - "type": "string" - } - }, - "required": [ - "value" - ], - "type": "object" - }, - "type": "array" + "italic": { + "type": "boolean", + "description": "是否斜体" + }, + "underline": { + "type": "boolean", + "description": "是否下划线" + }, + "strikethrough": { + "type": "boolean", + "description": "是否删除线" + }, + "color": { + "type": "string", + "description": "字体颜色，格式为 #RRGGBB" } }, - "type": "object" + "required": [ + "text" + ] }, - "legend": { - "oneOf": [ - { - "description": "图例配置", + "style": { + "type": "object", + "description": "图表样式配置", + "properties": { + "background": { + "type": "object", + "description": "背景配置", "properties": { - "bold": { - "description": "是否加粗", - "type": "boolean" + "color": { + "type": "string", + "description": "背景颜色，格式为 #RRGGBB" + } + } + }, + "font": { + "type": "object", + "description": "字体配置", + "properties": { + "size": { + "type": "number", + "description": "字体大小" }, "color": { - "description": "字体颜色，格式为 #RRGGBB", - "type": "string" + "type": "string", + "description": "字体颜色，格式为 #RRGGBB" + } + } + }, + "border": { + "type": "object", + "description": "边框配置", + "properties": { + "color": { + "type": "string", + "description": "边框颜色，格式为 #RRGGBB" }, - "fontSize": { - "description": "字体大小", - "type": "number" + "width": { + "type": "number", + "description": "边框宽度" }, - "italic": { - "description": "是否斜体", - "type": "boolean" + "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" - ], - "type": "string" + ] }, - "strikethrough": { - "description": "是否删除线", - "type": "boolean" + "fontSize": { + "type": "number", + "description": "字体大小" + }, + "bold": { + "type": "boolean", + "description": "是否加粗" + }, + "italic": { + "type": "boolean", + "description": "是否斜体" }, "underline": { - "description": "是否下划线", - "type": "boolean" + "type": "boolean", + "description": "是否下划线" + }, + "strikethrough": { + "type": "boolean", + "description": "是否删除线" + }, + "color": { + "type": "string", + "description": "字体颜色，格式为 #RRGGBB" } - }, - "type": "object" + } }, { - "description": "false 表示隐藏图例", - "type": "boolean" + "type": "boolean", + "description": "false 表示隐藏图例" } ] }, "plotArea": { + "type": "object", "description": "绘图区域配置", "properties": { - "axes": { - "description": "坐标轴配置数组", - "items": { - "description": "坐标轴配置", - "properties": { - "axisLine": { - "description": "是否显示轴线", - "type": "boolean" - }, - "gridLine": { - "oneOf": [ - { - "description": "网格线配置", - "properties": { - "color": { - "description": "网格线颜色", - "type": "string" - }, - "width": { - "description": "网格线宽度", - "type": "number" - } - }, - "type": "object" - }, - { - "description": "false 表示隐藏网格线", - "type": "boolean" - } - ] - }, - "label": { - "description": "坐标轴标签配置", - "properties": { - "angle": { - "description": "旋转角度，可选值：-90, -45, 0, 45, 90", - "type": "number" - }, - "bold": { - "description": "是否加粗", - "type": "boolean" - }, - "color": { - "description": "字体颜色", - "type": "string" - }, - "fontSize": { - "description": "字体大小", - "type": "number" - }, - "italic": { - "description": "是否斜体", - "type": "boolean" - }, - "strikethrough": { - "description": "是否删除线", - "type": "boolean" - }, - "underline": { - "description": "是否下划线", - "type": "boolean" - } - }, - "type": "object" - }, - "max": { - "description": "最大值", - "type": "number" - }, - "min": { - "description": "最小值", - "type": "number" - }, - "position": { - "description": "坐标轴位置", - "enum": [ - "left", - "right", - "bottom" - ], - "type": "string" - }, - "title": { - "description": "坐标轴标题配置", - "properties": { - "bold": { - "description": "是否加粗", - "type": "boolean" - }, - "color": { - "description": "字体颜色", - "type": "string" - }, - "fontSize": { - "description": "字体大小", - "type": "number" - }, - "italic": { - "description": "是否斜体", - "type": "boolean" - }, - "strikethrough": { - "description": "是否删除线", - "type": "boolean" - }, - "text": { - "description": "标题文本", - "type": "string" - }, - "underline": { - "description": "是否下划线", - "type": "boolean" - } - }, - "required": [ - "text" - ], - "type": "object" - }, - "type": { - "description": "坐标轴类型", - "enum": [ - "x", - "y", - "angle", - "radius" - ], - "type": "string" - }, - "valueType": { - "description": "是否将横轴数字视为文本，linear 表示将数字视为数值, ordinal 表示将数字视为文本", - "enum": [ - "ordinal", - "linear" - ], - "type": "string" - } - }, - "required": [ - "type" - ], - "type": "object" - }, - "type": "array" - }, "plot": { + "type": "object", "description": "绘图配置", "properties": { - "areas": { - "description": "全系列面积填充配置，面积图、雷达图、组合图生效。", - "properties": { - "color": { - "description": "区域填充颜色", - "type": "string" - } - }, - "type": "object" - }, - "bars": { - "description": "全系列柱状图、条形图、组合图生效。", - "properties": { - "backgroundColor": { - "description": "背景颜色", - "type": "string" - }, - "bar": { - "description": "单个柱子配置数组", - "items": { - "properties": { - "borderColor": { - "description": "边框颜色", - "type": "string" - }, - "borderStyle": { - "description": "边框样式", - "type": "string" - }, - "borderWidth": { - "description": "边框宽度", - "type": "number" - }, - "color": { - "description": "颜色", - "type": "string" - }, - "index": { - "description": "柱子索引", - "type": "number" - } - }, - "required": [ - "index" - ], - "type": "object" - }, - "type": "array" - }, - "borderColor": { - "description": "边框颜色", - "type": "string" - }, - "borderStyle": { - "description": "边框样式", - "enum": [ - "solid", - "dashed", - "dotted" - ], - "type": "string" - }, - "borderWidth": { - "description": "边框宽度", - "type": "number" - }, - "color": { - "description": "柱子颜色", - "type": "string" - }, - "gap": { - "description": "柱子间距比例，0-1之间", - "type": "number" - }, - "width": { - "description": "柱子宽度", - "type": "number" - } - }, - "type": "object" + "type": { + "type": "string", + "description": "图表类型", + "enum": [ + "bar", + "column", + "line", + "area", + "combo", + "pie", + "radar", + "scatter" + ] }, "comboType": { + "type": "string", "description": "组合图表默认类型", "enum": [ "column", "line", "area" - ], - "type": "string" + ] + }, + "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": { - "area": { - "description": "是否填充区域", - "type": "boolean" - }, "shape": { + "type": "string", "description": "雷达图形状", "enum": [ "polygon", "circle" - ], - "type": "string" - } - }, - "type": "object" - }, - "smooth": { - "description": "是否平滑曲线", - "type": "boolean" - }, - "stack": { - "description": "堆叠配置", - "properties": { - "percentage": { - "description": "是否百分比堆叠", - "type": "boolean" + ] + }, + "area": { + "type": "boolean", + "description": "是否填充区域" } - }, - "type": "object" - }, - "step": { - "description": "是否阶梯图", - "type": "boolean" + } } - }, - "type": "object" + } }, - "labels": { - "description": "数据标签配置", + "points": { + "type": "object", + "description": "全系列数据点配置，折线图、面积图、雷达图、散点图、组合图生效。", "properties": { - "bold": { - "description": "是否加粗", - "type": "boolean" - }, - "category": { - "description": "是否显示类别名", - "type": "boolean" - }, "color": { - "description": "字体颜色", - "type": "string" - }, - "fontSize": { - "description": "字体大小", - "type": "number" - }, - "italic": { - "description": "是否斜体", - "type": "boolean" - }, - "percentage": { - "description": "是否显示百分比", - "type": "boolean" + "type": "string", + "description": "数据点颜色" }, - "position": { - "description": "标签位置", + "shape": { + "type": "string", + "description": "数据点形状", "enum": [ - "auto", - "top", - "bottom", - "left", - "right", - "center", - "inside", - "outside" - ], - "type": "string" - }, - "series": { - "description": "是否显示系列名", - "type": "boolean" - }, - "strikethrough": { - "description": "是否删除线", - "type": "boolean" + "circle", + "triangle", + "rect", + "diamond", + "square" + ] }, - "underline": { - "description": "是否下划线", - "type": "boolean" + "size": { + "type": "number", + "description": "数据点大小" }, - "value": { - "description": "是否显示值", - "type": "boolean" + "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" + ] + } } - }, - "type": "object" + } }, "lines": { + "type": "object", "description": "全系列线条配置，折线图、面积图、雷达图、组合图生效。", "properties": { "color": { - "description": "线条颜色", - "type": "string" + "type": "string", + "description": "线条颜色" }, - "invalidType": { - "description": "无效值处理方式", - "enum": [ - "break", - "zero", - "link" - ], - "type": "string" + "width": { + "type": "number", + "description": "线条宽度" }, "style": { + "type": "string", "description": "线条样式", "enum": [ "solid", "dashed", "dotted" - ], - "type": "string" + ] }, - "width": { - "description": "线条宽度", - "type": "number" - } - }, - "type": "object" - }, - "points": { - "description": "全系列数据点配置，折线图、面积图、雷达图、散点图、组合图生效。", + "invalidType": { + "type": "string", + "description": "无效值处理方式", + "enum": [ + "break", + "zero", + "link" + ] + } + } + }, + "areas": { + "type": "object", + "description": "全系列面积填充配置，面积图、雷达图、组合图生效。", "properties": { "color": { - "description": "数据点颜色", - "type": "string" + "type": "string", + "description": "区域填充颜色" + } + } + }, + "bars": { + "type": "object", + "description": "全系列柱状图、条形图、组合图生效。", + "properties": { + "color": { + "type": "string", + "description": "柱子颜色" }, - "point": { - "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": { - "description": "颜色", - "type": "string" + "type": "string", + "description": "颜色" }, - "index": { - "description": "数据点索引", - "type": "number" + "borderColor": { + "type": "string", + "description": "边框颜色" }, - "shape": { - "description": "形状", - "type": "string" + "borderWidth": { + "type": "number", + "description": "边框宽度" }, - "size": { - "description": "大小", - "type": "number" + "borderStyle": { + "type": "string", + "description": "边框样式" } }, "required": [ "index" - ], - "type": "object" - }, - "type": "array" - }, - "shape": { - "description": "数据点形状", + ] + } + } + } + }, + "labels": { + "type": "object", + "description": "数据标签配置", + "properties": { + "position": { + "type": "string", + "description": "标签位置", "enum": [ - "circle", - "triangle", - "rect", - "diamond", - "square" - ], - "type": "string" + "auto", + "top", + "bottom", + "left", + "right", + "center", + "inside", + "outside" + ] }, - "size": { - "description": "数据点大小", - "type": "number" + "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": "字体颜色" } - }, - "type": "object" + } }, "series": { + "type": "array", "description": "单个系列配置数组", "items": { + "type": "object", "description": "系列配置", "properties": { - "area": { - "description": "区域填充配置，配置项同 plotArea.areas", - "type": "object" - }, - "bars": { - "description": "柱状图配置，配置项同 plotArea.bars", - "type": "object" + "index": { + "type": "number", + "description": "数据列索引，与 dim2.series[].index 值一致，从 1 开始（1 通常对应首列标签维度，2+ 对应后续数据维度列）" }, "comboType": { + "type": "string", "description": "组合图下该系列的图表类型，仅在 type 为 combo 时生效", "enum": [ "column", "line", "area" - ], - "type": "string" + ] }, - "index": { - "description": "数据列索引，与 dim2.series[].index 值一致，从 1 开始（1 通常对应首列标签维度，2+ 对应后续数据维度列）", - "type": "number" + "yAxisPosition": { + "type": "string", + "description": "Y轴位置", + "enum": [ + "left", + "right" + ] }, - "labels": { - "description": "数据标签配置", - "type": "object" + "points": { + "type": "object", + "description": "数据点配置，配置项同 plotArea.points" }, "line": { - "description": "线条配置，配置项同 plotArea.lines", - "type": "object" + "type": "object", + "description": "线条配置，配置项同 plotArea.lines" }, - "points": { - "description": "数据点配置，配置项同 plotArea.points", - "type": "object" + "area": { + "type": "object", + "description": "区域填充配置，配置项同 plotArea.areas" + }, + "bars": { + "type": "object", + "description": "柱状图配置，配置项同 plotArea.bars" + }, + "labels": { + "type": "object", + "description": "数据标签配置" }, "sectors": { + "type": "object", "description": "扇区配置（饼图）", "properties": { "borderColor": { - "description": "边框颜色", - "type": "string" + "type": "string", + "description": "边框颜色" }, "innerRadius": { - "description": "内半径比例，0-1之间", - "type": "number" + "type": "number", + "description": "内半径比例，0-1之间" }, "offsetRadius": { - "description": "偏移半径比例", - "type": "number" + "type": "number", + "description": "偏移半径比例" + }, + "startAngle": { + "type": "number", + "description": "起始角度，0-359" }, "sector": { + "type": "array", "description": "单个扇区配置数组", "items": { + "type": "object", "properties": { - "borderColor": { - "description": "边框颜色", - "type": "string" - }, - "color": { - "description": "颜色", - "type": "string" - }, "index": { - "description": "扇区索引", - "type": "number" + "type": "number", + "description": "扇区索引" + }, + "borderColor": { + "type": "string", + "description": "边框颜色" }, "offsetRadius": { - "description": "偏移半径", - "type": "number" + "type": "number", + "description": "偏移半径" + }, + "color": { + "type": "string", + "description": "颜色" } }, "required": [ "index" - ], - "type": "object" - }, - "type": "array" - }, - "startAngle": { - "description": "起始角度，0-359", - "type": "number" + ] + } } - }, - "type": "object" - }, - "yAxisPosition": { - "description": "Y轴位置", - "enum": [ - "left", - "right" - ], - "type": "string" + } } }, "required": [ "index" - ], - "type": "object" - }, - "type": "array" - }, - "type": { - "description": "图表类型", - "enum": [ - "bar", - "column", - "line", - "area", - "combo", - "pie", - "radar", - "scatter" - ], - "type": "string" - }, - "yAxisPosition": { - "description": "Y轴位置", - "enum": [ - "left", - "right" - ], - "type": "string" + ] + } } }, "required": [ "type" - ], - "type": "object" - } - }, - "type": "object" - }, - "style": { - "description": "图表样式配置", - "properties": { - "background": { - "description": "背景配置", - "properties": { - "color": { - "description": "背景颜色，格式为 #RRGGBB", - "type": "string" - } - }, - "type": "object" - }, - "border": { - "description": "边框配置", - "properties": { - "color": { - "description": "边框颜色，格式为 #RRGGBB", - "type": "string" - }, - "radius": { - "description": "边框圆角", - "type": "number" - }, - "style": { - "description": "边框样式", - "enum": [ - "solid", - "dashed", - "dotted" - ], - "type": "string" - }, - "width": { - "description": "边框宽度", - "type": "number" - } - }, - "type": "object" - }, - "colorGradient": { - "description": "是否启用颜色渐变", - "type": "boolean" + ] }, - "colorTheme": { - "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": [ - { - "items": { + "axes": { + "type": "array", + "description": "坐标轴配置数组", + "items": { + "type": "object", + "description": "坐标轴配置", + "properties": { + "type": { + "type": "string", + "description": "坐标轴类型", "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" - ], - "type": "string" + "x", + "y", + "angle", + "radius" + ] }, - "maxItems": 1, - "minItems": 1 - }, - { - "items": { - "description": "颜色字符串，十六进制格式：#RRGGBB", - "type": "string" + "position": { + "type": "string", + "description": "坐标轴位置", + "enum": [ + "left", + "right", + "bottom" + ] }, - "minItems": 2 - } - ], - "type": "array" - }, - "font": { - "description": "字体配置", - "properties": { - "color": { - "description": "字体颜色，格式为 #RRGGBB", - "type": "string" + "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 表示隐藏网格线" + } + ] + } }, - "size": { - "description": "字体大小", - "type": "number" - } - }, - "type": "object" + "required": [ + "type" + ] + } } - }, - "type": "object" + } }, - "subTitle": { - "description": "图表副标题配置", + "data": { + "type": "object", + "description": "图表数据配置", "properties": { - "bold": { - "description": "是否加粗", - "type": "boolean" - }, - "color": { - "description": "字体颜色，格式为 #RRGGBB", - "type": "string" - }, - "fontSize": { - "description": "字体大小", - "type": "number" - }, - "italic": { - "description": "是否斜体", - "type": "boolean" - }, - "strikethrough": { - "description": "是否删除线", - "type": "boolean" + "isStaticData": { + "type": "boolean", + "description": "是否为静态数据" }, - "text": { - "description": "副标题文本", - "type": "string" + "includeHiddenOrFilter": { + "type": "boolean", + "description": "是否包含隐藏或过滤的数据" }, - "textAlign": { - "description": "副标题对齐方式", + "direction": { + "type": "string", + "description": "数据方向，可选值：row（行方向）或column（列方向），常用值为column", "enum": [ - "left", - "center", - "right" - ], - "type": "string" - }, - "underline": { - "description": "是否下划线", - "type": "boolean" - } - }, - "required": [ - "text" - ], - "type": "object" - }, - "title": { - "description": "图表标题配置", - "properties": { - "bold": { - "description": "是否加粗", - "type": "boolean" - }, - "color": { - "description": "字体颜色，格式为 #RRGGBB", - "type": "string" - }, - "fontSize": { - "description": "字体大小", - "type": "number" - }, - "italic": { - "description": "是否斜体", - "type": "boolean" + "row", + "column" + ] }, - "strikethrough": { - "description": "是否删除线", - "type": "boolean" + "headerMode": { + "type": "string", + "description": "表头模式。inline 表示 refs 首行/首列就是表头；detached 表示 refs 仅覆盖实际数据范围，维度名和系列名需通过 nameRef 显式指定。", + "enum": [ + "inline", + "detached" + ] }, - "text": { - "description": "标题文本", - "type": "string" + "refs": { + "type": "array", + "description": "数据源引用范围数组", + "items": { + "type": "object", + "properties": { + "value": { + "type": "string", + "description": "图表数据源范围，格式为 'SheetName!A1:D100' 的连续区域" + } + }, + "required": [ + "value" + ] + } }, - "textAlign": { - "description": "标题对齐方式", - "enum": [ - "left", - "center", - "right" - ], - "type": "string" + "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 首行/首列时，可通过此字段把维度名显式指向目标表头单元格，图表会以该单元格当前值作为类别维度名展示。" + } + } + }, + "field": { + "type": "object", + "description": "字段配置（静态数据时传此参数）", + "properties": { + "valueType": { + "type": "string", + "description": "值类型", + "enum": [ + "number", + "string" + ] + }, + "name": { + "type": "string", + "description": "字段名称" + }, + "text": { + "type": "string", + "description": "字段文本数据" + } + }, + "required": [ + "text" + ] + } + } }, - "underline": { - "description": "是否下划线", - "type": "boolean" + "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 时生效", + "enum": [ + "sum", + "average", + "count", + "min", + "max", + "median" + ] + }, + "nameRef": { + "type": "string", + "description": "可选。系列名称的单元格引用（A1 表示法，如 'Sheet1!C1'）。当系列名称不直接来自 refs 首行/首列时，可通过此字段把系列名显式指向目标表头单元格，图表会以该单元格当前值作为系列名（图例/tooltip）展示。" + } + } + } + }, + "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": [ - "text" - ], - "type": "object" + } } - }, - "type": "object" + } } }, - "type": "object" + "additionalProperties": {} } }, "+cond-format-create": { "properties": { - "additionalProperties": false, "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\"=加粗+斜体。" + } + }, + "additionalProperties": false + }, "attrs": { + "type": "array", "description": "规则参数列表。不同 rule_type 下取值结构不同。当 rule_type 为 dataBar 时，attrs 必须包含两个对象，分别定义正值和负值的数据条颜色。", "items": { "oneOf": [ { - "additionalProperties": false, + "type": "object", "description": "数值比较类规则参数。", "properties": { "compare_type": { - "description": "比较运算符。", + "type": "string", "enum": [ "equal", "notEqual", @@ -2824,25 +2885,29 @@ "between", "notBetween" ], - "type": "string" + "description": "比较运算符。" }, "value": { - "description": "用于比较的值，例如 \"100\"、\"hello\"。between/notBetween 时用逗号分隔两个值。", - "type": "string" + "type": "string", + "description": "用于比较的值，例如 \"100\"、\"hello\"。between/notBetween 时用逗号分隔两个值。" } }, "required": [ "compare_type", "value" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "文本包含类规则参数。", "properties": { + "text": { + "type": "string", + "description": "用于匹配的文本内容。" + }, "compare_type": { - "description": "文本匹配方式。", + "type": "string", "enum": [ "beginsWith", "endsWith", @@ -2850,34 +2915,30 @@ "notContains", "is" ], - "type": "string" - }, - "text": { - "description": "用于匹配的文本内容。", - "type": "string" + "description": "文本匹配方式。" } }, "required": [ "compare_type", "text" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "时间段类规则参数。", "properties": { "operator": { - "description": "与指定时间段的比较关系。", + "type": "string", "enum": [ "before", "is", "after" ], - "type": "string" + "description": "与指定时间段的比较关系。" }, "time_period": { - "description": "时间段类型。", + "type": "string", "enum": [ "today", "yesterday", @@ -2890,37 +2951,37 @@ "lastWeek", "nextWeek" ], - "type": "string" + "description": "时间段类型。" } }, "required": [ "operator", "time_period" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "数据条规则参数。", "properties": { - "color": { - "description": "主颜色，例如 \"#63BE7B\"。", - "type": "string" - }, "gradient": { - "description": "是否使用渐变色数据条。", - "type": "boolean" - }, - "hide_value": { - "description": "是否隐藏单元格中的原始值，仅显示数据条。", - "type": "boolean" + "type": "boolean", + "description": "是否使用渐变色数据条。" }, "value": { - "description": "阈值或比例值，含义由 value_type 决定。", - "type": "number" + "type": "number", + "description": "阈值或比例值，含义由 value_type 决定。" + }, + "color": { + "type": "string", + "description": "主颜色，例如 \"#63BE7B\"。" + }, + "hide_value": { + "type": "boolean", + "description": "是否隐藏单元格中的原始值，仅显示数据条。" }, "value_type": { - "description": "阈值类型。", + "type": "string", "enum": [ "minValue", "maxValue", @@ -2930,29 +2991,21 @@ "formula", "auto" ], - "type": "string" + "description": "阈值类型。" } }, "required": [ "color", "value_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "色阶规则中的单个分段。ColorScaleAttrs 由 2 或 3 个该对象组成，分别表示最小值/中间值/最大值。", "properties": { - "color": { - "description": "该分段对应的颜色。", - "type": "string" - }, - "value": { - "description": "阈值数值，例如百分位或具体数值。", - "type": "number" - }, "value_type": { - "description": "阈值类型。", + "type": "string", "enum": [ "minValue", "maxValue", @@ -2962,89 +3015,93 @@ "formula", "auto" ], - "type": "string" + "description": "阈值类型。" + }, + "value": { + "type": "number", + "description": "阈值数值，例如百分位或具体数值。" + }, + "color": { + "type": "string", + "description": "该分段对应的颜色。" } }, "required": [ "value_type", "color" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "前 N/后 N 规则参数。", "properties": { "is_bottom": { - "description": "是否选取最后 N 个。true 表示最后 N 个，false 表示前 N 个。", - "type": "boolean" - }, - "value": { - "description": "N 或百分比数值。", - "type": "number" + "type": "boolean", + "description": "是否选取最后 N 个。true 表示最后 N 个，false 表示前 N 个。" }, "value_type": { - "description": "排名方式：percent 表示百分比，sort 表示按条目数。", + "type": "string", "enum": [ "percent", "sort" ], - "type": "string" + "description": "排名方式：percent 表示百分比，sort 表示按条目数。" + }, + "value": { + "type": "number", + "description": "N 或百分比数值。" } }, "required": [ "is_bottom", "value_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "平均值规则参数。", "properties": { "operator": { - "description": "与平均值的比较关系。", + "type": "string", "enum": [ "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual" ], - "type": "string" + "description": "与平均值的比较关系。" } }, "required": [ "operator" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "自定义公式规则参数。", "properties": { "formula": { - "description": "条件公式列表，例如 [\"=A1>0\"]。", + "type": "array", "items": { "type": "string" }, - "type": "array" + "description": "条件公式列表，例如 [\"=A1>0\"]。" } }, "required": [ "formula" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "图标集规则参数。", "properties": { - "hide_value": { - "description": "是否隐藏单元格原始值，仅显示图标。", - "type": "boolean" - }, "icon_type": { - "description": "图标集类型。其中 3Circles/4Circles/5Circles 为不同颜色的实心圆（如红、黄、绿），用于表示状态等级；5CirclesRatio 为不同填充比例的圆（从空心◯到半圆◑到满圆●），用于表示完成度、进度、比例。当涉及半圆、满圆、空心圆、填充比例、进度等场景时，应选择 5CirclesRatio。", + "type": "string", "enum": [ "3Arrows", "3ArrowsGray", @@ -3066,28 +3123,14 @@ "3Mood", "5CirclesRatio" ], - "type": "string" - }, - "operator": { - "description": "与阈值的比较关系。", - "enum": [ - "greaterThan", - "greaterThanOrEqual", - "lessThan", - "lessThanOrEqual" - ], - "type": "string" - }, - "reverse_icons": { - "description": "是否反转图标顺序。", - "type": "boolean" + "description": "图标集类型。其中 3Circles/4Circles/5Circles 为不同颜色的实心圆（如红、黄、绿），用于表示状态等级；5CirclesRatio 为不同填充比例的圆（从空心◯到半圆◑到满圆●），用于表示完成度、进度、比例。当涉及半圆、满圆、空心圆、填充比例、进度等场景时，应选择 5CirclesRatio。" }, - "value": { - "description": "用于比较的数值，含义由 value_type 决定。", - "type": "number" + "hide_value": { + "type": "boolean", + "description": "是否隐藏单元格原始值，仅显示图标。" }, "value_type": { - "description": "阈值类型。", + "type": "string", "enum": [ "minValue", "maxValue", @@ -3097,7 +3140,25 @@ "formula", "auto" ], - "type": "string" + "description": "阈值类型。" + }, + "operator": { + "type": "string", + "enum": [ + "greaterThan", + "greaterThanOrEqual", + "lessThan", + "lessThanOrEqual" + ], + "description": "与阈值的比较关系。" + }, + "value": { + "type": "number", + "description": "用于比较的数值，含义由 value_type 决定。" + }, + "reverse_icons": { + "type": "boolean", + "description": "是否反转图标顺序。" } }, "required": [ @@ -3105,25 +3166,31 @@ "value_type", "operator" ], - "type": "object" + "additionalProperties": false } ] - }, - "type": "array" + } }, "has_ref": { - "description": "可选。是否存在引用，用于标记规则是否依赖其他对象。", - "type": "boolean" - }, - "ranges": { - "description": "应用条件格式的 A1 范围列表。每个元素支持：矩形范围 \"A1:A10\"、整行 \"3:6\"、整列 \"C:C\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。例如 [\"A1:A10\",\"C:C\"]。", - "items": { - "type": "string" - }, - "type": "array" - }, + "type": "boolean", + "description": "可选。是否存在引用，用于标记规则是否依赖其他对象。" + } + }, + "required": [ + "rule_type", + "ranges", + "style" + ], + "additionalProperties": false + } + }, + "+cond-format-update": { + "properties": { + "description": "创建/更新的条件格式属性。", + "type": "object", + "properties": { "rule_type": { - "description": "条件格式规则类型。", + "type": "string", "enum": [ "duplicateValues", "uniqueValues", @@ -3139,66 +3206,60 @@ "expression", "iconSet" ], - "type": "string" + "description": "条件格式规则类型。" + }, + "ranges": { + "type": "array", + "description": "应用条件格式的 A1 范围列表。每个元素支持：矩形范围 \"A1:A10\"、整行 \"3:6\"、整列 \"C:C\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。例如 [\"A1:A10\",\"C:C\"]。", + "items": { + "type": "string" + } }, "style": { - "additionalProperties": false, - "description": "命中规则时应用的单元格样式。", - "properties": { - "back_color": { - "description": "背景色，CSS 十六进制表示，例如 \"#FF0000\"。", - "type": "string" - }, - "font": { - "description": "字体样式：\"bold\"=加粗，\"italic\"=斜体，\"bold italic\"=加粗+斜体。", - "enum": [ - "bold", - "italic", - "bold italic" - ], - "type": "string" + "type": "object", + "description": "命中规则时应用的单元格样式。", + "properties": { + "back_color": { + "type": "string", + "description": "背景色，CSS 十六进制表示，例如 \"#FF0000\"。" }, "fore_color": { - "description": "前景色/字体颜色。", - "type": "string" + "type": "string", + "description": "前景色/字体颜色。" }, "text_decoration": { - "description": "文字装饰：none=无，underline=下划线，strikethrough=删除线，underline_strikethrough=下划线+删除线。", + "type": "string", "enum": [ "none", "underline", "strikethrough", "underline_strikethrough" ], - "type": "string" + "description": "文字装饰：none=无，underline=下划线，strikethrough=删除线，underline_strikethrough=下划线+删除线。" + }, + "font": { + "type": "string", + "enum": [ + "bold", + "italic", + "bold italic" + ], + "description": "字体样式：\"bold\"=加粗，\"italic\"=斜体，\"bold italic\"=加粗+斜体。" } }, - "type": "object" - } - }, - "required": [ - "rule_type", - "ranges", - "style" - ], - "type": "object" - } - }, - "+cond-format-update": { - "properties": { - "additionalProperties": false, - "description": "创建/更新的条件格式属性。", - "properties": { + "additionalProperties": false + }, "attrs": { + "type": "array", "description": "规则参数列表。不同 rule_type 下取值结构不同。当 rule_type 为 dataBar 时，attrs 必须包含两个对象，分别定义正值和负值的数据条颜色。", "items": { "oneOf": [ { - "additionalProperties": false, + "type": "object", "description": "数值比较类规则参数。", "properties": { "compare_type": { - "description": "比较运算符。", + "type": "string", "enum": [ "equal", "notEqual", @@ -3209,25 +3270,29 @@ "between", "notBetween" ], - "type": "string" + "description": "比较运算符。" }, "value": { - "description": "用于比较的值，例如 \"100\"、\"hello\"。between/notBetween 时用逗号分隔两个值。", - "type": "string" + "type": "string", + "description": "用于比较的值，例如 \"100\"、\"hello\"。between/notBetween 时用逗号分隔两个值。" } }, "required": [ "compare_type", "value" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "文本包含类规则参数。", "properties": { + "text": { + "type": "string", + "description": "用于匹配的文本内容。" + }, "compare_type": { - "description": "文本匹配方式。", + "type": "string", "enum": [ "beginsWith", "endsWith", @@ -3235,34 +3300,30 @@ "notContains", "is" ], - "type": "string" - }, - "text": { - "description": "用于匹配的文本内容。", - "type": "string" + "description": "文本匹配方式。" } }, "required": [ "compare_type", "text" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "时间段类规则参数。", "properties": { "operator": { - "description": "与指定时间段的比较关系。", + "type": "string", "enum": [ "before", "is", "after" ], - "type": "string" + "description": "与指定时间段的比较关系。" }, "time_period": { - "description": "时间段类型。", + "type": "string", "enum": [ "today", "yesterday", @@ -3275,37 +3336,37 @@ "lastWeek", "nextWeek" ], - "type": "string" + "description": "时间段类型。" } }, "required": [ "operator", "time_period" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "数据条规则参数。", "properties": { - "color": { - "description": "主颜色，例如 \"#63BE7B\"。", - "type": "string" - }, "gradient": { - "description": "是否使用渐变色数据条。", - "type": "boolean" - }, - "hide_value": { - "description": "是否隐藏单元格中的原始值，仅显示数据条。", - "type": "boolean" + "type": "boolean", + "description": "是否使用渐变色数据条。" }, "value": { - "description": "阈值或比例值，含义由 value_type 决定。", - "type": "number" + "type": "number", + "description": "阈值或比例值，含义由 value_type 决定。" + }, + "color": { + "type": "string", + "description": "主颜色，例如 \"#63BE7B\"。" + }, + "hide_value": { + "type": "boolean", + "description": "是否隐藏单元格中的原始值，仅显示数据条。" }, "value_type": { - "description": "阈值类型。", + "type": "string", "enum": [ "minValue", "maxValue", @@ -3315,29 +3376,21 @@ "formula", "auto" ], - "type": "string" + "description": "阈值类型。" } }, "required": [ "color", "value_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "色阶规则中的单个分段。ColorScaleAttrs 由 2 或 3 个该对象组成，分别表示最小值/中间值/最大值。", "properties": { - "color": { - "description": "该分段对应的颜色。", - "type": "string" - }, - "value": { - "description": "阈值数值，例如百分位或具体数值。", - "type": "number" - }, "value_type": { - "description": "阈值类型。", + "type": "string", "enum": [ "minValue", "maxValue", @@ -3347,89 +3400,93 @@ "formula", "auto" ], - "type": "string" + "description": "阈值类型。" + }, + "value": { + "type": "number", + "description": "阈值数值，例如百分位或具体数值。" + }, + "color": { + "type": "string", + "description": "该分段对应的颜色。" } }, "required": [ "value_type", "color" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "前 N/后 N 规则参数。", "properties": { "is_bottom": { - "description": "是否选取最后 N 个。true 表示最后 N 个，false 表示前 N 个。", - "type": "boolean" - }, - "value": { - "description": "N 或百分比数值。", - "type": "number" + "type": "boolean", + "description": "是否选取最后 N 个。true 表示最后 N 个，false 表示前 N 个。" }, "value_type": { - "description": "排名方式：percent 表示百分比，sort 表示按条目数。", + "type": "string", "enum": [ "percent", "sort" ], - "type": "string" + "description": "排名方式：percent 表示百分比，sort 表示按条目数。" + }, + "value": { + "type": "number", + "description": "N 或百分比数值。" } }, "required": [ "is_bottom", "value_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "平均值规则参数。", "properties": { "operator": { - "description": "与平均值的比较关系。", + "type": "string", "enum": [ "greaterThan", "greaterThanOrEqual", "lessThan", "lessThanOrEqual" ], - "type": "string" + "description": "与平均值的比较关系。" } }, "required": [ "operator" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "自定义公式规则参数。", "properties": { "formula": { - "description": "条件公式列表，例如 [\"=A1>0\"]。", + "type": "array", "items": { "type": "string" }, - "type": "array" + "description": "条件公式列表，例如 [\"=A1>0\"]。" } }, "required": [ "formula" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "图标集规则参数。", "properties": { - "hide_value": { - "description": "是否隐藏单元格原始值，仅显示图标。", - "type": "boolean" - }, "icon_type": { - "description": "图标集类型。其中 3Circles/4Circles/5Circles 为不同颜色的实心圆（如红、黄、绿），用于表示状态等级；5CirclesRatio 为不同填充比例的圆（从空心◯到半圆◑到满圆●），用于表示完成度、进度、比例。当涉及半圆、满圆、空心圆、填充比例、进度等场景时，应选择 5CirclesRatio。", + "type": "string", "enum": [ "3Arrows", "3ArrowsGray", @@ -3451,28 +3508,14 @@ "3Mood", "5CirclesRatio" ], - "type": "string" - }, - "operator": { - "description": "与阈值的比较关系。", - "enum": [ - "greaterThan", - "greaterThanOrEqual", - "lessThan", - "lessThanOrEqual" - ], - "type": "string" - }, - "reverse_icons": { - "description": "是否反转图标顺序。", - "type": "boolean" + "description": "图标集类型。其中 3Circles/4Circles/5Circles 为不同颜色的实心圆（如红、黄、绿），用于表示状态等级；5CirclesRatio 为不同填充比例的圆（从空心◯到半圆◑到满圆●），用于表示完成度、进度、比例。当涉及半圆、满圆、空心圆、填充比例、进度等场景时，应选择 5CirclesRatio。" }, - "value": { - "description": "用于比较的数值，含义由 value_type 决定。", - "type": "number" + "hide_value": { + "type": "boolean", + "description": "是否隐藏单元格原始值，仅显示图标。" }, "value_type": { - "description": "阈值类型。", + "type": "string", "enum": [ "minValue", "maxValue", @@ -3482,7 +3525,25 @@ "formula", "auto" ], - "type": "string" + "description": "阈值类型。" + }, + "operator": { + "type": "string", + "enum": [ + "greaterThan", + "greaterThanOrEqual", + "lessThan", + "lessThanOrEqual" + ], + "description": "与阈值的比较关系。" + }, + "value": { + "type": "number", + "description": "用于比较的数值，含义由 value_type 决定。" + }, + "reverse_icons": { + "type": "boolean", + "description": "是否反转图标顺序。" } }, "required": [ @@ -3490,75 +3551,14 @@ "value_type", "operator" ], - "type": "object" + "additionalProperties": false } ] - }, - "type": "array" + } }, "has_ref": { - "description": "可选。是否存在引用，用于标记规则是否依赖其他对象。", - "type": "boolean" - }, - "ranges": { - "description": "应用条件格式的 A1 范围列表。每个元素支持：矩形范围 \"A1:A10\"、整行 \"3:6\"、整列 \"C:C\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。例如 [\"A1:A10\",\"C:C\"]。", - "items": { - "type": "string" - }, - "type": "array" - }, - "rule_type": { - "description": "条件格式规则类型。", - "enum": [ - "duplicateValues", - "uniqueValues", - "cellIs", - "containsText", - "timePeriod", - "containsBlanks", - "notContainsBlanks", - "dataBar", - "colorScale", - "rank", - "aboveAverage", - "expression", - "iconSet" - ], - "type": "string" - }, - "style": { - "additionalProperties": false, - "description": "命中规则时应用的单元格样式。", - "properties": { - "back_color": { - "description": "背景色，CSS 十六进制表示，例如 \"#FF0000\"。", - "type": "string" - }, - "font": { - "description": "字体样式：\"bold\"=加粗，\"italic\"=斜体，\"bold italic\"=加粗+斜体。", - "enum": [ - "bold", - "italic", - "bold italic" - ], - "type": "string" - }, - "fore_color": { - "description": "前景色/字体颜色。", - "type": "string" - }, - "text_decoration": { - "description": "文字装饰：none=无，underline=下划线，strikethrough=删除线，underline_strikethrough=下划线+删除线。", - "enum": [ - "none", - "underline", - "strikethrough", - "underline_strikethrough" - ], - "type": "string" - } - }, - "type": "object" + "type": "boolean", + "description": "可选。是否存在引用，用于标记规则是否依赖其他对象。" } }, "required": [ @@ -3566,63 +3566,65 @@ "ranges", "style" ], - "type": "object" + "additionalProperties": false } }, "+dropdown-set": { "options": { "description": "列表选项（type='list' 时必填）", + "type": "array", "items": { "type": "string" - }, - "type": "array" + } } }, "+dropdown-update": { "options": { "description": "列表选项（type='list' 时必填）", + "type": "array", "items": { "type": "string" - }, - "type": "array" + } } }, "+filter-create": { "properties": { - "additionalProperties": false, "description": "创建/更新的筛选器属性。", + "type": "object", "properties": { - "filtered_columns": { - "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", - "items": { - "type": "string" - }, - "type": "array" - }, "range": { - "description": "筛选对象作用的单元格范围（A1 表示法）。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。", - "type": "string" + "type": "string", + "description": "筛选对象作用的单元格范围（A1 表示法）。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。" }, "rules": { + "type": "array", "description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。update 时传空数组 [] 表示清空所有现有列的规则。", "items": { - "additionalProperties": false, + "type": "object", "description": "单列筛选规则。", "properties": { "column_index": { - "description": "作用的列索引，例如 \"A\"、\"B\"。", - "type": "string" + "type": "string", + "description": "作用的列索引，例如 \"A\"、\"B\"。" }, "conditions": { + "type": "array", "description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。", "items": { "oneOf": [ { - "additionalProperties": false, + "type": "object", "description": "文本条件筛选。", "properties": { + "type": { + "type": "string", + "enum": [ + "text" + ], + "description": "条件类型固定为 \"text\"。" + }, "compare_type": { - "description": "文本比较方式：beginsWith=以指定文本开头，doesNotBeginWith=不以指定文本开头，endsWith=以指定文本结尾，doesNotEndWith=不以指定文本结尾，contains=包含，doesNotContain=不包含，equals=等于，notEquals=不等于。", + "type": "string", "enum": [ "beginsWith", "doesNotBeginWith", @@ -3633,35 +3635,35 @@ "equals", "notEquals" ], - "type": "string" - }, - "type": { - "description": "条件类型固定为 \"text\"。", - "enum": [ - "text" - ], - "type": "string" + "description": "文本比较方式：beginsWith=以指定文本开头，doesNotBeginWith=不以指定文本开头，endsWith=以指定文本结尾，doesNotEndWith=不以指定文本结尾，contains=包含，doesNotContain=不包含，equals=等于，notEquals=不等于。" }, "values": { + "type": "array", "description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。", "items": { "type": "string" - }, - "type": "array" + } } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "数值条件筛选。", "properties": { + "type": { + "type": "string", + "enum": [ + "number" + ], + "description": "条件类型固定为 \"number\"。" + }, "compare_type": { - "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。", + "type": "string", "enum": [ "equal", "notEqual", @@ -3672,16 +3674,10 @@ "between", "notBetween" ], - "type": "string" - }, - "type": { - "description": "条件类型固定为 \"number\"。", - "enum": [ - "number" - ], - "type": "string" + "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。" }, "values": { + "type": "array", "description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。", "items": { "oneOf": [ @@ -3692,73 +3688,82 @@ "type": "string" } ] - }, - "type": "array" + } } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "颜色条件筛选。", "properties": { - "compare_type": { - "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。", + "type": { + "type": "string", "enum": [ - "backgroundColor", - "foregroundColor" + "color" ], - "type": "string" + "description": "条件类型固定为 \"color\"。" }, - "type": { - "description": "条件类型固定为 \"color\"。", + "compare_type": { + "type": "string", "enum": [ - "color" + "backgroundColor", + "foregroundColor" ], - "type": "string" + "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。" }, "value": { - "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。", - "type": "string" + "type": "string", + "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。" } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "多值条件筛选。", "properties": { + "type": { + "type": "string", + "enum": [ + "multiValue" + ], + "description": "条件类型固定为 \"multiValue\"。" + }, "compare_type": { - "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。", + "type": "string", "enum": [ "equal", "notEqual" ], - "type": "string" + "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。" + }, + "values": { + "type": "array", + "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", + "items": { + "type": "string" + } }, "date_groups": { + "type": "array", "description": "可选。年月日等聚合筛选信息。", "items": { - "additionalProperties": false, + "type": "object", "properties": { - "date_time_grouping": { - "enum": [ - "year", - "month", - "day", - "hour", - "minute", - "second" - ], - "type": "string" + "year": { + "type": "number" + }, + "month": { + "type": "number" }, "day": { "type": "number" @@ -3769,105 +3774,102 @@ "minute": { "type": "number" }, - "month": { - "type": "number" - }, "second": { "type": "number" }, - "year": { - "type": "number" - } - }, - "type": "object" - }, - "type": "array" - }, - "type": { - "description": "条件类型固定为 \"multiValue\"。", - "enum": [ - "multiValue" - ], - "type": "string" - }, - "values": { - "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", - "items": { - "type": "string" - }, - "type": "array" + "date_time_grouping": { + "type": "string", + "enum": [ + "year", + "month", + "day", + "hour", + "minute", + "second" + ] + } + }, + "additionalProperties": false + } } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false } ] - }, - "type": "array" + } }, "filtered_rows": { + "type": "array", "description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。", "items": { "type": "number" - }, - "type": "array" + } } }, "required": [ "column_index", "conditions" ], - "type": "object" - }, - "type": "array" + "additionalProperties": false + } + }, + "filtered_columns": { + "type": "array", + "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", + "items": { + "type": "string" + } } }, "required": [ "range", "rules" ], - "type": "object" + "additionalProperties": false } }, "+filter-update": { "properties": { - "additionalProperties": false, "description": "创建/更新的筛选器属性。", + "type": "object", "properties": { - "filtered_columns": { - "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", - "items": { - "type": "string" - }, - "type": "array" - }, "range": { - "description": "筛选对象作用的单元格范围（A1 表示法）。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。", - "type": "string" + "type": "string", + "description": "筛选对象作用的单元格范围（A1 表示法）。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。" }, "rules": { + "type": "array", "description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。update 时传空数组 [] 表示清空所有现有列的规则。", "items": { - "additionalProperties": false, + "type": "object", "description": "单列筛选规则。", "properties": { "column_index": { - "description": "作用的列索引，例如 \"A\"、\"B\"。", - "type": "string" + "type": "string", + "description": "作用的列索引，例如 \"A\"、\"B\"。" }, "conditions": { + "type": "array", "description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。", "items": { "oneOf": [ { - "additionalProperties": false, + "type": "object", "description": "文本条件筛选。", "properties": { + "type": { + "type": "string", + "enum": [ + "text" + ], + "description": "条件类型固定为 \"text\"。" + }, "compare_type": { - "description": "文本比较方式：beginsWith=以指定文本开头，doesNotBeginWith=不以指定文本开头，endsWith=以指定文本结尾，doesNotEndWith=不以指定文本结尾，contains=包含，doesNotContain=不包含，equals=等于，notEquals=不等于。", + "type": "string", "enum": [ "beginsWith", "doesNotBeginWith", @@ -3878,35 +3880,35 @@ "equals", "notEquals" ], - "type": "string" - }, - "type": { - "description": "条件类型固定为 \"text\"。", - "enum": [ - "text" - ], - "type": "string" + "description": "文本比较方式：beginsWith=以指定文本开头，doesNotBeginWith=不以指定文本开头，endsWith=以指定文本结尾，doesNotEndWith=不以指定文本结尾，contains=包含，doesNotContain=不包含，equals=等于，notEquals=不等于。" }, "values": { + "type": "array", "description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。", "items": { "type": "string" - }, - "type": "array" + } } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "数值条件筛选。", "properties": { + "type": { + "type": "string", + "enum": [ + "number" + ], + "description": "条件类型固定为 \"number\"。" + }, "compare_type": { - "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。", + "type": "string", "enum": [ "equal", "notEqual", @@ -3917,16 +3919,10 @@ "between", "notBetween" ], - "type": "string" - }, - "type": { - "description": "条件类型固定为 \"number\"。", - "enum": [ - "number" - ], - "type": "string" + "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。" }, "values": { + "type": "array", "description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。", "items": { "oneOf": [ @@ -3937,73 +3933,82 @@ "type": "string" } ] - }, - "type": "array" + } } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "颜色条件筛选。", "properties": { - "compare_type": { - "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。", + "type": { + "type": "string", "enum": [ - "backgroundColor", - "foregroundColor" + "color" ], - "type": "string" + "description": "条件类型固定为 \"color\"。" }, - "type": { - "description": "条件类型固定为 \"color\"。", + "compare_type": { + "type": "string", "enum": [ - "color" + "backgroundColor", + "foregroundColor" ], - "type": "string" + "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。" }, "value": { - "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。", - "type": "string" + "type": "string", + "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。" } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "多值条件筛选。", "properties": { + "type": { + "type": "string", + "enum": [ + "multiValue" + ], + "description": "条件类型固定为 \"multiValue\"。" + }, "compare_type": { - "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。", + "type": "string", "enum": [ "equal", "notEqual" ], - "type": "string" + "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。" + }, + "values": { + "type": "array", + "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", + "items": { + "type": "string" + } }, "date_groups": { + "type": "array", "description": "可选。年月日等聚合筛选信息。", "items": { - "additionalProperties": false, + "type": "object", "properties": { - "date_time_grouping": { - "enum": [ - "year", - "month", - "day", - "hour", - "minute", - "second" - ], - "type": "string" + "year": { + "type": "number" + }, + "month": { + "type": "number" }, "day": { "type": "number" @@ -4014,105 +4019,106 @@ "minute": { "type": "number" }, - "month": { - "type": "number" - }, "second": { "type": "number" }, - "year": { - "type": "number" + "date_time_grouping": { + "type": "string", + "enum": [ + "year", + "month", + "day", + "hour", + "minute", + "second" + ] } }, - "type": "object" - }, - "type": "array" - }, - "type": { - "description": "条件类型固定为 \"multiValue\"。", - "enum": [ - "multiValue" - ], - "type": "string" - }, - "values": { - "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", - "items": { - "type": "string" - }, - "type": "array" + "additionalProperties": false + } } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false } ] - }, - "type": "array" + } }, "filtered_rows": { + "type": "array", "description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。", "items": { "type": "number" - }, - "type": "array" + } } }, "required": [ "column_index", "conditions" ], - "type": "object" - }, - "type": "array" + "additionalProperties": false + } + }, + "filtered_columns": { + "type": "array", + "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", + "items": { + "type": "string" + } } }, "required": [ "range", "rules" ], - "type": "object" + "additionalProperties": false } }, "+filter-view-create": { "properties": { - "additionalProperties": false, "description": "create / update 的视图属性。create 必须传 range；update 至少传 view_name / range / rules 之一。delete 禁止传该字段。", + "type": "object", "properties": { - "filtered_columns": { - "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", - "items": { - "type": "string" - }, - "type": "array" + "view_name": { + "type": "string", + "description": "可选。视图名称。create 不传时系统自动分配；create / update 传入时若与现有视图重名，会自动以后缀避让，不会抛错。" }, "range": { - "description": "视图作用的单元格范围（A1 表示法）。create 必填；update 可选——未提供时沿用视图当前 range。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。", - "type": "string" + "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 完全一致。", "items": { - "additionalProperties": false, + "type": "object", "description": "单列筛选规则。", "properties": { "column_index": { - "description": "作用的列索引，例如 \"A\"、\"B\"。", - "type": "string" + "type": "string", + "description": "作用的列索引，例如 \"A\"、\"B\"。" }, "conditions": { + "type": "array", "description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。", "items": { "oneOf": [ { - "additionalProperties": false, + "type": "object", "description": "文本条件筛选。", "properties": { + "type": { + "type": "string", + "enum": [ + "text" + ], + "description": "条件类型固定为 \"text\"。" + }, "compare_type": { - "description": "文本比较方式:beginsWith=以指定文本开头,doesNotBeginWith=不以指定文本开头,endsWith=以指定文本结尾,doesNotEndWith=不以指定文本结尾,contains=包含,doesNotContain=不包含,equals=等于,notEquals=不等于。", + "type": "string", "enum": [ "beginsWith", "doesNotBeginWith", @@ -4123,35 +4129,35 @@ "equals", "notEquals" ], - "type": "string" - }, - "type": { - "description": "条件类型固定为 \"text\"。", - "enum": [ - "text" - ], - "type": "string" + "description": "文本比较方式:beginsWith=以指定文本开头,doesNotBeginWith=不以指定文本开头,endsWith=以指定文本结尾,doesNotEndWith=不以指定文本结尾,contains=包含,doesNotContain=不包含,equals=等于,notEquals=不等于。" }, "values": { + "type": "array", "description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。", "items": { "type": "string" - }, - "type": "array" + } } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "数值条件筛选。", "properties": { + "type": { + "type": "string", + "enum": [ + "number" + ], + "description": "条件类型固定为 \"number\"。" + }, "compare_type": { - "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。", + "type": "string", "enum": [ "equal", "notEqual", @@ -4162,16 +4168,10 @@ "between", "notBetween" ], - "type": "string" - }, - "type": { - "description": "条件类型固定为 \"number\"。", - "enum": [ - "number" - ], - "type": "string" + "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。" }, "values": { + "type": "array", "description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。", "items": { "oneOf": [ @@ -4182,73 +4182,82 @@ "type": "string" } ] - }, - "type": "array" + } } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "颜色条件筛选。", "properties": { - "compare_type": { - "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。", + "type": { + "type": "string", "enum": [ - "backgroundColor", - "foregroundColor" + "color" ], - "type": "string" + "description": "条件类型固定为 \"color\"。" }, - "type": { - "description": "条件类型固定为 \"color\"。", + "compare_type": { + "type": "string", "enum": [ - "color" + "backgroundColor", + "foregroundColor" ], - "type": "string" + "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。" }, "value": { - "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。", - "type": "string" + "type": "string", + "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。" } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "多值条件筛选。", "properties": { + "type": { + "type": "string", + "enum": [ + "multiValue" + ], + "description": "条件类型固定为 \"multiValue\"。" + }, "compare_type": { - "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。", + "type": "string", "enum": [ "equal", "notEqual" ], - "type": "string" + "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。" + }, + "values": { + "type": "array", + "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", + "items": { + "type": "string" + } }, "date_groups": { + "type": "array", "description": "可选。年月日等聚合筛选信息。", "items": { - "additionalProperties": false, + "type": "object", "properties": { - "date_time_grouping": { - "enum": [ - "year", - "month", - "day", - "hour", - "minute", - "second" - ], - "type": "string" + "year": { + "type": "number" + }, + "month": { + "type": "number" }, "day": { "type": "number" @@ -4259,105 +4268,102 @@ "minute": { "type": "number" }, - "month": { - "type": "number" - }, "second": { "type": "number" }, - "year": { - "type": "number" + "date_time_grouping": { + "type": "string", + "enum": [ + "year", + "month", + "day", + "hour", + "minute", + "second" + ] } }, - "type": "object" - }, - "type": "array" - }, - "type": { - "description": "条件类型固定为 \"multiValue\"。", - "enum": [ - "multiValue" - ], - "type": "string" - }, - "values": { - "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", - "items": { - "type": "string" - }, - "type": "array" + "additionalProperties": false + } } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false } ] - }, - "type": "array" + } }, "filtered_rows": { + "type": "array", "description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。", "items": { "type": "number" - }, - "type": "array" + } } }, "required": [ "column_index", "conditions" ], - "type": "object" - }, - "type": "array" + "additionalProperties": false + } }, - "view_name": { - "description": "可选。视图名称。create 不传时系统自动分配；create / update 传入时若与现有视图重名，会自动以后缀避让，不会抛错。", - "type": "string" + "filtered_columns": { + "type": "array", + "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", + "items": { + "type": "string" + } } }, - "type": "object" + "additionalProperties": false } }, "+filter-view-update": { "properties": { - "additionalProperties": false, "description": "create / update 的视图属性。create 必须传 range；update 至少传 view_name / range / rules 之一。delete 禁止传该字段。", + "type": "object", "properties": { - "filtered_columns": { - "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", - "items": { - "type": "string" - }, - "type": "array" + "view_name": { + "type": "string", + "description": "可选。视图名称。create 不传时系统自动分配；create / update 传入时若与现有视图重名，会自动以后缀避让，不会抛错。" }, "range": { - "description": "视图作用的单元格范围（A1 表示法）。create 必填；update 可选——未提供时沿用视图当前 range。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。", - "type": "string" + "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 完全一致。", "items": { - "additionalProperties": false, + "type": "object", "description": "单列筛选规则。", "properties": { "column_index": { - "description": "作用的列索引，例如 \"A\"、\"B\"。", - "type": "string" + "type": "string", + "description": "作用的列索引，例如 \"A\"、\"B\"。" }, "conditions": { + "type": "array", "description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。", "items": { "oneOf": [ { - "additionalProperties": false, + "type": "object", "description": "文本条件筛选。", "properties": { + "type": { + "type": "string", + "enum": [ + "text" + ], + "description": "条件类型固定为 \"text\"。" + }, "compare_type": { - "description": "文本比较方式:beginsWith=以指定文本开头,doesNotBeginWith=不以指定文本开头,endsWith=以指定文本结尾,doesNotEndWith=不以指定文本结尾,contains=包含,doesNotContain=不包含,equals=等于,notEquals=不等于。", + "type": "string", "enum": [ "beginsWith", "doesNotBeginWith", @@ -4366,37 +4372,37 @@ "contains", "doesNotContain", "equals", - "notEquals" - ], - "type": "string" - }, - "type": { - "description": "条件类型固定为 \"text\"。", - "enum": [ - "text" + "notEquals" ], - "type": "string" + "description": "文本比较方式:beginsWith=以指定文本开头,doesNotBeginWith=不以指定文本开头,endsWith=以指定文本结尾,doesNotEndWith=不以指定文本结尾,contains=包含,doesNotContain=不包含,equals=等于,notEquals=不等于。" }, "values": { + "type": "array", "description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。", "items": { "type": "string" - }, - "type": "array" + } } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "数值条件筛选。", "properties": { + "type": { + "type": "string", + "enum": [ + "number" + ], + "description": "条件类型固定为 \"number\"。" + }, "compare_type": { - "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。", + "type": "string", "enum": [ "equal", "notEqual", @@ -4407,16 +4413,10 @@ "between", "notBetween" ], - "type": "string" - }, - "type": { - "description": "条件类型固定为 \"number\"。", - "enum": [ - "number" - ], - "type": "string" + "description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。" }, "values": { + "type": "array", "description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。", "items": { "oneOf": [ @@ -4427,73 +4427,82 @@ "type": "string" } ] - }, - "type": "array" + } } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "颜色条件筛选。", "properties": { - "compare_type": { - "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。", + "type": { + "type": "string", "enum": [ - "backgroundColor", - "foregroundColor" + "color" ], - "type": "string" + "description": "条件类型固定为 \"color\"。" }, - "type": { - "description": "条件类型固定为 \"color\"。", + "compare_type": { + "type": "string", "enum": [ - "color" + "backgroundColor", + "foregroundColor" ], - "type": "string" + "description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。" }, "value": { - "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。", - "type": "string" + "type": "string", + "description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。" } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false }, { - "additionalProperties": false, + "type": "object", "description": "多值条件筛选。", "properties": { + "type": { + "type": "string", + "enum": [ + "multiValue" + ], + "description": "条件类型固定为 \"multiValue\"。" + }, "compare_type": { - "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。", + "type": "string", "enum": [ "equal", "notEqual" ], - "type": "string" + "description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。" + }, + "values": { + "type": "array", + "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", + "items": { + "type": "string" + } }, "date_groups": { + "type": "array", "description": "可选。年月日等聚合筛选信息。", "items": { - "additionalProperties": false, + "type": "object", "properties": { - "date_time_grouping": { - "enum": [ - "year", - "month", - "day", - "hour", - "minute", - "second" - ], - "type": "string" + "year": { + "type": "number" + }, + "month": { + "type": "number" }, "day": { "type": "number" @@ -4504,288 +4513,148 @@ "minute": { "type": "number" }, - "month": { - "type": "number" - }, "second": { "type": "number" }, - "year": { - "type": "number" + "date_time_grouping": { + "type": "string", + "enum": [ + "year", + "month", + "day", + "hour", + "minute", + "second" + ] } }, - "type": "object" - }, - "type": "array" - }, - "type": { - "description": "条件类型固定为 \"multiValue\"。", - "enum": [ - "multiValue" - ], - "type": "string" - }, - "values": { - "description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。", - "items": { - "type": "string" - }, - "type": "array" + "additionalProperties": false + } } }, "required": [ "type", "compare_type" ], - "type": "object" + "additionalProperties": false } ] - }, - "type": "array" + } }, "filtered_rows": { + "type": "array", "description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。", "items": { "type": "number" - }, - "type": "array" + } } }, "required": [ "column_index", "conditions" ], - "type": "object" - }, - "type": "array" + "additionalProperties": false + } }, - "view_name": { - "description": "可选。视图名称。create 不传时系统自动分配；create / update 传入时若与现有视图重名，会自动以后缀避让，不会抛错。", - "type": "string" + "filtered_columns": { + "type": "array", + "description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。", + "items": { + "type": "string" + } } }, - "type": "object" + "additionalProperties": false } }, "+pivot-create": { "properties": { - "additionalProperties": {}, "description": "创建/更新的透视表属性。", + "type": "object", "properties": { - "auto_fit_col": { - "description": "是否自动调整列宽以适应内容", - "type": "boolean" - }, - "calculated_fields": { - "description": "计算字段列表", - "items": { - "properties": { - "formula": { - "description": "公式表达式，引用其他字段名，例如 \"'Sales' + 'Tax'\"", - "type": "string" - }, - "name": { - "description": "计算字段的显示名称", - "type": "string" - }, - "summarize_by": { - "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" - ], - "type": "string" - } - }, - "required": [ - "name", - "formula" - ], - "type": "object" - }, - "type": "array" + "range": { + "type": "string", + "description": "放置透视表的左上角单元格 A1 地址（例如：'F1'）（仅 create 时有效）。可省略——省略后透视表放在新建子表的 A1 位置。" }, - "collapse": { - "additionalProperties": { - "items": { - "type": "string" - }, - "type": "array" - }, - "description": "行字段展开/折叠状态：字段名 -> 要折叠的项目列表", - "type": "object" + "source": { + "type": "string", + "description": "源数据区域地址，格式为 'SheetName!StartCell:EndCell'（例如：'Sheet1!A1:D100'）。create 时必填；update 时提供则切换数据源。" }, - "columns": { - "description": "横向分组字段（列字段）", + "rows": { + "description": "纵向分组字段（行字段）", + "type": "array", "items": { + "type": "object", "properties": { - "condition_filter": { - "description": "条件筛选：按文本/数值/日期条件筛选", - "properties": { - "operator": { - "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", - "type": "string" - }, - "type": { - "description": "条件类型", - "enum": [ - "text", - "number", - "date" - ], - "type": "string" - }, - "value": { - "description": "比较值" - }, - "value2": { - "description": "'between'/'notBetween' 的第二个边界值" - } - }, - "required": [ - "type", - "operator" - ], - "type": "object" - }, - "display_name": { - "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。", - "type": "string" - }, "field": { - "description": "源数据中的字段名（OOXML 字段引用）", - "type": "string" + "type": "string", + "description": "源数据中的字段名（OOXML 字段引用）" }, - "filter": { - "description": "快速筛选：只显示指定的项目", - "properties": { - "items": { - "description": "要显示的项目列表（其余项目被隐藏）", - "items": { - "type": "string" - }, - "type": "array" - } - }, - "required": [ - "items" - ], - "type": "object" + "display_name": { + "type": "string", + "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用；否则保持源字段原名，透视表产物已足够清晰。" }, - "group": { - "description": "分组配置", + "sort": { + "type": "object", + "description": "排序配置", "properties": { - "date_group_by": { - "description": "日期分组粒度（type='date' 时必填）", + "order": { + "type": "string", "enum": [ - "year", - "yearMonth", - "yearQuarter", - "yearMonthDate", - "quarter", - "month", - "monthDate", - "date", - "hour", - "hourMinute", - "minute" + "asc", + "desc" ], - "type": "string" - }, - "end": { - "description": "数值分组结束值", - "type": "number" - }, - "groups": { - "additionalProperties": { - "items": { - "type": "string" - }, - "type": "array" - }, - "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", - "type": "object" - }, - "interval": { - "description": "数值分组间隔（type='number' 时必填）", - "type": "number" - }, - "start": { - "description": "数值分组起始值", - "type": "number" + "description": "排序方向" }, - "type": { - "description": "分组类型", - "enum": [ - "date", - "number", - "element" - ], - "type": "string" - } - }, - "required": [ - "type" - ], - "type": "object" - }, - "sort": { - "description": "排序配置", - "properties": { "by": { - "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序", + "type": "string", "enum": [ "label", "value" ], - "type": "string" - }, - "order": { - "description": "排序方向", - "enum": [ - "asc", - "desc" - ], - "type": "string" + "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序" }, "value_field": { - "description": "by='value' 时必填，指定按哪个值字段排序", - "type": "string" + "type": "string", + "description": "by='value' 时必填，指定按哪个值字段排序" } }, "required": [ "order" - ], - "type": "object" - } - }, - "required": [ - "field" - ], - "type": "object" - }, - "type": "array" - }, - "filters": { - "description": "筛选区域字段（页字段）", - "items": { - "properties": { + ] + }, + "filter": { + "type": "object", + "description": "快速筛选：只显示指定的项目", + "properties": { + "items": { + "type": "array", + "items": { + "type": "string" + }, + "description": "要显示的项目列表（其余项目被隐藏）" + } + }, + "required": [ + "items" + ] + }, "condition_filter": { + "type": "object", "description": "条件筛选：按文本/数值/日期条件筛选", "properties": { - "operator": { - "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", - "type": "string" - }, "type": { - "description": "条件类型", + "type": "string", "enum": [ "text", "number", "date" ], - "type": "string" + "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": "比较值" @@ -4797,38 +4666,23 @@ "required": [ "type", "operator" - ], - "type": "object" - }, - "display_name": { - "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。", - "type": "string" - }, - "field": { - "description": "源数据中的字段名（OOXML 字段引用）", - "type": "string" - }, - "filter": { - "description": "快速筛选：只显示指定的项目", - "properties": { - "items": { - "description": "要显示的项目列表（其余项目被隐藏）", - "items": { - "type": "string" - }, - "type": "array" - } - }, - "required": [ - "items" - ], - "type": "object" + ] }, "group": { + "type": "object", "description": "分组配置", "properties": { + "type": { + "type": "string", + "enum": [ + "date", + "number", + "element" + ], + "description": "分组类型" + }, "date_group_by": { - "description": "日期分组粒度（type='date' 时必填）", + "type": "string", "enum": [ "year", "yearMonth", @@ -4842,123 +4696,144 @@ "hourMinute", "minute" ], - "type": "string" + "description": "日期分组粒度（type='date' 时必填）" + }, + "interval": { + "type": "number", + "description": "数值分组间隔（type='number' 时必填）" + }, + "start": { + "type": "number", + "description": "数值分组起始值" }, "end": { - "description": "数值分组结束值", - "type": "number" + "type": "number", + "description": "数值分组结束值" }, "groups": { + "type": "object", + "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { + "type": "array", "items": { "type": "string" - }, - "type": "array" - }, - "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", - "type": "object" - }, - "interval": { - "description": "数值分组间隔（type='number' 时必填）", - "type": "number" - }, - "start": { - "description": "数值分组起始值", - "type": "number" - }, - "type": { - "description": "分组类型", - "enum": [ - "date", - "number", - "element" - ], - "type": "string" + } + } } }, "required": [ "type" - ], - "type": "object" + ] } }, "required": [ "field" - ], - "type": "object" - }, - "type": "array" - }, - "range": { - "description": "放置透视表的左上角单元格 A1 地址（例如：'F1'）（仅 create 时有效）。可省略——省略后透视表放在新建子表的 A1 位置。", - "type": "string" - }, - "repeat_row_labels": { - "description": "是否显示重复项标签", - "type": "boolean" + ] + } }, - "rows": { - "description": "纵向分组字段（行字段）", + "columns": { + "description": "横向分组字段（列字段）", + "type": "array", "items": { + "type": "object", "properties": { - "condition_filter": { - "description": "条件筛选：按文本/数值/日期条件筛选", + "field": { + "type": "string", + "description": "源数据中的字段名（OOXML 字段引用）" + }, + "display_name": { + "type": "string", + "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。" + }, + "sort": { + "type": "object", + "description": "排序配置", "properties": { - "operator": { - "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", - "type": "string" - }, - "type": { - "description": "条件类型", + "order": { + "type": "string", "enum": [ - "text", - "number", - "date" + "asc", + "desc" ], - "type": "string" + "description": "排序方向" }, - "value": { - "description": "比较值" + "by": { + "type": "string", + "enum": [ + "label", + "value" + ], + "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序" }, - "value2": { - "description": "'between'/'notBetween' 的第二个边界值" + "value_field": { + "type": "string", + "description": "by='value' 时必填，指定按哪个值字段排序" } }, "required": [ - "type", - "operator" - ], - "type": "object" - }, - "display_name": { - "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用；否则保持源字段原名，透视表产物已足够清晰。", - "type": "string" - }, - "field": { - "description": "源数据中的字段名（OOXML 字段引用）", - "type": "string" + "order" + ] }, "filter": { + "type": "object", "description": "快速筛选：只显示指定的项目", "properties": { "items": { - "description": "要显示的项目列表（其余项目被隐藏）", + "type": "array", "items": { "type": "string" }, - "type": "array" + "description": "要显示的项目列表（其余项目被隐藏）" } }, "required": [ "items" - ], - "type": "object" + ] + }, + "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": { - "description": "日期分组粒度（type='date' 时必填）", + "type": "string", "enum": [ "year", "yearMonth", @@ -4972,130 +4847,181 @@ "hourMinute", "minute" ], - "type": "string" + "description": "日期分组粒度（type='date' 时必填）" + }, + "interval": { + "type": "number", + "description": "数值分组间隔（type='number' 时必填）" + }, + "start": { + "type": "number", + "description": "数值分组起始值" }, "end": { - "description": "数值分组结束值", - "type": "number" + "type": "number", + "description": "数值分组结束值" }, "groups": { + "type": "object", + "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { + "type": "array", "items": { "type": "string" - }, - "type": "array" + } + } + } + }, + "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": "元素分组：组名 -> 项目列表（type='element' 时必填）", - "type": "object" - }, - "interval": { - "description": "数值分组间隔（type='number' 时必填）", - "type": "number" - }, - "start": { - "description": "数值分组起始值", - "type": "number" - }, + "description": "要显示的项目列表（其余项目被隐藏）" + } + }, + "required": [ + "items" + ] + }, + "condition_filter": { + "type": "object", + "description": "条件筛选：按文本/数值/日期条件筛选", + "properties": { "type": { - "description": "分组类型", + "type": "string", "enum": [ - "date", + "text", "number", - "element" + "date" ], - "type": "string" + "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" - ], - "type": "object" + "type", + "operator" + ] }, - "sort": { - "description": "排序配置", + "group": { + "type": "object", + "description": "分组配置", "properties": { - "by": { - "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序", + "type": { + "type": "string", "enum": [ - "label", - "value" + "date", + "number", + "element" + ], + "description": "分组类型" + }, + "date_group_by": { + "type": "string", + "enum": [ + "year", + "yearMonth", + "yearQuarter", + "yearMonthDate", + "quarter", + "month", + "monthDate", + "date", + "hour", + "hourMinute", + "minute" ], - "type": "string" + "description": "日期分组粒度（type='date' 时必填）" }, - "order": { - "description": "排序方向", - "enum": [ - "asc", - "desc" - ], - "type": "string" + "interval": { + "type": "number", + "description": "数值分组间隔（type='number' 时必填）" }, - "value_field": { - "description": "by='value' 时必填，指定按哪个值字段排序", - "type": "string" + "start": { + "type": "number", + "description": "数值分组起始值" + }, + "end": { + "type": "number", + "description": "数值分组结束值" + }, + "groups": { + "type": "object", + "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } } }, "required": [ - "order" - ], - "type": "object" + "type" + ] } }, "required": [ "field" - ], - "type": "object" - }, - "type": "array" - }, - "show_col_grand_total": { - "description": "是否显示列总计（默认 true）", - "type": "boolean" - }, - "show_row_grand_total": { - "description": "是否显示行总计（默认 true）", - "type": "boolean" - }, - "show_subtotals": { - "description": "是否显示分类小计（默认 true，应用于所有字段）", - "type": "boolean" - }, - "source": { - "description": "源数据区域地址，格式为 'SheetName!StartCell:EndCell'（例如：'Sheet1!A1:D100'）。create 时必填；update 时提供则切换数据源。", - "type": "string" + ] + } }, "values": { - "description": "要汇总的字段（至少需要 1 个）", + "minItems": 1, + "type": "array", "items": { + "type": "object", "properties": { - "base_field": { - "description": "show_data_as 需要基准字段时的字段名", - "type": "string" - }, - "display_name": { - "description": "字段在透视表中的显示名（典型场景：把 count(销售额) 的值列头显示为 'GMV'）。不传则使用源字段原名。仅在用户明确要求重命名时使用。", - "type": "string" - }, "field": { - "description": "要汇总的源数据字段名", - "type": "string" + "type": "string", + "description": "要汇总的源数据字段名" }, - "show_data_as": { - "description": "值显示方式（默认 'normal'）", - "enum": [ - "normal", - "percentOfTotal", - "percentOfCol", - "percentOfRow", - "percentOfParentRow", - "percentOfParentCol", - "index" - ], - "type": "string" + "display_name": { + "type": "string", + "description": "字段在透视表中的显示名（典型场景：把 count(销售额) 的值列头显示为 'GMV'）。不传则使用源字段原名。仅在用户明确要求重命名时使用。" }, "summarize_by": { "default": "sum", "description": "汇总函数", + "type": "string", "enum": [ "sum", "count", @@ -5110,133 +5036,212 @@ "varp", "distinct", "median" - ], - "type": "string" + ] + }, + "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" - ], - "type": "object" + ] }, - "minItems": 1, - "type": "array" - } - }, - "type": "object" - } - }, - "+pivot-update": { - "properties": { - "additionalProperties": {}, - "description": "创建/更新的透视表属性。", - "properties": { + "description": "要汇总的字段（至少需要 1 个）" + }, "auto_fit_col": { - "description": "是否自动调整列宽以适应内容", - "type": "boolean" + "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": { - "formula": { - "description": "公式表达式，引用其他字段名，例如 \"'Sales' + 'Tax'\"", - "type": "string" - }, "name": { - "description": "计算字段的显示名称", - "type": "string" + "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" - ], - "type": "string" + ] } }, "required": [ "name", "formula" - ], - "type": "object" - }, - "type": "array" + ] + } }, "collapse": { + "type": "object", + "description": "行字段展开/折叠状态：字段名 -> 要折叠的项目列表", "additionalProperties": { + "type": "array", "items": { "type": "string" - }, - "type": "array" - }, - "description": "行字段展开/折叠状态：字段名 -> 要折叠的项目列表", - "type": "object" + } + } + } + }, + "additionalProperties": {} + } + }, + "+pivot-update": { + "properties": { + "description": "创建/更新的透视表属性。", + "type": "object", + "properties": { + "range": { + "type": "string", + "description": "放置透视表的左上角单元格 A1 地址（例如：'F1'）（仅 create 时有效）。可省略——省略后透视表放在新建子表的 A1 位置。" }, - "columns": { - "description": "横向分组字段（列字段）", + "source": { + "type": "string", + "description": "源数据区域地址，格式为 'SheetName!StartCell:EndCell'（例如：'Sheet1!A1:D100'）。create 时必填；update 时提供则切换数据源。" + }, + "rows": { + "description": "纵向分组字段（行字段）", + "type": "array", "items": { + "type": "object", "properties": { - "condition_filter": { - "description": "条件筛选：按文本/数值/日期条件筛选", + "field": { + "type": "string", + "description": "源数据中的字段名（OOXML 字段引用）" + }, + "display_name": { + "type": "string", + "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用；否则保持源字段原名，透视表产物已足够清晰。" + }, + "sort": { + "type": "object", + "description": "排序配置", "properties": { - "operator": { - "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", - "type": "string" - }, - "type": { - "description": "条件类型", + "order": { + "type": "string", "enum": [ - "text", - "number", - "date" + "asc", + "desc" ], - "type": "string" + "description": "排序方向" }, - "value": { - "description": "比较值" + "by": { + "type": "string", + "enum": [ + "label", + "value" + ], + "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序" }, - "value2": { - "description": "'between'/'notBetween' 的第二个边界值" + "value_field": { + "type": "string", + "description": "by='value' 时必填，指定按哪个值字段排序" } }, "required": [ - "type", - "operator" - ], - "type": "object" - }, - "display_name": { - "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。", - "type": "string" - }, - "field": { - "description": "源数据中的字段名（OOXML 字段引用）", - "type": "string" + "order" + ] }, "filter": { + "type": "object", "description": "快速筛选：只显示指定的项目", "properties": { "items": { - "description": "要显示的项目列表（其余项目被隐藏）", + "type": "array", "items": { "type": "string" }, - "type": "array" + "description": "要显示的项目列表（其余项目被隐藏）" } }, "required": [ "items" - ], - "type": "object" + ] + }, + "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": { - "description": "日期分组粒度（type='date' 时必填）", + "type": "string", "enum": [ "year", "yearMonth", @@ -5250,101 +5255,116 @@ "hourMinute", "minute" ], - "type": "string" + "description": "日期分组粒度（type='date' 时必填）" + }, + "interval": { + "type": "number", + "description": "数值分组间隔（type='number' 时必填）" + }, + "start": { + "type": "number", + "description": "数值分组起始值" }, "end": { - "description": "数值分组结束值", - "type": "number" + "type": "number", + "description": "数值分组结束值" }, "groups": { + "type": "object", + "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { + "type": "array", "items": { "type": "string" - }, - "type": "array" - }, - "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", - "type": "object" - }, - "interval": { - "description": "数值分组间隔（type='number' 时必填）", - "type": "number" - }, - "start": { - "description": "数值分组起始值", - "type": "number" - }, - "type": { - "description": "分组类型", - "enum": [ - "date", - "number", - "element" - ], - "type": "string" + } + } } }, "required": [ "type" - ], - "type": "object" + ] + } + }, + "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": { - "by": { - "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序", - "enum": [ - "label", - "value" - ], - "type": "string" - }, "order": { - "description": "排序方向", + "type": "string", "enum": [ "asc", "desc" ], - "type": "string" + "description": "排序方向" + }, + "by": { + "type": "string", + "enum": [ + "label", + "value" + ], + "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序" }, "value_field": { - "description": "by='value' 时必填，指定按哪个值字段排序", - "type": "string" + "type": "string", + "description": "by='value' 时必填，指定按哪个值字段排序" } }, "required": [ "order" - ], - "type": "object" - } - }, - "required": [ - "field" - ], - "type": "object" - }, - "type": "array" - }, - "filters": { - "description": "筛选区域字段（页字段）", - "items": { - "properties": { + ] + }, + "filter": { + "type": "object", + "description": "快速筛选：只显示指定的项目", + "properties": { + "items": { + "type": "array", + "items": { + "type": "string" + }, + "description": "要显示的项目列表（其余项目被隐藏）" + } + }, + "required": [ + "items" + ] + }, "condition_filter": { + "type": "object", "description": "条件筛选：按文本/数值/日期条件筛选", "properties": { - "operator": { - "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", - "type": "string" - }, "type": { - "description": "条件类型", + "type": "string", "enum": [ "text", "number", "date" ], - "type": "string" + "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": "比较值" @@ -5356,38 +5376,23 @@ "required": [ "type", "operator" - ], - "type": "object" - }, - "display_name": { - "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。", - "type": "string" - }, - "field": { - "description": "源数据中的字段名（OOXML 字段引用）", - "type": "string" - }, - "filter": { - "description": "快速筛选：只显示指定的项目", - "properties": { - "items": { - "description": "要显示的项目列表（其余项目被隐藏）", - "items": { - "type": "string" - }, - "type": "array" - } - }, - "required": [ - "items" - ], - "type": "object" + ] }, "group": { + "type": "object", "description": "分组配置", "properties": { + "type": { + "type": "string", + "enum": [ + "date", + "number", + "element" + ], + "description": "分组类型" + }, "date_group_by": { - "description": "日期分组粒度（type='date' 时必填）", + "type": "string", "enum": [ "year", "yearMonth", @@ -5401,80 +5406,87 @@ "hourMinute", "minute" ], - "type": "string" + "description": "日期分组粒度（type='date' 时必填）" + }, + "interval": { + "type": "number", + "description": "数值分组间隔（type='number' 时必填）" + }, + "start": { + "type": "number", + "description": "数值分组起始值" }, "end": { - "description": "数值分组结束值", - "type": "number" + "type": "number", + "description": "数值分组结束值" }, "groups": { + "type": "object", + "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { + "type": "array", "items": { "type": "string" - }, - "type": "array" - }, - "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", - "type": "object" - }, - "interval": { - "description": "数值分组间隔（type='number' 时必填）", - "type": "number" - }, - "start": { - "description": "数值分组起始值", - "type": "number" - }, - "type": { - "description": "分组类型", - "enum": [ - "date", - "number", - "element" - ], - "type": "string" + } + } } }, "required": [ "type" - ], - "type": "object" + ] } }, "required": [ "field" - ], - "type": "object" - }, - "type": "array" - }, - "range": { - "description": "放置透视表的左上角单元格 A1 地址（例如：'F1'）（仅 create 时有效）。可省略——省略后透视表放在新建子表的 A1 位置。", - "type": "string" - }, - "repeat_row_labels": { - "description": "是否显示重复项标签", - "type": "boolean" + ] + } }, - "rows": { - "description": "纵向分组字段（行字段）", + "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": { - "operator": { - "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", - "type": "string" - }, "type": { - "description": "条件类型", + "type": "string", "enum": [ "text", "number", "date" ], - "type": "string" + "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": "比较值" @@ -5486,38 +5498,23 @@ "required": [ "type", "operator" - ], - "type": "object" - }, - "display_name": { - "description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用；否则保持源字段原名，透视表产物已足够清晰。", - "type": "string" - }, - "field": { - "description": "源数据中的字段名（OOXML 字段引用）", - "type": "string" - }, - "filter": { - "description": "快速筛选：只显示指定的项目", - "properties": { - "items": { - "description": "要显示的项目列表（其余项目被隐藏）", - "items": { - "type": "string" - }, - "type": "array" - } - }, - "required": [ - "items" - ], - "type": "object" + ] }, "group": { + "type": "object", "description": "分组配置", "properties": { + "type": { + "type": "string", + "enum": [ + "date", + "number", + "element" + ], + "description": "分组类型" + }, "date_group_by": { - "description": "日期分组粒度（type='date' 时必填）", + "type": "string", "enum": [ "year", "yearMonth", @@ -5531,130 +5528,59 @@ "hourMinute", "minute" ], - "type": "string" + "description": "日期分组粒度（type='date' 时必填）" + }, + "interval": { + "type": "number", + "description": "数值分组间隔（type='number' 时必填）" + }, + "start": { + "type": "number", + "description": "数值分组起始值" }, "end": { - "description": "数值分组结束值", - "type": "number" + "type": "number", + "description": "数值分组结束值" }, "groups": { + "type": "object", + "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", "additionalProperties": { + "type": "array", "items": { "type": "string" - }, - "type": "array" - }, - "description": "元素分组：组名 -> 项目列表（type='element' 时必填）", - "type": "object" - }, - "interval": { - "description": "数值分组间隔（type='number' 时必填）", - "type": "number" - }, - "start": { - "description": "数值分组起始值", - "type": "number" - }, - "type": { - "description": "分组类型", - "enum": [ - "date", - "number", - "element" - ], - "type": "string" + } + } } }, "required": [ "type" - ], - "type": "object" - }, - "sort": { - "description": "排序配置", - "properties": { - "by": { - "description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序", - "enum": [ - "label", - "value" - ], - "type": "string" - }, - "order": { - "description": "排序方向", - "enum": [ - "asc", - "desc" - ], - "type": "string" - }, - "value_field": { - "description": "by='value' 时必填，指定按哪个值字段排序", - "type": "string" - } - }, - "required": [ - "order" - ], - "type": "object" + ] } }, "required": [ "field" - ], - "type": "object" - }, - "type": "array" - }, - "show_col_grand_total": { - "description": "是否显示列总计（默认 true）", - "type": "boolean" - }, - "show_row_grand_total": { - "description": "是否显示行总计（默认 true）", - "type": "boolean" - }, - "show_subtotals": { - "description": "是否显示分类小计（默认 true，应用于所有字段）", - "type": "boolean" - }, - "source": { - "description": "源数据区域地址，格式为 'SheetName!StartCell:EndCell'（例如：'Sheet1!A1:D100'）。create 时必填；update 时提供则切换数据源。", - "type": "string" + ] + } }, "values": { - "description": "要汇总的字段（至少需要 1 个）", + "minItems": 1, + "type": "array", "items": { - "properties": { - "base_field": { - "description": "show_data_as 需要基准字段时的字段名", - "type": "string" - }, - "display_name": { - "description": "字段在透视表中的显示名（典型场景：把 count(销售额) 的值列头显示为 'GMV'）。不传则使用源字段原名。仅在用户明确要求重命名时使用。", - "type": "string" - }, + "type": "object", + "properties": { "field": { - "description": "要汇总的源数据字段名", - "type": "string" + "type": "string", + "description": "要汇总的源数据字段名" }, - "show_data_as": { - "description": "值显示方式（默认 'normal'）", - "enum": [ - "normal", - "percentOfTotal", - "percentOfCol", - "percentOfRow", - "percentOfParentRow", - "percentOfParentCol", - "index" - ], - "type": "string" + "display_name": { + "type": "string", + "description": "字段在透视表中的显示名（典型场景：把 count(销售额) 的值列头显示为 'GMV'）。不传则使用源字段原名。仅在用户明确要求重命名时使用。" }, "summarize_by": { "default": "sum", "description": "汇总函数", + "type": "string", "enum": [ "sum", "count", @@ -5669,633 +5595,707 @@ "varp", "distinct", "median" - ], - "type": "string" + ] + }, + "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" - ], - "type": "object" + ] }, - "minItems": 1, - "type": "array" + "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" + } + } } }, - "type": "object" + "additionalProperties": {} } }, "+range-sort": { "sort-keys": { - "description": "排序条件列表（仅 sort 操作）。支持多级排序，靠前的条件优先级更高。", + "type": "array", "items": { + "type": "object", "properties": { - "ascending": { - "description": "是否升序排序", - "type": "boolean" - }, "column": { - "description": "排序依据的列字母（如 \"C\"、\"D\"），必须在 range 范围内", - "type": "string" + "type": "string", + "description": "排序依据的列字母（如 \"C\"、\"D\"），必须在 range 范围内" + }, + "ascending": { + "type": "boolean", + "description": "是否升序排序" } }, "required": [ "column", "ascending" - ], - "type": "object" + ] }, - "type": "array" + "description": "排序条件列表（仅 sort 操作）。支持多级排序，靠前的条件优先级更高。" } }, "+sparkline-create": { "properties": { - "additionalProperties": false, "description": "创建/更新/部分删除的迷你图属性。delete 时不传 sparklines 即删整组，传则删指定项。", + "type": "object", "properties": { "config": { - "additionalProperties": false, + "type": "object", "description": "迷你图样式配置, 相同 groupId 的迷你图共享相同的样式。", "properties": { - "axis": { - "additionalProperties": false, - "description": "坐标轴配置，包含坐标轴颜色、是否翻转、是否显示坐标轴。", - "properties": { - "color": { - "description": "坐标轴颜色。", - "type": "string" - }, - "reverse": { - "description": "是否翻转坐标轴方向。", - "type": "boolean" - }, - "visible": { - "description": "是否显示坐标轴。", - "type": "boolean" - } - }, - "type": "object" - }, - "contain_hidden_cells": { - "description": "隐藏的单元格数据是否参与绘制。", - "type": "boolean" + "theme_type": { + "type": "string", + "enum": [ + "pro", + "light", + "soft", + "brand", + "fresh" + ], + "description": "主题类型：pro、light、soft、brand、fresh。" }, - "empty_show_as": { - "description": "空单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。", + "non_num_show_as": { + "type": "string", "enum": [ "zero", "gap", "average" ], - "type": "string" - }, - "extremum_max": { - "additionalProperties": false, - "description": "最大极值配置，包含极值类型、极值。", - "properties": { - "type": { - "description": "极值类型，可选值：individual=单个迷你图极值，group=同组内极值，custom=自定义。", - "enum": [ - "individual", - "group", - "custom" - ], - "type": "string" - }, - "value": { - "description": "当 type='custom' 时生效的具体数值。", - "type": "number" - } - }, - "required": [ - "type" - ], - "type": "object" - }, - "extremum_min": { - "additionalProperties": false, - "description": "最小极值配置，包含极值类型、极值。", - "properties": { - "type": { - "description": "极值类型：individual=单个迷你图极值，group=同组内极值，custom=自定义。", - "enum": [ - "individual", - "group", - "custom" - ], - "type": "string" - }, - "value": { - "description": "当 type='custom' 时生效的具体数值。", - "type": "number" - } - }, - "required": [ - "type" - ], - "type": "object" - }, - "line_width": { - "description": "折线图线宽，可选值：1=1px，2=2px，3=3px，4=4px。", - "enum": [ - 1, - 2, - 3, - 4 - ], - "type": "number" + "description": "非数字单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。" }, - "non_num_show_as": { - "description": "非数字单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。", + "empty_show_as": { + "type": "string", "enum": [ "zero", "gap", "average" ], - "type": "string" + "description": "空单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。" + }, + "contain_hidden_cells": { + "type": "boolean", + "description": "隐藏的单元格数据是否参与绘制。" + }, + "series_color": { + "type": "string", + "description": "主系列颜色，例如 \"#4472C4\"。" }, "points": { - "additionalProperties": false, + "type": "object", "description": "特殊点样式配置，包含高点、低点、标记点、首点、尾点、负点。", "properties": { - "first_point": { - "additionalProperties": false, - "description": "首点配置，第一个数据点的样式。", + "last_point": { + "type": "object", + "description": "尾点配置，最后一个数据点的样式。", "properties": { "color": { - "description": "点的颜色。", - "type": "string" + "type": "string", + "description": "点的颜色。" }, "visible": { - "description": "是否显示该点。", - "type": "boolean" + "type": "boolean", + "description": "是否显示该点。" } }, - "type": "object" + "additionalProperties": false }, - "high_point": { - "additionalProperties": false, - "description": "高点配置，最高点的样式。", + "negative_point": { + "type": "object", + "description": "负点配置，负数点的样式。", "properties": { "color": { - "description": "点的颜色。", - "type": "string" + "type": "string", + "description": "点的颜色。" }, "visible": { - "description": "是否显示该点。", - "type": "boolean" + "type": "boolean", + "description": "是否显示该点。" } }, - "type": "object" + "additionalProperties": false }, - "last_point": { - "additionalProperties": false, - "description": "尾点配置，最后一个数据点的样式。", + "markers_point": { + "type": "object", + "description": "标记点配置，所有标记点的样式。", "properties": { "color": { - "description": "点的颜色。", - "type": "string" + "type": "string", + "description": "点的颜色。" }, "visible": { - "description": "是否显示该点。", - "type": "boolean" + "type": "boolean", + "description": "是否显示该点。" } }, - "type": "object" + "additionalProperties": false }, - "low_point": { - "additionalProperties": false, - "description": "低点配置，最低点的样式。", + "first_point": { + "type": "object", + "description": "首点配置，第一个数据点的样式。", "properties": { "color": { - "description": "点的颜色。", - "type": "string" + "type": "string", + "description": "点的颜色。" }, "visible": { - "description": "是否显示该点。", - "type": "boolean" + "type": "boolean", + "description": "是否显示该点。" } }, - "type": "object" + "additionalProperties": false }, - "markers_point": { - "additionalProperties": false, - "description": "标记点配置，所有标记点的样式。", + "high_point": { + "type": "object", + "description": "高点配置，最高点的样式。", "properties": { "color": { - "description": "点的颜色。", - "type": "string" + "type": "string", + "description": "点的颜色。" + }, + "visible": { + "type": "boolean", + "description": "是否显示该点。" + } + }, + "additionalProperties": false + }, + "low_point": { + "type": "object", + "description": "低点配置，最低点的样式。", + "properties": { + "color": { + "type": "string", + "description": "点的颜色。" }, "visible": { - "description": "是否显示该点。", - "type": "boolean" + "type": "boolean", + "description": "是否显示该点。" } }, - "type": "object" + "additionalProperties": false + } + }, + "additionalProperties": false + }, + "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": "是否显示坐标轴。" + } + }, + "additionalProperties": false + }, + "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" + ], + "additionalProperties": false + }, + "extremum_min": { + "type": "object", + "description": "最小极值配置，包含极值类型、极值。", + "properties": { + "type": { + "type": "string", + "enum": [ + "individual", + "group", + "custom" + ], + "description": "极值类型：individual=单个迷你图极值，group=同组内极值，custom=自定义。" }, - "negative_point": { - "additionalProperties": false, - "description": "负点配置，负数点的样式。", - "properties": { - "color": { - "description": "点的颜色。", - "type": "string" - }, - "visible": { - "description": "是否显示该点。", - "type": "boolean" - } - }, - "type": "object" + "value": { + "type": "number", + "description": "当 type='custom' 时生效的具体数值。" } }, - "type": "object" - }, - "series_color": { - "description": "主系列颜色，例如 \"#4472C4\"。", - "type": "string" - }, - "show_gradient": { - "description": "是否显示渐变效果。", - "type": "boolean" - }, - "show_radius": { - "description": "是否显示圆角，仅对柱形图和盈亏图生效。", - "type": "boolean" - }, - "theme_type": { - "description": "主题类型：pro、light、soft、brand、fresh。", - "enum": [ - "pro", - "light", - "soft", - "brand", - "fresh" - ], - "type": "string" - }, - "type": { - "description": "迷你图类型，可选值：line=折线图，column=柱形图，win_loss=盈亏图。", - "enum": [ - "line", - "column", - "win_loss" + "required": [ + "type" ], - "type": "string" + "additionalProperties": false } }, - "type": "object" + "additionalProperties": false }, "sparklines": { + "type": "array", "description": "迷你图项列表。create 时为待创建项（每项需 position + source/source_range）；update 时为待变更/新增项（每项需 sparkline_id；upsert=true 新增时需 position + source）；delete 时为待删除项（每项需 sparkline_id）。", "items": { - "additionalProperties": false, + "type": "object", "description": "单个迷你图项。", "properties": { + "sparkline_id": { + "type": "string", + "description": "迷你图 reference_id。create 时可选（不传系统生成）；update / delete 时必填。" + }, "position": { - "additionalProperties": false, + "type": "object", "description": "迷你图位置。create / update 时必填；delete 时省略。", "properties": { - "col": { - "description": "列索引，例如 \"A\"、\"B\"", - "type": "string" - }, "row": { - "description": "行索引（0-based）", + "type": "number", "minimum": 0, - "type": "number" + "description": "行索引（0-based）" + }, + "col": { + "type": "string", + "description": "列索引，例如 \"A\"、\"B\"" } }, "required": [ "row", "col" ], - "type": "object" + "additionalProperties": false }, "source": { - "description": "A1 范围字符串，表示数据来源，例如 \"Sheet1!A2:A10\"。create 必填（与 source_range 二选一）；update 仅在改源时传；delete 时省略。", - "type": "string" + "type": "string", + "description": "A1 范围字符串，表示数据来源，例如 \"Sheet1!A2:A10\"。create 必填（与 source_range 二选一）；update 仅在改源时传；delete 时省略。" }, "source_range": { - "additionalProperties": false, + "type": "object", "description": "结构化数据源范围（与 source 等价）。", "properties": { "range": { - "description": "数据源的 A1 引用区域", - "type": "string" + "type": "string", + "description": "数据源的 A1 引用区域" } }, "required": [ "range" ], - "type": "object" - }, - "sparkline_id": { - "description": "迷你图 reference_id。create 时可选（不传系统生成）；update / delete 时必填。", - "type": "string" + "additionalProperties": false } }, - "type": "object" - }, - "type": "array" + "additionalProperties": false + } } }, - "type": "object" + "additionalProperties": false } }, "+sparkline-update": { "properties": { - "additionalProperties": false, "description": "创建/更新/部分删除的迷你图属性。delete 时不传 sparklines 即删整组，传则删指定项。", + "type": "object", "properties": { "config": { - "additionalProperties": false, + "type": "object", "description": "迷你图样式配置, 相同 groupId 的迷你图共享相同的样式。", "properties": { - "axis": { - "additionalProperties": false, - "description": "坐标轴配置，包含坐标轴颜色、是否翻转、是否显示坐标轴。", - "properties": { - "color": { - "description": "坐标轴颜色。", - "type": "string" - }, - "reverse": { - "description": "是否翻转坐标轴方向。", - "type": "boolean" - }, - "visible": { - "description": "是否显示坐标轴。", - "type": "boolean" - } - }, - "type": "object" - }, - "contain_hidden_cells": { - "description": "隐藏的单元格数据是否参与绘制。", - "type": "boolean" + "theme_type": { + "type": "string", + "enum": [ + "pro", + "light", + "soft", + "brand", + "fresh" + ], + "description": "主题类型：pro、light、soft、brand、fresh。" }, - "empty_show_as": { - "description": "空单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。", + "non_num_show_as": { + "type": "string", "enum": [ "zero", "gap", "average" ], - "type": "string" - }, - "extremum_max": { - "additionalProperties": false, - "description": "最大极值配置，包含极值类型、极值。", - "properties": { - "type": { - "description": "极值类型，可选值：individual=单个迷你图极值，group=同组内极值，custom=自定义。", - "enum": [ - "individual", - "group", - "custom" - ], - "type": "string" - }, - "value": { - "description": "当 type='custom' 时生效的具体数值。", - "type": "number" - } - }, - "required": [ - "type" - ], - "type": "object" - }, - "extremum_min": { - "additionalProperties": false, - "description": "最小极值配置，包含极值类型、极值。", - "properties": { - "type": { - "description": "极值类型：individual=单个迷你图极值，group=同组内极值，custom=自定义。", - "enum": [ - "individual", - "group", - "custom" - ], - "type": "string" - }, - "value": { - "description": "当 type='custom' 时生效的具体数值。", - "type": "number" - } - }, - "required": [ - "type" - ], - "type": "object" - }, - "line_width": { - "description": "折线图线宽，可选值：1=1px，2=2px，3=3px，4=4px。", - "enum": [ - 1, - 2, - 3, - 4 - ], - "type": "number" + "description": "非数字单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。" }, - "non_num_show_as": { - "description": "非数字单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。", + "empty_show_as": { + "type": "string", "enum": [ "zero", "gap", "average" ], - "type": "string" + "description": "空单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。" + }, + "contain_hidden_cells": { + "type": "boolean", + "description": "隐藏的单元格数据是否参与绘制。" + }, + "series_color": { + "type": "string", + "description": "主系列颜色，例如 \"#4472C4\"。" }, "points": { - "additionalProperties": false, + "type": "object", "description": "特殊点样式配置，包含高点、低点、标记点、首点、尾点、负点。", "properties": { - "first_point": { - "additionalProperties": false, - "description": "首点配置，第一个数据点的样式。", + "last_point": { + "type": "object", + "description": "尾点配置，最后一个数据点的样式。", "properties": { "color": { - "description": "点的颜色。", - "type": "string" + "type": "string", + "description": "点的颜色。" }, "visible": { - "description": "是否显示该点。", - "type": "boolean" + "type": "boolean", + "description": "是否显示该点。" } }, - "type": "object" + "additionalProperties": false }, - "high_point": { - "additionalProperties": false, - "description": "高点配置，最高点的样式。", + "negative_point": { + "type": "object", + "description": "负点配置，负数点的样式。", "properties": { "color": { - "description": "点的颜色。", - "type": "string" + "type": "string", + "description": "点的颜色。" }, "visible": { - "description": "是否显示该点。", - "type": "boolean" + "type": "boolean", + "description": "是否显示该点。" } }, - "type": "object" + "additionalProperties": false }, - "last_point": { - "additionalProperties": false, - "description": "尾点配置，最后一个数据点的样式。", + "markers_point": { + "type": "object", + "description": "标记点配置，所有标记点的样式。", "properties": { "color": { - "description": "点的颜色。", - "type": "string" + "type": "string", + "description": "点的颜色。" }, "visible": { - "description": "是否显示该点。", - "type": "boolean" + "type": "boolean", + "description": "是否显示该点。" } }, - "type": "object" + "additionalProperties": false }, - "low_point": { - "additionalProperties": false, - "description": "低点配置，最低点的样式。", + "first_point": { + "type": "object", + "description": "首点配置，第一个数据点的样式。", "properties": { "color": { - "description": "点的颜色。", - "type": "string" + "type": "string", + "description": "点的颜色。" }, "visible": { - "description": "是否显示该点。", - "type": "boolean" + "type": "boolean", + "description": "是否显示该点。" } }, - "type": "object" + "additionalProperties": false }, - "markers_point": { - "additionalProperties": false, - "description": "标记点配置，所有标记点的样式。", + "high_point": { + "type": "object", + "description": "高点配置，最高点的样式。", "properties": { "color": { - "description": "点的颜色。", - "type": "string" + "type": "string", + "description": "点的颜色。" }, "visible": { - "description": "是否显示该点。", - "type": "boolean" + "type": "boolean", + "description": "是否显示该点。" } }, - "type": "object" + "additionalProperties": false }, - "negative_point": { - "additionalProperties": false, - "description": "负点配置，负数点的样式。", + "low_point": { + "type": "object", + "description": "低点配置，最低点的样式。", "properties": { "color": { - "description": "点的颜色。", - "type": "string" + "type": "string", + "description": "点的颜色。" }, "visible": { - "description": "是否显示该点。", - "type": "boolean" + "type": "boolean", + "description": "是否显示该点。" } }, - "type": "object" + "additionalProperties": false } }, - "type": "object" - }, - "series_color": { - "description": "主系列颜色，例如 \"#4472C4\"。", - "type": "string" - }, - "show_gradient": { - "description": "是否显示渐变效果。", - "type": "boolean" - }, - "show_radius": { - "description": "是否显示圆角，仅对柱形图和盈亏图生效。", - "type": "boolean" + "additionalProperties": false }, - "theme_type": { - "description": "主题类型：pro、light、soft、brand、fresh。", + "line_width": { + "type": "number", "enum": [ - "pro", - "light", - "soft", - "brand", - "fresh" + 1, + 2, + 3, + 4 ], - "type": "string" + "description": "折线图线宽，可选值：1=1px，2=2px，3=3px，4=4px。" }, "type": { - "description": "迷你图类型，可选值：line=折线图，column=柱形图，win_loss=盈亏图。", + "type": "string", "enum": [ "line", "column", "win_loss" ], - "type": "string" + "description": "迷你图类型，可选值：line=折线图，column=柱形图，win_loss=盈亏图。" + }, + "axis": { + "type": "object", + "description": "坐标轴配置，包含坐标轴颜色、是否翻转、是否显示坐标轴。", + "properties": { + "color": { + "type": "string", + "description": "坐标轴颜色。" + }, + "reverse": { + "type": "boolean", + "description": "是否翻转坐标轴方向。" + }, + "visible": { + "type": "boolean", + "description": "是否显示坐标轴。" + } + }, + "additionalProperties": false + }, + "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" + ], + "additionalProperties": false + }, + "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" + ], + "additionalProperties": false } }, - "type": "object" + "additionalProperties": false }, "sparklines": { + "type": "array", "description": "迷你图项列表。create 时为待创建项（每项需 position + source/source_range）；update 时为待变更/新增项（每项需 sparkline_id；upsert=true 新增时需 position + source）；delete 时为待删除项（每项需 sparkline_id）。", "items": { - "additionalProperties": false, + "type": "object", "description": "单个迷你图项。", "properties": { + "sparkline_id": { + "type": "string", + "description": "迷你图 reference_id。create 时可选（不传系统生成）；update / delete 时必填。" + }, "position": { - "additionalProperties": false, + "type": "object", "description": "迷你图位置。create / update 时必填；delete 时省略。", "properties": { - "col": { - "description": "列索引，例如 \"A\"、\"B\"", - "type": "string" - }, "row": { - "description": "行索引（0-based）", + "type": "number", "minimum": 0, - "type": "number" + "description": "行索引（0-based）" + }, + "col": { + "type": "string", + "description": "列索引，例如 \"A\"、\"B\"" } }, "required": [ "row", "col" ], - "type": "object" + "additionalProperties": false }, "source": { - "description": "A1 范围字符串，表示数据来源，例如 \"Sheet1!A2:A10\"。create 必填（与 source_range 二选一）；update 仅在改源时传；delete 时省略。", - "type": "string" + "type": "string", + "description": "A1 范围字符串，表示数据来源，例如 \"Sheet1!A2:A10\"。create 必填（与 source_range 二选一）；update 仅在改源时传；delete 时省略。" }, "source_range": { - "additionalProperties": false, + "type": "object", "description": "结构化数据源范围（与 source 等价）。", "properties": { "range": { - "description": "数据源的 A1 引用区域", - "type": "string" + "type": "string", + "description": "数据源的 A1 引用区域" } }, "required": [ "range" ], - "type": "object" - }, - "sparkline_id": { - "description": "迷你图 reference_id。create 时可选（不传系统生成）；update / delete 时必填。", - "type": "string" + "additionalProperties": false } }, - "type": "object" - }, - "type": "array" + "additionalProperties": false + } } }, - "type": "object" + "additionalProperties": false } } } diff --git a/shortcuts/sheets/lark_sheet_write_cells.go b/shortcuts/sheets/lark_sheet_write_cells.go index 2cd2eff9a..c44970e8d 100644 --- a/shortcuts/sheets/lark_sheet_write_cells.go +++ b/shortcuts/sheets/lark_sheet_write_cells.go @@ -340,7 +340,8 @@ func dropdownSetInput(runtime flagView, token, sheetID, sheetName string) (map[s // --colors -> highlight_colors (string array, hex) // --highlight -> enable_highlight (bool) // -// --colors length must equal --options length when both are set. +// --colors length may be shorter than --options (server cycles remaining +// options through a built-in 10-color palette) but must not exceed it. func buildDropdownValidation(runtime flagView) (map[string]interface{}, error) { options, err := requireJSONArray(runtime, "options") if err != nil { @@ -355,8 +356,8 @@ func buildDropdownValidation(runtime flagView) (map[string]interface{}, error) { if err != nil { return nil, err } - if len(colors) != len(options) { - return nil, common.FlagErrorf("--colors length (%d) must equal --options length (%d)", len(colors), len(options)) + if len(colors) > len(options) { + return nil, common.FlagErrorf("--colors length (%d) must not exceed --options length (%d)", len(colors), len(options)) } dv["highlight_colors"] = colors } @@ -370,8 +371,8 @@ func buildDropdownValidation(runtime flagView) (map[string]interface{}, error) { } // validateDropdownOptionsColors validates --options is a JSON array and that -// --colors (when set) has matching length. Returns the options length so -// callers can size their cells matrix at Validate time without re-parsing. +// --colors (when set) is no longer than --options. Returns the options length +// so callers can size their cells matrix at Validate time without re-parsing. func validateDropdownOptionsColors(runtime flagView) (int, error) { options, err := requireJSONArray(runtime, "options") if err != nil { @@ -382,8 +383,8 @@ func validateDropdownOptionsColors(runtime flagView) (int, error) { if err != nil { return 0, err } - if len(colors) != len(options) { - return 0, common.FlagErrorf("--colors length (%d) must equal --options length (%d)", len(colors), len(options)) + if len(colors) > len(options) { + return 0, common.FlagErrorf("--colors length (%d) must not exceed --options length (%d)", len(colors), len(options)) } } return len(options), nil diff --git a/shortcuts/sheets/lark_sheet_write_cells_test.go b/shortcuts/sheets/lark_sheet_write_cells_test.go index 5e10d1a25..aef33e272 100644 --- a/shortcuts/sheets/lark_sheet_write_cells_test.go +++ b/shortcuts/sheets/lark_sheet_write_cells_test.go @@ -173,22 +173,45 @@ func TestDropdownSet_CellsShape(t *testing.T) { } } -// TestDropdownSet_ColorsLengthMismatch checks the early Validate-time -// error when --colors length doesn't match --options. -func TestDropdownSet_ColorsLengthMismatch(t *testing.T) { +// TestDropdownSet_ColorsLongerThanOptions checks the early Validate-time +// error when --colors length exceeds --options. Equal-or-shorter lengths +// are accepted (server cycles the rest through a built-in palette). +func TestDropdownSet_ColorsLongerThanOptions(t *testing.T) { t.Parallel() _, stderr, err := runShortcutCapturingErr(t, DropdownSet, []string{ "--url", testURL, "--sheet-id", testSheetID, "--range", "A2:A4", - "--options", `["a","b","c"]`, - "--colors", `["#FFE699","#bff7d9"]`, + "--options", `["a","b"]`, + "--colors", `["#FFE699","#bff7d9","#ffb3b3"]`, "--dry-run", }) if err == nil { - t.Fatal("expected --colors length mismatch error, got nil") + t.Fatal("expected --colors length error, got nil") + } + if !strings.Contains(stderr, "must not exceed --options length") && !strings.Contains(err.Error(), "must not exceed --options length") { + t.Errorf("error message missing length-overflow hint:\nerr=%v\nstderr=%s", err, stderr) } - if !strings.Contains(stderr, "must equal --options length") && !strings.Contains(err.Error(), "must equal --options length") { - t.Errorf("error message missing length-mismatch hint:\nerr=%v\nstderr=%s", err, stderr) +} + +// TestDropdownSet_ColorsShorterAccepted verifies the partial-colors case: +// fewer colors than options is legal — array is forwarded as-is and the +// server fills remaining slots from its default palette. +func TestDropdownSet_ColorsShorterAccepted(t *testing.T) { + t.Parallel() + body := parseDryRunBody(t, DropdownSet, []string{ + "--url", testURL, "--sheet-id", testSheetID, + "--range", "A2:A4", + "--options", `["a","b","c","d"]`, + "--colors", `["#FFE699","#bff7d9"]`, + }) + input := decodeToolInput(t, body, "set_cell_range") + cells, _ := input["cells"].([]interface{}) + row0, _ := cells[0].([]interface{}) + cell, _ := row0[0].(map[string]interface{}) + dv, _ := cell["data_validation"].(map[string]interface{}) + colors, _ := dv["highlight_colors"].([]interface{}) + if len(colors) != 2 { + t.Errorf("highlight_colors length = %d, want 2 (forwarded as-is)", len(colors)) } } diff --git a/skills/lark-sheets/references/lark-sheets-batch-update.md b/skills/lark-sheets/references/lark-sheets-batch-update.md index ba3160e0b..97fcbc569 100644 --- a/skills/lark-sheets/references/lark-sheets-batch-update.md +++ b/skills/lark-sheets/references/lark-sheets-batch-update.md @@ -115,7 +115,7 @@ _单元格边框配置，含 top/bottom/left/right 四个方向，每个方向 ### `+dropdown-update` `--options` -_列表选项_ +_列表选项（type='list' 时必填）_ **数组项**（类型 string）： - 标量：string diff --git a/skills/lark-sheets/references/lark-sheets-chart.md b/skills/lark-sheets/references/lark-sheets-chart.md index b477e7742..d83555a3f 100644 --- a/skills/lark-sheets/references/lark-sheets-chart.md +++ b/skills/lark-sheets/references/lark-sheets-chart.md @@ -147,9 +147,9 @@ _公共四件套 · 系统：`--yes`、`--dry-run`_ _创建/更新的图表属性_ **顶层字段**： -- `position` (object) — 必填 { row: number, col: string } +- `position` (object?) — 必填 { row: number, col: string } - `offset` (object?) — 可选 { row_offset?: number, col_offset?: number } -- `size` (object) — 必填 { width: number, height: number } +- `size` (object?) — 必填 { width: number, height: number } - `snapshot` (object?) — 图表快照配置 { title?: object, subTitle?: object, style?: object, legend?: oneOf, plotArea?: object, …共 6 项 } ## Examples diff --git a/skills/lark-sheets/references/lark-sheets-write-cells.md b/skills/lark-sheets/references/lark-sheets-write-cells.md index a4e32f6b2..4608bdeaf 100644 --- a/skills/lark-sheets/references/lark-sheets-write-cells.md +++ b/skills/lark-sheets/references/lark-sheets-write-cells.md @@ -4,7 +4,7 @@ 1. **明确写入边界**：写入前必须能回答"目标 range 的起止行列号是多少？是否落在用户授权范围内？"。除用户明示要修改的区域外，禁止扩张到原数据列以外或新建 Sheet。 2. **完整性断言**：批量写入前先把"预期写入条数"硬编码到代码里（如要填 106 条翻译 → `expected = 106`），写完后回读断言 `actual == expected`。少于预期就继续写，禁止交付半成品。 -3. **回读抽样校验**：写完关键值 / 公式后，用 `+csv-get` 或 `+cells-get` 重新读取写入区域，至少抽样 3-5 个代表性单元格（首 / 中 / 末），核对值与预期一致（与 本地脚本 计算的预期值对照）。公式特定的"先验证模板再 copy_to_range / 修完再读回"细则见下方相关章节。 +3. **回读抽样校验**：写完关键值 / 公式后，用 `+csv-get` 或 `+cells-get` 重新读取写入区域，至少抽样 3-5 个代表性单元格（首 / 中 / 末），核对值与预期一致（与本地脚本计算的预期值对照）。公式特定的"先验证模板再 --copy-to-range / 修完再读回"细则见下方相关章节。 ## 新增列 / 新增行的样式继承（防止视觉风格不一致） @@ -17,7 +17,7 @@ 3. `cell_styles.number_format`（小数位 / 千分位 / 百分比 / 日期格式）—— 漏继承会导致同列数值格式混乱 4. `cell_styles.background_color`（背景色） 5. `border_styles`（四边框） -6. **`merged_cells`（合并范围）**——续写场景必查（高频致命错误）：用 `+sheet-info --info_type=merged_cells_infos` 读原数据区域的合并信息。**原行有跨列合并**（如标题行 `A1:G1` 合并）时，新行**必须**用 `+cells-{merge|unmerge}` 工具复制相同合并模式到新行（如续写第 3 个周报块的标题行 `A23:G23` 必须合并）。仅传 cells 数组的 5 类样式不够——合并范围要单独靠 `+cells-{merge|unmerge}` 工具落地（典型反例：续写多周记录表时，新增周次的标题行未合并，视觉上与原前几周风格不一致） +6. **`merged_cells`（合并范围）**——续写场景必查（高频致命错误）：用 `+sheet-info --include merges` 读原数据区域的合并信息。**原行有跨列合并**（如标题行 `A1:G1` 合并）时，新行**必须**用 `+cells-{merge|unmerge}` 工具复制相同合并模式到新行（如续写第 3 个周报块的标题行 `A23:G23` 必须合并）。仅传 cells 数组的 5 类样式不够——合并范围要单独靠 `+cells-{merge|unmerge}` 工具落地（典型反例：续写多周记录表时，新增周次的标题行未合并，视觉上与原前几周风格不一致） **采样模板的正确做法**： - 表头新列 → 读相邻表头单元格（如新加 D1 → 读 A1/B1/C1 任一） @@ -44,59 +44,56 @@ ## 使用场景 -写入。为一块单元格区域设置值、公式、批注/备注和/或格式。也支持通过 `rich_text` 中 `type: "embed-image"` 在单元格内嵌入图片（单元格图片）。关键：数组维度必须严格匹配——`cells` 二维数组必须与 `range` 的行列维度完全一致，range 是闭区间，否则会触发 `InvalidCellRangeError`。计算示例：区域 `A1:D3` = 3 行 × 4 列 = `[[r1c1,r1c2,r1c3,r1c4],[r2c1,r2c2,r2c3,r2c4],[r3c1,r3c2,r3c3,r3c4]]`；区域 `A41:N48` = 8 行 × 14 列 = 8 个数组且每个数组 14 个单元；单个单元格 `A1` = `[[cell]]`；单列区域 `B5:B7` = `[[cell1],[cell2],[cell3]]`。空单元请使用 `{}`。**如果填写的区域存在大量重复内容，务必优先使用 `copy_to_range` 字段复制，可大幅减少 `cells` 长度。** +写入。为一块单元格区域设置值、公式、批注/备注和/或格式。也支持通过 `rich_text` 中 `type: "embed-image"` 在单元格内嵌入图片（单元格图片）。关键：数组维度必须严格匹配——`cells` 二维数组必须与 `range` 的行列维度完全一致，range 是闭区间，否则会触发 `InvalidCellRangeError`。计算示例：区域 `A1:D3` = 3 行 × 4 列 = `[[r1c1,r1c2,r1c3,r1c4],[r2c1,r2c2,r2c3,r2c4],[r3c1,r3c2,r3c3,r3c4]]`；区域 `A41:N48` = 8 行 × 14 列 = 8 个数组且每个数组 14 个单元；单个单元格 `A1` = `[[cell]]`；单列区域 `B5:B7` = `[[cell1],[cell2],[cell3]]`。空单元请使用 `{}`。**如果填写的区域存在大量重复内容，务必优先使用 `--copy-to-range` 字段复制，可大幅减少 `cells` 长度。** > **单元格图片 vs 浮动图片**： > - **单元格图片**（本工具）：图片嵌入在单元格内部，属于单元格内容，随单元格移动。通过 `rich_text` 中 `type: "embed-image"` 写入。 -> - **浮动图片**：图片悬浮在单元格上方，可自由定位和调整大小，不属于单元格内容。→ 使用 lark_sheet_float_image Skill。 +> - **浮动图片**：图片悬浮在单元格上方，可自由定位和调整大小，不属于单元格内容。→ 使用 lark-sheets-float-image。 高频模式（**必须遵守，禁止逐行写入替代**）： -- 整列公式：先在 `H2` 写一个公式，再用 `copy_to_range: "H2:H100"` 或 `copy_to_range: "H:H"` 向下填充。**禁止对每一行单独调用 `+cells-set` 写入相同结构的公式** -- 整列格式：先在 `J1` 写一个带样式的模板单元格，再用 `copy_to_range: "J:J"` -- 首行样式：先在 `A1` 写一个模板单元格，再用 `copy_to_range: "1:1"` -- 用户说”这列 / 整列 / 这行 / 首行 / 向下复制”时，**必须**使用模板单元格 + `copy_to_range` -- 多区域写入相同格式/公式结构时，优先写一个模板，再用 `copy_to_range` 复制到所有目标区域 +- 整列公式：先在 `H2` 写一个公式，再用 `--copy-to-range "H2:H100"` 或 `--copy-to-range "H:H"` 向下填充。**禁止对每一行单独调用 `+cells-set` 写入相同结构的公式** +- 整列格式：先在 `J1` 写一个带样式的模板单元格，再用 `--copy-to-range "J:J"` +- 首行样式：先在 `A1` 写一个模板单元格，再用 `--copy-to-range "1:1"` +- 用户说”这列 / 整列 / 这行 / 首行 / 向下复制”时，**必须**使用模板单元格 + `--copy-to-range` +- 多区域写入相同格式/公式结构时，优先写一个模板，再用 `--copy-to-range` 复制到所有目标区域 -⚠️ **逐行写入公式是最常见的致命错误**：对每一行单独调用 `+cells-set` 写入公式（如调用 26 次），会快速耗尽轮次上限导致操作不完整。正确做法是 1 次模板写入 + 1 次 `copy_to_range` = 2 次调用完成。 +⚠️ **逐行写入公式是常见低效写法**：对每一行单独调用 `+cells-set` 写公式（如 26 次）既慢又易错，且不会自动平移公式引用。正确做法是 1 次模板写入 + 1 次 `--copy-to-range`（公式引用自动平移）。 -💡 **写入公式前先按迁移规则改写**：如果公式来自 Excel 或包含数组场景，先读取并遵循 `lark-sheets-formula-translation` skill 的规则完成改写，再把最终公式写入 `formula` 字段。 +💡 **写入公式前先按迁移规则改写**：如果公式来自 Excel 或包含数组场景，先读取并遵循 `lark-sheets-formula-translation` 的规则完成改写，再把最终公式写入 `formula` 字段。 💡 **内容与样式分离写入（推荐）**：当需要同时写入内容和样式时，`cells` 中每个单元格都带上 `cell_styles` / `border_styles` 会导致入参非常冗长。由于同一区域的样式通常高度重复（如整列统一背景色、统一边框），推荐拆成两步： 1. **先写内容**：`+cells-set` 只传 `value` / `formula`，不带样式，`cells` 入参精简 -2. **再批量刷样式**：对区域中的一个单元格写入目标样式作为模板，再用 `copy_to_range` 将样式扩展到整列 / 整行 / 整个区域（`copy_to_range` 会复制值、公式和样式，所以模板单元格应已包含正确的值） +2. **再批量刷样式**：对区域中的一个单元格写入目标样式作为模板，再用 `--copy-to-range` 将样式扩展到整列 / 整行 / 整个区域（`--copy-to-range` 会复制值、公式和样式，所以模板单元格应已包含正确的值） 示例：要对 A2:A100 写入数据并统一设置蓝色背景 + 边框： ``` Step 1: `+cells-set` — range="A2:A100", cells 只含 value（无样式，入参短） -Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styles（单个模板）, copy_to_range="A2:A100" +Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styles（单个模板）, --copy-to-range="A2:A100" ``` 这比在 99 个单元格中都重复写样式 JSON 高效得多。 -💡 **大批量数据分批写入（推荐）**：当需要写入大量行（如几十行以上）时，不要试图在一次调用中生成全部 `cells` 数据——`cells` 数组过大会导致模型生成内容过长而超时。应将数据拆分为多批，每批 20-50 行，分多次调用 `+cells-set` 逐批生成并写入（如先写 `A2:D21`，再写 `A22:D41`，依此类推）。每次调用只需生成当前批次的数据，控制单次生成量，避免超时。 +💡 **大批量数据分批写入（推荐）**：当需要写入大量行（如几十行以上）时，不要试图在一次调用中生成全部 `cells` 数据——`cells` 数组过大会让单次生成的内容过长，容易出错或被截断。应将数据拆分为多批，每批 20-50 行，分多次调用 `+cells-set` 逐批生成并写入（如先写 `A2:D21`，再写 `A22:D41`，依此类推）。每次只生成当前批次的数据，控制单次生成量。 注意： - 不要把 `cells` 写成字符串化 JSON -- 如果目标区域中已有值、公式或样式需要被覆盖，显式设置 `allow_overwrite=true` +- `+cells-set` 默认即覆盖非空 cell（`--allow-overwrite` 默认 true）；若要**保护**非空 cell 不被覆盖，显式传 `--allow-overwrite=false`（遇非空 cell 报错） - 若目标区域涉及合并单元格，不要向合并区域中的非左上角单元格写入数据；如需写入，应改写合并区域左上角单元格，或先调整/取消合并区域 - **构造 `range` 时行号必须基于逻辑行号**：如果之前通过 `+csv-get` 读取了数据，CSV 中被双引号包裹的多行字段（如 `"2026年3月2日\n星期一"`）是**一个单元格**，不是两行。写入时的行号必须按逻辑记录计算，不能按物理换行符计数，否则 `range` 会整体偏移导致写入到错误位置 -⚠️ **"样式与原表一致"必须包含 `border_styles`（高频致命错误）**：当用户说"样式和原表一致"、"保持原表格式"、"边框继承"等要求时，cells 里的 `cell_styles` **不能只传 `font_size` / `horizontal_alignment` / `vertical_alignment`**——这几项只覆盖字体和对齐，**不包含边框**。边框必须用独立的 `border_styles` 字段传（或在源 cell 用 `+cells-get` 读出来再原样复制）。 -- **反模式**：`cells=[[{cell_styles:{font_size:16, horizontal_alignment:"center", vertical_alignment:"middle"}}]]`（字体+对齐都有，但**新 cell 仍然没边框**，视觉上与原表断裂） -- **正确做法**：`cell_styles` + `border_styles` 一起传，`border_styles` 覆盖 top/bottom/left/right 四条边（或至少 data 区该加的几条），确保视觉连续 -- 特别是**新列/新行**场景，新 cell 底子里本来就没边框，如果不显式传 `border_styles`，copy_to_range 复制的模板也没边框 → 整列/整行无边框 +> 用户说"样式和原表一致 / 保持原表格式 / 边框继承"时同理：`cell_styles` 只覆盖字体和对齐、**不含边框**，边框必须用独立 `border_styles` 字段传——完整继承清单见上方「新增列 / 新增行的样式继承」。 -⚠️ **公式写入必须自己校验结果（后端不会报语法错）**：`+cells-set` 写公式时，即便公式有括号不配对（如 `=IFERROR(VALUE(REGEXEXTRACT(D5, "\d+"))), 0)` 比 IFERROR 多一个 `)`）或函数名拼错（`=UNIQUE(...)` 飞书不支持），**后端工具也会返回 `updated_cells_count=N, rc=0` 的"成功"**——错误会静默写进单元格显示为 `#VALUE!` / `#NAME?` / `#REF!`。因此： +⚠️ **公式写入必须自己校验结果（后端不会报语法错）**：`+cells-set` 写公式时，即便公式有括号不配对（如 `=IFERROR(VALUE(REGEXEXTRACT(D5, "\d+"))), 0)` 比 IFERROR 多一个 `)`）或用了飞书不支持的函数（如 `GOOGLETRANSLATE` / `CUBEVALUE`），**后端工具也会返回 `updated_cells_count=N, rc=0` 的"成功"**——错误会静默写进单元格显示为 `#VALUE!` / `#NAME?` / `#REF!`。因此： 1. **写完立即读回**：`+cells-set` 后紧跟 `+csv-get`（或 `+cells-get`）读目标范围前几行，检查是否出现 `#VALUE!` / `#NAME?` / `#REF!` / `#N/A` / `#DIV/0!` / `#NUM!` -2. **看到 `#` 开头的错误值**立即修公式：`#NAME?` 多半是函数名拼错或飞书不支持（UNIQUE/DISTINCT 等）；`#VALUE!` 多半是类型不匹配或括号错位；`#REF!` 是引用错误；`~CIRCULAR~REF~` 是循环引用（公式引用了自身或会闭环） -3. **`copy_to_range` 扩展前先验证模板**：模板单元格公式自己都算错，`copy_to_range` 复制到 100 行就是 100 个错误 -4. **飞书不支持的函数**：`UNIQUE` / `DISTINCT` / `FILTER`（部分）—— 对应"去重"场景改用透视表（`+pivot-{create|update|delete}`，值字段聚合方式选 count） +2. **看到 `#` 开头的错误值**立即修公式：`#NAME?` 多半是函数名拼错或用了飞书不支持的函数（如 `GOOGLETRANSLATE` / CUBE 系列；注意 `UNIQUE` / `FILTER` / `SPLIT` 飞书是支持的）；`#VALUE!` 多半是类型不匹配或括号错位；`#REF!` 是引用错误；`~CIRCULAR~REF~` 是循环引用（公式引用了自身或会闭环） +3. **`--copy-to-range` 扩展前先验证模板**：模板单元格公式自己都算错，`--copy-to-range` 复制到 100 行就是 100 个错误 +4. **去重 / 筛选函数**：飞书**支持** `UNIQUE` / `FILTER` / `SPLIT`（原生数组函数，详见 `lark-sheets-formula-translation`），可直接用；`DISTINCT` 不是飞书函数，去重用 `UNIQUE`。大数据量去重 / 分组也可用透视表（`+pivot-{create|update|delete}`，值字段聚合方式选 count） 5. **循环引用预检（高频致命错误）**：写聚合公式（SUM / AVERAGE / COUNT 等）前必须明确**引用范围不包含目标单元格自身或其传递依赖**。典型反例：在 C3 写 `=SUMIF(B:B,LEFT(B3,9)&"*",C:C)`，B 列匹配 B3 前 9 位时 C3 自己也命中，导致 C3 自引用 → `~CIRCULAR~REF~`。修法：用辅助列 / 显式排除自身（`SUMIFS(C:C, B:B, ..., A:A, "<>"&A3)`）/ 缩小范围避开自己 -6. **REGEX 模式覆盖率验证**：公式里的 `REGEXEXTRACT` / `REGEXMATCH` / `REGEXREPLACE` 等正则模式落地前必须用 本地脚本 在源列上跑一遍命中率统计（`df[col].str.contains(pattern).mean()`）；命中率 < 100% 时必须扩展 pattern 或加多分支（IFS / 多个 IFERROR 串联）兜底，**禁止**只覆盖样本前 N 行就交付（典型反例：用 `REGEXEXTRACT(D5,"长(\d+)")` 只匹配带"长"前缀的尺寸文本，对"宽×高"、"×"、"*"等其它分隔符直接漏匹配） +6. **REGEX 模式覆盖率验证**：公式里的 `REGEXEXTRACT` / `REGEXMATCH` / `REGEXREPLACE` 等正则模式落地前必须用本地脚本在源列上跑一遍命中率统计（`df[col].str.contains(pattern).mean()`）；命中率 < 100% 时必须扩展 pattern 或加多分支（IFS / 多个 IFERROR 串联）兜底，**禁止**只覆盖样本前 N 行就交付（典型反例：用 `REGEXEXTRACT(D5,"长(\d+)")` 只匹配带"长"前缀的尺寸文本，对"宽×高"、"×"、"*"等其它分隔符直接漏匹配） 7. **公式范围与用户指令字面对齐**：用户说"对 F 至 L 列求和"就必须写 `SUM(F2:L2)` 或 `F2+G2+H2+I2+J2+K2+L2`，**不能漏列、多列、错列**。写完用 `+cells-get` 拿回 `formula` 字符串，与用户原话逐字对照（参与求和的列名一致 / 起止列号一致 / 运算符一致），不一致就是违规 -⚠️ **收到 `formula_errors` 反馈后不要只打补丁（高频致命错误）**：`+cells-set` 返回值里若出现 `formula_errors: [{cell, formula, error_type, detail}]`，说明某些 cell 公式编译失败（`error_type=compile_failed` 通常是函数语法错如 `SPLIT(x)[1]` 飞书不支持；`non_formula` 是 `=` 开头但解析不通过）。此时**禁止只聚焦修报错点的局部语法**（如仅把 `[1]` 换成 `INDEX(..,1)`），必须： +⚠️ **收到 `formula_errors` 反馈后不要只打补丁（高频致命错误）**：`+cells-set` 返回值里若出现 `formula_errors: [{cell, formula, error_type, detail}]`，说明某些 cell 公式编译失败（`error_type=compile_failed` 通常是函数语法错如 `SPLIT(x)[1]` 的下标取值飞书不支持（SPLIT 本身支持，取第 N 项用 `INDEX(SPLIT(...),N)`）；`non_formula` 是 `=` 开头但解析不通过）。此时**禁止只聚焦修报错点的局部语法**（如仅把 `[1]` 换成 `INDEX(..,1)`），必须： 1. **重新审视整条公式的完整性**：被 formula_errors 标出的那一行，公式除了下标语法错，还可能有其他先天缺陷（字符清洗不全、IFERROR 兜底漏条件、引用列写错），修完语法错后立即整体复核 2. **同步对称修复所有相似列**：如果同一任务涉及多列相似处理（如"算 H 列面积"用 D 列尺寸、"算 I 列面积"用 E 列尺寸），**修完一列必须把同样的清洗/兜底逻辑同步到所有相似列**，禁止出现 H 列用 `SUBSTITUTE(长)+SUBSTITUTE(高)+SUBSTITUTE(×)` 而 I 列只用 `SUBSTITUTE(×)` 这种不对称处理——会导致一列编译通过有值、另一列编译通过但 IFERROR 全返回空，用户看到的是"数据为空"而非"公式错" @@ -109,7 +106,7 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl - **语义信号**（二选一）：用户 prompt 含"合计/汇总/总计/统计/各科平均分/最下面加一行算…/底部总计"等意图词；或上下文明确是"表尾追加一行做聚合" - **结构信号**：新行全行都在做聚合（含 `=SUM/AVERAGE/COUNT/MAX/MIN/SUBTOTAL(...)`，支持 IFERROR 包裹），**不是**单个 cell 算个参考值或每行都算的派生列 -满足上述时，**不要在本 skill 里猜样式**，直接去读 `lark-sheets-visual-standards` 的"汇总行规范"章节，按那里的规则配齐 `font.bold / horizontal_alignment / background_color / border_styles`。 +满足上述时，**不要在本 skill 里猜样式**，直接去读 `lark-sheets-visual-standards` 的「场景一 → 1A. 添加汇总行 / 表头行」章节，按那里的样式要点配齐 `font.bold / horizontal_alignment / background_color / border_styles`。 反例（**不是**汇总行，禁止自动加粗）： - 用户说"在 H5 帮我算个 AVERAGE 参考"→ 单 cell 计算 @@ -118,35 +115,10 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl **正确做法**（二选一）： -**做法 A（推荐）：两步走——先铺样式、再覆内容** +- **做法 A（推荐）**：按上方「内容与样式分离写入」两步法——先用模板单元格 + `--copy-to-range` 铺**完整样式**（`cell_styles` + `border_styles` 都要，不能只铺 border，否则新行字体 / 对齐 / 背景色全裸奔），再单独 `+cells-set` 写 value / formula。汇总行的 `cell_styles` 要点（bold / 背景色 / 上边框）见 `lark-sheets-visual-standards` 的「场景一 → 1A. 添加汇总行 / 表头行」。 +- **做法 B**：一次写入，但每个 cell（含空白格）都显式带 `cell_styles` + `border_styles`，**不能用 `{}`**。 -``` -Step 1: 用模板单元格 + copy_to_range 铺"完整样式"（不是只铺 border）到新区域 - `+cells-set` — range="A11", cells=[[{ - border_styles: {...}, - cell_styles: { /* 按行性质填充：数据行继承数据区样式；汇总行见 lark_sheet_visual_standards */ } - }]], copy_to_range="A11:H11" - -Step 2: 再用 `+cells-set` 单独写具体 value/formula（不再传样式，避免覆盖） - `+cells-set` — range="A11", cells=[[{value: "平均分"}]] - `+cells-set` — range="C11:F11", cells=[[{formula: "=AVERAGE(C2:C10)"}, {formula: "=AVERAGE(D2:D10)"}, ...]] -``` - -⚠️ **Step 1 `cell_styles` 禁止留空**：只铺 border、不铺 `cell_styles`，等于新行从格式上"裸奔"——没字体、没对齐、没背景色。如果新行是汇总行，这意味着 bold 丢失，用户感受"没做样式"。Step 1 的 `cell_styles` 要么继承源区块（`+cells-get` 读相邻已有行样式后复用），要么按汇总行规范（见 `lark-sheets-visual-standards`）配齐。 - -**做法 B：一次写入但每个 cell 都显式带样式** - -``` -`+cells-set` — range="A11:H11", cells=[[ - {value: "平均分", cell_styles: {...}, border_styles: {...}}, - {value: "", cell_styles: {...}, border_styles: {...}}, ← B11 不能是 {}，要显式带 border - {formula: "=AVERAGE(C2:C10)", cell_styles: {...}, border_styles: {...}}, - {formula: "=AVERAGE(D2:D10)", cell_styles: {...}, border_styles: {...}}, - ... -]] -``` - -**判断是不是"新行"**：`+csv-get` 返回的 `current_region` 是 `A1:H10`，你要写入的 range 是 `A11:H11`（超出 `current_region` 右/下边界），就是新行——必须按上述做法处理边框。 +**判断是不是"新行"**：写入 range 超出 `+csv-get` 返回的 `current_region` 右 / 下边界（如 `current_region=A1:H10`、写 `A11:H11`）即新行，必须按上述做法补边框。 ## 工具选择 @@ -154,7 +126,7 @@ Step 2: 再用 `+cells-set` 单独写具体 value/formula（不再传样式， | 场景 | 用这个 shortcut | 原因 | |------|----------------|------| -| 模型手里已经有 CSV 文本（小规模手动构造、从 `+csv-get` 取到后简单加工） | `+csv-put` | 直接传 CSV 文本 + start_cell，不用自己拼二维 cells 数组；必要时自动扩容行列 | +| 模型手里已经有 CSV 文本（小规模手动构造、从 `+csv-get` 取到后简单加工） | `+csv-put` | 直接传 CSV 文本 + `--start-cell`，不用自己拼二维 cells 数组；必要时自动扩容行列 | | 写入含公式、样式、批注、图片、数据校验等任意富写入 | `+cells-set` | 唯一支持完整字段的 shortcut | | 只改已有 cell 的样式，不动 value/formula | `+cells-set-style` | 拍平 10 个样式字段为独立 flag；不触发不必要的值写入 | | 单 cell 嵌入图片 | `+cells-set-image` | 比 `+cells-set` 参数更简短 | @@ -164,7 +136,7 @@ Step 2: 再用 `+cells-set` 单独写具体 value/formula（不再传样式， ⚠️ `+csv-put` 只写纯值，**不会**携带公式/样式/批注/图片；公式字符串以 `=` 开头会被当作字面量文本落地。如果数据里需要公式或样式，**必须**用 `+cells-set`（或"写值 + 补样式"两步法）。 -⚠️ 大数据回写走"`+csv-get --max-rows N` 分批读到本地 + 本地脚本处理 + `+csv-put` 分批回写"。 +⚠️ 大数据回写走"`+csv-get` 按 `--range` 行窗口分批读到本地 + 本地脚本处理 + `+csv-put` 分批回写"。 ## Shortcuts @@ -187,7 +159,7 @@ _公共四件套 · 系统：`--dry-run`_ | `--range` | string | required | 写入区域（A1 格式） | | `--cells` | string + File + Stdin（复合 JSON） | required | JSON：2D 数组 `[[{cell},...],...]`，维度与 `--range` 完全一致；每个 cell 可含 `value` / `formula` / `cell_styles` / `note` / `rich_text`（含 `type="embed-image"` 单元格嵌图）等，完整字段跑 `--print-schema` | | `--allow-overwrite` | bool | optional | 允许覆盖非空 cell（默认 true）；设为 false 时遇非空 cell 报错 | -| `--max-cells` | int | optional | 防爆，默认 50000 | +| `--max-cells` | int | optional | 防爆，默认 50000（隐藏 flag：不在 `--help` 列出，但可正常传入） | | `--copy-to-range` | string | optional | 复制范围（A1 表示法）：把 --range 中 --cells 写入的内容（值/公式/样式，取决于实际传入字段）复制到该区域，公式引用自动平移（如 C2=B2 → C3=B3）。适合先写一行/一块模板再扩展填充整列/整区域（如 --range A1:G1 写模板、--copy-to-range A1:G100 填充 100 行）。支持整行 3:6、整列 C:E、到列尾 D3:D、到行尾 D3:3；支持英文逗号分隔多个目标区域，如 C1:D2,E5:F6 | ### `+cells-set-style` @@ -243,30 +215,30 @@ _公共四件套 · 系统：`--dry-run`_ ## Schemas -> 复合 JSON flag（如 `--cells` / `--properties` / `--operations` / `--border-styles` / `--sort-keys`）的字段速查：只列顶层字段 + 一层嵌套结构。深层结构看 `## Examples` 段的真实示例；要拿完整 JSON Schema 跑 `lark-cli sheets --print-schema --flag-name `。先 `--print-schema`（不带 `--flag-name`）会列出该 shortcut 所有可查询的 flag。 +> 复合 JSON flag 字段速查（只列顶层 + 一层嵌套）。深层结构看下方 `## Examples`，或用 `--print-schema` 读完整 JSON Schema（用法见 SKILL.md「公共 flag 速查」与「Agent 使用提示」）。 ### `+cells-set` `--cells` **顶层字段**： -- `border_styles` (object?) — 单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top） { bottom?: object, left?: object, right?: object, top?: object } -- `cell_styles` (object?) — 单元格样式属性，包括字体、颜色、对齐方式和数字格式 { background_color?: string, font_color?: string, font_line?: enum, font_size?: number, font_style?: enum, …共 10 项 } -- `data_validation` (object?) — 数据验证配置 { enable_highlight?: boolean, help_text?: string, highlight_colors?: array, items?: array, operator?: enum, …共 9 项 } +- `value` (oneOf?) — 静态单元格值（文本、数字、布尔） - `formula` (string?) — 以 '=' 开头的单元格公式（例如：'=SUM(A1:A10)'） -- `multiple_values` (array?) — 多值内容，用于支持多选的列表验证单元格 each: { format?: string, value: oneOf } - `note` (string?) — 单元格批注/备注 -- `rich_text` (array?) — 富文本内容 each: { attachment_name?: string, attachment_token?: string, attachment_uri?: string, file_size?: number, image_height?: number, …共 17 项 } -- `value` (oneOf?) — 静态单元格值（文本、数字、布尔） +- `cell_styles` (object?) — 单元格样式属性，包括字体、颜色、对齐方式和数字格式 { font_color?: string, font_size?: number, font_weight?: enum, font_style?: enum, font_line?: enum, …共 10 项 } +- `border_styles` (object?) — 单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top） { top?: object, bottom?: object, left?: object, right?: object } +- `rich_text` (array?) — 富文本内容 each: { type: enum, text: string, style?: object, link?: string, mention_token?: string, …共 17 项 } +- `multiple_values` (array?) — 多值内容，用于支持多选的列表验证单元格 each: { value: oneOf, format?: string } +- `data_validation` (object?) — 数据验证配置 { type: enum, items?: array, range?: string, operator?: enum, values?: array, …共 9 项 } ### `+cells-set-style` `--border-styles` _单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top）_ **顶层字段**： -- `bottom` (object?) { color?: string, style?: enum, weight?: enum } -- `left` (object?) { color?: string, style?: enum, weight?: enum } -- `right` (object?) { color?: string, style?: enum, weight?: enum } -- `top` (object?) { color?: string, style?: enum, weight?: enum } +- `top` (object?) { style?: enum, weight?: enum, color?: string } +- `bottom` (object?) { style?: enum, weight?: enum, color?: string } +- `left` (object?) { style?: enum, weight?: enum, color?: string } +- `right` (object?) { style?: enum, weight?: enum, color?: string } ### `+dropdown-set` `--options` @@ -295,9 +267,9 @@ _列表选项（type='list' 时必填）_ 示例： ```bash -# 纯值（数组形态） +# 纯值（数组形态）；默认即覆盖非空 cell，无需显式传 --allow-overwrite lark-cli sheets +cells-set --url "https://example.feishu.cn/sheets/shtXXX" \ - --sheet-name "Sheet1" --range "A1:B2" --allow-overwrite \ + --sheet-name "Sheet1" --range "A1:B2" \ --cells '[[{"value":"name"},{"value":"score"}],[{"value":"alice"},{"value":95}]]' # 富 cell（公式 + 样式，cells 是二维矩阵每元素一个 cell schema） From 09c02e86578bc826c9cf09ca6c9217f09f854cf1 Mon Sep 17 00:00:00 2001 From: zhengzhijie Date: Mon, 25 May 2026 11:46:26 +0800 Subject: [PATCH 07/11] docs(sheets): sync dropdown --colors/--highlight clarification from spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirrors sheet-skill-spec MR !7 changes: - skills/lark-sheets/references/lark-sheets-write-cells.md: new "Dropdown 配色" section explaining how --colors (→ data_validation.highlight_colors) and --highlight (→ data_validation.enable_highlight) compose — length rule (shorter ok, longer rejected), --highlight gating, palette fallback behavior, minimal +dropdown-set example. - skills/lark-sheets/references/lark-sheets-batch-update.md: one-line pointer to the write_cells section for +dropdown-update / -delete (same rules). - shortcuts/sheets/data/flag-defs.json: --colors / --highlight `desc` fields gain the long-form server-field / length-rule descriptions used by `--help`. No Go-side change — earlier commit 538eb2e already loosened the buildDropdownValidation length check to "must not exceed"; this PR step just makes the docs / `--help` text catch up. --- shortcuts/sheets/data/flag-defs.json | 8 ++--- .../references/lark-sheets-batch-update.md | 6 ++-- .../references/lark-sheets-write-cells.md | 33 +++++++++++++++++-- 3 files changed, 39 insertions(+), 8 deletions(-) diff --git a/shortcuts/sheets/data/flag-defs.json b/shortcuts/sheets/data/flag-defs.json index d8687e227..713456e67 100644 --- a/shortcuts/sheets/data/flag-defs.json +++ b/shortcuts/sheets/data/flag-defs.json @@ -1879,7 +1879,7 @@ "kind": "own", "type": "string", "required": "optional", - "desc": "RGB hex color array (e.g. `[\"#1FB6C1\",\"#F006C2\"]`); length must equal `--options`", + "desc": "RGB hex pill colors for dropdown options (e.g. `[\"#1FB6C1\",\"#F006C2\"]`); maps to server `data_validation.highlight_colors`. Length may be **shorter than** `--options` (server cycles remaining slots through a built-in 10-color palette) but **must not exceed** it. Only takes effect when `--highlight` is also set.", "input": [ "file", "stdin" @@ -1897,7 +1897,7 @@ "kind": "own", "type": "bool", "required": "optional", - "desc": "Color-highlight options; default `false`" + "desc": "Enable pill-background color highlighting for dropdown options; default `false`. Maps to server `data_validation.enable_highlight`. When `true`, colors come from `--colors` in order; options beyond `--colors` length cycle through a built-in 10-color palette." }, { "name": "dry-run", @@ -2807,7 +2807,7 @@ "kind": "own", "type": "string", "required": "optional", - "desc": "Color array (same length as `--options`)", + "desc": "RGB hex pill colors for dropdown options (e.g. `[\"#1FB6C1\",\"#F006C2\"]`); maps to server `data_validation.highlight_colors`. Length may be **shorter than** `--options` (remaining slots cycle through a built-in palette) but **must not exceed** it. Only takes effect when `--highlight` is also set.", "input": [ "file", "stdin" @@ -2825,7 +2825,7 @@ "kind": "own", "type": "bool", "required": "optional", - "desc": "Color-highlight options" + "desc": "Enable pill-background color highlighting for dropdown options; default `false`. Maps to server `data_validation.enable_highlight`. Works with `--colors`; if `--colors` is omitted, all options cycle through a built-in 10-color palette." }, { "name": "dry-run", diff --git a/skills/lark-sheets/references/lark-sheets-batch-update.md b/skills/lark-sheets/references/lark-sheets-batch-update.md index 97fcbc569..3a7898a0f 100644 --- a/skills/lark-sheets/references/lark-sheets-batch-update.md +++ b/skills/lark-sheets/references/lark-sheets-batch-update.md @@ -22,6 +22,8 @@ 当同一工具需要对多个区域重复调用时，**必须**改用 `+batch-update` 合并为单次请求——`+batch-update` 是原子提交（要么全成功要么整批回滚）；逐个调用非原子，中途失败会留下半成品。 +**`+dropdown-update` / `+dropdown-delete` 的配色规则**（`--colors` 长度可短于 `--options` 但不能长于、必须配 `--highlight=true` 才生效、不传按内置 10 色色板循环补色）见 [`lark-sheets-write-cells`](./lark-sheets-write-cells.md) 的「Dropdown 配色」节，本 skill 不重复。 + ## Shortcuts | Shortcut | Risk | 分组 | @@ -70,9 +72,9 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_ | --- | --- | --- | --- | | `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（如 `["sheet1!A2:A100"]`），每项必须带 sheet 前缀 | | `--options` | string + File + Stdin（复合 JSON） | required | 选项 JSON 数组（如 `["opt1","opt2"]`） | -| `--colors` | string + File + Stdin（简单 JSON） | optional | 颜色数组（与 `--options` 等长） | +| `--colors` | string + File + Stdin（简单 JSON） | optional | 下拉选项的胶囊背景色，RGB hex 数组（如 `["#1FB6C1","#F006C2"]`）。映射到 server `data_validation.highlight_colors`。长度可以**短于** `--options`（剩余项按内置色板补色）但**不能长于**。仅当 `--highlight` 也传时才生效。 | | `--multiple` | bool | optional | 启用多选 | -| `--highlight` | bool | optional | 选项配色 | +| `--highlight` | bool | optional | 开启下拉选项的胶囊背景色高亮；默认 `false`。映射到 server `data_validation.enable_highlight`。需配合 `--colors` 使用——不传 `--colors` 时全部选项按内置 10 色色板循环。 | ### `+dropdown-delete` diff --git a/skills/lark-sheets/references/lark-sheets-write-cells.md b/skills/lark-sheets/references/lark-sheets-write-cells.md index 4608bdeaf..4849801f0 100644 --- a/skills/lark-sheets/references/lark-sheets-write-cells.md +++ b/skills/lark-sheets/references/lark-sheets-write-cells.md @@ -120,6 +120,35 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl **判断是不是"新行"**：写入 range 超出 `+csv-get` 返回的 `current_region` 右 / 下边界（如 `current_region=A1:H10`、写 `A11:H11`）即新行，必须按上述做法补边框。 +## Dropdown 配色（`+dropdown-set` / `+dropdown-update`） + +下拉的胶囊背景色高亮由两个 flag 控制，分别映射到 server `data_validation` 的两个字段： + +| CLI flag | server 字段 | 类型 | 含义 | +|---|---|---|---| +| `--highlight` | `enable_highlight` | bool | 总开关；为 `false`（默认）时所有选项无背景色 | +| `--colors` | `highlight_colors` | string[] | RGB hex 数组，如 `["#1FB6C1","#F006C2"]` | + +规则： + +- **`--colors` 长度可以短于 `--options`**（剩余项 server 按内置 10 色色板循环补色），**但不能长于**——CLI 端 Validate 阶段会拦截长于的情况。 +- **`--colors` 仅在 `--highlight=true` 时生效**——单独传 `--colors` 而不传 `--highlight`，server 不会显示任何背景色。 +- 完全不传两者，下拉就是纯文本选项（无配色）。 +- 想让所有选项都有颜色但不指定具体色——只传 `--highlight`，server 用内置色板循环。 + +最小用例（4 个 options 配 3 个 colors —— 前 3 个用指定色，第 4 个按内置色板补色）： + +``` +lark-cli sheets +dropdown-set \ + --url https://... --sheet-id \ + --range A2:A100 \ + --options '["待开始","进行中","已完成","已取消"]' \ + --colors '["#bff7d9","#FFE699","#bacefd"]' \ + --highlight +``` + +`+dropdown-update`（多 range 批量更新）的 `--colors` / `--highlight` 行为完全一致；只是 range 由单值变成 JSON 数组（每项带 sheet 前缀），同一份配色应用到所有 range。 + ## 工具选择 本 skill 提供以下 CLI shortcut，按数据来源 + 内容形态选： @@ -199,9 +228,9 @@ _公共四件套 · 系统：`--dry-run`_ | --- | --- | --- | --- | | `--range` | string | required | 目标范围（A1 格式，如 `A2:A100`） | | `--options` | string + File + Stdin（复合 JSON） | required | 选项 JSON 数组 `["opt1","opt2"]`；最多 500 项，每项 ≤100 字符，不含逗号 | -| `--colors` | string + File + Stdin（简单 JSON） | optional | RGB hex 颜色数组（如 `["#1FB6C1","#F006C2"]`），长度必须与 `--options` 一致 | +| `--colors` | string + File + Stdin（简单 JSON） | optional | 下拉选项的胶囊背景色，RGB hex 数组，如 `["#1FB6C1","#F006C2"]`。映射到 server `data_validation.highlight_colors`。长度可以**短于** `--options`（剩余项 server 按内置 10 色色板循环补色），但**不能长于**。仅当 `--highlight` 也传时才生效；单独传本 flag 不显示高亮色。 | | `--multiple` | bool | optional | 启用多选；默认 `false` | -| `--highlight` | bool | optional | 选项配色显示；默认 `false` | +| `--highlight` | bool | optional | 开启下拉选项的胶囊背景色高亮；默认 `false`。映射到 server `data_validation.enable_highlight`。不传或为 `false` 时所有选项无背景色；为 `true` 时按 `--colors` 顺序上色，未在 `--colors` 中提供的选项使用内置 10 色色板循环补色。 | ### `+csv-put` From f0d218f7ea5d1a5640a9c6b1c3fb2429e1deec2e Mon Sep 17 00:00:00 2001 From: zhengzhijie Date: Mon, 25 May 2026 14:23:08 +0800 Subject: [PATCH 08/11] feat(sheets): +dropdown-set/-update --source-range for listFromRange mode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previously +dropdown-set / +dropdown-update only emitted data_validation.type=list — agents wanting listFromRange (dropdown options sourced from existing cells, kept in sync with that range) had to drop down to +cells-set and hand-build a data_validation map. The flag now exposes it natively as --source-range, paired with --options under XOR. CLI changes: - shortcuts/sheets/lark_sheet_write_cells.go: * new dropdownTypeAndItems(runtime) — central XOR resolver: rejects 0 or 2 of {--options, --source-range}, returns (sourceSize, partial dv with type+items|range filled in). Source size = options length for list mode, rangeDimensions(--source-range) cell count for listFromRange. * buildDropdownValidation rewritten to call the resolver, then layer --colors / --multiple / --highlight on top — semantics unchanged for callers, just two modes instead of one. * validateDropdownOptions / -Colors renamed to validateDropdownSourceOrOptions so the XOR + length check fires at +dropdown-update Validate time too. * --colors length error message generalized: "must not exceed dropdown source size (N)" (covers both modes). - shortcuts/sheets/lark_sheet_batch_update.go: rename call site. - shortcuts/sheets/lark_sheet_write_cells_test.go: 4 new tests — ListFromRange (happy path: range + items absent + colors + highlight all emit), ListFromRange_ColorsLongerThanCells (overflow against T1:T3 cell count), XorBothSet, XorNeitherSet. Updated the existing ColorsLongerThanOptions assertion to match the new "source size" wording. Spec-driven changes (synced via npm run sync:cli from sheet-skill-spec MR !7 2c298b6): - shortcuts/sheets/data/flag-defs.json: --options Required flips to xor on +dropdown-set/-update; new --source-range row gains long-form description pointing at server data_validation.range + the XOR semantics. - skills/lark-sheets/references/lark-sheets-write-cells.md: "Dropdown 配色" section reorganized into "Dropdown 选项 + 配色" — XOR comparison table (list vs listFromRange), shared config flag table (--highlight / --colors), explicit length rule covering both modes, side-by-side minimal examples, server-range-normalization gotcha callout. - skills/lark-sheets/references/lark-sheets-batch-update.md pointer updated to mention both modes + that +dropdown-delete is unaffected. PPE smoke (ppe_lark_cli_sheet) on UFJxszjrZhZ1LVtc9FdcICSbn6b C column: - +cells-set C1 → "性别" (bold + centered): updated_cells_count=1 - +dropdown-set --range C2:C21 --source-range "Sheet1!T1:T3" --colors '["#cce8ff","#ffd6e7","#e6e6e6"]' --highlight: updated_cells_count=20 - read-back: data_validation.type=listFromRange + range=$T$1:$T$3 (server normalizes the prefix away on storage; highlight_colors / enable_highlight not echoed by get_cell_ranges, see byted-sheet read projection TODO). - error-path replay (both XOR violations + colors > source-size) all rejected at Validate stage with the expected messages. --- shortcuts/sheets/data/flag-defs.json | 18 +++- shortcuts/sheets/lark_sheet_batch_update.go | 2 +- shortcuts/sheets/lark_sheet_write_cells.go | 83 +++++++++++----- .../sheets/lark_sheet_write_cells_test.go | 99 ++++++++++++++++++- .../references/lark-sheets-batch-update.md | 5 +- .../references/lark-sheets-write-cells.md | 39 ++++++-- 6 files changed, 208 insertions(+), 38 deletions(-) diff --git a/shortcuts/sheets/data/flag-defs.json b/shortcuts/sheets/data/flag-defs.json index 713456e67..91781be7c 100644 --- a/shortcuts/sheets/data/flag-defs.json +++ b/shortcuts/sheets/data/flag-defs.json @@ -1867,7 +1867,7 @@ "name": "options", "kind": "own", "type": "string", - "required": "required", + "required": "xor", "desc": "Options as a JSON array, e.g. `[\"opt1\",\"opt2\"]`; up to 500 items, each ≤100 chars, no commas", "input": [ "file", @@ -1899,6 +1899,13 @@ "required": "optional", "desc": "Enable pill-background color highlighting for dropdown options; default `false`. Maps to server `data_validation.enable_highlight`. When `true`, colors come from `--colors` in order; options beyond `--colors` length cycle through a built-in 10-color palette." }, + { + "name": "source-range", + "kind": "own", + "type": "string", + "required": "xor", + "desc": "Source range for listFromRange dropdown (A1 + sheet prefix, e.g. `Sheet1!T1:T3`); maps to server `data_validation.range` and auto-sets `data_validation.type='listFromRange'`. XOR with `--options`: pass `--options` for an inline list (type=list), pass this for a range reference (type=listFromRange). `--colors` length rule unchanged (≤ source range cell count); `--highlight` / `--multiple` behave the same." + }, { "name": "dry-run", "kind": "system", @@ -2795,7 +2802,7 @@ "name": "options", "kind": "own", "type": "string", - "required": "required", + "required": "xor", "desc": "Options as a JSON array (e.g. `[\"opt1\",\"opt2\"]`)", "input": [ "file", @@ -2827,6 +2834,13 @@ "required": "optional", "desc": "Enable pill-background color highlighting for dropdown options; default `false`. Maps to server `data_validation.enable_highlight`. Works with `--colors`; if `--colors` is omitted, all options cycle through a built-in 10-color palette." }, + { + "name": "source-range", + "kind": "own", + "type": "string", + "required": "xor", + "desc": "Source range for listFromRange dropdown (A1 + sheet prefix, e.g. `Sheet1!T1:T3`); maps to server `data_validation.range` and auto-sets `data_validation.type='listFromRange'`. XOR with `--options`: pass `--options` for an inline list (type=list), pass this for a range reference (type=listFromRange). `--colors` length rule unchanged (≤ source range cell count); `--highlight` / `--multiple` behave the same." + }, { "name": "dry-run", "kind": "system", diff --git a/shortcuts/sheets/lark_sheet_batch_update.go b/shortcuts/sheets/lark_sheet_batch_update.go index d6591bb52..6cef40721 100644 --- a/shortcuts/sheets/lark_sheet_batch_update.go +++ b/shortcuts/sheets/lark_sheet_batch_update.go @@ -332,7 +332,7 @@ var DropdownUpdate = common.Shortcut{ if _, err := validateDropdownRanges(runtime); err != nil { return err } - if _, err := validateDropdownOptionsColors(runtime); err != nil { + if _, err := validateDropdownSourceOrOptions(runtime); err != nil { return err } return nil diff --git a/shortcuts/sheets/lark_sheet_write_cells.go b/shortcuts/sheets/lark_sheet_write_cells.go index c44970e8d..0d451890f 100644 --- a/shortcuts/sheets/lark_sheet_write_cells.go +++ b/shortcuts/sheets/lark_sheet_write_cells.go @@ -331,33 +331,33 @@ func dropdownSetInput(runtime flagView, token, sheetID, sheetName string) (map[s // ─── shared dropdown helpers ────────────────────────────────────────── -// buildDropdownValidation packs --options / --colors / --multiple / --highlight -// into the data_validation block expected by set_cell_range. Field names -// follow the canonical set_cell_range.data_validation schema: +// buildDropdownValidation packs --options or --source-range plus --colors / +// --multiple / --highlight into the data_validation block expected by +// set_cell_range. Field names follow the canonical +// set_cell_range.data_validation schema: // -// --options -> items (string array) -// --multiple -> support_multiple_values (bool) -// --colors -> highlight_colors (string array, hex) -// --highlight -> enable_highlight (bool) +// --options -> {type: "list", items: } +// --source-range -> {type: "listFromRange", range: } +// --multiple -> support_multiple_values (bool) +// --colors -> highlight_colors (string array, hex) +// --highlight -> enable_highlight (bool) // -// --colors length may be shorter than --options (server cycles remaining -// options through a built-in 10-color palette) but must not exceed it. +// --options and --source-range are XOR (caller must pass exactly one). +// --colors length may be shorter than the source size (options length or +// source-range cell count) — server cycles remaining slots through a +// built-in 10-color palette — but must not exceed it. func buildDropdownValidation(runtime flagView) (map[string]interface{}, error) { - options, err := requireJSONArray(runtime, "options") + sourceSize, dv, err := dropdownTypeAndItems(runtime) if err != nil { return nil, err } - dv := map[string]interface{}{ - "type": "list", - "items": options, - } if runtime.Str("colors") != "" { colors, err := requireJSONArray(runtime, "colors") if err != nil { return nil, err } - if len(colors) > len(options) { - return nil, common.FlagErrorf("--colors length (%d) must not exceed --options length (%d)", len(colors), len(options)) + if len(colors) > sourceSize { + return nil, common.FlagErrorf("--colors length (%d) must not exceed dropdown source size (%d)", len(colors), sourceSize) } dv["highlight_colors"] = colors } @@ -370,11 +370,46 @@ func buildDropdownValidation(runtime flagView) (map[string]interface{}, error) { return dv, nil } -// validateDropdownOptionsColors validates --options is a JSON array and that -// --colors (when set) is no longer than --options. Returns the options length -// so callers can size their cells matrix at Validate time without re-parsing. -func validateDropdownOptionsColors(runtime flagView) (int, error) { - options, err := requireJSONArray(runtime, "options") +// dropdownTypeAndItems resolves the XOR between --options and --source-range +// and returns (sourceSize, partial dv with type+items|range set). sourceSize +// is the option count for `list` mode or the source-range cell count for +// `listFromRange` mode — used to validate --colors length. +func dropdownTypeAndItems(runtime flagView) (int, map[string]interface{}, error) { + optsRaw := runtime.Str("options") + sourceRange := strings.TrimSpace(runtime.Str("source-range")) + switch { + case optsRaw != "" && sourceRange != "": + return 0, nil, common.FlagErrorf("--options and --source-range are mutually exclusive; pass exactly one") + case optsRaw == "" && sourceRange == "": + return 0, nil, common.FlagErrorf("one of --options (inline list) or --source-range (listFromRange) is required") + case optsRaw != "": + options, err := requireJSONArray(runtime, "options") + if err != nil { + return 0, nil, err + } + return len(options), map[string]interface{}{ + "type": "list", + "items": options, + }, nil + default: // sourceRange != "" + rows, cols, err := rangeDimensions(sourceRange) + if err != nil { + return 0, nil, common.FlagErrorf("--source-range %q: %v", sourceRange, err) + } + return rows * cols, map[string]interface{}{ + "type": "listFromRange", + "range": sourceRange, + }, nil + } +} + +// validateDropdownSourceOrOptions runs the XOR + --colors length check at +// Validate time so +dropdown-update / +dropdown-delete can fail fast without +// reaching the body-build step. Returns the dropdown source size (options +// length for list mode, source-range cell count for listFromRange) so +// callers can size their cells matrix. +func validateDropdownSourceOrOptions(runtime flagView) (int, error) { + sourceSize, _, err := dropdownTypeAndItems(runtime) if err != nil { return 0, err } @@ -383,11 +418,11 @@ func validateDropdownOptionsColors(runtime flagView) (int, error) { if err != nil { return 0, err } - if len(colors) > len(options) { - return 0, common.FlagErrorf("--colors length (%d) must not exceed --options length (%d)", len(colors), len(options)) + if len(colors) > sourceSize { + return 0, common.FlagErrorf("--colors length (%d) must not exceed dropdown source size (%d)", len(colors), sourceSize) } } - return len(options), nil + return sourceSize, nil } // ─── range parsing helpers ──────────────────────────────────────────── diff --git a/shortcuts/sheets/lark_sheet_write_cells_test.go b/shortcuts/sheets/lark_sheet_write_cells_test.go index aef33e272..df350a19c 100644 --- a/shortcuts/sheets/lark_sheet_write_cells_test.go +++ b/shortcuts/sheets/lark_sheet_write_cells_test.go @@ -174,8 +174,9 @@ func TestDropdownSet_CellsShape(t *testing.T) { } // TestDropdownSet_ColorsLongerThanOptions checks the early Validate-time -// error when --colors length exceeds --options. Equal-or-shorter lengths -// are accepted (server cycles the rest through a built-in palette). +// error when --colors length exceeds the dropdown source size (options +// length in list mode). Equal-or-shorter lengths are accepted (server +// cycles the rest through a built-in palette). func TestDropdownSet_ColorsLongerThanOptions(t *testing.T) { t.Parallel() _, stderr, err := runShortcutCapturingErr(t, DropdownSet, []string{ @@ -188,7 +189,7 @@ func TestDropdownSet_ColorsLongerThanOptions(t *testing.T) { if err == nil { t.Fatal("expected --colors length error, got nil") } - if !strings.Contains(stderr, "must not exceed --options length") && !strings.Contains(err.Error(), "must not exceed --options length") { + if !strings.Contains(stderr, "must not exceed dropdown source size") && !strings.Contains(err.Error(), "must not exceed dropdown source size") { t.Errorf("error message missing length-overflow hint:\nerr=%v\nstderr=%s", err, stderr) } } @@ -215,6 +216,98 @@ func TestDropdownSet_ColorsShorterAccepted(t *testing.T) { } } +// TestDropdownSet_ListFromRange verifies --source-range emits +// data_validation.type=listFromRange + data_validation.range, paired with +// --colors / --highlight propagating to highlight_colors / enable_highlight. +func TestDropdownSet_ListFromRange(t *testing.T) { + t.Parallel() + body := parseDryRunBody(t, DropdownSet, []string{ + "--url", testURL, "--sheet-id", testSheetID, + "--range", "B2:B21", + "--source-range", "Sheet1!T1:T3", + "--colors", `["#cce8ff","#ffd6e7","#e6e6e6"]`, + "--highlight", + }) + input := decodeToolInput(t, body, "set_cell_range") + cells, _ := input["cells"].([]interface{}) + row0, _ := cells[0].([]interface{}) + cell, _ := row0[0].(map[string]interface{}) + dv, _ := cell["data_validation"].(map[string]interface{}) + if dv["type"] != "listFromRange" { + t.Errorf("data_validation.type = %v, want listFromRange", dv["type"]) + } + if dv["range"] != "Sheet1!T1:T3" { + t.Errorf("data_validation.range = %v, want Sheet1!T1:T3 (verbatim, server normalizes)", dv["range"]) + } + if _, hasItems := dv["items"]; hasItems { + t.Errorf("listFromRange mode should not emit `items`: %#v", dv) + } + if dv["enable_highlight"] != true { + t.Errorf("data_validation.enable_highlight = %v, want true", dv["enable_highlight"]) + } + colors, _ := dv["highlight_colors"].([]interface{}) + if len(colors) != 3 { + t.Errorf("highlight_colors length = %d, want 3", len(colors)) + } +} + +// TestDropdownSet_ListFromRange_ColorsLongerThanCells rejects --colors +// longer than the source range cell count (T1:T3 has 3 cells, 4 colors +// must be refused). +func TestDropdownSet_ListFromRange_ColorsLongerThanCells(t *testing.T) { + t.Parallel() + _, stderr, err := runShortcutCapturingErr(t, DropdownSet, []string{ + "--url", testURL, "--sheet-id", testSheetID, + "--range", "B2:B21", + "--source-range", "Sheet1!T1:T3", + "--colors", `["#a","#b","#c","#d"]`, + "--highlight", + "--dry-run", + }) + if err == nil { + t.Fatal("expected --colors length error, got nil") + } + if !strings.Contains(stderr, "must not exceed dropdown source size") && !strings.Contains(err.Error(), "must not exceed dropdown source size") { + t.Errorf("error message missing source-size hint:\nerr=%v\nstderr=%s", err, stderr) + } +} + +// TestDropdownSet_XorBothSet rejects passing both --options and +// --source-range. +func TestDropdownSet_XorBothSet(t *testing.T) { + t.Parallel() + _, stderr, err := runShortcutCapturingErr(t, DropdownSet, []string{ + "--url", testURL, "--sheet-id", testSheetID, + "--range", "B2:B21", + "--options", `["a","b"]`, + "--source-range", "Sheet1!T1:T3", + "--dry-run", + }) + if err == nil { + t.Fatal("expected XOR error, got nil") + } + if !strings.Contains(stderr, "mutually exclusive") && !strings.Contains(err.Error(), "mutually exclusive") { + t.Errorf("error message missing XOR hint:\nerr=%v\nstderr=%s", err, stderr) + } +} + +// TestDropdownSet_XorNeitherSet rejects passing neither --options nor +// --source-range. +func TestDropdownSet_XorNeitherSet(t *testing.T) { + t.Parallel() + _, stderr, err := runShortcutCapturingErr(t, DropdownSet, []string{ + "--url", testURL, "--sheet-id", testSheetID, + "--range", "B2:B21", + "--dry-run", + }) + if err == nil { + t.Fatal("expected required-one error, got nil") + } + if !strings.Contains(stderr, "one of --options") && !strings.Contains(err.Error(), "one of --options") { + t.Errorf("error message missing required-one hint:\nerr=%v\nstderr=%s", err, stderr) + } +} + // TestCellsSetStyle_FlatFlags verifies that the 11 flat style flags + // --border-styles compose into cell_styles + border_styles per cell. func TestCellsSetStyle_FlatFlags(t *testing.T) { diff --git a/skills/lark-sheets/references/lark-sheets-batch-update.md b/skills/lark-sheets/references/lark-sheets-batch-update.md index 3a7898a0f..1438ac901 100644 --- a/skills/lark-sheets/references/lark-sheets-batch-update.md +++ b/skills/lark-sheets/references/lark-sheets-batch-update.md @@ -22,7 +22,7 @@ 当同一工具需要对多个区域重复调用时，**必须**改用 `+batch-update` 合并为单次请求——`+batch-update` 是原子提交（要么全成功要么整批回滚）；逐个调用非原子，中途失败会留下半成品。 -**`+dropdown-update` / `+dropdown-delete` 的配色规则**（`--colors` 长度可短于 `--options` 但不能长于、必须配 `--highlight=true` 才生效、不传按内置 10 色色板循环补色）见 [`lark-sheets-write-cells`](./lark-sheets-write-cells.md) 的「Dropdown 配色」节，本 skill 不重复。 +**`+dropdown-update` 的选项模式（`--options` / `--source-range` XOR，对应 server `type=list` / `type=listFromRange`）+ 配色规则**（`--colors` 长度可短不能长、必须配 `--highlight=true` 才生效、不传按内置 10 色色板循环补色）见 [`lark-sheets-write-cells`](./lark-sheets-write-cells.md) 的「Dropdown 选项 + 配色」节，本 skill 不重复。`+dropdown-delete` 不涉及这些 flag。 ## Shortcuts @@ -71,10 +71,11 @@ _公共：URL/token（无 sheet 定位） · 系统：`--dry-run`_ | Flag | Type | 必填 | 说明 | | --- | --- | --- | --- | | `--ranges` | string + File + Stdin（简单 JSON） | required | 目标范围 JSON 数组（如 `["sheet1!A2:A100"]`），每项必须带 sheet 前缀 | -| `--options` | string + File + Stdin（复合 JSON） | required | 选项 JSON 数组（如 `["opt1","opt2"]`） | +| `--options` | string + File + Stdin（复合 JSON） | xor | 选项 JSON 数组（如 `["opt1","opt2"]`） | | `--colors` | string + File + Stdin（简单 JSON） | optional | 下拉选项的胶囊背景色，RGB hex 数组（如 `["#1FB6C1","#F006C2"]`）。映射到 server `data_validation.highlight_colors`。长度可以**短于** `--options`（剩余项按内置色板补色）但**不能长于**。仅当 `--highlight` 也传时才生效。 | | `--multiple` | bool | optional | 启用多选 | | `--highlight` | bool | optional | 开启下拉选项的胶囊背景色高亮；默认 `false`。映射到 server `data_validation.enable_highlight`。需配合 `--colors` 使用——不传 `--colors` 时全部选项按内置 10 色色板循环。 | +| `--source-range` | string | xor | listFromRange 模式的下拉源 range，A1 表示法 + sheet 前缀（如 `Sheet1!T1:T3`）。映射到 server `data_validation.range`，搭配 server `data_validation.type='listFromRange'` 自动生效。跟 `--options` 二选一：传 `--options` 走 inline 列表（type=list），传本 flag 走 range 引用（type=listFromRange）。`--colors` 长度规则不变（≤ 源 range 单元格数），`--highlight` / `--multiple` 行为相同。 | ### `+dropdown-delete` diff --git a/skills/lark-sheets/references/lark-sheets-write-cells.md b/skills/lark-sheets/references/lark-sheets-write-cells.md index 4849801f0..5a7d3912f 100644 --- a/skills/lark-sheets/references/lark-sheets-write-cells.md +++ b/skills/lark-sheets/references/lark-sheets-write-cells.md @@ -120,9 +120,20 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl **判断是不是"新行"**：写入 range 超出 `+csv-get` 返回的 `current_region` 右 / 下边界（如 `current_region=A1:H10`、写 `A11:H11`）即新行，必须按上述做法补边框。 -## Dropdown 配色（`+dropdown-set` / `+dropdown-update`） +## Dropdown 选项 + 配色（`+dropdown-set` / `+dropdown-update`） -下拉的胶囊背景色高亮由两个 flag 控制，分别映射到 server `data_validation` 的两个字段： +### 两种选项模式（XOR） + +| 模式 | flag | server `data_validation.type` | 适用场景 | +|---|---|---|---| +| inline 列表 | `--options '["a","b","c"]'` | `list` | 固定选项集，写死在命令里 | +| 引用 range | `--source-range 'Sheet1!T1:T3'` | `listFromRange` | 选项来源是已有单元格，跟数据动态同步；适合维护一张「枚举值」列后多处引用 | + +**`--options` 和 `--source-range` 必须二选一传一个**（CLI 端 Validate 阶段拦截 0 个或 2 个的情况）。`--source-range` 用 A1 + sheet 前缀写法，跟目标 `--range` 可以是同 sheet 也可以是其它 sheet（如 `Refs!A1:A10`）。 + +### 配色（两种模式通用） + +下拉的胶囊背景色高亮由另外两个 flag 控制，跟选项模式正交，映射到 server `data_validation` 的两个字段： | CLI flag | server 字段 | 类型 | 含义 | |---|---|---|---| @@ -131,12 +142,14 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl 规则： -- **`--colors` 长度可以短于 `--options`**（剩余项 server 按内置 10 色色板循环补色），**但不能长于**——CLI 端 Validate 阶段会拦截长于的情况。 +- **`--colors` 长度可以短**：list 模式下 ≤ `--options` 长度，listFromRange 模式下 ≤ `--source-range` 的单元格数（剩余项 server 按内置 10 色色板循环补色），**但不能长于**——CLI 端 Validate 阶段会拦截长于的情况。 - **`--colors` 仅在 `--highlight=true` 时生效**——单独传 `--colors` 而不传 `--highlight`，server 不会显示任何背景色。 - 完全不传两者，下拉就是纯文本选项（无配色）。 - 想让所有选项都有颜色但不指定具体色——只传 `--highlight`，server 用内置色板循环。 -最小用例（4 个 options 配 3 个 colors —— 前 3 个用指定色，第 4 个按内置色板补色）： +### 最小用例 + +**list 模式**（4 个 options 配 3 个 colors —— 前 3 个用指定色，第 4 个按内置色板补色）： ``` lark-cli sheets +dropdown-set \ @@ -147,7 +160,20 @@ lark-cli sheets +dropdown-set \ --highlight ``` -`+dropdown-update`（多 range 批量更新）的 `--colors` / `--highlight` 行为完全一致；只是 range 由单值变成 JSON 数组（每项带 sheet 前缀），同一份配色应用到所有 range。 +**listFromRange 模式**（源 range 在同 sheet 的 T1:T3，3 个 options 配 3 个 colors）： + +``` +lark-cli sheets +dropdown-set \ + --url https://... --sheet-id \ + --range B2:B21 \ + --source-range 'Sheet1!T1:T3' \ + --colors '["#cce8ff","#ffd6e7","#e6e6e6"]' \ + --highlight +``` + +> ⚠️ **`--source-range` 必须带 sheet 前缀**（即使跟 `--range` 同 sheet），server 会自动把它规范化成 `$T$1:$T$3`（绝对引用）落库；回读时 sheet 前缀已被剥掉，agent 拿 read 结果再回写需要自己补前缀。 + +`+dropdown-update`（多 range 批量更新）的所有 flag 语义与 `+dropdown-set` 完全一致；只是目标 `--ranges` 由单值变成 JSON 数组（每项带 sheet 前缀），同一份选项 + 配色应用到所有 range。 ## 工具选择 @@ -227,10 +253,11 @@ _公共四件套 · 系统：`--dry-run`_ | Flag | Type | 必填 | 说明 | | --- | --- | --- | --- | | `--range` | string | required | 目标范围（A1 格式，如 `A2:A100`） | -| `--options` | string + File + Stdin（复合 JSON） | required | 选项 JSON 数组 `["opt1","opt2"]`；最多 500 项，每项 ≤100 字符，不含逗号 | +| `--options` | string + File + Stdin（复合 JSON） | xor | 选项 JSON 数组 `["opt1","opt2"]`；最多 500 项，每项 ≤100 字符，不含逗号 | | `--colors` | string + File + Stdin（简单 JSON） | optional | 下拉选项的胶囊背景色，RGB hex 数组，如 `["#1FB6C1","#F006C2"]`。映射到 server `data_validation.highlight_colors`。长度可以**短于** `--options`（剩余项 server 按内置 10 色色板循环补色），但**不能长于**。仅当 `--highlight` 也传时才生效；单独传本 flag 不显示高亮色。 | | `--multiple` | bool | optional | 启用多选；默认 `false` | | `--highlight` | bool | optional | 开启下拉选项的胶囊背景色高亮；默认 `false`。映射到 server `data_validation.enable_highlight`。不传或为 `false` 时所有选项无背景色；为 `true` 时按 `--colors` 顺序上色，未在 `--colors` 中提供的选项使用内置 10 色色板循环补色。 | +| `--source-range` | string | xor | listFromRange 模式的下拉源 range，A1 表示法 + sheet 前缀（如 `Sheet1!T1:T3`）。映射到 server `data_validation.range`，搭配 server `data_validation.type='listFromRange'` 自动生效。跟 `--options` 二选一：传 `--options` 走 inline 列表（type=list），传本 flag 走 range 引用（type=listFromRange）。`--colors` 长度规则不变（≤ 源 range 单元格数），`--highlight` / `--multiple` 行为相同。 | ### `+csv-put` From 38ef6ad51ec756cf089acc1c1501fb7fd0e588a9 Mon Sep 17 00:00:00 2001 From: zhengzhijie Date: Mon, 25 May 2026 14:28:07 +0800 Subject: [PATCH 09/11] =?UTF-8?q?docs(sheets):=20sync=20agent-voice=20rewr?= =?UTF-8?q?ite=20of=20Dropdown=20=E9=80=89=E9=A1=B9+=E9=85=8D=E8=89=B2=20f?= =?UTF-8?q?rom=20spec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirrors sheet-skill-spec MR !7 60df610 — narrative now describes how the flags interact (XOR, colors length rule, highlight gating, sheet-prefix read-back gotcha) without exposing the underlying data_validation field names or server-side normalization details that agents don't act on. No Go-side change, no shortcut behavior change. --- .../references/lark-sheets-batch-update.md | 2 +- .../references/lark-sheets-write-cells.md | 40 +++++++++---------- 2 files changed, 20 insertions(+), 22 deletions(-) diff --git a/skills/lark-sheets/references/lark-sheets-batch-update.md b/skills/lark-sheets/references/lark-sheets-batch-update.md index 1438ac901..e6ab669e4 100644 --- a/skills/lark-sheets/references/lark-sheets-batch-update.md +++ b/skills/lark-sheets/references/lark-sheets-batch-update.md @@ -22,7 +22,7 @@ 当同一工具需要对多个区域重复调用时，**必须**改用 `+batch-update` 合并为单次请求——`+batch-update` 是原子提交（要么全成功要么整批回滚）；逐个调用非原子，中途失败会留下半成品。 -**`+dropdown-update` 的选项模式（`--options` / `--source-range` XOR，对应 server `type=list` / `type=listFromRange`）+ 配色规则**（`--colors` 长度可短不能长、必须配 `--highlight=true` 才生效、不传按内置 10 色色板循环补色）见 [`lark-sheets-write-cells`](./lark-sheets-write-cells.md) 的「Dropdown 选项 + 配色」节，本 skill 不重复。`+dropdown-delete` 不涉及这些 flag。 +**`+dropdown-update` 的选项模式（`--options` / `--source-range` 二选一）+ 配色规则**（`--colors` 长度可短不能长、必须配 `--highlight=true` 才生效、不传按内置 10 色色板循环补色）见 [`lark-sheets-write-cells`](./lark-sheets-write-cells.md) 的「Dropdown 选项 + 配色」节，本 skill 不重复。`+dropdown-delete` 不涉及这些 flag。 ## Shortcuts diff --git a/skills/lark-sheets/references/lark-sheets-write-cells.md b/skills/lark-sheets/references/lark-sheets-write-cells.md index 5a7d3912f..2bb12a8de 100644 --- a/skills/lark-sheets/references/lark-sheets-write-cells.md +++ b/skills/lark-sheets/references/lark-sheets-write-cells.md @@ -122,34 +122,32 @@ Step 2: `+cells-set` — range="A2", cells 含 value + cell_styles + border_styl ## Dropdown 选项 + 配色（`+dropdown-set` / `+dropdown-update`） -### 两种选项模式（XOR） +### 选项怎么来：`--options` 与 `--source-range` 二选一 -| 模式 | flag | server `data_validation.type` | 适用场景 | -|---|---|---|---| -| inline 列表 | `--options '["a","b","c"]'` | `list` | 固定选项集，写死在命令里 | -| 引用 range | `--source-range 'Sheet1!T1:T3'` | `listFromRange` | 选项来源是已有单元格，跟数据动态同步；适合维护一张「枚举值」列后多处引用 | +| flag | 选项来源 | 适用场景 | +|---|---|---| +| `--options '["a","b","c"]'` | 写在命令里的固定列表 | 选项集是常量、不需要事后维护 | +| `--source-range 'Sheet1!T1:T3'` | 已有单元格里的值 | 选项要跟数据动态同步；想维护一张「枚举值」列后多处引用 | -**`--options` 和 `--source-range` 必须二选一传一个**（CLI 端 Validate 阶段拦截 0 个或 2 个的情况）。`--source-range` 用 A1 + sheet 前缀写法，跟目标 `--range` 可以是同 sheet 也可以是其它 sheet（如 `Refs!A1:A10`）。 +两个 flag **必须传一个、且只能传一个**——同时传或都不传，CLI 会立刻报错。`--source-range` 用 A1 + sheet 前缀写法（如 `Sheet1!T1:T3`），可以指同 sheet 也可以指其它 sheet（如 `Refs!A1:A10`）。 -### 配色（两种模式通用） +### 配色：`--colors` 与 `--highlight`（与选项模式无关） -下拉的胶囊背景色高亮由另外两个 flag 控制，跟选项模式正交，映射到 server `data_validation` 的两个字段： +- `--highlight`：开下拉选项的胶囊背景色总开关；不传默认 `false`、无配色。 +- `--colors '["#hex","#hex",...]'`：每个选项对应一种胶囊背景色；只在 `--highlight` 也传时生效。 -| CLI flag | server 字段 | 类型 | 含义 | -|---|---|---|---| -| `--highlight` | `enable_highlight` | bool | 总开关；为 `false`（默认）时所有选项无背景色 | -| `--colors` | `highlight_colors` | string[] | RGB hex 数组，如 `["#1FB6C1","#F006C2"]` | +长度规则： +- `--colors` 长度**可以短于**选项数（list 模式短于 `--options` 长度，listFromRange 模式短于 `--source-range` 的单元格数），未指定的选项按内置 10 色色板循环补色； +- `--colors` 长度**不能长于**选项数——CLI 端 Validate 阶段就会拦截，错误信息形如 `--colors length (4) must not exceed dropdown source size (3)`。 -规则： - -- **`--colors` 长度可以短**：list 模式下 ≤ `--options` 长度，listFromRange 模式下 ≤ `--source-range` 的单元格数（剩余项 server 按内置 10 色色板循环补色），**但不能长于**——CLI 端 Validate 阶段会拦截长于的情况。 -- **`--colors` 仅在 `--highlight=true` 时生效**——单独传 `--colors` 而不传 `--highlight`，server 不会显示任何背景色。 -- 完全不传两者，下拉就是纯文本选项（无配色）。 -- 想让所有选项都有颜色但不指定具体色——只传 `--highlight`，server 用内置色板循环。 +排列组合： +- 想要纯文本下拉、无配色 → 都不传 `--highlight` / `--colors`； +- 想要每个选项指定确切颜色 → 同时传 `--highlight` 和 `--colors`； +- 想要所有选项都有颜色但不指定具体色 → 只传 `--highlight`，颜色按内置色板循环。 ### 最小用例 -**list 模式**（4 个 options 配 3 个 colors —— 前 3 个用指定色，第 4 个按内置色板补色）： +**`--options` 模式**（4 个选项配 3 个颜色——前 3 个指定色，第 4 个按内置色板补）： ``` lark-cli sheets +dropdown-set \ @@ -160,7 +158,7 @@ lark-cli sheets +dropdown-set \ --highlight ``` -**listFromRange 模式**（源 range 在同 sheet 的 T1:T3，3 个 options 配 3 个 colors）： +**`--source-range` 模式**（先在 Sheet1!T1:T3 维护「男/女/保密」三行，再让 B2:B21 引用它）： ``` lark-cli sheets +dropdown-set \ @@ -171,7 +169,7 @@ lark-cli sheets +dropdown-set \ --highlight ``` -> ⚠️ **`--source-range` 必须带 sheet 前缀**（即使跟 `--range` 同 sheet），server 会自动把它规范化成 `$T$1:$T$3`（绝对引用）落库；回读时 sheet 前缀已被剥掉，agent 拿 read 结果再回写需要自己补前缀。 +> ⚠️ **`--source-range` 必须带 sheet 前缀**（即使跟 `--range` 同 sheet）。注意一个坑：回读这种 listFromRange 下拉单元格时，`data_validation.range` 看起来不带 sheet 前缀（形如 `$T$1:$T$3`），如果要把读出来的 range 反过来写回 `--source-range`，**必须自己重新补上 sheet 前缀**，否则会被拒。 `+dropdown-update`（多 range 批量更新）的所有 flag 语义与 `+dropdown-set` 完全一致；只是目标 `--ranges` 由单值变成 JSON 数组（每项带 sheet 前缀），同一份选项 + 配色应用到所有 range。 From fa503fa47fd78e358b0928c04ec2e4c6c79f03a8 Mon Sep 17 00:00:00 2001 From: zhengzhijie Date: Mon, 25 May 2026 14:35:43 +0800 Subject: [PATCH 10/11] chore(sheets): restore --colors in parseJSONFlag docstring example list MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The earlier commit 49104ec swapped --colors out of parseJSONFlag's "Used by" example list when it deleted the flag (item #2 there removed --colors / --highlight from +dropdown-set/-update). Subsequent commits 8672d8e / 538eb2e / fb90c8b reinstated --colors (and added --source-range) but did not roll back this docstring tweak — leaving an orphan reference to --properties where --colors used to be. This restores the example list to its pre-49104ec form so the docstring matches what the helper actually services on this branch's HEAD. Pure docstring change — function behavior unaffected, no test movement. --- shortcuts/sheets/helpers.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shortcuts/sheets/helpers.go b/shortcuts/sheets/helpers.go index 79b7223a3..64206b9e2 100644 --- a/shortcuts/sheets/helpers.go +++ b/shortcuts/sheets/helpers.go @@ -156,7 +156,7 @@ func sheetSelectorPlaceholder(sheetID, sheetName string) string { // parseJSONFlag parses a JSON string from a flag value. Returns nil when the // flag is empty (caller decides if that's acceptable). Used by --data / -// --style / --options / --ranges / --properties and friends. +// --style / --options / --ranges / --colors and friends. func parseJSONFlag(runtime flagView, name string) (interface{}, error) { raw := strings.TrimSpace(runtime.Str(name)) if raw == "" { From f0dea38aeb146a3ee517bd7f795329230be32f72 Mon Sep 17 00:00:00 2001 From: zhengzhijie Date: Mon, 25 May 2026 14:41:59 +0800 Subject: [PATCH 11/11] fix(sheets): post-rebase test fixups after dropping superseded fix #1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two test fallouts from rebasing onto upstream 4be06c8 (which independently re-fixed +workbook-create and +dim-move with a more thorough approach): - shortcuts/sheets/lark_sheet_workbook_test.go: our PR's earlier TestWorkbookCreate_DryRun "with headers and data → 2-step plan" subtest asserted the expedient sheet_name="Sheet1" / no-sheet_id wire body that matched our dropped fix #1 implementation. Upstream's fix #1 resolves the workbook's first sheet via get_workbook_structure and fills with the real sheet_id instead. Reset this file to upstream's version — our superseded assertions disappear, upstream's tests cover the new wire shape. - shortcuts/sheets/execute_paths_test.go: TestExecute_RangeSort fixture still used the legacy {col, order} sort-key shape because the rebase resolution picked the upstream version of this file wholesale (it contained other unrelated changes). Re-apply just the one fixture update to {column, ascending} so fix #5's CLI-side rejection logic exercises a valid input — server-side sort_conditions has required fields `column` (string) and `ascending` (bool); the historical {col, order} vocabulary was never accepted. go build ./... + go test ./shortcuts/sheets/... -count=1 both green. --- shortcuts/sheets/execute_paths_test.go | 2 +- shortcuts/sheets/lark_sheet_workbook_test.go | 9 --------- 2 files changed, 1 insertion(+), 10 deletions(-) diff --git a/shortcuts/sheets/execute_paths_test.go b/shortcuts/sheets/execute_paths_test.go index fbe55c76c..8b08aaed2 100644 --- a/shortcuts/sheets/execute_paths_test.go +++ b/shortcuts/sheets/execute_paths_test.go @@ -398,7 +398,7 @@ func TestExecute_RangeSort(t *testing.T) { "--url", testURL, "--sheet-id", testSheetID, "--range", "A1:D50", "--has-header", - "--sort-keys", `[{"col":"B","order":"asc"}]`, + "--sort-keys", `[{"column":"B","ascending":true}]`, }, stub) if err != nil { t.Fatalf("execute failed: %v", err) diff --git a/shortcuts/sheets/lark_sheet_workbook_test.go b/shortcuts/sheets/lark_sheet_workbook_test.go index 5298d41c0..f7b257fc2 100644 --- a/shortcuts/sheets/lark_sheet_workbook_test.go +++ b/shortcuts/sheets/lark_sheet_workbook_test.go @@ -317,15 +317,6 @@ func TestWorkbookCreate_DryRun(t *testing.T) { if input["range"] != "A1:B3" { t.Errorf("fill range = %v, want A1:B3 (1 header + 2 data rows × 2 cols)", input["range"]) } - // New workbook → fill targets the default sheet by name (no - // extra get_workbook_structure call is needed to learn the - // auto-generated sheet_id). - if input["sheet_name"] != "Sheet1" { - t.Errorf("fill sheet_name = %v, want Sheet1", input["sheet_name"]) - } - if _, hasID := input["sheet_id"]; hasID { - t.Errorf("fill sheet_id should be omitted (server rejects empty); got %v", input["sheet_id"]) - } }) }