Se connecter Office.js à n’importe quel framework JavaScript

Office.js est indépendant de l’infrastructure et fonctionne en toute transparence avec n’importe quelle bibliothèque ou infrastructure JavaScript côté client. Que vous générez avec React, Angular, Vue, Svelte ou toute autre infrastructure, le modèle d’intégration est le même : assurez-vous que Office.js s’initialise avant le rendu de votre application.

Remarque

Vous pouvez également utiliser des frameworks côté serveur tels que ASP.NET, PHP et Java pour créer des compléments Office, mais cet article ne les couvre pas. Cet article se concentre spécifiquement sur les frameworks JavaScript côté client qui s’exécutent dans le navigateur.

Cet article décrit les modèles universels d’intégration des Office.js avec les frameworks JavaScript côté client, ainsi que les considérations importantes et fournit des exemples sur plusieurs frameworks.

Conseil

Cet article est conçu pour les développeurs qui créent des compléments Office à partir de zéro à l’aide de leur infrastructure JavaScript préférée ou qui intègrent Office.js dans un projet d’infrastructure existant. Si vous utilisez le générateur Yeoman pour les compléments Office ou microsoft 365 Agents Toolkit, ces outils fournissent déjà la configuration Office.js correcte.

Configuration requise

Connaissance du framework JavaScript que vous avez choisi.
Compréhension de base des compléments Office. Consultez Vue d’ensemble de la plateforme des compléments Office.
Node.js installé pour la gestion des packages.

Démarrage rapide : Le modèle universel

Quelle que soit l’infrastructure que vous choisissez, utilisez le modèle suivant.

Référencez Office.js à partir du CDN dans votre code HTML <head>.
Appelez Office.onReady() et attendez qu’il se termine.
Initialisez votre infrastructure une fois Office.js prête.

// Universal pattern - works with any framework.
Office.onReady((info) => {
  // Office.js is now ready.
  // Initialize your framework here.
  initializeYourFramework();
});

Charger Office.js à partir du CDN

Vous devez référencer l’API JavaScript Office à partir du réseau de distribution de contenu (CDN) dans votre fichier HTML. Ajoutez la balise suivante <script> dans la <head> section de votre page HTML, avant les autres balises de script ou références de bundle d’infrastructure.

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>My Office Add-in</title>

  <!-- Office.js must be loaded from CDN, not bundled -->
  <script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>

  <!-- Your framework bundle loads after Office.js -->
</head>

Importante

Chargez Office.js à partir du CDN et référencez-le dans votre fichier HTML. Ne l’importez pas dans votre code JavaScript ou TypeScript.
La référence Office.js doit apparaître dans la <head> section pour garantir que l’API est entièrement initialisée avant le chargement des éléments de corps.
Ne regroupez pas Office.js avec le code de votre application. Référencez-la toujours à partir du CDN.

Pour plus d’informations sur le référencement de Office.js, notamment les API en préversion et les autres points de terminaison CDN, voir Référencement de la bibliothèque d’API JavaScript Office.

Initialiser votre infrastructure après Office.onReady

La clé pour intégrer Office.js à n’importe quelle infrastructure consiste à initialiser votre application à l’intérieur du Office.onReady() rappel. Cette approche garantit Office.js est entièrement initialisé avant le début du rendu de votre infrastructure. Cette initialisation est importante, car Office.js doit :

Téléchargez et mettez en cache les fichiers de bibliothèque d’API à partir du CDN.
Initialisez l’environnement d’exécution Office.
Établissez la communication avec l’application Office.

Si votre infrastructure s’affiche avant que Office.js ne soit prêt, les appels aux API Office échouent. En initialisant votre application dans Office.onReady(), vous garantissez Office.js est prêt lorsque votre code d’application s’exécute.

Exemples

Les exemples suivants illustrent le même modèle d’intégration dans différentes infrastructures. Le modèle est identique : seule la méthode d’initialisation de l’infrastructure change.

React

// src/index.tsx
Office.onReady(() => {
  const root = ReactDOM.createRoot(document.getElementById('root'));
  root.render(<App />);
});

Angle

// src/main.ts
Office.onReady(() => {
  platformBrowserDynamic()
    .bootstrapModule(AppModule)
    .catch(err => console.error(err));
});

Vue

// src/main.ts
Office.onReady(() => {
  createApp(App).mount('#app');
});

Svelte

// src/main.ts
Office.onReady(() => {
  new App({ target: document.getElementById('app') });
});

