PicoBot/.agents/skills/lark-sheets/references/lark-sheets-visual-standards.md

飞书表格样式与配色规范

本文定位：飞书表格"正确视觉输出"的取值标准与美化决策流——配色、表头、对齐、数值格式、斑马纹、列宽行高、图表展示，以及新增 / 继承 / 美化已有区域三类场景的做法。 边界：本文只讲"样式长什么样、怎么决策"；怎么调用工具写入样式（cell_styles / border_styles 字段、合并、resize 等参数）见 lark-sheets-write-cells / lark-sheets-range-operations / lark-sheets-batch-update。条件格式（高亮 / 标红 / 数据条 / 色阶）见 lark-sheets-conditional-format。本文不含 shortcut，铁律见 lark-sheets-core-operations。

最高优先级原则

• 用户指令优先：用户明确提出的格式要求（如"使用红色背景"）具有最高权重，即使与通用审美冲突。
• 继承原表风格：编辑前先采样原文件视觉特征（色系、边框、对齐、数字格式），新增内容必须与之对齐。严禁对已有风格的文件强行施加通用标准化格式。
• 扩展而非覆盖：新增行列或追加数据时，目标是"扩展原模板"——继承邻近区域的表头风格、条纹节奏、边框层级、对齐方式、数字格式和列宽/行高策略。
• 美化只动样式属性，不动数据：对已有区域做美化时，只能修改 font / fill / border / alignment / number_format 这 5 类样式属性。禁止改动原始单元格的 value / formula、合并区域、行列结构、Sheet 名称。如果美化需求需要改变数据布局（例如"汇总行加进表里"），必须把"加汇总行"和"美化"拆成两步，前者属于编辑动作、需另行得到用户授权。
• 不可见视觉属性也属保护对象：原表的合并范围、对齐方式（H-Align/V-Align）、行高列宽、数字格式是用户能感知但不一定会明示的视觉属性。即使用户没说"保留这些"，禁止因写入新内容而修改它们；写公式 / 写值 / 写新列时只传 value / formula，不要重置 alignment / number_format 等字段为默认值（重置等同于改动）。例外：用户明示要修改这些属性时（如"调整对齐 / 合并 / 列宽"）才能动。
• 美化范围必须覆盖所有用户语义目标：用户说"给表格加边框 / 美化整个表"时，范围 = 实际数据区域含所有数据行（含汇总行、总计行、表尾备注行），不能停在"看起来主体内容结束"的地方。落地前先用 current_region + 末尾 5~10 行核对真实末行（同 lark-sheets-read-data 的「确定数据范围的正确流程」），再设置美化范围。范围漏掉用户提到的目标行 / 列直接判失败。

美化任务 5 维度 checklist（用户说"美化 / 整理 / 让表更清晰 / 适合打印"时必做）

当用户用"美化 / 整理表格 / 让表清晰 / 适合打印 / 调整样式"等口语表达主动美化需求时，必须遍历以下 5 个维度逐一落地，只动一处就交付（如只加边框）属于违规：

1. 表头格式区分：表头行加粗 + 背景色填充（与数据行有色差）+ 居中对齐；多行表头时全部行同步处理
2. 对齐方式：文本列左对齐、数值 / 货币 / 百分比列右对齐、日期 / 分类列居中；垂直方向统一居中
3. 数值格式：每列统一小数位 + 千分位（用 number_format）；金额列统一货币符号；同一列内禁止出现 0 位 / 1 位 / 2 位小数混杂
4. 边框：覆盖范围按上方「美化范围必须覆盖所有用户语义目标」规则（含汇总 / 总计 / 表尾说明行），内外框线清晰
5. 列宽 + 行高 + 自动换行：详细规则见 lark-sheets-range-operations 的「写入后列宽自适应」章节（按最长字符数扩列宽 / 长文本设置 cell_styles.word_wrap="auto-wrap" + 调高行高 / 长数字设置 number_format 防科学计数法）

