Prise en charge de l’API JavaScript Office pour les compléments de contenu et de volet Office

Importante

Cet article s’applique aux API communes, le modèle d’API JavaScript Office qui a été introduit avec Office 2013. Ces API comprennent des fonctionnalités telles qu’une interface utilisateur, des boîtes de dialogue et des paramètres du client, qui sont communes à plusieurs types d’applications Office. Les compléments Outlook utilisent uniquement les API communes, notamment le sous-ensemble d’API exposées via l’objet Boîte aux lettres .

Vous devriez utiliser les API communes uniquement pour les scénarios qui ne sont pas pris en charge par les API spécifiques de l’application. Pour savoir quand utiliser les API communes au lieu des API propres aux applications, consultez Comprendre l’API JavaScript Office.

Vous pouvez utiliser l’API JavaScript Office pour créer des compléments de volet Office ou de contenu pour les applications clientes Office. Les méthodes et les objets pris en charge par les compléments du volet Office et de contenu sont classés de la manière suivante :

1. Objets communs partagés avec d’autres compléments Office. Ces objets incluent Office, Context et AsyncResult. L’objet Office est l’objet racine de l’API JavaScript Office. L’objet Context représente l’environnement d’exécution du complément. et OfficeContext sont les objets fondamentaux de n’importe quel complément Office. L’objet AsyncResult représente les résultats d’une opération asynchrone, comme les données retournées à la getSelectedDataAsync méthode , qui lit ce qu’un utilisateur a sélectionné dans un document.

2. Objet Document. La majorité des éléments de l’API disponibles pour les compléments de contenu et du volet Office sont exposés via les méthodes, propriétés et événements de l’objet Document. Un complément de contenu ou de volet Office peut utiliser la propriété Office.context.document pour accéder à l’objet Document et, via celui-ci, peut accéder aux membres clés de l’API pour l’utilisation des données dans des documents, tels que les objets Bindings et CustomXmlParts , ainsi que les méthodes getSelectedDataAsync, setSelectedDataAsync et getFileAsync . L’objet Document fournit également la propriété mode pour déterminer si un document est en lecture seule ou en mode édition, la propriété URL pour obtenir l’URL du document actif et l’accès à l’objet Settings . L’objet Document prend également en charge l’ajout de gestionnaires d’événements pour l’événement SelectionChanged , ce qui vous permet de détecter quand un utilisateur modifie sa sélection dans le document.

   Un complément de contenu ou de volet Office peut accéder à l’objet Document uniquement après le chargement du DOM et de l’environnement d’exécution, généralement dans le gestionnaire d’événements pour l’événement Office.initialize . Pour plus d’informations sur le flux d’événements lors de l’initialisation d’un complément et sur la vérification du chargement correct du DOM et de l’environnement d’exécution, voir la page relative au chargement du DOM et de l’environnement d’exécution.

3. Objets pour l’utilisation de fonctionnalités spécifiques. Pour utiliser des fonctionnalités spécifiques de l’API, utilisez les objets et méthodes suivants.

   • Les objets CustomXmlParts, CustomXmlPart et les objets associés pour créer et manipuler des parties XML personnalisées dans des documents Word.

   • Les objets CustomXmlParts et CustomXmlPart et les objets associés pour créer et manipuler des parties XML personnalisées dans des documents Word.

   • Les objets File et Slice pour créer une copie de l’intégralité du document, le diviser en blocs ou en « sections », puis lire ou transmettre les données dans ces sections.

   • L’objet Settings pour enregistrer des données personnalisées, telles que des préférences utilisateur et l’état du complément.

Importante

Certains des membres d’API ne sont pas pris en charge dans toutes les applications Office pouvant héberger des compléments de contenu et du volet Office. Pour déterminer les membres pris en charge, voir les ressources suivantes :

Pour obtenir un résumé de la prise en charge de l’API JavaScript Office dans les applications clientes Office, consultez Présentation de l’API JavaScript Office.

Lire et écrire dans une sélection active dans un document, une feuille de calcul ou une présentation

Vous pouvez lire ou écrire dans la sélection en cours de l’utilisateur dans un document, une feuille de calcul ou une présentation. Selon l’application Office de votre complément, vous pouvez spécifier le type de structure de données à lire ou écrire en tant que paramètre dans les méthodes getSelectedDataAsync et setSelectedDataAsync de l’objet Document . Par exemple, vous pouvez indiquer n’importe quel type de données (HTML, données tabulaires, Office Open XML ou texte) pour Word, des données texte et tabulaires pour Excel et des données texte pour PowerPoint et Project. Vous pouvez également créer des gestionnaires d’événements pour détecter les modifications apportées à la sélection de l’utilisateur. L’exemple suivant obtient des données de la sélection sous forme de texte à l’aide de la getSelectedDataAsync méthode .

