Konfigurieren Ihres Office-Add-Ins für die Verwendung einer freigegebenen Runtime

Auf Desktopplattformen führt Ihr Add-In standardmäßig Code für Menübandschaltflächen, benutzerdefinierte Funktionen und den Aufgabenbereich in separaten Laufzeitumgebungen aus. Dies führt zu Einschränkungen, z. B. dass globale Daten nicht einfach freigegeben werden können und nicht über eine benutzerdefinierte Funktion auf alle CORS-Funktionen zugegriffen werden kann.

Sie können Ihr Office-Add-In jedoch so konfigurieren, dass Code in derselben Runtime (als freigegebene Runtime bezeichnet) freigegeben wird. Dies ermöglicht eine bessere Koordination im gesamten Add-in sowie Zugriff auf den Aufgabenbereich DOM und CORS aus allen Teilen des Add-Ins.

Das Konfigurieren einer freigegebenen Runtime ermöglicht die folgenden Szenarien.

• Ihr Office-Add-In kann zusätzliche UI-Features verwenden.
  • Ändern der Verfügbarkeit von Add-In-Befehlen
  • Ausführen von Code in Ihrem Office-Add-In, wenn ein Dokument geöffnet wird
  • Anzeigen oder Ausblenden des Aufgabenbereichs Ihres Office-Add-In
  • Hinzufügen benutzerdefinierter Tastenkombinationen zu Ihren Office-Add-Ins (unterstützt in Excel, PowerPoint und Word Add-Ins)
• Die folgenden sind nur für Excel-Add-Ins verfügbar.
  • Erstellen benutzerdefinierter kontextbezogener Registerkarten in Office-Add-Ins
  • Benutzerdefinierte Funktionen verfügen über vollständige CORS-Unterstützung.
  • Benutzerdefinierten Funktionen können Office.js-APIs zum Lesen von Daten in Tabellenkalkulationsdokumenten aufrufen.

In diesem Artikel wird der Prozess der Konfiguration eines Add-Ins für die Verwendung einer freigegebenen Runtime schrittweise erläutert.

Erstellen des Add-In-Projekts

Wenn Sie erfahren möchten, wie Sie ein Add-In in eine freigegebene Runtime konvertieren , erstellen Sie zunächst ein Add-In-Projekt, das noch nicht für die Verwendung einer freigegebenen Runtime als fortlaufendes Beispiel konfiguriert ist. Verwenden Sie das Agents Toolkit, um ein Aufgabenbereichprojekt zu erstellen, kein benutzerdefiniertes Funktionsprojekt. Anweisungen finden Sie unter Erstellen von Office-Add-In-Projekten mit dem Microsoft 365 Agents Toolkit.

Konfigurieren des Manifests

Führen Sie die folgenden Schritte aus, um ein Projekt für die Verwendung einer freigegebenen Runtime zu konfigurieren. Das fortlaufende Beispielprojekt verwendet das einheitliche Manifest.

Konfigurieren der Datei webpack.config.js

Im fortlaufenden Beispiel und wahrscheinlich in einem vorhandenen Add-In erstellt die webpack.config.js mehrere Laufzeitladeprogramme. Sie müssen sie so ändern, dass nur die freigegebene Runtime über die taskpane.html-Datei geladen wird.

1. Öffnen Sie die Datei webpack.config.js.

2. Wenn Ihre Datei webpack.config.js den folgenden Plug-In-Code commands.html enthält, dann entfernen Sie diesen.

   new HtmlWebpackPlugin({
       filename: "commands.html",
       template: "./src/commands/commands.html",
       chunks: ["polyfill", "commands"]
     })
   

3. Wenn Sie ein vorhandenes add-in für benutzerdefinierte Funktionen für die Verwendung einer freigegebenen Runtime konfigurieren, enthält die webpack.config.js-Datei den folgenden functions.html Plug-In-Code. Entfernen Sie ihn.

   new HtmlWebpackPlugin({
       filename: "functions.html",
       template: "./src/functions/functions.html",
       chunks: ["polyfill", "functions"]
     })
   

