From a0e56715c751e9fba7bd257764fbcdcee474c094 Mon Sep 17 00:00:00 2001
From: zhengzhijiej-tech <zhengzhijie.j@bytedance.com>
Date: Mon, 6 Jul 2026 11:44:49 +0800
Subject: [PATCH] docs(sheets): sync chart schema and labels guidance (#1716)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* chore(sheets): update chart flag schema

* docs(sheets): clarify chart labels field is presence-toggle, not value-toggle

Synced from sheet-skill-spec. Chart labels (plotArea.plot.labels and per-series
labels) are toggled by object existence — passing labels at all turns data
labels on, even when value/category/series/percentage are all false (server
falls back to showing value). Models repeatedly try `{ value: false, category:
false, series: false }` to disable, which silently shows the value fallback.
The reference doc now spells out both directions: pass labels to show, omit
the whole labels field to hide.

Also picks up earlier spec-side drift not yet propagated:
- pivot-table reference: +pivot-list info return + overlap validation
- flag-defs: cell-matrix fan-out cap default 200000 -> 50000 (#1578)
---
 shortcuts/sheets/data/flag-schemas.json       | 1448 ++++++++++++++++-
 .../references/lark-sheets-chart.md           |    4 +-
 2 files changed, 1447 insertions(+), 5 deletions(-)

diff --git a/shortcuts/sheets/data/flag-schemas.json b/shortcuts/sheets/data/flag-schemas.json
index bef5db5bf..c2323b388 100644
--- a/shortcuts/sheets/data/flag-schemas.json
+++ b/shortcuts/sheets/data/flag-schemas.json
@@ -1175,6 +1175,150 @@
                             "type": "number",
                             "description": "数据点大小"
                           },
+                          "fillGradient": {
+                            "type": "object",
+                            "description": "数据点填充渐变配置",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "linear",
+                                  "radial"
+                                ],
+                                "description": "渐变类型"
+                              },
+                              "x0": {
+                                "type": "number",
+                                "description": "起点 x，0-1 归一化坐标"
+                              },
+                              "y0": {
+                                "type": "number",
+                                "description": "起点 y，0-1 归一化坐标"
+                              },
+                              "x1": {
+                                "type": "number",
+                                "description": "终点 x，0-1 归一化坐标"
+                              },
+                              "y1": {
+                                "type": "number",
+                                "description": "终点 y，0-1 归一化坐标"
+                              },
+                              "r0": {
+                                "type": "number",
+                                "description": "径向渐变起点半径"
+                              },
+                              "r1": {
+                                "type": "number",
+                                "description": "径向渐变终点半径"
+                              },
+                              "gradientMethod": {
+                                "type": "string",
+                                "description": "渐变插值方法"
+                              },
+                              "stops": {
+                                "type": "array",
+                                "description": "渐变色标数组，至少 2 个",
+                                "minItems": 2,
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "offset": {
+                                      "type": "number",
+                                      "description": "色标位置 0-1"
+                                    },
+                                    "color": {
+                                      "type": "string",
+                                      "description": "色标颜色"
+                                    },
+                                    "opacity": {
+                                      "type": "number",
+                                      "description": "色标透明度 0-1"
+                                    }
+                                  },
+                                  "required": [
+                                    "offset",
+                                    "color"
+                                  ]
+                                }
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "stops"
+                            ]
+                          },
+                          "strokeGradient": {
+                            "type": "object",
+                            "description": "数据点描边渐变配置",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "linear",
+                                  "radial"
+                                ],
+                                "description": "渐变类型"
+                              },
+                              "x0": {
+                                "type": "number",
+                                "description": "起点 x，0-1 归一化坐标"
+                              },
+                              "y0": {
+                                "type": "number",
+                                "description": "起点 y，0-1 归一化坐标"
+                              },
+                              "x1": {
+                                "type": "number",
+                                "description": "终点 x，0-1 归一化坐标"
+                              },
+                              "y1": {
+                                "type": "number",
+                                "description": "终点 y，0-1 归一化坐标"
+                              },
+                              "r0": {
+                                "type": "number",
+                                "description": "径向渐变起点半径"
+                              },
+                              "r1": {
+                                "type": "number",
+                                "description": "径向渐变终点半径"
+                              },
+                              "gradientMethod": {
+                                "type": "string",
+                                "description": "渐变插值方法"
+                              },
+                              "stops": {
+                                "type": "array",
+                                "description": "渐变色标数组，至少 2 个",
+                                "minItems": 2,
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "offset": {
+                                      "type": "number",
+                                      "description": "色标位置 0-1"
+                                    },
+                                    "color": {
+                                      "type": "string",
+                                      "description": "色标颜色"
+                                    },
+                                    "opacity": {
+                                      "type": "number",
+                                      "description": "色标透明度 0-1"
+                                    }
+                                  },
+                                  "required": [
+                                    "offset",
+                                    "color"
+                                  ]
+                                }
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "stops"
+                            ]
+                          },
                           "point": {
                             "type": "array",
                             "description": "单个数据点配置数组",
@@ -1196,6 +1340,78 @@
                                 "size": {
                                   "type": "number",
                                   "description": "大小"
+                                },
+                                "fillGradient": {
+                                  "type": "object",
+                                  "description": "单个数据点填充渐变配置",
+                                  "properties": {
+                                    "type": {
+                                      "type": "string",
+                                      "enum": [
+                                        "linear",
+                                        "radial"
+                                      ],
+                                      "description": "渐变类型"
+                                    },
+                                    "x0": {
+                                      "type": "number",
+                                      "description": "起点 x，0-1 归一化坐标"
+                                    },
+                                    "y0": {
+                                      "type": "number",
+                                      "description": "起点 y，0-1 归一化坐标"
+                                    },
+                                    "x1": {
+                                      "type": "number",
+                                      "description": "终点 x，0-1 归一化坐标"
+                                    },
+                                    "y1": {
+                                      "type": "number",
+                                      "description": "终点 y，0-1 归一化坐标"
+                                    },
+                                    "r0": {
+                                      "type": "number",
+                                      "description": "径向渐变起点半径"
+                                    },
+                                    "r1": {
+                                      "type": "number",
+                                      "description": "径向渐变终点半径"
+                                    },
+                                    "gradientMethod": {
+                                      "type": "string",
+                                      "description": "渐变插值方法"
+                                    },
+                                    "stops": {
+                                      "type": "array",
+                                      "description": "渐变色标数组，至少 2 个",
+                                      "minItems": 2,
+                                      "items": {
+                                        "type": "object",
+                                        "properties": {
+                                          "offset": {
+                                            "type": "number",
+                                            "description": "色标位置 0-1"
+                                          },
+                                          "color": {
+                                            "type": "string",
+                                            "description": "色标颜色"
+                                          },
+                                          "opacity": {
+                                            "type": "number",
+                                            "description": "色标透明度 0-1"
+                                          }
+                                        },
+                                        "required": [
+                                          "offset",
+                                          "color"
+                                        ]
+                                      }
+                                    }
+                                  },
+                                  "required": [
+                                    "type",
+                                    "stops"
+                                  ]
                                 }
                               },
                               "required": [
@@ -1234,6 +1450,78 @@
                               "zero",
                               "link"
                             ]
