Class Ui

Ui

Google 应用的界面环境实例，允许脚本添加 菜单、对话框和边栏等功能。脚本只能与 打开编辑器的当前实例，并且仅当脚本与编辑器绑定时。

// Display a dialog box with a title, message, input field, and "Yes" and "No" buttons. The
// user can also close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('Getting to know you', 'May I know your name?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response.getSelectedButton() == ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() == ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

属性

属性	类型	说明
Button	Button	一个枚举，表示由 alert 或 PromptResponse.getSelectedButton() 返回的预定本地化对话框按钮，以指明 用户点击了对话框中的哪个按钮。
ButtonSet	ButtonSet	一个枚举，表示由一个或多个已确定的本地化集合， 添加到提醒或提示中。

方法

方法	返回类型	简介
alert(prompt)	Button	在用户编辑器中打开一个对话框，其中显示给定消息和“确定”按钮。
alert(prompt, buttons)	Button	在用户编辑器中打开一个对话框，其中包含指定消息和一组按钮。
alert(title, prompt, buttons)	Button	在用户编辑器中打开一个对话框，其中包含给定的标题、消息和一组按钮。
createAddonMenu()	Menu	创建可用于将子菜单插入编辑器的“扩展程序”菜单中的构建器。
createMenu(caption)	Menu	创建一个可用于向编辑器界面添加菜单的构建器。
prompt(prompt)	PromptResponse	在用户编辑器中打开输入对话框，其中显示给定消息和“确定”按钮。
prompt(prompt, buttons)	PromptResponse	在用户编辑器中打开一个输入对话框，其中包含给定消息和一组按钮。
prompt(title, prompt, buttons)	PromptResponse	在用户编辑器中打开一个输入对话框，其中包含给定的标题、消息和一组 按钮。
showModalDialog(userInterface, title)	void	在用户编辑器中打开包含自定义客户端内容的模态对话框。
showModelessDialog(userInterface, title)	void	在用户编辑器中打开一个包含自定义客户端内容的非模式对话框。
showSidebar(userInterface)	void	在用户编辑器中打开边栏，其中包含自定义客户端内容。

已弃用的方法

方法	返回类型	简介
showDialog(userInterface)	void	在用户编辑器中打开一个包含自定义客户端内容的对话框。

详细文档

alert(prompt)

在用户编辑器中打开一个对话框，其中显示给定消息和“确定”按钮。此方法 在对话框打开时挂起服务器端脚本。脚本会在用户 会关闭对话框，但会Jdbc 即使连接和LockService锁定 在整个暂停期内持续有效。如需了解详情，请参阅对话框和边栏指南。

// Display "Hello, world" in a dialog box with an "OK" button. The user can also close the
// dialog by clicking the close button in its title bar.
SpreadsheetApp.getUi().alert('Hello, world');

参数

名称	类型	说明
prompt	String	要在对话框中显示的消息。

返回

Button - 用户点击的按钮。

---

alert(prompt, buttons)

在用户编辑器中打开一个对话框，其中包含指定消息和一组按钮。此方法 在对话框打开时挂起服务器端脚本。脚本会在用户 会关闭对话框，但会Jdbc 即使连接和LockService锁定 在整个暂停期内持续有效。如需了解详情，请参阅对话框和边栏指南。

// Display a dialog box with a message and "Yes" and "No" buttons. The user can also close the
// dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.alert('Are you sure you want to continue?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response == ui.Button.YES) {
  Logger.log('The user clicked "Yes."');
} else {
  Logger.log('The user clicked "No" or the close button in the dialog\'s title bar.');
}

参数

名称	类型	说明
prompt	String	要在对话框中显示的消息。
buttons	ButtonSet	设置为在对话框中显示的按钮。

返回

Button - 用户点击的按钮。

---

alert(title, prompt, buttons)

在用户编辑器中打开一个对话框，其中包含给定的标题、消息和一组按钮。这个 方法会在对话框打开时挂起服务器端脚本。脚本在 用户关闭了对话框，但Jdbc 但使用 LockService 的锁时， 在整个暂停期内持续有效。如需了解详情，请参阅对话框和边栏指南。

// Display a dialog box with a title, message, and "Yes" and "No" buttons. The user can also
// close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.alert('Confirm', 'Are you sure you want to continue?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response == ui.Button.YES) {
  Logger.log('The user clicked "Yes."');
} else {
  Logger.log('The user clicked "No" or the close button in the dialog\'s title bar.');
}

参数

