Google Workspace 文档中的对话框和边栏 (original) (raw)
绑定到 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!
侧边栏可以在 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!
文件打开对话框
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作为引荐来源。 - 点击完成。
- 您必须调用 PickerBuilder.setOrigin(google.script.host.origin)。
示例
以下示例展示了 Apps Script 中的 Google Picker。