Class Ui

Ui

Instance de l'environnement d'interface utilisateur pour une application Google qui permet au script d'ajouter des fonctionnalités telles que des menus, des boîtes de dialogue et des barres latérales. Un script ne peut interagir avec l'UI que pour l'instance actuelle d'un éditeur ouvert, et uniquement si le script est lié au conteneur de l'éditeur.

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

Propriétés

Propriété	Type	Description
Button	Button	Énumération représentant les boutons de boîte de dialogue prédéterminés et localisés renvoyés par une alerte ou PromptResponse.getSelectedButton() pour indiquer le bouton sur lequel l'utilisateur a cliqué dans une boîte de dialogue.
ButtonSet	ButtonSet	Énumération représentant des ensembles prédéterminés et localisés d'un ou plusieurs boutons de boîte de dialogue pouvant être ajoutés à une alerte ou à une invite.

Méthodes

Méthode	Type renvoyé	Brève description
alert(prompt)	Button	Ouvre une boîte de dialogue dans l'éditeur de l'utilisateur avec le message donné et un bouton "OK".
alert(prompt, buttons)	Button	Ouvre une boîte de dialogue dans l'éditeur de l'utilisateur avec le message et l'ensemble de boutons donnés.
alert(title, prompt, buttons)	Button	Ouvre une boîte de dialogue dans l'éditeur de l'utilisateur avec le titre, le message et l'ensemble de boutons spécifiés.
createAddonMenu()	Menu	Crée un générateur qui peut être utilisé pour insérer un sous-menu dans le menu "Extensions" de l'éditeur.
createMenu(caption)	Menu	Crée un compilateur qui peut être utilisé pour ajouter un menu à l'interface utilisateur de l'éditeur.
prompt(prompt)	PromptResponse	Ouvre une boîte de dialogue de saisie dans l'éditeur de l'utilisateur avec le message donné et un bouton "OK".
prompt(prompt, buttons)	PromptResponse	Ouvre une boîte de dialogue de saisie dans l'éditeur de l'utilisateur avec le message et l'ensemble de boutons spécifiés.
prompt(title, prompt, buttons)	PromptResponse	Ouvre une boîte de dialogue de saisie dans l'éditeur de l'utilisateur avec le titre, le message et l'ensemble de boutons spécifiés.
showModalDialog(userInterface, title)	void	Ouvre une boîte de dialogue modale dans l'éditeur de l'utilisateur avec du contenu personnalisé côté client.
showModelessDialog(userInterface, title)	void	Ouvre une boîte de dialogue non modale dans l'éditeur de l'utilisateur avec du contenu personnalisé côté client.
showSidebar(userInterface)	void	Ouvre une barre latérale dans l'éditeur de l'utilisateur avec du contenu personnalisé côté client.

Méthodes obsolètes

Méthode	Type renvoyé	Brève description
showDialog(userInterface)	void	Ouvre une boîte de dialogue dans l'éditeur de l'utilisateur avec du contenu personnalisé côté client.

Documentation détaillée

alert(prompt)

Ouvre une boîte de dialogue dans l'éditeur de l'utilisateur avec le message donné et un bouton "OK". Cette méthode suspend le script côté serveur pendant que la boîte de dialogue est ouverte. Le script reprend après que l'utilisateur a fermé la boîte de dialogue, mais les connexions Jdbc et les verrous LockService ne persistent pas pendant la suspension. Pour en savoir plus, consultez le guide des boîtes de dialogue et des barres latérales.

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

Paramètres

Nom	Type	Description
prompt	String	Message à afficher dans la boîte de dialogue.

Renvois

Button : bouton sur lequel l'utilisateur a cliqué.

---

alert(prompt, buttons)

Ouvre une boîte de dialogue dans l'éditeur de l'utilisateur avec le message et l'ensemble de boutons donnés. Cette méthode suspend le script côté serveur pendant que la boîte de dialogue est ouverte. Le script reprend après que l'utilisateur a fermé la boîte de dialogue, mais les connexions Jdbc et les verrous LockService ne persistent pas pendant la suspension. Pour en savoir plus, consultez le guide des boîtes de dialogue et des barres latérales.

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

Paramètres

Nom	Type	Description
prompt	String	Message à afficher dans la boîte de dialogue.
buttons	ButtonSet	Ensemble de boutons à afficher dans la boîte de dialogue.

Renvois

Button : bouton sur lequel l'utilisateur a cliqué.

---

alert(title, prompt, buttons)

