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 è associato al contenitore dell'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.');
}

Proprietà

Proprietà	Tipo	Descrizione
Button	Button	Un'enumerazione che rappresenta pulsanti di dialogo localizzati e predeterminati restituiti da un avviso o da PromptResponse.getSelectedButton() per indicare su quale pulsante di una finestra di dialogo ha fatto clic l'utente.
ButtonSet	ButtonSet	Un'enumerazione che rappresenta insiemi localizzati predeterminati di uno o più pulsanti di dialogo che possono essere aggiunti a un avviso o a una richiesta.

Metodi

Metodo	Tipo restituito	Breve descrizione
alert(prompt)	Button	Si apre una finestra di dialogo nell'editor dell'utente con il messaggio specificato e un pulsante "Ok".
alert(prompt, buttons)	Button	Apre una finestra di dialogo nell'editor dell'utente con il messaggio e il set di pulsanti specificati.
alert(title, prompt, buttons)	Button	Apre una finestra di dialogo nell'editor dell'utente con il titolo, il messaggio e il set di pulsanti specificati.
createAddonMenu()	Menu	Crea un builder che può essere utilizzato per inserire un sottomenu nel menu Estensioni dell'editor.
createMenu(caption)	Menu	Crea un builder che può essere utilizzato per aggiungere un menu all'interfaccia utente dell'editor.
prompt(prompt)	PromptResponse	Apre una finestra di dialogo di input nell'editor dell'utente con il messaggio specificato e un pulsante "Ok".
prompt(prompt, buttons)	PromptResponse	Apre una finestra di dialogo di input nell'editor dell'utente con il messaggio e il set di pulsanti specificati.
prompt(title, prompt, buttons)	PromptResponse	Apre una finestra di dialogo di input nell'editor dell'utente con il titolo, il messaggio e il set di pulsanti specificati.
showModalDialog(userInterface, title)	void	Apre una finestra di dialogo modale nell'editor dell'utente con contenuti personalizzati lato client.
showModelessDialog(userInterface, title)	void	Apre una finestra di dialogo non modale nell'editor dell'utente con contenuti personalizzati lato client.
showSidebar(userInterface)	void	Apre una barra laterale nell'editor dell'utente con contenuti personalizzati lato client.

Metodi ritirati

Metodo	Tipo restituito	Breve descrizione
showDialog(userInterface)	void	Apre una finestra di dialogo nell'editor dell'utente con contenuti personalizzati lato client.

Documentazione dettagliata

alert(prompt)

Si 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 vengono mantenuti durante la sospensione. Per saperne di più, consulta la guida a finestre di dialogo e 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

Nome	Tipo	Descrizione
prompt	String	Il messaggio da visualizzare nella finestra di dialogo.

Indietro

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

---

alert(prompt, buttons)

Apre una finestra di dialogo nell'editor dell'utente con il messaggio e il set 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 vengono mantenuti durante la sospensione. Per saperne di più, consulta la guida a finestre di dialogo e 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.
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.',
  );
}

Parametri

Nome	Tipo	Descrizione
prompt	String	Il messaggio da visualizzare nella finestra di dialogo.
buttons	ButtonSet	Il pulsante impostato per essere visualizzato nella finestra di dialogo.

Indietro

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

---

alert(title, prompt, buttons)

Apre una finestra di dialogo nell'editor dell'utente con il titolo, il messaggio e il set 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 LockService non vengono mantenuti durante la sospensione. Per saperne di più, consulta la guida a finestre di dialogo e 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.
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.',
  );
}

Parametri

Nome	Tipo	Descrizione
title	String	Il titolo da visualizzare sopra la finestra di dialogo.
prompt	String	Il messaggio da visualizzare nella finestra di dialogo.
buttons	ButtonSet	Il pulsante impostato per essere visualizzato nella finestra di dialogo.

Indietro

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

---

createAddonMenu()

Crea un builder che può essere utilizzato per inserire un sottomenu nel menu Estensioni dell'editor. Il menu non viene aggiornato finché non viene chiamato Menu.addToUi(). Se lo script viene eseguito 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 saperne 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();
}

Indietro

Menu: il nuovo strumento di creazione di menu.

---

createMenu(caption)

