使用Google Apps Script在Google Docs指定位置插入脚注

你之前脚注插入位置错误的核心原因是：Google Docs API使用全文档连续全局字符偏移作为位置索引，你手动取文档最后一个内容块的起始索引叠加文本长度的计算方式，本质是把插入点硬编码到了文档末尾，完全没有定位到目标文本所在的位置；另外如果用DocumentApp服务的子元素遍历接口计算索引，会因为接口返回的子元素序号和Docs API全局索引不映射，进一步加大偏移误差。
你现有流程里「先写完所有文档内容、调用saveAndClose()关闭文档，再通过Docs API插入脚注」的整体逻辑是对的，不需要调整，只需要修正目标位置的索引计算逻辑即可。

按以下步骤操作即可精准定位插入点：

• 所有内容写入完成并执行saveAndClose()后，通过Docs API的Documents.get接口拉取文档正文全量结构，不要用DocumentApp的接口做位置计算
• 遍历返回的所有正文内容块，跳过表格、图片、分页符等非文本元素，在文本段中匹配目标关键词Urgência，基于每个元素自带的startIndex属性计算该词后方的全局偏移量，这个值就是脚注上标的精准插入位置
• 按顺序发起两次batchUpdate请求：先在计算出的位置调用createFootnote创建脚注，拿到返回的脚注segmentId后，再向脚注段内写入对应文本内容

function insertFootnoteAtTarget() {
  // 替换为你实际生成的文档ID
  const DOC_ID = SpreadsheetApp.getActiveSpreadsheet().getRangeByName("generated_doc_id").getValue();
  const TARGET_KEYWORD = "Urgência";
  const FOOTNOTE_TEXT = "这里替换为你需要展示的脚注实际内容";

  // 拉取文档正文结构，只拿需要的字段减少请求体积
  const docContent = Docs.Documents.get(DOC_ID, {
    fields: "body/content(startIndex,endIndex,paragraph.elements(startIndex,endIndex,textRun.content))"
  });
  let insertPosition = null;

  // 遍历块定位目标位置
  for (const block of docContent.body.content) {
    // 跳过无段落、无文本内容的块
    if (!block.paragraph?.elements) continue;
    const blockBaseIndex = block.startIndex || 0;
    for (const elem of block.paragraph.elements) {
      if (!elem.textRun) continue;
      const elemText = elem.textRun.content;
      const keywordOffset = elemText.indexOf(TARGET_KEYWORD);
      if (keywordOffset !== -1) {
        // 计算关键词末尾的全局索引：块起始 + 元素在段内起始 + 关键词在元素内起始 + 关键词长度
        insertPosition = blockBaseIndex + elem.startIndex + keywordOffset + TARGET_KEYWORD.length;
        break;
      }
    }
    if (insertPosition) break;
  }

  if (!insertPosition) throw new Error("文档中未找到目标关键词Urgência，请检查内容写入逻辑");

  // 第一步：创建脚注
  const createFootnoteRes = Docs.Documents.batchUpdate({
    requests: [
      {
        createFootnote: {
          location: {
            index: insertPosition
          }
        }
      }
    ]
  }, DOC_ID);

  // 第二步：向脚注内写入文本
  const newFootnote = createFootnoteRes.replies[0].createFootnote;
  Docs.Documents.batchUpdate({
    requests: [
      {
        insertText: {
          location: {
            segmentId: newFootnote.footnoteId,
            index: 1 // 脚注独立段的内容起始索引固定为1
          },
          text: FOOTNOTE_TEXT
        }
      }
    ]
  }, DOC_ID);
}

• 绝对不要手动累加各内容块的长度计算索引，所有位置值必须以Docs API返回的元素自带startIndex/endIndex为准，表格单元格、页眉页脚属于独立segment，不会占用正文全局索引，不会干扰定位
• 如果文档其他章节也出现过Urgência一词，可以把匹配关键词改成完整串4.8 Urgência，避免误匹配到其他位置
• 必须等全文档所有内容写入、格式配置完成，且saveAndClose()执行完毕后再拉取文档结构计算索引，否则写入过程中内容动态变化会导致索引偏移
• 脚本需要提前在高级服务里开启Docs API权限，否则调用会报错

内容的提问来源于stack exchange，提问作者Frederico Falcetta