引言：Google Apps Script 文件上传的挑战
在 google apps script 开发中，当需要从 html 用户界面（前端）向 apps script 服务器端函数（后端）提交包含文件（如图片、文档）的表单数据时，开发者常会遇到挑战。由于 apps script 的沙盒环境限制，传统的浏览器 file api 或 formdata 对象在直接传递给 google.script.run 时可能无法按预期工作，尤其是在处理文件内容本身而非仅其元数据时。本教程将深入探讨两种有效的解决方案，帮助您克服这些挑战，实现文件与表单数据的无缝集成。
策略一：利用 google.script.run 直接提交表单对象
Google Apps Script 的 HTML Service 提供了一种简便的方式来处理表单提交，即直接将完整的 <form> 元素作为参数传递给服务器端函数。在这种模式下，Apps Script 会自动解析表单数据：常规的文本输入字段会被转换为字符串，而文件输入字段 (<input type="file">) 的内容则会被转换为 Apps Script 后端可识别的 Blob 对象。
原理阐述
当一个 <form> 元素被 google.script.run 调用时，它会被封装成一个 JavaScript 对象，其中表单字段的 name 属性作为键，其值作为对应的值。对于文件输入，其值不再是文件名字符串，而是 Apps Script 的 Blob 对象，可以直接用于 DriveApp.createFile() 等操作。
前端 HTML 结构
为了使服务器端能够正确识别表单字段，请确保所有输入元素都包含 name 属性。
<!DOCTYPE html>
<html>
<head>
<base target="_top">
</head>
<body>
<form id="myForm" onsubmit="handleFormSubmit(this); return false;">
<label for="alertSelect">警报类型:</label>
<input name="alertSelect" id="alertSelect" type="text" value="事件" /><br><br>
<label for="alertSubject">警报主题:</label>
<input name="alertSubject" id="alertSubject" type="text" value="系统维护通知" /><br><br>
<label for="imageUpload">上传图片:</label>
<input name="myFile" id="imageUpload" type="file" /><br><br>
<input type="submit" value="提交表单" />
</form>
<div id="status"></div>
<script>
function handleFormSubmit(formObject) {
document.getElementById('status').innerText = '正在提交...';
google.script.run
.withSuccessHandler(updateStatus)
.withFailureHandler(showError)
.processForm(formObject);
}
function updateStatus(fileUrl) {
document.getElementById('status').innerText = '文件上传成功，链接：' + fileUrl;
document.getElementById('myForm').reset(); // 清空表单
}
function showError(error) {
document.getElementById('status').innerText = '提交失败: ' + error.message;
console.error(error);
}
</script>
</body>
</html>后端 Google Apps Script (Code.gs) 处理
在服务器端，您可以通过 formObject 参数直接访问表单字段。文件输入字段的值将是一个 Blob 对象。
/**
* 接收前端提交的表单对象，处理文件和文本数据。
* @param {Object} formObject 包含表单字段和文件 Blob 的对象。
* @returns {string} 上传文件的 Google Drive URL。
*/
function processForm(formObject) {
// 访问文本字段
var alertType = formObject.alertSelect;
var alertSubject = formObject.alertSubject;
Logger.log('警报类型: ' + alertType);
Logger.log('警报主题: ' + alertSubject);
// 访问文件 Blob
var fileBlob = formObject.myFile;
if (fileBlob && fileBlob.getName()) { // 检查文件是否存在
try {
// 使用 DriveApp.createFile() 将 Blob 保存到 Google Drive
var driveFile = DriveApp.createFile(fileBlob);
Logger.log('文件 "' + driveFile.getName() + '" 已上传到 Google Drive，ID: ' + driveFile.getId());
// 返回文件 URL 或 ID
return driveFile.getUrl();
} catch (e) {
Logger.log('文件上传失败: ' + e.message);
throw new Error('文件上传失败: ' + e.message);
}
} else {
Logger.log('未上传文件。');
return '未上传文件。';
}
}优点与局限
- 优点： 实现简单，无需手动处理 FormData 或 OAuth 令牌，适合单个文件或少量文件的简单上传场景。
- 局限： 对于多文件上传、需要指定上传文件夹、或者需要更细粒度控制上传过程（如进度条、分块上传）的场景，此方法可能不够灵活。同时，所有非文件字段都会被转换为字符串，如果需要保持原始数据类型（如数字、布尔值），需要在后端进行额外的类型转换。
策略二：客户端通过 Drive API 预先上传文件至 Google Drive
当需要处理多个文件、精确控制文件上传到 Google Drive 的目标文件夹，或者需要更灵活的上传流程时，可以在客户端（前端）直接调用 Google Drive API 进行文件上传。这种方法涉及到在前端获取 Apps Script 的 OAuth 令牌，并使用 fetch API 向 Drive API 发送请求。文件上传成功后，将返回的文件 ID 传递给 Apps Script 后端进行后续处理。
原理阐述
- 获取 OAuth 令牌： Apps Script 后端通过 ScriptApp.getOAuthToken() 获取当前用户的访问令牌，并将其传递给前端 HTML 模板。
- 前端上传文件： 前端 JavaScript 使用 fetch API，构造 multipart/form-data 请求，将文件数据连同元数据（如文件名、父文件夹ID）发送到 Google Drive API 的 /upload/drive/v3/files 端点。请求头中需包含 Authorization: Bearer <OAuth Token>。
- 传递文件 ID： 文件上传成功后，Drive API 返回的文件 ID 会被收集起来，然后作为表单数据的一部分，通过 google.script.run 传递给 Apps Script 后端。
- 后端处理： 后端接收到文件 ID 后，可以使用 DriveApp.getFileById() 访问这些文件，并进行进一步操作（如将其链接保存到 Google Sheet，或作为附件发送邮件）。
前端获取 OAuth 令牌 (Code.gs)
您需要在 doGet() 函数中将 OAuth 令牌传递给 HTML 模板。
/**
* 处理 GET 请求，渲染 HTML 模板并注入 OAuth 令牌。
* @param {Object} e 事件对象。
* @returns {HtmlOutput} 渲染后的 HTML 内容。
*/
function doGet(e) {
var htmlTemplate = HtmlService.createTemplateFromFile('index.html');
// 注入 OAuth 令牌，前端将使用此令牌调用 Drive API
htmlTemplate.dataFromServerTemplate = { OAuthToken : ScriptApp.getOAuthToken() };
return htmlTemplate.evaluate();
}前端 JavaScript (index.html)
前端代码将负责遍历选定的文件，为每个文件调用 Drive API 进行上传，并收集返回的文件 ID。
<!DOCTYPE html>
<html>
<head>
<base target="_top">
</head>
<body>
<form id="myForm">
<label for="alertSelect">警报类型:</label>
<input name="alertSelect" id="alertSelect" type="text" value="事件" /><br><br>
<label for="alertSubject">警报主题:</label>
<input name="alertSubject" id="alertSubject" type="text" value="系统维护通知" /><br><br>
<label for="imageUpload">上传图片:</label>
<input name="imageUpload" id="imageUpload" type="file" multiple /><br><br> <!-- 允许多文件上传 -->
<button type="button" onclick="saveAlertWithFiles()">提交表单 (带文件)</button>
</form>
<div id="status"></div>
<script>
// 假设 data 变量已通过模板注入 OAuthToken
var data = <?!= JSON.stringify(dataFromServerTemplate) ?>;
async function saveAlertWithFiles() {
document.getElementById('status').innerText = '正在上传文件...';
let fileInput = document.getElementById("imageUpload");
let accessToken = data.OAuthToken;
// 替换为您的 Google Drive 目标文件夹 ID (可选)
let folderId = "YOUR_GOOGLE_DRIVE_FOLDER_ID";
let imageIds = [];
if (fileInput.files.length > 0) {
for (let i = 0; i < fileInput.files.length; i++) {
let file = fileInput.files[i];
let formData = new FormData();
// 构建文件元数据，包括文件名和目标文件夹
formData.append('metadata', new Blob([JSON.stringify({
name: file.name,
// 如果指定了文件夹ID，则上传到该文件夹
parents: folderId ? [folderId] : []
})], { type: 'application/json' }));
formData.append('file', file); // 文件的二进制数据
try {
let response = await fetch('https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart', {
method: 'POST',
headers: { 'Authorization': `Bearer ${accessToken}` },
body: formData
});
let result = await response.json();
if (result.id) {
imageIds.push(result.id);
console.log(`文件 "${file.name}" 上传成功，ID: ${result.id}`);
} else {
console.error(`文件 "${file.name}" 上传失败:`, result);
document.getElementById('status').innerText = `文件 "${file.name}" 上传失败。`;
return; // 遇到错误停止
}
} catch (error) {
console.error(`上传文件 "${file.name}" 时发生错误:`, error);
document.getElementById('status').innerText = `上传文件 "${file.name}" 时发生错误。`;
return; // 遇到错误停止
}
}
}
document.getElementById('status').innerText = '文件上传完成，正在提交表单数据...';
// 构建其他表单数据，并将 imageIds 包含进去
let record = {
'Alert Type': document.getElementById('alertSelect').value,
'Alert Subject': document.getElementById('alertSubject').value,
'Images': imageIds, // 传递文件ID数组
'Alert Active': true
};
let out = [record]; // 按照原始问题中的数据结构
// 将 record 传递给后端
google.script.run
.withSuccessHandler(clearForm)
.withFailureHandler(showError)
.saveAlerts(out);
}
function clearForm() {
document.getElementById('status').innerText = '表单提交成功！';
document.getElementById('myForm').reset();
}
function showError(error) {
document.getElementById('status').innerText = '表单提交失败: ' + error.message;
console.error(error);
}
</script>
</body>
</html>后端 Google Apps Script (Code.gs) 处理
后端函数将接收一个包含文件 ID 数组的数据对象。您可以使用这些 ID 来检索文件，并进行后续操作。
/**
* 接收前端提交的表单数据和文件ID数组。
* @param {Array<Object>} data 包含表单字段和文件ID数组的对象。
*/
function saveAlerts(data) {
Logger.log('接收到的数据: ' + JSON.stringify(data));
if (!data || data.length === 0) {
throw new Error("未接收到任何数据。");
}
let record = data[0]; // 假设只处理第一个记录
let alertType = record['Alert Type'];
let alertSubject = record['Alert Subject'];
let imageIds = record['Images']; // 获取文件ID数组
// 示例：将数据保存到 Google Sheet (假设 alerts 是一个 Spreadsheet 对象)
// var alerts = SpreadsheetApp.getActive 
