Class 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.');
}

属性

媒体资源类型说明
ButtonButton此枚举表示由 alertPromptResponse.getSelectedButton() 返回的预定的本地化对话框按钮,以指示用户点击的对话框中的按钮。
ButtonSetButtonSet一个枚举,表示由可添加到提醒提示中的一个或多个对话框按钮预定的本地化集。

方法

方法返回类型简介
alert(prompt)Button在用户的编辑器中打开一个对话框,其中包含指定的消息和“确定”按钮。
alert(prompt, buttons)Button在用户的编辑器中打开一个对话框,其中包含指定的消息和一组按钮。
alert(title, prompt, buttons)Button在用户的编辑器中打开一个对话框,其中包含指定的标题、消息和一组按钮。
createAddonMenu()Menu创建一个构建器,该构建器可用于将子菜单插入编辑器的“Extensions”菜单中。
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在用户的编辑器中打开边栏,其中包含自定义客户端内容。

详细文档

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');

参数

名称类型说明
promptString对话框中显示的消息。

弃踢回攻

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.');
}

参数

名称类型说明
promptString对话框中显示的消息。
buttonsButtonSet设置为在对话框中显示的按钮。

弃踢回攻

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.');
}

参数

名称类型说明
titleString要在对话框上方显示的标题。
promptString对话框中显示的消息。
buttonsButtonSet设置为在对话框中显示的按钮。

弃踢回攻

Button - 用户点击的按钮。


createAddonMenu()

创建一个构建器,该构建器可用于将子菜单插入编辑器的“Extensions”菜单中。在调用 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();
}

参数

名称类型说明
captionString菜单的标签,对于顶级菜单,所有主要单词的首字母都采用大写形式,或者子菜单只有第一个单词的首字母大写。

弃踢回攻

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.');
}

参数

名称类型说明
promptString对话框中显示的消息。

弃踢回攻

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.');
}

参数

名称类型说明
promptString对话框中显示的消息。
buttonsButtonSet设置为在对话框中显示的按钮。

弃踢回攻

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.');
}

参数

名称类型说明
titleString要在对话框上方显示的标题。
promptString对话框中显示的消息。
buttonsButtonSet设置为在对话框中显示的按钮。

弃踢回攻

PromptResponse - 用户响应的表示形式。


showModalDialog(userInterface, title)

在用户的编辑器中打开一个模态对话框,其中包含自定义客户端内容。在对话框打开时,此方法不会暂停服务器端脚本。如需与服务器端脚本进行通信,客户端组件必须使用适用于 HtmlServicegoogle.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');

参数

名称类型说明
userInterfaceObjectHtmlOutput,表示要显示的接口。
titleString对话框的标题;替换通过对 userInterface 对象调用 setTitle() 设置的任何标题。

授权

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

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

showModelessDialog(userInterface, title)

在用户的编辑器中打开一个非模态对话框,其中包含自定义客户端内容。在对话框打开时,此方法不会暂停服务器端脚本。如需与服务器端脚本进行通信,客户端组件必须使用适用于 HtmlServicegoogle.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');

参数

名称类型说明
userInterfaceObjectHtmlOutput,表示要显示的接口。
titleString对话框的标题;替换通过对 userInterface 对象调用 setTitle() 设置的任何标题。

授权

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

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

showSidebar(userInterface)

在用户的编辑器中打开边栏,其中包含自定义客户端内容。在边栏打开时,此方法不会暂停服务器端脚本。如需与服务器端脚本进行通信,客户端组件必须使用适用于 HtmlServicegoogle.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);

参数

名称类型说明
userInterfaceObjectHtmlOutput,表示要显示的接口。

授权

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

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

已废弃的方法