差异化标注场景：用户要求"重复行 / 异常值 / 重要项视觉区分"时，标注列 / 行必须设置与普通数据显著不同的 cell_styles（背景色 + 加粗 + 字体色至少改一项），不能与普通数据格式完全一致。

通用样式规范

以下取值标准都在「最高优先级原则」的继承原表风格 / 扩展而非覆盖前提下生效：凡涉及"沿用原表"的条目，遵循该原则即可，本节不再逐条复述。

1. 表头样式

• 表头/汇总行须与数据区域有明确视觉区分。
• 使用低饱和度背景色搭配字体颜色（如深蓝 + 白字，浅蓝 + 黑字），文字加粗、水平居中。
• 表头覆盖多列时使用合并单元格。

2. 数据区域样式

• 减少垂直线条，优先使用水平浅灰细线。
• 对齐方式：文本左对齐，数值/货币/百分比右对齐，日期或分类居中，所有内容垂直居中。
• 次要信息（备注、次要日期等）使用缩小字号或浅灰色。
• Zebra Stripes：数据行 > 10 行时可使用交替背景色引导视线。
  • 设置前先清理原区域背景色为白色（#FFFFFF），再设置斑马纹色，避免新旧混杂。
  • 优先直接设置单元格背景色，而非条件格式（除非用户要求）。
  • 推荐配色：奇数行 #FFFFFF，偶数行 #F3F4F6 或 #EBF1F8。

3. 数值格式

• 百分比使用 % 符号，适当注明单位和货币符号（¥、$）。
• 大于 1000 的数字使用千分位符，保留一致的小数位数（1–2 位）。
• 涉及数据检索的须注明数据来源。
• 可使用数据条/色阶/条件格式增强可视化。

4. 整体结构

• 长表/宽表考虑冻结行列，方便滚动查看。
• 长文本处理：启用自动换行，行高合理调整以确保阅读舒适，添加适当垂直留白，目标是清晰、专业、不拥挤的布局。
• 保持表格简洁，合理分组（可用合并单元格展示分组），在适当位置添加合计或汇总行。
• 区域分隔：多阶段或多类别时，使用柔和背景色块进行逻辑分区，而非简单边框。
• 增删行列的样式规则：
  • 新增整列继承同组列的表头样式、列宽、对齐和数字格式；新增整行继承同层级数据行或汇总行风格，避免写成表头风格。追加列时需判断是否应加入已有合并单元格（常见于顶部标题行）。
  • 若追加位置紧邻汇总行、说明区或空白分隔区，先判断真实数据区域边界再操作，避免破坏原有结构。
  • Zebra Stripes 维护：插入或删除行后若影响后续行奇偶性，须从受影响行往后重建条纹（先清理再重设）。少量增删用局部重建，大量变动用全局清理+统一重建。
  • 具体采样与复制流程见下方「场景二：从已有区域继承美化」。
• 列宽调整（飞书 +rows-resize / +cols-resize 按 pixel 传值）：
  • 禁止硬编码固定列宽，须根据该列实际内容长度估算像素。
  • 经验估算：中文每字约 15-18px，英文/数字每字约 7-9px，外加 10-16px padding。
  • 上下限建议 80~400px；超上限启用自动换行（word_wrap: auto-wrap）+ 调整行高，而非无限加宽。
  • 合并单元格不参与列宽计算，避免撑宽单列。
  • 复制自原文件的列优先沿用原列宽，不重新计算覆盖。

5. 配色

• 优先沿用原表色板与明暗层级（见「继承原表风格」），新增区域不凭空换色，确保视觉连续。
• 背景填充选择柔和色（如浅蓝 #DDEBF7），区分颜色时优先同一主题色不同深浅，避免超过 3 种主题色。

6. 图表展示