+                          },
+                          "strokeGradient": {
+                            "type": "object",
+                            "description": "线条描边渐变配置",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "linear",
+                                  "radial"
+                                ],
+                                "description": "渐变类型"
+                              },
+                              "x0": {
+                                "type": "number",
+                                "description": "起点 x，0-1 归一化坐标"
+                              },
+                              "y0": {
+                                "type": "number",
+                                "description": "起点 y，0-1 归一化坐标"
+                              },
+                              "x1": {
+                                "type": "number",
+                                "description": "终点 x，0-1 归一化坐标"
+                              },
+                              "y1": {
+                                "type": "number",
+                                "description": "终点 y，0-1 归一化坐标"
+                              },
+                              "r0": {
+                                "type": "number",
+                                "description": "径向渐变起点半径"
+                              },
+                              "r1": {
+                                "type": "number",
+                                "description": "径向渐变终点半径"
+                              },
+                              "gradientMethod": {
+                                "type": "string",
+                                "description": "渐变插值方法"
+                              },
+                              "stops": {
+                                "type": "array",
+                                "description": "渐变色标数组，至少 2 个",
+                                "minItems": 2,
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "offset": {
+                                      "type": "number",
+                                      "description": "色标位置 0-1"
+                                    },
+                                    "color": {
+                                      "type": "string",
+                                      "description": "色标颜色"
+                                    },
+                                    "opacity": {
+                                      "type": "number",
+                                      "description": "色标透明度 0-1"
+                                    }
+                                  },
+                                  "required": [
+                                    "offset",
+                                    "color"
+                                  ]
+                                }
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "stops"
+                            ]
                           }
                         }
                       },
@@ -1244,6 +1532,78 @@
                           "color": {
                             "type": "string",
                             "description": "区域填充颜色"
+                          },
+                          "fillGradient": {
+                            "type": "object",
+                            "description": "区域填充渐变",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "linear",
+                                  "radial"
+                                ],
+                                "description": "渐变类型"
+                              },
+                              "x0": {
+                                "type": "number",
+                                "description": "起点 x，0-1 归一化坐标"
+                              },
+                              "y0": {
+                                "type": "number",
+                                "description": "起点 y，0-1 归一化坐标"
+                              },
+                              "x1": {
+                                "type": "number",
+                                "description": "终点 x，0-1 归一化坐标"
+                              },
+                              "y1": {
+                                "type": "number",
+                                "description": "终点 y，0-1 归一化坐标"
+                              },
+                              "r0": {
+                                "type": "number",
+                                "description": "径向渐变起点半径"
+                              },
+                              "r1": {
+                                "type": "number",
+                                "description": "径向渐变终点半径"
+                              },
+                              "gradientMethod": {
+                                "type": "string",
+                                "description": "渐变插值方法"
+                              },
+                              "stops": {
+                                "type": "array",
+                                "description": "渐变色标数组，至少 2 个",
+                                "minItems": 2,
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "offset": {
+                                      "type": "number",
+                                      "description": "色标位置 0-1"
+                                    },
+                                    "color": {
+                                      "type": "string",
+                                      "description": "色标颜色"
+                                    },
+                                    "opacity": {
+                                      "type": "number",
+                                      "description": "色标透明度 0-1"
+                                    }
+                                  },
+                                  "required": [
+                                    "offset",
+                                    "color"
+                                  ]
+                                }
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "stops"
+                            ]
                           }
                         }
                       },
@@ -1284,6 +1644,150 @@
                             "type": "string",
                             "description": "背景颜色"
                           },