名称	类型	说明
title	String	要在对话框上方显示的标题。
prompt	String	要在对话框中显示的消息。
buttons	ButtonSet	设置为在对话框中显示的按钮。

返回

Button - 用户点击的按钮。

---

createAddonMenu()

创建可用于将子菜单插入编辑器的“扩展程序”菜单中的构建器。通过 直到调用 Menu.addToUi() 之后才会更新菜单。如果脚本正在运行 作为插件，子菜单名称与应用商店中的插件名称一致；如果脚本已直接绑定到文档，则子菜单名称 与脚本名称匹配。如需了解详情，请参阅菜单指南。

// Add an item to the Add-on menu, under a sub-menu whose name is set automatically.
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createAddonMenu()
      .addItem('Show', 'showSidebar')
      .addToUi();
}

返回

Menu - 新的菜单构建器。

---

createMenu(caption)

创建一个可用于向编辑器界面添加菜单的构建器。菜单不是 实际上会添加到 Menu.addToUi() 被调用为止。如需了解详情，请参阅菜单指南。顶级菜单的标签应为 虽然子菜单的标签应以 句首字母大写（仅第一个单词的首字母大写）。如果该脚本是作为插件发布的，系统会忽略 caption 参数，并将 菜单会添加为“扩展程序”菜单的子菜单，等同于 createAddonMenu()。

// Add a custom menu to the active document, including a separator and a sub-menu.
function onOpen(e) {
  SpreadsheetApp.getUi()
      .createMenu('My Menu')
      .addItem('My menu item', 'myFunction')
      .addSeparator()
      .addSubMenu(SpreadsheetApp.getUi().createMenu('My sub-menu')
          .addItem('One sub-menu item', 'mySecondFunction')
          .addItem('Another sub-menu item', 'myThirdFunction'))
      .addToUi();
}

参数

名称	类型	说明
caption	String	菜单的标签，顶级菜单的所有主要字词均采用大写形式； 或只针对子菜单的第一个单词的首字母大写。

返回

Menu - 新的菜单构建器。

---

prompt(prompt)

在用户编辑器中打开输入对话框，其中显示给定消息和“确定”按钮。这个 方法会在对话框打开时挂起服务器端脚本。脚本在 用户关闭了对话框，但Jdbc 但使用 LockService 的锁时， 在整个暂停期内持续有效。如需了解详情，请参阅对话框和边栏指南。

// Display a dialog box with a message, input field, and an "OK" button. The user can also
// close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('Enter your name:');

// Process the user's response.
if (response.getSelectedButton() == ui.Button.OK) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

参数

名称	类型	说明
prompt	String	要在对话框中显示的消息。

返回

PromptResponse - 表示用户响应。

---

prompt(prompt, buttons)

在用户编辑器中打开一个输入对话框，其中包含给定消息和一组按钮。这个 方法会在对话框打开时挂起服务器端脚本。脚本在 用户关闭了对话框，但Jdbc 但使用 LockService 的锁时， 在整个暂停期内持续有效。如需了解详情，请参阅对话框和边栏指南。

// Display a dialog box with a message, input field, and "Yes" and "No" buttons. The user can
// also close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('May I know your name?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response.getSelectedButton() == ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() == ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

参数

名称	类型	说明
prompt	String	要在对话框中显示的消息。
buttons	ButtonSet	设置为在对话框中显示的按钮。

返回

PromptResponse - 表示用户响应。

---

prompt(title, prompt, buttons)

在用户编辑器中打开一个输入对话框，其中包含给定的标题、消息和一组 按钮。此方法会在对话框打开时暂停服务器端脚本。脚本 在用户关闭对话框后恢复，但 Jdbc 连接和 LockService 锁定不会在整个 暂停。有关详情，请参阅有关 对话框和边栏。

// Display a dialog box with a title, message, input field, and "Yes" and "No" buttons. The
// user can also close the dialog by clicking the close button in its title bar.
var ui = SpreadsheetApp.getUi();
var response = ui.prompt('Getting to know you', 'May I know your name?', ui.ButtonSet.YES_NO);

// Process the user's response.
if (response.getSelectedButton() == ui.Button.YES) {
  Logger.log('The user\'s name is %s.', response.getResponseText());
} else if (response.getSelectedButton() == ui.Button.NO) {
  Logger.log('The user didn\'t want to provide a name.');
} else {
  Logger.log('The user clicked the close button in the dialog\'s title bar.');
}

参数

名称	类型	说明
title	String	要在对话框上方显示的标题。
prompt	String	要在对话框中显示的消息。
buttons	ButtonSet	设置为在对话框中显示的按钮。