• 遵循用户指令选择图表类型，或匹配用户意图（饼图/环形图 → 占比，折线图 → 趋势）。
• 包含必要元素：标题、图例、数据标签、坐标轴标题。
• 调整至合适大小，避免数据和标签过多堆叠。
• 图表放置防重叠：新增图表前须计算放置区域，避免与已有图表重叠。具体步骤：
  1. 调用 +chart-list 获取当前工作表所有已有图表的 position（锚点单元格：row 行索引、col 列索引如 "A"/"B"）、offset（锚点内偏移：row_offset、col_offset，单位像素）以及 size（width、height，单位像素）。
  2. 获取工作表的行高和列宽信息（像素）。
  3. 根据每个图表的锚点 position.row/position.col + 偏移 offset.row_offset/offset.col_offset + 尺寸 size.width/size.height，结合行高列宽，计算出每个已有图表覆盖的像素矩形区域 (x_min, y_min, x_max, y_max)。
  4. 为新图表选定大小后，候选放置位置应避开所有已有矩形区域；若存在重叠则向下或向右偏移，直至找到无冲突位置。
  5. 若工作表已无足够空间，优先向下方空白区域放置，保持图表间至少 1 行或 1 列的间距。

飞书表格中颜色需带 # 前缀（如 #0070C0），与 openpyxl 的无前缀写法不同。 具体工具调用参数格式，请读取对应工具 skill（lark-sheets-write-cells、lark-sheets-conditional-format、lark-sheets-range-operations 等）。

---

场景化操作指南

场景一：新增独立样式

适用情况：在表格中创建全新的、具有独立视觉特征的区域，如汇总行、新表头、独立数据表等。

1A. 添加汇总行 / 表头行

决策流程：

1. 先用 +cells-get 读取目标位置上方的数据区域，确认数据边界和已有样式（背景色、字体大小等）
2. 如果需要新增空行，先用 +dim-{insert|delete|hide|unhide|freeze|group|ungroup} 插入行
3. 用 +cells-set 写入汇总公式 + 特殊样式（背景色区分 + 加粗 + 边框）
4. 如果汇总行标题需要跨列显示，追加 +cells-{merge|unmerge} 合并标题区域

样式要点：

• 汇总行使用比数据区域更深的同色系背景（如数据区 #EBF1F8 → 汇总行 #D6E4F0 或 #4472C4 + 白字）
• 必须加粗，水平对齐方式与数据列一致（数值列右对齐，文本列左对齐）
• 上方加一条较粗的边框线，与数据区域形成视觉分隔

1B. 添加独立数据表/独立区域

决策流程：

1. 新建 sheet，或用 +cells-get 或 +workbook-info 确认已有表格的占用范围，找到空闲区域
2. 用 +cells-get 采样已有表格的表头样式（背景色、字体大小、字重、对齐方式）和数据区域样式
3. 新表头复用已有表头的配色和字体参数（保持风格统一），但内容和列宽可独立
4. 新数据区域复用已有数据区域的对齐规则、边框风格、数字格式
5. 用 +cells-set 一次性写入新表头 + 数据

样式要点：

• 必须复用：背景色色系、字体大小、字重、边框风格
• 可以独立：列宽、行高、具体数字格式（根据新数据的类型调整）
• 新旧表格之间至少留 1~2 行空白作为视觉分隔

场景二：从已有区域继承美化

适用情况：新增的行/列/区域与已有内容性质相同（数据类型、层级一致），需要无缝衔接已有格式。

2A. 继续补充行/列（数据性质与已有内容一致）

核心规则：采样紧邻 2 行 → 判断并延续 Zebra Stripes 奇偶性 → 按 write-cells 的继承清单带齐样式写入。

斑马纹延续要点（本节只管"奇偶判断"这一标准，"带哪些样式字段写入"的机制见下方指针）：

• 至少读 2 行（末行 + 倒数第二行）才能判断是否有斑马纹交替色
• 若倒数两行背景色不同（如 #FFFFFF 与 #F3F4F6），新行按奇偶延续，不要固定一个色

具体继承哪些字段、怎么采样与写入（+cells-get 读源行 cell_styles + border_styles、+sheet-info --include row_heights,merges 读行高合并、带齐 6 类样式写入）见 lark-sheets-write-cells 的「新增列 / 新增行的样式继承」章节——border_styles 四边最易遗漏，以那里为准。

