Utilisation d’événements à l’aide de l’API JavaScript pour Excel

  • Article

Cet article décrit des concepts importants relatifs à l’utilisation des événements dans Excel et fournit des exemples de code montrant comment inscrire des gestionnaires d’événements, gérer des événements et supprimer des gestionnaires d’événements à l’aide de l’API JavaScript pour Excel.

Événements dans Excel

Chaque fois que certains types de modifications se produisent dans un classeur Excel, une notification d’événement se déclenche. En utilisant l’API JavaScript pour Excel, vous pouvez inscrire les gestionnaires d’événements autorisant votre complément à exécuter automatiquement une fonction désignée lorsqu’un événement spécifique se produit. Les événements suivants sont actuellement pris en charge.

Événement Description Objets pris en charge
onActivated Se produit lorsqu’un objet est activé. Chart, ChartCollection, Shape, Worksheet, WorksheetCollection
onActivated Se produit lorsqu’un classeur est activé. Classeur
onAdded Se produit lorsqu’un objet est ajouté à la collection. ChartCollection, CommentCollection, TableCollection, WorksheetCollection
onAutoSaveSettingChanged Se produit lorsque le paramètre de autoSave est modifié dans le classeur. Classeur
onCalculated Se produit lorsqu’une feuille de calcul a terminé un calcul (ou que toutes les feuilles de calcul de la collection ont terminé). Worksheet, WorksheetCollection
onChanged Se produit lorsque les données de cellules ou de commentaires individuels ont changé. CommentCollection, Table, TableCollection, Worksheet, WorksheetCollection
onColumnSorted Se produit lorsqu’une ou plusieurs colonnes ont été triées. Ce problème se produit en raison de l’opération de tri de gauche à droite. Worksheet, WorksheetCollection
onDataChanged Se produit lors de la modification des données ou de la mise en forme dans la liaison. Binding
onDeactivated Se produit lorsqu’un objet est désactivé. Chart, ChartCollection, Shape, Worksheet, WorksheetCollection
onDeleted Se produit lorsqu’un objet est supprimé de la collection. ChartCollection, CommentCollection, TableCollection, WorksheetCollection
onFormatChanged Se produit lorsque le format est modifié sur une feuille de calcul. Worksheet, WorksheetCollection
onFormulaChanged Se produit lorsqu’une formule est modifiée. Worksheet, WorksheetCollection
onMoved Se produit lorsqu’une feuille de calcul est déplacée dans un classeur. WorksheetCollection
onNameChanged Se produit lorsque le nom de la feuille de calcul est modifié. Worksheet, WorksheetCollection
onProtectionChanged Se produit lorsque l’état de protection de la feuille de calcul est modifié. Worksheet, WorksheetCollection
onRowHiddenChanged Se produit lorsque l’état de ligne masquée change sur une feuille de calcul spécifique. Worksheet, WorksheetCollection
onRowSorted Se produit lorsqu’une ou plusieurs lignes ont été triées. Cela se produit en raison d’une opération de tri de haut en bas. Worksheet, WorksheetCollection
onSelectionChanged Se produit lorsque la cellule active ou la plage sélectionnée est modifiée. Liaison, Table, Classeur, Feuille de calcul, WorksheetCollection
onSettingsChanged Se produit lorsque les paramètres dans le document sont modifiés. SettingCollection
onSingleClicked Se produit lorsque l’opération clic gauche/tape se produit dans la feuille de calcul. Worksheet, WorksheetCollection
onVisibilityChanged Se produit lorsque la visibilité de la feuille de calcul est modifiée. Worksheet, WorksheetCollection

Événements en préversion

Remarque

Les événements suivants sont actuellement disponibles uniquement en préversion publique. Pour utiliser cette fonctionnalité, vous devez utiliser la préversion de la bibliothèque d’API JavaScript Office à partir du réseau de distribution de contenu (CDN)Office.js. Le fichier de définition de type pour la compilation et la IntelliSense TypeScript se trouve aux CDN et DefinitelyTyped. Vous pouvez installer ces types avec npm install --save-dev @types/office-js-preview . Pour plus d’informations sur notre API à venir, visitez Jeux d’exigences concernant l’API JavaScript pour Excel.

Événement Description Objets pris en charge
onFiltered Se produit lorsqu’un filtre est appliqué à un objet. Table, TableCollection, Worksheet, WorksheetCollection

Déclencheurs d’événements

