Référencement de la bibliothèque de l’API JavaScript Office

La bibliothèque d’API JavaScript Office fournit les API que votre complément peut utiliser pour interagir avec l’application Office. Le moyen le plus simple de référencer la bibliothèque consiste à utiliser le réseau de distribution de contenu (CDN) en ajoutant la balise suivante <script> dans la <head> section de votre page HTML.

<head>
    ...
    <script src="https://officeapis.public.onecdn.static.microsoft/1/office.js" type="text/javascript"></script>
</head>

Cette approche télécharge et met en cache les fichiers d’API JavaScript Office lors du premier chargement de votre complément. Il garantit que votre complément utilise l’implémentation la plus récente de Office.js et ses fichiers associés pour la version spécifiée.

Le CDN utilise le domaine dans le officeapis.public.onecdn.static.microsoft cadre du domaine unifié pour les applications et services Microsoft 365.

Office.js comportement de l’API web spécifique

Office.js remplace les méthodes Window.history par défaut de replaceState et pushState par null. Si votre complément s’appuie sur ces méthodes, remplacez la référence de la bibliothèque Office.js par la solution de contournement suivante.

<script type="text/javascript">
    // Cache the history method values.
    window._historyCache = {
        replaceState: window.history.replaceState,
        pushState: window.history.pushState
    };
</script>

<script type="text/javascript" src="https://officeapis.public.onecdn.static.microsoft/1/office.js"></script>

<script type="text/javascript">
    // Restore the history method values after loading Office.js
    window.history.replaceState = window._historyCache.replaceState;
    window.history.pushState = window._historyCache.pushState;
</script>

Merci à @stepper et à la communauté Stack Overflow d’avoir suggéré et vérifié cette solution de contournement.

Solution de contournement pour Next.js

La solution de contournement précédente ne fonctionne pas dans Next.js, car Next.js gère la page <head> et son routeur côté client dépend des méthodes d’historique. Empêchez plutôt Office.js de remplacer les méthodes. Ajoutez le script suivant afin qu’il s’exécute avant le chargement de Office.js. Par exemple, dans un projet qui utilise App Router, ajoutez-le à l’entrée <head>app/layout.tsx avant le script Office.js.

<script
  dangerouslySetInnerHTML={{
    __html: `
      ["replaceState", "pushState"].forEach((methodName) => {
        let browserMethod = window.history[methodName];
        Object.defineProperty(window.history, methodName, {
          configurable: true,
          get: () => browserMethod,
          set: (value) => {
            if (typeof value === "function") {
              browserMethod = value;
            }
          },
        });
      });
    `,
  }}
/>
<script type="text/javascript" src="https://officeapis.public.onecdn.static.microsoft/1/office.js" />

Contrôle de version d’API et compatibilité descendante

Dans l’extrait de code HTML précédent, l’URL /1/ CDN précédente office.js spécifie la dernière version incrémentielle dans la version 1 de Office.js. Étant donné que l’API JavaScript Office maintient la compatibilité descendante, la dernière version continue à prendre en charge les membres de l’API qui ont été introduits précédemment dans la version 1.

Si vous envisagez de publier votre complément Office sur la Place de marché Microsoft Marketplace, vous devez utiliser cette référence CDN. Utilisez des références locales uniquement pour les scénarios internes, de développement et de débogage.

Activation d’IntelliSense pour un projet TypeScript

En plus de référencer l’API JavaScript Office comme décrit précédemment, vous pouvez également activer IntelliSense pour un projet de complément TypeScript à l’aide des définitions de type de DefinitelyTyped. Pour ce faire, exécutez la commande suivante dans une invite système compatible avec Node (ou une fenêtre git bash) à partir de la racine du dossier de votre projet. Node.js doit être installé (qui inclut npm).

npm install --save-dev @types/office-js

API en préversion

Microsoft introduit pour la première fois de nouvelles API JavaScript en « préversion ». Après suffisamment de tests et de commentaires des utilisateurs, les API font partie d’un ensemble d’exigences numéroté spécifique.

Références CDN pour d’autres environnements Microsoft 365

21Vianet exploite et gère un service Office 365 optimisé par les technologies Microsoft sous licence pour fournir des services Office 365 pour la Chine conformes à la législation et réglementations locales. Les compléments développés pour être utilisés dans cet environnement cloud doivent utiliser le CDN correspondant. À utiliser https://appsforoffice.cdn.partner.office365.cn/appsforoffice/lib/1/hosted/office.js à la place de la référence CDN standard. Cela garantit une conformité continue et améliore les performances des compléments.

Mettre à jour les points de terminaison CDN hérités

Auparavant, la bibliothèque Office.js était servie à partir du https://appsforoffice.microsoft.com/lib/1/hosted/office.js point de terminaison. Pour basculer vers le nouveau point de terminaison Office.js CDN, mettez à jour la référence de script Office.js dans chaque page de complément de https://appsforoffice.microsoft.com/lib/1/hosted/office.js à https://officeapis.public.onecdn.static.microsoft/1/office.js. Le nouveau point de terminaison sert la même version Office.js actuelle, mais il active des valeurs sécurisées supplémentaires par défaut. Avant le basculement :

• Si votre complément repose sur des globaux Microsoft Ajax qui Office.js précédemment chargés automatiquement, remplacez cette dépendance par une alternative prise en charge ou chargez et gérez directement la bibliothèque requise.
• Si votre complément utilise ExecuteFunction des commandes, enregistrez chaque gestionnaire de commandes à l’aide Office.actions.associate(...)de .
• Si votre complément ou votre organization utilise des paramètres restrictifs de stratégie de sécurité du contenu ou de types de confiance, vérifiez que le nouveau point de terminaison et Office.js stratégie de types de confiance sont autorisés.
• Assurez-vous que cette autorisation *.static.microsoft est autorisée par toutes les listes vertes réseau applicables.
• Testez le complément dans ses applications et environnements Office pris en charge, notamment l’activation, les commandes et les boîtes de dialogue.

Voir aussi

• Compréhension de l’API JavaScript pour Office
• API JavaScript pour Office
• Instructions pour le déploiement de compléments Office sur les clouds du secteur public
• Termes du contrat de licence logiciel Microsoft pour la bibliothèque d’API Microsoft Office JavaScript (Office.js)