Google Sheets setValues未调用对象toString()，直接显示对象内部结构

问题现象 #

使用Google Apps Script的setValue()/setValues()方法写入自定义对象实例时，方法不会调用对象的toString()、valueOf()或[Symbol.toPrimitive]转换方法，而是直接输出对象的内部属性键值对（如{b=2.0, a=1.0}），这种显示仅适合开发者调试，不符合终端用户的需求。

示例代码：

class Sample {
  [Symbol.toPrimitive](hint) {
    Logger.log('symbol')
    return `${this.a}-${this.b}`;
  }
  constructor(a, b) {
    this.a = a;
    this.b = b;
  }
  toString() {
    Logger.log('toString')
    return `${this.a}-${this.b}`;
  }
  valueOf() {
    Logger.log('valueOf')
    return `${this.a}-${this.b}`;
  }
}

function test() {
  const sample = new Sample(1, 2);
  SpreadsheetApp.getActiveSpreadsheet().getActiveSheet().getRange(1, 1).setValue(sample)
}

• 预期单元格值：1-2
• 实际单元格值：{b=2.0, a=1.0}

单个值可以手动调用sample.toString()解决，但面对混合了自定义对象和原始值的二维矩阵时，批量调用setValues()无法自动转换对象，且不想提前遍历预处理整个矩阵。

原因分析 #

Google Apps Script的Spreadsheet服务在处理非原始类型数据时，默认逻辑是序列化对象的可枚举属性，而非触发对象的原始值转换方法。这种设计偏向于开发者调试时查看对象结构，而非面向终端用户的展示需求。

可行解决方案 #

方案1：给自定义类添加toJSON()方法 #

Spreadsheet服务在序列化对象时会优先调用toJSON()方法，只需在类中实现该方法返回期望的字符串即可：

class Sample {
  [Symbol.toPrimitive](hint) {
    Logger.log('symbol')
    return `${this.a}-${this.b}`;
  }
  constructor(a, b) {
    this.a = a;
    this.b = b;
  }
  toString() {
    Logger.log('toString')
    return `${this.a}-${this.b}`;
  }
  valueOf() {
    Logger.log('valueOf')
    return `${this.a}-${this.b}`;
  }
  // 添加toJSON方法
  toJSON() {
    return `${this.a}-${this.b}`;
  }
}

修改后，调用setValue()或setValues()时会自动使用toJSON()返回的值，无需手动预处理。

方案2：封装自动转换的工具函数 #

如果无法修改类的定义（比如使用第三方类），可以封装一个递归遍历矩阵的工具函数，自动将对象转换为字符串：

function transformMatrix(matrix) {
  return matrix.map(row => 
    row.map(cell => 
      typeof cell === 'object' && cell !== null ? cell.toString() : cell
    )
  );
}

// 使用示例
function testBatch() {
  const matrix = [
    [new Sample(1,2), "原始字符串", 123],
    [new Sample(3,4), null, true]
  ];
  const transformedMatrix = transformMatrix(matrix);
  SpreadsheetApp.getActiveSpreadsheet().getActiveSheet().getRange(1,1,2,3).setValues(transformedMatrix);
}

该函数会递归处理矩阵中的每个元素，将对象自动转换为toString()的结果，不影响原始值的类型。

说明 #

目前Google Sheets的Spreadsheet服务并未提供全局配置来改变对象的序列化行为，上述方案是最直接的解决方式。如果需要更灵活的转换逻辑，可以在工具函数中根据对象类型定制转换规则。

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