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 è legato 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àTipoDescrizione
ButtonButtonUn enum che rappresenta i pulsanti di dialogo localizzati predeterminati restituiti da un avviso o da PromptResponse.getSelectedButton() per indicare su quale pulsante di una finestra di dialogo ha fatto clic l'utente.
ButtonSetButtonSetUn enum che rappresenta insiemi predeterminati e localizzati di uno o più pulsanti di dialogo che possono essere aggiunti a un avviso o a un prompt.

Metodi

MetodoTipo restituitoBreve descrizione
alert(prompt)ButtonViene aperta 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 l'insieme 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)PromptResponseViene aperta 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 l'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 modale nell'editor dell'utente con contenuti lato client personalizzati.
showSidebar(userInterface)voidViene aperta una barra laterale nell'editor dell'utente con contenuti lato client personalizzati.

Documentazione dettagliata

alert(prompt)

Viene aperta una finestra di dialogo nell'editor dell'utente con il messaggio specificato e un pulsante "OK". Questo metodo interrompe 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 rimangono invariati 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

NomeTipoDescrizione
promptStringIl messaggio da visualizzare nella finestra di dialogo.

Invio

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 l'insieme di pulsanti specificati. Questo metodo interrompe 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 rimangono invariati 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

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

Invio

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 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 chiude la finestra di dialogo, ma le connessioni Jdbc e i blocchi LockService non rimangono invariati 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

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.

Invio

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

createAddonMenu()

Crea un generatore che può essere utilizzato per inserire un sottomenu nel menu Estensioni dell'editor. Il menu non viene effettivamente 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 è legato 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();
}

Invio

Menu: il nuovo Strumento per la creazione 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 scritta con le iniziali maiuscole (tutte le parole principali in maiuscolo), mentre l'etichetta di un sottomenu deve essere scritta con la maiuscola a inizio 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

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.

Invio

Menu: il nuovo Strumento per la creazione di menu.

prompt(prompt)

Viene aperta 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 chiude la finestra di dialogo, ma le connessioni Jdbc e i blocchi LockService non rimangono invariati 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

NomeTipoDescrizione
promptStringIl messaggio da visualizzare nella finestra di dialogo.

Invio

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 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 chiude la finestra di dialogo, ma le connessioni Jdbc e i blocchi LockService non rimangono invariati 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

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

Invio

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 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 ignorato 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 su dialoghi 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

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.

Invio

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 la finestra di dialogo è 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 finestra di dialogo programmaticamente, chiama google.script.host.close() lato client di un'HtmlService web app. Per ulteriori informazioni, consulta la guida a finestre di dialogo e barre laterali.

Le finestre di dialogo modali impediscono all'utente di interagire con altri elementi oltre alla finestra di dialogo. Invece, le finestre di dialogo modali e le barre laterali consentono all'utente di interagire con l'editor. In quasi tutti i casi, una finestra di dialogo o una barra laterale modale è una scelta migliore di una finestra di dialogo senza modalità. 

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

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 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 eseguire callback asincroni utilizzando l'API google.script per HtmlService. Per chiudere la finestra di dialogo programmaticamente, chiama google.script.host.close() lato client di un'HtmlService web app. Per ulteriori informazioni, consulta la guida a finestre di dialogo e barre laterali.

Le finestre di dialogo modali consentono all'utente di interagire con l'editor dietro la finestra di dialogo. Invece, le finestre di dialogo modali non lo fanno. In quasi tutti i casi, una finestra di dialogo obbligatoria o una barra laterale è una scelta migliore di una finestra di dialogo senza modalità. 

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

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)

Viene aperta 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 eseguire callback asincroni utilizzando l'API google.script per HtmlService. Per chiudere la barra laterale in modo programmatico, chiama google.script.host.close() lato client di un'HtmlService web app. Per ulteriori informazioni, consulta la guida a finestre di dialogo e barra laterali.

La barra laterale viene visualizzata sul lato destro dell'editor per gli utenti i cui ambienti utilizzano una lingua con scrittura da sinistra a destra e sul lato sinistro 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

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 ritirati