JavaScript simple sans framework

// src/app.js
Office.onReady((info) => {
  document.getElementById('run-button').onclick = run;

  if (info.host === Office.HostType.Excel) {
    console.log('Running in Excel');
  }
});

Utiliser des API Office.js dans votre application

Une fois Office.js initialisé (lorsque l’opération Office.onReady() est terminée), vous pouvez appeler les API Office n’importe où dans votre complément. Utilisez les hooks de cycle de vie ou les gestionnaires d’événements de votre infrastructure pour appeler les API Office si nécessaire.

// React example: Call an Office JS API in the useEffect lifecycle hook.
import { useEffect, useState } from 'react';

function MyComponent() {
  const [data, setData] = useState('');

  useEffect(() => {
    loadData();
  }, []);

  async function loadData() {
    await Excel.run(async (context) => {
      const range = context.workbook.getSelectedRange();
      range.load('values');
      await context.sync();

      // Update component state with the data from Excel.
      const value = range.values[0][0];
      setData(value);
    });
  }

  return <div>Selected cell: {data}</div>;
}

// Similar patterns for other frameworks:
// Angular: ngOnInit() { this.loadData(); }
// Vue: onMounted(() => { loadData(); })
// Svelte: onMount(() => { loadData(); })

Prise en charge de TypeScript

Pour activer IntelliSense et la vérification de type pour Office.js dans les projets TypeScript, installez les définitions de type à partir de DefinitelyTyped.

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

TypeScript reconnaît automatiquement les types. Vous n’avez pas besoin d’une instruction d’importation dans votre code, car Office.js est chargé globalement à partir du CDN.

// TypeScript automatically recognizes Office types.
Office.onReady((info: Office.OfficeInfo) => {
  if (info.host === Office.HostType.Excel) {
    // TypeScript provides IntelliSense for Excel APIs.
  }
});

Pour plus d’informations, consultez Référencement de la bibliothèque d’API JavaScript Office.

Autres considérations

Indicateurs de chargement

Si vous souhaitez afficher un indicateur de chargement pendant l’initialisation de Office.js, affichez-le avant d’appeler Office.onReady() et masquez-le à l’intérieur du rappel.

// Show loading indicator.
document.getElementById('loading')!.style.display = 'block';

Office.onReady((info) => {
  // Hide loading indicator.
  document.getElementById('loading')!.style.display = 'none';

  // Initialize framework.
  initializeYourFramework();
});

Pour une meilleure expérience utilisateur avec des frameworks qui ont leurs propres états de chargement, utilisez un chargeur HTML/CSS simple qui s’affiche immédiatement. Ensuite, laissez votre infrastructure prendre le relais une fois qu’elle est montée.

Cycle de vie des composants et de l’API de boîte de dialogue

L’API boîte de dialogue Office ouvre des pages dans des fenêtres de navigateur distinctes. Ce comportement a des implications importantes pour les applications framework :

Chaque boîte de dialogue crée un contexte d’exécution avec un instance de framework distinct.
La boîte de dialogue exécute sa propre copie du code de votre application.
Vous devez appeler Office.onReady() dans la page de boîte de dialogue.
La page principale et les fenêtres de dialogue ne partagent pas l’état.
Le stockage de session n’est pas partagé entre les contextes.

Si vous utilisez un routeur d’infrastructure pour accéder à un itinéraire de dialogue, n’oubliez pas que la fenêtre de dialogue crée une instance complète de votre application. Il ne réutilise pas le instance existant.

// Main page - opens a dialog.
Office.context.ui.displayDialogAsync(
  'https://localhost:3000/dialog-route',
  { height: 50, width: 50 },
  (result) => {
    if (result.status === Office.AsyncResultStatus.Succeeded) {
      const dialog = result.value;
      dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
        // Handle message from dialog.
      });
    } else {
      // Handle error opening the dialog.
      console.error(result.error);
    }
  }
);

// Dialog page - must also call Office.onReady.
Office.onReady(() => {
  // This is a separate framework instance.
  initializeYourFramework();
});

Solution de contournement de l’API d’historique

Office.js remplace les méthodes replaceStateWindow.history par défaut et pushState par null. Si votre infrastructure ou routeur dépend de ces méthodes (courantes dans React Router, Vue Router, Angular Router, etc.), vous devez les mettre en cache et les restaurer.

Ajoutez ce code à votre fichier HTML, en encapsulant la balise de script Office.js :

