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
Propriedade | Tipo | Descrição |
---|---|---|
Button | Button | Uma 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. |
ButtonSet | ButtonSet | Uma 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étodo | Tipo de retorno | Breve descrição |
---|---|---|
alert(prompt) | Button | Abre uma caixa de diálogo no editor do usuário com a mensagem fornecida e um botão "OK" |
alert(prompt, buttons) | Button | Abre uma caixa de diálogo no editor do usuário com a mensagem e o conjunto de botões fornecidos. |
alert(title, prompt, buttons) | Button | Abre uma caixa de diálogo no editor do usuário com o título, a mensagem e o conjunto de botões fornecidos. |
createAddonMenu() | Menu | Cria um builder que pode ser usado para inserir um submenu no menu de complemento do editor. |
createMenu(caption) | Menu | Cria um builder que pode ser usado para adicionar um menu à interface do usuário do editor. |
prompt(prompt) | PromptResponse | Abre uma caixa de diálogo de entrada no editor do usuário com a mensagem fornecida e um botão "OK". |
prompt(prompt, buttons) | PromptResponse | Abre 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) | PromptResponse | 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. |
showModalDialog(userInterface, title) | void | Abre uma caixa de diálogo modal no editor do usuário com conteúdo personalizado no lado do cliente. |
showModelessDialog(userInterface, title) | void | Abre uma caixa de diálogo sem modo no editor do usuário com conteúdo personalizado no lado do cliente. |
showSidebar(userInterface) | void | Abre 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
Nome | Tipo | Descrição |
---|---|---|
prompt | String | A 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
Nome | Tipo | Descrição |
---|---|---|
prompt | String | A mensagem a ser exibida na caixa de diálogo. |
buttons | ButtonSet | O 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
Nome | Tipo | Descrição |
---|---|---|
title | String | O título a ser exibido acima da caixa de diálogo. |
prompt | String | A mensagem a ser exibida na caixa de diálogo. |
buttons | ButtonSet | O 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
Nome | Tipo | Descrição |
---|---|---|
caption | String | A 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
Nome | Tipo | Descrição |
---|---|---|
prompt | String | A 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
Nome | Tipo | Descrição |
---|---|---|
prompt | String | A mensagem a ser exibida na caixa de diálogo. |
buttons | ButtonSet | O 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
Nome | Tipo | Descrição |
---|---|---|
title | String | O título a ser exibido acima da caixa de diálogo. |
prompt | String | A mensagem a ser exibida na caixa de diálogo. |
buttons | ButtonSet | O 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
Nome | Tipo | Descrição |
---|---|---|
userInterface | Object | Um HtmlOutput que representa a interface a ser exibida. |
title | String | O 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
Nome | Tipo | Descrição |
---|---|---|
userInterface | Object | Um HtmlOutput que representa a interface a ser exibida. |
title | String | O 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
Nome | Tipo | Descrição |
---|---|---|
userInterface | Object | Um 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