Office.context.document.getSelectedDataAsync(
    Office.CoercionType.Text, function (asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write('Action failed. Error: ' + asyncResult.error.message);
        }
        else {
            write('Selected data: ' + asyncResult.value);
        }
    });

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

Pour plus d’informations et d’exemples, reportez-vous à l’article Lecture et écriture de données dans la sélection active d’un document ou d’une feuille de calcul.

Lier à une région dans un document ou une feuille de calcul

Vous pouvez utiliser les getSelectedDataAsync méthodes et setSelectedDataAsync pour lire ou écrire dans la sélection actuelle de l’utilisateur dans un document, une feuille de calcul ou une présentation. Toutefois, si vous souhaitez accéder à la même région dans un document via des sessions d’exécution de votre complément sans demander à l’utilisateur d’effectuer une sélection, vous devez d’abord établir une liaison avec cette région. Avec une liaison, vous pouvez également vous abonner à des données et à des événements de modification de sélection, uniquement pour la région liée.

Vous pouvez ajouter une liaison à l’aide des méthodes addFromNamedItemAsync, addFromPromptAsync ou addFromSelectionAsync de l’objet Bindings. Ces méthodes renvoient un identificateur que vous pouvez ensuite utiliser pour accéder aux données de la liaison ou pour vous abonner à ses événements de modification de données ou de sélection.

Voici un exemple qui ajoute une liaison au texte actuellement sélectionné dans un document, à l’aide de la Bindings.addFromSelectionAsync méthode .

Office.context.document.bindings.addFromSelectionAsync(
    Office.BindingType.Text, { id: 'myBinding' }, function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write('Added new binding with type: ' +
            asyncResult.value.type + ' and id: ' + asyncResult.value.id);
    }
});

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Pour plus d’informations et d’exemples, reportez-vous à l’article Liaisons de régions dans un document ou une feuille de calcul.

Obtenir des documents entiers

Si votre complément du volet Office s’exécute dans PowerPoint ou Word, vous pouvez utiliser les méthodes Document.getFileAsync, File.getSliceAsync et File.closeAsync pour obtenir la totalité d’une présentation ou d’un document.

Lorsque vous appelez Document.getFileAsync , vous obtenez une copie du document dans un objet File . L’objet File fournit l’accès au document en « blocs » représentés sous forme d’objets Slice . Lorsque vous appelez getFileAsync, vous pouvez spécifier le type de fichier (texte ou format Open Office XML compressé) et la taille des tranches (jusqu’à 4 Mo). Pour accéder au contenu de l’objet File , vous appelez File.getSliceAsync ensuite qui retourne les données brutes dans la propriété Slice.data . Si vous avez spécifié un format compressé, vous obtiendrez les données du fichier sous la forme d’un tableau d’octets. Si vous transférez le fichier à un service web, vous pouvez transformer les données brutes compressées dans une chaîne codée en Base64 avant l’envoi. Enfin, lorsque vous avez terminé d’obtenir des tranches du fichier, utilisez la File.closeAsync méthode pour fermer le document.

Pour plus d’informations, reportez-vous à l’article expliquant comment obtenir l’intégralité d’un document à partir d’un complément pour PowerPoint ou Word.

Lire et écrire des parties XML personnalisées d’un document Word

Using the Open Office XML file format and content controls, you can add custom XML parts to a Word document and bind elements in the XML parts to content controls in that document. When you open the document, Word reads and automatically populates bound content controls with data from the custom XML parts. Users can also write data into the content controls, and when the user saves the document, the data in the controls will be saved to the bound XML parts. Task pane add-ins for Word, can use the Document.customXmlParts property,CustomXmlParts, CustomXmlPart, and CustomXmlNode objects to read and write data dynamically to the document.

Les parties XML personnalisées peuvent être associées à des espaces de noms. Pour obtenir des données à partir des parties XML personnalisées dans un espace de noms, utilisez la méthode CustomXmlParts.getByNamespaceAsync.

Vous pouvez également utiliser la CustomXmlParts.getByIdAsync pour accéder aux parties XML personnalisées par leur GUID. Après avoir obtenu une partie XML personnalisée, utilisez la méthode CustomXmlPart.getXmlAsync pour obtenir les données XML.

