Class Ui

UI

Un'istanza dell'ambiente dell'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 l'interfaccia utente solo per l'istanza corrente di un editor aperto e solo se lo script è legato al container all'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 pulsanti di dialogo localizzati predeterminati restituiti da un avviso o PromptResponse.getSelectedButton() per indicare il pulsante di 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 un messaggio.

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 la serie di pulsanti specificati.
alert(title, prompt, buttons)ButtonApre una finestra di dialogo nell'editor dell'utente con il titolo, il messaggio e la serie di pulsanti specificati.
createAddonMenu()MenuCrea un generatore che può essere utilizzato per inserire un sottomenu nel menu Estensioni 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 immissione 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 la serie di pulsanti specificati.
prompt(title, prompt, buttons)PromptResponseApre una finestra di dialogo di input nell'editor dell'utente con il titolo, il messaggio e la serie 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 nell'editor dell'utente una finestra di dialogo non modale con contenuti lato client personalizzati.
showSidebar(userInterface)voidApre nell'editor dell'utente una barra laterale 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 chiude la finestra di dialogo, ma le connessioni Jdbc e i blocchi LockService non permangono per tutta la durata della sospensione. Per ulteriori informazioni, 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.

Ritorni

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 la serie di pulsanti specificati. Questo metodo sospende lo script lato server mentre la finestra di dialogo è aperta. Lo script riprende dopo che l'utente chiude la finestra di dialogo, ma le connessioni Jdbc e i blocchi LockService non permangono per tutta la durata della sospensione. Per ulteriori informazioni, 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 la visualizzazione nella finestra di dialogo.

Ritorni

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 la serie di pulsanti specificati. Questo metodo sospende lo script lato server mentre la finestra di dialogo è aperta. Lo script riprende dopo che l'utente chiude la finestra di dialogo, ma le connessioni e i blocchi LockService di Jdbc non persistono per tutta la durata della sospensione. Per ulteriori informazioni, 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 la visualizzazione nella finestra di dialogo.

Ritorni

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


createAddonMenu()

Crea un generatore che può essere utilizzato per inserire un sottomenu nel menu Estensioni dell'editor. In realtà il menu non viene aggiornato finché non viene chiamato 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 ulteriori informazioni, 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();
}

Ritorni

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 viene effettivamente aggiunto finché non viene chiamato Menu.addToUi(). Per ulteriori informazioni, consulta la guida ai menu. L'etichetta di un menu di primo livello deve essere in maiuscolo (tutte le parole principali con iniziale maiuscola), anche se l'etichetta di un sottomenu deve essere maiuscola solo per la prima parola. Se lo script viene pubblicato come componente aggiuntivo, il parametro caption viene ignorato e il menu viene aggiunto come sottomenu del menu Estensioni, 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 in maiuscolo per un sottomenu.

Ritorni

Menu: il nuovo generatore di menu.


prompt(prompt)

Apre una finestra di dialogo di immissione 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 chiude la finestra di dialogo, ma le connessioni e i blocchi LockService di Jdbc non persistono per tutta la durata della sospensione. Per ulteriori informazioni, 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.

Ritorni

PromptResponse: una rappresentazione della risposta dell'utente.


prompt(prompt, buttons)

Apre una finestra di dialogo di input nell'editor dell'utente con il messaggio e la serie di pulsanti specificati. Questo metodo sospende lo script lato server mentre la finestra di dialogo è aperta. Lo script riprende dopo che l'utente chiude la finestra di dialogo, ma le connessioni e i blocchi LockService di Jdbc non persistono per tutta la durata della sospensione. Per ulteriori informazioni, 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 la visualizzazione nella finestra di dialogo.

Ritorni

PromptResponse: una 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 la serie di pulsanti specificati. Questo metodo sospende lo script lato server mentre la finestra di dialogo è aperta. Lo script viene ripristinato dopo che l'utente ha ignorato la finestra di dialogo, ma le connessioni Jdbc e i blocchi LockService non vengono mantenuti 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 la visualizzazione nella finestra di dialogo.

Ritorni

PromptResponse: una 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 è aperta la finestra di dialogo. Per comunicare con lo script lato server, il componente lato client deve eseguire 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 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 elementi diversi dalla finestra di dialogo. Al contrario, le finestre di dialogo non moderate e le sidebar consentono all'utente di interagire con l'editor. In quasi tutti i casi, una finestra di dialogo modale o una barra laterale è una scelta migliore rispetto a una finestra di dialogo non modale.

// 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 chiamando 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 nell'editor dell'utente una finestra di dialogo non modale 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 deve eseguire 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 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 che si trova dietro la finestra di dialogo. Al contrario, le finestre di dialogo modali non lo fanno. In quasi tutti i casi, una finestra di dialogo modale o barra laterale è una scelta migliore rispetto a una finestra di dialogo non modale.

// 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 chiamando 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 nell'editor dell'utente una barra laterale 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 eseguire 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 di 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 da destra a sinistra. Tutte le barre laterali mostrate dagli script hanno una larghezza di 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