google-sheets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Sheets authoring

Google Sheets 制作

Two coordinate systems, on purpose

两套坐标系（有意设计）

VALUE tools (

read_range

write_range

append_rows

clear_range

) address a TAB TITLE plus A1 cells:

{sheet: "Data", cells: "A1:B4"}

STRUCTURE/FORMAT tools (

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

) address the numeric

sheetId

get_spreadsheet

returns both (each tab's title AND sheetId) with no cell data - call it first and keep the mapping. A new tab's sheetId is in

add_sheet_tab

's reply (

replies[0].addSheet.properties.sheetId

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

）。

Sequencing a styled sheet: values first, then format, chart last

样式化表格的步骤：先写数据，再格式化，最后加图表

```
create_spreadsheet
```
(optionally with named tabs; it cannot target a folder - move it after with google-drive
```
google_drive_move_or_rename
```
).
```
write_range
```
the data with
```
parseInput: true
```
when values include numbers, dates, or formulas (default false stores everything as literal text - a top source of "chart is empty" bugs).
Format like a real dashboard, not a bare grid:
- ```
format_cells
```
  bold header with a fill color and white text; number patterns on value columns (
```
$#,##0
```
  ,
```
0.0%
```
  ).
- ```
freeze_rows_or_columns
```
  the header row.
- ```
set_basic_filter
```
  over the table range - filter dropdowns are what make it read as a data table.
- ```
set_borders
```
  (outer heavier than inner) or
```
add_banding
```
  for alternating row colors;
```
set_column_width
```
  so nothing clips.
- ```
add_conditional_formatting
```
  for thresholds worth seeing at a glance.
```
add_chart
```
LAST, after the data exists.

```
create_spreadsheet
```
（可选创建命名的标签页；它不能指定文件夹——之后用 google-drive 的
```
google_drive_move_or_rename
```
移动）。
当值包含数字、日期或公式时，用
```
parseInput: true
```
的
```
write_range
```
写入数据（默认为 false，会把所有内容存为字面文本——这是“图表为空”类 bug 的头号原因）。
要像真实仪表板一样格式化，而不是光秃秃的网格：
- 用
```
format_cells
```
  加粗表头，设置填充色和白色文字；在数值列上设置数字格式（
```
$#,##0
```
  、
```
0.0%
```
  ）。
- 用
```
freeze_rows_or_columns
```
  冻结表头行。
- 用
```
set_basic_filter
```
  在表格范围上添加筛选——筛选下拉框正是让表格看起来像数据表的关键。
- 用
```
set_borders
```
  （外边框比内边框粗）或
```
add_banding
```
  实现交替行颜色；用
```
set_column_width
```
  确保内容不被裁切。
- 用
```
add_conditional_formatting
```
  标出一目了然的关键阈值。
最后再
```
add_chart
```
，确保数据已存在。

Charts

图表

In
```
add_chart
```
, the FIRST range is the domain (x axis / pie labels) and later ranges are the series, one column each; anchoring a chart to the wrong or reversed ranges is the most common chart bug. All ranges live on the same tab as the chart.
```
headerCount: 1
```
uses the first cells as series labels - include the header row in each range when you set it.
Place the chart over empty cells beside or below the table, not on top of the data it plots.
A wrong chart is fixed in place, not worked around:
```
get_spreadsheet
```
lists every tab's charts (chartId, title),
```
update_chart
```
replaces a chart's spec keeping its position,
```
delete_chart
```
removes one. Never add a second chart to paper over a bad first one.

在
```
add_chart
```
中，第一个范围是类别轴（x 轴 / 饼图标签），后续范围是数据系列，每列一个；将图表锚定到错误或颠倒的范围是最常见的图表 bug。所有范围必须与图表位于同一标签页。
```
headerCount: 1
```
会把每个范围的第一行单元格用作系列标签——设置时需要把表头行包含在每个范围内。
将图表放在表格旁边或下方的空白单元格区域，不要覆盖它要绘制的数据。
错误的图表应当直接就地修复，而不是绕开：
```
get_spreadsheet
```
会列出每个标签页的图表（chartId、标题），
```
update_chart
```
替换图表的 spec 并保持其位置，
```
delete_chart
```
删除图表。绝不要添加第二个图表来掩盖第一个坏图表。

Named and protected ranges

命名和保护区域

```
add_named_range
```
makes formulas self-documenting (
```
=SUM(Budget)
```
instead of
```
=SUM(B2:B13)
```
); write the formula with
```
parseInput: true
```
. Names cannot look like cell references.
```
protect_range
```
guards headers and formula cells (
```
warningOnly: true
```
by default warns editors;
```
false
```
locks them). Protect AFTER the last write to that range, or your own writes fight the protection.

get_spreadsheet

lists both, with the ids

delete_named_range

and

unprotect_range

need.

```
add_named_range
```
让公式具有自文档性（用
```
=SUM(Budget)
```
代替
```
=SUM(B2:B13)
```
）；使用
```
parseInput: true
```
写入公式。名称不能看起来像单元格引用。
```
protect_range
```
保护表头和公式单元格（默认
```
warningOnly: true
```
会提醒编辑者；
```
false
```
则锁定）。必须在最后一次写入该区域之后再进行保护，否则你自己的写入会和保护冲突。

get_spreadsheet

会列出两者，以及

delete_named_range

和

unprotect_range

所需的 id。

Pitfalls

常见陷阱

No revision guard anywhere: last write wins. Read before writing when a collaborator may be editing.
```
merge_cells
```
keeps only the top-left value; write the text after merging.
```
sort_range
```
rewrites cell positions; sort before adding formulas that reference the range, and exclude the header row from the sorted range.
```
insert_rows_or_columns
```
/
```
delete_rows_or_columns
```
positions are 1-based (A=1); deletes are immediate and not undoable through the API.
```
find_replace_sheet
```
is literal (never regex here) and can search inside formulas with
```
searchFormulas: true
```
.
Whole-tab reads can blow the byte cap; bound
```
cells
```
(e.g. "1:2000") on tabs you have not sized and follow
```
nextCells
```
when truncated.

任何地方都没有修订保护：最后一次写入生效。当可能有协作者编辑时，写入前先读取。
```
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
```
。

Verify your work

验证你的工作

read_range

for values (FORMATTED_VALUE shows what the user sees; UNFORMATTED_VALUE the raw numbers - use it to confirm numbers are numbers, not text).

get_spreadsheet

for structure: tabs, charts, named ranges, protections. google-drive

google_drive_export_file

(pdf renders every tab including charts and formatting) when the visual result matters.

用

read_range

读取值（FORMATTED_VALUE 显示用户看到的内容；UNFORMATTED_VALUE 是原始数字——用它来确认数字确实是数字，而不是文本）。用

get_spreadsheet

检查结构：标签页、图表、命名区域、保护。当视觉效果很重要时，用 google-drive 的

google_drive_export_file

（PDF 会渲染包括图表和格式在内的所有标签页）。