Class Ui

UI

Un'istanza dell'ambiente di interfaccia utente per un'app Google che consente allo script di aggiungere funzionalità come menu, finestre di dialogo e barre laterali. Uno script può interagire con la UI per l'istanza corrente di un editor aperto e solo se lo script è vincolato al container dall'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.');
}

Proprietà

ProprietàTipoDescrizione
ButtonButtonUn'enumerazione che rappresenta i pulsanti di dialogo localizzati e predeterminati restituiti da un avviso o da PromptResponse.getSelectedButton() per indicare il pulsante in una finestra di dialogo su cui l'utente ha fatto clic.
ButtonSetButtonSetUn'enumerazione che rappresenta insiemi predeterminati e localizzati di uno o più pulsanti di dialogo che possono essere aggiunti a un avviso o a una richiesta.

Metodi

MetodoTipo restituitoBreve descrizione
alert(prompt)ButtonApre una finestra di dialogo nell'editor dell'utente con il messaggio specificato e un pulsante "OK".
alert(prompt, buttons)ButtonApre una finestra di dialogo nell'editor dell'utente con il messaggio e l'insieme di pulsanti specificati.
alert(title, prompt, buttons)ButtonApre una finestra di dialogo nell'editor dell'utente con il titolo, il messaggio e una serie di pulsanti specificati.
createAddonMenu()MenuCrea un generatore che può essere utilizzato per inserire un sottomenu nel menu Componente aggiuntivo dell'editor.
createMenu(caption)MenuCrea un generatore che può essere utilizzato per aggiungere un menu all'interfaccia utente dell'editor.
prompt(prompt)PromptResponseApre una finestra di dialogo di input nell'editor dell'utente con il messaggio specificato e un pulsante "OK".
prompt(prompt, buttons)PromptResponseApre una finestra di dialogo di input nell'editor dell'utente con il messaggio e un insieme di pulsanti specificati.
prompt(title, prompt, buttons)PromptResponseApre una finestra di dialogo di input nell'editor dell'utente con il titolo, il messaggio e l'insieme di pulsanti specificati.
showModalDialog(userInterface, title)voidApre una finestra di dialogo modale nell'editor dell'utente con contenuti lato client personalizzati.
showModelessDialog(userInterface, title)voidApre una finestra di dialogo senza modalità nell'editor dell'utente con contenuti lato client personalizzati.
showSidebar(userInterface)voidApre una barra laterale nell'editor dell'utente con contenuti lato client personalizzati.

Documentazione dettagliata

alert(prompt)

Apre una finestra di dialogo nell'editor dell'utente con il messaggio specificato e un pulsante "OK". Questo metodo sospende lo script lato server mentre la finestra di dialogo è aperta. Lo script riprende dopo che l'utente ignora la finestra di dialogo, ma le connessioni Jdbc e le serrature LockService non vengono mantenute durante la sospensione. Per scoprire di più, consulta la guida alle finestre di dialogo e alle barre laterali.

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

Parametri

NomeTipoDescrizione
promptStringIl messaggio da visualizzare nella finestra di dialogo.

Andata e ritorno

Button: il pulsante su cui l'utente ha fatto clic.


alert(prompt, buttons)

Apre una finestra di dialogo nell'editor dell'utente con il messaggio e l'insieme di pulsanti specificati. Questo metodo sospende lo script lato server mentre la finestra di dialogo è aperta. Lo script riprende dopo che l'utente ignora la finestra di dialogo, ma le connessioni Jdbc e le serrature LockService non vengono mantenute durante la sospensione. Per scoprire di più, consulta la guida alle finestre di dialogo e alle barre laterali.

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

Parametri

NomeTipoDescrizione
promptStringIl messaggio da visualizzare nella finestra di dialogo.
buttonsButtonSetIl pulsante impostato per essere visualizzato nella finestra di dialogo.

Andata e ritorno

Button: il pulsante su cui l'utente ha fatto clic.


alert(title, prompt, buttons)