Ouvre une boîte de dialogue dans l'éditeur de l'utilisateur avec le titre, le message et l'ensemble de boutons spécifiés. Cette méthode suspend le script côté serveur pendant que la boîte de dialogue est ouverte. Le script reprend après que l'utilisateur a fermé la boîte de dialogue, mais les connexions Jdbc et les verrous LockService ne persistent pas pendant la suspension. Pour en savoir plus, consultez le guide des boîtes de dialogue et des barres latérales.

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

Paramètres

Nom	Type	Description
title	String	Titre à afficher au-dessus de la boîte de dialogue.
prompt	String	Message à afficher dans la boîte de dialogue.
buttons	ButtonSet	Ensemble de boutons à afficher dans la boîte de dialogue.

Renvois

Button : bouton sur lequel l'utilisateur a cliqué.

---

createAddonMenu()

Crée un générateur qui peut être utilisé pour insérer un sous-menu dans le menu "Extensions" de l'éditeur. Le menu n'est pas mis à jour tant que Menu.addToUi() n'est pas appelé. Si le script s'exécute en tant que module complémentaire, le nom du sous-menu correspond à celui du module complémentaire dans la boutique en ligne. Si le script est associé directement au document, le nom du sous-menu correspond à celui du script. Pour en savoir plus, consultez le guide des 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();
}

Renvois

Menu : nouveau générateur de menus.

---

createMenu(caption)

Crée un compilateur qui peut être utilisé pour ajouter un menu à l'interface utilisateur de l'éditeur. Le menu n'est pas ajouté tant que Menu.addToUi() n'est pas appelé. Pour en savoir plus, consultez le guide des menus. Le libellé d'un menu de premier niveau doit être en casse titre (tous les mots importants sont en majuscules), tandis que celui d'un sous-menu doit être en casse phrase (seul le premier mot est en majuscule). Si le script est publié en tant que module complémentaire, le paramètre caption est ignoré et le menu est ajouté en tant que sous-menu du menu "Modules complémentaires", ce qui équivaut à 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();
}

Paramètres

Nom	Type	Description
caption	String	Libellé du menu, avec tous les mots importants en majuscules pour un menu de premier niveau, ou uniquement le premier mot en majuscule pour un sous-menu.

Renvois

Menu : nouveau générateur de menus.

---

prompt(prompt)

Ouvre une boîte de dialogue de saisie dans l'éditeur de l'utilisateur avec le message donné et un bouton "OK". Cette méthode suspend le script côté serveur pendant que la boîte de dialogue est ouverte. Le script reprend après que l'utilisateur a fermé la boîte de dialogue, mais les connexions Jdbc et les verrous LockService ne persistent pas pendant la suspension. Pour en savoir plus, consultez le guide des boîtes de dialogue et des barres latérales.

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

Paramètres

Nom	Type	Description
prompt	String	Message à afficher dans la boîte de dialogue.

Renvois

PromptResponse : représentation de la réponse de l'utilisateur.

---

prompt(prompt, buttons)

Ouvre une boîte de dialogue de saisie dans l'éditeur de l'utilisateur avec le message et l'ensemble de boutons spécifiés. Cette méthode suspend le script côté serveur pendant que la boîte de dialogue est ouverte. Le script reprend après que l'utilisateur a fermé la boîte de dialogue, mais les connexions Jdbc et les verrous LockService ne persistent pas pendant la suspension. Pour en savoir plus, consultez le guide des boîtes de dialogue et des barres latérales.

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

Paramètres

Nom	Type	Description
prompt	String	Message à afficher dans la boîte de dialogue.
buttons	ButtonSet	Ensemble de boutons à afficher dans la boîte de dialogue.

Renvois

PromptResponse : représentation de la réponse de l'utilisateur.

---

prompt(title, prompt, buttons)

Ouvre une boîte de dialogue de saisie dans l'éditeur de l'utilisateur avec le titre, le message et l'ensemble de boutons spécifiés. Cette méthode suspend le script côté serveur pendant que la boîte de dialogue est ouverte. Le script reprend une fois que l'utilisateur a fermé la boîte de dialogue, mais les connexions Jdbc et les verrous LockService ne sont pas conservés pendant la suspension. Pour en savoir plus, consultez le guide des boîtes de dialogue et des barres latérales.

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

Paramètres

Nom	Type	Description
title	String	Titre à afficher au-dessus de la boîte de dialogue.
prompt	String	Message à afficher dans la boîte de dialogue.
buttons	ButtonSet	Ensemble de boutons à afficher dans la boîte de dialogue.

Renvois

PromptResponse : représentation de la réponse de l'utilisateur.

---

showModalDialog(userInterface, title)

