Cette page a été traduite par l'API Cloud Translation.

Actions de l'éditeur

Utilisez des objets Action pour créer un comportement interactif dans les modules complémentaires Google Workspace.

Les objets d'action définissent ce qui se passe lorsqu'un utilisateur interagit avec un widget (par exemple, un bouton) dans l'interface utilisateur du module complémentaire.

Ajouter une action à un widget

Pour associer une action à un widget, utilisez une fonction de gestionnaire de widgets, qui définit également la condition qui déclenche l'action. Lorsqu'elle est déclenchée, l'action exécute une fonction de rappel désignée. La fonction de rappel reçoit un objet d'événement qui contient des informations sur les interactions côté client de l'utilisateur. Vous devez implémenter la fonction de rappel et faire en sorte qu'elle renvoie un objet de réponse spécifique.

Exemple: Afficher une nouvelle fiche lorsqu'un utilisateur clique sur un bouton

Si vous souhaitez ajouter à votre module complémentaire un bouton permettant de créer et d'afficher une nouvelle fiche lorsque l'utilisateur clique dessus, procédez comme suit:

Créez un widget de bouton.
Pour définir une action de création de carte, ajoutez la fonction de gestionnaire de widget de bouton setOnClickAction(action).
Créez une fonction de rappel Apps Script à exécuter et spécifiez-la en tant que (action) dans la fonction de gestionnaire de widgets. Dans ce cas, la fonction de rappel doit créer la carte souhaitée et renvoyer un objet ActionResponse. L'objet de réponse indique au module complémentaire d'afficher la fiche de la fonction de rappel.

L'exemple suivant illustre la création d'un widget de bouton. L'action demande le champ d'application drive.file pour le fichier actuel au nom du module complémentaire.

/**
 * Adds a section to the Card Builder that displays a "REQUEST PERMISSION" button.
 * When it's clicked, the callback triggers file scope permission flow. This is used in
 * the add-on when the home-page displays basic data.
 */
function addRequestFileScopeButtonToBuilder(cardBuilder) {
    var buttonSection = CardService.newCardSection();
    // If the add-on does not have access permission, add a button that
    // allows the user to provide that permission on a per-file basis.
    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClickedInEditor");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setBackgroundColor("#4285f4")
      .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
      .setOnClickAction(buttonAction);

    buttonSection.addWidget(button);
    cardBuilder.addSection(buttonSection);
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the 
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document’s ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClickedInEditor(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();

Interactions d'accès aux fichiers pour les API REST

Les modules complémentaires Google Workspace qui étendent les éditeurs et utilisent les API REST peuvent inclure une action de widget supplémentaire pour demander l'accès aux fichiers. Cette action nécessite que la fonction de rappel d'action associée renvoie un objet de réponse spécialisé:

Tentative d'action	La fonction de rappel doit renvoyer
Demander l'accès au fichier current_document	`EditorFileScopeActionResponse`

Pour que vous puissiez utiliser cette action de widget et cet objet de réponse, toutes les conditions suivantes doivent être remplies:

Le module complémentaire utilise des API REST.
Le module complémentaire présente la boîte de dialogue de requête de champ d'application du fichier à l'aide de la méthode CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build();.
Le module complémentaire inclut le champ d'application de l'éditeur https://www.googleapis.com/auth/drive.file et le déclencheur onFileScopeGranted dans son fichier manifeste.

Demander l'accès au fichier pour le document actuel

Pour demander l'accès au fichier actuel, procédez comme suit:

Créez une fiche de page d'accueil qui vérifie si le module complémentaire a le champ d'application drive.file.
Si le module complémentaire ne dispose pas du champ d'application drive.file, créez un moyen de demander aux utilisateurs d'accorder le champ d'application drive.file pour le document actuel.

Exemple: Obtenir l'accès actuel au document dans Google Docs

L'exemple suivant crée une interface pour Google Docs qui affiche la taille du document actuel. Si le module complémentaire ne dispose pas de l'autorisation drive.file, il affiche un bouton pour lancer l'autorisation du champ d'application du fichier.

/**
 * Build a simple card that checks selected items' quota usage. Checking
 * quota usage requires user-permissions, so this add-on provides a button
 * to request `drive.file` scope for items the add-on doesn't yet have
 * permission to access.
 *
 * @param e The event object passed containing information about the
 *   current document.
 * @return {Card}
 */
function onDocsHomepage(e) {
  return createAddOnView(e);
}

function onFileScopeGranted(e) {
  return createAddOnView(e);
}

/**
 * For the current document, display either its quota information or
 * a button that allows the user to provide permission to access that
 * file to retrieve its quota details.
 *
 * @param e The event containing information about the current document
 * @return {Card}
 */
function createAddOnView(e) {
  var docsEventObject = e['docs'];
  var builder =  CardService.newCardBuilder();

  var cardSection = CardService.newCardSection();
  if (docsEventObject['addonHasFileScopePermission']) {
    cardSection.setHeader(docsEventObject['title']);
    // This add-on uses the recommended, limited-permission `drive.file`
    // scope to get granular per-file access permissions.
    // See: https://developers.google.com/drive/api/v2/about-auth
    // If the add-on has access permission, read and display its quota.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "This file takes up: " + getQuotaBytesUsed(docsEventObject['id'])));
  } else {
    // If the add-on does not have access permission, add a button that
    // allows the user to provide that permission on a per-file basis.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "The add-on needs permission to access this file's quota."));

    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClicked");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setOnClickAction(buttonAction);

    cardSection.addWidget(button);
  }
  return builder.addSection(cardSection).build();
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document’s ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClicked(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();
}