Class Ui

Ui

Uma instância do ambiente de interface do usuário de um app Google que permite que o script adicione 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 apenas se 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
ButtonButtonUm tipo enumerado que representa botões de diálogo localizados e predeterminados retornados por um alert 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 localizados e predefinidos de um ou mais botões de caixa de diálogo que podem ser adicionados a um alerta ou a um prompt.

Métodos

MétodoTipo de retornoBreve descrição
alert(prompt)ButtonAbre uma caixa de diálogo no editor do usuário com a mensagem 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 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 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 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 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 do lado do cliente.
MétodoTipo de retornoBreve descrição
showDialog(userInterface)voidAbre uma caixa de diálogo 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 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 fecha a caixa de diálogo, mas as conexões Jdbc e as travas LockService não permanecem 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
promptStringMensagem 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 fecha a caixa de diálogo, mas as conexões Jdbc e as travas LockService não permanecem 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
promptStringMensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO botão definido para aparecer 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 as travas LockService não permanecem 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 que aparece acima da caixa de diálogo.
promptStringMensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO botão definido para aparecer 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 da Web. 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 menus.

createMenu(caption)

Cria um builder que pode ser usado para adicionar um menu à interface do usuário do editor. O menu não será 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úscula), mas o rótulo de um submenu precisa estar em letras maiú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 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 menus.

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 as travas LockService não permanecem 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
promptStringMensagem 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 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 as travas LockService não permanecem 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
promptStringMensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO botão definido para aparecer 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 é retomado depois que o usuário dispensa a caixa de diálogo, mas as conexões Jdbc e os bloqueios LockService não são mantidos 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 que aparece acima da caixa de diálogo.
promptStringMensagem a ser exibida na caixa de diálogo.
buttonsButtonSetO botão definido para aparecer 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 programaticamente, 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 outra coisa que não seja a 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 escolha melhor do que uma caixa de diálogo sem modo. 

// 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. Ele 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 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 programaticamente, 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. Em contraste, caixas de diálogo modais não têm. 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.
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. Ele 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 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.

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

Obsoleto. Esse método foi descontinuado em março de 2014. A substituição direta é showModelessDialog(userInterface, title), mas showModalDialog(userInterface, title) é uma escolha melhor em quase todos os casos.

Abre uma caixa de diálogo 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 programaticamente, 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. 

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

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