4. Wenn Ihr Projekt entweder die Funktionen oder Befehlsblöcke verwendet hat, fügen Sie sie der Blöckeliste für den Aufgabenbereich hinzu, wie im folgenden Code gezeigt.

     new HtmlWebpackPlugin({
       filename: "taskpane.html",
       template: "./src/taskpane/taskpane.html",
       chunks: ["polyfill", "taskpane", "commands", "functions"]
     })
   

5. Speichern Sie Ihre Änderungen, und erstellen Sie das Projekt neu.

   npm run build
   

Testen Ihrer Office-Add-In-Änderungen

Vergewissern Sie sich mit den folgenden Schritten, dass Sie die freigegebene Runtime ordnungsgemäß verwenden.

1. Öffnen Sie die taskpane.js Datei.

2. Kommentieren Sie den vorhandenen Code in der Datei aus, und fügen Sie dann den folgenden Code hinzu. Dieser Code zeigt an, wie oft der Aufgabenbereich geöffnet wurde. Das Hinzufügen des Ereignisses onVisibilityModeChanged wird nur in einer freigegebenen Runtime unterstützt.

   /*global document, Office*/
   
   let _count = 0;
   
   Office.onReady(() => {
     document.getElementById("sideload-msg").style.display = "none";
     document.getElementById("app-body").style.display = "flex";
   
     updateCount(); // Update count on first open.
     Office.addin.onVisibilityModeChanged((args) => {
       if (args.visibilityMode === Office.VisibilityMode.taskpane) {
         updateCount(); // Update count on subsequent opens.
       }
     });
   });
   
   function updateCount() {
     _count++;
     document.getElementById("run").textContent = "Task pane opened " + _count + " times.";
   }
   

3. Speichern Sie die Änderungen, und führen Sie die Projekt aus.

   npm start
   

Jedes Mal, wenn Sie den Aufgabenbereich öffnen, wird die Anzahl der Geöffneten erhöht. Der Wert von _count geht nicht verloren, da die freigegebene Runtime ihren Code weiterhin ausführt, auch wenn der Aufgabenbereich geschlossen ist.

Wenn Sie die Tests abgeschlossen haben, befolgen Sie die bewährten Methoden, um den Entwicklungsserver zu beenden und das Add-In zu deinstallieren, wie unter Verwenden der Deinstallationsfunktion Ihres Tools beschrieben. Stellen Sie dann den ursprünglichen Code von taskpane.jswieder her.

Bewährte Methode: Vermeiden mehrerer Aufgabenbereiche

Eine freigegebene Runtime unterstützt nur einen Aufgabenbereich, obwohl dieser Aufgabenbereich mehrere Seiten enthalten kann. Die Implementierung dieser Vorgehensweise hängt vom Typ des Manifests ab.

• Einheitliches Manifest für Microsoft 365: In dem Laufzeitobjekt, das mit einer "long" Lebensdauer konfiguriert ist, sollte keines der Objekte im "actions" Array über eine "view" -Eigenschaft verfügen.
• Nur Add-In-Manifest: Im Vorgängerelement <Host> , das über ein nachfolgerfähiges <Runtime> Element verfügt, das auf eine long Lebensdauer festgelegt ist, sollte keines der nachfolgerbasierten <Action> Elemente ein untergeordnetes <TaskpaneID> Element aufweisen.

Siehe auch

• Aufrufen von Excel-APIs aus einer benutzerdefinierten Funktion
• Hinzufügen benutzerdefinierter Tastenkombinationen zu Ihren Office-Add-Ins
• Erstellen benutzerdefinierter kontextbezogener Registerkarten in Office-Add-Ins
• Ändern der Verfügbarkeit von Add-In-Befehlen
• Ausführen von Code in Ihrem Office-Add-In, wenn ein Dokument geöffnet wird
• Anzeigen oder Ausblenden des Aufgabenbereichs Ihres Office-Add-In
• Tutorial: Daten und Ereignisse zwischen benutzerdefinierten Excel-Funktionen und dem Aufgabenbereich freigeben
• Runtimes in Office-Add-Ins