2B. 基于模板区域的修改（copy 保留所有格式）

核心思路：三步分层法

Step 1 — 格式铺开：`+batch-update` + `+range-copy`（或 `+range-fill`）
  └── 将模板行/区域的 **全部格式**（样式、边框、数字格式、数据验证等）复制到目标区域
  └── 推荐用 `+range-copy --paste-type formats`（仅复制格式，目标值/公式保留），即"格式刷"
  └── 若需连带公式平移填充（如公式列结构一致），改用 `+range-fill --series-type copy` 或 `+range-copy --paste-type all`

Step 2 — 内容覆写：`+batch-update` + `+cells-set`（仅传 value/formula，不传任何样式）
  └── 将每行的实际数据写入，cell_styles 全部省略，因为格式已在 Step 1 中就位

Step 3 — 微调收尾：`+batch-update` + `+rows-resize / +cols-resize` / `+cells-{merge|unmerge}` 等
  └── 调整行高列宽、处理合并单元格、扩展条件格式范围等边缘情况

关键注意事项：

• Step 1 用 +range-copy --paste-type formats 时只铺格式、不动值/公式，Step 2 再用 +cells-set 写值即可（+cells-set 默认覆盖，无需额外 flag）；若 Step 1 用 --paste-type all 连带复制了值/公式，Step 2 写入同样会覆盖（默认行为）
• +range-fill --series-type auto（或 linear/date）会自动递增数字序列（1→2→3）和日期序列，+range-fill --series-type copy 则原样复制值但公式引用会自动平移
• 如果模板区域存在合并单元格，copy/fill 不会复制合并状态，必须在 Step 3 中用 +cells-{merge|unmerge} 补全
• 如果模板区域有条件格式，需要在 Step 3 中通过 +cond-format-update 扩展 ranges

场景：纯"格式刷"（用户说"把 A 列样式应用到 B 列"、"格式复制过去"、"只刷格式不改数据"）

单步即可，无需三步分层：调用 +range-copy --paste-type formats，--source-range 为样式来源、--target-range 为目标起点。参数细节见 lark-sheets-range-operations。

场景三：已有区域格式美化

适用情况：对已存在数据的区域进行格式美化（不改变数据内容），重点处理表头、汇总行等特殊行的识别与格式设置，需特别注意合并单元格的安全操作。

整体操作流程

1. 探查阶段
   ├── `+workbook-info` → 获取子表列表、行列数、冻结位置
   ├── `+sheet-info --include merges` → 获取合并区域
   ├── `+cells-get`（前几行 + 末尾几行，`--include style`）→ 采样表头/数据区/汇总行样式
   └── 分析结果 → 建立区域地图（表头行号、数据起止行号、汇总行号、合并区域列表）

2. 规划阶段
   ├── 判断表头行：通常第 1 行或前 2 行，特征为加粗/背景色/合并/居中
   ├── 判断汇总行：通常最后 1~2 行，特征为加粗/SUM/AVERAGE 公式/更深背景色
   ├── 判断合并区域：从 `+cells-get` 返回中识别（多个单元格同值且样式相同通常暗示合并）
   └── 制定美化方案：按区域分别设置样式

3. 执行阶段（按顺序）
   ├── 先处理合并单元格（如需取消合并再重新合并，必须先 unmerge 再 merge）
   ├── 设置表头样式
   ├── 设置数据区域样式
   ├── 设置汇总行样式
   └── 调整列宽行高

美化中的合并单元格要点

• 编辑前先识别已有合并区域（见探查阶段），避免破坏原有语义分区。
• 美化表头/分组标题时，若需修改合并区域的范围或样式，遵循"先 unmerge → 修改 → 再 merge"顺序。
• 合并区域样式只写左上角，不要对合并内的其他单元格重复写入样式。

合并单元格完整的安全操作规则（含数据保护、样式占位等 5 条）见 lark-sheets-range-operations 的 +cells-{merge|unmerge} 章节。