+                          "fillGradient": {
+                            "type": "object",
+                            "description": "柱子填充渐变",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "linear",
+                                  "radial"
+                                ],
+                                "description": "渐变类型"
+                              },
+                              "x0": {
+                                "type": "number",
+                                "description": "起点 x，0-1 归一化坐标"
+                              },
+                              "y0": {
+                                "type": "number",
+                                "description": "起点 y，0-1 归一化坐标"
+                              },
+                              "x1": {
+                                "type": "number",
+                                "description": "终点 x，0-1 归一化坐标"
+                              },
+                              "y1": {
+                                "type": "number",
+                                "description": "终点 y，0-1 归一化坐标"
+                              },
+                              "r0": {
+                                "type": "number",
+                                "description": "径向渐变起点半径"
+                              },
+                              "r1": {
+                                "type": "number",
+                                "description": "径向渐变终点半径"
+                              },
+                              "gradientMethod": {
+                                "type": "string",
+                                "description": "渐变插值方法"
+                              },
+                              "stops": {
+                                "type": "array",
+                                "description": "渐变色标数组，至少 2 个",
+                                "minItems": 2,
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "offset": {
+                                      "type": "number",
+                                      "description": "色标位置 0-1"
+                                    },
+                                    "color": {
+                                      "type": "string",
+                                      "description": "色标颜色"
+                                    },
+                                    "opacity": {
+                                      "type": "number",
+                                      "description": "色标透明度 0-1"
+                                    }
+                                  },
+                                  "required": [
+                                    "offset",
+                                    "color"
+                                  ]
+                                }
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "stops"
+                            ]
+                          },
+                          "strokeGradient": {
+                            "type": "object",
+                            "description": "柱子描边渐变",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "linear",
+                                  "radial"
+                                ],
+                                "description": "渐变类型"
+                              },
+                              "x0": {
+                                "type": "number",
+                                "description": "起点 x，0-1 归一化坐标"
+                              },
+                              "y0": {
+                                "type": "number",
+                                "description": "起点 y，0-1 归一化坐标"
+                              },
+                              "x1": {
+                                "type": "number",
+                                "description": "终点 x，0-1 归一化坐标"
+                              },
+                              "y1": {
+                                "type": "number",
+                                "description": "终点 y，0-1 归一化坐标"
+                              },
+                              "r0": {
+                                "type": "number",
+                                "description": "径向渐变起点半径"
+                              },
+                              "r1": {
+                                "type": "number",
+                                "description": "径向渐变终点半径"
+                              },
+                              "gradientMethod": {
+                                "type": "string",
+                                "description": "渐变插值方法"
+                              },
+                              "stops": {
+                                "type": "array",
+                                "description": "渐变色标数组，至少 2 个",
+                                "minItems": 2,
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "offset": {
+                                      "type": "number",
+                                      "description": "色标位置 0-1"
+                                    },
+                                    "color": {
+                                      "type": "string",
+                                      "description": "色标颜色"
+                                    },
+                                    "opacity": {
+                                      "type": "number",
+                                      "description": "色标透明度 0-1"
+                                    }
+                                  },
+                                  "required": [
+                                    "offset",
+                                    "color"
+                                  ]
+                                }
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "stops"
+                            ]
+                          },
                           "bar": {
                             "type": "array",
                             "description": "单个柱子配置数组",
@@ -1309,6 +1813,78 @@
                                 "borderStyle": {
                                   "type": "string",
                                   "description": "边框样式"
+                                },
+                                "fillGradient": {
+                                  "type": "object",
+                                  "description": "单个柱子填充渐变",
+                                  "properties": {
+                                    "type": {
+                                      "type": "string",
+                                      "enum": [
+                                        "linear",
+                                        "radial"
+                                      ],
+                                      "description": "渐变类型"
+                                    },
+                                    "x0": {
+                                      "type": "number",
+                                      "description": "起点 x，0-1 归一化坐标"
+                                    },
+                                    "y0": {
+                                      "type": "number",
+                                      "description": "起点 y，0-1 归一化坐标"
+                                    },
+                                    "x1": {
+                                      "type": "number",
+                                      "description": "终点 x，0-1 归一化坐标"
+                                    },
+                                    "y1": {
+                                      "type": "number",
+                                      "description": "终点 y，0-1 归一化坐标"
+                                    },
+                                    "r0": {
+                                      "type": "number",
+                                      "description": "径向渐变起点半径"
+                                    },
+                                    "r1": {
+                                      "type": "number",
+                                      "description": "径向渐变终点半径"
+                                    },
+                                    "gradientMethod": {
+                                      "type": "string",
+                                      "description": "渐变插值方法"
+                                    },
+                                    "stops": {
+                                      "type": "array",
+                                      "description": "渐变色标数组，至少 2 个",
+                                      "minItems": 2,
+                                      "items": {
+                                        "type": "object",
+                                        "properties": {
+                                          "offset": {
+                                            "type": "number",
+                                            "description": "色标位置 0-1"
+                                          },
+                                          "color": {
+                                            "type": "string",
+                                            "description": "色标颜色"
+                                          },
+                                          "opacity": {
+                                            "type": "number",
+                                            "description": "色标透明度 0-1"
+                                          }
+                                        },
+                                        "required": [
+                                          "offset",
+                                          "color"
+                                        ]
+                                      }
+                                    }
+                                  },
+                                  "required": [
+                                    "type",
+                                    "stops"
+                                  ]
                                 }
                               },
                               "required": [
@@ -1320,7 +1896,7 @@
                       },
                       "labels": {
                         "type": "object",
-                        "description": "数据标签配置",
+                        "description": "数据标签配置。labels 对象的存在性即开关：不显示数据标签时省略整个 labels 字段；一旦传入 labels（即便 value/category/series/percentage 全部置为 false），数据标签仍会显示，且默认兜底显示 value。",
                         "properties": {
                           "position": {
                             "type": "string",
@@ -1424,7 +2000,7 @@
                             },
                             "labels": {
                               "type": "object",
-                              "description": "数据标签配置"
+                              "description": "数据标签配置（覆盖单系列，配置项同 plotArea.plot.labels）。不覆盖该系列数据标签时省略整个 labels 字段；一旦传入 labels（即便显示开关全部置为 false），该系列仍会显示数据标签。"
                             },
                             "sectors": {
                               "type": "object",
@@ -1446,6 +2022,78 @@
                                   "type": "number",
                                   "description": "起始角度，0-359"
                                 },
+                                "fillGradient": {
+                                  "type": "object",
+                                  "description": "扇区填充渐变",
+                                  "properties": {
+                                    "type": {
+                                      "type": "string",
+                                      "enum": [
+                                        "linear",
+                                        "radial"
+                                      ],
+                                      "description": "渐变类型"
+                                    },
+                                    "x0": {
+                                      "type": "number",
+                                      "description": "起点 x，0-1 归一化坐标"
+                                    },
+                                    "y0": {
+                                      "type": "number",
+                                      "description": "起点 y，0-1 归一化坐标"
+                                    },
+                                    "x1": {
+                                      "type": "number",
+                                      "description": "终点 x，0-1 归一化坐标"
+                                    },
+                                    "y1": {
+                                      "type": "number",
+                                      "description": "终点 y，0-1 归一化坐标"
+                                    },
+                                    "r0": {
+                                      "type": "number",
+                                      "description": "径向渐变起点半径"
+                                    },
+                                    "r1": {
+                                      "type": "number",
+                                      "description": "径向渐变终点半径"
+                                    },
+                                    "gradientMethod": {
+                                      "type": "string",
+                                      "description": "渐变插值方法"
+                                    },
+                                    "stops": {
+                                      "type": "array",
+                                      "description": "渐变色标数组，至少 2 个",
+                                      "minItems": 2,
+                                      "items": {
+                                        "type": "object",
+                                        "properties": {
+                                          "offset": {
+                                            "type": "number",
+                                            "description": "色标位置 0-1"
+                                          },
+                                          "color": {
+                                            "type": "string",
+                                            "description": "色标颜色"
+                                          },
+                                          "opacity": {
+                                            "type": "number",
+                                            "description": "色标透明度 0-1"
+                                          }
+                                        },
+                                        "required": [
+                                          "offset",
+                                          "color"
+                                        ]
+                                      }
+                                    }
+                                  },
+                                  "required": [
+                                    "type",
+                                    "stops"
+                                  ]
+                                },
                                 "sector": {
                                   "type": "array",
                                   "description": "单个扇区配置数组",
@@ -1467,6 +2115,78 @@
                                       "color": {
                                         "type": "string",
                                         "description": "颜色"
+                                      },
+                                      "fillGradient": {
+                                        "type": "object",
+                                        "description": "单个扇区填充渐变",
+                                        "properties": {
+                                          "type": {
+                                            "type": "string",
+                                            "enum": [
+                                              "linear",
+                                              "radial"
+                                            ],
+                                            "description": "渐变类型"
+                                          },
+                                          "x0": {
+                                            "type": "number",
+                                            "description": "起点 x，0-1 归一化坐标"
+                                          },
+                                          "y0": {
+                                            "type": "number",
+                                            "description": "起点 y，0-1 归一化坐标"
+                                          },
+                                          "x1": {
+                                            "type": "number",
+                                            "description": "终点 x，0-1 归一化坐标"
+                                          },
+                                          "y1": {
+                                            "type": "number",
+                                            "description": "终点 y，0-1 归一化坐标"
+                                          },
+                                          "r0": {
+                                            "type": "number",
+                                            "description": "径向渐变起点半径"
+                                          },
+                                          "r1": {
+                                            "type": "number",
+                                            "description": "径向渐变终点半径"
+                                          },
+                                          "gradientMethod": {
+                                            "type": "string",
+                                            "description": "渐变插值方法"
+                                          },
+                                          "stops": {
+                                            "type": "array",
+                                            "description": "渐变色标数组，至少 2 个",
+                                            "minItems": 2,
+                                            "items": {
+                                              "type": "object",
+                                              "properties": {
+                                                "offset": {
+                                                  "type": "number",
+                                                  "description": "色标位置 0-1"
+                                                },
+                                                "color": {
+                                                  "type": "string",
+                                                  "description": "色标颜色"
+                                                },
+                                                "opacity": {
+                                                  "type": "number",
+                                                  "description": "色标透明度 0-1"
+                                                }
+                                              },
+                                              "required": [
+                                                "offset",
+                                                "color"
+                                              ]
+                                            }
+                                          }
+                                        },
+                                        "required": [
+                                          "type",
+                                          "stops"
+                                        ]
                                       }
                                     },
                                     "required": [
@@ -2211,6 +2931,150 @@
                             "type": "number",
                             "description": "数据点大小"
                           },
+                          "fillGradient": {
+                            "type": "object",
+                            "description": "数据点填充渐变配置",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "linear",
+                                  "radial"
+                                ],
+                                "description": "渐变类型"
+                              },
+                              "x0": {
+                                "type": "number",
+                                "description": "起点 x，0-1 归一化坐标"
+                              },
+                              "y0": {
+                                "type": "number",
+                                "description": "起点 y，0-1 归一化坐标"
+                              },
+                              "x1": {
+                                "type": "number",
+                                "description": "终点 x，0-1 归一化坐标"
+                              },
+                              "y1": {
+                                "type": "number",
+                                "description": "终点 y，0-1 归一化坐标"
+                              },
+                              "r0": {
+                                "type": "number",
+                                "description": "径向渐变起点半径"
+                              },
+                              "r1": {
+                                "type": "number",
+                                "description": "径向渐变终点半径"
+                              },
+                              "gradientMethod": {
+                                "type": "string",
+                                "description": "渐变插值方法"
+                              },
+                              "stops": {
+                                "type": "array",
+                                "description": "渐变色标数组，至少 2 个",
+                                "minItems": 2,
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "offset": {
+                                      "type": "number",
+                                      "description": "色标位置 0-1"
+                                    },
+                                    "color": {
+                                      "type": "string",
+                                      "description": "色标颜色"
+                                    },
+                                    "opacity": {
+                                      "type": "number",
+                                      "description": "色标透明度 0-1"
+                                    }
+                                  },
+                                  "required": [
+                                    "offset",
+                                    "color"
+                                  ]
+                                }
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "stops"
+                            ]
+                          },
+                          "strokeGradient": {
+                            "type": "object",
+                            "description": "数据点描边渐变配置",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "linear",
+                                  "radial"
+                                ],
+                                "description": "渐变类型"
+                              },
+                              "x0": {
+                                "type": "number",
+                                "description": "起点 x，0-1 归一化坐标"
+                              },
+                              "y0": {
+                                "type": "number",
+                                "description": "起点 y，0-1 归一化坐标"
+                              },
+                              "x1": {
+                                "type": "number",
+                                "description": "终点 x，0-1 归一化坐标"
+                              },
+                              "y1": {
+                                "type": "number",
+                                "description": "终点 y，0-1 归一化坐标"
+                              },
+                              "r0": {
+                                "type": "number",
+                                "description": "径向渐变起点半径"
+                              },
+                              "r1": {
+                                "type": "number",
+                                "description": "径向渐变终点半径"
+                              },
+                              "gradientMethod": {
+                                "type": "string",
+                                "description": "渐变插值方法"
+                              },
+                              "stops": {
+                                "type": "array",
+                                "description": "渐变色标数组，至少 2 个",
+                                "minItems": 2,
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "offset": {
+                                      "type": "number",
+                                      "description": "色标位置 0-1"
+                                    },
+                                    "color": {
+                                      "type": "string",
+                                      "description": "色标颜色"
+                                    },
+                                    "opacity": {
+                                      "type": "number",
+                                      "description": "色标透明度 0-1"
+                                    }
+                                  },
+                                  "required": [
+                                    "offset",
+                                    "color"
+                                  ]
+                                }
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "stops"
+                            ]
+                          },
                           "point": {
                             "type": "array",
                             "description": "单个数据点配置数组",
@@ -2232,6 +3096,78 @@
                                 "size": {
                                   "type": "number",
                                   "description": "大小"
+                                },
+                                "fillGradient": {
+                                  "type": "object",
+                                  "description": "单个数据点填充渐变配置",
+                                  "properties": {
+                                    "type": {
+                                      "type": "string",
+                                      "enum": [
+                                        "linear",
+                                        "radial"
+                                      ],
+                                      "description": "渐变类型"
+                                    },
+                                    "x0": {
+                                      "type": "number",
+                                      "description": "起点 x，0-1 归一化坐标"
+                                    },
+                                    "y0": {
+                                      "type": "number",
+                                      "description": "起点 y，0-1 归一化坐标"
+                                    },
+                                    "x1": {
+                                      "type": "number",
+                                      "description": "终点 x，0-1 归一化坐标"
+                                    },
+                                    "y1": {
+                                      "type": "number",
+                                      "description": "终点 y，0-1 归一化坐标"
+                                    },
+                                    "r0": {
+                                      "type": "number",
+                                      "description": "径向渐变起点半径"
+                                    },
+                                    "r1": {
+                                      "type": "number",
+                                      "description": "径向渐变终点半径"
+                                    },
+                                    "gradientMethod": {
+                                      "type": "string",
+                                      "description": "渐变插值方法"
+                                    },
+                                    "stops": {
+                                      "type": "array",
+                                      "description": "渐变色标数组，至少 2 个",
+                                      "minItems": 2,
+                                      "items": {
+                                        "type": "object",
+                                        "properties": {
+                                          "offset": {
+                                            "type": "number",
+                                            "description": "色标位置 0-1"
+                                          },
+                                          "color": {
+                                            "type": "string",
+                                            "description": "色标颜色"
+                                          },
+                                          "opacity": {
+                                            "type": "number",
+                                            "description": "色标透明度 0-1"
+                                          }
+                                        },
+                                        "required": [
+                                          "offset",
+                                          "color"
+                                        ]
+                                      }
+                                    }
+                                  },
+                                  "required": [
+                                    "type",
+                                    "stops"
+                                  ]
                                 }
                               },
                               "required": [
@@ -2270,6 +3206,78 @@
                               "zero",
                               "link"
                             ]
