Class Ui

IU

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

// 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
ButtonButtonUma enumeração que representa botões de caixa de diálogo localizados predeterminados retornados por um alerta ou PromptResponse.getSelectedButton() para indicar o botão em uma caixa de diálogo em que o usuário clicou.
ButtonSetButtonSetUma enumeração 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 a uma solicitação.

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 de complemento 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 fornecida e o conjunto de botões.
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 no lado do cliente.
showModelessDialog(userInterface, title)voidAbre uma caixa de diálogo sem modo no editor do usuário com conteúdo personalizado no 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 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 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
promptStringA mensagem a ser exibida na caixa de diálogo.

Retornar

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 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 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
promptStringA mensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO botão definido para exibição na caixa de diálogo.

Retornar

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 LockService de bloqueio 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.
promptStringA mensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO botão definido para exibição na caixa de diálogo.

Retornar

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


createAddonMenu()

Cria um builder que pode ser usado para inserir um submenu no menu de complemento do editor. O menu só é atualizado quando Menu.addToUi() é chamado. Se o script estiver sendo executado como um complemento, o nome do submenu vai corresponder ao nome do complemento na loja on-line. Se o script for vinculado ao documento diretamente, o nome do submenu vai corresponder ao nome 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();
}

Retornar

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 quando Menu.addToUi() é chamado. Para mais informações, consulte o guia de menus. A etiqueta de um menu de nível superior precisa estar em maiúsculas (todas as palavras principais com letras maiúsculas), enquanto a etiqueta de um submenu precisa estar em frases (apenas a primeira palavra em letras maiúsculas). Caso o script seja publicado como um complemento, o parâmetro caption será ignorado, e o menu será adicionado como um submenu do menu de complementos, 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
captionStringA etiqueta do menu, com todas as principais palavras em letras maiúsculas para um menu de nível superior, ou apenas a primeira palavra com letra maiúscula em um submenu.

Retornar

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 LockService de bloqueio 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
promptStringA mensagem a ser exibida na caixa de diálogo.

Retornar

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 fornecida e o conjunto de botões. 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 LockService de bloqueio 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
promptStringA mensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO botão definido para exibição na caixa de diálogo.

Retornar

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. Esse método suspende o script do lado do servidor enquanto a caixa de diálogo está aberta. O script retoma depois que o usuário dispensa a caixa de diálogo, mas as conexões Jdbc e os bloqueios LockService não permanecem na 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.
promptStringA mensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO botão definido para exibição na caixa de diálogo.

Retornar

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 no lado do cliente. Esse método não suspende o script do lado do servidor enquanto a caixa de diálogo 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 caixa de diálogo de forma programática, chame google.script.host.close() no lado do cliente de um app da Web HtmlService. Para ver mais informações, consulte o guia para caixas de diálogo e barras laterais.

As caixas de diálogo modais impedem que o usuário interaja com algo 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 exibida.
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 no lado do cliente. Esse método não suspende o script do lado do servidor enquanto a caixa de diálogo 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 caixa de diálogo de forma programática, chame google.script.host.close() no lado do cliente de um app da Web HtmlService. Para ver mais informações, consulte o guia para 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, as caixas de diálogo modais não. Em quase todos os casos, uma caixa de diálogo modal ou uma barra lateral é uma opção 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 exibida.
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 ver mais informações, consulte o guia para caixas de diálogo e barras laterais.

A barra lateral é exibida no lado direito do editor para usuários com ambientes que usam um idioma da esquerda para a direita e do 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 exibida.

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