本文详细介绍了在google apps script web应用中，客户端javascript如何与服务器端脚本进行高效且正确的数据交互。重点阐述了`google.script.run`的异步特性及其`withsuccesshandler`回调机制，纠正了常见的同步调用误区，并提供了优化后的客户端代码示例，确保数据能够从服务器端正确传递并被客户端处理。
理解Google Apps Script的客户端-服务器通信机制
在Google Apps Script开发的Web应用中，客户端（HTML页面中的JavaScript）与服务器端（.gs文件中的Apps Script代码）之间的通信是一个核心概念。客户端无法直接访问服务器端变量或同步执行服务器端函数并获取返回值，因为这种交互是异步的。
google.script.run是客户端JavaScript调用服务器端Apps Script函数的关键接口。然而，许多开发者初次使用时常会遇到一个误区：试图像调用普通JavaScript函数一样，直接从google.script.run表达式中获取返回值。
核心要点：
- 异步执行： google.script.run调用服务器端函数后会立即返回，它本身不返回任何值。服务器端函数的实际结果会在稍后通过回调函数传递回来。
- 回调机制： 要获取服务器端函数的执行结果，必须使用withSuccessHandler(callbackFunction)方法。callbackFunction是一个客户端JavaScript函数，当服务器端函数成功执行并返回数据时，这些数据将作为参数传递给callbackFunction。
- 函数范围： google.script.run只能调用服务器端（.gs文件）中定义的全局函数。它不能调用客户端（HTML文件）中定义的JavaScript函数。
常见错误分析
在提供的代码示例中，存在两个主要问题导致“getdatafromserver() is not a function”错误或无法正确传递变量：
-
尝试通过google.script.run调用客户端函数： 原始代码片段：
document.getElementById('btn_btn1').addEventListener('click', async function test(){ await google.script.run.withSuccessHandler(showData).getdatafromserver() })这里尝试通过google.script.run调用名为getdatafromserver()的函数。然而，getdatafromserver()是一个在Index.html中定义的客户端JavaScript函数，而不是在Code.gs中定义的服务器端函数。google.script.run只能调用服务器端函数，因此会报错。
-
误解google.script.run的返回值： 原始代码片段：
function getdatafromserver(){ temp = id_input.value var array1 = google.script.run.withSuccessHandler(data =>{ datatable1 = data }).get_range_by_id(temp) return datatable1 // 此时 datatable1 可能尚未被赋值 }在这个客户端函数中，google.script.run.withSuccessHandler(...).get_range_by_id(temp)是一个异步操作。当return datatable1执行时，服务器端函数可能还没有执行完毕，data也还没有传递给withSuccessHandler的回调函数，因此datatable1可能仍是未定义或旧值。google.script.run本身并不返回服务器端函数的结果。
正确的数据传递与异步处理
要正确实现从客户端获取用户输入（如ID），发送到服务器端处理，并将处理结果返回客户端显示，应遵循以下模式：
- 客户端获取输入并触发服务器调用： 创建一个客户端函数，负责获取用户输入，然后使用google.script.run.withSuccessHandler()调用服务器端函数。
- 服务器端处理请求并返回数据： 服务器端函数接收客户端参数，执行业务逻辑（如查询Google Sheet），然后返回数据。
- 客户端回调函数处理结果： withSuccessHandler指定的回调函数接收服务器端返回的数据，并更新HTML页面。
优化后的客户端代码示例
根据上述原则，对Index.html中的JavaScript代码进行如下修改：
<script>
/**
* 客户端函数：获取用户输入的ID，并调用服务器端函数获取数据。
*/
function getAndDisplayDataFromServer() {
var id_input_element = document.getElementById('id1');
var input_id_value = id_input_element.value;
// 使用 google.script.run 调用服务器端函数 get_range_by_id
// 并指定 showData 作为成功回调函数，处理服务器返回的数据
google.script.run.withSuccessHandler(showData).get_range_by_id(input_id_value);
}
/**
* 客户端回调函数：接收服务器端返回的数据数组，并将其渲染到DataTable。
* @param {Array} dataArray 从服务器端获取的数据数组
*/
function showData(dataArray) {
$(document).ready(function () {
// 检查DataTable是否已初始化，如果已初始化则销毁以避免重复初始化错误
if ($.fn.DataTable.isDataTable('#data-table')) {
$('#data-table').DataTable().destroy();
}
$('#data-table').DataTable({
data: dataArray,
columns: [
{ "title": "ID" },
{ "title": "Rating" },
{ "title": "Reviews" },
{ "title": "Book title" },
{ "title": "Number of Pages" },
{ "title": "Type" },
{ "title": "Price" }
]
});
});
}
// 绑定按钮点击事件到 getAndDisplayDataFromServer 函数
document.getElementById('btn_btn1').addEventListener('click', getAndDisplayDataFromServer);
</script>修改说明：
- 移除了原先的getdatafromserver()函数，因为其逻辑被整合到了getAndDisplayDataFromServer()中，并且更重要的是，避免了通过google.script.run调用客户端函数。
- document.getElementById('btn_btn1').addEventListener('click', getAndDisplayDataFromServer);：当按钮被点击时，直接调用getAndDisplayDataFromServer这个客户端函数。
- 在getAndDisplayDataFromServer函数中，直接使用google.script.run.withSuccessHandler(showData).get_range_by_id(input_id_value);来调用服务器端的get_range_by_id函数，并将showData指定为成功回调函数。这样，get_range_by_id执行完毕后返回的数据会自动作为参数传递给showData。
- showData函数现在专门负责接收服务器返回的数据并更新表格，它的调用完全由withSuccessHandler管理。
- 在showData中增加了对DataTable是否已初始化的判断和销毁逻辑，以确保在多次点击按钮更新数据时，DataTable能够正确重新渲染，避免“Cannot reinitialise DataTable”的错误。
服务器端代码（Code.gs）保持不变
服务器端代码（Code.gs）中的函数，如get_range_by_id(id1)，其逻辑是正确的，它负责根据传入的ID从Google Sheet中获取相应的数据行并返回。这些函数是google.script.run可以调用的目标。
// ... (之前的 getData, read_id, include 函数) ...
function find_id(id1){
var list_index = []
var id_array = read_id()
for(i = 1; i<= id_array.length;i++){
if(id1 == id_array[i]){
list_index.push(i)
}
}
if(list_index.length > 0){
return list_index.at(-1)
}else{
return "ID isn't existed"
}
}
function get_range_by_id(id1){
var row_num = find_id(id1)
// 确保 row_num 是有效数字，并且 getData() 返回的是一个二维数组
if (typeof row_num === 'number' && row_num >= 0) {
var all_data = getData();
if (all_data && row_num < all_data.length) {
return [all_data[row_num]]; // 返回一个包含目标行的二维数组
}
}
return []; // 如果找不到或发生错误，返回空数组
}注意： 服务器端get_range_by_id函数中，getData()[row_num]可能返回一个单行数组，但DataTable通常期望一个二维数组（行数组的数组）。因此，[getData()[row_num]]的写法是正确的，它将单行数据封装成一个包含一个元素的二维数组。同时，增加了对row_num有效性的检查，以提高健壮性。
部署注意事项
当您修改了Google Apps Script项目的代码（无论是.gs文件还是HTML文件），特别是作为Web应用部署时，请务必部署一个新的版本。仅仅保存代码不足以让Web应用反映最新的更改。
部署新版本步骤：
- 在Apps Script编辑器中，点击右上角的“部署”按钮。
- 选择“管理部署”。
- 点击当前部署旁边的铅笔图标（编辑部署）。
- 在“版本”下拉菜单中选择“新建版本”。
- 点击“部署”。
通过部署新版本，确保您的Web应用始终运行最新且正确的代码。
总结
掌握google.script.run的异步特性和withSuccessHandler回调机制是构建健壮Google Apps Script Web应用的关键。通过将客户端操作和服务器端逻辑清晰分离，并利用回调函数处理异步结果，可以有效地实现客户端与服务器端之间的数据交互，提升应用的响应性和用户体验。