返回

PromptResponse - 表示用户响应。

---

showModalDialog(userInterface, title)

在用户编辑器中打开包含自定义客户端内容的模态对话框。此方法 不在对话框打开时挂起服务器端脚本。为了与 服务器端脚本，客户端组件必须使用 HtmlService 的 google.script API 进行异步回调。关闭对话框 以编程方式，调用 HtmlService Web 客户端上的 google.script.host.close() 应用。如需了解详情，请参阅对话框和 。

模态对话框可防止用户与对话框以外的任何内容互动。修改者 相比之下，无模式对话框和边栏可让用户与编辑器互动。在几乎所有情况下， 模态对话框或边栏比非模态对话框更好。

// Display a modal dialog box with custom HtmlService content.
var htmlOutput = HtmlService
    .createHtmlOutput('<p>A change of speed, a change of style...</p>')
    .setWidth(250)
    .setHeight(300);
SpreadsheetApp.getUi().showModalDialog(htmlOutput, 'My add-on');

参数

名称	类型	说明
userInterface	Object	HtmlOutput 来代表要显示的界面
title	String	对话框的标题；覆盖通过调用 上的 setTitle() 设置的任何标题 userInterface 对象。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/script.container.ui

---

showModelessDialog(userInterface, title)

在用户编辑器中打开一个包含自定义客户端内容的非模式对话框。此方法 在对话框打开时不会挂起服务器端脚本。为了与 服务器端脚本，客户端组件必须使用 HtmlService 的 google.script API 进行异步回调。关闭对话框 以编程方式，调用 HtmlService Web 客户端上的 google.script.host.close() 应用。如需了解详情，请参阅对话框和 边栏。

无模式对话框可让用户与对话框后面的编辑器进行交互。相比之下 模态对话框不会执行这些操作。在几乎所有情况下， 对话框或边栏比非模态对话框更好。

// Display a modeless dialog box with custom HtmlService content.
var htmlOutput = HtmlService
    .createHtmlOutput('<p>A change of speed, a change of style...</p>')
    .setWidth(250)
    .setHeight(300);
SpreadsheetApp.getUi().showModelessDialog(htmlOutput, 'My add-on');

参数

名称	类型	说明
userInterface	Object	HtmlOutput 来代表要显示的界面
title	String	对话框的标题；覆盖通过调用 上的 setTitle() 设置的任何标题 userInterface 对象。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/script.container.ui

---

showSidebar(userInterface)

在用户编辑器中打开边栏，其中包含自定义客户端内容。此方法 不在边栏打开时挂起服务器端脚本。为了与 服务器端脚本，客户端组件必须使用 HtmlService 的 google.script API 进行异步回调。关闭边栏 以编程方式，调用 HtmlService Web 客户端上的 google.script.host.close() 应用。如需了解详情，请参阅对话框和 边栏。

如果用户的环境使用 对于从左到右书写的语言，则位于编辑器左侧。全部 脚本显示的边栏宽度为 300 像素。

// Display a sidebar with custom HtmlService content.
var htmlOutput = HtmlService
    .createHtmlOutput('<p>A change of speed, a change of style...</p>')
    .setTitle('My add-on');
SpreadsheetApp.getUi().showSidebar(htmlOutput);

参数

名称	类型	说明
userInterface	Object	HtmlOutput 来代表要显示的界面

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/script.container.ui

已弃用的方法

showDialog(userInterface)

已弃用。自 2014 年 3 月起，此方法已被弃用。直接替换为 showModelessDialog(userInterface, title)，但 showModalDialog(userInterface, title) 为 几乎在所有情况下都是更好的选择。

在用户编辑器中打开一个包含自定义客户端内容的对话框。此方法 不在对话框打开时挂起服务器端脚本。为了与 服务器端脚本，客户端组件必须使用 HtmlService 的 google.script API 进行异步回调。关闭对话框 以编程方式，调用 HtmlService Web 客户端上的 google.script.host.close() 应用。如需了解详情，请参阅对话框和 边栏。

// Display a dialog box with custom HtmlService content.
var htmlOutput = HtmlService
    .createHtmlOutput('<p>A change of speed, a change of style...</p>')
    .setTitle('My add-on')
    .setWidth(250)
    .setHeight(300);
SpreadsheetApp.getUi().showDialog(htmlOutput);

参数

名称	类型	说明
userInterface	Object	HtmlOutput 来代表要显示的界面

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/script.container.ui