google-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Docs authoring

Google Docs 编写

Locate text, never compute indexes (the #1 source of bugs)

定位文本，不要计算索引（错误的头号来源）

Docs edits address zero-based UTF-16 index ranges within one tab, and every write SHIFTS later indexes. Guessed or stale indexes silently hit the wrong paragraphs - the classic symptom is two lists merging into one continued numbering. The tools remove the need for index math:

```
find_text
```
returns FRESH
```
{start, end}
```
ranges for exact text - the direct source of indexes for
```
apply_text_style
```
,
```
apply_paragraph_style
```
,
```
delete_content
```
, and
```
set_paragraph_format
```
. Locate, then edit, in back-to-back calls.
```
create_list
```
takes
```
firstItemText
```
/
```
lastItemText
```
anchors and resolves the range itself: name the first and last item paragraphs and no index ever touches your hands. Use one
```
create_list
```
per list with the right preset (BULLET_* for bullets, NUMBERED_* for numbers); never stretch one call across two visually separate lists.

When a range must come from structure instead of a phrase (styling a whole paragraph, addressing a table), read it from

read_document

elements: a paragraph's

{start, end}

is the range for paragraph-level tools. END IS EXCLUSIVE: one short misses the last character, one long styles the character after the phrase (the classic italic-or-link off-by-one).

When raw indexes are unavoidable:

read_document

first, compute ONE edit, pass

requiredRevisionId

, apply, and re-read before the next positional edit. Order multi-part positional work BACK-TO-FRONT (highest index first) when re-reading between steps is too expensive; earlier ranges stay valid.

Docs 编辑操作针对单个标签页内从零开始的 UTF-16 索引范围，并且每次写入都会使后续索引发生偏移。猜测或过期的索引会静默地作用于错误的段落——典型症状是两个列表合并为一个连续编号列表。这些工具消除了索引计算的需求：

```
find_text
```
返回精确文本的实时
```
{start, end}
```
范围——这是
```
apply_text_style
```
、
```
apply_paragraph_style
```
、
```
delete_content
```
和
```
set_paragraph_format
```
的索引直接来源。先定位，再编辑，连续调用即可。
```
create_list
```
接受
```
firstItemText
```
/
```
lastItemText
```
锚点并自行解析范围：指定第一个和最后一个项目段落，无需手动接触任何索引。每个列表使用一次
```
create_list
```
，并选用正确的预设（项目符号用
```
BULLET_*
```
，数字编号用
```
NUMBERED_*
```
）；切勿在一次调用中跨越两个视觉上独立的列表。

当范围必须来自结构而非文本片段时（例如为整个段落设置样式、处理表格），从

read_document

元素中读取：段落的

{start, end}

就是段落级工具所需的范围。END 是排他性的：少一位会漏掉最后一个字符，多一位会把短语后面的字符也加上样式（经典的斜体或链接差一错误）。

当不可避免地要使用原始索引时：先调用

read_document

，计算一次编辑，传入

requiredRevisionId

，执行编辑，在下一次位置编辑前重新读取。当步骤间重新读取代价过高时，将多部分位置编辑按从后到前的顺序（最高索引优先）执行；较早的范围仍然有效。

Creating a document

创建文档

create_document

makes a BLANK doc (its API ignores content), so plan:

Content known up front: prefer google-drive
```
google_drive_create_file
```
with Markdown (
```
target_mime_type: ...document
```
), which imports headings, lists, and tables in one call and can target a folder.
Building incrementally:
```
create_document
```
, then
```
insert_text
```
with
```
index
```
omitted to APPEND each paragraph; append mode reads the tail itself and is revision-guarded automatically.
```
paragraphStyle
```
styles the new paragraphs and
```
bold
```
/
```
italic
```
style the inserted text in the same call, so a well-structured document is a sequence of appends with no styling pass.
Doc creates cannot set a parent folder. When placement matters, create and then google-drive
```
google_drive_move_or_rename
```
with
```
destination_folder_id
```
.

create_document

创建的是空白文档（其 API 忽略内容），因此需要规划：

内容预先已知：优先使用 google-drive 的
```
google_drive_create_file
```
，并传入 Markdown（
```
target_mime_type: ...document
```
），它能在一次调用中导入标题、列表和表格，并可指定目标文件夹。
逐步构建：先调用
```
create_document
```
，然后使用
```
insert_text
```
（省略
```
index
```
参数）以追加方式逐段写入；追加模式会自行读取文档末尾，并自动进行修订保护。
```
paragraphStyle
```
可在同一次调用中为新段落设置样式，
```
bold
```
/
```
italic
```
可为插入的文本设置样式，因此结构良好的文档就是一系列追加操作，无需单独的样式处理步骤。
创建文档时无法设置父文件夹。当位置很重要时，先创建，然后使用 google-drive 的
```
google_drive_move_or_rename
```
并指定
```
destination_folder_id
```
。

Structure is not optional

结构不是可选项

A document without hierarchy reads as a text dump. Default shape for any report/memo/notes request: a TITLE paragraph, an italic byline or date line, HEADING_2 per section, short body paragraphs with bold on the phrases that matter, and bulleted lists for enumerations. Use

insert_text

's paragraphStyle/bold/italic arguments as you write rather than styling afterwards.

没有层级结构的文档读起来就像文本转储。任何报告/备忘录/笔记请求的默认结构应为：一个标题段落、一个斜体的署名或日期行、每个章节使用 HEADING_2、简短正文段落并在关键短语上加粗、枚举内容使用项目符号列表。在写作时通过

insert_text

的 paragraphStyle/bold/italic 参数来应用样式，而不是事后统一添加。

Styling

样式

Character styling (
```
apply_text_style
```
): bold/italic/underline/strike, fontSize, fontFamily, textColor/backgroundColor as
```
#RRGGBB
```
, linkUrl. Exclusive END index: to style one paragraph without its trailing newline, use
```
end - 1
```
from the read.
Paragraph styling:
```
apply_paragraph_style
```
for named styles (TITLE/HEADING_1..6),
```
set_paragraph_format
```
for alignment, indents, and line spacing (percent, 100 = single).
Lists:
```
create_list
```
over the paragraphs' range; each newline-separated paragraph becomes one item. Insert the plain lines first, then bullet them.
The preset is part of correctness: enumerations get a BULLET_* preset by default; NUMBERED_* only when the content is ordered (steps, rankings) or the request says numbered.
Before bulleting, check the read for paragraphs that ALREADY show a leading bullet - text appended directly after a list inherits its membership, and
```
create_list
```
over such paragraphs restyles the ORIGINAL list, continuing its numbering (a second list showing 4, 5, 6). Strip first:
```
create_list
```
with
```
remove: true
```
over exactly the new paragraphs, then apply the wanted preset.

字符样式（
```
apply_text_style
```
）：粗体/斜体/下划线/删除线、fontSize、fontFamily、textColor/backgroundColor（使用
```
#RRGGBB
```
格式）、linkUrl。排他性 END 索引：如果要为一个段落设置样式但不包含其末尾换行符，请使用读取结果中的
```
end - 1
```
。
段落样式：
```
apply_paragraph_style
```
用于命名样式（TITLE/HEADING_1..6），
```
set_paragraph_format
```
用于对齐、缩进和行间距（百分比，100 表示单倍行距）。
列表：对段落范围调用
```
create_list
```
；每个换行分隔的段落成为一项。先插入纯文本行，再将其转换为项目符号列表。
预设是正确性的一部分：枚举默认使用
```
BULLET_*
```
预设；只有内容是有序的（步骤、排名）或请求明确要求编号时才使用
```
NUMBERED_*
```
。
在添加项目符号之前，检查读取结果中是否已有段落显示了前导项目符号——在列表之后直接追加的文本会继承列表成员身份，对这类段落调用
```
create_list
```
会重新设置原列表的样式，并延续其编号（第二个列表可能显示为 4、5、6）。需要先剥离：对恰好新追加的段落使用
```
create_list
```
并设置
```
remove: true
```
，然后再应用所需的预设。

Tables and images

表格和图片

```
insert_table
```
inserts an EMPTY grid. To fill it: re-read (cells appear with their own index ranges) and
```
insert_text
```
into cells from the LAST cell to the first, so earlier cell indexes stay valid.
Style a table AFTER filling it, addressing it by the table element's
```
start
```
from
```
read_document
```
:
```
set_table_cell_shading
```
the header row (pick the row's text color against that fill),
```
merge_table_cells
```
for a title cell spanning columns (top-left content survives, the rest is dropped),
```
set_table_column_width
```
for fixed widths in points. Structural edits (merge) shift indexes: re-read before further text edits.
```
insert_image
```
needs a PUBLICLY fetchable URL (Google fetches it; auth walls and private hosts fail), PNG/JPEG/GIF. Size with width/height in points (aspect kept when only one is set).
```
insert_page_break
```
starts a new page at an index.

```
insert_table
```
插入一个空网格。要填充它：重新读取文档（单元格会出现自己的索引范围），然后从最后一个单元格到第一个单元格依次调用
```
insert_text
```
，这样前面的单元格索引仍然有效。
在填充表格后再设置样式，通过
```
read_document
```
返回的表格元素的
```
start
```
来定位表格：使用
```
set_table_cell_shading
```
为标题行设置底纹（选择该行的文本颜色以匹配填充色），使用
```
merge_table_cells
```
合并跨列标题单元格（左上角内容保留，其余内容丢弃），使用
```
set_table_column_width
```
以磅为单位设置固定列宽。结构性编辑（如合并）会改变索引：在进一步的文本编辑之前需要重新读取。
```
insert_image
```
需要一个可公开访问的 URL（Google 会去获取它；需要认证的服务和私有主机无法访问），支持 PNG/JPEG/GIF。可通过 width/height 以磅为单位设置大小（只设置一个时保持宽高比）。
```
insert_page_break
```
在指定索引处开始新页面。

Headers and footers

页眉和页脚

set_header_footer

sets the default header or footer in one call: it creates the segment when the doc has none, replaces the text otherwise, and empty text clears it. The text is static (no page-number fields exist in the API); it applies to the first tab. Never

insert_text

a fake header into the body - it scrolls away with the content.

set_header_footer

一次调用即可设置默认页眉或页脚：当文档没有该节时创建，有则替换其中的文本，传入空文本则清除。文本是静态的（API 中不存在页码字段）；它适用于第一个标签页。切勿将伪造页眉用

insert_text

插入正文——它会在内容滚动时消失。

Bulk text ops

批量文本操作

replace_text

replaces literal strings everywhere (or in named tabs) with no index math; prefer it for renames and corrections.

delete_content

rejects ranges that split table structure or surrogate pairs; deleting a paragraph's final newline merges it with the next.

replace_text

可在所有位置（或指定标签页中）替换字面字符串，无需索引计算；重命名和更正时优先使用它。

delete_content

会拒绝拆分表格结构或代理对的范围；删除段落的末尾换行符会使其与下一段合并。

Verify your work

验证你的工作

Re-read with

read_document

for structure and styles, or google-drive

google_drive_read_file

for the whole doc as Markdown, or

google_drive_export_file

(pdf) when the visual result matters. After any styling call, confirm the styled span covers exactly the intended text before moving on.

使用

read_document

重新读取以检查结构和样式，或使用 google-drive 的

google_drive_read_file

将整个文档读取为 Markdown，或使用

google_drive_export_file

（pdf）当视觉效果重要时。在任何样式调用之后，先确认样式覆盖的范围精确地包含预期的文本，然后再继续。