Événements au sein d’un classeur Excel pouvant être déclenchés par :

  • Interaction de l’utilisateur via l’interface utilisateur Excel (IU) modifiant le classeur
  • Complément (JavaScript) Office modifiant le classeur
  • Complément VBA (macro) modifiant le classeur

Toute modification conforme aux comportements par défaut d’Excel déclenche les événements correspondants dans un classeur.

Cycle de vie d’un gestionnaire d’événements

Un gestionnaire d’événements est créé lorsqu’un complément inscrit le gestionnaire d’événements. Il est détruit lorsque le complément annule l’inscription du gestionnaire d’événements ou lorsque le complément est actualisé, rechargé ou fermé. Les gestionnaires d’événements ne sont pas conservés dans le fichier Excel ou entre des sessions avec Excel sur le web.

Attention

Lorsqu’un objet dans lequel des événements sont inscrits est supprimé (par exemple, un tableau avec un événement onChanged), le gestionnaire d’événements n’est plus déclenché mais reste en mémoire jusqu’à ce que le complément ou la session Excel soit actualisé(e) ou se ferme.

Événements et co-création

Avec la co-création, plusieurs personnes peuvent travailler ensemble et modifier le même classeur Excel simultanément. Pour les événements pouvant être déclenchés par un co-auteur, tels que onChanged, l’objet Event correspondant contient une propriété source qui indique si l’événement a été déclenché localement par l’utilisateur actuel (event.source = Local) ou par le co-auteur à distance (event.source = Remote).

Inscription d’un gestionnaire d’événements

L’exemple de code suivant inscrit un gestionnaire d’événements pour l’événement onChanged dans la feuille de calcul Sample. Le code indique que la fonction handleChange doit être exécutée lorsque les données de la feuille de calcul sont modifiées.

await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getItem("Sample");
    worksheet.onChanged.add(handleChange);

    await context.sync();
    console.log("Event handler successfully registered for onChanged event in the worksheet.");
}).catch(errorHandlerFunction);

Gestion d’un événement

Comme indiqué dans l’exemple précédent, lorsque vous inscrivez un gestionnaire d’événements, vous indiquez la fonction devant être exécutée lorsque l’événement spécifié se produit. Vous pouvez créer cette fonction pour effectuer n’importe quelle action nécessaire à votre scénario. L’exemple de code suivant montre une fonction de gestionnaire d’événements qui écrit simplement des informations sur l’événement dans la console.

async function handleChange(event) {
    await Excel.run(async (context) => {
        await context.sync();        
        console.log("Change type of event: " + event.changeType);
        console.log("Address of event: " + event.address);
        console.log("Source of event: " + event.source);       
    }).catch(errorHandlerFunction);
}

Suppression d’un gestionnaire d’événements

L’exemple de code suivant inscrit un gestionnaire d’événements pour l’événement onSelectionChanged dans la feuille de calcul Sample et définit la fonction handleSelectionChange qui est exécutée lorsqu’un événement se produit. Il définit également la fonction remove() pouvant être appelée par la suite pour supprimer ce gestionnaire d’événements. Notez que le RequestContext utilisé pour créer le gestionnaire d’événements est nécessaire pour le supprimer.

let eventResult;

async function run() {
  await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getItem("Sample");
    eventResult = worksheet.onSelectionChanged.add(handleSelectionChange);

    await context.sync();
    console.log("Event handler successfully registered for onSelectionChanged event in the worksheet.");
  });
}

async function handleSelectionChange(event) {
  await Excel.run(async (context) => {
    await context.sync();
    console.log("Address of current selection: " + event.address);
  });
}

async function remove() {
  await Excel.run(eventResult.context, async (context) => {
    eventResult.remove();
    await context.sync();
    
    eventResult = null;
    console.log("Event handler successfully removed.");
  });
}

Activation et désactivation d’événements

La performance d’un complément peut être améliorée en désactivant les événements. Par exemple, il se peut que votre application ne doive jamais recevoir d’événements, ou elle peut ignorer des événements lors de modifications par lots de plusieurs entités.

Les événements sont activés et désactivés au niveau runtime. La propriété enableEvents détermine si les événements sont déclenchés et leurs gestionnaires activés.

L’exemple de code suivant montre comment activer et désactiver des événements.

await Excel.run(async (context) => {
    context.runtime.load("enableEvents");
    await context.sync();

    let eventBoolean = !context.runtime.enableEvents;
    context.runtime.enableEvents = eventBoolean;
    if (eventBoolean) {
        console.log("Events are currently on.");
    } else {
        console.log("Events are currently off.");
    }
    
    await context.sync();
});

Voir aussi