google-sheets

Google Sheets 创作

有意采用两种坐标系统

• VALUE 工具（read_range、write_range、append_rows、clear_range） 使用工作表标签标题和 A1 单元格地址：{sheet: "Data", cells: "A1:B4"}。
• STRUCTURE/FORMAT 工具（format_cells、set_borders、merge_cells、 add_chart、add_conditional_formatting、insert_rows_or_columns、 delete_rows_or_columns、freeze_rows_or_columns、sort_range、 set_data_validation、set_basic_filter、add_banding、 set_column_width、rename_sheet_tab、delete_sheet_tab）使用数字 sheetId。

get_spreadsheet 会返回两者（每个标签的标题和 sheetId），但不包含单元格 数据——请先调用它并保存映射。新标签的 sheetId 可在 add_sheet_tab 的回复中找到（replies[0].addSheet.properties.sheetId）。

按顺序创建带样式的工作表：先填值，再设格式，最后添加图表

1. create_spreadsheet（可选创建带名称的标签；它无法指定文件夹——之后使用 google-drive google_drive_move_or_rename 移动）。
2. 使用 write_range 写入数据；当值包含数字、日期或公式时，将 parseInput: true。默认值 false 会把所有内容都存为纯文本——这是导致“图表为空”问题的主要原因之一。
3. 设置格式，让它像真正的仪表板，而不是光秃秃的网格：
   • 使用 format_cells 将标题行设为粗体、填充颜色和白色文字；为数值列设置数字格式（$#,##0、0.0%）。
   • 使用 freeze_rows_or_columns 冻结标题行。
   • 对表格区域使用 set_basic_filter——筛选下拉菜单能让它呈现为数据表。
   • 使用 set_borders（外边框比内边框更粗）或 add_banding 设置交替行颜色；使用 set_column_width 避免内容被截断。
   • 使用 add_conditional_formatting 突出显示值得一眼关注的阈值。
4. 等数据就绪后，最后调用 add_chart。

图表

• 在 add_chart 中，第一个范围是维度（x 轴／饼图标签），后续范围是数据系列，每个范围对应一列；图表最常见的问题是锚定到错误或顺序颠倒的范围。所有范围都必须位于图表所在的同一标签中。headerCount: 1 会将首个单元格用作数据系列标签——设置此项时，请在每个范围中包含标题行。
• 将图表放在表格旁边或下方的空白单元格上，不要遮住其所绘制的数据。
• 图表有误时，应直接修复，而不是绕道处理：get_spreadsheet 会列出每个标签的图表（chartId、标题），update_chart 会在保留图表位置的同时替换其规格，delete_chart 可删除图表。切勿为了掩盖错误的第一个图表而再添加第二个。

命名范围和受保护范围

• add_named_range 可让公式更易读懂（例如 =SUM(Budget)，而不是 =SUM(B2:B13)）；编写公式时设置 parseInput: true。名称不能与单元格引用相似。
• protect_range 可保护标题和公式单元格（默认 warningOnly: true，会向编辑者发出警告；设为 false 则会锁定它们）。应在对该范围进行最后一次写入后再设置保护，否则你自己的写入也会受到保护限制。
• get_spreadsheet 会列出两者及其 ID，供 delete_named_range 和 unprotect_range 使用。

注意事项

• 全程没有修订版本保护：最后一次写入优先。如果协作者可能正在编辑，请先读取再写入。
• merge_cells 只会保留左上角单元格的值；合并后再写入文本。
• sort_range 会重排单元格位置；添加引用该范围的公式之前先排序，并将标题行排除在排序范围之外。
• insert_rows_or_columns／delete_rows_or_columns 的位置从 1 开始计数（A=1）；删除会立即生效，且无法通过 API 撤销。
• find_replace_sheet 使用字面匹配（此处绝不使用正则表达式），并且可以通过 searchFormulas: true 搜索公式内容。
• 读取整个标签可能会超出字节上限；对于尚未确定大小的标签，请限制 cells 范围（例如 "1:2000"），并在结果被截断时继续读取 nextCells。

验证你的工作

使用 read_range 查看值（FORMATTED_VALUE 显示用户看到的内容； UNFORMATTED_VALUE 显示原始数字——可用它确认数字是数字， 而不是文本）。使用 get_spreadsheet 查看结构：工作表标签页、图表、命名范围、 保护设置。若视觉效果很重要，可使用 google-drive google_drive_export_file（pdf 会渲染每个标签页，包括图表和格式）。