绑定到 Google 文档、表格或表单的脚本可以显示多种类型的界面元素,包括预构建的提醒和提示,以及包含自定义 HTML 服务页面的对话框和边栏。通常,这些元素通过菜单项打开。(请注意,在 Google 表单中,只有打开表单进行修改的编辑者才能看到界面元素,而打开表单进行回复的用户则看不到。)
提醒对话框
提醒是一种预构建的对话框,会在 Google 文档、表格、幻灯片或 Google 表单编辑器中打开。它会显示一条消息和一个“确定”按钮;标题和其他按钮是可选的。这类似于在网络浏览器中的客户端 JavaScript 中调用 window.alert()
。
提醒会在对话框打开期间暂停服务器端脚本。脚本会在用户关闭对话框后恢复,但 JDBC 连接不会在暂停期间保留。
如下例所示,Google 文档、表单、幻灯片和表格均使用 Ui.alert()
方法,该方法有三种变体。如需替换默认的“确定”按钮,请将 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 文档、表格、幻灯片或 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 Picker 是一种 JavaScript API,可让用户选择或上传 Google 云端硬盘文件。Google Picker 库可在 HTML 服务中使用,用于创建自定义对话框,让用户选择现有文件或上传新文件,然后将所选内容传回脚本以供进一步使用。
要求
若要将 Google 选择器与 Apps Script 搭配使用,您需要满足多项要求。
为 Google Picker 设置环境。
您的脚本项目必须使用标准 Google Cloud 项目。
Apps Script project manifest 必须指定 Google Picker API 所需的授权范围,以便
ScriptApp.getOAuthToken()
为PickerBuilder.setOauthtoken()
返回正确的令牌。在
PickerBuilder.setDeveloperKey()
中设置的 API 密钥可以限制为仅供 Apps Script 使用。在应用限制下,完成以下步骤:- 选择 HTTP 引荐来源网址(网站)。
- 在网站限制下,点击添加一项。
- 点击引荐来源网址并输入
*.google.com
。 - 添加另一个项,并输入
*.googleusercontent.com
作为引荐来源。 - 点击完成。
示例
以下示例展示了 Apps Script 中的 Google Picker。