Class Ui

IU

Uma instância do ambiente da interface do usuário para um Google app que permite ao script adicionar recursos como menus, caixas de diálogo e barras laterais. Um script só pode interagir com a IU da instância atual de um editor aberto e somente se o script estiver vinculado ao contêiner ao editor.

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

Propriedades

PropriedadeTipoDescrição
ButtonButtonUm tipo enumerado que representa botões de caixas de diálogo predeterminados e localizados retornados por um alerta ou PromptResponse.getSelectedButton() para indicar em qual botão em uma caixa de diálogo o usuário clicou.
ButtonSetButtonSetUm tipo enumerado que representa conjuntos predeterminados e localizados de um ou mais botões de caixa de diálogo que podem ser adicionados a um alerta ou um comando.

Métodos

MétodoTipo de retornoBreve descrição
alert(prompt)ButtonAbre uma caixa de diálogo no editor do usuário com a mensagem fornecida e um botão "OK".
alert(prompt, buttons)ButtonAbre uma caixa de diálogo no editor do usuário com a mensagem e o conjunto de botões fornecidos.
alert(title, prompt, buttons)ButtonAbre uma caixa de diálogo no editor do usuário com o título, a mensagem e o conjunto de botões fornecidos.
createAddonMenu()MenuCria um builder que pode ser usado para inserir um submenu no menu "Extensões" do editor.
createMenu(caption)MenuCria um builder que pode ser usado para adicionar um menu à interface do usuário do editor.
prompt(prompt)PromptResponseAbre uma caixa de diálogo de entrada no editor do usuário com a mensagem fornecida e um botão "OK".
prompt(prompt, buttons)PromptResponseAbre uma caixa de diálogo de entrada no editor do usuário com a mensagem e o conjunto de botões fornecidos.
prompt(title, prompt, buttons)PromptResponseAbre uma caixa de diálogo de entrada no editor do usuário com o título, a mensagem e o conjunto de botões fornecidos.
showModalDialog(userInterface, title)voidAbre uma caixa de diálogo modal no editor do usuário com conteúdo personalizado do lado do cliente.
showModelessDialog(userInterface, title)voidAbre uma caixa de diálogo sem modo no editor do usuário com conteúdo personalizado do lado do cliente.
showSidebar(userInterface)voidAbre uma barra lateral no editor do usuário com conteúdo personalizado no lado do cliente.

Documentação detalhada

alert(prompt)

Abre uma caixa de diálogo no editor do usuário com a mensagem fornecida e um botão "OK". Esse método suspensa o script do lado do servidor enquanto a caixa de diálogo estiver aberta. O script é retomado depois que o usuário dispensa a caixa de diálogo, mas as conexões Jdbc e os bloqueios LockService não persistem na suspensão. Para mais informações, consulte o guia de caixas de diálogo e barras laterais.

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

Parâmetros

NomeTipoDescrição
promptStringMensagem a ser exibida na caixa de diálogo.

Retorno

Button: o botão em que o usuário clicou.


alert(prompt, buttons)

Abre uma caixa de diálogo no editor do usuário com a mensagem e o conjunto de botões fornecidos. Esse método suspensa o script do lado do servidor enquanto a caixa de diálogo estiver aberta. O script é retomado depois que o usuário dispensa a caixa de diálogo, mas as conexões Jdbc e os bloqueios LockService não persistem na suspensão. Para mais informações, consulte o guia de caixas de diálogo e barras laterais.

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

Parâmetros

NomeTipoDescrição
promptStringMensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO botão definido para ser exibido na caixa de diálogo.

Retorno

Button: o botão em que o usuário clicou.


alert(title, prompt, buttons)

Abre uma caixa de diálogo no editor do usuário com o título, a mensagem e o conjunto de botões fornecidos. Esse método suspende o script do lado do servidor enquanto a caixa de diálogo está aberta. O script é retomado depois que o usuário dispensa a caixa de diálogo, mas as conexões Jdbc e os bloqueios LockService não persistem na suspensão. Para mais informações, consulte o guia de caixas de diálogo e barras laterais.

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

Parâmetros

NomeTipoDescrição
titleStringO título a ser exibido acima da caixa de diálogo.
promptStringMensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO botão definido para ser exibido na caixa de diálogo.

Retorno

Button: o botão em que o usuário clicou.


createAddonMenu()

Cria um builder que pode ser usado para inserir um submenu no menu "Extensões" do editor. O menu não é realmente atualizado até que Menu.addToUi() seja chamado. Se o script estiver sendo executado como um complemento, o nome do submenu será igual ao nome do complemento na loja on-line. Se o script estiver vinculado ao documento diretamente, o nome do submenu será igual ao do script. Para mais informações, consulte o guia de menus.

// 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();
}

Retorno

Menu: o novo criador de menus.


createMenu(caption)

Cria um builder que pode ser usado para adicionar um menu à interface do usuário do editor. O menu só é adicionado depois que Menu.addToUi() é chamado. Para mais informações, consulte o guia de menus. O rótulo de um menu de nível superior precisa estar com a primeira letra maiúscula (todas as principais palavras em maiúscula), embora o rótulo de um submenu de seja em letras maiúsculas e minúsculas (apenas a primeira palavra em maiúscula). Se o script for publicado como um complemento, o parâmetro caption será ignorado, e o menu será adicionado como um submenu do menu "Extensões", equivalente a 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();
}

Parâmetros

