此页面由 Cloud Translation API 翻译。

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`	一个枚举，表示提醒或 `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)

参数

授权

`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)`