Utiliser des événements à l’aide de l’API JavaScript Word

Article
2024-07-16

Cet article décrit les concepts importants liés à l’utilisation des événements dans Word et fournit des exemples de code qui montrent 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 Word.

Événements dans Word

Lorsque certaines modifications se produisent dans un document Word, les notifications d’événements se déclenchent. Les API JavaScript Word vous permettent d’inscrire des gestionnaires d’événements qui permettent à votre complément d’exécuter automatiquement des fonctions désignées lorsque ces modifications se produisent. Les événements suivants sont actuellement pris en charge.

Événement	Description	Objets pris en charge	Déclenché pendant la co-création ?
`onAnnotationClicked`	Se produit lorsque l’utilisateur sélectionne une annotation. Objet de données d’événement : AnnotationClickedEventArgs	Document	Non
`onAnnotationHovered`	Se produit lorsque l’utilisateur place le curseur sur une annotation. Objet de données d’événement : AnnotationHoveredEventArgs	Document	Non
`onAnnotationInserted`	Se produit lorsque l’utilisateur ajoute une ou plusieurs annotations. Objet de données d’événement : AnnotationInsertedEventArgs	Document	Non
`onAnnotationPopupAction`	Se produit lorsque l’utilisateur effectue une action dans un menu contextuel d’annotation. Objet de données d’événement : AnnotationPopupActionEventArgs	Document	Non
`onAnnotationRemoved`	Se produit lorsque l’utilisateur supprime une ou plusieurs annotations. Objet de données d’événement : AnnotationRemovedEventArgs	Document	Non
`onContentControlAdded`	Se produit lorsqu’un contrôle de contenu est ajouté. Exécutez `context.sync()` dans le gestionnaire pour obtenir les propriétés du nouveau contrôle de contenu. Objet de données d’événement : ContentControlAddedEventArgs	Document	Oui
`onDataChanged`	Se produit lorsque les données du contrôle de contenu sont modifiées. Pour obtenir le nouveau texte, chargez ce contrôle de contenu dans le gestionnaire. Pour obtenir l’ancien texte, ne le chargez pas. Objet de données d’événement : ContentControlDataChangedEventArgs	ContentControl	Oui
`onDeleted`	Se produit lorsque le contrôle de contenu est supprimé. Ne chargez pas ce contrôle de contenu dans le gestionnaire, sinon vous ne pourrez pas obtenir ses propriétés d’origine. Objet de données d’événement : ContentControlDeletedEventArgs	ContentControl	Oui
`onEntered`	Se produit lorsque le contrôle de contenu est entré. Objet de données d’événement : ContentControlEnteredEventArgs	ContentControl	Oui
`onExited`	Se produit lorsque le contrôle de contenu est arrêté, par exemple lorsque le curseur quitte le contrôle de contenu. Objet de données d’événement : ContentControlExitedEventArgs	ContentControl	Oui
`onParagraphAdded`	Se produit lorsque l’utilisateur ajoute de nouveaux paragraphes. Objet de données d’événement : ParagraphAddedEventArgs	Document	Oui
`onParagraphChanged`	Se produit lorsque l’utilisateur modifie des paragraphes. Objet de données d’événement : ParagraphChangedEventArgs	Document	Oui
`onParagraphDeleted`	Se produit lorsque l’utilisateur supprime des paragraphes. Objet de données d’événement : ParagraphDeletedEventArgs	Document	Oui
`onSelectionChanged`	Se produit lorsque la sélection dans le contrôle de contenu est modifiée. Objet de données d’événement : ContentControlSelectionChangedEventArgs	ContentControl	Oui

É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 .

Événement	Description	Objets pris en charge	Déclenché pendant la co-création ?
`onCommentAdded`	Se produit lorsque de nouveaux commentaires sont ajoutés. Objet de données d’événement : CommentEventArgs	Body ContentControl Paragraphe Range	Oui
`onCommentChanged`	Se produit lorsqu’un commentaire ou sa réponse est modifié. Objet de données d’événement : CommentEventArgs	Body ContentControl Paragraphe Range	Oui
`onCommentDeleted`	Se produit lorsque les commentaires sont supprimés. Objet de données d’événement : CommentEventArgs	Body Paragraphe	Oui
`onCommentDeselected`	Se produit lorsqu’un commentaire est désélectionné. Objet de données d’événement : CommentEventArgs	Body ContentControl Paragraphe Range	Oui
`onCommentSelected`	Se produit lorsqu’un commentaire est sélectionné. Objet de données d’événement : CommentEventArgs	Body ContentControl Paragraphe Range	Oui

Déclencheurs d’événements

Les événements au sein d’un document Word peuvent être déclenchés par :