NomeTipoDescrição
captionStringO rótulo do menu, com todas as principais palavras em maiúscula para um menu de nível superior, ou apenas a primeira palavra em maiúscula para um submenu.

Retorno

Menu: o novo criador de menus.


prompt(prompt)

Abre uma caixa de diálogo de entrada no editor do usuário com a mensagem fornecida e um botão "OK". Esse método suspende o script do lado do servidor enquanto a caixa de diálogo está aberta. O script é retomado depois que o usuário dispensa a caixa de diálogo, mas as conexões Jdbc e os bloqueios LockService não persistem na suspensão. Para mais informações, consulte o guia de caixas de diálogo e barras laterais.

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

Parâmetros

NomeTipoDescrição
promptStringMensagem a ser exibida na caixa de diálogo.

Retorno

PromptResponse: uma representação da resposta do usuário.


prompt(prompt, buttons)

Abre uma caixa de diálogo de entrada no editor do usuário com a mensagem e o conjunto de botões fornecidos. Esse método suspende o script do lado do servidor enquanto a caixa de diálogo está aberta. O script é retomado depois que o usuário dispensa a caixa de diálogo, mas as conexões Jdbc e os bloqueios LockService não persistem na suspensão. Para mais informações, consulte o guia de caixas de diálogo e barras laterais.

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

Parâmetros

NomeTipoDescrição
promptStringMensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO botão definido para ser exibido na caixa de diálogo.

Retorno

PromptResponse: uma representação da resposta do usuário.


prompt(title, prompt, buttons)

Abre uma caixa de diálogo de entrada no editor do usuário com o título, a mensagem e o conjunto de botões fornecidos. Este método suspende o script do lado do servidor enquanto a caixa de diálogo está aberta. O script é retomado depois que o usuário dispensa a caixa de diálogo, mas as conexões Jdbc e os bloqueios LockService não permanecem durante a suspensão. Para ver mais informações, consulte o guia de caixas de diálogo e barras laterais.

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

Parâmetros

NomeTipoDescrição
titleStringO título a ser exibido acima da caixa de diálogo.
promptStringMensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO botão definido para ser exibido na caixa de diálogo.

Retorno

PromptResponse: uma representação da resposta do usuário.


showModalDialog(userInterface, title)

Abre uma caixa de diálogo modal no editor do usuário com conteúdo personalizado do lado do cliente. Esse método não suspende o script do lado do servidor enquanto a caixa de diálogo estiver aberta. Para se comunicar com o script do lado do servidor, o componente do lado do cliente precisa fazer callbacks assíncronos usando a API google.script para HtmlService. Para fechar a caixa de diálogo de maneira programática, chame google.script.host.close() no lado do cliente de um app da Web HtmlService. Para mais informações, consulte o guia de caixas de diálogo e barras laterais.

As caixas de diálogo modais impedem que o usuário interaja com outras coisas além da caixa de diálogo. Por outro lado, caixas de diálogo sem modo e barras laterais permitem que o usuário interaja com o editor. Em quase todos os casos, uma caixa de diálogo ou barra lateral modal é uma escolha melhor do que uma caixa de diálogo sem modo.

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

Parâmetros

NomeTipoDescrição
userInterfaceObjectUm HtmlOutput que representa a interface a ser mostrada.
titleStringO título da caixa de diálogo. Substitui qualquer título definido chamando setTitle() no objeto userInterface.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

showModelessDialog(userInterface, title)

Abre uma caixa de diálogo sem modo no editor do usuário com conteúdo personalizado do lado do cliente. Esse método não suspende o script do lado do servidor enquanto a caixa de diálogo estiver aberta. Para se comunicar com o script do lado do servidor, o componente do lado do cliente precisa fazer callbacks assíncronos usando a API google.script para HtmlService. Para fechar a caixa de diálogo de maneira programática, chame google.script.host.close() no lado do cliente de um app da Web HtmlService. Para mais informações, consulte o guia de caixas de diálogo e barras laterais.

As caixas de diálogo sem modo permitem que o usuário interaja com o editor por trás da caixa de diálogo. Por outro lado, caixas de diálogo modais não. Em quase todos os casos, uma caixa de diálogo modal ou uma barra lateral é uma escolha melhor do que uma caixa de diálogo sem modo.

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

Parâmetros

NomeTipoDescrição
userInterfaceObjectUm HtmlOutput que representa a interface a ser mostrada.
titleStringO título da caixa de diálogo. Substitui qualquer título definido chamando setTitle() no objeto userInterface.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

showSidebar(userInterface)

Abre uma barra lateral no editor do usuário com conteúdo personalizado no lado do cliente. Esse método não suspende o script do lado do servidor enquanto a barra lateral está aberta. Para se comunicar com o script do lado do servidor, o componente do lado do cliente precisa fazer callbacks assíncronos usando a API google.script para HtmlService. Para fechar a barra lateral de maneira programática, chame google.script.host.close() no lado do cliente de um app da Web HtmlService. Para mais informações, consulte o guia de caixas de diálogo e barras laterais.

A barra lateral aparece no lado direito do editor para usuários com ambientes que usam um idioma da esquerda para a direita e no lado esquerdo do editor para idiomas da direita para a esquerda. Todas as barras laterais mostradas por scripts têm 300 pixels de largura.

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

Parâmetros

NomeTipoDescrição
userInterfaceObjectUm HtmlOutput que representa a interface a ser mostrada.

Autorização

Os scripts que usam esse método exigem autorização com um ou mais dos seguintes escopos:

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

Métodos obsoletos