Freigeben über

Implementieren der ereignisbasierten Aktivierung in Excel-, PowerPoint- und Word-Add-Ins

Die ereignisbasierte Aktivierung startet automatisch ein zentral bereitgestelltes Word-, Excel- oder PowerPoint-Add-In, wenn ein Dokument erstellt oder geöffnet wird. Dadurch kann das Add-In kritische Inhalte ohne manuelle Vorgänge überprüfen, einfügen oder aktualisieren. Das Add-In wird im Hintergrund geöffnet, um zu vermeiden, dass der Benutzer gestört wird.

Hinweis

Informationen zum Implementieren der ereignisbasierten Aktivierung für Outlook-Add-Ins finden Sie unter Konfigurieren Ihres Outlook-Add-Ins für die ereignisbasierte Aktivierung.

Unterstützte Ereignisse und Clients

Ereignisname Beschreibung Unterstützte Clients und Kanäle
OnDocumentOpened Tritt auf, wenn ein Benutzer ein Dokument öffnet oder ein neues Dokument, eine neue Kalkulationstabelle oder Präsentation erstellt.
  • Windows (Build >= 16.0.18324.20032)
  • Office im Web
  • Office für Mac wird später verfügbar sein

Verhalten und Einschränkungen

Beachten Sie bei der Entwicklung eines ereignisbasierten Add-Ins die folgenden Featureverhalten und Einschränkungen.

  • Office auf macos wird nicht unterstützt.
  • Das einheitliche Manifest wird nicht unterstützt.
  • Ereignisbasierte Add-Ins funktionieren nur, wenn sie von einem Administrator bereitgestellt werden. Wenn Benutzer sie direkt aus AppSource oder dem Office Store installieren, werden sie nicht automatisch gestartet. Admin Bereitstellungen erfolgen durch Hochladen des Manifests in die Microsoft 365 Admin Center.
  • Wenn ein Benutzer mehrere Add-Ins installiert, die dasselbe Aktivierungsereignis behandeln, wird nur ein Add-In aktiviert. Es gibt keine deterministische Möglichkeit, zu wissen, welches Add-In aktiviert wird. Wenn z. B. mehrere Add-Ins ausgeführt werden, die behandeln OnDocumentOpened, wird nur einer dieser Handler ausgeführt.
  • APIs, die mit der Benutzeroberfläche interagieren oder UI-Elemente anzeigen, werden für Word, PowerPoint und Excel unter Windows nicht unterstützt. Dies liegt daran, dass der Ereignishandler in einer reinen JavaScript-Runtime ausgeführt wird. Weitere Informationen finden Sie unter Runtimes in Office-Add-Ins.

Exemplarische Vorgehensweise: Automatisches Handeln beim Öffnen des Dokuments

In den folgenden Abschnitten wird beschrieben, wie Sie ein Word-Add-In entwickeln, das den Dokumentkopf automatisch ändert, wenn ein neues oder vorhandenes Dokument geöffnet wird. Während dieses spezifische Beispiel für Word gilt, ist die Manifestkonfiguration für Excel und PowerPoint identisch.

Wichtig

Für dieses Beispiel müssen Sie über ein Microsoft 365-Abonnement mit der unterstützten Version von Word verfügen.

Erstellen eines neuen Add-Ins

Erstellen Sie ein neues Add-In, indem Sie den Schnellstart Word Add-Ins ausführen. Dadurch erhalten Sie ein funktionierendes Office-Add-In, dem Sie den ereignisbasierten Aktivierungscode hinzufügen können.

Konfigurieren des Manifests

Um ein ereignisbasiertes Add-In zu aktivieren, müssen Sie die folgenden Elemente im VersionOverridesV1_0 Knoten des Manifests konfigurieren.

  • Erstellen Sie im Runtimes-Element ein neues Override-Element für Runtime. Überschreiben Sie den Typ "javascript", und verweisen Sie auf die JavaScript-Datei, die die Funktion enthält, die Sie mit dem Ereignis auslösen möchten.
  • Fügen Sie im DesktopFormFactor-Element ein FunctionFile-Element für die JavaScript-Datei mit dem Ereignishandler hinzu.
  • Legen Sie im ExtensionPoint-Element auf xsi:type fest LaunchEvent. Dadurch wird die ereignisbasierte Aktivierungsfunktion in Ihrem Add-In aktiviert.
  • Legen Sie im LaunchEvent-Element auf Type fest OnDocumentOpened , und geben Sie den JavaScript-Funktionsnamen des Ereignishandlers im -Attribut an FunctionName .