Ouvre une boîte de dialogue modale dans l'éditeur de l'utilisateur avec du contenu personnalisé côté client. Cette méthode ne suspend pas le script côté serveur pendant que la boîte de dialogue est ouverte. Pour communiquer avec le script côté serveur, le composant côté client doit effectuer des rappels asynchrones à l'aide de l'API google.script pour HtmlService. Pour fermer la boîte de dialogue de manière programmatique, appelez google.script.host.close() côté client d'une application Web HtmlService. Pour en savoir plus, consultez le guide des boîtes de dialogue et des barres latérales.

Les boîtes de dialogue modales empêchent l'utilisateur d'interagir avec autre chose que la boîte de dialogue. En revanche, les boîtes de dialogue non modales et les barres latérales permettent à l'utilisateur d'interagir avec l'éditeur. Dans presque tous les cas, une boîte de dialogue modale ou une barre latérale sont de meilleurs choix qu'une boîte de dialogue 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');

Paramètres

Nom	Type	Description
userInterface	Object	Un HtmlOutput représentant l'interface à afficher.
title	String	Titre de la boîte de dialogue. Remplace tout titre défini en appelant setTitle() sur l'objet userInterface.

Autorisation

Les scripts qui utilisent cette méthode nécessitent une autorisation avec un ou plusieurs des scopes suivants :

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

---

showModelessDialog(userInterface, title)

Ouvre une boîte de dialogue non modale dans l'éditeur de l'utilisateur avec du contenu personnalisé côté client. Cette méthode ne suspend pas le script côté serveur pendant que la boîte de dialogue est ouverte. Pour communiquer avec le script côté serveur, le composant côté client doit effectuer des rappels asynchrones à l'aide de l'API google.script pour HtmlService. Pour fermer la boîte de dialogue de manière programmatique, appelez google.script.host.close() côté client d'une application Web HtmlService. Pour en savoir plus, consultez le guide des boîtes de dialogue et des barres latérales.

Les boîtes de dialogue non modales permettent à l'utilisateur d'interagir avec l'éditeur situé derrière la boîte de dialogue. En revanche, les boîtes de dialogue modales ne le font pas. Dans presque tous les cas, une boîte de dialogue modale ou une barre latérale sont de meilleurs choix qu'une boîte de dialogue 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');

Paramètres

Nom	Type	Description
userInterface	Object	Un HtmlOutput représentant l'interface à afficher.
title	String	Titre de la boîte de dialogue. Remplace tout titre défini en appelant setTitle() sur l'objet userInterface.

Autorisation

Les scripts qui utilisent cette méthode nécessitent une autorisation avec un ou plusieurs des scopes suivants :

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

---

showSidebar(userInterface)

Ouvre une barre latérale dans l'éditeur de l'utilisateur avec du contenu personnalisé côté client. Cette méthode ne suspend pas le script côté serveur lorsque la barre latérale est ouverte. Pour communiquer avec le script côté serveur, le composant côté client doit effectuer des rappels asynchrones à l'aide de l'API google.script pour HtmlService. Pour fermer la barre latérale de manière programmatique, appelez google.script.host.close() côté client d'une application Web HtmlService. Pour en savoir plus, consultez le guide sur les boîtes de dialogue et les barres latérales.

La barre latérale s'affiche à droite de l'éditeur pour les utilisateurs dont l'environnement utilise une langue qui se lit de gauche à droite, et à gauche pour les langues qui se lisent de droite à gauche. Toutes les barres latérales affichées par les scripts ont une largeur de 300 pixels.

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

Paramètres

Nom	Type	Description
userInterface	Object	Un HtmlOutput représentant l'interface à afficher.

Autorisation

Les scripts qui utilisent cette méthode nécessitent une autorisation avec un ou plusieurs des scopes suivants :

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

Méthodes obsolètes

showDialog(userInterface)

Obsolète. Cette méthode est obsolète depuis mars 2014. Le remplacement direct est showModelessDialog(userInterface, title), mais showModalDialog(userInterface, title) est un meilleur choix dans presque tous les cas.

Ouvre une boîte de dialogue dans l'éditeur de l'utilisateur avec du contenu personnalisé côté client. Cette méthode ne suspend pas le script côté serveur pendant que la boîte de dialogue est ouverte. Pour communiquer avec le script côté serveur, le composant côté client doit effectuer des rappels asynchrones à l'aide de l'API google.script pour HtmlService. Pour fermer la boîte de dialogue de manière programmatique, appelez google.script.host.close() côté client d'une application Web HtmlService. Pour en savoir plus, consultez le guide des boîtes de dialogue et des barres latérales.

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

Paramètres

Nom	Type	Description
userInterface	Object	Un HtmlOutput représentant l'interface à afficher.

Autorisation

Les scripts qui utilisent cette méthode nécessitent une autorisation avec un ou plusieurs des scopes suivants :

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