您可以混合使用 Apps 脚本代码和 HTML,以最低的努力即可生成动态网页。如果您使用过混合使用代码和 HTML 的模板语言(例如 PHP、ASP 或 JSP),应该会对该语法感到熟悉。
脚本
Apps Script 模板可以包含三个特殊标记,称为脚本段。在脚本中,您可以编写在普通 Apps 脚本文件中可正常运行的任何代码:脚本可以调用其他代码文件中定义的函数、引用全局变量或使用任何 Apps 脚本 API。您甚至可以在脚本中定义函数和变量,但需要注意的是,代码文件或其他模板中定义的函数无法调用这些函数和变量。
如果您将以下示例粘贴到脚本编辑器中,<?= ... ?>
标记(打印脚本)的内容将以斜体显示。该斜体代码会在将网页提供给用户之前在服务器上运行。由于脚本代码会在网页提交之前执行,因此每个网页只能运行一次;与您通过 google.script.run
调用的客户端 JavaScript 或 Apps Script 函数不同,脚本无法在网页加载后再次执行。
Code.gs
function doGet() {
return HtmlService
.createTemplateFromFile('Index')
.evaluate();
}
Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
</head>
<body>
Hello, World! The time is <?= new Date() ?>.
</body>
</html>
请注意,适用于模板化 HTML 的 doGet()
函数不同于创建和分发基本 HTML 中的示例。此处显示的函数会从 HTML 文件生成 HtmlTemplate
对象,然后调用其 evaluate()
方法来执行脚本片段,并将模板转换为脚本可向用户提供的 HtmlOutput
对象。
标准脚本
标准脚本片段使用语法 <? ... ?>
,可执行代码,而无需将内容明确输出到网页。不过,如以下示例所示,脚本段中代码的结果仍可能会影响脚本段外的 HTML 内容:
Code.gs
function doGet() {
return HtmlService
.createTemplateFromFile('Index')
.evaluate();
}
Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
</head>
<body>
<? if (true) { ?>
<p>This will always be served!</p>
<? } else { ?>
<p>This will never be served.</p>
<? } ?>
</body>
</html>
打印脚本
使用语法 <?= ... ?>
的输出脚本会使用上下文转义将其代码的结果输出到网页中。
上下文转义是指 Apps Script 会跟踪页面上输出的上下文(HTML 属性内、客户端 script
标记内或其他任何位置),并自动添加转义字符,以防范跨站点脚本攻击 (XSS)。
在此示例中,第一个输出脚本会直接输出字符串;紧随其后的是用于设置数组和循环的标准脚本,最后是用于输出数组内容的另一个输出脚本。
Code.gs
function doGet() {
return HtmlService
.createTemplateFromFile('Index')
.evaluate();
}
Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
</head>
<body>
<?= 'My favorite Google products:' ?>
<? var data = ['Gmail', 'Docs', 'Android'];
for (var i = 0; i < data.length; i++) { ?>
<b><?= data[i] ?></b>
<? } ?>
</body>
</html>
请注意,打印脚本只会输出其第一个语句的值;所有其余语句的行为就像包含在标准脚本中一样。例如,脚本 <?= 'Hello, world!'; 'abc' ?>
只会输出“Hello, world!”
强制打印脚本
强制输出脚本(使用语法 <?!= ... ?>
)与输出脚本类似,但它们会避免上下文转义。
如果您的脚本允许不受信任的用户输入,则上下文转义非常重要。与之相反,如果脚本的输出有意包含您希望按指定方式精确插入的 HTML 或脚本,则需要强制输出。
一般而言,除非您知道需要按原样打印 HTML 或 JavaScript,否则请使用打印脚本,而不是强制打印脚本。
脚本中的 Apps 脚本代码
脚本片段不仅可以运行常规 JavaScript;您还可以使用以下三种方法中的任意一种,让模板访问 Apps Script 数据。
不过,请注意,由于模板代码会在向用户提供网页之前执行,因此这些方法只能向网页提取初始内容。如需以互动方式从网页访问 Apps 脚本数据,请改用 google.script.run
API。
从模板调用 Apps 脚本函数
脚本片段可以调用在 Apps 脚本代码文件或库中定义的任何函数。此示例展示了一种将数据从电子表格拉取到模板中,然后根据数据构建 HTML 表格的方法。
Code.gs
function doGet() {
return HtmlService
.createTemplateFromFile('Index')
.evaluate();
}
function getData() {
return SpreadsheetApp
.openById('1234567890abcdefghijklmnopqrstuvwxyz')
.getActiveSheet()
.getDataRange()
.getValues();
}
Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
</head>
<body>
<? var data = getData(); ?>
<table>
<? for (var i = 0; i < data.length; i++) { ?>
<tr>
<? for (var j = 0; j < data[i].length; j++) { ?>
<td><?= data[i][j] ?></td>
<? } ?>
</tr>
<? } ?>
</table>
</body>
</html>
直接调用 Apps 脚本 API
您还可以在脚本中直接使用 Apps 脚本代码。此示例通过在模板本身(而不是通过单独的函数)中加载数据,实现了与上一个示例相同的结果。
Code.gs
function doGet() {
return HtmlService
.createTemplateFromFile('Index')
.evaluate();
}
Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
</head>
<body>
<? var data = SpreadsheetApp
.openById('1234567890abcdefghijklmnopqrstuvwxyz')
.getActiveSheet()
.getDataRange()
.getValues(); ?>
<table>
<? for (var i = 0; i < data.length; i++) { ?>
<tr>
<? for (var j = 0; j < data[i].length; j++) { ?>
<td><?= data[i][j] ?></td>
<? } ?>
</tr>
<? } ?>
</table>
</body>
</html>
将变量推送到模板
最后,您可以将变量作为 HtmlTemplate
对象的属性分配给模板,从而将变量推送到模板中。同样,此示例会产生与前面的示例相同的结果。
Code.gs
function doGet() {
var t = HtmlService.createTemplateFromFile('Index');
t.data = SpreadsheetApp
.openById('1234567890abcdefghijklmnopqrstuvwxyz')
.getActiveSheet()
.getDataRange()
.getValues();
return t.evaluate();
}
Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
</head>
<body>
<table>
<? for (var i = 0; i < data.length; i++) { ?>
<tr>
<? for (var j = 0; j < data[i].length; j++) { ?>
<td><?= data[i][j] ?></td>
<? } ?>
</tr>
<? } ?>
</table>
</body>
</html>
调试模板
模板可能很难调试,因为系统不会直接执行您编写的代码;而是由服务器将模板转换为代码,然后执行生成的代码。
如果您不清楚模板如何解读脚本,HtmlTemplate
类中的两个调试方法可以帮助您更好地了解具体情况。
getCode()
getCode()
会返回一个字符串,其中包含服务器根据模板创建的代码。如果您记录代码,然后将其粘贴到脚本编辑器中,就可以像正常的 Apps 脚本代码一样运行和调试它。
下面的简单模板再次显示 Google 产品列表,后跟 getCode()
的结果:
Code.gs
function myFunction() {
Logger.log(HtmlService
.createTemplateFromFile('Index')
.getCode());
}
Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
</head>
<body>
<?= 'My favorite Google products:' ?>
<? var data = ['Gmail', 'Docs', 'Android'];
for (var i = 0; i < data.length; i++) { ?>
<b><?= data[i] ?></b>
<? } ?>
</body>
</html>
LOG(已评估)
(function() { var output = HtmlService.initTemplate(); output._ = '<!DOCTYPE html>\n';
output._ = '<html>\n' +
' <head>\n' +
' <base target=\"_top\">\n' +
' </head>\n' +
' <body>\n' +
' '; output._$ = 'My favorite Google products:' ;
output._ = ' '; var data = ['Gmail', 'Docs', 'Android'];
for (var i = 0; i < data.length; i++) { ;
output._ = ' <b>'; output._$ = data[i] ; output._ = '</b>\n';
output._ = ' '; } ;
output._ = ' </body>\n';
output._ = '</html>';
/* End of user code */
return output.$out.append('');
})();
getCodeWithComments()
getCodeWithComments()
与 getCode()
类似,但会将经过评估的代码作为与原始模板并排显示的注释返回。
浏览已评估的代码
在任何经过评估的代码示例中,您首先会注意到方法 HtmlService.initTemplate()
创建的隐式 output
对象。此方法未记录,因为只有模板本身需要使用它。output
是一个特殊的 HtmlOutput
对象,具有两个命名方式不寻常的属性:_
和 _$
,它们是调用 append()
和 appendUntrusted()
的简写形式。
output
还有一个特殊属性 $out
,它是指不具有这些特殊属性的常规 HtmlOutput
对象。模板会在代码末尾返回该普通对象。
现在,您已经了解了此语法,其余代码应该很容易理解。脚本之外的 HTML 内容(例如 b
标记)使用 output._ =
附加(不进行上下文转义),脚本则作为 JavaScript 附加(是否进行上下文转义取决于脚本的类型)。
请注意,经过求值的代码会保留模板中的行号。如果您在运行经过评估的代码时收到错误消息,该行将与模板中的等效内容相对应。
评论层次结构
由于已评估的代码会保留行号,因此脚本中的内容可以用来注释其他脚本,甚至 HTML 代码。以下示例展示了注释的一些意想不到的效果:
<? var x; // a comment ?> This sentence won't print because a comment begins inside a scriptlet on the same line. <? var y; // ?> <?= "This sentence won't print because a comment begins inside a scriptlet on the same line."; output.append("This sentence will print because it's on the next line, even though it's in the same scriptlet.”) ?> <? doSomething(); /* ?> This entire block is commented out, even if you add a */ in the HTML or in a <script> */ </script> tag, <? until you end the comment inside a scriptlet. */ ?>