在 Google Sheets/Workspace…

当需要为 Google Sheets 添加自定义菜单、触发器、侧边栏、邮件/PDF 导出或外部 API 集成时，用 Apps Script 编写并部署自动化脚本。

适用场景

解决思路

1. 先明确要自动化的场景：自定义菜单动作（报表生成、数据处理）、自动触发行为（编辑时、表单提交时、定时）、数据录入侧边栏、基于表格数据的邮件通知、PDF 导出与分发。
2. 按固定结构生成脚本：文件头注释（项目名、说明、安装步骤）、顶部配置常量、onOpen() 用于创建菜单，然后是各功能函数。
3. 提供统一安装步骤：打开 Google Sheet → Extensions > Apps Script → 删除编辑器内已有代码 → 粘贴脚本 → Save → 关闭 Apps Script 标签页 → 重新加载电子表格（onOpen 在页面加载时运行）。
4. 提醒首次授权流程：每个用户首次运行会看到 Google OAuth 同意屏，未验证脚本需点击 Advanced > Go to [Project Name] (unsafe) > Allow，这是每用户一次性的。
5. 函数命名规则：以 _ 结尾的函数是私有的，无法被客户端 HTML 通过 google.script.run 调用，且会静默失败；菜单项引用的函数名也必须是公开函数名字符串。
6. 批量读写数据：始终用 getRange().getValues() / setValues() 一次性读写，不要逐单元格操作（100x100 场景下 70 秒 vs 1 秒，差 70 倍）。
7. 使用 V8 运行时（Rhino 已于 2026 年 1 月移除），支持 const/let、箭头函数、模板字符串、解构、类、async/generators；但 setTimeout/setInterval 用 Utilities.sleep(ms) 替代，fetch 用 UrlFetchApp.fetch()，FormData 手动构造 payload，URL 用字符串处理，crypto 用 Utilities.computeDigest() / Utilities.getUuid()。
8. 在修改表格的函数返回前调用 SpreadsheetApp.flush()，尤其是从 HTML 对话框调用的函数，否则对话框显示 Done 时改动可能还不可见。
9. 区分简单触发器与可安装触发器：简单 onEdit 无需授权但不能发邮件、访问其他文件、URL fetch、打开对话框；需要这些能力时用 ScriptApp.newTrigger() 创建可安装触发器。
10. 自定义表格函数（=MY_FUNCTION()）必须带 @customfunction JSDoc 标签，只能用基础 JS、Utilities、CacheService，不能用 MailApp、UrlFetchApp、SpreadsheetApp.getUi()、触发器，且有 30 秒执行上限（普通函数 6 分钟）。
11. 注意配额：免费账号脚本单次运行 6 分钟、定时触发器 30 分钟、触发器每日总运行 90 分钟、每日邮件 100 封、每日 URL Fetch 20000 次、Properties 存储 500 KB、同时执行 30 个；Workspace 账号邮件 1500 封、URL Fetch 100000 次、触发器每日 6 小时。
12. 长操作使用模态进度对话框：菜单函数调用 showProgress(message, serverFn)，HTML 中用 google.script.run 的 withSuccessHandler/withFailureHandler 调用公开动作函数，成功后 1.2 秒自动关闭，失败显示错误 3 秒后关闭；被调用的动作函数必须公开（无下划线），并在返回前 flush()。
13. 常用交互：用 SpreadsheetApp.getActiveSpreadsheet().toast(message, title, seconds) 显示提示；用 ui.alert() 做 Yes/No 确认；用 ui.prompt() 获取输入。
14. 侧边栏应用：用 HtmlService.createHtmlOutput() 生成 HTML，通过 google.script.run 调用服务端公开函数，用 showSidebar() 显示。
15. 触发器写法：onEdit(e) 简单触发器用 e.source、e.range 判断工作表和列；可安装触发器用 ScriptApp.newTrigger('fn').timeBased().atHour(8).everyDays(1).create()、.forSpreadsheet(...).onEdit().create()、.forSpreadsheet(...).onFormSubmit().create()，需手动运行一次 setup 函数。
16. 从表格发邮件：用 getDisplayValues() 读取数据，拼接 HTML 表格，用 MailApp.sendEmail({to, subject, htmlBody}) 发送。
17. PDF 导出：用 ss.getUrl().replace(/\/edit.*$/, '') + '/export?exportFormat=pdf&format=pdf&size=A4&portrait=true&fitw=true&sheetnames=false&printtitle=false&gridlines=false&gid=' + sheetId 构造 URL，用 UrlFetchApp.fetch 带 Authorization: Bearer + ScriptApp.getOAuthToken() 获取 blob，setName 后用 MailApp 作为附件发送。
18. 外部 API 调用：GET 用 UrlFetchApp.fetch(url, {headers}) 后 JSON.parse(r.getContentText())；POST 用 method: 'post'、contentType: 'application/json'、payload: JSON.stringify(payload)、muteHttpExceptions: true，检查 getResponseCode() 后解析。
19. 数据验证下拉：用 SpreadsheetApp.newDataValidation().requireValueInList([...], true).setAllowInvalid(false).setHelpText(...).build() 或 requireValueInRange(range) 后 setDataValidation 应用到范围。
20. 持久化存储用 PropertiesService：getScriptProperties()（共享）、getUserProperties()（每用户）、getDocumentProperties()（每表格），用 setProperty/getProperty，上限 500 KB。
21. 自动归档已完成行：从数据底部向上遍历（for i = data.length - 1; i >= 1; i--），匹配状态列后 archive.appendRow(data[i]) 并 source.deleteRow(i + 1)，最后 flush()。
22. 重复检测：一次 getValues() 读取整列，用对象记录已见值，对原始行和重复行用 setBackground('#f4cccc') 高亮。
23. 批量发邮件：先检查 MailApp.getRemainingDailyQuota()，不足则 alert 并返回；逐行读取 Email/Name/Status，跳过已发送，每次发送包 try/catch，成功写 'Sent'，失败写 'Error: ' + e.message，最后 flush()。
24. 汇总仪表盘：循环编号周标签页（01-52），读取每个的汇总单元格，写入 Summary 表，用 ss.getSheetByName(tabName) 遍历，不存在则 ss.insertSheet('Summary')，最后 summary.autoResizeColumns() 并 flush()。
25. 错误处理：外部调用一律 try/catch，用 muteHttpExceptions: true 自行处理 HTTP 错误，非 200 抛错，Logger.log 记录后重新抛出以便对话框错误处理器捕获。
26. 调试手段：Logger.log()/console.log() 在 Apps Script 编辑器 View > Execution Log 查看；在编辑器下拉选择函数手动 Run；Executions 标签查看最近运行与堆栈；触发器失败在 script.google.com > My Projects > Executions 查看；部署前始终在表格副本上测试。
27. 部署前检查清单：HTML 对话框调用的函数均为公开（无下划线）、修改函数返回前调用 flush()、外部 API 与 MailApp 包 try/catch、配置常量置顶、头部注释含安装说明、在副本上测试、考虑多用户行为、长操作使用模态进度对话框、不硬编码表名、批量发送前检查邮件配额。
28. 其他可重建能力：用 sheet.hideRows()/showRows()/isRowHiddenByUser() 控制行列显隐；用 setBackground()/setFontWeight()/setBorder()/setNumberFormat() 和条件格式做格式化；用 range.protect()/setUnprotectedRanges() 做数据保护；用 getSheetByName()/copyTo()/insertSheet() 处理多表；用 onEdit 在 B 列编辑时自动编号 A 列；用 POST 到 chat.googleapis.com 发 Google Chat webhook。

适用边界 · 注意事项

• 需要 setTimeout/setInterval、fetch、FormData、URL、crypto 等浏览器/Node API 时——Apps Script 不提供，必须改用 Utilities.sleep、UrlFetchApp、手动构造 payload、字符串处理、Utilities.computeDigest 等替代方案。
• 自定义表格函数（=MY_FUNCTION()）中需要发邮件、调用外部 API、访问 UI 或触发器时——这些服务在自定义函数中不可用，且执行上限仅 30 秒，应改为普通函数或可安装触发器。
• 简单 onEdit 触发器需要发邮件、访问其他文件、URL fetch 或打开对话框时——简单触发器无授权，必须改用 ScriptApp.newTrigger() 创建可安装触发器。