Apre una finestra di dialogo nell'editor dell'utente con il titolo, il messaggio e una serie di pulsanti specificati. Questo metodo sospende lo script lato server mentre la finestra di dialogo è aperta. Lo script riprende dopo che l'utente ignora la finestra di dialogo, ma le connessioni Jdbc e i blocchi LockService non continuano a essere sospesi. Per scoprire di più, consulta la guida alle finestre di dialogo e alle barre laterali.

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

Parametri

NomeTipoDescrizione
titleStringIl titolo da visualizzare sopra la finestra di dialogo.
promptStringIl messaggio da visualizzare nella finestra di dialogo.
buttonsButtonSetIl pulsante impostato per essere visualizzato nella finestra di dialogo.

Andata e ritorno

Button: il pulsante su cui l'utente ha fatto clic.


createAddonMenu()

Crea un generatore che può essere utilizzato per inserire un sottomenu nel menu Componente aggiuntivo dell'editor. Il menu non può essere aggiornato finché non viene chiamato il numero Menu.addToUi(). Se lo script è in esecuzione come componente aggiuntivo, il nome del sottomenu corrisponde al nome del componente aggiuntivo nel Web Store; se lo script è associato direttamente al documento, il nome del sottomenu corrisponde al nome dello script. Per scoprire di più, consulta la guida ai menu.

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

Andata e ritorno

Menu: il nuovo generatore di menu.


createMenu(caption)

Crea un generatore che può essere utilizzato per aggiungere un menu all'interfaccia utente dell'editor. Il menu non può essere aggiunto fino a quando non viene chiamato Menu.addToUi(). Per scoprire di più, consulta la guida ai menu. L'etichetta di un menu di primo livello deve essere in maiuscolo (tutte le parole principali sono in maiuscolo), ma l'etichetta di un sottomenu deve essere in maiuscolo (solo la prima parola deve essere in maiuscolo). Se lo script viene pubblicato come componente aggiuntivo, il parametro caption viene ignorato e il menu viene aggiunto come sottomenu del menu Componenti aggiuntivi, 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();
}

Parametri

NomeTipoDescrizione
captionStringL'etichetta del menu, con tutte le parole principali in maiuscolo per un menu di primo livello o solo la prima parola maiuscola per un sottomenu.

Andata e ritorno

Menu: il nuovo generatore di menu.


prompt(prompt)

Apre una finestra di dialogo di input nell'editor dell'utente con il messaggio specificato e un pulsante "OK". Questo metodo sospende lo script lato server mentre la finestra di dialogo è aperta. Lo script riprende dopo che l'utente ignora la finestra di dialogo, ma le connessioni Jdbc e i blocchi LockService non continuano a essere sospesi. Per scoprire di più, consulta la guida alle finestre di dialogo e alle barre laterali.

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

Parametri

NomeTipoDescrizione
promptStringIl messaggio da visualizzare nella finestra di dialogo.

Andata e ritorno

PromptResponse: rappresentazione della risposta dell'utente.


prompt(prompt, buttons)

Apre una finestra di dialogo di input nell'editor dell'utente con il messaggio e un insieme di pulsanti specificati. Questo metodo sospende lo script lato server mentre la finestra di dialogo è aperta. Lo script riprende dopo che l'utente ignora la finestra di dialogo, ma le connessioni Jdbc e i blocchi LockService non continuano a essere sospesi. Per scoprire di più, consulta la guida alle finestre di dialogo e alle barre laterali.

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

Parametri

NomeTipoDescrizione
promptStringIl messaggio da visualizzare nella finestra di dialogo.
buttonsButtonSetIl pulsante impostato per essere visualizzato nella finestra di dialogo.

Andata e ritorno

PromptResponse: rappresentazione della risposta dell'utente.


prompt(title, prompt, buttons)

Apre una finestra di dialogo di input nell'editor dell'utente con il titolo, il messaggio e l'insieme di pulsanti specificati. Questo metodo sospende lo script lato server mentre la finestra di dialogo è aperta. Lo script riprende dopo che l'utente ha chiuso la finestra di dialogo, ma le connessioni Jdbc e i blocchi di LockService non vengono mantenute durante la sospensione. Per ulteriori informazioni, consulta la guida alle finestre di dialogo e alle barre laterali.

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

Parametri

