mirror of
https://github.com/larksuite/cli.git
synced 2026-09-14 18:42:53 +08:00
xiongyuanwen-byted
bd898a1d74
* feat(sheets): add +sheet-show-gridline / +sheet-hide-gridline shortcuts
* docs(sheets): strengthen lark-sheets references for common editing pitfalls
Add targeted guidance to six lark-sheets references to reduce frequent
mistakes when editing spreadsheets through the CLI:
- write-cells: sanity-check units / dimension conversion / quantity factors
before formula writes (formulas can run clean yet be off by a factor);
keep derived output off original data columns to avoid clobbering source
- core-operations: prefer live formulas for derived values even when "live
update" is not explicitly requested; scope rewrite/transform precisely so
rows/columns that should stay unchanged are kept 1:1; treat header-stated
format rules as checklist items; confirm the artifact file actually exists
before finishing; write back bare values from local scripts
- visual-standards: apply border/header formatting on explicit request and
identify the real header row; keep font size consistent with the source
- range-operations: keep total column width within A4 for printing
- read-data: dedup/compare long numbers via raw values, not csv formatted
display (scientific notation collapses distinct numbers and causes false
duplicates)
- chart: format date/number axes via source-cell number_format; place charts
outside the data area so they do not cover existing data
* feat(sheets): implement table-put/table-get and sync skill specs
- Add lark_sheet_table_io.go with +table-put / +table-get and tests
- Refactor read-data; extend workbook; register new shortcuts
- Sync generated flag defs/schemas (go:embed) from sheet-skill-spec
- Sync skill references (write-cells numeric-column guidance, plus
read-data / workbook / chart updates)
* docs(sheets): surface typed-write path at the write-decision point
Quick-ref table (SKILL.md, the first decision point) had no +table-put and
gated typed writes on "DataFrame", so a model holding a Counter/list/dict
would fall back to +csv-put and silently lose number/date fidelity.
- split csv-put row to plain-text values (no numeric/date semantics)
- add +table-put row for typed writes into an existing sheet
- add +workbook-create --sheets row for create + typed write in one shot
- add judgment note: number/amount/date/percent/count -> +table-put
(or +workbook-create --sheets when the workbook does not exist yet);
plain text -> +csv-put
- reframe write-cells scenario row to lead with numeric semantics
- point new-table writes at +workbook-create --sheets (one shot) instead
of the create-empty-then-table-put two-step
Synced from sheet-skill-spec canonical (generate:cli + sync:cli).
* docs(sheets): sync SKILL.md (drop "not for local Excel" caveat)
Mirror the upstream sheet-skill-spec change removing the "not applicable to local Excel files" tail from the sheets skill and reference descriptions.
* docs(sheets): sync SKILL.md (drop "Feishu sheets only" caveat)
Mirror the upstream sheet-skill-spec change removing the "applies to Feishu sheets only" tail from the 14 sheet reference descriptions.
* feat(sheets): add +workbook-import wrapping the drive import core
Import a local xlsx/xls/csv as a new spreadsheet by delegating to the shared drive import flow with the target type pinned to sheet. Refactor drive +import to expose ImportParams / ValidateImport / PlanImportDryRun / RunImport (behavior unchanged, existing drive tests still cover it); sheets reuses them. Regenerate flag_defs_gen.go and sync the spec mirror.
* refactor(sheets): reuse the drive export core in +workbook-export
Replace +workbook-export's parallel export-task implementation with the shared drive ExportParams/RunExport core (pinned to type=sheet). Drops ~90 lines of duplicated poll/download code; +workbook-export now inherits drive's ctx cancellation, resume-on-timeout, filename sanitize/overwrite, and the full set of export status labels. The output contract aligns with drive's (adds ready/downloaded/doc_type; saved_path preserved). Also normalize an empty drive --output-dir to "." so drive +export behavior is unchanged, and fix the sheets export e2e to call +workbook-export instead of a nonexistent +export.
* docs(sheets): keep original column widths; align chart axis with requested metric
- range-operations: only widen new / overflowing columns; never recompute or
shrink the widths of existing columns (any blanket resize, even by 1px,
breaks the original visual format)
- chart: when the user asks for a share / percentage, the value axis should be
a percentage (pie, or stack.percentage on bar/column) rather than raw counts
* docs(sheets): reword guidance to avoid eval-specific phrasing
Replace scoring-framework wording in the examples with plain functional
consequences (e.g. "not delivered", "goes stale when the source changes",
"breaks the original visual format"), so the references stay agent-facing.
* docs: add lark sheets financial modeling guidance
* docs(sheets): align write-cells reference with the generated output
Bring the hand-applied write-cells example in line with the spec-generated
reference so the CLI mirror is byte-identical to the canonical source.
* docs(sheets): align +csv-put help with formula support
Sync the formula-support wording from sheet-skill-spec (flag-defs, skill
references) and update the hand-authored cobra Description and comment for
+csv-put. +csv-put evaluates a leading-= cell as a formula via
set_range_from_csv; descriptions only, no behavior change.
* docs(sheets): fix invalid +dim-insert example in chart reference
The chart reference's placement example used non-existent flags
--dimension/--start/--end for +dim-insert. The real signature is
--position (required) + --count (required); copying the example
fails Validate with "--position is required". Replace it with
+dim-insert --position V --count 6 (insert 6 columns before V,
i.e. after U), aligning with the sheet-structure reference.
* docs(sheets): chart coordinate base / quoting + filter condition enums
Sync three reference-doc corrections from the spec source:
1. chart: label position.row as 0-based (first row = row:0), distinct
from the 1-based row numbers used by A1 ranges and +dim-insert
--position, removing the row-base ambiguity.
2. chart: convert the three runnable examples whose JSON contains a
quoted sheet prefix ('Sheet1'!A1) from inline single-quoted
--properties '{...}' to a stdin heredoc (--properties - <<'JSON').
Inside an inline single-quoted string bash strips the inner quotes
around the sheet name (and splits names with spaces into words),
corrupting the JSON; a quoted heredoc delimiter performs no shell
substitution and preserves it. Adds a short note on the pitfall.
3. filter / filter-view: add the full conditions[].type x compare_type
enum table (text / number / multiValue / color and their respective
compare_type values and values shape), and call out the
equals/notEquals (with s) vs equal/notEqual (no s) gotcha. The docs
previously only showed two values via examples.
* docs(sheets): label +sheet-create --index as 0-based
The base flag description for +sheet-create's --index omitted the
coordinate base, while its siblings +sheet-move ("Target position
(0-based)") and +sheet-copy already state 0-based. Align the description
so the index base is unambiguous. Synced from the spec source
(flag-defs.json + workbook reference).
* fix(sheets): regenerate flag defs and fix asasalint in table io
* feat(sheets): add counta to chart aggregateType enum
Add `counta` (count non-empty cells, incl. text) to manage_chart_object
dim2.series[].aggregateType in the chart flag schema. `count` only counts
numeric cells, so counting occurrences of a text/category column renders an
empty chart; `counta` enables category frequency counts. Synced from the
sheet-skill-spec canonical schema.
* feat(sheets): make --target-position and --range mutually exclusive on +pivot-create
Both flags map to the same wire field (properties.range), so passing
non-default values for both is ambiguous. Mirror the
--target-sheet-id / --target-sheet-name mutex pattern: --target-position
takes priority over --range, and supplying both with non-default values
is rejected up front with a typed FlagErrorf. --target-position=A1 is
the documented default and is treated as "not set".
Add a symmetric validateCreateInput hook on objectCRUDSpec (alongside
the existing validateUpdateInput), wire it into objectCreateInput, and
inject the pivot-specific check on pivotSpec.
* feat(sheets): rework +workbook-create flags and --styles
- --values builds a type-less typed payload, writing through --sheets' batched set_cell_range path (raw passthrough preserves auto-detect; large tables batch; big ints via json.Number)
- drop --headers (subsumed by --values first row) and --header-style (typed header no longer auto-bold; use --styles instead)
- styles: deep-merge overlapping cell_styles/border_styles fields (was wholesale-replace which dropped fields); add manual border_styles validation (style/weight enums + sides) since --styles is on parseJSONFlagSkip and bypasses the schema validator
- regenerate flag-defs/flag-schemas/skills mirror from sheet-skill-spec (--styles flag + full per-side border schema)
* fix(sheets): add mention_type enum to set_cell_range cells schema
Constrain rich_text mention_type to the proto MENTION_FILE_TYPE set so a
file @mention with an out-of-enum value (e.g. 6 = cloud shared folder) is
rejected by the schema validator before it reaches the server and fails
pb serialization ("mentionFileInfo.fileType: enum value expected").
- data/flag-schemas.json: mention_type gains enum + per-value description
- lark_sheet_write_cells_test.go: cover reject (6) + allow (0 / 2 / 22)
* feat(sheets): implement pandas-split --sheets protocol for +table-put/+table-get/+workbook-create
Synced from sheet-skill-spec canonical (cli:table_put schema +
references). +table-put/+workbook-create accept the new shape via a
tableSheetIn -> tableSheetSpec normalize step (dtype string -> internal
type/format mapping). +table-get emits the same shape so the writer's
df_to_sheet and the reader's sheet_to_df round-trip cleanly.
isoDateToSerial now accepts the full ISO datetime form
(2024-01-15T00:00:00.000, including timezone suffixes) emitted by
df.to_json(date_format="iso"), not just yyyy-mm-dd. End-to-end verified
by the spec repo's contracts/python_helper_roundtrip script against a
real Lark spreadsheet on pandas 2.2 and 3.0.
* feat(sheets): add --dataframe Arrow IPC input for +table-put/+table-get/+workbook-create
Introduce a binary-typed twin of --sheets: --dataframe accepts an Arrow IPC
(Feather v2) payload that pandas' df.to_feather() writes, deriving dtypes and
per-column number formats from the Arrow schema. The two producers are mutually
exclusive and funnel through a shared resolver so +table-put and
+workbook-create stay in lockstep; +table-get gains --dataframe-out for
single-sheet reads. Also auto-grow a sub-sheet's row/column count before
writing so blocks past the backend's default 200x20 bounds no longer fail with
range-exceeds-sheet-bounds.
* docs(lark-sheets): remove financial modeling standards reference
Drop the lark-sheets-financial-modeling-standards.md reference doc and all
pointers to it from SKILL.md, core-operations, and visual-standards. Bump
skill version to 3.0.0.
* docs(lark-sheets): clarify cell-image vs float-image routing and fix reference self-references
Synced from sheet-skill-spec.
- Add a binding-based decision (does the image belong to a record and move with its row?) to route +cells-set-image vs +float-image-create across the SKILL entry, float-image and write-cells references.
- Add routing rows to the SKILL command cheat-sheet and warn against defaulting to float-image out of familiarity.
- Replace mislabeled 本 skill / 子 skill / 跨 skill wording in references with 本文 / reference names, matching the existing convention.
* feat(sheets): add --styles to +table-put for one-step typed write with styling
+table-put now accepts --styles (same shape as +workbook-create's --styles):
cell_styles merge into the set_cell_range matrix, while cell_merges /
row_sizes / col_sizes apply as their own tool calls after the write. The
styles payload is name-matched against the written sheets and validated up
front, so a malformed or mismatched style fails before any write lands.
Also points +sheet-create users to +table-put (auto-creates missing sheets)
when they need data/styles, via a runtime Tip and the lark-sheets skill
references. Flag is sourced from the upstream Base table and regenerated
through sheet-skill-spec (flag-defs.json / flag-schemas.json / gen file).
Adds unit tests (dry-run styles, name-mismatch reject, execute) and a
dry-run E2E (tests/cli_e2e/sheets/sheets_table_put_dryrun_test.go).
* docs(lark-sheets): point read-data to +sheet-info for hidden row/col identification
skip-hidden defaults to false (lossless reads), but the read primitives don't mark which rows/cols are hidden. Cross-reference +sheet-info --include hidden_rows,hidden_cols + row_indices/col_indices so agents can identify hidden ranges when they need to filter or interpret hidden data.
Synced from sheet-skill-spec.
* feat(sheets): document link requirement for @document mentions in cells flag schema
@document mentions (mention_type != 0) must pass link (doc URL) to render a
clickable card; @user mentions (mention_type=0) don't need it. Synced from the
upstream tools-schema.
* fix(sheets): reject cond-format attrs whose shape mismatches rule_type
A conditional-format rule created with --rule-type colorScale but
cellIs-shaped attrs ({compare_type,value}, no color) was accepted by
the CLI and written through to the server, producing a color-less
color-scale segment. That dirty data crashes the frontend on snapshot
deserialization, so the spreadsheet can no longer be opened (5005).
The per-entry schema check can't catch this: properties.attrs.items is
a oneOf over all nine attr shapes and passes as soon as any branch
matches, blind to the sibling rule_type — {compare_type,value} matches
the cellIs branch even when rule_type says colorScale. The tool side
maps attrs blindly by rule_type and only validates dataBar count and
iconSet ordering, so the gap reaches the data layer.
Add a cross-field validator (validateCondFormatAttrs) wired into both
create and update via the new objectCRUDSpec.validateCreateInput hook
(twin of validateUpdateInput). It enforces, per rule_type, the keys
every attrs entry must carry — mirroring the tool's converter contract
— and treats an empty required string (notably color) as missing.
Rule types that take no attrs (duplicateValues / uniqueValues /
containsBlanks / notContainsBlanks) and updates that omit rule_type are
left to the server.
* test(sheets): guard condFormatAttrsRequired against flag-schemas drift
Add TestCondFormatAttrsRequired_MatchesSchemaOneOf, comparing the
hand-maintained condFormatAttrsRequired table against the embedded
flag-schemas.json attrs oneOf (multiset of required-key sets, for both
create and update). The cross-field validator only holds if its
per-rule_type required keys mirror the schema branches, and the two
share no compile-time link — this pins them together so a future schema
sync that adds/drops a required key can't silently desync the table.
* fix(sheets): default +table-get to full used range, not A1 current region
+table-get without --range anchored its current_region probe at A1, so an
internal blank row or column silently truncated everything past it — agents
then treated the partial data as complete (the pro016 / pro025 incident).
- Probe the used range over the full physical grid (row_count × column_count
from the workbook structure) so it spans internal blank rows/columns; fall
back to the legacy A1 anchor when dimensions are unknown.
- Emit the actually-read `range` on every sheet so callers can detect
truncation (get_cell_ranges has no has_more flag).
- Fix the same A1-anchor bug in append mode's last-data-row probe, which could
otherwise overwrite data past an internal blank row.
- Add unit + dry-run/live E2E coverage; refresh synced skill docs.
* docs(sheets): fix csv-get current_region guidance to cross-check row_count
current_region is a blank-row/column-bounded block, not the true sheet extent:
an internal blank row truncates it, so it can miss rows past the gap. The
read-data reference previously called it the "真实数据边界" and told agents to
prefer it over row_count — which drove the "read only to current_region's last
row, miss the tail" failure.
- current_region: warn it can be both smaller (internal blank rows truncate)
and larger (trailing summary/signature rows) than the real data range.
- csv-get output contract: clarify its row_count/col_count is the returned size
(= actual_range), not the physical sheet size; has_more only reflects the
current range, not whether the whole sheet was read.
- "确定数据范围的正确流程": add a step to cross-check against +workbook-info's
physical row_count and probe past current_region's last row for data beyond an
internal blank row.
* fix(sheets): collapse duplicate validateCreateInput from bad merge resolution
A prior merge kept both branches' independently-added validateCreateInput
fields on objectCRUDSpec with conflicting signatures (pivot's
func(rt, input) and cond-format's func(input)), plus both call sites in
objectCreateInput, which failed to compile (validateCreateInput redeclared).
Collapse to the single richer func(rt flagView, input) signature and one
call site. cond-format's validateCondFormatAttrs (func(input), still shared
with validateUpdateInput) is wrapped in a closure that ignores rt. Both
behaviors are preserved: pivot --target-position/--range mutex and
cond-format attrs-shape-vs-rule_type validation.
* refactor(sheets): migrate legacy error helpers to typed errs in sheets domain
golangci-lint forbidigo (errs-no-legacy-helper / errs-no-bare-wrap) flagged
the table I/O, workbook, and dataframe shortcuts that landed on this branch:
93 common.FlagErrorf and 48 fmt.Errorf calls.
- Replace every common.FlagErrorf with common.ValidationErrorf (typed
*errs.ValidationError, same signature) across workbook / table_io /
dataframe / object_crud.
- writeDataframeOut's two final --dataframe-out write failures become typed
errs.NewInternalError(SubtypeFileIO, ...).WithCause(err).
- applyWorkbookCreateVisualOps now passes the typed callTool error through
unchanged (re-wrapping would downgrade classification) and attaches the
failing op as a recovery hint only when none is set.
- The remaining fmt.Errorf are genuine intermediate errors that the command
layer re-wraps into typed validation errors (buildTypedCell / Arrow
decode-encode) or surfaces as a partial_success message string
(writeTypedSheets via tablePutPartial); each carries a //nolint:forbidigo
with that reason, per the lint guidance.
No behavior change: error messages and partial-success shapes are preserved;
gofmt, go vet, golangci-lint (0 issues) and sheets tests all pass.
* fix(shortcuts): clarify single-stdin constraint in flag help and error hint
Input flags advertised '(supports @file, - for stdin)' per flag, leading
AI agents to write '--a - <x --b - <y' where the second '<' silently
clobbers the first and the first flag reads the wrong payload. A process
has a single stdin, so at most one flag per call can use '-'.
- Reword the generated help hint to '- reads stdin (one flag per call;
use @file for others)'.
- Add an actionable .WithHint to the stdin-conflict validation error
pointing callers to @file for the extra flags.
- Assert the new hint in TestResolveInputFlags_DuplicateStdin.
* feat(sheets): +cells-get/+csv-get --max-chars 默认值 200000 → 500000
放宽默认防爆上限。flag_defs_gen.go 由 go generate 重生；flag_defs_test.go
的 expected default 同步；flag-schemas.json schema_version 2 → 3 是上游
spec-tables 架构调整带来的元数据 bump，与本业务改动无关、go:embed 不解析
该字段、无功能影响。
Synced from sheet-skill-spec@93f7a78.
* docs(lark-sheets): sync from spec — +csv-put 含逗号公式正例 + 收敛警示标签
源同步自 sheet-skill-spec：write-cells 补含逗号公式 RFC 4180 转义正例与结构化写入优先指引；全 reference 收敛「高频致命错误」类标签。
* docs(lark-sheets): sync from spec — --max-chars 放出为可见 flag + 落盘优先指引
源同步自 sheet-skill-spec：--max-chars 放出（默认 500000，可调小避免大输出被 Bash/终端转存为文件、改 has_more 分页）；read-data 增「大数据优先落盘」指引。
* feat(sheets): 写操作报错增强 + --token 别名
- 复合 JSON shape 校验失败时报错附 --print-schema 提示，agent 可直接拿到精确结构（pro26 头号：+cells-set --cells 反复猜 shape）
- JSON 解析失败且该 flag 支持 stdin 时提示改用 stdin（公式/引号/逗号内联到 shell 被转义弄坏 JSON）
- --token 作为 --spreadsheet-token 的解析期别名：复用 sheets 已有 PostMount 钩子 + pflag normalize，仅 sheets 包，common 零改动
* docs(lark-sheets): sync from spec — set+H 改单引号 / 速查表补臆造命令名 / workbook-import 引导
* fix(sheets): migrate +table-put to typed error contract
The merge from main brought in #1449 (retire legacy error envelopes),
which removed output.ExitError / output.ErrDetail and forbids
constructing them. Port tablePutPartial off the legacy envelope:
- no sheets written -> typed errs.APIError (plain failure)
- some sheets written -> ok:false result via runtime.OutPartialFailure
carrying written_sheets, returning the partial-failure exit signal
Also fix two drifts the same merge introduced:
- regenerate flag_defs_gen.go to match the committed flag-defs.json
- update the --max-chars flag test to assert visible (no longer hidden)
* docs(lark-sheets): sync from spec — set+H 告诫通则化（移入 stdin 段）
* feat(sheets): styles 接受 halign/valign 等对齐字段别名
把模型常幻觉的 horizontal_align / halign / vertical_align / valign 映射到
规范字段 horizontal_alignment / vertical_alignment，覆盖 --styles 与 typed
--cells；与规范字段冲突时报错而非静默择一。同步 lark-sheets skill 文档补
对齐字段说明 + --print-schema --flag-name styles 提示。
* feat(sheets): resolve wiki URLs to the backing spreadsheet for --url
Sheets shortcuts only accepted /sheets/ and /spreadsheets/ URLs via --url.
A /wiki/<node_token> URL was rejected with "must be a spreadsheet URL"
because the wiki node_token is not a spreadsheet token: resolving it to the
backing spreadsheet needs a wiki get_node call, which Validate/DryRun (kept
network-free) must not make.
Mirror the existing slides/doc/drive two-stage pattern:
- parseSpreadsheetRef classifies --url / --spreadsheet-token network-free
into a sheet token or an (unresolved) wiki node_token.
- resolveSpreadsheetTokenExec (Execute only) resolves a /wiki/ node_token
via wiki get_node, verifies obj_type=sheet, and returns the obj_token.
The wiki:node:read scope is enforced on this path only, so non-wiki
invocations are unaffected.
- resolveSpreadsheetToken stays network-free for Validate/DryRun, passing
the node_token through unchanged.
All 47 Execute paths (including +batch-update and +workbook-export) switch
to the Exec resolver; Validate/DryRun keep the network-free one. No tool
schema change: the CLI feeds the resolved spreadsheet token as excel_id, so
this is a pure CLI-layer change.
Tested: unit (parse classification + wiki get_node e2e via httpmock) and
live end-to-end against a real wiki spreadsheet (read: +workbook-info,
+cells-get, +csv-get; write: +sheet-create, +sheet-rename, +csv-put).
* docs(sheets): note --url accepts wiki URLs (synced from spec)
* fix(sheets): match --url path segment via url.Parse, not substring
parseSpreadsheetRef classified /wiki/ with strings.Index over the whole URL, so a /sheets/ link whose query or fragment merely contained /wiki/ (e.g. .../sheets/sht?from=/wiki/x) was hijacked into a get_node call. Now parse the URL and match /sheets/, /spreadsheets/, /wiki/ only as a path prefix, mirroring slides parsePresentationRef which already fixed this class. Drop the substring helpers. Also align wiki resolution with slides: CallAPITyped (typed error + log_id) and classify an incomplete get_node response as InternalError instead of a --url validation error. Add regression tests for query/fragment /wiki/ and incomplete node.
* fix(sheets): satisfy errorlint/copyloopvar + regen flag defs
- helpers_test.go: drop the Go 1.22+ redundant `tc := tc` loop copy
(copyloopvar).
- lark_sheet_dataframe.go, lark_sheet_table_io.go: switch the
intermediate-error fmt.Errorf calls from %v to %w so errorlint passes.
Behavior unchanged — these errors are always rewrapped into typed
validation errors at the command layer.
- flag_defs_gen.go: regenerate from data/flag-defs.json (drift from the
wiki-URL merge).
* ci: allow Apache Arrow module in license check
Arrow is Apache-2.0 overall, but it vendors c-ares (LicenseRef-C-Ares,
ISC-like) inside the module which go-licenses classifies as Unknown and
the strict disallowed_types=...,unknown gate rejects.
Pass --ignore github.com/apache/arrow/go/v17 since Arrow is required by
sheets +table-put / +table-get / +workbook-create --dataframe (Arrow IPC
ingest) and the vendored c-ares is not redistributed by us.
* fix(sheets): resolve wiki URL in +range-move/+range-copy Execute
transformExecuteFn (the named Execute helper shared by +range-move and +range-copy) still called the network-free resolveSpreadsheetToken, so a /wiki/ URL reached transform_range as an unresolved node_token and failed. #1519's sweep over Execute hooks only rewrote inline closures; this is the only Execute backed by a named helper. Switch it to resolveSpreadsheetTokenExec (Validate/DryRun stay network-free) and add a +range-move wiki-URL regression test.
* refactor(sheets): drop +table-put manual capacity grow; rely on set_cell_range auto-grow
set_cell_range now auto-grows the sub-sheet to fit the write, so the
ensureSheetCapacity helper (and its modify_sheet_structure dim-insert
call before each write) is no longer needed. This also closes a data-
safety hole flagged in review: inserting before the last existing row
could push real data down into the area set_cell_range was about to
write, and allow_overwrite=false could not protect against it because
the structural insert had already mutated the sheet by the time the
write-collision check ran.
Verified end-to-end against a real spreadsheet: +table-put writing
300x25 into a fresh Sheet1 (default 200x20) succeeds in one write and
the sheet ends up 301x25.
* fix(sheets): close --dataframe stdin guard hole
--dataframe is binary and bypasses the common Input resolver, which is
where the existing single-stdin guard lives. Result: an invocation like
+table-put --dataframe - --styles - was accepted, then one of the two
consumers raced for stdin and the other silently saw an empty stream.
Add a stdinConsumed marker on RuntimeContext that both consumers share:
common.resolveInputFlags sets it when an Input flag uses '-', and
readDataframeBytes both checks and sets it. A second consumer is
rejected up front with an actionable hint pointing at @file.
Flagged in code review (lark_sheet_dataframe.go:93).
* fix(sheets): harden +table-put / +table-get input validation and round-trip safety
Four review-flagged correctness gaps in table I/O, all bundled because
they touch the same file:
1. --sheets accepted trailing data after the first JSON value
(json.Decoder does not surface that, unlike json.Unmarshal). A new
decoderExpectEOF helper rejects e.g. `--sheets '{...} oops'` with a
typed validation error instead of letting the leading object pass
through and surface as a confusing downstream failure.
2. +table-get with a duplicate header (e.g. `amount, amount`) used to
read back successfully — the dtypes map silently collapsed to one
entry — and only failed later on +table-put because the writer
rejects duplicate column names. Fail fast at read time with an
actionable hint to rename or pass --no-header. --no-header mode is
exempt (fallback col<N> names are always unique).
3. +table-put dry-run rendered an invalid range like A1:C0 when
header=false with rows=[]. tablePutFullRange returns "" for an
empty matrix or zero columns instead of building a degenerate
rectangle.
4. +table-get with --sheet-id and a get_workbook_structure miss (read
failure or selector mismatch) used to return a target with
name="", which then broke +table-get → +table-put round-trip (the
writer requires a non-empty sheet name). Fall back to using the id
as the name.
End-to-end verified against a real spreadsheet: trailing data, duplicate
header, and --no-header fallback all behave as advertised.
* fix(sheets): apply +workbook-create style-only ops instead of silently dropping them
A +workbook-create call carrying only cell_merges / row_sizes / col_sizes
(no --values / --sheets and no cell_styles) used to create the workbook
but silently drop the requested visual ops. Two reasons, both fixed:
- workbookCreateStyleDimensions only counted cell_styles when computing
the write extent, so cell_merges / row_sizes / col_sizes always
contributed 0 → buildValuesPayload returned a nil payload → Execute
skipped writeTypedSheets entirely → no visual ops ran. Extend the
helper to fold the merge / resize ranges in.
- Pure row_sizes / col_sizes payloads can never expand a cell rectangle
(they are dimension ranges, not cell ranges), so even with the extent
fix Execute would still skip the write path. Add a no-data branch:
when payload == nil but a styles item is present, look up the default
sheet and apply visual ops directly via applyWorkbookCreateVisualOps.
The dry-run plan mirrors this so the preview shows the visual ops.
Also picks up the --values trailing-JSON-data EOF check (mirror of the
--sheets one in lark_sheet_table_io.go).
End-to-end verified against a real spreadsheet: a cell_merges-only
+workbook-create now produces a sheet with merged_cells_count: 1.
* fix(sheets): preserve causes and render messages cleanly for typed validation errors
common.ValidationErrorf goes through fmt.Sprintf, which does not support
%w — the seven call sites that used `%w` were rendering the cause as
literal `%!w(*fmt.wrapError=&{...})` and dropping the cause from the
typed-error chain (so callers couldn't errors.As back to the underlying
error).
Switch each to `%v` for clean rendering and attach the cause via
.WithCause(err) so the typed contract is preserved. Touched call sites:
- lark_sheet_dataframe.go: --dataframe Arrow decode / stdin read / file
read failures (3 call sites).
- lark_sheet_table_io.go: --sheets invalid JSON, payload-validate
per-cell coercion error, buildSheetMatrix per-cell error,
--dataframe-out arrow encode failure (4 call sites).
End-to-end verified against a real spreadsheet: both invalid-JSON and
typed-cell errors now render readable messages instead of %!w(...).
* sync(sheets): pick up +sheet-{show,hide}-gridline in +batch-update schema
Mirror of the sheet-skill-spec change adding the two gridline shortcuts
to cli-schemas.json batch_update.operations.shortcut enum. Synced from
the upstream canonical via generate:cli + sync:cli.
Verified end-to-end on a real spreadsheet — +batch-update with a
+sheet-hide-gridline op passes schema validation and the backend run
returns succeeded: 1.
* sync(sheets): pick up +workbook-export UX clarification from spec
Mirror of the sheet-skill-spec update that documents +workbook-export's
default-no-download behavior and its relationship to drive +export
--doc-type sheet. Synced from canonical via generate:cli + sync:cli +
go generate.
End-to-end verified against a real spreadsheet:
- Omit --output-path → ok:true, downloaded:false, file_token returned
- Pass --output-path ./crfix_test.xlsx → ok:true, file saved
(17892 bytes), saved_path returned
The --help output for +workbook-export now states the default behavior
and points callers at `drive +export --doc-type sheet` when they need
the --output-dir / --file-name / --overwrite split.
* test(sheets): assert typed errs.Problem instead of err.Error() substrings
Per the coding guideline "Error-path tests must assert typed metadata via
errs.ProblemOf (category / subtype / param) and cause preservation, not
message substrings alone." — sweep through every error-path assertion in
the sheets domain and replace the
`strings.Contains(stdout+stderr+err.Error(), ...)` pattern with two
small helpers landed in helpers_test.go:
requireProblem(t, err, wantCategory, wantSubtype, msgContains)
-> *errs.Problem
requireValidation(t, err, msgContains)
-> *errs.ValidationError // shorthand for CategoryValidation +
// SubtypeInvalidArgument; lets callers
// also assert .Param / .Params / .Cause
~60 assertion sites across 18 test files now check the typed envelope
shape, with message-substring checks moved onto the returned Problem
(.Message / .Hint / .Param). The substring is preserved as a sanity
check rather than the sole assertion, so a category drift like
validation → internal would now fail loudly instead of slipping past.
Cases intentionally left as substring (each with a one-line reason):
- Errors that come straight from cobra's native flag parser (untyped
*errors.errorString — e.g. "required flag(s) ... not set", mutually-
exclusive groups). Re-typing these needs a custom FlagErrorFunc and
is out of scope here.
- Intermediate errors from decodeArrowToSheet that the caller wraps
into a typed envelope (`//nolint:forbidigo` reason). Those unit
tests assert the unwrapped intermediate directly.
One production tweak:
- shortcuts/sheets/flag_schema.go: printFlagSchemaFor returns typed
*errs.ValidationError (with WithParam("--flag-name") on the
unknown-flag branch) instead of raw fmt.Errorf. The framework
already wraps this when called via --print-schema, so user-facing
behaviour is unchanged; direct callers (and tests) now get the
typed envelope.
Verified: go test ./shortcuts/sheets/... passes; golangci-lint
--new-from-rev=origin/main reports 0 issues.
* test(common): assert typed errs.Problem instead of err.Error() substrings
Mirror of the sweep just landed in shortcuts/sheets: replace error-path
substring assertions with typed-envelope checks via two small helpers
landed in a new shortcuts/common/typed_error_assertions_test.go:
requireProblem(t, err, wantCategory, wantSubtype, msgContains)
-> *errs.Problem
requireValidation(t, err, msgContains)
-> *errs.ValidationError // shorthand for CategoryValidation +
// SubtypeInvalidArgument; lets callers
// also assert .Param / .Params / .Cause
8 sites moved to typed assertions across runner_jq_test.go,
mcp_client_test.go, drive_media_upload_typed_test.go, and
runner_input_test.go (the input tests already used a typed-param helper;
this just retargets the substring follow-up onto the typed Message).
Sites intentionally left as substring + comment (production returns raw
fmt.Errorf, not a typed envelope):
- runner_botinfo_test.go (6 sites): BotInfo / fetchBotInfo wrap upstream
errors with fmt.Errorf so the SDK-level message ([99991], 403,
invalid character, etc.) shows through.
- runner_args_test.go (4 sites in 2 tests): rejectPositionalArgs returns
raw fmt.Errorf to satisfy cobra's PositionalArgs contract.
- permission_grant_test.go (2 sites): assert on stderr / hint strings,
not error messages — already out of the err.Error() substring class.
No production code changes.
Verified: go test ./shortcuts/common/... passes;
golangci-lint --new-from-rev=origin/main ./shortcuts/common/... reports
0 issues.
* fix(sheets): plug four +table-put / +table-get correctness gaps flagged in CR
Four review-flagged bugs, all in lark_sheet_table_io.go (bundled because
they touch the same file and the same +table-put / +table-get domain):
1. +table-get --dry-run dropped the --sheet-id / --sheet-name selector
from the get_cell_ranges body, while Execute always passed it. Agents
that validate the dry-run shape and then run live would see a request
shape mismatch. The dry-run now calls sheetSelectorForToolInput so
the body matches Execute.
2. isDateNumberFormat used a simple `strings.ContainsRune(_, 'y')` so
number formats like "JPY #,##0" (a currency prefix that happens to
contain a lone 'Y') were misread as date formats — round-tripping
integer cells out as ISO dates. The detector is now token-aware:
it skips quoted "...", `\\x`-escaped, and `[...]` bracket sections,
and only fires on an unescaped `yy` (a real Excel year token).
3. sheetCreateDims sized new append-mode sheets by `headerOn(s)` only,
but writeSheetData forces a header on empty append sheets when
Header == nil. Near 50000 rows / 200 cols this created the sheet one
row short and the follow-up set_cell_range bounced off the backend
ceiling. Size now matches the forced-header logic exactly.
4. tableGetTargets fallback paths (read-failure / selector mismatch on
--sheet-id) returned a target with name="" — already corrected for
--sheet-id structure-success path in 086876d2, but the structure-
failure fallback still left it empty. Use the id as the name there
too so the +table-get → +table-put round-trip never breaks on a
nameless sheet.
End-to-end verified against a real spreadsheet:
- table-get --dry-run with --sheet-name / --sheet-id both render the
selector field in the get_cell_ranges body
- A real round-trip (typed put → get) preserves dtypes + formats
* fix(sheets): bound --dataframe memory use with byte / row / column caps
readDataframeBytes used to read the whole Arrow file unbounded — a
stdin / file > 1 GiB would OOM the CLI long before the backend
per-sheet ceilings kicked in. decodeArrowToSheet then materialized
every record into [][]interface{} regardless of size.
Three caps now match the backend's per-sheet hard ceilings:
- byte cap: 256 MiB (covers worst-case 200×50000 cells × ~25 B Arrow
overhead). File path pre-Stat()s before opening; both file and stdin
paths read through io.LimitReader so an oversized input is rejected
without allocating the full payload.
- column cap: 200, checked at schema-decode time before allocating any
per-column slices.
- row cap: 50000, checked during record-batch iteration so a 1M-row
Arrow file is rejected mid-stream instead of fully decoding first.
End-to-end verified against PPE — a 257 MiB file is rejected at file-
Stat with a typed validation error before any read happens.
* fix(drive): wrap +export ctx cancellation/deadline as typed errs.NetworkError
The poll loop in RunExport returned ctx.Err() directly in two places —
on the inter-attempt sleep cancel and on the pre-attempt deadline check.
That let context.Canceled / context.DeadlineExceeded escape as untyped
errors at the cobra layer, bypassing the typed-error contract every
other failure path already honors.
Add wrapExportContextErr that maps both into errs.NewNetworkError with
SubtypeNetworkTransport / SubtypeNetworkTimeout respectively and
preserves the cause via .WithCause(err), so callers can still
errors.Is(err, context.Canceled) downstream.
CR-flagged at drive_export.go:229 / :234.
* ci(license): narrow Apache Arrow workaround with a follow-up assertion
The dependency-license check still has to --ignore Apache Arrow wholesale
because go-licenses' classifier parses its LICENSE.txt as a single license
and mis-reports the module as LicenseRef-C-Ares / Unknown (Arrow inlines
the c-ares 3rdparty notice alongside its own Apache-2.0). Re-classifying
on our side isn't possible without changing go-licenses itself.
The CR concern was that --ignore is too wide — a future Arrow re-license
or new inlined dep would silently sail through. Add a follow-up step that
re-checks Arrow's LICENSE.txt independently: it must still open with
"Apache License" AND must still inline the c-ares 3rdparty notice (the
two facts that make the --ignore safe today). If either invariant breaks,
CI fails here and forces a human to re-evaluate the ignore.
Verified locally — both assertions pass against the current pinned
Arrow v17.
* sync(sheets): pick up +table-put payload-shape doc corrections from spec
Mirror of the sheet-skill-spec change that fixes three places teaching
an invalid +table-put payload shape — the typed protocol only has
columns / data / dtypes / formats (no formula field) and must always
be wrapped in an outer {"sheets":[...]} envelope. write-cells and the
SKILL.md decision table previously used the wrong field names (type /
format) and pointed users at +table-put for formula writes, which the
shortcut can't actually accept.
Synced from upstream canonical via generate:cli + sync:cli.
* test(sheets/e2e): add E2E coverage for new shortcuts + typed workbook-create
AGENTS.md requires a dry-run E2E for every new shortcut and a live E2E
for new flows. Three new files cover the four shortcuts this branch
adds or materially changes:
- sheets_gridline_dryrun_test.go — pins +sheet-show-gridline /
+sheet-hide-gridline as a single modify_workbook_structure call with
the right operation name (show_gridline / hide_gridline) and
sheet_id, so an op-name typo would trip CI before any live run.
- sheets_workbook_import_dryrun_test.go — pins +workbook-import as a
two-step plan (drive media upload + drive import-task create) with
the doc type hard-coded to "sheet" — the wrapper's whole reason for
existing on top of generic drive +import. --name reaches file_name
on the wire; file_extension is sniffed from the local file.
- sheets_table_put_typed_workflow_test.go — two live workflows running
against a freshly created spreadsheet. The first runs the full
typed +table-put → +table-get round-trip (date / numeric / object
columns with custom number_format) and asserts the dtype + format
contract holds end-to-end. The second exercises the typed
+workbook-create --sheets path: create + write in one shortcut, the
payload sheet name adopts the workbook's default sheet (no empty
"Sheet1" left behind), and the typed contract still survives the
read-back.
End-to-end verified locally (user identity): typed put round-trips
preserve dtypes (date → datetime64[ns], numeric → float64, object →
object) + formats verbatim; workbook-create adopts the named sheet as
the first sheet with the same typed shape intact.
* sync(sheets): pick up sheets_df.py — pandas ↔ JSON skill script from spec
Mirror of the sheet-skill-spec change that adds a DataFrame ↔ JSON
bridge as a skill-bundled Python script instead of inside the CLI
binary. Per PR #1355 review (docx NcmxdRo2yoZ4OXxoMUZcxRZ7nHd, §4.2):
keep the CLI a thin JSON/REST client; pandas / Arrow editing lives in
the caller's Python process. Synced from canonical via generate:cli +
sync:cli.
- skills/lark-sheets/scripts/sheets_df.py (new): pandas DataFrame ↔
one sheet, .parquet / .feather / .arrow / .csv / .json. Shells out to
`+table-put` / `+table-get` over typed JSON — no CLI changes.
- SKILL.md decision tree + write-cells.md +table-put section: explicit
pointers so pandas users land on the script instead of hand-rolling
the `--sheets` payload.
End-to-end verified against PPE: 3-row DataFrame (datetime / float /
object) round-trips parquet → script put → real sheet → script get →
parquet with dtypes preserved.
* Revert "sync(sheets): pick up sheets_df.py — pandas ↔ JSON skill script from spec"
This reverts commit 2964983b92.
* sync(sheets): pick up sheets_df.py + doc DRY cleanup from spec
Mirror of the sheet-skill-spec change that ships a 32-line helper-only
sheets_df.py (df_to_sheet + sheet_to_df) and removes the corresponding
inline `def` blocks from three reference docs.
- skills/lark-sheets/scripts/sheets_df.py (new): pandas DataFrame ↔
one +table-put / +table-get sheet, importable as a library. Same
helper pair the docs already taught, lifted out of the prose so
callers can `from sheets_df import df_to_sheet, sheet_to_df`.
- lark-sheets-write-cells.md / lark-sheets-read-data.md /
lark-sheets-workbook.md: drop the inline helper definitions; keep
the usage examples (single/multi-sheet, round-trip) and switch them
to import-from-script. workbook reference's +workbook-create
--sheets section now points pandas users at the helper directly
(was previously a textual reference back to write-cells).
End-to-end verified against PPE (--as user):
- +workbook-create with df_to_sheet for three sheets (income / balance
/ cashflow): create ok, dtypes (datetime64[ns] / float64) + formats
(#,##0 / 0.0% / yyyy-mm-dd) survive on read-back through sheet_to_df.
- read → pandas mutate → write-back round-trip preserves both data
and formats.
* chore: drop accidentally-committed __pycache__/ and gitignore .pyc
The previous commit (5fac9c39) shipped sheets_df.py and inadvertently
included its `__pycache__/sheets_df.cpython-312.pyc` — local Python
import created the bytecode cache during PPE round-trip verification and
`git add skills/lark-sheets/` swept it in.
Remove the pyc and add Python bytecode patterns to .gitignore so the
skill-bundled helper scripts don't pull cache files into future commits.
* refactor(sheets): drop --dataframe / --dataframe-out + apache/arrow dep
Per the design review at NcmxdRo2yoZ4OXxoMUZcxRZ7nHd, the Arrow IPC binary
input/output channel adds a heavy columnar runtime to the CLI for no new
capability — the typed JSON --sheets path already covers everything, and
the column-major / zero-copy advantages collapse the moment the CLI re-
encodes into the row-oriented sheets OpenAPI JSON body. Removing it also
lets us drop the `--ignore github.com/apache/arrow/go/v17` license-check
escape hatch.
Deleted:
- shortcuts/sheets/lark_sheet_dataframe.go (+ test)
- --dataframe branches in +table-put / +workbook-create
- --dataframe-out branch in +table-get
- StdinConsumed / MarkStdinConsumed exported methods (the binary stdin
reader was the only out-of-band consumer); internal stdinConsumed
guard against duplicate `-` input flags stays
- apache/arrow/go/v17 + transitive deps via `go mod tidy`
- CI go-licenses --ignore for arrow and the LICENSE.txt assertion step
- --dataframe / --dataframe-out coverage in skill references
Pandas users keep the round-trip via the existing skill script
skills/lark-sheets/scripts/sheets_df.py over the JSON path.
The full pre-removal state is preserved on branch feat/sheets-arrow-stash.
Upstream sheet-skill-spec follow-up: the two flag rows in the canonical
spec + base table tblV2F6fqIjyCFQW must also be dropped so the next sync
does not re-add them.
* sync(sheets): pick up --sheets one-liner fix from spec
Mirrors sheet-skill-spec 5562f83. The +table-put / +workbook-create
--sheets flag descriptions (and the --print-schema description on the
sheets array) now point at the existing df_to_sheet helper instead of
the previous misleading one-liner that produced a dict missing the
outer {"sheets":[...]} envelope and the per-sheet `name`. Agents that
copy-paste the description verbatim now build a valid payload.
Auto-synced via spec's generate:cli + sync:consumers; go generate
./shortcuts/sheets/... regenerated flag_defs_gen.go so its embedded
flagDefs stays byte-equal to data/flag-defs.json.
* test(sheets/e2e): close E2E coverage gaps for newly added shortcuts
AGENTS.md requires both dry-run and live E2E for every newly registered
shortcut, and behavior-changing refactors need at least the matching
half. Three gaps remained on feat/lark-sheets-develop:
- +sheet-show-gridline / +sheet-hide-gridline (new): only dry-run E2E.
Add sheets_gridline_workflow_test.go — create a real spreadsheet,
toggle hide then show against a live sub-sheet, assert ok=true on
both (gridline state is write-only — there is no read-back field on
+sheet-info / +workbook-info — so a successful envelope is the
meaningful signal; the dry-run E2E already pins the wire shape).
- +workbook-import (new): only dry-run E2E. Add
sheets_workbook_import_workflow_test.go — write a local CSV, run
the full upload → create-task → poll, assert ready=true with a
sheet token, +info confirms the imported workbook is reachable,
cleanup deletes the spreadsheet.
- +workbook-export refactor (no-download default changed): had live
E2E but no dry-run E2E in tests/cli_e2e/. Add
sheets_workbook_export_dryrun_test.go — pin the three sheet-
specific differences vs drive +export: type=sheet hard-coded,
csv mode routes --sheet-id onto sub_id (xlsx mode omits it), and
--output-path maps onto the dry-run plan's top-level output_dir.
Also pins the csv-without-sheet-id validation error.
* refactor(sheets): unify workbookCreatedButFillFailed with OutPartialFailure
Three "made it halfway and stopped" exits in the sheets domain previously
disagreed on shape, which made the post-failure recovery flow hard for
agents to predict from one command to another:
- +table-put partial write → exit 1, stdout ok:false envelope
- +table-put zero-sheet write → exit 1, stderr api/server_error
- +workbook-create create-but-fill → exit 2, stderr validation/failed_precondition
OutPartialFailure exists exactly for "the side effect landed but the
follow-up didn't" — it stamps an ok:false result envelope on stdout
(carrying the state the caller needs to recover) and returns the bare
partial-failure exit signal. The workbook-create fill-failure path was
the odd one out: it surfaced as a typed failed_precondition error on
stderr, which agents couldn't tell apart from a plain validation refusal
even though the spreadsheet really did exist and a retry / cleanup was
possible.
Migrate workbookCreatedButFillFailed onto OutPartialFailure so the four
call sites in +workbook-create's Execute (sheet-resolve failure, initial
fill failure, style-only resolve failure, style-only apply failure) emit
the same envelope shape +table-put's partial write does:
{
"ok": false,
"data": {
"spreadsheet_token": "shtNEW",
"reason": "spreadsheet shtNEW created but initial fill failed",
"hint": "the spreadsheet exists; retry the fill … or delete it",
"cause": {"category": "...", "subtype": "...", "message": "..."}
}
}
The inner failure's typed problem (category / subtype / message) is
flattened into the `cause` field so agents stay diagnosable from the JSON
envelope alone, instead of having to errors.Unwrap a Go error.
Updated TestExecute_WorkbookCreate_FillFailureKeepsToken to assert the
new shape (ok:false envelope on stdout, *output.PartialFailureError exit
signal, structured cause carrying the underlying invalid_response
subtype) — preserving the original test intent (token must survive for
recovery; inner cause must stay diagnosable) under the new contract.
* chore(sheets): three review nits — WithCause + stale comment + unexport
- shortcuts/sheets/flag_schema_validate.go:106 — composite-JSON shape
validation was wrapping vErr's message into a typed sheets validation
error without preserving vErr as the typed cause; add the missing
.WithCause(vErr) so errors.Unwrap and ProblemOf still find the
underlying validator error (matches every other typed-error chain
helper in the file).
- shortcuts/sheets/lark_sheet_batch_update.go:92 — comment claimed
batchUpdateInput returns "FlagErrorf-typed errors", but FlagErrorf no
longer exists (the typed-error migration replaced it with
common.ValidationErrorf / errs.ValidationError); update the comment
to reflect what is actually returned.
- shortcuts/drive/drive_export.go:121 — drop the ValidateExport public
alias and rename to validateExport. sheets +workbook-export reuses
RunExport / PlanExportDryRun from this package but inlines its own
(sheet-specific) Validate, so there is no cross-package call site —
ValidateExport was a misleading sibling of the genuinely-shared
ValidateImport. Comment added to record the asymmetry so future
readers do not export it back.
* chore(deps): drop stale indirect bumps left by the arrow removal
The earlier --dataframe / --dataframe-out + apache/arrow/go/v17 removal
deleted the arrow consumer but left two indirect lines in go.mod pinned
to the versions arrow had pulled in:
- github.com/kr/text v0.2.0
- golang.org/x/exp v0.0.0-20240222234643-814bf88cf225
With arrow gone, larksuite/cli was the only requirer of those exact
versions; every real consumer needs lower ones (kr/pretty wants
kr/text v0.1.0; charmbracelet/huh wants x/exp …20231006; xo/terminfo
wants x/exp …20220909). Removing the two indirect lines and running
`go mod tidy` lets MVS pick the real-consumer versions and drops the
explicit indirect entries entirely — go.mod net-diff against main is
now zero for this branch.
Verified locally: go build ./...; go test ./shortcuts/sheets/...
./shortcuts/drive/... ./shortcuts/common/... ./internal/auth/...
./cmd/auth/... — all green.
---------
Co-authored-by: zhengzhijie <zhengzhijie.j@bytedance.com>
Co-authored-by: Chenweifeng-bd <chenweifeng.1534@bytedance.com>
7002 lines
281 KiB
JSON
7002 lines
281 KiB
JSON
{
|
||
"schema_version": "3",
|
||
"flags": {
|
||
"+batch-update": {
|
||
"operations": {
|
||
"type": "array",
|
||
"description": "要批量执行的 CLI shortcut 操作列表，按声明顺序串行执行；任一失败立即中断。",
|
||
"items": {
|
||
"type": "object",
|
||
"required": [
|
||
"shortcut",
|
||
"input"
|
||
],
|
||
"properties": {
|
||
"shortcut": {
|
||
"type": "string",
|
||
"enum": [
|
||
"+cells-set",
|
||
"+cells-set-style",
|
||
"+cells-clear",
|
||
"+cells-merge",
|
||
"+cells-unmerge",
|
||
"+cells-replace",
|
||
"+csv-put",
|
||
"+dropdown-set",
|
||
"+dim-insert",
|
||
"+dim-delete",
|
||
"+dim-hide",
|
||
"+dim-unhide",
|
||
"+dim-freeze",
|
||
"+dim-group",
|
||
"+dim-ungroup",
|
||
"+rows-resize",
|
||
"+cols-resize",
|
||
"+range-move",
|
||
"+range-copy",
|
||
"+range-fill",
|
||
"+range-sort",
|
||
"+sheet-create",
|
||
"+sheet-delete",
|
||
"+sheet-rename",
|
||
"+sheet-move",
|
||
"+sheet-copy",
|
||
"+sheet-hide",
|
||
"+sheet-unhide",
|
||
"+sheet-set-tab-color",
|
||
"+sheet-show-gridline",
|
||
"+sheet-hide-gridline",
|
||
"+chart-create",
|
||
"+chart-update",
|
||
"+chart-delete",
|
||
"+pivot-create",
|
||
"+pivot-update",
|
||
"+pivot-delete",
|
||
"+cond-format-create",
|
||
"+cond-format-update",
|
||
"+cond-format-delete",
|
||
"+filter-create",
|
||
"+filter-update",
|
||
"+filter-delete",
|
||
"+filter-view-create",
|
||
"+filter-view-update",
|
||
"+filter-view-delete",
|
||
"+sparkline-create",
|
||
"+sparkline-update",
|
||
"+sparkline-delete",
|
||
"+float-image-create",
|
||
"+float-image-update",
|
||
"+float-image-delete"
|
||
],
|
||
"description": "CLI shortcut 名（不是底层 MCP tool 名）。+dim-move 不在表中——它走 legacy v2 endpoint，无法批；+cells-set-image / +workbook-create 也不在——前者含多步图片上传，后者是新建工作簿，都不属于 atomic batch 范畴；所有读操作、fan-out wrapper（+batch-update 自身 / +cells-batch-set-style / +cells-batch-clear / +dropdown-{update,delete}）一律禁。"
|
||
},
|
||
"input": {
|
||
"type": "object",
|
||
"description": "该 shortcut 的入参集——含子表定位 sheet_id（或 sheet_name），但不含 spreadsheet token/url（后者只在顶层 --url/--spreadsheet-token 给一次；+batch-update 顶层没有 --sheet-id）；input 的键是该 shortcut 的 flag 展平成 JSON、不是再套一层嵌套。基础 flag 跑 `lark-cli sheets <shortcut> --help`，复合 JSON flag 跑 `--print-schema --flag-name <flag>`。不要手填 `operation`（动作由 shortcut 名表达）。"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"+cells-batch-set-style": {
|
||
"border-styles": {
|
||
"type": "object",
|
||
"description": "单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top）。",
|
||
"properties": {
|
||
"top": {
|
||
"type": "object",
|
||
"properties": {
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"type": "string",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
]
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"type": "string",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
]
|
||
},
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"bottom": {
|
||
"type": "object",
|
||
"properties": {
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"type": "string",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
]
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"type": "string",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
]
|
||
},
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"left": {
|
||
"type": "object",
|
||
"properties": {
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"type": "string",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
]
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"type": "string",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
]
|
||
},
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"right": {
|
||
"type": "object",
|
||
"properties": {
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"type": "string",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
]
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"type": "string",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
]
|
||
},
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"+cells-set": {
|
||
"cells": {
|
||
"description": "【维度】行列数必须与 range 完全一致：'A1:C2'→[[_,_,_],[_,_,_]]（2行×3列），'B5:B7'→[[_],[_],[_]]（3行×1列），'A1'→[[_]]（1×1）。不修改的单元格填 {}。【内容字段，只能选一个】value（普通值）/ formula（公式，以 = 开头）/ rich_text（富文本）/ multiple_values（多值）。【可叠加字段，可与内容字段自由组合】cell_styles、border_styles、note、data_validation。【增量】所有字段均为增量更新，未传字段保留原值不变。",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"value": {
|
||
"description": "静态单元格值（文本、数字、布尔）。公式请优先使用 'formula' 字段；如果误把以 '=' 开头的公式字符串写到这里，工具会按 Excel 语义自动识别为公式入库，但仍应按 'formula' 字段的契约传参。",
|
||
"oneOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "boolean"
|
||
}
|
||
]
|
||
},
|
||
"formula": {
|
||
"description": "以 '=' 开头的单元格公式（例如：'=SUM(A1:A10)'）。公式必须写在此字段，而不是 'value'。",
|
||
"type": "string"
|
||
},
|
||
"note": {
|
||
"description": "单元格批注/备注。设为 null 可清除已有的批注。",
|
||
"type": "string",
|
||
"nullable": true
|
||
},
|
||
"cell_styles": {
|
||
"type": "object",
|
||
"properties": {
|
||
"font_color": {
|
||
"description": "字体颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
},
|
||
"font_size": {
|
||
"description": "字体大小（单位：px/像素，例如 10、12、14）",
|
||
"type": "number"
|
||
},
|
||
"font_weight": {
|
||
"description": "字重",
|
||
"type": "string",
|
||
"enum": [
|
||
"normal",
|
||
"bold"
|
||
]
|
||
},
|
||
"font_style": {
|
||
"description": "字体样式",
|
||
"type": "string",
|
||
"enum": [
|
||
"normal",
|
||
"italic"
|
||
]
|
||
},
|
||
"font_line": {
|
||
"description": "字体线条样式",
|
||
"type": "string",
|
||
"enum": [
|
||
"none",
|
||
"underline",
|
||
"line-through"
|
||
]
|
||
},
|
||
"background_color": {
|
||
"description": "背景颜色（十六进制，例如 \"#ffffff\"）",
|
||
"type": "string"
|
||
},
|
||
"horizontal_alignment": {
|
||
"description": "水平对齐方式",
|
||
"type": "string",
|
||
"enum": [
|
||
"left",
|
||
"center",
|
||
"right"
|
||
]
|
||
},
|
||
"vertical_alignment": {
|
||
"description": "垂直对齐方式",
|
||
"type": "string",
|
||
"enum": [
|
||
"top",
|
||
"middle",
|
||
"bottom"
|
||
]
|
||
},
|
||
"number_format": {
|
||
"description": "数字格式（例如：文本用 \"@\"、数字用 \"0.00\"、货币用 \"$#,##0.00\"、日期用 \"mm/dd/yyyy\"）",
|
||
"type": "string"
|
||
},
|
||
"word_wrap": {
|
||
"description": "是否自动换行，默认溢出，可选自动换行或裁剪。",
|
||
"type": "string",
|
||
"enum": [
|
||
"overflow",
|
||
"auto-wrap",
|
||
"word-clip"
|
||
]
|
||
}
|
||
},
|
||
"description": "单元格样式属性，包括字体、颜色、对齐方式和数字格式"
|
||
},
|
||
"border_styles": {
|
||
"type": "object",
|
||
"description": "单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top）。",
|
||
"properties": {
|
||
"top": {
|
||
"type": "object",
|
||
"properties": {
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"type": "string",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
]
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"type": "string",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
]
|
||
},
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"bottom": {
|
||
"type": "object",
|
||
"properties": {
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"type": "string",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
]
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"type": "string",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
]
|
||
},
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"left": {
|
||
"type": "object",
|
||
"properties": {
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"type": "string",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
]
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"type": "string",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
]
|
||
},
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"right": {
|
||
"type": "object",
|
||
"properties": {
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"type": "string",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
]
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"type": "string",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
]
|
||
},
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"rich_text": {
|
||
"description": "富文本内容。设置后会忽略 value 字段。可包含带样式的文本段 text、超链接 link、@提及 mention、单元格图片 embed-image、附件 attachment。",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"type": {
|
||
"description": "段类型",
|
||
"type": "string",
|
||
"enum": [
|
||
"text",
|
||
"link",
|
||
"mention",
|
||
"embed-image",
|
||
"attachment"
|
||
]
|
||
},
|
||
"text": {
|
||
"description": "显示文本",
|
||
"type": "string"
|
||
},
|
||
"style": {
|
||
"description": "文本段样式（仅 type='text' 时生效），结构同 cell_styles",
|
||
"type": "object"
|
||
},
|
||
"link": {
|
||
"description": "超链接地址（type='link' 时必填）；@文档 mention（mention_type 非 0）时也必填，传文档 URL（如搜索结果里的文档链接），否则卡片不可点。@人（mention_type=0）不需要传",
|
||
"type": "string"
|
||
},
|
||
"mention_token": {
|
||
"description": "@提及目标的 token，如 userId 或 fileId（仅 type='mention' 时必填）",
|
||
"type": "string"
|
||
},
|
||
"mention_type": {
|
||
"description": "@提及类型编号（仅 type='mention' 时可选）。0 或不填=@用户；@文件时按类型取：1=文档 3=电子表格 8=多维表格 11=思维笔记 12=文件 15=旧版幻灯片 16=知识库 22=新版文档 30=幻灯片 38=画板",
|
||
"type": "number",
|
||
"enum": [
|
||
0,
|
||
1,
|
||
3,
|
||
8,
|
||
11,
|
||
12,
|
||
15,
|
||
16,
|
||
22,
|
||
30,
|
||
38
|
||
]
|
||
},
|
||
"notify": {
|
||
"description": "是否发送通知（仅 type='mention' 时可选，默认 true）",
|
||
"type": "boolean"
|
||
},
|
||
"image_width": {
|
||
"description": "图片宽度（像素，仅 type='embed-image' 时使用）",
|
||
"type": "number"
|
||
},
|
||
"image_height": {
|
||
"description": "图片高度（像素，仅 type='embed-image' 时使用）",
|
||
"type": "number"
|
||
},
|
||
"image_name": {
|
||
"description": "图片名称（仅 type='embed-image' 时使用，创建新图片时必填）",
|
||
"type": "string"
|
||
},
|
||
"image_uri": {
|
||
"description": "图片文件 reference_id（仅 type='embed-image' 时使用，与 image_token 二选一，如`<|image|>:abcdef` 或者 `<|superscript|>:abcdef-<|image|>:abcdef`，其中 `abcdef` 为实际的对象 ID，占位符仅用于示意）",
|
||
"type": "string"
|
||
},
|
||
"image_token": {
|
||
"description": "图片文件 token（仅 type='embed-image' 时可选，修改已有图片时可从 get_cell_range 获取）",
|
||
"type": "string"
|
||
},
|
||
"attachment_token": {
|
||
"description": "附件文件 token，通过飞书 Drive 上传获取（仅 type='attachment' 时可选，修改已有附件时可从 get_cell_range 获取）",
|
||
"type": "string"
|
||
},
|
||
"attachment_uri": {
|
||
"description": "附件文件 reference_id（仅 type='attachment' 时使用，与 attachment_token 二选一，如`<|attachment|>:abcdef` 或者 `<|superscript|>:abcdef-<|attachment|>:abcdef`，其中 `abcdef` 为实际的对象 ID，占位符仅用于示意）",
|
||
"type": "string"
|
||
},
|
||
"attachment_name": {
|
||
"description": "附件文件名称（仅 type='attachment' 时使用，配合 attachment_reference_id 使用，创建新附件时必填）",
|
||
"type": "string"
|
||
},
|
||
"mime_type": {
|
||
"description": "附件 MIME 类型（仅 type='attachment' 时使用，例如 'application/pdf'）",
|
||
"type": "string"
|
||
},
|
||
"file_size": {
|
||
"description": "附件文件大小（字节，仅 type='attachment' 时使用）",
|
||
"type": "number"
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"text"
|
||
]
|
||
}
|
||
},
|
||
"multiple_values": {
|
||
"description": "多值内容，用于支持多选的列表验证单元格。设置后会忽略 value 和 rich_text 字段。",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"value": {
|
||
"description": "值（文本、数字、布尔）",
|
||
"oneOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "boolean"
|
||
}
|
||
]
|
||
},
|
||
"format": {
|
||
"description": "可选的数字格式（例如 '$#,##0.00'）",
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": [
|
||
"value"
|
||
]
|
||
}
|
||
},
|
||
"data_validation": {
|
||
"description": "数据验证配置。设为 null 可清除已有的数据验证。",
|
||
"type": "object",
|
||
"nullable": true,
|
||
"properties": {
|
||
"type": {
|
||
"description": "数据验证类型：list（下拉列表）、listFromRange（引用范围下拉列表）、number（数字）、date（日期）、textLength（文本长度）、checkbox（复选框）",
|
||
"type": "string",
|
||
"enum": [
|
||
"list",
|
||
"listFromRange",
|
||
"number",
|
||
"date",
|
||
"textLength",
|
||
"checkbox"
|
||
]
|
||
},
|
||
"items": {
|
||
"description": "列表选项",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"range": {
|
||
"description": "源数据区域（type='listFromRange' 时必填，格式：'SheetName!A1:A10'）",
|
||
"type": "string"
|
||
},
|
||
"operator": {
|
||
"description": "比较运算符（type='number'/'date'/'textLength' 时必填）",
|
||
"type": "string",
|
||
"enum": [
|
||
"equal",
|
||
"notEqual",
|
||
"greaterThan",
|
||
"greaterThanOrEqual",
|
||
"lessThan",
|
||
"lessThanOrEqual",
|
||
"between",
|
||
"notBetween"
|
||
]
|
||
},
|
||
"values": {
|
||
"description": "比较值（operator 为 'between'/'notBetween' 时需要两个值，其它运算符需要一个值）",
|
||
"type": "array",
|
||
"items": {
|
||
"oneOf": [
|
||
{
|
||
"type": "string"
|
||
},
|
||
{
|
||
"type": "number"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"support_multiple_values": {
|
||
"description": "列表验证是否支持多选（type='list'/'listFromRange' 时可选，默认 false）",
|
||
"type": "boolean"
|
||
},
|
||
"help_text": {
|
||
"description": "验证失败时显示的提示文本",
|
||
"type": "string"
|
||
},
|
||
"enable_highlight": {
|
||
"description": "是否开启下拉选项的胶囊背景色高亮，仅 type='list'/'listFromRange' 生效。默认 true，自动按内置 10 色色板循环上色。仅当用户明确要求纯色下拉时才传 false。当用户要求按下拉项分别染色时，用本字段 + highlight_colors 一步搞定即可，不要走条件格式（条件格式是染整格背景，语义不符）。",
|
||
"type": "boolean"
|
||
},
|
||
"highlight_colors": {
|
||
"description": "下拉选项的胶囊背景色数组（十六进制，例如 [\"#FFE699\",\"#bff7d9\",\"#ffb3b3\"]）。按顺序对应（type='list' 对应 items；type='listFromRange' 按 range 内单元格行优先顺序，如 A1:A10 对应第 1-10 项；A1:B2 顺序为 A1,B1,A2,B2）。长度可以短于但不能长于；未指定项及不提供该字段时按内置 10 色色板循环补色。当 enable_highlight=false 时本字段被忽略。",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"+cells-set-style": {
|
||
"border-styles": {
|
||
"type": "object",
|
||
"description": "单元格边框配置，含 top/bottom/left/right 四个方向，每个方向的结构相同（见 top）。",
|
||
"properties": {
|
||
"top": {
|
||
"type": "object",
|
||
"properties": {
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"type": "string",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
]
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"type": "string",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
]
|
||
},
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"bottom": {
|
||
"type": "object",
|
||
"properties": {
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"type": "string",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
]
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"type": "string",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
]
|
||
},
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"left": {
|
||
"type": "object",
|
||
"properties": {
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"type": "string",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
]
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"type": "string",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
]
|
||
},
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"right": {
|
||
"type": "object",
|
||
"properties": {
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"type": "string",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
]
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"type": "string",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
]
|
||
},
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"+chart-create": {
|
||
"properties": {
|
||
"description": "创建/更新的图表属性。",
|
||
"type": "object",
|
||
"properties": {
|
||
"position": {
|
||
"type": "object",
|
||
"description": "必填。图表在表格中的单元格位置。注意：选择位置时应避免覆盖已有数据的单元格，并确保图表不超出当前表格的行列范围。",
|
||
"properties": {
|
||
"row": {
|
||
"type": "number",
|
||
"minimum": 0,
|
||
"description": "行索引（0-based）"
|
||
},
|
||
"col": {
|
||
"type": "string",
|
||
"description": "列索引，例如 \"A\"、\"B\""
|
||
}
|
||
},
|
||
"required": [
|
||
"row",
|
||
"col"
|
||
]
|
||
},
|
||
"offset": {
|
||
"type": "object",
|
||
"description": "可选。图表在位置基础上的偏移量（像素）。",
|
||
"properties": {
|
||
"row_offset": {
|
||
"type": "number",
|
||
"description": "行偏移量（像素）"
|
||
},
|
||
"col_offset": {
|
||
"type": "number",
|
||
"description": "列偏移量（像素）"
|
||
}
|
||
}
|
||
},
|
||
"size": {
|
||
"type": "object",
|
||
"description": "必填。图表大小（像素）。注意：设定大小时应确保图表不超出当前表格的行列范围，并避免覆盖已有数据的单元格。",
|
||
"properties": {
|
||
"width": {
|
||
"type": "number",
|
||
"minimum": 10,
|
||
"description": "宽度（像素）"
|
||
},
|
||
"height": {
|
||
"type": "number",
|
||
"minimum": 10,
|
||
"description": "高度（像素）"
|
||
}
|
||
},
|
||
"required": [
|
||
"width",
|
||
"height"
|
||
]
|
||
},
|
||
"snapshot": {
|
||
"type": "object",
|
||
"description": "图表快照配置。更新图表时必须传入完整的图表属性定义，不能只传修改的部分。应先通过 get_chart_objects 获取当前图表快照，修改需要变更的字段后，将完整快照传入。",
|
||
"properties": {
|
||
"title": {
|
||
"type": "object",
|
||
"description": "图表标题配置",
|
||
"properties": {
|
||
"text": {
|
||
"type": "string",
|
||
"description": "标题文本"
|
||
},
|
||
"textAlign": {
|
||
"type": "string",
|
||
"description": "标题对齐方式",
|
||
"enum": [
|
||
"left",
|
||
"center",
|
||
"right"
|
||
]
|
||
},
|
||
"fontSize": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"bold": {
|
||
"type": "boolean",
|
||
"description": "是否加粗"
|
||
},
|
||
"italic": {
|
||
"type": "boolean",
|
||
"description": "是否斜体"
|
||
},
|
||
"underline": {
|
||
"type": "boolean",
|
||
"description": "是否下划线"
|
||
},
|
||
"strikethrough": {
|
||
"type": "boolean",
|
||
"description": "是否删除线"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色，格式为 #RRGGBB"
|
||
}
|
||
},
|
||
"required": [
|
||
"text"
|
||
]
|
||
},
|
||
"subTitle": {
|
||
"type": "object",
|
||
"description": "图表副标题配置",
|
||
"properties": {
|
||
"text": {
|
||
"type": "string",
|
||
"description": "副标题文本"
|
||
},
|
||
"textAlign": {
|
||
"type": "string",
|
||
"description": "副标题对齐方式",
|
||
"enum": [
|
||
"left",
|
||
"center",
|
||
"right"
|
||
]
|
||
},
|
||
"fontSize": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"bold": {
|
||
"type": "boolean",
|
||
"description": "是否加粗"
|
||
},
|
||
"italic": {
|
||
"type": "boolean",
|
||
"description": "是否斜体"
|
||
},
|
||
"underline": {
|
||
"type": "boolean",
|
||
"description": "是否下划线"
|
||
},
|
||
"strikethrough": {
|
||
"type": "boolean",
|
||
"description": "是否删除线"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色，格式为 #RRGGBB"
|
||
}
|
||
},
|
||
"required": [
|
||
"text"
|
||
]
|
||
},
|
||
"style": {
|
||
"type": "object",
|
||
"description": "图表样式配置",
|
||
"properties": {
|
||
"background": {
|
||
"type": "object",
|
||
"description": "背景配置",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "背景颜色，格式为 #RRGGBB"
|
||
}
|
||
}
|
||
},
|
||
"font": {
|
||
"type": "object",
|
||
"description": "字体配置",
|
||
"properties": {
|
||
"size": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色，格式为 #RRGGBB"
|
||
}
|
||
}
|
||
},
|
||
"border": {
|
||
"type": "object",
|
||
"description": "边框配置",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "边框颜色，格式为 #RRGGBB"
|
||
},
|
||
"width": {
|
||
"type": "number",
|
||
"description": "边框宽度"
|
||
},
|
||
"style": {
|
||
"type": "string",
|
||
"description": "边框样式",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted"
|
||
]
|
||
},
|
||
"radius": {
|
||
"type": "number",
|
||
"description": "边框圆角"
|
||
}
|
||
}
|
||
},
|
||
"colorTheme": {
|
||
"type": "array",
|
||
"description": "颜色主题配置。支持两种模式：1. 仅传一个预设主题名称（字符串数组，长度为1）；2. 传多个自定义十六进制颜色字符串。预设主题：brandColorSeries@v2、rainbowColorSeries@v2、complementaryColorSeries@v2、converseColorSeries@v2、primaryColorSeries@v2、singleColorSeries-B-@v2、singleColorSeries-W-@v2、singleColorSeries-G-@v2、singleColorSeries-Y-@v2、singleColorSeries-O-@v2、singleColorSeries-R-@v2、singleColorSeries-D-@v2。十六进制格式：#RRGGBB",
|
||
"oneOf": [
|
||
{
|
||
"minItems": 1,
|
||
"maxItems": 1,
|
||
"items": {
|
||
"type": "string",
|
||
"enum": [
|
||
"brandColorSeries@v2",
|
||
"rainbowColorSeries@v2",
|
||
"complementaryColorSeries@v2",
|
||
"converseColorSeries@v2",
|
||
"primaryColorSeries@v2",
|
||
"singleColorSeries-B-@v2",
|
||
"singleColorSeries-W-@v2",
|
||
"singleColorSeries-G-@v2",
|
||
"singleColorSeries-Y-@v2",
|
||
"singleColorSeries-O-@v2",
|
||
"singleColorSeries-R-@v2",
|
||
"singleColorSeries-D-@v2"
|
||
]
|
||
}
|
||
},
|
||
{
|
||
"minItems": 2,
|
||
"items": {
|
||
"type": "string",
|
||
"description": "颜色字符串，十六进制格式：#RRGGBB"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"colorGradient": {
|
||
"type": "boolean",
|
||
"description": "是否启用颜色渐变"
|
||
}
|
||
}
|
||
},
|
||
"legend": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"description": "图例配置",
|
||
"properties": {
|
||
"position": {
|
||
"type": "string",
|
||
"description": "图例位置",
|
||
"enum": [
|
||
"top",
|
||
"bottom",
|
||
"left",
|
||
"right"
|
||
]
|
||
},
|
||
"fontSize": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"bold": {
|
||
"type": "boolean",
|
||
"description": "是否加粗"
|
||
},
|
||
"italic": {
|
||
"type": "boolean",
|
||
"description": "是否斜体"
|
||
},
|
||
"underline": {
|
||
"type": "boolean",
|
||
"description": "是否下划线"
|
||
},
|
||
"strikethrough": {
|
||
"type": "boolean",
|
||
"description": "是否删除线"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色，格式为 #RRGGBB"
|
||
}
|
||
}
|
||
},
|
||
{
|
||
"type": "boolean",
|
||
"description": "false 表示隐藏图例"
|
||
}
|
||
]
|
||
},
|
||
"plotArea": {
|
||
"type": "object",
|
||
"description": "绘图区域配置",
|
||
"properties": {
|
||
"plot": {
|
||
"type": "object",
|
||
"description": "绘图配置",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "图表类型",
|
||
"enum": [
|
||
"bar",
|
||
"column",
|
||
"line",
|
||
"area",
|
||
"combo",
|
||
"pie",
|
||
"radar",
|
||
"scatter"
|
||
]
|
||
},
|
||
"comboType": {
|
||
"type": "string",
|
||
"description": "组合图表默认类型",
|
||
"enum": [
|
||
"column",
|
||
"line",
|
||
"area"
|
||
]
|
||
},
|
||
"yAxisPosition": {
|
||
"type": "string",
|
||
"description": "Y轴位置",
|
||
"enum": [
|
||
"left",
|
||
"right"
|
||
]
|
||
},
|
||
"extra": {
|
||
"type": "object",
|
||
"description": "额外配置",
|
||
"properties": {
|
||
"smooth": {
|
||
"type": "boolean",
|
||
"description": "是否平滑曲线"
|
||
},
|
||
"step": {
|
||
"type": "boolean",
|
||
"description": "是否阶梯图"
|
||
},
|
||
"stack": {
|
||
"type": "object",
|
||
"description": "堆叠配置",
|
||
"properties": {
|
||
"percentage": {
|
||
"type": "boolean",
|
||
"description": "是否百分比堆叠"
|
||
}
|
||
}
|
||
},
|
||
"radar": {
|
||
"type": "object",
|
||
"description": "雷达图配置",
|
||
"properties": {
|
||
"shape": {
|
||
"type": "string",
|
||
"description": "雷达图形状",
|
||
"enum": [
|
||
"polygon",
|
||
"circle"
|
||
]
|
||
},
|
||
"area": {
|
||
"type": "boolean",
|
||
"description": "是否填充区域"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"points": {
|
||
"type": "object",
|
||
"description": "全系列数据点配置，折线图、面积图、雷达图、散点图、组合图生效。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "数据点颜色"
|
||
},
|
||
"shape": {
|
||
"type": "string",
|
||
"description": "数据点形状",
|
||
"enum": [
|
||
"circle",
|
||
"triangle",
|
||
"rect",
|
||
"diamond",
|
||
"square"
|
||
]
|
||
},
|
||
"size": {
|
||
"type": "number",
|
||
"description": "数据点大小"
|
||
},
|
||
"point": {
|
||
"type": "array",
|
||
"description": "单个数据点配置数组",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"index": {
|
||
"type": "number",
|
||
"description": "数据点索引"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "颜色"
|
||
},
|
||
"shape": {
|
||
"type": "string",
|
||
"description": "形状"
|
||
},
|
||
"size": {
|
||
"type": "number",
|
||
"description": "大小"
|
||
}
|
||
},
|
||
"required": [
|
||
"index"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"lines": {
|
||
"type": "object",
|
||
"description": "全系列线条配置，折线图、面积图、雷达图、组合图生效。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "线条颜色"
|
||
},
|
||
"width": {
|
||
"type": "number",
|
||
"description": "线条宽度"
|
||
},
|
||
"style": {
|
||
"type": "string",
|
||
"description": "线条样式",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted"
|
||
]
|
||
},
|
||
"invalidType": {
|
||
"type": "string",
|
||
"description": "无效值处理方式",
|
||
"enum": [
|
||
"break",
|
||
"zero",
|
||
"link"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"areas": {
|
||
"type": "object",
|
||
"description": "全系列面积填充配置，面积图、雷达图、组合图生效。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "区域填充颜色"
|
||
}
|
||
}
|
||
},
|
||
"bars": {
|
||
"type": "object",
|
||
"description": "全系列柱状图、条形图、组合图生效。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "柱子颜色"
|
||
},
|
||
"borderColor": {
|
||
"type": "string",
|
||
"description": "边框颜色"
|
||
},
|
||
"borderWidth": {
|
||
"type": "number",
|
||
"description": "边框宽度"
|
||
},
|
||
"borderStyle": {
|
||
"type": "string",
|
||
"description": "边框样式",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted"
|
||
]
|
||
},
|
||
"width": {
|
||
"type": "number",
|
||
"description": "柱子宽度"
|
||
},
|
||
"gap": {
|
||
"type": "number",
|
||
"description": "柱子间距比例，0-1之间"
|
||
},
|
||
"backgroundColor": {
|
||
"type": "string",
|
||
"description": "背景颜色"
|
||
},
|
||
"bar": {
|
||
"type": "array",
|
||
"description": "单个柱子配置数组",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"index": {
|
||
"type": "number",
|
||
"description": "柱子索引"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "颜色"
|
||
},
|
||
"borderColor": {
|
||
"type": "string",
|
||
"description": "边框颜色"
|
||
},
|
||
"borderWidth": {
|
||
"type": "number",
|
||
"description": "边框宽度"
|
||
},
|
||
"borderStyle": {
|
||
"type": "string",
|
||
"description": "边框样式"
|
||
}
|
||
},
|
||
"required": [
|
||
"index"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"labels": {
|
||
"type": "object",
|
||
"description": "数据标签配置",
|
||
"properties": {
|
||
"position": {
|
||
"type": "string",
|
||
"description": "标签位置",
|
||
"enum": [
|
||
"auto",
|
||
"top",
|
||
"bottom",
|
||
"left",
|
||
"right",
|
||
"center",
|
||
"inside",
|
||
"outside"
|
||
]
|
||
},
|
||
"series": {
|
||
"type": "boolean",
|
||
"description": "是否显示系列名"
|
||
},
|
||
"category": {
|
||
"type": "boolean",
|
||
"description": "是否显示类别名"
|
||
},
|
||
"value": {
|
||
"type": "boolean",
|
||
"description": "是否显示值"
|
||
},
|
||
"percentage": {
|
||
"type": "boolean",
|
||
"description": "是否显示百分比"
|
||
},
|
||
"fontSize": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"bold": {
|
||
"type": "boolean",
|
||
"description": "是否加粗"
|
||
},
|
||
"italic": {
|
||
"type": "boolean",
|
||
"description": "是否斜体"
|
||
},
|
||
"underline": {
|
||
"type": "boolean",
|
||
"description": "是否下划线"
|
||
},
|
||
"strikethrough": {
|
||
"type": "boolean",
|
||
"description": "是否删除线"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色"
|
||
}
|
||
}
|
||
},
|
||
"series": {
|
||
"type": "array",
|
||
"description": "单个系列配置数组",
|
||
"items": {
|
||
"type": "object",
|
||
"description": "系列配置",
|
||
"properties": {
|
||
"index": {
|
||
"type": "number",
|
||
"description": "数据列索引，与 dim2.series[].index 值一致，从 1 开始（1 通常对应首列标签维度，2+ 对应后续数据维度列）"
|
||
},
|
||
"comboType": {
|
||
"type": "string",
|
||
"description": "组合图下该系列的图表类型，仅在 type 为 combo 时生效",
|
||
"enum": [
|
||
"column",
|
||
"line",
|
||
"area"
|
||
]
|
||
},
|
||
"yAxisPosition": {
|
||
"type": "string",
|
||
"description": "Y轴位置",
|
||
"enum": [
|
||
"left",
|
||
"right"
|
||
]
|
||
},
|
||
"points": {
|
||
"type": "object",
|
||
"description": "数据点配置，配置项同 plotArea.points"
|
||
},
|
||
"line": {
|
||
"type": "object",
|
||
"description": "线条配置，配置项同 plotArea.lines"
|
||
},
|
||
"area": {
|
||
"type": "object",
|
||
"description": "区域填充配置，配置项同 plotArea.areas"
|
||
},
|
||
"bars": {
|
||
"type": "object",
|
||
"description": "柱状图配置，配置项同 plotArea.bars"
|
||
},
|
||
"labels": {
|
||
"type": "object",
|
||
"description": "数据标签配置"
|
||
},
|
||
"sectors": {
|
||
"type": "object",
|
||
"description": "扇区配置（饼图）",
|
||
"properties": {
|
||
"borderColor": {
|
||
"type": "string",
|
||
"description": "边框颜色"
|
||
},
|
||
"innerRadius": {
|
||
"type": "number",
|
||
"description": "内半径比例，0-1之间"
|
||
},
|
||
"offsetRadius": {
|
||
"type": "number",
|
||
"description": "偏移半径比例"
|
||
},
|
||
"startAngle": {
|
||
"type": "number",
|
||
"description": "起始角度，0-359"
|
||
},
|
||
"sector": {
|
||
"type": "array",
|
||
"description": "单个扇区配置数组",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"index": {
|
||
"type": "number",
|
||
"description": "扇区索引"
|
||
},
|
||
"borderColor": {
|
||
"type": "string",
|
||
"description": "边框颜色"
|
||
},
|
||
"offsetRadius": {
|
||
"type": "number",
|
||
"description": "偏移半径"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "颜色"
|
||
}
|
||
},
|
||
"required": [
|
||
"index"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"index"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
},
|
||
"axes": {
|
||
"type": "array",
|
||
"description": "坐标轴配置数组",
|
||
"items": {
|
||
"type": "object",
|
||
"description": "坐标轴配置",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "坐标轴类型",
|
||
"enum": [
|
||
"x",
|
||
"y",
|
||
"angle",
|
||
"radius"
|
||
]
|
||
},
|
||
"position": {
|
||
"type": "string",
|
||
"description": "坐标轴位置",
|
||
"enum": [
|
||
"left",
|
||
"right",
|
||
"bottom"
|
||
]
|
||
},
|
||
"max": {
|
||
"type": "number",
|
||
"description": "最大值"
|
||
},
|
||
"min": {
|
||
"type": "number",
|
||
"description": "最小值"
|
||
},
|
||
"valueType": {
|
||
"type": "string",
|
||
"description": "是否将横轴数字视为文本，linear 表示将数字视为数值, ordinal 表示将数字视为文本",
|
||
"enum": [
|
||
"ordinal",
|
||
"linear"
|
||
]
|
||
},
|
||
"title": {
|
||
"type": "object",
|
||
"description": "坐标轴标题配置",
|
||
"properties": {
|
||
"text": {
|
||
"type": "string",
|
||
"description": "标题文本"
|
||
},
|
||
"fontSize": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"bold": {
|
||
"type": "boolean",
|
||
"description": "是否加粗"
|
||
},
|
||
"italic": {
|
||
"type": "boolean",
|
||
"description": "是否斜体"
|
||
},
|
||
"underline": {
|
||
"type": "boolean",
|
||
"description": "是否下划线"
|
||
},
|
||
"strikethrough": {
|
||
"type": "boolean",
|
||
"description": "是否删除线"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色"
|
||
}
|
||
},
|
||
"required": [
|
||
"text"
|
||
]
|
||
},
|
||
"label": {
|
||
"type": "object",
|
||
"description": "坐标轴标签配置",
|
||
"properties": {
|
||
"angle": {
|
||
"type": "number",
|
||
"description": "旋转角度，可选值：-90, -45, 0, 45, 90"
|
||
},
|
||
"fontSize": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"bold": {
|
||
"type": "boolean",
|
||
"description": "是否加粗"
|
||
},
|
||
"italic": {
|
||
"type": "boolean",
|
||
"description": "是否斜体"
|
||
},
|
||
"underline": {
|
||
"type": "boolean",
|
||
"description": "是否下划线"
|
||
},
|
||
"strikethrough": {
|
||
"type": "boolean",
|
||
"description": "是否删除线"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色"
|
||
}
|
||
}
|
||
},
|
||
"axisLine": {
|
||
"type": "boolean",
|
||
"description": "是否显示轴线"
|
||
},
|
||
"gridLine": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"description": "网格线配置",
|
||
"properties": {
|
||
"width": {
|
||
"type": "number",
|
||
"description": "网格线宽度"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "网格线颜色"
|
||
}
|
||
}
|
||
},
|
||
{
|
||
"type": "boolean",
|
||
"description": "false 表示隐藏网格线"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"plot"
|
||
]
|
||
},
|
||
"data": {
|
||
"type": "object",
|
||
"description": "图表数据配置",
|
||
"properties": {
|
||
"isStaticData": {
|
||
"type": "boolean",
|
||
"description": "是否为静态数据"
|
||
},
|
||
"includeHiddenOrFilter": {
|
||
"type": "boolean",
|
||
"description": "是否包含隐藏或过滤的数据"
|
||
},
|
||
"direction": {
|
||
"type": "string",
|
||
"description": "数据方向，可选值：row（行方向）或column（列方向），常用值为column",
|
||
"enum": [
|
||
"row",
|
||
"column"
|
||
]
|
||
},
|
||
"headerMode": {
|
||
"type": "string",
|
||
"description": "表头模式。inline 表示 refs 首行/首列就是表头；detached 表示 refs 仅覆盖实际数据范围，维度名和系列名需通过 nameRef 显式指定。",
|
||
"enum": [
|
||
"inline",
|
||
"detached"
|
||
]
|
||
},
|
||
"refs": {
|
||
"type": "array",
|
||
"description": "数据源引用范围数组",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"value": {
|
||
"type": "string",
|
||
"description": "图表数据源范围，格式为 'SheetName!A1:D100' 的连续区域"
|
||
}
|
||
},
|
||
"required": [
|
||
"value"
|
||
]
|
||
}
|
||
},
|
||
"dim1": {
|
||
"type": "object",
|
||
"description": "维度1配置（类别维度）",
|
||
"properties": {
|
||
"serie": {
|
||
"type": "object",
|
||
"description": "系列配置（非静态数据时传此参数）",
|
||
"properties": {
|
||
"index": {
|
||
"type": "number",
|
||
"description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引"
|
||
},
|
||
"aggregate": {
|
||
"type": "boolean",
|
||
"description": "是否汇总相同的类别，默认为true，true 情况下 aggregateType 才生效"
|
||
},
|
||
"nameRef": {
|
||
"type": "string",
|
||
"description": "可选。维度名称的单元格引用（A1 表示法，如 'Sheet1!A1'）。当维度名称不直接来自 refs 首行/首列时，可通过此字段把维度名显式指向目标表头单元格，图表会以该单元格当前值作为类别维度名展示。"
|
||
}
|
||
},
|
||
"required": [
|
||
"index"
|
||
]
|
||
},
|
||
"field": {
|
||
"type": "object",
|
||
"description": "字段配置（静态数据时传此参数）",
|
||
"properties": {
|
||
"valueType": {
|
||
"type": "string",
|
||
"description": "值类型",
|
||
"enum": [
|
||
"number",
|
||
"string"
|
||
]
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "字段名称"
|
||
},
|
||
"text": {
|
||
"type": "string",
|
||
"description": "字段文本数据"
|
||
}
|
||
},
|
||
"required": [
|
||
"text"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"dim2": {
|
||
"type": "object",
|
||
"description": "维度2配置（值维度）",
|
||
"properties": {
|
||
"series": {
|
||
"type": "array",
|
||
"description": "系列配置数组（非静态数据时传此参数）",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"index": {
|
||
"type": "number",
|
||
"description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引"
|
||
},
|
||
"aggregateType": {
|
||
"type": "string",
|
||
"description": "汇总方式，默认为'sum'，仅在 aggregate 为 true 时生效。count 只统计数值单元格；counta 统计所有非空单元格（含文本），按文本/分类列统计出现次数（如各类别的数量、频次分布）时用 counta。",
|
||
"enum": [
|
||
"sum",
|
||
"average",
|
||
"count",
|
||
"counta",
|
||
"min",
|
||
"max",
|
||
"median"
|
||
]
|
||
},
|
||
"nameRef": {
|
||
"type": "string",
|
||
"description": "可选。系列名称的单元格引用（A1 表示法，如 'Sheet1!C1'）。当系列名称不直接来自 refs 首行/首列时，可通过此字段把系列名显式指向目标表头单元格，图表会以该单元格当前值作为系列名（图例/tooltip）展示。"
|
||
}
|
||
},
|
||
"required": [
|
||
"index"
|
||
]
|
||
}
|
||
},
|
||
"fields": {
|
||
"type": "array",
|
||
"description": "字段配置数组（静态数据时传此参数）",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"valueType": {
|
||
"type": "string",
|
||
"description": "值类型",
|
||
"enum": [
|
||
"number"
|
||
]
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "字段名称"
|
||
},
|
||
"text": {
|
||
"type": "string",
|
||
"description": "字段文本数据"
|
||
}
|
||
},
|
||
"required": [
|
||
"text"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"plotArea",
|
||
"data"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"+chart-update": {
|
||
"properties": {
|
||
"description": "创建/更新的图表属性。",
|
||
"type": "object",
|
||
"properties": {
|
||
"position": {
|
||
"type": "object",
|
||
"description": "必填。图表在表格中的单元格位置。注意：选择位置时应避免覆盖已有数据的单元格，并确保图表不超出当前表格的行列范围。",
|
||
"properties": {
|
||
"row": {
|
||
"type": "number",
|
||
"minimum": 0,
|
||
"description": "行索引（0-based）"
|
||
},
|
||
"col": {
|
||
"type": "string",
|
||
"description": "列索引，例如 \"A\"、\"B\""
|
||
}
|
||
},
|
||
"required": [
|
||
"row",
|
||
"col"
|
||
]
|
||
},
|
||
"offset": {
|
||
"type": "object",
|
||
"description": "可选。图表在位置基础上的偏移量（像素）。",
|
||
"properties": {
|
||
"row_offset": {
|
||
"type": "number",
|
||
"description": "行偏移量（像素）"
|
||
},
|
||
"col_offset": {
|
||
"type": "number",
|
||
"description": "列偏移量（像素）"
|
||
}
|
||
}
|
||
},
|
||
"size": {
|
||
"type": "object",
|
||
"description": "必填。图表大小（像素）。注意：设定大小时应确保图表不超出当前表格的行列范围，并避免覆盖已有数据的单元格。",
|
||
"properties": {
|
||
"width": {
|
||
"type": "number",
|
||
"minimum": 10,
|
||
"description": "宽度（像素）"
|
||
},
|
||
"height": {
|
||
"type": "number",
|
||
"minimum": 10,
|
||
"description": "高度（像素）"
|
||
}
|
||
},
|
||
"required": [
|
||
"width",
|
||
"height"
|
||
]
|
||
},
|
||
"snapshot": {
|
||
"type": "object",
|
||
"description": "图表快照配置。更新图表时必须传入完整的图表属性定义，不能只传修改的部分。应先通过 get_chart_objects 获取当前图表快照，修改需要变更的字段后，将完整快照传入。",
|
||
"properties": {
|
||
"title": {
|
||
"type": "object",
|
||
"description": "图表标题配置",
|
||
"properties": {
|
||
"text": {
|
||
"type": "string",
|
||
"description": "标题文本"
|
||
},
|
||
"textAlign": {
|
||
"type": "string",
|
||
"description": "标题对齐方式",
|
||
"enum": [
|
||
"left",
|
||
"center",
|
||
"right"
|
||
]
|
||
},
|
||
"fontSize": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"bold": {
|
||
"type": "boolean",
|
||
"description": "是否加粗"
|
||
},
|
||
"italic": {
|
||
"type": "boolean",
|
||
"description": "是否斜体"
|
||
},
|
||
"underline": {
|
||
"type": "boolean",
|
||
"description": "是否下划线"
|
||
},
|
||
"strikethrough": {
|
||
"type": "boolean",
|
||
"description": "是否删除线"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色，格式为 #RRGGBB"
|
||
}
|
||
},
|
||
"required": [
|
||
"text"
|
||
]
|
||
},
|
||
"subTitle": {
|
||
"type": "object",
|
||
"description": "图表副标题配置",
|
||
"properties": {
|
||
"text": {
|
||
"type": "string",
|
||
"description": "副标题文本"
|
||
},
|
||
"textAlign": {
|
||
"type": "string",
|
||
"description": "副标题对齐方式",
|
||
"enum": [
|
||
"left",
|
||
"center",
|
||
"right"
|
||
]
|
||
},
|
||
"fontSize": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"bold": {
|
||
"type": "boolean",
|
||
"description": "是否加粗"
|
||
},
|
||
"italic": {
|
||
"type": "boolean",
|
||
"description": "是否斜体"
|
||
},
|
||
"underline": {
|
||
"type": "boolean",
|
||
"description": "是否下划线"
|
||
},
|
||
"strikethrough": {
|
||
"type": "boolean",
|
||
"description": "是否删除线"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色，格式为 #RRGGBB"
|
||
}
|
||
},
|
||
"required": [
|
||
"text"
|
||
]
|
||
},
|
||
"style": {
|
||
"type": "object",
|
||
"description": "图表样式配置",
|
||
"properties": {
|
||
"background": {
|
||
"type": "object",
|
||
"description": "背景配置",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "背景颜色，格式为 #RRGGBB"
|
||
}
|
||
}
|
||
},
|
||
"font": {
|
||
"type": "object",
|
||
"description": "字体配置",
|
||
"properties": {
|
||
"size": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色，格式为 #RRGGBB"
|
||
}
|
||
}
|
||
},
|
||
"border": {
|
||
"type": "object",
|
||
"description": "边框配置",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "边框颜色，格式为 #RRGGBB"
|
||
},
|
||
"width": {
|
||
"type": "number",
|
||
"description": "边框宽度"
|
||
},
|
||
"style": {
|
||
"type": "string",
|
||
"description": "边框样式",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted"
|
||
]
|
||
},
|
||
"radius": {
|
||
"type": "number",
|
||
"description": "边框圆角"
|
||
}
|
||
}
|
||
},
|
||
"colorTheme": {
|
||
"type": "array",
|
||
"description": "颜色主题配置。支持两种模式：1. 仅传一个预设主题名称（字符串数组，长度为1）；2. 传多个自定义十六进制颜色字符串。预设主题：brandColorSeries@v2、rainbowColorSeries@v2、complementaryColorSeries@v2、converseColorSeries@v2、primaryColorSeries@v2、singleColorSeries-B-@v2、singleColorSeries-W-@v2、singleColorSeries-G-@v2、singleColorSeries-Y-@v2、singleColorSeries-O-@v2、singleColorSeries-R-@v2、singleColorSeries-D-@v2。十六进制格式：#RRGGBB",
|
||
"oneOf": [
|
||
{
|
||
"minItems": 1,
|
||
"maxItems": 1,
|
||
"items": {
|
||
"type": "string",
|
||
"enum": [
|
||
"brandColorSeries@v2",
|
||
"rainbowColorSeries@v2",
|
||
"complementaryColorSeries@v2",
|
||
"converseColorSeries@v2",
|
||
"primaryColorSeries@v2",
|
||
"singleColorSeries-B-@v2",
|
||
"singleColorSeries-W-@v2",
|
||
"singleColorSeries-G-@v2",
|
||
"singleColorSeries-Y-@v2",
|
||
"singleColorSeries-O-@v2",
|
||
"singleColorSeries-R-@v2",
|
||
"singleColorSeries-D-@v2"
|
||
]
|
||
}
|
||
},
|
||
{
|
||
"minItems": 2,
|
||
"items": {
|
||
"type": "string",
|
||
"description": "颜色字符串，十六进制格式：#RRGGBB"
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"colorGradient": {
|
||
"type": "boolean",
|
||
"description": "是否启用颜色渐变"
|
||
}
|
||
}
|
||
},
|
||
"legend": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"description": "图例配置",
|
||
"properties": {
|
||
"position": {
|
||
"type": "string",
|
||
"description": "图例位置",
|
||
"enum": [
|
||
"top",
|
||
"bottom",
|
||
"left",
|
||
"right"
|
||
]
|
||
},
|
||
"fontSize": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"bold": {
|
||
"type": "boolean",
|
||
"description": "是否加粗"
|
||
},
|
||
"italic": {
|
||
"type": "boolean",
|
||
"description": "是否斜体"
|
||
},
|
||
"underline": {
|
||
"type": "boolean",
|
||
"description": "是否下划线"
|
||
},
|
||
"strikethrough": {
|
||
"type": "boolean",
|
||
"description": "是否删除线"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色，格式为 #RRGGBB"
|
||
}
|
||
}
|
||
},
|
||
{
|
||
"type": "boolean",
|
||
"description": "false 表示隐藏图例"
|
||
}
|
||
]
|
||
},
|
||
"plotArea": {
|
||
"type": "object",
|
||
"description": "绘图区域配置",
|
||
"properties": {
|
||
"plot": {
|
||
"type": "object",
|
||
"description": "绘图配置",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "图表类型",
|
||
"enum": [
|
||
"bar",
|
||
"column",
|
||
"line",
|
||
"area",
|
||
"combo",
|
||
"pie",
|
||
"radar",
|
||
"scatter"
|
||
]
|
||
},
|
||
"comboType": {
|
||
"type": "string",
|
||
"description": "组合图表默认类型",
|
||
"enum": [
|
||
"column",
|
||
"line",
|
||
"area"
|
||
]
|
||
},
|
||
"yAxisPosition": {
|
||
"type": "string",
|
||
"description": "Y轴位置",
|
||
"enum": [
|
||
"left",
|
||
"right"
|
||
]
|
||
},
|
||
"extra": {
|
||
"type": "object",
|
||
"description": "额外配置",
|
||
"properties": {
|
||
"smooth": {
|
||
"type": "boolean",
|
||
"description": "是否平滑曲线"
|
||
},
|
||
"step": {
|
||
"type": "boolean",
|
||
"description": "是否阶梯图"
|
||
},
|
||
"stack": {
|
||
"type": "object",
|
||
"description": "堆叠配置",
|
||
"properties": {
|
||
"percentage": {
|
||
"type": "boolean",
|
||
"description": "是否百分比堆叠"
|
||
}
|
||
}
|
||
},
|
||
"radar": {
|
||
"type": "object",
|
||
"description": "雷达图配置",
|
||
"properties": {
|
||
"shape": {
|
||
"type": "string",
|
||
"description": "雷达图形状",
|
||
"enum": [
|
||
"polygon",
|
||
"circle"
|
||
]
|
||
},
|
||
"area": {
|
||
"type": "boolean",
|
||
"description": "是否填充区域"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"points": {
|
||
"type": "object",
|
||
"description": "全系列数据点配置，折线图、面积图、雷达图、散点图、组合图生效。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "数据点颜色"
|
||
},
|
||
"shape": {
|
||
"type": "string",
|
||
"description": "数据点形状",
|
||
"enum": [
|
||
"circle",
|
||
"triangle",
|
||
"rect",
|
||
"diamond",
|
||
"square"
|
||
]
|
||
},
|
||
"size": {
|
||
"type": "number",
|
||
"description": "数据点大小"
|
||
},
|
||
"point": {
|
||
"type": "array",
|
||
"description": "单个数据点配置数组",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"index": {
|
||
"type": "number",
|
||
"description": "数据点索引"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "颜色"
|
||
},
|
||
"shape": {
|
||
"type": "string",
|
||
"description": "形状"
|
||
},
|
||
"size": {
|
||
"type": "number",
|
||
"description": "大小"
|
||
}
|
||
},
|
||
"required": [
|
||
"index"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"lines": {
|
||
"type": "object",
|
||
"description": "全系列线条配置，折线图、面积图、雷达图、组合图生效。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "线条颜色"
|
||
},
|
||
"width": {
|
||
"type": "number",
|
||
"description": "线条宽度"
|
||
},
|
||
"style": {
|
||
"type": "string",
|
||
"description": "线条样式",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted"
|
||
]
|
||
},
|
||
"invalidType": {
|
||
"type": "string",
|
||
"description": "无效值处理方式",
|
||
"enum": [
|
||
"break",
|
||
"zero",
|
||
"link"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"areas": {
|
||
"type": "object",
|
||
"description": "全系列面积填充配置，面积图、雷达图、组合图生效。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "区域填充颜色"
|
||
}
|
||
}
|
||
},
|
||
"bars": {
|
||
"type": "object",
|
||
"description": "全系列柱状图、条形图、组合图生效。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "柱子颜色"
|
||
},
|
||
"borderColor": {
|
||
"type": "string",
|
||
"description": "边框颜色"
|
||
},
|
||
"borderWidth": {
|
||
"type": "number",
|
||
"description": "边框宽度"
|
||
},
|
||
"borderStyle": {
|
||
"type": "string",
|
||
"description": "边框样式",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted"
|
||
]
|
||
},
|
||
"width": {
|
||
"type": "number",
|
||
"description": "柱子宽度"
|
||
},
|
||
"gap": {
|
||
"type": "number",
|
||
"description": "柱子间距比例，0-1之间"
|
||
},
|
||
"backgroundColor": {
|
||
"type": "string",
|
||
"description": "背景颜色"
|
||
},
|
||
"bar": {
|
||
"type": "array",
|
||
"description": "单个柱子配置数组",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"index": {
|
||
"type": "number",
|
||
"description": "柱子索引"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "颜色"
|
||
},
|
||
"borderColor": {
|
||
"type": "string",
|
||
"description": "边框颜色"
|
||
},
|
||
"borderWidth": {
|
||
"type": "number",
|
||
"description": "边框宽度"
|
||
},
|
||
"borderStyle": {
|
||
"type": "string",
|
||
"description": "边框样式"
|
||
}
|
||
},
|
||
"required": [
|
||
"index"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"labels": {
|
||
"type": "object",
|
||
"description": "数据标签配置",
|
||
"properties": {
|
||
"position": {
|
||
"type": "string",
|
||
"description": "标签位置",
|
||
"enum": [
|
||
"auto",
|
||
"top",
|
||
"bottom",
|
||
"left",
|
||
"right",
|
||
"center",
|
||
"inside",
|
||
"outside"
|
||
]
|
||
},
|
||
"series": {
|
||
"type": "boolean",
|
||
"description": "是否显示系列名"
|
||
},
|
||
"category": {
|
||
"type": "boolean",
|
||
"description": "是否显示类别名"
|
||
},
|
||
"value": {
|
||
"type": "boolean",
|
||
"description": "是否显示值"
|
||
},
|
||
"percentage": {
|
||
"type": "boolean",
|
||
"description": "是否显示百分比"
|
||
},
|
||
"fontSize": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"bold": {
|
||
"type": "boolean",
|
||
"description": "是否加粗"
|
||
},
|
||
"italic": {
|
||
"type": "boolean",
|
||
"description": "是否斜体"
|
||
},
|
||
"underline": {
|
||
"type": "boolean",
|
||
"description": "是否下划线"
|
||
},
|
||
"strikethrough": {
|
||
"type": "boolean",
|
||
"description": "是否删除线"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色"
|
||
}
|
||
}
|
||
},
|
||
"series": {
|
||
"type": "array",
|
||
"description": "单个系列配置数组",
|
||
"items": {
|
||
"type": "object",
|
||
"description": "系列配置",
|
||
"properties": {
|
||
"index": {
|
||
"type": "number",
|
||
"description": "数据列索引，与 dim2.series[].index 值一致，从 1 开始（1 通常对应首列标签维度，2+ 对应后续数据维度列）"
|
||
},
|
||
"comboType": {
|
||
"type": "string",
|
||
"description": "组合图下该系列的图表类型，仅在 type 为 combo 时生效",
|
||
"enum": [
|
||
"column",
|
||
"line",
|
||
"area"
|
||
]
|
||
},
|
||
"yAxisPosition": {
|
||
"type": "string",
|
||
"description": "Y轴位置",
|
||
"enum": [
|
||
"left",
|
||
"right"
|
||
]
|
||
},
|
||
"points": {
|
||
"type": "object",
|
||
"description": "数据点配置，配置项同 plotArea.points"
|
||
},
|
||
"line": {
|
||
"type": "object",
|
||
"description": "线条配置，配置项同 plotArea.lines"
|
||
},
|
||
"area": {
|
||
"type": "object",
|
||
"description": "区域填充配置，配置项同 plotArea.areas"
|
||
},
|
||
"bars": {
|
||
"type": "object",
|
||
"description": "柱状图配置，配置项同 plotArea.bars"
|
||
},
|
||
"labels": {
|
||
"type": "object",
|
||
"description": "数据标签配置"
|
||
},
|
||
"sectors": {
|
||
"type": "object",
|
||
"description": "扇区配置（饼图）",
|
||
"properties": {
|
||
"borderColor": {
|
||
"type": "string",
|
||
"description": "边框颜色"
|
||
},
|
||
"innerRadius": {
|
||
"type": "number",
|
||
"description": "内半径比例，0-1之间"
|
||
},
|
||
"offsetRadius": {
|
||
"type": "number",
|
||
"description": "偏移半径比例"
|
||
},
|
||
"startAngle": {
|
||
"type": "number",
|
||
"description": "起始角度，0-359"
|
||
},
|
||
"sector": {
|
||
"type": "array",
|
||
"description": "单个扇区配置数组",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"index": {
|
||
"type": "number",
|
||
"description": "扇区索引"
|
||
},
|
||
"borderColor": {
|
||
"type": "string",
|
||
"description": "边框颜色"
|
||
},
|
||
"offsetRadius": {
|
||
"type": "number",
|
||
"description": "偏移半径"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "颜色"
|
||
}
|
||
},
|
||
"required": [
|
||
"index"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"index"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
},
|
||
"axes": {
|
||
"type": "array",
|
||
"description": "坐标轴配置数组",
|
||
"items": {
|
||
"type": "object",
|
||
"description": "坐标轴配置",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"description": "坐标轴类型",
|
||
"enum": [
|
||
"x",
|
||
"y",
|
||
"angle",
|
||
"radius"
|
||
]
|
||
},
|
||
"position": {
|
||
"type": "string",
|
||
"description": "坐标轴位置",
|
||
"enum": [
|
||
"left",
|
||
"right",
|
||
"bottom"
|
||
]
|
||
},
|
||
"max": {
|
||
"type": "number",
|
||
"description": "最大值"
|
||
},
|
||
"min": {
|
||
"type": "number",
|
||
"description": "最小值"
|
||
},
|
||
"valueType": {
|
||
"type": "string",
|
||
"description": "是否将横轴数字视为文本，linear 表示将数字视为数值, ordinal 表示将数字视为文本",
|
||
"enum": [
|
||
"ordinal",
|
||
"linear"
|
||
]
|
||
},
|
||
"title": {
|
||
"type": "object",
|
||
"description": "坐标轴标题配置",
|
||
"properties": {
|
||
"text": {
|
||
"type": "string",
|
||
"description": "标题文本"
|
||
},
|
||
"fontSize": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"bold": {
|
||
"type": "boolean",
|
||
"description": "是否加粗"
|
||
},
|
||
"italic": {
|
||
"type": "boolean",
|
||
"description": "是否斜体"
|
||
},
|
||
"underline": {
|
||
"type": "boolean",
|
||
"description": "是否下划线"
|
||
},
|
||
"strikethrough": {
|
||
"type": "boolean",
|
||
"description": "是否删除线"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色"
|
||
}
|
||
},
|
||
"required": [
|
||
"text"
|
||
]
|
||
},
|
||
"label": {
|
||
"type": "object",
|
||
"description": "坐标轴标签配置",
|
||
"properties": {
|
||
"angle": {
|
||
"type": "number",
|
||
"description": "旋转角度，可选值：-90, -45, 0, 45, 90"
|
||
},
|
||
"fontSize": {
|
||
"type": "number",
|
||
"description": "字体大小"
|
||
},
|
||
"bold": {
|
||
"type": "boolean",
|
||
"description": "是否加粗"
|
||
},
|
||
"italic": {
|
||
"type": "boolean",
|
||
"description": "是否斜体"
|
||
},
|
||
"underline": {
|
||
"type": "boolean",
|
||
"description": "是否下划线"
|
||
},
|
||
"strikethrough": {
|
||
"type": "boolean",
|
||
"description": "是否删除线"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "字体颜色"
|
||
}
|
||
}
|
||
},
|
||
"axisLine": {
|
||
"type": "boolean",
|
||
"description": "是否显示轴线"
|
||
},
|
||
"gridLine": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"description": "网格线配置",
|
||
"properties": {
|
||
"width": {
|
||
"type": "number",
|
||
"description": "网格线宽度"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "网格线颜色"
|
||
}
|
||
}
|
||
},
|
||
{
|
||
"type": "boolean",
|
||
"description": "false 表示隐藏网格线"
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"plot"
|
||
]
|
||
},
|
||
"data": {
|
||
"type": "object",
|
||
"description": "图表数据配置",
|
||
"properties": {
|
||
"isStaticData": {
|
||
"type": "boolean",
|
||
"description": "是否为静态数据"
|
||
},
|
||
"includeHiddenOrFilter": {
|
||
"type": "boolean",
|
||
"description": "是否包含隐藏或过滤的数据"
|
||
},
|
||
"direction": {
|
||
"type": "string",
|
||
"description": "数据方向，可选值：row（行方向）或column（列方向），常用值为column",
|
||
"enum": [
|
||
"row",
|
||
"column"
|
||
]
|
||
},
|
||
"headerMode": {
|
||
"type": "string",
|
||
"description": "表头模式。inline 表示 refs 首行/首列就是表头；detached 表示 refs 仅覆盖实际数据范围，维度名和系列名需通过 nameRef 显式指定。",
|
||
"enum": [
|
||
"inline",
|
||
"detached"
|
||
]
|
||
},
|
||
"refs": {
|
||
"type": "array",
|
||
"description": "数据源引用范围数组",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"value": {
|
||
"type": "string",
|
||
"description": "图表数据源范围，格式为 'SheetName!A1:D100' 的连续区域"
|
||
}
|
||
},
|
||
"required": [
|
||
"value"
|
||
]
|
||
}
|
||
},
|
||
"dim1": {
|
||
"type": "object",
|
||
"description": "维度1配置（类别维度）",
|
||
"properties": {
|
||
"serie": {
|
||
"type": "object",
|
||
"description": "系列配置（非静态数据时传此参数）",
|
||
"properties": {
|
||
"index": {
|
||
"type": "number",
|
||
"description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引"
|
||
},
|
||
"aggregate": {
|
||
"type": "boolean",
|
||
"description": "是否汇总相同的类别，默认为true，true 情况下 aggregateType 才生效"
|
||
},
|
||
"nameRef": {
|
||
"type": "string",
|
||
"description": "可选。维度名称的单元格引用（A1 表示法，如 'Sheet1!A1'）。当维度名称不直接来自 refs 首行/首列时，可通过此字段把维度名显式指向目标表头单元格，图表会以该单元格当前值作为类别维度名展示。"
|
||
}
|
||
},
|
||
"required": [
|
||
"index"
|
||
]
|
||
},
|
||
"field": {
|
||
"type": "object",
|
||
"description": "字段配置（静态数据时传此参数）",
|
||
"properties": {
|
||
"valueType": {
|
||
"type": "string",
|
||
"description": "值类型",
|
||
"enum": [
|
||
"number",
|
||
"string"
|
||
]
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "字段名称"
|
||
},
|
||
"text": {
|
||
"type": "string",
|
||
"description": "字段文本数据"
|
||
}
|
||
},
|
||
"required": [
|
||
"text"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"dim2": {
|
||
"type": "object",
|
||
"description": "维度2配置（值维度）",
|
||
"properties": {
|
||
"series": {
|
||
"type": "array",
|
||
"description": "系列配置数组（非静态数据时传此参数）",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"index": {
|
||
"type": "number",
|
||
"description": "系列索引，数据源从左往右，从 1 开始计数对应数据源的列索引；如果数据方向direction为 'row'，则为从上往下，从 1 开始计数对应数据源的行索引"
|
||
},
|
||
"aggregateType": {
|
||
"type": "string",
|
||
"description": "汇总方式，默认为'sum'，仅在 aggregate 为 true 时生效。count 只统计数值单元格；counta 统计所有非空单元格（含文本），按文本/分类列统计出现次数（如各类别的数量、频次分布）时用 counta。",
|
||
"enum": [
|
||
"sum",
|
||
"average",
|
||
"count",
|
||
"counta",
|
||
"min",
|
||
"max",
|
||
"median"
|
||
]
|
||
},
|
||
"nameRef": {
|
||
"type": "string",
|
||
"description": "可选。系列名称的单元格引用（A1 表示法，如 'Sheet1!C1'）。当系列名称不直接来自 refs 首行/首列时，可通过此字段把系列名显式指向目标表头单元格，图表会以该单元格当前值作为系列名（图例/tooltip）展示。"
|
||
}
|
||
},
|
||
"required": [
|
||
"index"
|
||
]
|
||
}
|
||
},
|
||
"fields": {
|
||
"type": "array",
|
||
"description": "字段配置数组（静态数据时传此参数）",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"valueType": {
|
||
"type": "string",
|
||
"description": "值类型",
|
||
"enum": [
|
||
"number"
|
||
]
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"description": "字段名称"
|
||
},
|
||
"text": {
|
||
"type": "string",
|
||
"description": "字段文本数据"
|
||
}
|
||
},
|
||
"required": [
|
||
"text"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"plotArea",
|
||
"data"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"+cond-format-create": {
|
||
"properties": {
|
||
"description": "创建/更新的条件格式属性。",
|
||
"type": "object",
|
||
"properties": {
|
||
"rule_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"duplicateValues",
|
||
"uniqueValues",
|
||
"cellIs",
|
||
"containsText",
|
||
"timePeriod",
|
||
"containsBlanks",
|
||
"notContainsBlanks",
|
||
"dataBar",
|
||
"colorScale",
|
||
"rank",
|
||
"aboveAverage",
|
||
"expression",
|
||
"iconSet"
|
||
],
|
||
"description": "条件格式规则类型。"
|
||
},
|
||
"ranges": {
|
||
"type": "array",
|
||
"description": "应用条件格式的 A1 范围列表。每个元素支持：矩形范围 \"A1:A10\"、整行 \"3:6\"、整列 \"C:C\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。例如 [\"A1:A10\",\"C:C\"]。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"style": {
|
||
"type": "object",
|
||
"description": "命中规则时应用的单元格样式。",
|
||
"properties": {
|
||
"back_color": {
|
||
"type": "string",
|
||
"description": "背景色，CSS 十六进制表示，例如 \"#FF0000\"。"
|
||
},
|
||
"fore_color": {
|
||
"type": "string",
|
||
"description": "前景色/字体颜色。"
|
||
},
|
||
"text_decoration": {
|
||
"type": "string",
|
||
"enum": [
|
||
"none",
|
||
"underline",
|
||
"strikethrough",
|
||
"underline_strikethrough"
|
||
],
|
||
"description": "文字装饰：none=无，underline=下划线，strikethrough=删除线，underline_strikethrough=下划线+删除线。"
|
||
},
|
||
"font": {
|
||
"type": "string",
|
||
"enum": [
|
||
"bold",
|
||
"italic",
|
||
"bold italic"
|
||
],
|
||
"description": "字体样式：\"bold\"=加粗，\"italic\"=斜体，\"bold italic\"=加粗+斜体。"
|
||
}
|
||
}
|
||
},
|
||
"attrs": {
|
||
"type": "array",
|
||
"description": "规则参数列表。不同 rule_type 下取值结构不同。当 rule_type 为 dataBar 时，attrs 必须包含两个对象，分别定义正值和负值的数据条颜色。",
|
||
"items": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"description": "数值比较类规则参数。",
|
||
"properties": {
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"equal",
|
||
"notEqual",
|
||
"greaterThan",
|
||
"greaterThanOrEqual",
|
||
"lessThan",
|
||
"lessThanOrEqual",
|
||
"between",
|
||
"notBetween"
|
||
],
|
||
"description": "比较运算符。"
|
||
},
|
||
"value": {
|
||
"type": "string",
|
||
"description": "用于比较的值，例如 \"100\"、\"hello\"。between/notBetween 时用逗号分隔两个值。"
|
||
}
|
||
},
|
||
"required": [
|
||
"compare_type",
|
||
"value"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "文本包含类规则参数。",
|
||
"properties": {
|
||
"text": {
|
||
"type": "string",
|
||
"description": "用于匹配的文本内容。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"beginsWith",
|
||
"endsWith",
|
||
"containsText",
|
||
"notContains",
|
||
"is"
|
||
],
|
||
"description": "文本匹配方式。"
|
||
}
|
||
},
|
||
"required": [
|
||
"compare_type",
|
||
"text"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "时间段类规则参数。",
|
||
"properties": {
|
||
"operator": {
|
||
"type": "string",
|
||
"enum": [
|
||
"before",
|
||
"is",
|
||
"after"
|
||
],
|
||
"description": "与指定时间段的比较关系。"
|
||
},
|
||
"time_period": {
|
||
"type": "string",
|
||
"enum": [
|
||
"today",
|
||
"yesterday",
|
||
"tomorrow",
|
||
"last7Days",
|
||
"thisMonth",
|
||
"lastMonth",
|
||
"nextMonth",
|
||
"thisWeek",
|
||
"lastWeek",
|
||
"nextWeek"
|
||
],
|
||
"description": "时间段类型。"
|
||
}
|
||
},
|
||
"required": [
|
||
"operator",
|
||
"time_period"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "数据条规则参数。",
|
||
"properties": {
|
||
"gradient": {
|
||
"type": "boolean",
|
||
"description": "是否使用渐变色数据条。"
|
||
},
|
||
"value": {
|
||
"type": "number",
|
||
"description": "阈值或比例值，含义由 value_type 决定。"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "主颜色，例如 \"#63BE7B\"。"
|
||
},
|
||
"hide_value": {
|
||
"type": "boolean",
|
||
"description": "是否隐藏单元格中的原始值，仅显示数据条。"
|
||
},
|
||
"value_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"minValue",
|
||
"maxValue",
|
||
"num",
|
||
"percentile",
|
||
"percent",
|
||
"formula",
|
||
"auto"
|
||
],
|
||
"description": "阈值类型。"
|
||
}
|
||
},
|
||
"required": [
|
||
"color",
|
||
"value_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "色阶规则中的单个分段。ColorScaleAttrs 由 2 或 3 个该对象组成，分别表示最小值/中间值/最大值。",
|
||
"properties": {
|
||
"value_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"minValue",
|
||
"maxValue",
|
||
"num",
|
||
"percentile",
|
||
"percent",
|
||
"formula",
|
||
"auto"
|
||
],
|
||
"description": "阈值类型。"
|
||
},
|
||
"value": {
|
||
"type": "number",
|
||
"description": "阈值数值，例如百分位或具体数值。"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "该分段对应的颜色。"
|
||
}
|
||
},
|
||
"required": [
|
||
"value_type",
|
||
"color"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "前 N/后 N 规则参数。",
|
||
"properties": {
|
||
"is_bottom": {
|
||
"type": "boolean",
|
||
"description": "是否选取最后 N 个。true 表示最后 N 个，false 表示前 N 个。"
|
||
},
|
||
"value_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"percent",
|
||
"sort"
|
||
],
|
||
"description": "排名方式：percent 表示百分比，sort 表示按条目数。"
|
||
},
|
||
"value": {
|
||
"type": "number",
|
||
"description": "N 或百分比数值。"
|
||
}
|
||
},
|
||
"required": [
|
||
"is_bottom",
|
||
"value_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "平均值规则参数。",
|
||
"properties": {
|
||
"operator": {
|
||
"type": "string",
|
||
"enum": [
|
||
"greaterThan",
|
||
"greaterThanOrEqual",
|
||
"lessThan",
|
||
"lessThanOrEqual"
|
||
],
|
||
"description": "与平均值的比较关系。"
|
||
}
|
||
},
|
||
"required": [
|
||
"operator"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "自定义公式规则参数。",
|
||
"properties": {
|
||
"formula": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "条件公式列表，例如 [\"=A1>0\"]。"
|
||
}
|
||
},
|
||
"required": [
|
||
"formula"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "图标集规则参数。",
|
||
"properties": {
|
||
"icon_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"3Arrows",
|
||
"3ArrowsGray",
|
||
"3Triangles",
|
||
"4ArrowsGray",
|
||
"4Arrows",
|
||
"5ArrowsGray",
|
||
"5Arrows",
|
||
"3Circles",
|
||
"3MultiGraphics",
|
||
"4Circles",
|
||
"5Circles",
|
||
"2Status",
|
||
"3Status",
|
||
"2CommentStatus",
|
||
"3Flags",
|
||
"3Stars",
|
||
"3HeartShaped",
|
||
"3Mood",
|
||
"5CirclesRatio"
|
||
],
|
||
"description": "图标集类型。其中 3Circles/4Circles/5Circles 为不同颜色的实心圆（如红、黄、绿），用于表示状态等级；5CirclesRatio 为不同填充比例的圆（从空心◯到半圆◑到满圆●），用于表示完成度、进度、比例。当涉及半圆、满圆、空心圆、填充比例、进度等场景时，应选择 5CirclesRatio。"
|
||
},
|
||
"hide_value": {
|
||
"type": "boolean",
|
||
"description": "是否隐藏单元格原始值，仅显示图标。"
|
||
},
|
||
"value_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"minValue",
|
||
"maxValue",
|
||
"num",
|
||
"percentile",
|
||
"percent",
|
||
"formula",
|
||
"auto"
|
||
],
|
||
"description": "阈值类型。"
|
||
},
|
||
"operator": {
|
||
"type": "string",
|
||
"enum": [
|
||
"greaterThan",
|
||
"greaterThanOrEqual",
|
||
"lessThan",
|
||
"lessThanOrEqual"
|
||
],
|
||
"description": "与阈值的比较关系。"
|
||
},
|
||
"value": {
|
||
"type": "number",
|
||
"description": "用于比较的数值，含义由 value_type 决定。"
|
||
},
|
||
"reverse_icons": {
|
||
"type": "boolean",
|
||
"description": "是否反转图标顺序。"
|
||
}
|
||
},
|
||
"required": [
|
||
"icon_type",
|
||
"value_type",
|
||
"operator"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"has_ref": {
|
||
"type": "boolean",
|
||
"description": "可选。是否存在引用，用于标记规则是否依赖其他对象。"
|
||
}
|
||
},
|
||
"required": [
|
||
"rule_type",
|
||
"ranges",
|
||
"style"
|
||
]
|
||
}
|
||
},
|
||
"+cond-format-update": {
|
||
"properties": {
|
||
"description": "创建/更新的条件格式属性。",
|
||
"type": "object",
|
||
"properties": {
|
||
"rule_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"duplicateValues",
|
||
"uniqueValues",
|
||
"cellIs",
|
||
"containsText",
|
||
"timePeriod",
|
||
"containsBlanks",
|
||
"notContainsBlanks",
|
||
"dataBar",
|
||
"colorScale",
|
||
"rank",
|
||
"aboveAverage",
|
||
"expression",
|
||
"iconSet"
|
||
],
|
||
"description": "条件格式规则类型。"
|
||
},
|
||
"ranges": {
|
||
"type": "array",
|
||
"description": "应用条件格式的 A1 范围列表。每个元素支持：矩形范围 \"A1:A10\"、整行 \"3:6\"、整列 \"C:C\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。例如 [\"A1:A10\",\"C:C\"]。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"style": {
|
||
"type": "object",
|
||
"description": "命中规则时应用的单元格样式。",
|
||
"properties": {
|
||
"back_color": {
|
||
"type": "string",
|
||
"description": "背景色，CSS 十六进制表示，例如 \"#FF0000\"。"
|
||
},
|
||
"fore_color": {
|
||
"type": "string",
|
||
"description": "前景色/字体颜色。"
|
||
},
|
||
"text_decoration": {
|
||
"type": "string",
|
||
"enum": [
|
||
"none",
|
||
"underline",
|
||
"strikethrough",
|
||
"underline_strikethrough"
|
||
],
|
||
"description": "文字装饰：none=无，underline=下划线，strikethrough=删除线，underline_strikethrough=下划线+删除线。"
|
||
},
|
||
"font": {
|
||
"type": "string",
|
||
"enum": [
|
||
"bold",
|
||
"italic",
|
||
"bold italic"
|
||
],
|
||
"description": "字体样式：\"bold\"=加粗，\"italic\"=斜体，\"bold italic\"=加粗+斜体。"
|
||
}
|
||
}
|
||
},
|
||
"attrs": {
|
||
"type": "array",
|
||
"description": "规则参数列表。不同 rule_type 下取值结构不同。当 rule_type 为 dataBar 时，attrs 必须包含两个对象，分别定义正值和负值的数据条颜色。",
|
||
"items": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"description": "数值比较类规则参数。",
|
||
"properties": {
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"equal",
|
||
"notEqual",
|
||
"greaterThan",
|
||
"greaterThanOrEqual",
|
||
"lessThan",
|
||
"lessThanOrEqual",
|
||
"between",
|
||
"notBetween"
|
||
],
|
||
"description": "比较运算符。"
|
||
},
|
||
"value": {
|
||
"type": "string",
|
||
"description": "用于比较的值，例如 \"100\"、\"hello\"。between/notBetween 时用逗号分隔两个值。"
|
||
}
|
||
},
|
||
"required": [
|
||
"compare_type",
|
||
"value"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "文本包含类规则参数。",
|
||
"properties": {
|
||
"text": {
|
||
"type": "string",
|
||
"description": "用于匹配的文本内容。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"beginsWith",
|
||
"endsWith",
|
||
"containsText",
|
||
"notContains",
|
||
"is"
|
||
],
|
||
"description": "文本匹配方式。"
|
||
}
|
||
},
|
||
"required": [
|
||
"compare_type",
|
||
"text"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "时间段类规则参数。",
|
||
"properties": {
|
||
"operator": {
|
||
"type": "string",
|
||
"enum": [
|
||
"before",
|
||
"is",
|
||
"after"
|
||
],
|
||
"description": "与指定时间段的比较关系。"
|
||
},
|
||
"time_period": {
|
||
"type": "string",
|
||
"enum": [
|
||
"today",
|
||
"yesterday",
|
||
"tomorrow",
|
||
"last7Days",
|
||
"thisMonth",
|
||
"lastMonth",
|
||
"nextMonth",
|
||
"thisWeek",
|
||
"lastWeek",
|
||
"nextWeek"
|
||
],
|
||
"description": "时间段类型。"
|
||
}
|
||
},
|
||
"required": [
|
||
"operator",
|
||
"time_period"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "数据条规则参数。",
|
||
"properties": {
|
||
"gradient": {
|
||
"type": "boolean",
|
||
"description": "是否使用渐变色数据条。"
|
||
},
|
||
"value": {
|
||
"type": "number",
|
||
"description": "阈值或比例值，含义由 value_type 决定。"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "主颜色，例如 \"#63BE7B\"。"
|
||
},
|
||
"hide_value": {
|
||
"type": "boolean",
|
||
"description": "是否隐藏单元格中的原始值，仅显示数据条。"
|
||
},
|
||
"value_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"minValue",
|
||
"maxValue",
|
||
"num",
|
||
"percentile",
|
||
"percent",
|
||
"formula",
|
||
"auto"
|
||
],
|
||
"description": "阈值类型。"
|
||
}
|
||
},
|
||
"required": [
|
||
"color",
|
||
"value_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "色阶规则中的单个分段。ColorScaleAttrs 由 2 或 3 个该对象组成，分别表示最小值/中间值/最大值。",
|
||
"properties": {
|
||
"value_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"minValue",
|
||
"maxValue",
|
||
"num",
|
||
"percentile",
|
||
"percent",
|
||
"formula",
|
||
"auto"
|
||
],
|
||
"description": "阈值类型。"
|
||
},
|
||
"value": {
|
||
"type": "number",
|
||
"description": "阈值数值，例如百分位或具体数值。"
|
||
},
|
||
"color": {
|
||
"type": "string",
|
||
"description": "该分段对应的颜色。"
|
||
}
|
||
},
|
||
"required": [
|
||
"value_type",
|
||
"color"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "前 N/后 N 规则参数。",
|
||
"properties": {
|
||
"is_bottom": {
|
||
"type": "boolean",
|
||
"description": "是否选取最后 N 个。true 表示最后 N 个，false 表示前 N 个。"
|
||
},
|
||
"value_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"percent",
|
||
"sort"
|
||
],
|
||
"description": "排名方式：percent 表示百分比，sort 表示按条目数。"
|
||
},
|
||
"value": {
|
||
"type": "number",
|
||
"description": "N 或百分比数值。"
|
||
}
|
||
},
|
||
"required": [
|
||
"is_bottom",
|
||
"value_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "平均值规则参数。",
|
||
"properties": {
|
||
"operator": {
|
||
"type": "string",
|
||
"enum": [
|
||
"greaterThan",
|
||
"greaterThanOrEqual",
|
||
"lessThan",
|
||
"lessThanOrEqual"
|
||
],
|
||
"description": "与平均值的比较关系。"
|
||
}
|
||
},
|
||
"required": [
|
||
"operator"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "自定义公式规则参数。",
|
||
"properties": {
|
||
"formula": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "条件公式列表，例如 [\"=A1>0\"]。"
|
||
}
|
||
},
|
||
"required": [
|
||
"formula"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "图标集规则参数。",
|
||
"properties": {
|
||
"icon_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"3Arrows",
|
||
"3ArrowsGray",
|
||
"3Triangles",
|
||
"4ArrowsGray",
|
||
"4Arrows",
|
||
"5ArrowsGray",
|
||
"5Arrows",
|
||
"3Circles",
|
||
"3MultiGraphics",
|
||
"4Circles",
|
||
"5Circles",
|
||
"2Status",
|
||
"3Status",
|
||
"2CommentStatus",
|
||
"3Flags",
|
||
"3Stars",
|
||
"3HeartShaped",
|
||
"3Mood",
|
||
"5CirclesRatio"
|
||
],
|
||
"description": "图标集类型。其中 3Circles/4Circles/5Circles 为不同颜色的实心圆（如红、黄、绿），用于表示状态等级；5CirclesRatio 为不同填充比例的圆（从空心◯到半圆◑到满圆●），用于表示完成度、进度、比例。当涉及半圆、满圆、空心圆、填充比例、进度等场景时，应选择 5CirclesRatio。"
|
||
},
|
||
"hide_value": {
|
||
"type": "boolean",
|
||
"description": "是否隐藏单元格原始值，仅显示图标。"
|
||
},
|
||
"value_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"minValue",
|
||
"maxValue",
|
||
"num",
|
||
"percentile",
|
||
"percent",
|
||
"formula",
|
||
"auto"
|
||
],
|
||
"description": "阈值类型。"
|
||
},
|
||
"operator": {
|
||
"type": "string",
|
||
"enum": [
|
||
"greaterThan",
|
||
"greaterThanOrEqual",
|
||
"lessThan",
|
||
"lessThanOrEqual"
|
||
],
|
||
"description": "与阈值的比较关系。"
|
||
},
|
||
"value": {
|
||
"type": "number",
|
||
"description": "用于比较的数值，含义由 value_type 决定。"
|
||
},
|
||
"reverse_icons": {
|
||
"type": "boolean",
|
||
"description": "是否反转图标顺序。"
|
||
}
|
||
},
|
||
"required": [
|
||
"icon_type",
|
||
"value_type",
|
||
"operator"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"has_ref": {
|
||
"type": "boolean",
|
||
"description": "可选。是否存在引用，用于标记规则是否依赖其他对象。"
|
||
}
|
||
},
|
||
"required": [
|
||
"rule_type",
|
||
"ranges",
|
||
"style"
|
||
]
|
||
}
|
||
},
|
||
"+dropdown-set": {
|
||
"options": {
|
||
"description": "列表选项",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"+dropdown-update": {
|
||
"options": {
|
||
"description": "列表选项",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"+filter-create": {
|
||
"properties": {
|
||
"description": "创建/更新的筛选器属性。",
|
||
"type": "object",
|
||
"properties": {
|
||
"range": {
|
||
"type": "string",
|
||
"description": "筛选对象作用的单元格范围（A1 表示法）。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。"
|
||
},
|
||
"rules": {
|
||
"type": "array",
|
||
"description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。update 为整组覆盖（PUT 语义）：传入的 rules 即更新后的完整规则集，会先清空所有现有列的旧规则再应用，未列出的列其旧规则会被清除（不与旧规则合并）；传空数组 [] 即清空所有列的规则。",
|
||
"items": {
|
||
"type": "object",
|
||
"description": "单列筛选规则。",
|
||
"properties": {
|
||
"column_index": {
|
||
"type": "string",
|
||
"description": "作用的列索引，例如 \"A\"、\"B\"。"
|
||
},
|
||
"conditions": {
|
||
"type": "array",
|
||
"description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。",
|
||
"items": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"description": "文本条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"text"
|
||
],
|
||
"description": "条件类型固定为 \"text\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"beginsWith",
|
||
"doesNotBeginWith",
|
||
"endsWith",
|
||
"doesNotEndWith",
|
||
"contains",
|
||
"doesNotContain",
|
||
"equals",
|
||
"notEquals"
|
||
],
|
||
"description": "文本比较方式：beginsWith=以指定文本开头，doesNotBeginWith=不以指定文本开头，endsWith=以指定文本结尾，doesNotEndWith=不以指定文本结尾，contains=包含，doesNotContain=不包含，equals=等于，notEquals=不等于。"
|
||
},
|
||
"values": {
|
||
"type": "array",
|
||
"description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "数值条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"number"
|
||
],
|
||
"description": "条件类型固定为 \"number\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"equal",
|
||
"notEqual",
|
||
"greaterThan",
|
||
"greaterThanOrEqual",
|
||
"lessThan",
|
||
"lessThanOrEqual",
|
||
"between",
|
||
"notBetween"
|
||
],
|
||
"description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。"
|
||
},
|
||
"values": {
|
||
"type": "array",
|
||
"description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。",
|
||
"items": {
|
||
"oneOf": [
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "string"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "颜色条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"color"
|
||
],
|
||
"description": "条件类型固定为 \"color\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"backgroundColor",
|
||
"foregroundColor"
|
||
],
|
||
"description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。"
|
||
},
|
||
"value": {
|
||
"type": "string",
|
||
"description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。"
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "多值条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"multiValue"
|
||
],
|
||
"description": "条件类型固定为 \"multiValue\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"equal",
|
||
"notEqual"
|
||
],
|
||
"description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。"
|
||
},
|
||
"values": {
|
||
"type": "array",
|
||
"description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"date_groups": {
|
||
"type": "array",
|
||
"description": "可选。年月日等聚合筛选信息。",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"year": {
|
||
"type": "number"
|
||
},
|
||
"month": {
|
||
"type": "number"
|
||
},
|
||
"day": {
|
||
"type": "number"
|
||
},
|
||
"hour": {
|
||
"type": "number"
|
||
},
|
||
"minute": {
|
||
"type": "number"
|
||
},
|
||
"second": {
|
||
"type": "number"
|
||
},
|
||
"date_time_grouping": {
|
||
"type": "string",
|
||
"enum": [
|
||
"year",
|
||
"month",
|
||
"day",
|
||
"hour",
|
||
"minute",
|
||
"second"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"filtered_rows": {
|
||
"type": "array",
|
||
"description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。",
|
||
"items": {
|
||
"type": "number"
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"column_index",
|
||
"conditions"
|
||
]
|
||
}
|
||
},
|
||
"filtered_columns": {
|
||
"type": "array",
|
||
"description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"range",
|
||
"rules"
|
||
]
|
||
}
|
||
},
|
||
"+filter-update": {
|
||
"properties": {
|
||
"description": "创建/更新的筛选器属性。",
|
||
"type": "object",
|
||
"properties": {
|
||
"range": {
|
||
"type": "string",
|
||
"description": "筛选对象作用的单元格范围（A1 表示法）。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。"
|
||
},
|
||
"rules": {
|
||
"type": "array",
|
||
"description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。update 为整组覆盖（PUT 语义）：传入的 rules 即更新后的完整规则集，会先清空所有现有列的旧规则再应用，未列出的列其旧规则会被清除（不与旧规则合并）；传空数组 [] 即清空所有列的规则。",
|
||
"items": {
|
||
"type": "object",
|
||
"description": "单列筛选规则。",
|
||
"properties": {
|
||
"column_index": {
|
||
"type": "string",
|
||
"description": "作用的列索引，例如 \"A\"、\"B\"。"
|
||
},
|
||
"conditions": {
|
||
"type": "array",
|
||
"description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。",
|
||
"items": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"description": "文本条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"text"
|
||
],
|
||
"description": "条件类型固定为 \"text\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"beginsWith",
|
||
"doesNotBeginWith",
|
||
"endsWith",
|
||
"doesNotEndWith",
|
||
"contains",
|
||
"doesNotContain",
|
||
"equals",
|
||
"notEquals"
|
||
],
|
||
"description": "文本比较方式：beginsWith=以指定文本开头，doesNotBeginWith=不以指定文本开头，endsWith=以指定文本结尾，doesNotEndWith=不以指定文本结尾，contains=包含，doesNotContain=不包含，equals=等于，notEquals=不等于。"
|
||
},
|
||
"values": {
|
||
"type": "array",
|
||
"description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "数值条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"number"
|
||
],
|
||
"description": "条件类型固定为 \"number\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"equal",
|
||
"notEqual",
|
||
"greaterThan",
|
||
"greaterThanOrEqual",
|
||
"lessThan",
|
||
"lessThanOrEqual",
|
||
"between",
|
||
"notBetween"
|
||
],
|
||
"description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。"
|
||
},
|
||
"values": {
|
||
"type": "array",
|
||
"description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。",
|
||
"items": {
|
||
"oneOf": [
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "string"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "颜色条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"color"
|
||
],
|
||
"description": "条件类型固定为 \"color\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"backgroundColor",
|
||
"foregroundColor"
|
||
],
|
||
"description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。"
|
||
},
|
||
"value": {
|
||
"type": "string",
|
||
"description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。"
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "多值条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"multiValue"
|
||
],
|
||
"description": "条件类型固定为 \"multiValue\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"equal",
|
||
"notEqual"
|
||
],
|
||
"description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。"
|
||
},
|
||
"values": {
|
||
"type": "array",
|
||
"description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"date_groups": {
|
||
"type": "array",
|
||
"description": "可选。年月日等聚合筛选信息。",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"year": {
|
||
"type": "number"
|
||
},
|
||
"month": {
|
||
"type": "number"
|
||
},
|
||
"day": {
|
||
"type": "number"
|
||
},
|
||
"hour": {
|
||
"type": "number"
|
||
},
|
||
"minute": {
|
||
"type": "number"
|
||
},
|
||
"second": {
|
||
"type": "number"
|
||
},
|
||
"date_time_grouping": {
|
||
"type": "string",
|
||
"enum": [
|
||
"year",
|
||
"month",
|
||
"day",
|
||
"hour",
|
||
"minute",
|
||
"second"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"filtered_rows": {
|
||
"type": "array",
|
||
"description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。",
|
||
"items": {
|
||
"type": "number"
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"column_index",
|
||
"conditions"
|
||
]
|
||
}
|
||
},
|
||
"filtered_columns": {
|
||
"type": "array",
|
||
"description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"range",
|
||
"rules"
|
||
]
|
||
}
|
||
},
|
||
"+filter-view-create": {
|
||
"properties": {
|
||
"description": "create / update 的视图属性。create 必须传 range；update 至少传 view_name / range / rules 之一。delete 禁止传该字段。",
|
||
"type": "object",
|
||
"properties": {
|
||
"view_name": {
|
||
"type": "string",
|
||
"description": "可选。视图名称。create 不传时系统自动分配；create / update 传入时若与现有视图重名，会自动以后缀避让，不会抛错。"
|
||
},
|
||
"range": {
|
||
"type": "string",
|
||
"description": "视图作用的单元格范围（A1 表示法）。create 必填；update 可选——未提供时沿用视图当前 range。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。"
|
||
},
|
||
"rules": {
|
||
"type": "array",
|
||
"description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。结构与 manage_filter_object.properties.rules 完全一致。update 同样为整组覆盖（PUT 语义）：传入的 rules 整组替换该视图所有列的规则，未列出的列其旧规则会被清除（不与旧规则合并），传空数组 [] 即清空全部。",
|
||
"items": {
|
||
"type": "object",
|
||
"description": "单列筛选规则。",
|
||
"properties": {
|
||
"column_index": {
|
||
"type": "string",
|
||
"description": "作用的列索引，例如 \"A\"、\"B\"。"
|
||
},
|
||
"conditions": {
|
||
"type": "array",
|
||
"description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。",
|
||
"items": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"description": "文本条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"text"
|
||
],
|
||
"description": "条件类型固定为 \"text\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"beginsWith",
|
||
"doesNotBeginWith",
|
||
"endsWith",
|
||
"doesNotEndWith",
|
||
"contains",
|
||
"doesNotContain",
|
||
"equals",
|
||
"notEquals"
|
||
],
|
||
"description": "文本比较方式:beginsWith=以指定文本开头,doesNotBeginWith=不以指定文本开头,endsWith=以指定文本结尾,doesNotEndWith=不以指定文本结尾,contains=包含,doesNotContain=不包含,equals=等于,notEquals=不等于。"
|
||
},
|
||
"values": {
|
||
"type": "array",
|
||
"description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "数值条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"number"
|
||
],
|
||
"description": "条件类型固定为 \"number\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"equal",
|
||
"notEqual",
|
||
"greaterThan",
|
||
"greaterThanOrEqual",
|
||
"lessThan",
|
||
"lessThanOrEqual",
|
||
"between",
|
||
"notBetween"
|
||
],
|
||
"description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。"
|
||
},
|
||
"values": {
|
||
"type": "array",
|
||
"description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。",
|
||
"items": {
|
||
"oneOf": [
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "string"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "颜色条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"color"
|
||
],
|
||
"description": "条件类型固定为 \"color\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"backgroundColor",
|
||
"foregroundColor"
|
||
],
|
||
"description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。"
|
||
},
|
||
"value": {
|
||
"type": "string",
|
||
"description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。"
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "多值条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"multiValue"
|
||
],
|
||
"description": "条件类型固定为 \"multiValue\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"equal",
|
||
"notEqual"
|
||
],
|
||
"description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。"
|
||
},
|
||
"values": {
|
||
"type": "array",
|
||
"description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"date_groups": {
|
||
"type": "array",
|
||
"description": "可选。年月日等聚合筛选信息。",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"year": {
|
||
"type": "number"
|
||
},
|
||
"month": {
|
||
"type": "number"
|
||
},
|
||
"day": {
|
||
"type": "number"
|
||
},
|
||
"hour": {
|
||
"type": "number"
|
||
},
|
||
"minute": {
|
||
"type": "number"
|
||
},
|
||
"second": {
|
||
"type": "number"
|
||
},
|
||
"date_time_grouping": {
|
||
"type": "string",
|
||
"enum": [
|
||
"year",
|
||
"month",
|
||
"day",
|
||
"hour",
|
||
"minute",
|
||
"second"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"filtered_rows": {
|
||
"type": "array",
|
||
"description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。",
|
||
"items": {
|
||
"type": "number"
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"column_index",
|
||
"conditions"
|
||
]
|
||
}
|
||
},
|
||
"filtered_columns": {
|
||
"type": "array",
|
||
"description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"+filter-view-update": {
|
||
"properties": {
|
||
"description": "create / update 的视图属性。create 必须传 range；update 至少传 view_name / range / rules 之一。delete 禁止传该字段。",
|
||
"type": "object",
|
||
"properties": {
|
||
"view_name": {
|
||
"type": "string",
|
||
"description": "可选。视图名称。create 不传时系统自动分配；create / update 传入时若与现有视图重名，会自动以后缀避让，不会抛错。"
|
||
},
|
||
"range": {
|
||
"type": "string",
|
||
"description": "视图作用的单元格范围（A1 表示法）。create 必填；update 可选——未提供时沿用视图当前 range。支持：矩形范围 \"A1:D100\"、整行 \"3:6\"、整列 \"C:E\"、某一格到列尾 \"D3:D\"、某一格到行尾 \"D3:3\"。"
|
||
},
|
||
"rules": {
|
||
"type": "array",
|
||
"description": "列级筛选规则列表，每一项对应一个具体列的筛选条件。结构与 manage_filter_object.properties.rules 完全一致。update 同样为整组覆盖（PUT 语义）：传入的 rules 整组替换该视图所有列的规则，未列出的列其旧规则会被清除（不与旧规则合并），传空数组 [] 即清空全部。",
|
||
"items": {
|
||
"type": "object",
|
||
"description": "单列筛选规则。",
|
||
"properties": {
|
||
"column_index": {
|
||
"type": "string",
|
||
"description": "作用的列索引，例如 \"A\"、\"B\"。"
|
||
},
|
||
"conditions": {
|
||
"type": "array",
|
||
"description": "该列上的条件列表。**目前每列仅支持 1 个 condition**（传入多个会被拒绝，请用 multiValue 或单条件表达），数组形式为未来扩展多条件组合预留。",
|
||
"items": {
|
||
"oneOf": [
|
||
{
|
||
"type": "object",
|
||
"description": "文本条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"text"
|
||
],
|
||
"description": "条件类型固定为 \"text\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"beginsWith",
|
||
"doesNotBeginWith",
|
||
"endsWith",
|
||
"doesNotEndWith",
|
||
"contains",
|
||
"doesNotContain",
|
||
"equals",
|
||
"notEquals"
|
||
],
|
||
"description": "文本比较方式:beginsWith=以指定文本开头,doesNotBeginWith=不以指定文本开头,endsWith=以指定文本结尾,doesNotEndWith=不以指定文本结尾,contains=包含,doesNotContain=不包含,equals=等于,notEquals=不等于。"
|
||
},
|
||
"values": {
|
||
"type": "array",
|
||
"description": "可选。用于比较的文本值列表，只需要提供一个值，例如 [\"华东\"]。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "数值条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"number"
|
||
],
|
||
"description": "条件类型固定为 \"number\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"equal",
|
||
"notEqual",
|
||
"greaterThan",
|
||
"greaterThanOrEqual",
|
||
"lessThan",
|
||
"lessThanOrEqual",
|
||
"between",
|
||
"notBetween"
|
||
],
|
||
"description": "数值比较方式，例如 greaterThan=大于、between=介于两个值之间。"
|
||
},
|
||
"values": {
|
||
"type": "array",
|
||
"description": "可选。用于比较的数值参数列表。大多数比较运算需要 1 个值（如 [5000]），between/notBetween 需要 2 个值（如 [1000, 5000]）。",
|
||
"items": {
|
||
"oneOf": [
|
||
{
|
||
"type": "number"
|
||
},
|
||
{
|
||
"type": "string"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "颜色条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"color"
|
||
],
|
||
"description": "条件类型固定为 \"color\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"backgroundColor",
|
||
"foregroundColor"
|
||
],
|
||
"description": "颜色比较类型：backgroundColor=按单元格背景色，foregroundColor=按字体颜色。"
|
||
},
|
||
"value": {
|
||
"type": "string",
|
||
"description": "可选。用于匹配的颜色值，使用十六进制颜色字符串，例如 \"#FF0000\"。"
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
},
|
||
{
|
||
"type": "object",
|
||
"description": "多值条件筛选。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"multiValue"
|
||
],
|
||
"description": "条件类型固定为 \"multiValue\"。"
|
||
},
|
||
"compare_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"equal",
|
||
"notEqual"
|
||
],
|
||
"description": "多值比较方式：equal=仅保留 values 中的值，notEqual=排除 values 中的值。"
|
||
},
|
||
"values": {
|
||
"type": "array",
|
||
"description": "可选。参与筛选的枚举值列表，例如 [\"华东\", \"华南\"]。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"date_groups": {
|
||
"type": "array",
|
||
"description": "可选。年月日等聚合筛选信息。",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"year": {
|
||
"type": "number"
|
||
},
|
||
"month": {
|
||
"type": "number"
|
||
},
|
||
"day": {
|
||
"type": "number"
|
||
},
|
||
"hour": {
|
||
"type": "number"
|
||
},
|
||
"minute": {
|
||
"type": "number"
|
||
},
|
||
"second": {
|
||
"type": "number"
|
||
},
|
||
"date_time_grouping": {
|
||
"type": "string",
|
||
"enum": [
|
||
"year",
|
||
"month",
|
||
"day",
|
||
"hour",
|
||
"minute",
|
||
"second"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"compare_type"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"filtered_rows": {
|
||
"type": "array",
|
||
"description": "可选。由该列条件直接导致被隐藏的行索引列表（0-based），用于调试或回显。",
|
||
"items": {
|
||
"type": "number"
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"column_index",
|
||
"conditions"
|
||
]
|
||
}
|
||
},
|
||
"filtered_columns": {
|
||
"type": "array",
|
||
"description": "可选。拥有激活筛选条件的列索引列表，如 [\"A\", \"B\"]，通常等价于 rules 中出现的列索引集合。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"+pivot-create": {
|
||
"properties": {
|
||
"description": "创建/更新的透视表属性。",
|
||
"type": "object",
|
||
"properties": {
|
||
"range": {
|
||
"type": "string",
|
||
"description": "放置透视表的左上角单元格 A1 地址（例如：'F1'）（仅 create 时有效）。可省略——省略后透视表放在新建子表的 A1 位置。"
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"description": "源数据区域地址，格式为 'SheetName!StartCell:EndCell'（例如：'Sheet1!A1:D100'）。create 时必填；update 时提供则切换数据源。"
|
||
},
|
||
"rows": {
|
||
"description": "纵向分组字段（行字段）",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"field": {
|
||
"type": "string",
|
||
"description": "源数据中的字段名（OOXML 字段引用）"
|
||
},
|
||
"display_name": {
|
||
"type": "string",
|
||
"description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用；否则保持源字段原名，透视表产物已足够清晰。"
|
||
},
|
||
"sort": {
|
||
"type": "object",
|
||
"description": "排序配置",
|
||
"properties": {
|
||
"order": {
|
||
"type": "string",
|
||
"enum": [
|
||
"asc",
|
||
"desc"
|
||
],
|
||
"description": "排序方向"
|
||
},
|
||
"by": {
|
||
"type": "string",
|
||
"enum": [
|
||
"label",
|
||
"value"
|
||
],
|
||
"description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序"
|
||
},
|
||
"value_field": {
|
||
"type": "string",
|
||
"description": "by='value' 时必填，指定按哪个值字段排序"
|
||
}
|
||
},
|
||
"required": [
|
||
"order"
|
||
]
|
||
},
|
||
"filter": {
|
||
"type": "object",
|
||
"description": "快速筛选：只显示指定的项目",
|
||
"properties": {
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "要显示的项目列表（其余项目被隐藏）"
|
||
}
|
||
},
|
||
"required": [
|
||
"items"
|
||
]
|
||
},
|
||
"condition_filter": {
|
||
"type": "object",
|
||
"description": "条件筛选：按文本/数值/日期条件筛选",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"text",
|
||
"number",
|
||
"date"
|
||
],
|
||
"description": "条件类型"
|
||
},
|
||
"operator": {
|
||
"type": "string",
|
||
"description": "text: equals|notEquals|contains|notContains|beginsWith|notBeginsWith|endsWith|notEndsWith|empty|notEmpty; number: equals|notEquals|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual|between|notBetween; date: equals|notEquals|earlierThan|earlierThanOrEqual|laterThan|laterThanOrEqual|between|notBetween|today|yesterday|tomorrow|thisWeek|lastWeek|nextWeek|thisMonth|lastMonth|nextMonth|thisQuarter|lastQuarter|nextQuarter|thisYear|lastYear|nextYear|yearToDate|quarter|month"
|
||
},
|
||
"value": {
|
||
"description": "比较值"
|
||
},
|
||
"value2": {
|
||
"description": "'between'/'notBetween' 的第二个边界值"
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"operator"
|
||
]
|
||
},
|
||
"group": {
|
||
"type": "object",
|
||
"description": "分组配置",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"date",
|
||
"number",
|
||
"element"
|
||
],
|
||
"description": "分组类型"
|
||
},
|
||
"date_group_by": {
|
||
"type": "string",
|
||
"enum": [
|
||
"year",
|
||
"yearMonth",
|
||
"yearQuarter",
|
||
"yearMonthDate",
|
||
"quarter",
|
||
"month",
|
||
"monthDate",
|
||
"date",
|
||
"hour",
|
||
"hourMinute",
|
||
"minute"
|
||
],
|
||
"description": "日期分组粒度（type='date' 时必填）"
|
||
},
|
||
"interval": {
|
||
"type": "number",
|
||
"description": "数值分组间隔（type='number' 时必填）"
|
||
},
|
||
"start": {
|
||
"type": "number",
|
||
"description": "数值分组起始值"
|
||
},
|
||
"end": {
|
||
"type": "number",
|
||
"description": "数值分组结束值"
|
||
},
|
||
"groups": {
|
||
"type": "object",
|
||
"description": "元素分组：组名 -> 项目列表（type='element' 时必填）",
|
||
"additionalProperties": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
}
|
||
},
|
||
"required": [
|
||
"field"
|
||
]
|
||
}
|
||
},
|
||
"columns": {
|
||
"description": "横向分组字段（列字段）",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"field": {
|
||
"type": "string",
|
||
"description": "源数据中的字段名（OOXML 字段引用）"
|
||
},
|
||
"display_name": {
|
||
"type": "string",
|
||
"description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。"
|
||
},
|
||
"sort": {
|
||
"type": "object",
|
||
"description": "排序配置",
|
||
"properties": {
|
||
"order": {
|
||
"type": "string",
|
||
"enum": [
|
||
"asc",
|
||
"desc"
|
||
],
|
||
"description": "排序方向"
|
||
},
|
||
"by": {
|
||
"type": "string",
|
||
"enum": [
|
||
"label",
|
||
"value"
|
||
],
|
||
"description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序"
|
||
},
|
||
"value_field": {
|
||
"type": "string",
|
||
"description": "by='value' 时必填，指定按哪个值字段排序"
|
||
}
|
||
},
|
||
"required": [
|
||
"order"
|
||
]
|
||
},
|
||
"filter": {
|
||
"type": "object",
|
||
"description": "快速筛选：只显示指定的项目",
|
||
"properties": {
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "要显示的项目列表（其余项目被隐藏）"
|
||
}
|
||
},
|
||
"required": [
|
||
"items"
|
||
]
|
||
},
|
||
"condition_filter": {
|
||
"type": "object",
|
||
"description": "条件筛选：按文本/数值/日期条件筛选",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"text",
|
||
"number",
|
||
"date"
|
||
],
|
||
"description": "条件类型"
|
||
},
|
||
"operator": {
|
||
"type": "string",
|
||
"description": "text: equals|notEquals|contains|notContains|beginsWith|notBeginsWith|endsWith|notEndsWith|empty|notEmpty; number: equals|notEquals|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual|between|notBetween; date: equals|notEquals|earlierThan|earlierThanOrEqual|laterThan|laterThanOrEqual|between|notBetween|today|yesterday|tomorrow|thisWeek|lastWeek|nextWeek|thisMonth|lastMonth|nextMonth|thisQuarter|lastQuarter|nextQuarter|thisYear|lastYear|nextYear|yearToDate|quarter|month"
|
||
},
|
||
"value": {
|
||
"description": "比较值"
|
||
},
|
||
"value2": {
|
||
"description": "'between'/'notBetween' 的第二个边界值"
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"operator"
|
||
]
|
||
},
|
||
"group": {
|
||
"type": "object",
|
||
"description": "分组配置",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"date",
|
||
"number",
|
||
"element"
|
||
],
|
||
"description": "分组类型"
|
||
},
|
||
"date_group_by": {
|
||
"type": "string",
|
||
"enum": [
|
||
"year",
|
||
"yearMonth",
|
||
"yearQuarter",
|
||
"yearMonthDate",
|
||
"quarter",
|
||
"month",
|
||
"monthDate",
|
||
"date",
|
||
"hour",
|
||
"hourMinute",
|
||
"minute"
|
||
],
|
||
"description": "日期分组粒度（type='date' 时必填）"
|
||
},
|
||
"interval": {
|
||
"type": "number",
|
||
"description": "数值分组间隔（type='number' 时必填）"
|
||
},
|
||
"start": {
|
||
"type": "number",
|
||
"description": "数值分组起始值"
|
||
},
|
||
"end": {
|
||
"type": "number",
|
||
"description": "数值分组结束值"
|
||
},
|
||
"groups": {
|
||
"type": "object",
|
||
"description": "元素分组：组名 -> 项目列表（type='element' 时必填）",
|
||
"additionalProperties": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
}
|
||
},
|
||
"required": [
|
||
"field"
|
||
]
|
||
}
|
||
},
|
||
"filters": {
|
||
"description": "筛选区域字段（页字段）",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"field": {
|
||
"type": "string",
|
||
"description": "源数据中的字段名（OOXML 字段引用）"
|
||
},
|
||
"display_name": {
|
||
"type": "string",
|
||
"description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。"
|
||
},
|
||
"filter": {
|
||
"type": "object",
|
||
"description": "快速筛选：只显示指定的项目",
|
||
"properties": {
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "要显示的项目列表（其余项目被隐藏）"
|
||
}
|
||
},
|
||
"required": [
|
||
"items"
|
||
]
|
||
},
|
||
"condition_filter": {
|
||
"type": "object",
|
||
"description": "条件筛选：按文本/数值/日期条件筛选",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"text",
|
||
"number",
|
||
"date"
|
||
],
|
||
"description": "条件类型"
|
||
},
|
||
"operator": {
|
||
"type": "string",
|
||
"description": "text: equals|notEquals|contains|notContains|beginsWith|notBeginsWith|endsWith|notEndsWith|empty|notEmpty; number: equals|notEquals|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual|between|notBetween; date: equals|notEquals|earlierThan|earlierThanOrEqual|laterThan|laterThanOrEqual|between|notBetween|today|yesterday|tomorrow|thisWeek|lastWeek|nextWeek|thisMonth|lastMonth|nextMonth|thisQuarter|lastQuarter|nextQuarter|thisYear|lastYear|nextYear|yearToDate|quarter|month"
|
||
},
|
||
"value": {
|
||
"description": "比较值"
|
||
},
|
||
"value2": {
|
||
"description": "'between'/'notBetween' 的第二个边界值"
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"operator"
|
||
]
|
||
},
|
||
"group": {
|
||
"type": "object",
|
||
"description": "分组配置",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"date",
|
||
"number",
|
||
"element"
|
||
],
|
||
"description": "分组类型"
|
||
},
|
||
"date_group_by": {
|
||
"type": "string",
|
||
"enum": [
|
||
"year",
|
||
"yearMonth",
|
||
"yearQuarter",
|
||
"yearMonthDate",
|
||
"quarter",
|
||
"month",
|
||
"monthDate",
|
||
"date",
|
||
"hour",
|
||
"hourMinute",
|
||
"minute"
|
||
],
|
||
"description": "日期分组粒度（type='date' 时必填）"
|
||
},
|
||
"interval": {
|
||
"type": "number",
|
||
"description": "数值分组间隔（type='number' 时必填）"
|
||
},
|
||
"start": {
|
||
"type": "number",
|
||
"description": "数值分组起始值"
|
||
},
|
||
"end": {
|
||
"type": "number",
|
||
"description": "数值分组结束值"
|
||
},
|
||
"groups": {
|
||
"type": "object",
|
||
"description": "元素分组：组名 -> 项目列表（type='element' 时必填）",
|
||
"additionalProperties": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
}
|
||
},
|
||
"required": [
|
||
"field"
|
||
]
|
||
}
|
||
},
|
||
"values": {
|
||
"minItems": 1,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"field": {
|
||
"type": "string",
|
||
"description": "要汇总的源数据字段名"
|
||
},
|
||
"display_name": {
|
||
"type": "string",
|
||
"description": "字段在透视表中的显示名（典型场景：把 count(销售额) 的值列头显示为 'GMV'）。不传则使用源字段原名。仅在用户明确要求重命名时使用。"
|
||
},
|
||
"summarize_by": {
|
||
"default": "sum",
|
||
"description": "汇总函数",
|
||
"type": "string",
|
||
"enum": [
|
||
"sum",
|
||
"count",
|
||
"average",
|
||
"max",
|
||
"min",
|
||
"product",
|
||
"countNums",
|
||
"stdDev",
|
||
"stdDevp",
|
||
"var",
|
||
"varp",
|
||
"distinct",
|
||
"median"
|
||
]
|
||
},
|
||
"show_data_as": {
|
||
"type": "string",
|
||
"description": "值显示方式（默认 'normal'）",
|
||
"enum": [
|
||
"normal",
|
||
"percentOfTotal",
|
||
"percentOfCol",
|
||
"percentOfRow",
|
||
"percentOfParentRow",
|
||
"percentOfParentCol",
|
||
"index"
|
||
]
|
||
},
|
||
"base_field": {
|
||
"type": "string",
|
||
"description": "show_data_as 需要基准字段时的字段名"
|
||
}
|
||
},
|
||
"required": [
|
||
"field"
|
||
]
|
||
},
|
||
"description": "要汇总的字段（至少需要 1 个）"
|
||
},
|
||
"auto_fit_col": {
|
||
"type": "boolean",
|
||
"description": "是否自动调整列宽以适应内容"
|
||
},
|
||
"show_row_grand_total": {
|
||
"type": "boolean",
|
||
"description": "是否显示行总计（默认 true）"
|
||
},
|
||
"show_col_grand_total": {
|
||
"type": "boolean",
|
||
"description": "是否显示列总计（默认 true）"
|
||
},
|
||
"show_subtotals": {
|
||
"type": "boolean",
|
||
"description": "是否显示分类小计（默认 true，应用于所有字段）"
|
||
},
|
||
"repeat_row_labels": {
|
||
"type": "boolean",
|
||
"description": "是否显示重复项标签"
|
||
},
|
||
"calculated_fields": {
|
||
"type": "array",
|
||
"description": "计算字段列表",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "计算字段的显示名称"
|
||
},
|
||
"formula": {
|
||
"type": "string",
|
||
"description": "公式表达式，引用其他字段名，例如 \"'Sales' + 'Tax'\""
|
||
},
|
||
"summarize_by": {
|
||
"type": "string",
|
||
"default": "sum",
|
||
"description": "计算字段汇总方式（默认 'sum'，仅支持 sum/custom 两种）：'sum' 表示先对 formula 中引用的各源字段分别求和后再代入公式（formula 是逐字段求和后的标量表达式，例如 \"'Sales'+'Tax'\" 等价于 SUM(Sales)+SUM(Tax)）；'custom' 表示数组直接传给 formula，要求 formula 自带聚合函数（例如 \"SUM('Sales')+SUM('Tax')\" 或 \"AVERAGE('Sales')\"）。需要 count/average/max/min 等其他聚合方式时，请改用 values[] 字段对源字段直接聚合，calculated_fields 不适用。",
|
||
"enum": [
|
||
"sum",
|
||
"custom"
|
||
]
|
||
}
|
||
},
|
||
"required": [
|
||
"name",
|
||
"formula"
|
||
]
|
||
}
|
||
},
|
||
"collapse": {
|
||
"type": "object",
|
||
"description": "行字段展开/折叠状态：字段名 -> 要折叠的项目列表",
|
||
"additionalProperties": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"+pivot-update": {
|
||
"properties": {
|
||
"description": "创建/更新的透视表属性。",
|
||
"type": "object",
|
||
"properties": {
|
||
"range": {
|
||
"type": "string",
|
||
"description": "放置透视表的左上角单元格 A1 地址（例如：'F1'）（仅 create 时有效）。可省略——省略后透视表放在新建子表的 A1 位置。"
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"description": "源数据区域地址，格式为 'SheetName!StartCell:EndCell'（例如：'Sheet1!A1:D100'）。create 时必填；update 时提供则切换数据源。"
|
||
},
|
||
"rows": {
|
||
"description": "纵向分组字段（行字段）",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"field": {
|
||
"type": "string",
|
||
"description": "源数据中的字段名（OOXML 字段引用）"
|
||
},
|
||
"display_name": {
|
||
"type": "string",
|
||
"description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用；否则保持源字段原名，透视表产物已足够清晰。"
|
||
},
|
||
"sort": {
|
||
"type": "object",
|
||
"description": "排序配置",
|
||
"properties": {
|
||
"order": {
|
||
"type": "string",
|
||
"enum": [
|
||
"asc",
|
||
"desc"
|
||
],
|
||
"description": "排序方向"
|
||
},
|
||
"by": {
|
||
"type": "string",
|
||
"enum": [
|
||
"label",
|
||
"value"
|
||
],
|
||
"description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序"
|
||
},
|
||
"value_field": {
|
||
"type": "string",
|
||
"description": "by='value' 时必填，指定按哪个值字段排序"
|
||
}
|
||
},
|
||
"required": [
|
||
"order"
|
||
]
|
||
},
|
||
"filter": {
|
||
"type": "object",
|
||
"description": "快速筛选：只显示指定的项目",
|
||
"properties": {
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "要显示的项目列表（其余项目被隐藏）"
|
||
}
|
||
},
|
||
"required": [
|
||
"items"
|
||
]
|
||
},
|
||
"condition_filter": {
|
||
"type": "object",
|
||
"description": "条件筛选：按文本/数值/日期条件筛选",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"text",
|
||
"number",
|
||
"date"
|
||
],
|
||
"description": "条件类型"
|
||
},
|
||
"operator": {
|
||
"type": "string",
|
||
"description": "text: equals|notEquals|contains|notContains|beginsWith|notBeginsWith|endsWith|notEndsWith|empty|notEmpty; number: equals|notEquals|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual|between|notBetween; date: equals|notEquals|earlierThan|earlierThanOrEqual|laterThan|laterThanOrEqual|between|notBetween|today|yesterday|tomorrow|thisWeek|lastWeek|nextWeek|thisMonth|lastMonth|nextMonth|thisQuarter|lastQuarter|nextQuarter|thisYear|lastYear|nextYear|yearToDate|quarter|month"
|
||
},
|
||
"value": {
|
||
"description": "比较值"
|
||
},
|
||
"value2": {
|
||
"description": "'between'/'notBetween' 的第二个边界值"
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"operator"
|
||
]
|
||
},
|
||
"group": {
|
||
"type": "object",
|
||
"description": "分组配置",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"date",
|
||
"number",
|
||
"element"
|
||
],
|
||
"description": "分组类型"
|
||
},
|
||
"date_group_by": {
|
||
"type": "string",
|
||
"enum": [
|
||
"year",
|
||
"yearMonth",
|
||
"yearQuarter",
|
||
"yearMonthDate",
|
||
"quarter",
|
||
"month",
|
||
"monthDate",
|
||
"date",
|
||
"hour",
|
||
"hourMinute",
|
||
"minute"
|
||
],
|
||
"description": "日期分组粒度（type='date' 时必填）"
|
||
},
|
||
"interval": {
|
||
"type": "number",
|
||
"description": "数值分组间隔（type='number' 时必填）"
|
||
},
|
||
"start": {
|
||
"type": "number",
|
||
"description": "数值分组起始值"
|
||
},
|
||
"end": {
|
||
"type": "number",
|
||
"description": "数值分组结束值"
|
||
},
|
||
"groups": {
|
||
"type": "object",
|
||
"description": "元素分组：组名 -> 项目列表（type='element' 时必填）",
|
||
"additionalProperties": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
}
|
||
},
|
||
"required": [
|
||
"field"
|
||
]
|
||
}
|
||
},
|
||
"columns": {
|
||
"description": "横向分组字段（列字段）",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"field": {
|
||
"type": "string",
|
||
"description": "源数据中的字段名（OOXML 字段引用）"
|
||
},
|
||
"display_name": {
|
||
"type": "string",
|
||
"description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。"
|
||
},
|
||
"sort": {
|
||
"type": "object",
|
||
"description": "排序配置",
|
||
"properties": {
|
||
"order": {
|
||
"type": "string",
|
||
"enum": [
|
||
"asc",
|
||
"desc"
|
||
],
|
||
"description": "排序方向"
|
||
},
|
||
"by": {
|
||
"type": "string",
|
||
"enum": [
|
||
"label",
|
||
"value"
|
||
],
|
||
"description": "'label' = 按字段标签排序（默认），'value' = 按某个值字段的汇总结果排序"
|
||
},
|
||
"value_field": {
|
||
"type": "string",
|
||
"description": "by='value' 时必填，指定按哪个值字段排序"
|
||
}
|
||
},
|
||
"required": [
|
||
"order"
|
||
]
|
||
},
|
||
"filter": {
|
||
"type": "object",
|
||
"description": "快速筛选：只显示指定的项目",
|
||
"properties": {
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "要显示的项目列表（其余项目被隐藏）"
|
||
}
|
||
},
|
||
"required": [
|
||
"items"
|
||
]
|
||
},
|
||
"condition_filter": {
|
||
"type": "object",
|
||
"description": "条件筛选：按文本/数值/日期条件筛选",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"text",
|
||
"number",
|
||
"date"
|
||
],
|
||
"description": "条件类型"
|
||
},
|
||
"operator": {
|
||
"type": "string",
|
||
"description": "text: equals|notEquals|contains|notContains|beginsWith|notBeginsWith|endsWith|notEndsWith|empty|notEmpty; number: equals|notEquals|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual|between|notBetween; date: equals|notEquals|earlierThan|earlierThanOrEqual|laterThan|laterThanOrEqual|between|notBetween|today|yesterday|tomorrow|thisWeek|lastWeek|nextWeek|thisMonth|lastMonth|nextMonth|thisQuarter|lastQuarter|nextQuarter|thisYear|lastYear|nextYear|yearToDate|quarter|month"
|
||
},
|
||
"value": {
|
||
"description": "比较值"
|
||
},
|
||
"value2": {
|
||
"description": "'between'/'notBetween' 的第二个边界值"
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"operator"
|
||
]
|
||
},
|
||
"group": {
|
||
"type": "object",
|
||
"description": "分组配置",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"date",
|
||
"number",
|
||
"element"
|
||
],
|
||
"description": "分组类型"
|
||
},
|
||
"date_group_by": {
|
||
"type": "string",
|
||
"enum": [
|
||
"year",
|
||
"yearMonth",
|
||
"yearQuarter",
|
||
"yearMonthDate",
|
||
"quarter",
|
||
"month",
|
||
"monthDate",
|
||
"date",
|
||
"hour",
|
||
"hourMinute",
|
||
"minute"
|
||
],
|
||
"description": "日期分组粒度（type='date' 时必填）"
|
||
},
|
||
"interval": {
|
||
"type": "number",
|
||
"description": "数值分组间隔（type='number' 时必填）"
|
||
},
|
||
"start": {
|
||
"type": "number",
|
||
"description": "数值分组起始值"
|
||
},
|
||
"end": {
|
||
"type": "number",
|
||
"description": "数值分组结束值"
|
||
},
|
||
"groups": {
|
||
"type": "object",
|
||
"description": "元素分组：组名 -> 项目列表（type='element' 时必填）",
|
||
"additionalProperties": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
}
|
||
},
|
||
"required": [
|
||
"field"
|
||
]
|
||
}
|
||
},
|
||
"filters": {
|
||
"description": "筛选区域字段（页字段）",
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"field": {
|
||
"type": "string",
|
||
"description": "源数据中的字段名（OOXML 字段引用）"
|
||
},
|
||
"display_name": {
|
||
"type": "string",
|
||
"description": "字段在透视表中的显示名。不传则使用源字段原名。仅在用户明确要求重命名时使用。"
|
||
},
|
||
"filter": {
|
||
"type": "object",
|
||
"description": "快速筛选：只显示指定的项目",
|
||
"properties": {
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
},
|
||
"description": "要显示的项目列表（其余项目被隐藏）"
|
||
}
|
||
},
|
||
"required": [
|
||
"items"
|
||
]
|
||
},
|
||
"condition_filter": {
|
||
"type": "object",
|
||
"description": "条件筛选：按文本/数值/日期条件筛选",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"text",
|
||
"number",
|
||
"date"
|
||
],
|
||
"description": "条件类型"
|
||
},
|
||
"operator": {
|
||
"type": "string",
|
||
"description": "text: equals|notEquals|contains|notContains|beginsWith|notBeginsWith|endsWith|notEndsWith|empty|notEmpty; number: equals|notEquals|greaterThan|greaterThanOrEqual|lessThan|lessThanOrEqual|between|notBetween; date: equals|notEquals|earlierThan|earlierThanOrEqual|laterThan|laterThanOrEqual|between|notBetween|today|yesterday|tomorrow|thisWeek|lastWeek|nextWeek|thisMonth|lastMonth|nextMonth|thisQuarter|lastQuarter|nextQuarter|thisYear|lastYear|nextYear|yearToDate|quarter|month"
|
||
},
|
||
"value": {
|
||
"description": "比较值"
|
||
},
|
||
"value2": {
|
||
"description": "'between'/'notBetween' 的第二个边界值"
|
||
}
|
||
},
|
||
"required": [
|
||
"type",
|
||
"operator"
|
||
]
|
||
},
|
||
"group": {
|
||
"type": "object",
|
||
"description": "分组配置",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"date",
|
||
"number",
|
||
"element"
|
||
],
|
||
"description": "分组类型"
|
||
},
|
||
"date_group_by": {
|
||
"type": "string",
|
||
"enum": [
|
||
"year",
|
||
"yearMonth",
|
||
"yearQuarter",
|
||
"yearMonthDate",
|
||
"quarter",
|
||
"month",
|
||
"monthDate",
|
||
"date",
|
||
"hour",
|
||
"hourMinute",
|
||
"minute"
|
||
],
|
||
"description": "日期分组粒度（type='date' 时必填）"
|
||
},
|
||
"interval": {
|
||
"type": "number",
|
||
"description": "数值分组间隔（type='number' 时必填）"
|
||
},
|
||
"start": {
|
||
"type": "number",
|
||
"description": "数值分组起始值"
|
||
},
|
||
"end": {
|
||
"type": "number",
|
||
"description": "数值分组结束值"
|
||
},
|
||
"groups": {
|
||
"type": "object",
|
||
"description": "元素分组：组名 -> 项目列表（type='element' 时必填）",
|
||
"additionalProperties": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
}
|
||
},
|
||
"required": [
|
||
"field"
|
||
]
|
||
}
|
||
},
|
||
"values": {
|
||
"minItems": 1,
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"field": {
|
||
"type": "string",
|
||
"description": "要汇总的源数据字段名"
|
||
},
|
||
"display_name": {
|
||
"type": "string",
|
||
"description": "字段在透视表中的显示名（典型场景：把 count(销售额) 的值列头显示为 'GMV'）。不传则使用源字段原名。仅在用户明确要求重命名时使用。"
|
||
},
|
||
"summarize_by": {
|
||
"default": "sum",
|
||
"description": "汇总函数",
|
||
"type": "string",
|
||
"enum": [
|
||
"sum",
|
||
"count",
|
||
"average",
|
||
"max",
|
||
"min",
|
||
"product",
|
||
"countNums",
|
||
"stdDev",
|
||
"stdDevp",
|
||
"var",
|
||
"varp",
|
||
"distinct",
|
||
"median"
|
||
]
|
||
},
|
||
"show_data_as": {
|
||
"type": "string",
|
||
"description": "值显示方式（默认 'normal'）",
|
||
"enum": [
|
||
"normal",
|
||
"percentOfTotal",
|
||
"percentOfCol",
|
||
"percentOfRow",
|
||
"percentOfParentRow",
|
||
"percentOfParentCol",
|
||
"index"
|
||
]
|
||
},
|
||
"base_field": {
|
||
"type": "string",
|
||
"description": "show_data_as 需要基准字段时的字段名"
|
||
}
|
||
},
|
||
"required": [
|
||
"field"
|
||
]
|
||
},
|
||
"description": "要汇总的字段（至少需要 1 个）"
|
||
},
|
||
"auto_fit_col": {
|
||
"type": "boolean",
|
||
"description": "是否自动调整列宽以适应内容"
|
||
},
|
||
"show_row_grand_total": {
|
||
"type": "boolean",
|
||
"description": "是否显示行总计（默认 true）"
|
||
},
|
||
"show_col_grand_total": {
|
||
"type": "boolean",
|
||
"description": "是否显示列总计（默认 true）"
|
||
},
|
||
"show_subtotals": {
|
||
"type": "boolean",
|
||
"description": "是否显示分类小计（默认 true，应用于所有字段）"
|
||
},
|
||
"repeat_row_labels": {
|
||
"type": "boolean",
|
||
"description": "是否显示重复项标签"
|
||
},
|
||
"calculated_fields": {
|
||
"type": "array",
|
||
"description": "计算字段列表",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "计算字段的显示名称"
|
||
},
|
||
"formula": {
|
||
"type": "string",
|
||
"description": "公式表达式，引用其他字段名，例如 \"'Sales' + 'Tax'\""
|
||
},
|
||
"summarize_by": {
|
||
"type": "string",
|
||
"default": "sum",
|
||
"description": "计算字段汇总方式（默认 'sum'，仅支持 sum/custom 两种）：'sum' 表示先对 formula 中引用的各源字段分别求和后再代入公式（formula 是逐字段求和后的标量表达式，例如 \"'Sales'+'Tax'\" 等价于 SUM(Sales)+SUM(Tax)）；'custom' 表示数组直接传给 formula，要求 formula 自带聚合函数（例如 \"SUM('Sales')+SUM('Tax')\" 或 \"AVERAGE('Sales')\"）。需要 count/average/max/min 等其他聚合方式时，请改用 values[] 字段对源字段直接聚合，calculated_fields 不适用。",
|
||
"enum": [
|
||
"sum",
|
||
"custom"
|
||
]
|
||
}
|
||
},
|
||
"required": [
|
||
"name",
|
||
"formula"
|
||
]
|
||
}
|
||
},
|
||
"collapse": {
|
||
"type": "object",
|
||
"description": "行字段展开/折叠状态：字段名 -> 要折叠的项目列表",
|
||
"additionalProperties": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"+range-sort": {
|
||
"sort-keys": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"column": {
|
||
"type": "string",
|
||
"description": "排序依据的列字母（如 \"C\"、\"D\"），必须在 range 范围内"
|
||
},
|
||
"ascending": {
|
||
"type": "boolean",
|
||
"description": "是否升序排序"
|
||
}
|
||
},
|
||
"required": [
|
||
"column",
|
||
"ascending"
|
||
]
|
||
},
|
||
"description": "排序条件列表（仅 sort 操作）。支持多级排序，靠前的条件优先级更高。"
|
||
}
|
||
},
|
||
"+sparkline-create": {
|
||
"properties": {
|
||
"description": "创建/更新/部分删除的迷你图属性。delete 时不传 sparklines 即删整组，传则删指定项。",
|
||
"type": "object",
|
||
"properties": {
|
||
"config": {
|
||
"type": "object",
|
||
"description": "迷你图样式配置, 相同 groupId 的迷你图共享相同的样式。",
|
||
"properties": {
|
||
"theme_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"pro",
|
||
"light",
|
||
"soft",
|
||
"brand",
|
||
"fresh"
|
||
],
|
||
"description": "主题类型：pro、light、soft、brand、fresh。"
|
||
},
|
||
"non_num_show_as": {
|
||
"type": "string",
|
||
"enum": [
|
||
"zero",
|
||
"gap",
|
||
"average"
|
||
],
|
||
"description": "非数字单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。"
|
||
},
|
||
"empty_show_as": {
|
||
"type": "string",
|
||
"enum": [
|
||
"zero",
|
||
"gap",
|
||
"average"
|
||
],
|
||
"description": "空单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。"
|
||
},
|
||
"contain_hidden_cells": {
|
||
"type": "boolean",
|
||
"description": "隐藏的单元格数据是否参与绘制。"
|
||
},
|
||
"series_color": {
|
||
"type": "string",
|
||
"description": "主系列颜色，例如 \"#4472C4\"。"
|
||
},
|
||
"points": {
|
||
"type": "object",
|
||
"description": "特殊点样式配置，包含高点、低点、标记点、首点、尾点、负点。",
|
||
"properties": {
|
||
"last_point": {
|
||
"type": "object",
|
||
"description": "尾点配置，最后一个数据点的样式。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "点的颜色。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示该点。"
|
||
}
|
||
}
|
||
},
|
||
"negative_point": {
|
||
"type": "object",
|
||
"description": "负点配置，负数点的样式。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "点的颜色。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示该点。"
|
||
}
|
||
}
|
||
},
|
||
"markers_point": {
|
||
"type": "object",
|
||
"description": "标记点配置，所有标记点的样式。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "点的颜色。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示该点。"
|
||
}
|
||
}
|
||
},
|
||
"first_point": {
|
||
"type": "object",
|
||
"description": "首点配置，第一个数据点的样式。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "点的颜色。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示该点。"
|
||
}
|
||
}
|
||
},
|
||
"high_point": {
|
||
"type": "object",
|
||
"description": "高点配置，最高点的样式。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "点的颜色。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示该点。"
|
||
}
|
||
}
|
||
},
|
||
"low_point": {
|
||
"type": "object",
|
||
"description": "低点配置，最低点的样式。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "点的颜色。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示该点。"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"line_width": {
|
||
"type": "number",
|
||
"enum": [
|
||
1,
|
||
2,
|
||
3,
|
||
4
|
||
],
|
||
"description": "折线图线宽，可选值：1=1px，2=2px，3=3px，4=4px。"
|
||
},
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"line",
|
||
"column",
|
||
"win_loss"
|
||
],
|
||
"description": "迷你图类型，可选值：line=折线图，column=柱形图，win_loss=盈亏图。"
|
||
},
|
||
"axis": {
|
||
"type": "object",
|
||
"description": "坐标轴配置，包含坐标轴颜色、是否翻转、是否显示坐标轴。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "坐标轴颜色。"
|
||
},
|
||
"reverse": {
|
||
"type": "boolean",
|
||
"description": "是否翻转坐标轴方向。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示坐标轴。"
|
||
}
|
||
}
|
||
},
|
||
"show_gradient": {
|
||
"type": "boolean",
|
||
"description": "是否显示渐变效果。"
|
||
},
|
||
"show_radius": {
|
||
"type": "boolean",
|
||
"description": "是否显示圆角，仅对柱形图和盈亏图生效。"
|
||
},
|
||
"extremum_max": {
|
||
"type": "object",
|
||
"description": "最大极值配置，包含极值类型、极值。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"individual",
|
||
"group",
|
||
"custom"
|
||
],
|
||
"description": "极值类型，可选值：individual=单个迷你图极值，group=同组内极值，custom=自定义。"
|
||
},
|
||
"value": {
|
||
"type": "number",
|
||
"description": "当 type='custom' 时生效的具体数值。"
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
},
|
||
"extremum_min": {
|
||
"type": "object",
|
||
"description": "最小极值配置，包含极值类型、极值。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"individual",
|
||
"group",
|
||
"custom"
|
||
],
|
||
"description": "极值类型：individual=单个迷你图极值，group=同组内极值，custom=自定义。"
|
||
},
|
||
"value": {
|
||
"type": "number",
|
||
"description": "当 type='custom' 时生效的具体数值。"
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"sparklines": {
|
||
"type": "array",
|
||
"description": "迷你图项列表。create 时为待创建项（每项需 position + source/source_range）；update 时为待变更/新增项（每项需 sparkline_id；upsert=true 新增时需 position + source）；delete 时为待删除项（每项需 sparkline_id）。",
|
||
"items": {
|
||
"type": "object",
|
||
"description": "单个迷你图项。",
|
||
"properties": {
|
||
"sparkline_id": {
|
||
"type": "string",
|
||
"description": "迷你图 reference_id。create 时可选（不传系统生成）；update / delete 时必填。"
|
||
},
|
||
"position": {
|
||
"type": "object",
|
||
"description": "迷你图位置。create / update 时必填；delete 时省略。",
|
||
"properties": {
|
||
"row": {
|
||
"type": "number",
|
||
"minimum": 0,
|
||
"description": "行索引（0-based）"
|
||
},
|
||
"col": {
|
||
"type": "string",
|
||
"description": "列索引，例如 \"A\"、\"B\""
|
||
}
|
||
},
|
||
"required": [
|
||
"row",
|
||
"col"
|
||
]
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"description": "A1 范围字符串，表示数据来源，例如 \"Sheet1!A2:A10\"。create 必填（与 source_range 二选一）；update 仅在改源时传；delete 时省略。"
|
||
},
|
||
"source_range": {
|
||
"type": "object",
|
||
"description": "结构化数据源范围（与 source 等价）。",
|
||
"properties": {
|
||
"range": {
|
||
"type": "string",
|
||
"description": "数据源的 A1 引用区域"
|
||
}
|
||
},
|
||
"required": [
|
||
"range"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"+sparkline-update": {
|
||
"properties": {
|
||
"description": "创建/更新/部分删除的迷你图属性。delete 时不传 sparklines 即删整组，传则删指定项。",
|
||
"type": "object",
|
||
"properties": {
|
||
"config": {
|
||
"type": "object",
|
||
"description": "迷你图样式配置, 相同 groupId 的迷你图共享相同的样式。",
|
||
"properties": {
|
||
"theme_type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"pro",
|
||
"light",
|
||
"soft",
|
||
"brand",
|
||
"fresh"
|
||
],
|
||
"description": "主题类型：pro、light、soft、brand、fresh。"
|
||
},
|
||
"non_num_show_as": {
|
||
"type": "string",
|
||
"enum": [
|
||
"zero",
|
||
"gap",
|
||
"average"
|
||
],
|
||
"description": "非数字单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。"
|
||
},
|
||
"empty_show_as": {
|
||
"type": "string",
|
||
"enum": [
|
||
"zero",
|
||
"gap",
|
||
"average"
|
||
],
|
||
"description": "空单元格显示方式：zero=显示为0，gap=显示为间距，average=取前后均值。"
|
||
},
|
||
"contain_hidden_cells": {
|
||
"type": "boolean",
|
||
"description": "隐藏的单元格数据是否参与绘制。"
|
||
},
|
||
"series_color": {
|
||
"type": "string",
|
||
"description": "主系列颜色，例如 \"#4472C4\"。"
|
||
},
|
||
"points": {
|
||
"type": "object",
|
||
"description": "特殊点样式配置，包含高点、低点、标记点、首点、尾点、负点。",
|
||
"properties": {
|
||
"last_point": {
|
||
"type": "object",
|
||
"description": "尾点配置，最后一个数据点的样式。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "点的颜色。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示该点。"
|
||
}
|
||
}
|
||
},
|
||
"negative_point": {
|
||
"type": "object",
|
||
"description": "负点配置，负数点的样式。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "点的颜色。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示该点。"
|
||
}
|
||
}
|
||
},
|
||
"markers_point": {
|
||
"type": "object",
|
||
"description": "标记点配置，所有标记点的样式。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "点的颜色。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示该点。"
|
||
}
|
||
}
|
||
},
|
||
"first_point": {
|
||
"type": "object",
|
||
"description": "首点配置，第一个数据点的样式。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "点的颜色。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示该点。"
|
||
}
|
||
}
|
||
},
|
||
"high_point": {
|
||
"type": "object",
|
||
"description": "高点配置，最高点的样式。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "点的颜色。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示该点。"
|
||
}
|
||
}
|
||
},
|
||
"low_point": {
|
||
"type": "object",
|
||
"description": "低点配置，最低点的样式。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "点的颜色。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示该点。"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"line_width": {
|
||
"type": "number",
|
||
"enum": [
|
||
1,
|
||
2,
|
||
3,
|
||
4
|
||
],
|
||
"description": "折线图线宽，可选值：1=1px，2=2px，3=3px，4=4px。"
|
||
},
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"line",
|
||
"column",
|
||
"win_loss"
|
||
],
|
||
"description": "迷你图类型，可选值：line=折线图，column=柱形图，win_loss=盈亏图。"
|
||
},
|
||
"axis": {
|
||
"type": "object",
|
||
"description": "坐标轴配置，包含坐标轴颜色、是否翻转、是否显示坐标轴。",
|
||
"properties": {
|
||
"color": {
|
||
"type": "string",
|
||
"description": "坐标轴颜色。"
|
||
},
|
||
"reverse": {
|
||
"type": "boolean",
|
||
"description": "是否翻转坐标轴方向。"
|
||
},
|
||
"visible": {
|
||
"type": "boolean",
|
||
"description": "是否显示坐标轴。"
|
||
}
|
||
}
|
||
},
|
||
"show_gradient": {
|
||
"type": "boolean",
|
||
"description": "是否显示渐变效果。"
|
||
},
|
||
"show_radius": {
|
||
"type": "boolean",
|
||
"description": "是否显示圆角，仅对柱形图和盈亏图生效。"
|
||
},
|
||
"extremum_max": {
|
||
"type": "object",
|
||
"description": "最大极值配置，包含极值类型、极值。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"individual",
|
||
"group",
|
||
"custom"
|
||
],
|
||
"description": "极值类型，可选值：individual=单个迷你图极值，group=同组内极值，custom=自定义。"
|
||
},
|
||
"value": {
|
||
"type": "number",
|
||
"description": "当 type='custom' 时生效的具体数值。"
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
},
|
||
"extremum_min": {
|
||
"type": "object",
|
||
"description": "最小极值配置，包含极值类型、极值。",
|
||
"properties": {
|
||
"type": {
|
||
"type": "string",
|
||
"enum": [
|
||
"individual",
|
||
"group",
|
||
"custom"
|
||
],
|
||
"description": "极值类型：individual=单个迷你图极值，group=同组内极值，custom=自定义。"
|
||
},
|
||
"value": {
|
||
"type": "number",
|
||
"description": "当 type='custom' 时生效的具体数值。"
|
||
}
|
||
},
|
||
"required": [
|
||
"type"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"sparklines": {
|
||
"type": "array",
|
||
"description": "迷你图项列表。create 时为待创建项（每项需 position + source/source_range）；update 时为待变更/新增项（每项需 sparkline_id；upsert=true 新增时需 position + source）；delete 时为待删除项（每项需 sparkline_id）。",
|
||
"items": {
|
||
"type": "object",
|
||
"description": "单个迷你图项。",
|
||
"properties": {
|
||
"sparkline_id": {
|
||
"type": "string",
|
||
"description": "迷你图 reference_id。create 时可选（不传系统生成）；update / delete 时必填。"
|
||
},
|
||
"position": {
|
||
"type": "object",
|
||
"description": "迷你图位置。create / update 时必填；delete 时省略。",
|
||
"properties": {
|
||
"row": {
|
||
"type": "number",
|
||
"minimum": 0,
|
||
"description": "行索引（0-based）"
|
||
},
|
||
"col": {
|
||
"type": "string",
|
||
"description": "列索引，例如 \"A\"、\"B\""
|
||
}
|
||
},
|
||
"required": [
|
||
"row",
|
||
"col"
|
||
]
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"description": "A1 范围字符串，表示数据来源，例如 \"Sheet1!A2:A10\"。create 必填（与 source_range 二选一）；update 仅在改源时传；delete 时省略。"
|
||
},
|
||
"source_range": {
|
||
"type": "object",
|
||
"description": "结构化数据源范围（与 source 等价）。",
|
||
"properties": {
|
||
"range": {
|
||
"type": "string",
|
||
"description": "数据源的 A1 引用区域"
|
||
}
|
||
},
|
||
"required": [
|
||
"range"
|
||
]
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"+table-put": {
|
||
"sheets": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"description": "一个或多个子表的 typed 数据，每个数组元素写入一张子表；支持多 DataFrame → 多子表一次写入。每个数组项的形状对齐 pandas `df.to_json(orient=\"split\")`：列名走 `columns`、二维取值走 `data`、每列的 pandas dtype 走 `dtypes`、可选的展示格式走 `formats`，并显式带上目标子表名 `name`。pandas 来源直接用 `scripts/sheets_df.py` 的 `df_to_sheet(df, name)` 生成一项，再把 list 包到 `{\"sheets\":[...]}`。",
|
||
"items": {
|
||
"type": "object",
|
||
"required": [
|
||
"name",
|
||
"columns",
|
||
"data"
|
||
],
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "目标子表名。按名匹配已有子表；不存在则新建该子表。同一次调用内子表名不可重复。"
|
||
},
|
||
"start_cell": {
|
||
"type": "string",
|
||
"default": "A1",
|
||
"description": "写入起点单元格（A1 记法，如 \"B2\"），默认 \"A1\"。mode=append 时忽略其行号、仅沿用其列。"
|
||
},
|
||
"mode": {
|
||
"type": "string",
|
||
"enum": [
|
||
"overwrite",
|
||
"append"
|
||
],
|
||
"default": "overwrite",
|
||
"description": "overwrite（默认）：从 start_cell 起写「表头 + 数据」块；append：把数据追加到子表已有数据下方（默认不重复表头）。"
|
||
},
|
||
"header": {
|
||
"type": "boolean",
|
||
"description": "是否写一行列名表头。省略时按 mode 取默认:overwrite→true、append→false（避免在已有表头下重复）；显式给值可覆盖。"
|
||
},
|
||
"allow_overwrite": {
|
||
"type": "boolean",
|
||
"default": true,
|
||
"description": "为 false 时，若写入会落在非空单元格则拒写以保护原数据（返回 partial_success）。默认 true。"
|
||
},
|
||
"columns": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"description": "列名字符串数组，顺序与 `data` 中每行取值一一对应。同一子表内列名不可重复。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"data": {
|
||
"type": "array",
|
||
"description": "数据行；每行是一个数组，长度必须等于 `columns` 数。元素按 `dtypes` 推得的列类型取值（date 列写 ISO yyyy-mm-dd 字符串、number 列写数值、bool 列写布尔、其余写文本），null 表示空单元格。",
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": [
|
||
"string",
|
||
"number",
|
||
"boolean",
|
||
"null"
|
||
],
|
||
"description": "单元格值：date→ISO yyyy-mm-dd 字符串；number→数值（json.Number 精度保留）；bool→布尔；string→文本；null→空单元格。"
|
||
}
|
||
}
|
||
},
|
||
"dtypes": {
|
||
"type": "object",
|
||
"description": "可选。列名 → pandas dtype 字符串的映射；缺失项默认按 object（string + 文本格式 `@`）处理，所以省略整段时整张表按文本写入（导入 CSV-shaped 数据的最简形态）。dtype 解析规则：`int*` / `uint*` / `Int*` / `UInt*` / `float*` / `Float*` / `complex*` → number（精度保留），`bool` / `boolean` → bool，`datetime64[ns]` / 含时区的 `datetime64[ns, UTC]` 等 → date（默认 `yyyy-mm-dd` 格式），`object` / `string` / `category` / 未识别 → string + 文本格式 `@`（数字样字符串如「00123」不会塌缩成数字）。",
|
||
"additionalProperties": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"formats": {
|
||
"type": "object",
|
||
"description": "可选。列名 → Excel number_format 字符串的映射，覆盖 dtype 自带的默认格式（金额 `#,##0.00`、百分比 `0.0%`、自定义日期 `yyyy-mm` 等）。percent 列的数值尺度由调用方负责（0.0469 配 `0.00%` 显示 4.69%）。",
|
||
"additionalProperties": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"styles": {
|
||
"items": {
|
||
"properties": {
|
||
"cell_merges": {
|
||
"description": "单元格合并操作数组；range 使用 A1 单元格范围，merge_type 默认 all。",
|
||
"items": {
|
||
"properties": {
|
||
"merge_type": {
|
||
"enum": [
|
||
"all",
|
||
"rows",
|
||
"columns"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"range": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": [
|
||
"range"
|
||
],
|
||
"type": "object"
|
||
},
|
||
"type": "array"
|
||
},
|
||
"cell_styles": {
|
||
"description": "单元格样式操作数组；每项用 A1 单元格 range 指定范围，字段名与 +cells-set-style 对齐。",
|
||
"items": {
|
||
"properties": {
|
||
"background_color": {
|
||
"type": "string"
|
||
},
|
||
"border_styles": {
|
||
"type": "object",
|
||
"description": "边框配置，结构同 +cells-set-style --border-styles。",
|
||
"properties": {
|
||
"bottom": {
|
||
"properties": {
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
},
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"type": "object"
|
||
},
|
||
"left": {
|
||
"properties": {
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
},
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"type": "object"
|
||
},
|
||
"right": {
|
||
"properties": {
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
},
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"type": "object"
|
||
},
|
||
"top": {
|
||
"properties": {
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
},
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"type": "object"
|
||
}
|
||
}
|
||
},
|
||
"font_color": {
|
||
"type": "string"
|
||
},
|
||
"font_line": {
|
||
"enum": [
|
||
"none",
|
||
"underline",
|
||
"line-through"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"font_size": {
|
||
"type": "number"
|
||
},
|
||
"font_style": {
|
||
"enum": [
|
||
"normal",
|
||
"italic"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"font_weight": {
|
||
"enum": [
|
||
"normal",
|
||
"bold"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"horizontal_alignment": {
|
||
"enum": [
|
||
"left",
|
||
"center",
|
||
"right"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"number_format": {
|
||
"type": "string"
|
||
},
|
||
"range": {
|
||
"description": "A1 单元格范围，必须落在该子表本次写入区域内；例如 A1:B1、B2。",
|
||
"type": "string"
|
||
},
|
||
"vertical_alignment": {
|
||
"enum": [
|
||
"top",
|
||
"middle",
|
||
"bottom"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"word_wrap": {
|
||
"enum": [
|
||
"overflow",
|
||
"auto-wrap",
|
||
"word-clip"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": [
|
||
"range"
|
||
],
|
||
"type": "object"
|
||
},
|
||
"type": "array"
|
||
},
|
||
"col_sizes": {
|
||
"description": "列宽操作数组；range 使用列范围如 A:C，type 为 pixel/standard，pixel 需要 size。",
|
||
"items": {
|
||
"properties": {
|
||
"range": {
|
||
"type": "string"
|
||
},
|
||
"size": {
|
||
"type": "number"
|
||
},
|
||
"type": {
|
||
"enum": [
|
||
"pixel",
|
||
"standard"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": [
|
||
"range",
|
||
"type"
|
||
],
|
||
"type": "object"
|
||
},
|
||
"type": "array"
|
||
},
|
||
"name": {
|
||
"description": "子表名。--sheets 模式下必须与同位置 --sheets.sheets[].name 一致；--values 模式下建议写 Sheet1（其 name 会被忽略）。",
|
||
"type": "string"
|
||
},
|
||
"row_sizes": {
|
||
"description": "行高操作数组；range 使用行范围如 1:3，type 为 pixel/standard/auto，pixel 需要 size。",
|
||
"items": {
|
||
"properties": {
|
||
"range": {
|
||
"type": "string"
|
||
},
|
||
"size": {
|
||
"type": "number"
|
||
},
|
||
"type": {
|
||
"enum": [
|
||
"pixel",
|
||
"standard",
|
||
"auto"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": [
|
||
"range",
|
||
"type"
|
||
],
|
||
"type": "object"
|
||
},
|
||
"type": "array"
|
||
}
|
||
},
|
||
"required": [
|
||
"name"
|
||
],
|
||
"type": "object"
|
||
},
|
||
"type": "array"
|
||
}
|
||
},
|
||
"+workbook-create": {
|
||
"sheets": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"description": "一个或多个子表的 typed 数据，每个数组元素写入一张子表；支持多 DataFrame → 多子表一次写入。每个数组项的形状对齐 pandas `df.to_json(orient=\"split\")`：列名走 `columns`、二维取值走 `data`、每列的 pandas dtype 走 `dtypes`、可选的展示格式走 `formats`，并显式带上目标子表名 `name`。pandas 来源直接用 `scripts/sheets_df.py` 的 `df_to_sheet(df, name)` 生成一项，再把 list 包到 `{\"sheets\":[...]}`。",
|
||
"items": {
|
||
"type": "object",
|
||
"required": [
|
||
"name",
|
||
"columns",
|
||
"data"
|
||
],
|
||
"properties": {
|
||
"name": {
|
||
"type": "string",
|
||
"description": "目标子表名。按名匹配已有子表；不存在则新建该子表。同一次调用内子表名不可重复。"
|
||
},
|
||
"start_cell": {
|
||
"type": "string",
|
||
"default": "A1",
|
||
"description": "写入起点单元格（A1 记法，如 \"B2\"），默认 \"A1\"。mode=append 时忽略其行号、仅沿用其列。"
|
||
},
|
||
"mode": {
|
||
"type": "string",
|
||
"enum": [
|
||
"overwrite",
|
||
"append"
|
||
],
|
||
"default": "overwrite",
|
||
"description": "overwrite（默认）：从 start_cell 起写「表头 + 数据」块；append：把数据追加到子表已有数据下方（默认不重复表头）。"
|
||
},
|
||
"header": {
|
||
"type": "boolean",
|
||
"description": "是否写一行列名表头。省略时按 mode 取默认:overwrite→true、append→false（避免在已有表头下重复）；显式给值可覆盖。"
|
||
},
|
||
"allow_overwrite": {
|
||
"type": "boolean",
|
||
"default": true,
|
||
"description": "为 false 时，若写入会落在非空单元格则拒写以保护原数据（返回 partial_success）。默认 true。"
|
||
},
|
||
"columns": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"description": "列名字符串数组，顺序与 `data` 中每行取值一一对应。同一子表内列名不可重复。",
|
||
"items": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"data": {
|
||
"type": "array",
|
||
"description": "数据行；每行是一个数组，长度必须等于 `columns` 数。元素按 `dtypes` 推得的列类型取值（date 列写 ISO yyyy-mm-dd 字符串、number 列写数值、bool 列写布尔、其余写文本），null 表示空单元格。",
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": [
|
||
"string",
|
||
"number",
|
||
"boolean",
|
||
"null"
|
||
],
|
||
"description": "单元格值：date→ISO yyyy-mm-dd 字符串；number→数值（json.Number 精度保留）；bool→布尔；string→文本；null→空单元格。"
|
||
}
|
||
}
|
||
},
|
||
"dtypes": {
|
||
"type": "object",
|
||
"description": "可选。列名 → pandas dtype 字符串的映射；缺失项默认按 object（string + 文本格式 `@`）处理，所以省略整段时整张表按文本写入（导入 CSV-shaped 数据的最简形态）。dtype 解析规则：`int*` / `uint*` / `Int*` / `UInt*` / `float*` / `Float*` / `complex*` → number（精度保留），`bool` / `boolean` → bool，`datetime64[ns]` / 含时区的 `datetime64[ns, UTC]` 等 → date（默认 `yyyy-mm-dd` 格式），`object` / `string` / `category` / 未识别 → string + 文本格式 `@`（数字样字符串如「00123」不会塌缩成数字）。",
|
||
"additionalProperties": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"formats": {
|
||
"type": "object",
|
||
"description": "可选。列名 → Excel number_format 字符串的映射，覆盖 dtype 自带的默认格式（金额 `#,##0.00`、百分比 `0.0%`、自定义日期 `yyyy-mm` 等）。percent 列的数值尺度由调用方负责（0.0469 配 `0.00%` 显示 4.69%）。",
|
||
"additionalProperties": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"styles": {
|
||
"items": {
|
||
"properties": {
|
||
"cell_merges": {
|
||
"description": "单元格合并操作数组；range 使用 A1 单元格范围，merge_type 默认 all。",
|
||
"items": {
|
||
"properties": {
|
||
"merge_type": {
|
||
"enum": [
|
||
"all",
|
||
"rows",
|
||
"columns"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"range": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": [
|
||
"range"
|
||
],
|
||
"type": "object"
|
||
},
|
||
"type": "array"
|
||
},
|
||
"cell_styles": {
|
||
"description": "单元格样式操作数组；每项用 A1 单元格 range 指定范围，字段名与 +cells-set-style 对齐。",
|
||
"items": {
|
||
"properties": {
|
||
"background_color": {
|
||
"type": "string"
|
||
},
|
||
"border_styles": {
|
||
"type": "object",
|
||
"description": "边框配置，结构同 +cells-set-style --border-styles。",
|
||
"properties": {
|
||
"bottom": {
|
||
"properties": {
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
},
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"type": "object"
|
||
},
|
||
"left": {
|
||
"properties": {
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
},
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"type": "object"
|
||
},
|
||
"right": {
|
||
"properties": {
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
},
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"type": "object"
|
||
},
|
||
"top": {
|
||
"properties": {
|
||
"color": {
|
||
"description": "边框颜色（十六进制，例如 \"#000000\"）",
|
||
"type": "string"
|
||
},
|
||
"style": {
|
||
"description": "边框线型；传 \"none\" 表示清除该方向边框（无边框线）",
|
||
"enum": [
|
||
"solid",
|
||
"dashed",
|
||
"dotted",
|
||
"double",
|
||
"none"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"weight": {
|
||
"description": "边框粗细/线宽",
|
||
"enum": [
|
||
"thin",
|
||
"medium",
|
||
"thick"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"type": "object"
|
||
}
|
||
}
|
||
},
|
||
"font_color": {
|
||
"type": "string"
|
||
},
|
||
"font_line": {
|
||
"enum": [
|
||
"none",
|
||
"underline",
|
||
"line-through"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"font_size": {
|
||
"type": "number"
|
||
},
|
||
"font_style": {
|
||
"enum": [
|
||
"normal",
|
||
"italic"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"font_weight": {
|
||
"enum": [
|
||
"normal",
|
||
"bold"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"horizontal_alignment": {
|
||
"enum": [
|
||
"left",
|
||
"center",
|
||
"right"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"number_format": {
|
||
"type": "string"
|
||
},
|
||
"range": {
|
||
"description": "A1 单元格范围，必须落在该子表本次写入区域内；例如 A1:B1、B2。",
|
||
"type": "string"
|
||
},
|
||
"vertical_alignment": {
|
||
"enum": [
|
||
"top",
|
||
"middle",
|
||
"bottom"
|
||
],
|
||
"type": "string"
|
||
},
|
||
"word_wrap": {
|
||
"enum": [
|
||
"overflow",
|
||
"auto-wrap",
|
||
"word-clip"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": [
|
||
"range"
|
||
],
|
||
"type": "object"
|
||
},
|
||
"type": "array"
|
||
},
|
||
"col_sizes": {
|
||
"description": "列宽操作数组；range 使用列范围如 A:C，type 为 pixel/standard，pixel 需要 size。",
|
||
"items": {
|
||
"properties": {
|
||
"range": {
|
||
"type": "string"
|
||
},
|
||
"size": {
|
||
"type": "number"
|
||
},
|
||
"type": {
|
||
"enum": [
|
||
"pixel",
|
||
"standard"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": [
|
||
"range",
|
||
"type"
|
||
],
|
||
"type": "object"
|
||
},
|
||
"type": "array"
|
||
},
|
||
"name": {
|
||
"description": "子表名。--sheets 模式下必须与同位置 --sheets.sheets[].name 一致；--values 模式下建议写 Sheet1（其 name 会被忽略）。",
|
||
"type": "string"
|
||
},
|
||
"row_sizes": {
|
||
"description": "行高操作数组；range 使用行范围如 1:3，type 为 pixel/standard/auto，pixel 需要 size。",
|
||
"items": {
|
||
"properties": {
|
||
"range": {
|
||
"type": "string"
|
||
},
|
||
"size": {
|
||
"type": "number"
|
||
},
|
||
"type": {
|
||
"enum": [
|
||
"pixel",
|
||
"standard",
|
||
"auto"
|
||
],
|
||
"type": "string"
|
||
}
|
||
},
|
||
"required": [
|
||
"range",
|
||
"type"
|
||
],
|
||
"type": "object"
|
||
},
|
||
"type": "array"
|
||
}
|
||
},
|
||
"required": [
|
||
"name"
|
||
],
|
||
"type": "object"
|
||
},
|
||
"type": "array"
|
||
}
|
||
}
|
||
}
|
||
}
|