+                          },
+                          "strokeGradient": {
+                            "type": "object",
+                            "description": "线条描边渐变配置",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "linear",
+                                  "radial"
+                                ],
+                                "description": "渐变类型"
+                              },
+                              "x0": {
+                                "type": "number",
+                                "description": "起点 x，0-1 归一化坐标"
+                              },
+                              "y0": {
+                                "type": "number",
+                                "description": "起点 y，0-1 归一化坐标"
+                              },
+                              "x1": {
+                                "type": "number",
+                                "description": "终点 x，0-1 归一化坐标"
+                              },
+                              "y1": {
+                                "type": "number",
+                                "description": "终点 y，0-1 归一化坐标"
+                              },
+                              "r0": {
+                                "type": "number",
+                                "description": "径向渐变起点半径"
+                              },
+                              "r1": {
+                                "type": "number",
+                                "description": "径向渐变终点半径"
+                              },
+                              "gradientMethod": {
+                                "type": "string",
+                                "description": "渐变插值方法"
+                              },
+                              "stops": {
+                                "type": "array",
+                                "description": "渐变色标数组，至少 2 个",
+                                "minItems": 2,
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "offset": {
+                                      "type": "number",
+                                      "description": "色标位置 0-1"
+                                    },
+                                    "color": {
+                                      "type": "string",
+                                      "description": "色标颜色"
+                                    },
+                                    "opacity": {
+                                      "type": "number",
+                                      "description": "色标透明度 0-1"
+                                    }
+                                  },
+                                  "required": [
+                                    "offset",
+                                    "color"
+                                  ]
+                                }
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "stops"
+                            ]
                           }
                         }
                       },