NomeTipoDescrizione
titleStringIl titolo da visualizzare sopra la finestra di dialogo.
promptStringIl messaggio da visualizzare nella finestra di dialogo.
buttonsButtonSetIl pulsante impostato per essere visualizzato nella finestra di dialogo.

Andata e ritorno

PromptResponse: rappresentazione della risposta dell'utente.


showModalDialog(userInterface, title)

Apre una finestra di dialogo modale nell'editor dell'utente con contenuti lato client personalizzati. Questo metodo non sospende lo script lato server mentre la finestra di dialogo è aperta. Per comunicare con lo script lato server, il componente lato client deve effettuare callback asincroni utilizzando l'API google.script per HtmlService. Per chiudere la finestra di dialogo in modo programmatico, chiama google.script.host.close() sul lato client di un'app web di HtmlService. Per ulteriori informazioni, consulta la guida alle finestre di dialogo e alle barre laterali.

Le finestre di dialogo modali impediscono all'utente di interagire con qualsiasi elemento diverso dalla finestra di dialogo. Tramite finestre di dialogo senza finestre e barre laterali permettono invece all'utente di interagire con l'editor. In quasi tutti i casi, una finestra di dialogo o una barra laterale modale è una scelta migliore rispetto a una finestra di dialogo senza modalità.

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

Parametri

NomeTipoDescrizione
userInterfaceObjectUn HtmlOutput che rappresenta l'interfaccia da visualizzare.
titleStringIl titolo della finestra di dialogo; sostituisce qualsiasi titolo impostato richiamando setTitle() sull'oggetto userInterface.

Autorizzazione

Gli script che utilizzano questo metodo richiedono l'autorizzazione con uno o più dei seguenti ambiti:

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

showModelessDialog(userInterface, title)

Apre una finestra di dialogo senza modalità nell'editor dell'utente con contenuti lato client personalizzati. Questo metodo non sospende lo script lato server mentre la finestra di dialogo è aperta. Per comunicare con lo script lato server, il componente lato client deve effettuare callback asincroni utilizzando l'API google.script per HtmlService. Per chiudere la finestra di dialogo in modo programmatico, chiama google.script.host.close() sul lato client di un'app web di HtmlService. Per ulteriori informazioni, consulta la guida alle finestre di dialogo e alle barre laterali.

Le finestre di dialogo senza modalità consentono all'utente di interagire con l'editor dietro la finestra di dialogo. Al contrario, le finestre di dialogo modali no. In quasi tutti i casi, una finestra di dialogo modale o barra laterale è una scelta migliore rispetto a una finestra di dialogo senza modalità.

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

Parametri

NomeTipoDescrizione
userInterfaceObjectUn HtmlOutput che rappresenta l'interfaccia da visualizzare.
titleStringIl titolo della finestra di dialogo; sostituisce qualsiasi titolo impostato richiamando setTitle() sull'oggetto userInterface.

Autorizzazione

Gli script che utilizzano questo metodo richiedono l'autorizzazione con uno o più dei seguenti ambiti:

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

showSidebar(userInterface)

Apre una barra laterale nell'editor dell'utente con contenuti lato client personalizzati. Questo metodo non sospende lo script lato server mentre la barra laterale è aperta. Per comunicare con lo script lato server, il componente lato client deve effettuare callback asincroni utilizzando l'API google.script per HtmlService. Per chiudere la barra laterale in modo programmatico, chiama google.script.host.close() sul lato client per un'app web HtmlService. Per ulteriori informazioni, consulta la guida alle finestre di dialogo e alle barre laterali.

La barra laterale viene visualizzata sul lato destro dell'editor per gli utenti i cui ambienti utilizzano una lingua da sinistra a destra e sul lato sinistro dell'editor per le lingue che si trovano da destra a sinistra. Tutte le barre laterali mostrate dagli script sono larghe 300 pixel.

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

Parametri

NomeTipoDescrizione
userInterfaceObjectUn HtmlOutput che rappresenta l'interfaccia da visualizzare.

Autorizzazione

Gli script che utilizzano questo metodo richiedono l'autorizzazione con uno o più dei seguenti ambiti:

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

Metodi deprecati