如何使用Google Docs API在指定项目符号下插入子项并维持层级？

问题分析 #

直接用insertText插入\n\tNew text时，Docs API会把新文本识别为一级列表项，而非目标父列表（Text 1）的子项，导致层级错误。这是因为手动加制表符无法让API正确继承父列表的格式属性，必须显式设置段落的列表嵌套规则。

解决方案 #

使用insertParagraph请求插入新段落，同时指定其所属的列表ID和嵌套层级，确保新文本成为Text 1的二级子项。

步骤1：获取目标列表ID和插入位置 #

先通过documents.get接口获取文档结构，定位Text 1的列表ID，以及原1.1 Internal text段落的起始位置（作为插入点）：

from googleapiclient.discovery import build

# 初始化Docs服务
service = build('docs', 'v1', credentials=YOUR_CREDENTIALS)
DOCUMENT_ID = "你的文档ID"

# 获取文档内容
doc = service.documents().get(documentId=DOCUMENT_ID).execute()
content = doc['body']['content']

parent_list_id = None
insert_index = None

for element in content:
    if 'paragraph' in element:
        para = element['paragraph']
        text_content = para['text']['content'].strip()
        # 定位Text 1的段落，获取父列表ID
        if text_content == 'Text 1' and para.get('bullet'):
            parent_list_id = para['bullet']['listId']
        # 定位原Internal text段落，获取插入位置（在它之前插入）
        elif text_content == 'Internal text':
            insert_index = element['startIndex']
            break

步骤2：插入带嵌套层级的新段落 #

构建insertParagraph请求，指定列表ID和嵌套层级（二级列表对应nestingLevel: 1，一级为0）：

requests = [
    {
        "insertParagraph": {
            "location": {"index": insert_index},
            "paragraph": {
                "text": "New text",
                "bullet": {
                    "listId": parent_list_id,
                    "nestingLevel": 1
                }
            }
        }
    }
]

# 执行批量更新
service.documents().batchUpdate(
    documentId=DOCUMENT_ID,
    body={"requests": requests}
).execute()

关键说明 #

• 必须显式设置bullet属性：通过指定父列表的listId和对应nestingLevel，让API明确新段落的层级关系。
• 插入位置选择：在原二级列表项之前插入，确保新文本成为父列表的第一个子项，后续原子项会自动调整编号为1.2。

内容的提问来源于stack exchange，提问作者Vítor César