Pour ajouter un nouveau composant XML personnalisé à un document, utilisez la Document.customXmlParts propriété pour obtenir les parties XML personnalisées qui se trouvent dans le document et appelez la méthode CustomXmlParts.addAsync .

Pour plus d’informations sur la gestion des composants XML personnalisés avec un complément du volet Office, voir Comprendre quand et comment utiliser Office Open XML dans votre complément Word.

Persistance des paramètres de complément

Vous devez souvent enregistrer les données personnalisées pour votre complément, telles que les préférences d’un utilisateur ou l’état du complément, et accéder à ces données lors de la prochaine ouverture du complément. Vous pouvez utiliser des techniques de programmation web courantes pour enregistrer les données, comme les cookies de navigateur ou le stockage web HTML 5. Si votre complément est également exécuté dans Excel, PowerPoint ou Word, vous pouvez également utiliser les méthodes de l’objet Settings. Les données créées avec l’objet Settings sont stockées dans la feuille de calcul, la présentation ou le document dans lequel le complément a été inséré et enregistré. Ces données sont disponibles seulement pour le complément qui les a créées.

Pour éviter les allers-retours vers le serveur où le document est stocké, les données créées avec l’objet Settings sont gérées en mémoire au moment de l’exécution. Les données de paramètres enregistrées précédemment sont chargées en mémoire lors de l’initialisation du complément et les modifications apportées à ces données sont uniquement enregistrées dans le document quand vous appelez la méthode Settings.saveAsync. En interne, les données sont stockées dans un objet JSON sérialisé en tant que paires nom/valeur. Vous pouvez utiliser les méthodes get, set et remove de l’objet Settings pour lire, écrire et supprimer des éléments dans la copie en mémoire des données. La ligne de code suivante explique comment créer un paramètre nommé themeColor et définir sa valeur sur « green ».

Office.context.document.settings.set('themeColor', 'green');

Étant donné que les données de paramètres créées ou supprimées avec les set méthodes et remove agissent sur une copie en mémoire des données, vous devez appeler pour conserver saveAsync les modifications apportées aux données de paramètres dans le document avec lequel votre complément fonctionne.

Pour plus d’informations sur l’utilisation de données personnalisées à l’aide des méthodes de l’objet Settings , consultez Persistance de l’état et des paramètres du complément.

Modèle d’autorisations et gouvernance

Votre complément utilise le manifeste de l’application pour demander l’autorisation d’accéder au niveau de fonctionnalité dont il a besoin à partir de l’API JavaScript Office. La méthode varie en fonction du type de manifeste.

• Manifeste unifié pour Microsoft 365 : utilisez la propriété « authorization.permissions.resourceSpecific ». Par exemple, si votre complément nécessite un accès en lecture/écriture au document, son manifeste doit spécifier Document.ReadWrite.User comme valeur dans sa propriété « authorization.permissions.resourceSpecific.name ». L’exemple suivant demande l’autorisation de lecture du document , qui autorise uniquement les méthodes qui peuvent lire (mais pas écrire dans) le document.

  "authorization": {
      "permissions": {
        "resourceSpecific": [
          ...
          {
            "name": "Document.Read.User",
            "type": "Delegated"
          },
        ]
      }
  },
  

  Remarque

  Le manifeste unifié pour Microsoft 365 peut être utilisé dans les compléments Outlook de production. Il est disponible uniquement en préversion pour les compléments Excel, PowerPoint et Word.

• Manifeste de complément uniquement : utilisez l’élément Permissions dans le manifeste Par exemple, si votre complément nécessite un accès en lecture/écriture au document, son manifeste doit spécifier ReadWriteDocument comme valeur de texte dans son Permissions élément. Étant donné que les autorisations ont pour objectif de protéger la vie privée et la sécurité de l’utilisateur, en tant que meilleures pratiques, nous vous recommandons de demander le niveau d’autorisation minimal requis pour ses fonctionnalités. L’exemple suivant montre comment demander l’autorisation de lecture de document dans le manifeste d’un volet Office.

  <?xml version="1.0" encoding="utf-8"?>
  <OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:type="TaskPaneApp">
      <!-- Other manifest elements omitted. -->
      <Permissions>ReadDocument</Permissions>
      ...
  </OfficeApp>
  

Pour plus d’informations, consultez Demande d’autorisations pour l’utilisation d’API dans les compléments.

Voir aussi

• API JavaScript pour Office
• Référence de schéma pour les manifestes des compléments Office
• Résolution des erreurs rencontrées par l’utilisateur avec des compléments Office
• Temps d'exécution dans les compléments Office