Google Apps Script 的 Evaluate() 函式：全面新手指南
更新日期： 2023 年 10 月 24 日
Google Apps Script 提供了眾多的功能，其中之一便是 evaluate() 函數。
這個函數雖然在許多情況下都極為實用，但卻往往容易被忽視。
透過本文，我們將帶領大家一同深入了解 evaluate() 函數的運作方式，包括它的基本概念、如何使用、以及實際應用等範疇。
什麼是 evaluate() 函數？
在 Google Apps Script 中，evaluate() 是 HtmlService 物件的一個方法。
當我們需要將 Apps Script（這是伺服器端腳本）中的資訊，傳遞給在瀏覽器（用戶端）上運行的網頁時，這個方法就派上用場了。
這個方法可以讓你的 Apps Script 代碼生成一個 HTML 回應，然後將這個回應傳送到客戶端，也就是瀏覽器。
比如說，我們可能會將從 Google Drive、Google 表單、或是其他 Google 應用程式取得的資料，並透過 evaluate() 方法，傳遞到用戶端的網頁中。
當我們調用 evaluate() 方法時，它會返回一個 HtmlOutput 物件。
這個物件包含了 Apps Script 程式所生成的 HTML 內容，並將該 HtmlOutput 物件回傳到用戶端的網頁中。
通常，evaluate() 方法通常會和 HtmlService 物件的 createTemplateFromFile() 方法一起使用。
createTemplateFromFile() 方法會從我們指定的 HTML 文件中創建一個「模板」，然後我們可以用 evaluate() 方法來將這個模板轉換成 HtmlOutput 物件，最後將這個物件回傳到用戶端。
補充：createTemplateFromFile() 函數的功能是什麼？
在 Google Apps Script 中，createTemplateFromFile(filename) 是一個方法。
它會從指定的 HTML 檔案，建立一個新的 HTML 模板。這個方法返回一個 HtmlTemplate 物件。
HtmlTemplate 物件是 Google Apps Script 中的一種特殊物件，它讓你可以在 HTML 檔案中插入 Apps Script 變數。
例如，你可以在 HTML 文件中使用 <?= variable ?> 來插入一個 Apps Script 的變數，或者使用 <? function() ?> 來呼叫一個 Apps Script 的函數。
例如：
<!DOCTYPE html>
<html>
<head>
<base target="_top">
</head>
<body>
Hello, <?= name ?>!
</body>
</html>在這個例子中，<?= name ?> 將會被替換為 HtmlTemplate 物件的 name 屬性。
在 Apps Script 中，你可以這樣操作：
let template = HtmlService.createTemplateFromFile('myTemplate');
template.name = "World";
let htmlOutput = template.evaluate().getContent();
Logger.log(htmlOutput); // Logs: Hello, World!在這個例子中，htmlOutput 將包含經過 HtmlTemplate 物件求值後的 HTML 內容。
如何使用 evaluate() 函數
這裡有一個簡單的使用 evaluate() 的範例。
假設我們想要在一個稱為 Page.html 的網頁上，顯示當前的日期。
我們可以在伺服器端的 Apps Script 中創建一個函數來獲取當前的日期，並使用 evaluate() 函數將這個資訊傳遞到用戶端：
function doGet() {
let template = HtmlService.createTemplateFromFile('Page');
template.date = new Date();
return template.evaluate();
}在這個範例中，我們首先使用 HtmlService.createTemplateFromFile() 方法創建了一個 HTML 模板。
然後，我們在該模板物件上增加了一個名為 date 的成員，並將其設定為當前的日期。
補充：點記法
在 JavaScript（包括 Google Apps Script）中，物件的成員可以使用點表示法（.）來訪問和賦值。
如果你想要新增物件的成員，你可以直接使用點表示法來設置它。這是一個常見的操作，不需要特殊的語法或函數。
下面是一個範例，演示了如何創建一個空物件，然後使用點表示法來新增和訪問成員：
let myObject = {}; // 創建一個空物件
// 使用點表示法來新增和設置成員
myObject.name = "John";
myObject.age = 30;
// 使用點表示法來訪問成員
var name = myObject.name; // 結果是 "John"
var age = myObject.age; // 結果是 30你也可以使用方括號表示法來新增和訪問成員。這尤其有用當屬性名稱包括空格或其他非法字符時：
myObject["first name"] = "John";
var firstName = myObject["first name"]; // 結果是 "John"在 Page.html 頁面中，我們可以使用 <?= date ?> 語法來顯示傳遞的日期：
<!DOCTYPE html>
<html>
<body>
<h1>Today's date is <?= date ?></h1>
</body>
</html>在這個 HTML 文件中，<?= date ?> 是一個樣板變數，當 evaluate() 方法執行時，它將被替換為 date 成員的值，也就是我們在 doGet() 函數中設定的當前日期。
最後，我們使用 evaluate() 方法將這個模板求值為一個 HtmlOutput 物件，並返回給用戶端。
evaluate() 函數的進階實例解析
以下，我們將更深入地探討 evaluate() 函數的使用，並提供一些實例來說明其應用。
一個常見的 evaluate() 函數使用場景，是將服務器端的 Apps Script 資訊傳遞給用戶端的 HTML，如上一節的範例所示。
下面是一個更複雜的範例，其中我們從 Google 雲端硬碟中讀取文件，並將其內容顯示在用戶端的頁面上：
// 伺服器端代碼
function doGet() {
let template = HtmlService.createTemplateFromFile('Page');
let fileId = 'INSERT_FILE_ID_HERE'; // 請將這裡換成實際的 Google 雲端硬碟文件 ID
let doc = DocumentApp.openById(fileId);
let content = doc.getBody().getText();
template.content = content;
return template.evaluate();
}<!-- 用戶端代碼 (Page.html) -->
<!DOCTYPE html>
<html>
<body>
<p><?= content ?></p>
</body>
</html>在此範例中，我們首先從服務器端的 Apps Script 中，讀取一個 Google 雲端硬碟中的文件，並將文件的內容做為一個字串。
之後，我們將這個字串指派給 HTML 模板的 content 屬性。在用戶端的 HTML 中，我們使用 <?= content ?> 來顯示這個字串。
注意在實際應用中，你需要將 'INSERT_FILE_ID_HERE' 替換為你想要讀取的 Google 雲端硬碟文件的 ID。。
補充：如何取得文件 ID
當您在 Google Drive 打開一個文件，例如 Google 文件，URL 通常看起來像這樣：
https://docs.google.com/document/d/1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R9S0T1U2V/edit其中，1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R9S0T1U2V 部分就是文件的 ID。在這個例子中，您需要將上述代碼中的 'INSERT_FILE_ID_HERE' 替換為這個 ID。
請注意，這個 ID 是隨機生成的，所以每個文件的 ID 都是唯一的。您必須用您想讀取的實際文件的 ID 替換它。
此實例顯示了 evaluate() 函數的強大之處，它可以讓我們在用戶端的頁面中，顯示來自服務器端的任意資訊。
在接下來的章節中，我們將進一步討論如何優化這個過程，並避免一些常見的問題。
evaluate() 函數的常見問題與解答
當你使用 evaluate() 函數時，可能會遇到一些常見的問題。在這個章節裡，我們會講解這些問題並給出相應的解決方案。
執行 evaluate() 時，出現了「當前服務不支援指定的 Content-Type」的錯誤
當你使用 evaluate() 函數返回一個 HtmlOutput 物件時。
你必須確保你的 HTML、CSS 和 JavaScript 的內容都是有效的。
如果你在服務器端的 Apps Script 中包含了不被支援的內容，例如二進位的數據或非文本內容，則可能會出現此問題。
請檢查你的程式碼以確保你只在 HtmlOutput 中包含被支援的內容。
使用 evaluate() 函數返回的內容，並未如預期般在用戶端顯示
確保你的 HTML 文件有正確地接收和顯示從 evaluate() 函數返回的數據。
如果你在 JavaScript 中使用的變數或函數，與 Apps Script 的變數或函數名稱相同，可能會產生衝突。
請確保你的變數和函數名稱是獨一無二的，並且沒有與 Apps Script 的名稱產生衝突。
無法正確地讀取從 evaluate() 函數返回的資料
如果你發現無法讀取從 evaluate() 函數返回的資料，可能是因為你的資料包含特殊的字符或格式。
當你從 Apps Script 傳送資料到用戶端時，所有的資料都將被轉換為字串。
如果你的資料包含複雜的結構，例如物件或陣列，你需要在傳送之前將它們轉換為字串，然後在用戶端再將它們轉換回原來的格式。
你可以使用 JSON.stringify() 和 JSON.parse() 來實現這個過程。
以上就是在使用 evaluate() 函數時可能會遇到的一些常見問題和解決方案。
記得，總是確保你的 Apps Script 和 HTML 內容都是正確且有效的，並且適應 evaluate() 函數的要求和限制。
結語
透過本文的教學與討論，你已經初步了解了 Google Apps Script 的 evaluate() 函數的基礎知識、使用方法、以及一些實例解析。
evaluate() 函數擁有強大的功能，可以讓你在用戶端和服務器端之間有效地傳遞和操作數據。
然而，要充分利用這個函數的能力，我們需要對其工作原理有一定的理解，並能夠解決在使用過程中可能遇到的問題。
感謝你的閱讀，希望這篇文章對你的學習和工作有所幫助。
參考資源
Google Apps Script 官方文檔
官方文檔是最準確且最新的資訊來源。在這裡，你可以找到 evaluate() 函數以及其他 Apps Script 方法和物件的詳細介紹。
Google Apps Script 網頁應用程式
這篇文章是關於如何使用 evaluate() 函數來返回 HTML 的輸出的詳細。
Stack Overflow
Stack Overflow 是一個程式設計問題和解答的社區。在這裡，你可以找到很多關於 Apps Script 的實際問題和專業解答。
Apps Script Fundamentals
這是一系列的教學影片，涵蓋了 Apps Script 的基礎知識，包括 evaluate() 函數。
希望這些資源，能夠幫助你對 Google Apps Script 的 evaluate() 函數有更深入的理解和應用。
在學習的過程中，如果有任何問題或困惑，記得多利用這些資源尋求解答。