Class Ui

Ui

Uma instância do ambiente de interface do usuário para um app do Google que permite ao script adicionar recursos como menus, caixas de diálogo e barras laterais. Um script só pode interagir com a interface da instância atual de um editor aberto e somente se ele estiver vinculado ao contêiner do 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.
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.');
}

Propriedades

PropriedadeTipoDescrição
ButtonButtonUma enumeração que representa botões de caixa de diálogo predeterminados e localizados retornados por um alerta ou PromptResponse.getSelectedButton() para indicar em qual botão de uma caixa de diálogo 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 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 especificada 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 especificados.
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 especificados.
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 especificada 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 especificados.
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 especificados.
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 modalidade 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 do lado do cliente.

Documentação detalhada

alert(prompt)

Abre uma caixa de diálogo no editor do usuário com a mensagem especificada 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 durante a 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 especificados. 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 durante a 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.
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.',
  );
}

Parâmetros

NomeTipoDescrição
promptStringA mensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO conjunto de botões a ser exibido 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 especificados. 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 durante a 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.
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.',
  );
}

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 conjunto de botões a ser exibido 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 "Extensões" do editor. O menu não será atualizado até que Menu.addToUi() seja 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 estiver vinculado diretamente ao documento, o nome do submenu vai corresponder ao nome do script. Para mais informações, consulte o guia sobre 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 cardápios.

createMenu(caption)

Cria um builder que pode ser usado para adicionar um menu à interface do usuário do editor. O menu não é adicionado até que Menu.addToUi() seja chamado. Para mais informações, consulte o guia sobre menus. O rótulo de um menu de nível superior precisa estar em maiúsculas (todas as palavras principais em maiúsculas), mas o rótulo de um submenu precisa estar em minúsculas (apenas a primeira palavra em maiúsculas). 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 palavras principais em maiúsculas para um menu de nível superior ou apenas a primeira palavra em maiúsculas para um submenu.

Retornar

Menu: o novo criador de cardápios.

prompt(prompt)

Abre uma caixa de diálogo de entrada no editor do usuário com a mensagem especificada 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 durante a 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.
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.');
}

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 e o conjunto de botões especificados. 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 durante a 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.
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.');
}

Parâmetros

NomeTipoDescrição
promptStringA mensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO conjunto de botões a ser exibido 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 especificados. 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 durante a 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, 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.');
}

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 conjunto de botões a ser exibido 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 do 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 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 qualquer coisa além da caixa de diálogo. Por outro lado, as caixas de diálogo sem modo e as barras laterais permitem que o usuário interaja com o editor. 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 não modal. 

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

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 modalidade 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 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 mais informações, consulte o guia de caixas de diálogo e barras laterais.

As caixas de diálogo sem modalidade 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 fazem isso. 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 modalidade. 

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

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 do 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 cujos ambientes usam um idioma da esquerda para a direita e no lado esquerdo 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.
const 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