如何使用googleapis为Google Sheets单元格设置部分内容格式？

问题场景 #

我用googleapis包往Google Sheets插入数据，想要在单个单元格里添加多个链接（比如https://foo、https://bar）。手动操作可以轻松实现，也能通过以下代码查询到手动输入的数据格式：

const res = await sheets.spreadsheets.get({
    spreadsheetId,
    ranges: ['Intro!A1'],
    includeGridData: true
})

但自己写代码测试格式设置时，stringValue能正常写入，textFormatRuns却完全不生效，测试代码如下：

{
  userEnteredValue: {
    stringValue: "ABCDEFGHIJKLMNOP\nabcdefghijklmnop"
  },
  textFormatRuns: [
    {
      format: { bold: true, underline: true, link: { uri: "https://ddg.gg" } }
    },
    {
      format:{}, startIndex: 9,
    }
  ]
}

问题原因&解决方法 #

你的问题出在两个核心点：API调用方式错误，以及textFormatRuns的结构存在疏漏。

1. 必须使用batchUpdate接口 #

普通的values.update接口仅支持纯文本值写入，不处理富文本格式。要设置单元格的文本格式，必须使用spreadsheets.batchUpdate方法。

2. 修正textFormatRuns的结构 #

每个格式段需要明确startIndex，格式的生效范围是当前段的startIndex到下一个段的startIndex。另外，换行符\n会被算作一个字符，计算索引时要将其纳入考量。

以下是可正常运行的示例代码，实现给单元格内不同文本段添加不同链接：

// 构建批量更新请求
const updateRequest = {
  spreadsheetId: '你的表格ID',
  resource: {
    requests: [
      {
        updateCells: {
          range: {
            sheetId: 你的工作表ID, // 需填写工作表的数字ID，而非名称
            startRowIndex: 0,
            endRowIndex: 1,
            startColumnIndex: 0,
            endColumnIndex: 1
          },
          rows: [
            {
              values: [
                {
                  userEnteredValue: {
                    stringValue: "Google 百度"
                  },
                  textFormatRuns: [
                    // 给"Google"添加链接（索引范围0-5）
                    {
                      startIndex: 0,
                      format: {
                        underline: true,
                        link: { uri: "https://google.com" }
                      }
                    },
                    // 从索引6开始重置格式（对应空格位置）
                    {
                      startIndex: 6,
                      format: {}
                    },
                    // 给"百度"添加链接（索引范围7-8）
                    {
                      startIndex: 7,
                      format: {
                        underline: true,
                        link: { uri: "https://baidu.com" }
                      }
                    }
                  ]
                }
              ]
            }
          ],
          fields: 'userEnteredValue,textFormatRuns' // 必须指定这两个字段，否则格式设置会被忽略
        }
      }
    ]
  }
};

// 执行更新操作
const res = await sheets.spreadsheets.batchUpdate(updateRequest);

关键注意事项 #

• fields参数必须包含textFormatRuns，否则API会直接跳过格式设置逻辑；
• 索引计算要精准，每个字符（包括空格、换行符）都占用一个索引位置；
• 格式段是连续覆盖的，最后一段无需指定结束索引，默认生效到文本末尾。

内容的提问来源于stack exchange，提问作者Joel Peltonen