Crea un builder che può essere utilizzato per aggiungere un menu all'interfaccia utente dell'editor. Il menu non verrà aggiunto finché non viene chiamato Menu.addToUi(). Per saperne di più, consulta la guida ai menu. L'etichetta di un menu di primo livello deve essere in maiuscole nel titolo (tutte le parole principali in maiuscolo), mentre l'etichetta di un sottomenu deve essere in maiuscole nella frase (solo la prima parola in maiuscolo). 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

Nome	Tipo	Descrizione
caption	String	L'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.

Indietro

Menu: il nuovo strumento di creazione 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 ha chiuso la finestra di dialogo, ma le connessioni Jdbc e i blocchi LockService non vengono mantenuti durante la sospensione. Per saperne di più, consulta la guida a finestre di dialogo e 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.
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.');
}

Parametri

Nome	Tipo	Descrizione
prompt	String	Il messaggio da visualizzare nella finestra di dialogo.

Indietro

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 il set 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 LockService non vengono mantenuti durante la sospensione. Per saperne di più, consulta la guida a finestre di dialogo e 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.
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.');
}

Parametri

Nome	Tipo	Descrizione
prompt	String	Il messaggio da visualizzare nella finestra di dialogo.
buttons	ButtonSet	Il pulsante impostato per essere visualizzato nella finestra di dialogo.

Indietro

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 il set 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 LockService non vengono mantenuti durante la sospensione. Per saperne di più, consulta la guida a finestre di dialogo e 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.
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.');
}

Parametri

Nome	Tipo	Descrizione
title	String	Il titolo da visualizzare sopra la finestra di dialogo.
prompt	String	Il messaggio da visualizzare nella finestra di dialogo.
buttons	ButtonSet	Il pulsante impostato per essere visualizzato nella finestra di dialogo.

Indietro

PromptResponse: una rappresentazione della risposta dell'utente.

---

showModalDialog(userInterface, title)

Apre una finestra di dialogo modale nell'editor dell'utente con contenuti personalizzati lato client. 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 HtmlService. Per saperne di più, consulta la guida a finestre di dialogo e barre laterali.

Le finestre di dialogo modali impediscono all'utente di interagire con qualsiasi altro elemento oltre alla finestra di dialogo. Al contrario, le finestre di dialogo non modali e le barre laterali 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.
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');

Parametri

Nome	Tipo	Descrizione
userInterface	Object	Un HtmlOutput che rappresenta l'interfaccia da visualizzare.
title	String	Il titolo della finestra di dialogo, che 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 una finestra di dialogo non modale nell'editor dell'utente con contenuti personalizzati lato client. 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 HtmlService. Per saperne di più, consulta la guida a finestre di dialogo e barre laterali.

Le finestre di dialogo non modali consentono all'utente di interagire con l'editor 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 una barra laterale è una scelta migliore rispetto a una finestra di dialogo non modale.

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

Parametri

Nome	Tipo	Descrizione
userInterface	Object	Un HtmlOutput che rappresenta l'interfaccia da visualizzare.
title	String	Il titolo della finestra di dialogo, che 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 una barra laterale nell'editor dell'utente con contenuti personalizzati lato client. 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 di un'app web HtmlService. Per saperne di più, consulta la guida a finestre di dialogo e barre laterali.

La barra laterale viene visualizzata a destra dell'editor per gli utenti i cui ambienti utilizzano una lingua con scrittura da sinistra a destra e a sinistra dell'editor per le lingue con scrittura da destra a sinistra. Tutte le barre laterali mostrate dagli script hanno una larghezza di 300 pixel.

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

Parametri

Nome	Tipo	Descrizione
userInterface	Object	Un 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 ritirati

showDialog(userInterface)

Deprecato. A partire da marzo 2014, questo metodo è obsoleto. La sostituzione diretta è showModelessDialog(userInterface, title), ma showModalDialog(userInterface, title) è una scelta migliore in quasi tutti i casi.

Apre una finestra di dialogo nell'editor dell'utente con contenuti personalizzati lato client. 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 HtmlService. Per saperne di più, consulta la guida a finestre di dialogo e barre laterali.

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

Parametri

Nome	Tipo	Descrizione
userInterface	Object	Un 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