<head>
  <!-- Cache history methods before Office.js loads -->
  <script type="text/javascript">
    window._historyCache = {
      replaceState: window.history.replaceState,
      pushState: window.history.pushState
    };
  </script>

  <!-- Load Office.js -->
  <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>

  <!-- Restore history methods after Office.js loads -->
  <script type="text/javascript">
    window.history.replaceState = window._historyCache.replaceState;
    window.history.pushState = window._historyCache.pushState;
  </script>
</head>

Remarque

Cette solution de contournement n’est nécessaire que si votre application utilise le routage côté client (routeur React, routeur Vue, routeur Angular, etc.). Les applications statiques sans routage n’ont pas besoin de cette solution de contournement.

Test en dehors des applications Office

Vous pouvez développer et tester l’interface utilisateur de votre complément à l’aide des outils de développement du navigateur sans charger une version test dans Office. Cette approche permet une itération plus rapide pendant le développement et facilite le débogage de vos composants d’interface utilisateur.

Lorsque vous ouvrez votre complément dans un navigateur standard (en dehors d’une application Office), Office.onReady() s’exécute toujours, mais il se résout avec null pour les propriétés de l’hôte et de la plateforme.

Office.onReady((info) => {
  if (info?.host) {
    console.log(`Running in ${info.host} on ${info.platform}`);
  } else {
    console.log('Running outside of Office (development mode)');
  }

  // Initialize your framework, regardless of whether the add-in is running inside or outside of Office.
  initializeYourFramework();
});

Générer des outils et des bundlers

Les frameworks JavaScript modernes utilisent généralement des outils de génération tels que Webpack, Vite, Rollup ou esbuild. Lors de la configuration de votre build :

N’importez pas ou n’importez pas de Office.js dans votre code JavaScript ou TypeScript.
Chargez Office.js à partir du CDN à l’aide d’une <script> balise dans votre code HTML.
Configurez votre bundler pour qu’il soit traité Office comme une variable globale.

Exemple : configuration De TypeScript avec Vite

Si vous utilisez Vite avec TypeScript, vous n’avez généralement pas besoin d’une configuration Vite spéciale pour Office.js. Le @types/office-js package fournit les définitions de type nécessaires. Toutefois, si vous devez vous assurer que les types Office.js sont disponibles, vérifiez votre tsconfig.json:

// tsconfig.json
{
  "compilerOptions": {
    "types": ["office-js"]
    // ... your other compiler options ...
  }
}

Exemple : configuration de Webpack

// webpack.config.js
module.exports = {
  externals: {
    'office': 'Office'
  }
};

Les projets de complément générés par le générateur Yeoman pour les compléments Office incluent la configuration de build correcte par défaut.

Blocage réseau et pare-feu

Si les filtres réseau, les pare-feu ou les extensions de navigateur bloquent l'Office.js CDN, Office.onReady() ne se résout jamais. Envisagez d’implémenter un délai d’expiration pour les scénarios d’entreprise où les stratégies réseau peuvent bloquer le CDN.

let officeInitialized = false;

// Set a timeout.
setTimeout(() => {
  if (!officeInitialized) {
    console.error('Office.js failed to initialize. Network may be blocking CDN.');
    // Show error message to user.
  }
}, 10000); // 10 second timeout

Office.onReady((info) => {
  officeInitialized = true;
  initializeYourFramework();
});

Pour plus d’informations sur les considérations relatives au CDN, consultez Référencement de la bibliothèque d’API JavaScript Office.

Problèmes de réactivité ou de zone spécifiques à l’infrastructure

Certaines infrastructures utilisent des zones ou des systèmes de réactivité pour suivre les changements d’état. Dans de rares cas, les appels d’API Office ne déclenchent pas de mises à jour de l’interface utilisateur, car ils s’exécutent en dehors de la zone de détection des modifications de l’infrastructure.

Angular : si l’interface utilisateur ne se met pas à jour après les appels de l’API Office, encapsulez votre code dans NgZone.run():

import { NgZone } from '@angular/core';

constructor(private zone: NgZone) {}

async loadDataFromExcel() {
  let cellValue: string;

  // Make Office API call
  await Excel.run(async (context) => {
    const range = context.workbook.getSelectedRange();
    range.load('values');
    await context.sync();
    cellValue = range.values[0][0];
  });

  // Update Angular component state inside zone
  this.zone.run(() => {
    this.myData = cellValue;
  });
}

Voir aussi

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-02-04