绑定到 Google 文档、表格或表单的脚本可以显示多种类型的界面元素,包括预构建的提醒和提示,以及包含自定义 HTML 服务页面的对话框和边栏。通常情况下,这些元素可通过菜单项打开。(请注意,在 Google 表单中,界面元素仅对打开表单进行修改的用户可见,而对打开表单进行回复的用户不可见。)
提醒对话框
提醒是在 Google 文档、表格、幻灯片或表单编辑器中打开的预构建对话框。它会显示一条消息和一个“确定”按钮;标题和备用按钮是可选的。这类似于在网络浏览器内的客户端 JavaScript 中调用 window.alert()
。
当对话框打开时,提醒会暂停服务器端脚本。脚本在用户关闭对话框后恢复,但 JDBC 连接在暂停期间不会保留。
如下例所示,Google 文档、表单、幻灯片和表格都使用 Ui.alert()
方法,该方法提供三种变体。如需替换默认的“OK”按钮,请将 Ui.ButtonSet
枚举中的值作为 buttons
参数传递。如需评估用户点击的是哪个按钮,请将 alert()
的返回值与 Ui.Button
枚举进行比较。
function onOpen() {
SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
.createMenu('Custom Menu')
.addItem('Show alert', 'showAlert')
.addToUi();
}
function showAlert() {
var ui = SpreadsheetApp.getUi(); // Same variations.
var result = ui.alert(
'Please confirm',
'Are you sure you want to continue?',
ui.ButtonSet.YES_NO);
// Process the user's response.
if (result == ui.Button.YES) {
// User clicked "Yes".
ui.alert('Confirmation received.');
} else {
// User clicked "No" or X in the title bar.
ui.alert('Permission denied.');
}
}
提示对话框
提示是在 Google 文档、表格、幻灯片或表单编辑器中打开的预构建对话框。它会显示一条消息、一个文本输入字段和一个“确定”按钮;标题和备用按钮是可选的。这类似于在网络浏览器内的客户端 JavaScript 中调用 window.prompt()
。
在对话框打开时提示暂停服务器端脚本。脚本在用户关闭对话框后恢复,但 JDBC 连接在暂停期间不会保留。
如下例所示,Google 文档、表单、幻灯片和表格都使用 Ui.prompt()
方法,该方法有三种变体。如需替换默认的“确定”按钮,请将 Ui.ButtonSet
枚举中的值作为 buttons
参数传递。如需评估用户的响应,请捕获 prompt()
的返回值,然后调用 PromptResponse.getResponseText()
来检索用户的输入,并将 PromptResponse.getSelectedButton()
的返回值与 Ui.Button
枚举进行比较。
function onOpen() {
SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp.
.createMenu('Custom Menu')
.addItem('Show prompt', 'showPrompt')
.addToUi();
}
function showPrompt() {
var ui = SpreadsheetApp.getUi(); // Same variations.
var result = ui.prompt(
'Let\'s get to know each other!',
'Please enter your name:',
ui.ButtonSet.OK_CANCEL);
// Process the user's response.
var button = result.getSelectedButton();
var text = result.getResponseText();
if (button == ui.Button.OK) {
// User clicked "OK".
ui.alert('Your name is ' + text + '.');
} else if (button == ui.Button.CANCEL) {
// User clicked "Cancel".
ui.alert('I didn\'t get your name.');
} else if (button == ui.Button.CLOSE) {
// User clicked X in the title bar.
ui.alert('You closed the dialog.');
}
}
自定义对话框
自定义对话框可以在 Google 文档、表格、幻灯片或表单编辑器中显示 HTML 服务界面。
自定义对话框打开时不会暂停服务器端脚本。
客户端组件可以使用适用于 HTML 服务接口的 google.script
API 对服务器端脚本进行异步调用。
该对话框可以通过在 HTML 服务接口的客户端中调用 google.script.host.close()
自行关闭。该对话框不能由其他界面关闭,只能由用户或自身关闭。
如下例所示,Google 文档、表单、幻灯片和表格都使用 Ui.showModalDialog()
方法打开对话框。
Code.gs
function onOpen() { SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp. .createMenu('Custom Menu') .addItem('Show dialog', 'showDialog') .addToUi(); } function showDialog() { var html = HtmlService.createHtmlOutputFromFile('Page') .setWidth(400) .setHeight(300); SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp. .showModalDialog(html, 'My custom dialog'); }
Page.html
Hello, world! <input type="button" value="Close" onclick="google.script.host.close()" />
自定义边栏
边栏可以在 Google 文档、表单、幻灯片和表格编辑器中显示 HTML 服务界面。
对话框打开时,边栏不会暂停服务器端脚本。客户端组件可以使用适用于 HTML 服务接口的 google.script
API 对服务器端脚本进行异步调用。
边栏可通过在 HTML 服务接口的客户端中调用 google.script.host.close()
自行关闭。边栏无法由其他界面关闭,只能由用户或自身关闭。
如下例所示,Google 文档、表单、幻灯片和表格都使用 Ui.showSidebar()
方法打开边栏。
Code.gs
function onOpen() { SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp. .createMenu('Custom Menu') .addItem('Show sidebar', 'showSidebar') .addToUi(); } function showSidebar() { var html = HtmlService.createHtmlOutputFromFile('Page') .setTitle('My custom sidebar'); SpreadsheetApp.getUi() // Or DocumentApp or SlidesApp or FormApp. .showSidebar(html); }
Page.html
Hello, world! <input type="button" value="Close" onclick="google.script.host.close()" />
打开文件的对话框
Google 选择器是一个“文件打开”对话框,用于保存存储在 Google 服务器(包括 Google 云端硬盘、Google 图片搜索、Google 视频搜索等)中的信息。
如下例所示,可以在 HTML 服务中使用 Picker 的客户端 JavaScript API 来创建自定义对话框,让用户选择现有文件或上传新文件,然后将选定的文件传回您的脚本以供进一步使用。
如需启用选择器并获取 API 密钥,请按照以下说明操作:
- 验证您的脚本项目使用的是标准 GCP 项目。
- 在 Google Cloud 项目中启用“Google Picker API”。
- 在 Google Cloud 项目仍处于打开状态时,选择 API 和服务,然后点击凭据。
- 依次点击创建凭据 > API 密钥。此操作会创建密钥,但您应修改密钥,以向密钥添加应用限制和 API 限制。
- 在 API 密钥对话框中,点击关闭。
- 在您创建的 API 密钥旁边,依次点击“更多”图标
> 修改 API 密钥。
在应用限制下,完成以下步骤:
- 选择 HTTP 引荐来源网址(网站)。
- 在网站限制下,点击添加一项。
- 点击 Referrer(引荐来源网址),然后输入
*.google.com
。 - 再添加一个商品,然后输入
*.googleusercontent.com
作为引荐来源网址。 - 点击完成。
在 API 限制下,完成以下步骤:
- 选择限制密钥。
在选择 API 部分中,选择 Google Picker API,然后点击确定。
注意:除非您已启用 Google Picker API,否则它不会显示,因为列表仅显示已为 Cloud 项目启用的 API。
在 API 密钥下,点击“复制到剪贴板”图标
。
点击底部的保存。