@@ -2280,6 +3288,78 @@
                           "color": {
                             "type": "string",
                             "description": "区域填充颜色"
+                          },
+                          "fillGradient": {
+                            "type": "object",
+                            "description": "区域填充渐变",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "linear",
+                                  "radial"
+                                ],
+                                "description": "渐变类型"
+                              },
+                              "x0": {
+                                "type": "number",
+                                "description": "起点 x，0-1 归一化坐标"
+                              },
+                              "y0": {
+                                "type": "number",
+                                "description": "起点 y，0-1 归一化坐标"
+                              },
+                              "x1": {
+                                "type": "number",
+                                "description": "终点 x，0-1 归一化坐标"
+                              },
+                              "y1": {
+                                "type": "number",
+                                "description": "终点 y，0-1 归一化坐标"
+                              },
+                              "r0": {
+                                "type": "number",
+                                "description": "径向渐变起点半径"
+                              },
+                              "r1": {
+                                "type": "number",
+                                "description": "径向渐变终点半径"
+                              },
+                              "gradientMethod": {
+                                "type": "string",
+                                "description": "渐变插值方法"
+                              },
+                              "stops": {
+                                "type": "array",
+                                "description": "渐变色标数组，至少 2 个",
+                                "minItems": 2,
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "offset": {
+                                      "type": "number",
+                                      "description": "色标位置 0-1"
+                                    },
+                                    "color": {
+                                      "type": "string",
+                                      "description": "色标颜色"
+                                    },
+                                    "opacity": {
+                                      "type": "number",
+                                      "description": "色标透明度 0-1"
+                                    }
+                                  },
+                                  "required": [
+                                    "offset",
+                                    "color"
+                                  ]
+                                }
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "stops"
+                            ]
                           }
                         }
                       },
