google-docs

Google Docs 编写

定位文本，切勿计算索引（最常见的错误来源）

Docs 编辑使用单个标签页内从 0 开始的 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} 就是段落级工具所需的范围。结束位置不包含在范围内：少一个字符会漏掉最后一个字符，多一个字符则会设置短语之后字符的样式（这是斜体或链接设置中典型的差一位错误）。

无法避免使用原始索引时：先调用 read_document，计算一次编辑，传入 requiredRevisionId 并执行，然后在下一次按位置编辑前重新读取。如果多部分按位置编辑的步骤之间重新读取成本过高，则按从后往前的顺序处理（从最高索引开始）；这样较早的范围仍然有效。

创建文档

create_document 会创建空白文档（其 API 会忽略内容），因此请提前规划：

• 内容已确定：优先使用 google-drive 的 google_drive_create_file 创建 Markdown（target_mime_type: ...document），这样一次调用即可导入标题、列表和表格，还可以指定目标文件夹。
• 逐步构建：先调用 create_document，然后使用省略 index 的 insert_text 逐段追加；追加模式会自行读取末尾位置，并自动使用版本修订保护。paragraphStyle 可设置新段落的样式，bold/italic 可设置插入文本的样式，因此结构良好的文档只需依次追加，无需再单独设置样式。
• 创建文档时无法设置父文件夹。需要指定存放位置时，先创建文档，再调用 google-drive 的 google_drive_move_or_rename 并设置 destination_folder_id。

结构必不可少

缺少层次结构的文档读起来就像一段文本转储。任何报告、备忘录或笔记请求的默认结构：一个标题段落、一行斜体署名或日期、每个部分使用一个 HEADING_2、简短的正文段落，并将重点短语加粗；列举内容使用项目符号列表。编写时使用 insert_text 的 paragraphStyle/bold/italic 参数设置样式，而不是事后再设置。

样式

• 字符样式（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，然后再应用所需预设。

表格和图片

• 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。宽度／高度以点为单位；只设置其中一项时会保持纵横比。
• insert_page_break 会从指定索引处开始新的一页。

页眉和页脚

set_header_footer 可通过一次调用设置默认页眉或页脚：如果文档中没有相应区段，就会创建；否则会替换其中的文本；设置为空文本则会清除内容。文本为静态文本（API 不支持页码字段）；该设置仅应用于第一个标签页。切勿在正文中使用 insert_text 插入伪页眉——它会随着内容滚动而消失。

批量文本操作

replace_text 可在所有位置（或指定标签页）替换字面字符串，无需计算索引；重命名和修正时优先使用它。delete_content 不接受会拆分表格结构或代理对的范围；删除段落末尾的换行符会使该段落与下一段合并。

验证结果

使用 read_document 重新读取文档以检查结构和样式；也可以使用 google-drive google_drive_read_file 将整个文档作为 Markdown 读取，或在需要检查视觉效果时使用 google_drive_export_file（pdf）。每次调用样式设置后，都要确认样式范围恰好覆盖目标文本，然后再继续。