Google Apps Script在线与本地IDE的JSDoc类型标记兼容问题

先看示例代码：

function caller(){
  getSpreadsheet1();// 仅在线IDE可识别
  getSpreadsheet2();// 仅本地IDE（VS Code）可识别
}

/**
 * @returns {SpreadsheetApp.Spreadsheet}
 */
function getSpreadsheet1(){
  var spreadsheet = SpreadsheetApp.openById('');
  return spreadsheet;
}

/**
 * @returns {GoogleAppsScript.Spreadsheet.Spreadsheet}
 */
function getSpreadsheet2(){
  var spreadsheet = SpreadsheetApp.openById('');
  return spreadsheet;
}

问题详情 #

• 新版Google Apps Script在线IDE中，getSpreadsheet1()的JSDoc返回类型标记SpreadsheetApp.Spreadsheet能正常触发Spreadsheet类成员的自动补全
• 本地VS Code已按官方指南安装@types/google-apps-script，但仅getSpreadsheet2()使用的GoogleAppsScript.Spreadsheet.Spreadsheet标记能触发自动补全，getSpreadsheet1()的标记无效
• 本地VS Code可正确识别SpreadsheetApp.openById('')的返回类型

解决方法 #

通过自定义类型声明文件，将在线IDE使用的SpreadsheetApp子类型映射到本地类型系统可识别的GoogleAppsScript命名空间类型：

1. 在项目根目录创建一个类型声明文件，比如gas-global.d.ts
2. 在文件中添加以下代码：

declare namespace SpreadsheetApp {
  // 映射Spreadsheet类型
  type Spreadsheet = GoogleAppsScript.Spreadsheet.Spreadsheet;
  // 按需添加其他需要映射的类型，比如Sheet、Range等
  // type Sheet = GoogleAppsScript.Spreadsheet.Sheet;
  // type Range = GoogleAppsScript.Spreadsheet.Range;
}

3. 确保VS Code加载该声明文件：
   • 若项目有tsconfig.json，将该文件路径加入include数组
   • 无tsconfig.json时，直接放在项目根目录即可，VS Code会自动识别

完成后，本地VS Code就能识别@returns {SpreadsheetApp.Spreadsheet}这类标记，实现和在线IDE一致的自动补全效果。

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