@@ -2320,6 +3400,150 @@
                             "type": "string",
                             "description": "背景颜色"
                           },
+                          "fillGradient": {
+                            "type": "object",
+                            "description": "柱子填充渐变",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "linear",
+                                  "radial"
+                                ],
+                                "description": "渐变类型"
+                              },
+                              "x0": {
+                                "type": "number",
+                                "description": "起点 x，0-1 归一化坐标"
+                              },
+                              "y0": {
+                                "type": "number",
+                                "description": "起点 y，0-1 归一化坐标"
+                              },
+                              "x1": {
+                                "type": "number",
+                                "description": "终点 x，0-1 归一化坐标"
+                              },
+                              "y1": {
+                                "type": "number",
+                                "description": "终点 y，0-1 归一化坐标"
+                              },
+                              "r0": {
+                                "type": "number",
+                                "description": "径向渐变起点半径"
+                              },
+                              "r1": {
+                                "type": "number",
+                                "description": "径向渐变终点半径"
+                              },
+                              "gradientMethod": {
+                                "type": "string",
+                                "description": "渐变插值方法"
+                              },
+                              "stops": {
+                                "type": "array",
+                                "description": "渐变色标数组，至少 2 个",
+                                "minItems": 2,
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "offset": {
+                                      "type": "number",
+                                      "description": "色标位置 0-1"
+                                    },
+                                    "color": {
+                                      "type": "string",
+                                      "description": "色标颜色"
+                                    },
+                                    "opacity": {
+                                      "type": "number",
+                                      "description": "色标透明度 0-1"
+                                    }
+                                  },
+                                  "required": [
+                                    "offset",
+                                    "color"
+                                  ]
+                                }
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "stops"
+                            ]
+                          },
+                          "strokeGradient": {
+                            "type": "object",
+                            "description": "柱子描边渐变",
+                            "properties": {
+                              "type": {
+                                "type": "string",
+                                "enum": [
+                                  "linear",
+                                  "radial"
+                                ],
+                                "description": "渐变类型"
+                              },
+                              "x0": {
+                                "type": "number",
+                                "description": "起点 x，0-1 归一化坐标"
+                              },
+                              "y0": {
+                                "type": "number",
+                                "description": "起点 y，0-1 归一化坐标"
+                              },
+                              "x1": {
+                                "type": "number",
+                                "description": "终点 x，0-1 归一化坐标"
+                              },
+                              "y1": {
+                                "type": "number",
+                                "description": "终点 y，0-1 归一化坐标"
+                              },
+                              "r0": {
+                                "type": "number",
+                                "description": "径向渐变起点半径"
+                              },
+                              "r1": {
+                                "type": "number",
+                                "description": "径向渐变终点半径"
+                              },
+                              "gradientMethod": {
+                                "type": "string",
+                                "description": "渐变插值方法"
+                              },
+                              "stops": {
+                                "type": "array",
+                                "description": "渐变色标数组，至少 2 个",
+                                "minItems": 2,
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "offset": {
+                                      "type": "number",
+                                      "description": "色标位置 0-1"
+                                    },
+                                    "color": {
+                                      "type": "string",
+                                      "description": "色标颜色"
+                                    },
+                                    "opacity": {
+                                      "type": "number",
+                                      "description": "色标透明度 0-1"
+                                    }
+                                  },
+                                  "required": [
+                                    "offset",
+                                    "color"
+                                  ]
+                                }
+                              }
+                            },
+                            "required": [
+                              "type",
+                              "stops"
+                            ]
+                          },
                           "bar": {
                             "type": "array",
                             "description": "单个柱子配置数组",
@@ -2345,6 +3569,78 @@
                                 "borderStyle": {
                                   "type": "string",
                                   "description": "边框样式"
+                                },
+                                "fillGradient": {
+                                  "type": "object",
+                                  "description": "单个柱子填充渐变",
+                                  "properties": {
+                                    "type": {
+                                      "type": "string",
+                                      "enum": [
+                                        "linear",
+                                        "radial"
+                                      ],
+                                      "description": "渐变类型"
+                                    },
+                                    "x0": {
+                                      "type": "number",
+                                      "description": "起点 x，0-1 归一化坐标"
+                                    },
+                                    "y0": {
+                                      "type": "number",
+                                      "description": "起点 y，0-1 归一化坐标"
+                                    },
+                                    "x1": {
+                                      "type": "number",
+                                      "description": "终点 x，0-1 归一化坐标"
+                                    },
+                                    "y1": {
+                                      "type": "number",
+                                      "description": "终点 y，0-1 归一化坐标"
+                                    },
+                                    "r0": {
+                                      "type": "number",
+                                      "description": "径向渐变起点半径"
+                                    },
+                                    "r1": {
+                                      "type": "number",
+                                      "description": "径向渐变终点半径"
+                                    },
+                                    "gradientMethod": {
+                                      "type": "string",
+                                      "description": "渐变插值方法"
+                                    },
+                                    "stops": {
+                                      "type": "array",
+                                      "description": "渐变色标数组，至少 2 个",
+                                      "minItems": 2,
+                                      "items": {
+                                        "type": "object",
+                                        "properties": {
+                                          "offset": {
+                                            "type": "number",
+                                            "description": "色标位置 0-1"
+                                          },
+                                          "color": {
+                                            "type": "string",
+                                            "description": "色标颜色"
+                                          },
+                                          "opacity": {
+                                            "type": "number",
+                                            "description": "色标透明度 0-1"
+                                          }
+                                        },
+                                        "required": [
+                                          "offset",
+                                          "color"
+                                        ]
+                                      }
+                                    }
+                                  },
+                                  "required": [
+                                    "type",
+                                    "stops"
+                                  ]
                                 }
                               },
                               "required": [
@@ -2356,7 +3652,7 @@
                       },
                       "labels": {
                         "type": "object",
-                        "description": "数据标签配置",
+                        "description": "数据标签配置。labels 对象的存在性即开关：不显示数据标签时省略整个 labels 字段；一旦传入 labels（即便 value/category/series/percentage 全部置为 false），数据标签仍会显示，且默认兜底显示 value。",
                         "properties": {
                           "position": {
                             "type": "string",
@@ -2460,7 +3756,7 @@
                             },
                             "labels": {
                               "type": "object",
-                              "description": "数据标签配置"
+                              "description": "数据标签配置（覆盖单系列，配置项同 plotArea.plot.labels）。不覆盖该系列数据标签时省略整个 labels 字段；一旦传入 labels（即便显示开关全部置为 false），该系列仍会显示数据标签。"
                             },
                             "sectors": {
                               "type": "object",
@@ -2482,6 +3778,78 @@
                                   "type": "number",
                                   "description": "起始角度，0-359"
                                 },
+                                "fillGradient": {
+                                  "type": "object",
+                                  "description": "扇区填充渐变",
+                                  "properties": {
+                                    "type": {
+                                      "type": "string",
+                                      "enum": [
+                                        "linear",
+                                        "radial"
+                                      ],
+                                      "description": "渐变类型"
+                                    },
+                                    "x0": {
+                                      "type": "number",
+                                      "description": "起点 x，0-1 归一化坐标"
+                                    },
+                                    "y0": {
+                                      "type": "number",
+                                      "description": "起点 y，0-1 归一化坐标"
+                                    },
+                                    "x1": {
+                                      "type": "number",
+                                      "description": "终点 x，0-1 归一化坐标"
+                                    },
+                                    "y1": {
+                                      "type": "number",
+                                      "description": "终点 y，0-1 归一化坐标"
+                                    },
+                                    "r0": {
+                                      "type": "number",
+                                      "description": "径向渐变起点半径"
+                                    },
+                                    "r1": {
+                                      "type": "number",
+                                      "description": "径向渐变终点半径"
+                                    },
+                                    "gradientMethod": {
+                                      "type": "string",
+                                      "description": "渐变插值方法"
+                                    },
+                                    "stops": {
+                                      "type": "array",
+                                      "description": "渐变色标数组，至少 2 个",
+                                      "minItems": 2,
+                                      "items": {
+                                        "type": "object",
+                                        "properties": {
+                                          "offset": {
+                                            "type": "number",
+                                            "description": "色标位置 0-1"
+                                          },
+                                          "color": {
+                                            "type": "string",
+                                            "description": "色标颜色"
+                                          },
+                                          "opacity": {
+                                            "type": "number",
+                                            "description": "色标透明度 0-1"
+                                          }
+                                        },
+                                        "required": [
+                                          "offset",
+                                          "color"
+                                        ]
+                                      }
+                                    }
+                                  },
+                                  "required": [
+                                    "type",
+                                    "stops"
+                                  ]
+                                },
                                 "sector": {
                                   "type": "array",
                                   "description": "单个扇区配置数组",
@@ -2503,6 +3871,78 @@
                                       "color": {
                                         "type": "string",
                                         "description": "颜色"
+                                      },
+                                      "fillGradient": {
+                                        "type": "object",
+                                        "description": "单个扇区填充渐变",
+                                        "properties": {
+                                          "type": {
+                                            "type": "string",
+                                            "enum": [
+                                              "linear",
+                                              "radial"
+                                            ],
+                                            "description": "渐变类型"
+                                          },
+                                          "x0": {
+                                            "type": "number",
+                                            "description": "起点 x，0-1 归一化坐标"
+                                          },
+                                          "y0": {
+                                            "type": "number",
+                                            "description": "起点 y，0-1 归一化坐标"
+                                          },
+                                          "x1": {
+                                            "type": "number",
+                                            "description": "终点 x，0-1 归一化坐标"
+                                          },
+                                          "y1": {
+                                            "type": "number",
+                                            "description": "终点 y，0-1 归一化坐标"
+                                          },
+                                          "r0": {
+                                            "type": "number",
+                                            "description": "径向渐变起点半径"
+                                          },
+                                          "r1": {
+                                            "type": "number",
+                                            "description": "径向渐变终点半径"
+                                          },
+                                          "gradientMethod": {
+                                            "type": "string",
+                                            "description": "渐变插值方法"
+                                          },
+                                          "stops": {
+                                            "type": "array",
+                                            "description": "渐变色标数组，至少 2 个",
+                                            "minItems": 2,
+                                            "items": {
+                                              "type": "object",
+                                              "properties": {
+                                                "offset": {
+                                                  "type": "number",
+                                                  "description": "色标位置 0-1"
+                                                },
+                                                "color": {
+                                                  "type": "string",
+                                                  "description": "色标颜色"
+                                                },
+                                                "opacity": {
+                                                  "type": "number",
+                                                  "description": "色标透明度 0-1"
+                                                }
+                                              },
+                                              "required": [
+                                                "offset",
+                                                "color"
+                                              ]
+                                            }
+                                          }
+                                        },
+                                        "required": [
+                                          "type",
+                                          "stops"
+                                        ]
                                       }
                                     },
                                     "required": [
diff --git a/skills/lark-sheets/references/lark-sheets-chart.md b/skills/lark-sheets/references/lark-sheets-chart.md
index 429ea3fa9..f41087b3e 100644
--- a/skills/lark-sheets/references/lark-sheets-chart.md
+++ b/skills/lark-sheets/references/lark-sheets-chart.md
@@ -31,7 +31,9 @@
 
 **常见配置错误（必须注意）**：
 - **图表类型选择错误**：用户说"堆积柱形图/百分比堆积"时，应在 `properties.snapshot.plotArea.plot.extra.stack` 中配置堆叠；百分比堆叠需在该 stack 下设置 `percentage: true`。用户说"占比/比例"时，优先考虑饼图或百分比堆积图。注意区分 `column`（柱形图，纵向）与 `bar`（条形图，横向）是两个不同的 type 取值，"对比/各 XX" 类纵向柱默认用 `column`
-- **数据标签缺失**：用户需要看到具体数值时，需配置 `properties.snapshot.plotArea.plot.labels`（数据标签）相关字段
+- **数据标签开关**：`plotArea.plot.labels` 对象的**存在性即开关**——
+  - 用户需要看到具体数值/类别时：传入 `labels` 并配置 `value` / `category` / `series` / `percentage` 等显示位。
+  - 用户明确说"不要数据标签 / 关掉标签"时：**整个 `labels` 字段省略**。不要用 `labels: { value: false, category: false, series: false }` 这种"全部置 false"的写法关闭——只要传了 `labels`，系统就会显示数据标签（且默认兜底显示 value）。
 - **数据源范围与系列名来源要对齐**：
   - **默认情况（inline 模式）**：`refs` 范围**应包含表头行**（首行/首列即系列名），且范围要精确覆盖目标数据，不要多选或少选。
   - **合并标题行要跳过**：如果表格在表头上方存在合并的标题行（如"员工统计表"横跨多列的大标题），`refs` 必须跳过标题行、从真正的列标题行开始。例如表头在第 3 行、数据在第 4-20 行，则 `refs` 应为 `A3:G20` 而非 `A1:G20`。包含合并标题行会导致列名识别错误、表头被当作数据参与聚合计算。