Verwenden Sie den folgenden Beispielmanifestcode, um Ihr Projekt zu aktualisieren.

  1. Öffnen Sie in Ihrem Code-Editor das Schnellstartprojekt, das Sie erstellt haben.

  2. Öffnen Sie die manifest.xml Datei, die sich im Stammverzeichnis Ihres Projekts befindet.

  3. Wählen Sie den gesamten <VersionOverrides-Knoten> (einschließlich der Tags öffnen und schließen) aus, und ersetzen Sie ihn durch den folgenden XML-Code.

      <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Hosts>
      <Host xsi:type="Document">
        <Runtimes>
          <Runtime resid="Taskpane.Url" lifetime="long" />
          <Runtime resid="WebViewRuntime.Url">
            <Override type="javascript" resid="JsRuntimeWord.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <GetStarted>
            <Title resid="GetStarted.Title"/>
            <Description resid="GetStarted.Description"/>
            <LearnMoreUrl resid="GetStarted.LearnMoreUrl"/>
          </GetStarted>
          <FunctionFile resid="Commands.Url"/>
          <ExtensionPoint xsi:type="LaunchEvent">
            <LaunchEvents>
              <LaunchEvent Type="OnDocumentOpened" FunctionName="changeHeader"></LaunchEvent>
            </LaunchEvents>
            <SourceLocation resid="WebViewRuntime.Url"/>
          </ExtensionPoint>
          <ExtensionPoint xsi:type="PrimaryCommandSurface">
            <OfficeTab id="TabHome">
              <Group id="CommandsGroup">
                <Label resid="CommandsGroup.Label"/>
                <Icon>
                  <bt:Image size="16" resid="Icon.16x16"/>
                  <bt:Image size="32" resid="Icon.32x32"/>
                  <bt:Image size="80" resid="Icon.80x80"/>
                </Icon>
                <Control xsi:type="Button" id="TaskpaneButton">
                  <Label resid="TaskpaneButton.Label"/>
                  <Supertip>
                    <Title resid="TaskpaneButton.Label"/>
                    <Description resid="TaskpaneButton.Tooltip"/>
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Icon.16x16"/>
                    <bt:Image size="32" resid="Icon.32x32"/>
                    <bt:Image size="80" resid="Icon.80x80"/>
                  </Icon>
                  <Action xsi:type="ShowTaskpane">
                    <TaskpaneId>ButtonId1</TaskpaneId>
                    <SourceLocation resid="Taskpane.Url"/>
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Icon.16x16" DefaultValue="https://localhost:3000/assets/icon-16.png"/>
        <bt:Image id="Icon.32x32" DefaultValue="https://localhost:3000/assets/icon-32.png"/>
        <bt:Image id="Icon.80x80" DefaultValue="https://localhost:3000/assets/icon-80.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="GetStarted.LearnMoreUrl" DefaultValue="https://go.microsoft.com/fwlink/?LinkId=276812"/>
        <bt:Url id="Commands.Url" DefaultValue="https://localhost:3000/commands.html"/>
        <bt:Url id="Taskpane.Url" DefaultValue="https://localhost:3000/taskpane.html"/>
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://localhost:3000/commands.html"/>
        <bt:Url id="JsRuntimeWord.Url" DefaultValue="https://localhost:3000/commands.js"/>
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="GetStarted.Title" DefaultValue="Get started with your sample add-in!"/>
        <bt:String id="CommandsGroup.Label" DefaultValue="Event-based add-in activation"/>
        <bt:String id="TaskpaneButton.Label" DefaultValue="My add-in"/>
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="GetStarted.Description" DefaultValue="Your sample add-in loaded successfully. Go to the HOME tab and click the 'Show Task Pane' button to get started."/>
        <bt:String id="TaskpaneButton.Tooltip" DefaultValue="Click to show the task pane"/>
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>

  4. Speichern Sie Ihre Änderungen.

Implementieren des Ereignishandlers