Interaction utilisateur via l’interface utilisateur Word qui modifie le document.
Code du complément Office (JavaScript) qui modifie le document.
Code de complément VBA (macro) qui modifie le document.
Co-auteur qui modifie à distance le document à l’aide de l’interface utilisateur Word ou du code de complément. Pour plus d’informations, consultez Événements et co-création.

Toute modification conforme au comportement par défaut de Word déclenche les événements correspondants dans un document.

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 Word ou entre les sessions avec Word sur le web.

Événements et co-création

Avec la co-création, plusieurs personnes peuvent collaborer et modifier simultanément le même document Word. Pour les événements pouvant être déclenchés par un co-auteur, tels que onParagraphChanged, 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).

Les événements qui utilisent les objets de données suivants sont déclenchés pendant la co-création.

CommentEventArgs (aperçu)
ContentControlAddedEventArgs
ContentControlDataChangedEventArgs
ContentControlDeletedEventArgs
ContentControlEnteredEventArgs
ContentControlExitedEventArgs
ContentControlSelectionChangedEventArgs
ParagraphAddedEventArgs
ParagraphChangedEventArgs
ParagraphDeletedEventArgs

Inscription d’un gestionnaire d’événements

L’exemple de code suivant inscrit un gestionnaire d’événements pour l’événement onParagraphChanged dans le document. Le code spécifie que lorsque le contenu change dans le document, la fonction s’exécute handleChange .

await Word.run(async (context) => {
    eventContext = context.document.onParagraphChanged.add(handleChange);

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

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 Word.run(async (context) => {
        await context.sync();        
        console.log("Type of event: " + event.type);
        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 onParagraphChanged dans le document et définit la handleChange fonction qui s’exécutera lorsque l’événement se produira. Il définit également la fonction deregisterEventHandler() 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 eventContext;

async function registerEventHandler() {
  await Word.run(async (context) => {
    eventContext = context.document.onParagraphChanged.add(handleChange);

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

async function handleChange(event: Word.ParagraphChangedEventArgs) {
  await Word.run(async (context) => {
    await context.sync();
    console.log(`${event.type} event was detected.`);
  });
}

async function deregisterEventHandler() {
  // The `RequestContext` used to create the event handler is needed to remove it.
  // In this example, `eventContext` is being used to keep track of that context.
  await Word.run(eventContext.context, async (context) => {
    eventContext.remove();
    await context.sync();
    
    eventContext = null;
    console.log("Removed event handler that was tracking content changes in paragraphs.");
  });
}

Utiliser .track()

Certains types d’événements vous obligent également à appeler track() sur l’objet auquel vous ajoutez l’événement.

Événements de contrôle de contenu
- onDataChanged
- onDeleted
- onEntered
- onExited
- onSelectionChanged
Événements de commentaire (préversion)
- onCommentAdded
- onCommentChanged
- onCommentDeleted
- onCommentDeselected
- onCommentSelected

L’exemple de code suivant montre comment inscrire un gestionnaire d’événements sur chaque contrôle de contenu. Étant donné que vous ajoutez l’événement aux contrôles de contenu, track() est appelé sur chaque contrôle de contenu de la collection.

let eventContexts = [];

await Word.run(async (context) => {
  const contentControls: Word.ContentControlCollection = context.document.contentControls;
  contentControls.load("items");
  await context.sync();

  // Register the onDeleted event handler on each content control.
  if (contentControls.items.length === 0) {
    console.log("There aren't any content controls in this document so can't register event handlers.");
  } else {
    for (let i = 0; i < contentControls.items.length; i++) {
      eventContexts[i] = contentControls.items[i].onDeleted.add(contentControlDeleted);

      // Call track() on each content control.
      contentControls.items[i].track();
    }

    await context.sync();

    console.log("Added event handlers for when content controls are deleted.");
  }
});

L’exemple de code suivant montre comment inscrire des gestionnaires d’événements de commentaire sur l’objet body du document et inclut un body.track() appel.

let eventContexts = [];

// Registers event handlers.
await Word.run(async (context) => {
  const body: Word.Body = context.document.body;

  // Track the body object since you're adding comment events to it.
  body.track();
  await context.sync();

  eventContexts[0] = body.onCommentAdded.add(onEventHandler);
  eventContexts[1] = body.onCommentChanged.add(onChangedHandler);
  eventContexts[2] = body.onCommentDeleted.add(onEventHandler);
  eventContexts[3] = body.onCommentDeselected.add(onEventHandler);
  eventContexts[4] = body.onCommentSelected.add(onEventHandler);
  await context.sync();

  console.log("Event handlers registered.");
});

Voir aussi

Modèle d’objet JavaScript Word dans les compléments Office
Ces exemples et d’autres sont disponibles dans notre outil Script Lab :

Partager via