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.
const ui = SpreadsheetApp.getUi();
const 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.
const ui = SpreadsheetApp.getUi();
const 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.
const ui = SpreadsheetApp.getUi();
const 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.
const ui = SpreadsheetApp.getUi();
const 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.
const ui = SpreadsheetApp.getUi();
const 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.
const ui = SpreadsheetApp.getUi();
const 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.
const 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`	对话框的标题；会替换通过对 `userInterface` 对象调用 `setTitle()` 设置的任何标题。

授权

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

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.
const 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`	对话框的标题；会替换通过对 `userInterface` 对象调用 `setTitle()` 设置的任何标题。

授权

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

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.
const 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.
const 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

Class Ui 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

属性

方法

已弃用的方法

详细文档

alert(prompt)

参数

返回

alert(prompt, buttons)

参数

返回

alert(title, prompt, buttons)

参数

返回

createAddonMenu()

返回

createMenu(caption)

参数

返回

prompt(prompt)

参数

返回

prompt(prompt, buttons)

参数

返回

prompt(title, prompt, buttons)

参数

返回

showModalDialog(userInterface, title)

参数

授权

showModelessDialog(userInterface, title)

参数

授权

showSidebar(userInterface)

参数

授权

已弃用的方法

showDialog(userInterface)

参数

授权

Class Ui

`alert(prompt)`

`alert(prompt, buttons)`

`alert(title, prompt, buttons)`

`createAddonMenu()`

`createMenu(caption)`

`prompt(prompt)`

`prompt(prompt, buttons)`

`prompt(title, prompt, buttons)`

`showModalDialog(userInterface, title)`

`showModelessDialog(userInterface, title)`

`showSidebar(userInterface)`

`showDialog(userInterface)`