Damit Ihr Add-In bei Auftreten des OnDocumentOpened Ereignisses agieren kann, müssen Sie einen JavaScript-Ereignishandler implementieren. In diesem Abschnitt erstellen Sie die changeHeader -Funktion, die neuen Dokumenten einen "Public"-Header oder einen "Streng vertraulichen" Header zu vorhandenen Dokumenten hinzufügt, die bereits Inhalt enthalten.

  1. Öffnen Sie im Ordner ./src/commands die Datei mit dem Namen commands.js.

  2. Ersetzen Sie den gesamten Inhalt von commands.js durch den folgenden JavaScript-Code.

      /*
  * Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
  * See LICENSE in the project root for license information.
  */
  /* global global, Office, self, window */

  Office.onReady(() => {
    // If needed, Office.js is ready to be called
  });

  async function changeHeader(event) {
    Word.run(async (context) => {
      const body = context.document.body;
      body.load("text");
      await context.sync();

      if (body.text.length == 0) {
      // For new or empty documents, make a "Public" header. 
        const header = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.primary);
        const firstPageHeader = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.firstPage);
        header.clear();
        firstPageHeader.clear();

        header.insertParagraph("Public - The data is for the public and shareable externally", "Start");
        firstPageHeader.insertParagraph("Public - The data is for the public and shareable externally", "Start");
        header.font.color = "#07641d";
        firstPageHeader.font.color = "#07641d";
        await context.sync();
      } else {
        // For existing documents, make a "Highly Confidential" header.
        const header = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.primary);
        const firstPageHeader = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.firstPage);
        header.clear();
        firstPageHeader.clear();
        header.insertParagraph("Highly Confidential - The data must be secret or in some way highly critical", "Start");
        firstPageHeader.insertParagraph("Highly Confidential - The data must be secret or in some way highly critical", "Start");
        header.font.color = "#f8334d";
        firstPageHeader.font.color = "#f8334d";
        await context.sync();
      }
    });

    // Calling event.completed is required. event.completed lets the platform know that processing has completed.
    event.completed();
  }

  async function paragraphChanged() {
    await Word.run(async (context) => {
      const results = context.document.body.search("110");
      results.load("length");
      await context.sync();
      if (results.items.length == 0) {
        const header = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.primary);
        header.clear();
        header.insertParagraph("Public - The data is for the public and shareable externally", "Start");
        const font = header.font;
        font.color = "#07641d";

        await context.sync();
      } else {
        const header = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.primary);
        header.clear();
        header.insertParagraph("Highly Confidential - The data must be secret or in some way highly critical", "Start");
        const font = header.font;
        font.color = "#f8334d";

        await context.sync();
      }
    });
  }

  async function registerOnParagraphChanged(event) {
    Word.run(async (context) => {
      let eventContext = context.document.onParagraphChanged.add(paragraphChanged);
      await context.sync();
    });
    // Calling event.completed is required. event.completed lets the platform know that processing has completed.
    event.completed();
  }


  Office.actions.associate("changeHeader", changeHeader);
  Office.actions.associate("registerOnParagraphChanged", registerOnParagraphChanged);

  3. Speichern Sie Ihre Änderungen.

Testen und Überprüfen Ihres Add-Ins

  1. Führen Sie aus npm start , um Ihr Projekt zu erstellen und den Webserver zu starten. Ignorieren Sie das geöffnete Word Dokument.
  2. Laden Sie Ihr Add-In manuell in Word im Web quer, indem Sie die Anleitung unter Querladen von Office-Add-Ins in Office im Web befolgen. Verwenden Sie die manifest.xml im Stammverzeichnis des Projekts.
  3. Versuchen Sie, sowohl neue als auch vorhandene Word Dokumente in Word im Web zu öffnen. Header sollten beim Öffnen automatisch hinzugefügt werden.

Bereitstellen Ihres Add-Ins

Ereignisbasierte Add-Ins funktionieren nur, wenn sie von einem Administrator bereitgestellt werden. Wenn Benutzer sie direkt aus AppSource oder dem Office Store installieren, werden sie nicht automatisch gestartet. Um eine Administratorbereitstellung auszuführen, laden Sie das Manifest in die Microsoft 365 Admin Center hoch, indem Sie die folgenden Aktionen ausführen.

  1. Erweitern Sie im Verwaltungsportal den Abschnitt Einstellungen im Navigationsbereich, und wählen Sie dann Integrierte Apps aus.
  2. Wählen Sie auf der Seite Integrierte Apps die Aktion Benutzerdefinierte Apps hochladen aus.

Weitere Informationen zum Bereitstellen eines Add-Ins finden Sie unter Bereitstellen und Veröffentlichen von Office-Add-Ins im Microsoft 365 Admin Center.