Aktivieren von Add-Ins mit Ereignissen

Durch die ereignisbasierte Aktivierung kann Ihr Add-In automatisch als Reaktion auf Ereignisse gestartet werden, sodass es kritische Inhalte ohne direkte Benutzeraktion überprüfen, einfügen oder aktualisieren kann. Das Add-In wird im Hintergrund aktiviert, um den Benutzer nicht zu stören. Sie können auch die ereignisbasierte Aktivierung in die Aufgabenbereiche und Funktionsbefehle integrieren.

Übersicht

Die einzelnen Schritte zum Hinzufügen ereignisbasierter Funktionen zu einem Add-In variieren zwar je nach Plattform und Manifesttyp, der allgemeine Ablauf ist jedoch wie folgt.

1. Aktualisieren Sie das Manifest, um eine Aktion zur Behandlung des Ereignisses zuzuweisen.
2. Erstellen Sie eine JavaScript-Funktion, und stellen Sie sicher, dass die Event.Completed-Methode aufgerufen wird.
3. Verwenden Sie die Office.actions.associate-Methode , um die Funktion der im Manifest angegebenen Aktion zuzuordnen.

Testen Sie die ereignisbasierte Aktivierung.

Erfahren Sie, wie Sie Workflows optimieren und die Benutzererfahrung mit ereignisbasierter Aktivierung verbessern können. Probieren Sie die Beispiele aus, um das Feature in Aktion zu sehen.

Outlook-Beispiele

• Automatisches Festlegen des Betreffs für eine neue Nachricht oder einen Termin
• Automatische Überprüfung auf eine Anlage, bevor eine Nachricht gesendet wird
• Automatisches Aktualisieren Ihrer Signatur beim Wechseln zwischen E-Mail-Konten
• Verschlüsseln von Anlagen, Verarbeiten von Teilnehmern von Besprechungsanfragen und Reagieren auf Änderungen von Termindatum/-uhrzeit mithilfe der ereignisbasierten Aktivierung von Outlook
• Festlegen Ihrer Signatur mithilfe der ereignisbasierten Aktivierung in Outlook
• Identifizieren und Markieren externer Empfänger mithilfe der ereignisbasierten Aktivierung von Outlook
• Überprüfen Sie mithilfe von Smart Alerts die Farbkategorien einer Nachricht oder eines Termins, bevor sie gesendet wird
• Überprüfen der Vertraulichkeitsbezeichnung einer Nachricht

Word-Beispiele

• Hinzufügen von Kopfzeilen beim Öffnen eines Dokuments

Unterstützte Ereignisse

In der folgenden Tabelle sind die derzeit verfügbaren Ereignisse sowie die unterstützten Clients für jedes Ereignis aufgeführt. Wenn ein Ereignis ausgelöst wird, empfängt der Handler ein event Objekt, das für den Ereignistyp spezifische Details enthalten kann. Die Spalte "Beschreibung " enthält ggf. einen Link zum zugehörigen Objekt.

Excel-, PowerPoint-, Word-Ereignisse

Ein Beispiel für ein Add-In, das mit diesem Ereignis aktiviert wird, finden Sie unter word-add-label-on-open.

Outlook-Ereignisse

Die Unterstützung für dieses Feature in Outlook wurde im Anforderungssatz 1.10 eingeführt. In nachfolgenden Anforderungssätzen stehen nun zusätzliche Ereignisse zur Verfügung. In der folgenden Tabelle sind die Mindestanforderungen für jedes Ereignis sowie die Clients und Plattformen aufgeführt, die sie unterstützen. Weitere Informationen zu Outlook-Clients und den von ihnen unterstützten Anforderungssätzen finden Sie unter Anforderungssätze, die von Exchange-Servern und Outlook-Clients unterstützt werden.

Ereignisbasierte Aktivierung in Outlook auf mobilen Geräten

Outlook für Mobilgeräte unterstützt APIs bis zum Postfachanforderungssatz 1.5. Die Unterstützung für zusätzliche APIs und Features, die in späteren Anforderungssätzen eingeführt werden, wie z. B. das OnNewMessageCompose Ereignis, ist jetzt aktiviert. Weitere Informationen finden Sie unter Implementieren der ereignisbasierten Aktivierung in Outlook Mobile-Add-Ins.

Verhalten und Einschränkungen

Achten Sie beim Entwickeln eines ereignisbasierten Add-Ins auf die folgenden Featureverhalten und -einschränkungen.

• Ereignisbasierte Add-Ins funktionieren nur, wenn sie von einem Administrator bereitgestellt werden. Wenn Benutzer sie direkt aus dem Microsoft Marketplace oder dem Office Store installieren, werden sie nicht automatisch gestartet (Informationen zu Problemumgehungen für die Microsoft Marketplace-Einschränkung finden Sie unter Auflistungsoptionen für Ihr ereignisbasiertes Add-In im Microsoft Marketplace). Admin-Bereitstellungen erfolgen durch Hochladen des Manifests in das Microsoft 365 Admin Center.

• APIs, die mit der Benutzeroberfläche interagieren oder Benutzeroberflächenelemente anzeigen, werden für Word, PowerPoint und Excel nicht unterstützt. Dies liegt daran, dass der Ereignishandler in einer reinen JavaScript-Laufzeit ausgeführt wird. Weitere Informationen finden Sie unter Laufzeiten in Office-Add-Ins.

• Ereignisbasierte Add-Ins benötigen eine Internetverbindung, um gestartet werden zu können, wenn ein bestimmtes Ereignis eintritt. Von Add-In-Ereignishandlern wird erwartet, dass sie kurz, einfach und so nichtinvasiv wie möglich sind. Nach der Aktivierung tritt für Ihr Add-In innerhalb von ungefähr 300 Sekunden ein Timeout auf, der maximalen Zeitspanne, die für die Ausführung ereignisbasierter Add-Ins zulässig ist. Um zu signalisieren, dass Ihr Add-In die Verarbeitung eines Startereignisses abgeschlossen hat, muss der zugeordnete Ereignishandler die event.completed-Methode aufrufen. (Beachten Sie, dass die Ausführung von Code nach der event.completed Anweisung nicht garantiert ist.) Jedes Mal, wenn ein Ereignis ausgelöst wird, das vom Add-In behandelt wird, wird das Add-In erneut aktiviert und führt den zugeordneten Ereignishandler aus, und das Timeoutfenster wird zurückgesetzt. Das Add-In endet, nachdem es das Zeitlimit überschritten hat, oder der Benutzer das Fenster zum Verfassen schließt oder das Element sendet.

• Das Verhalten mehrerer Add-Ins, die dasselbe Ereignis abonnieren, ist nicht deterministisch. Outlook startet die Add-Ins in keiner bestimmten Reihenfolge. Für Excel, PowerPoint und Word wird nur ein zufälliges Add-In aktiviert. Wenn beispielsweise mehrere Word-Add-Ins, die OnDocumentOpened, verarbeiten, wird nur einer dieser Handler ausgeführt.

• Derzeit können nur fünf ereignisbasierte Add-Ins aktiv ausgeführt werden.

• In allen unterstützten Outlook-Clients muss der Benutzer beim aktuellen E-Mail-Element bleiben, für das das Add-In aktiviert wurde, damit die Ausführung abgeschlossen werden kann. Wenn Sie vom aktuellen Element weg navigieren (z. B. zu einem anderen Fenster oder einer anderen Registerkarte zum Verfassen wechseln), wird der Add-In-Vorgang beendet. Ein Add-In, das beim OnMessageSend Ereignis aktiviert wird, handhabt das Wechseln von Elementen jedoch unterschiedlich, je nachdem, auf welchem Outlook-Client es ausgeführt wird. Weitere Informationen finden Sie im Abschnitt "Benutzer navigiert von der aktuellen Nachricht weg" unter Behandeln von OnMessageSend- und OnAppointmentSend-Ereignissen in Ihrem Outlook-Add-In mit intelligenten Benachrichtigungen.

• Zusätzlich zum Elementwechsel beendet ein ereignisbasiertes Add-In auch den Betrieb, wenn der Benutzer die Nachricht oder den Termin sendet, den er verfasst.

Ereignisbasierte Add-In-Einschränkungen in Excel, PowerPoint, Word und dem klassischen Outlook unter Windows

Beachten Sie beim Entwickeln eines ereignisbasierten Add-Ins, das auf einem Windows-Client ausgeführt werden soll, Folgendes:

• Importe werden in der JavaScript-Datei, in der Sie die Behandlung für die ereignisbasierte Aktivierung implementieren, nicht unterstützt.

• Für die ereignisbasierte Aktivierung wird nur die JavaScript-Datei unterstützt, auf die im Manifest verwiesen wird. Sie müssen Ihren JavaScript-Code für die Ereignisbehandlung in dieser einzigen Datei bündeln. Der Speicherort der JavaScript-Datei, auf die verwiesen wird, im Manifest variiert je nach Typ des Manifests, das Ihr Add-In verwendet.

  • Nur-Add-In-Manifest: <Override> Untergeordnetes Element des <Runtime> Knotens
  • Einheitliches Manifest für Microsoft 365: "script" Eigenschaft des "code" Objekts

  Beachten Sie, dass ein großes JavaScript-Paket Probleme mit der Leistung Ihres Add-Ins verursachen kann. Es wird empfohlen, umfangreiche Vorgänge vorzuverarbeiten, damit sie nicht in den Ereignisbehandlungscode aufgenommen werden.

• Wenn die im Manifest angegebene JavaScript-Funktion zur Behandlung eines Ereignisses ausgeführt wird, wird Code eingegeben Office.onReady() und Office.initialize nicht ausgeführt. Es wird empfohlen, stattdessen die von Ereignishandlern benötigte Startlogik zu den Ereignishandlern hinzuzufügen, z. B. die Überprüfung der Clientversion des Benutzers.

• Beim Verfassen einer Nachricht, die durch einen Link zur E-Mail (mailtoLink) initiiert wurde, wird beim Abrufen der Empfänger aus den Feldern "An", "Cc" oder "Bcc" im OnNewMessageCompose Ereignishandler möglicherweise ein leeres Array zurückgegeben. Dies geschieht, wenn Outlook die Auflösung der E-Mail-Adressen der Empfänger bis zum Auftreten des OnNewMessageCompose Ereignisses noch nicht abgeschlossen hat. Um dieses Problem zu umgehen, suchen Sie stattdessen im OnMessageRecipientsChanged Ereignishandler nach Empfängern.

Ereignisbasierte Add-In-Einschränkungen in Excel, PowerPoint und Word

Die folgenden Plattformen oder Features werden noch nicht unterstützt.

• Office für Mac

Ereignisbasierte Add-In-Einschränkungen in Outlook im Web und dem neuen Outlook unter Windows

In Outlook im Web und dem neuen Outlook unter Windows wird die ereignisbasierte Aktivierung nur auf standardmäßigen Nachrichten- und Terminoberflächen zum Lesen und Verfassen unterstützt. Die ereignisbasierte Aktivierung funktioniert möglicherweise nicht, wenn Sie auf einigen nicht standardmäßigen Oberflächen komponieren. Zum Beispiel:

• Antworten auf eine Besprechungseinladung mit der Option RSVP mit Notiz .
• Weiterleiten einer Besprechung aus dem Kalender.

Nicht unterstützte APIs

Einige Office.js-APIs, die die Benutzeroberfläche ändern oder verändern, sind in den Ereignishandlern ereignisbasierter Add-Ins nicht zulässig. Die folgenden sind blockierte APIs.

Vorschau von Features in Ereignishandlern (klassisches Outlook unter Windows)

Das klassische Outlook unter Windows enthält eine lokale Kopie der Produktions- und Betaversionen von Office.js, anstatt aus dem Content Delivery Network (CDN) geladen zu werden. Standardmäßig wird auf die lokale Produktionskopie der API verwiesen. Um auf die lokale Beta-Kopie der API zu verweisen, müssen Sie die Registrierung Ihres Computers konfigurieren. Auf diese Weise können Sie Vorschaufeatures in Ihren Ereignishandlern im klassischen Outlook unter Windows testen.

1. Navigieren Sie in der Registrierung zu HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Wenn der Schlüssel nicht vorhanden ist, erstellen Sie ihn.

2. Erstellen Sie einen Eintrag mit dem Namen, EnableBetaAPIsInJavaScript und legen Sie den Wert auf 1fest.

   

Einmaliges Anmelden (SSO) aktivieren

Um SSO in Ihrem ereignisbasierten Add-In zu aktivieren, müssen Sie die JavaScript-Datei einem bekannten URI hinzufügen. Anleitungen zum Konfigurieren dieser Ressource finden Sie unter Verwenden von einmaligem Anmelden (Single Sign-On, SSO) oder Cross-Origin Resource Sharing (CORS) in Ihrem ereignisbasierten oder Spamberichts-Office-Add-In.

Externe Daten anfordern

Sie können externe Daten mithilfe einer API wie Fetch oder mithilfe von XMLHttpRequest (XHR) anfordern, einer Standard-Web-API, die HTTP-Anforderungen zur Interaktion mit Servern ausgibt.

Beachten Sie, dass Sie zusätzliche Sicherheitsmaßnahmen verwenden müssen, wenn Sie XMLHttpRequest-Objekte verwenden, die die Richtlinie gleichen Ursprungs und CORS (Cross-Origin Resource Sharing) erfordern.

Um CORS-Anforderungen von Ihrem ereignisbasierten Add-In zu stellen, müssen Sie das Add-In und die zugehörige JavaScript-Datei einem bekannten URI hinzufügen. Anleitungen zum Konfigurieren dieser Ressource finden Sie unter Verwenden von einmaligem Anmelden (Single Sign-On, SSO) oder Cross-Origin Resource Sharing (CORS) in Ihrem ereignisbasierten oder Spamberichts-Office-Add-In.

Problembehandlung für Ihr Add-In

Während Sie Ihr ereignisbasiertes Add-In entwickeln, müssen Sie möglicherweise Probleme beheben, z. B. dass Ihr Add-In nicht geladen wird oder das Ereignis nicht eintritt. Anleitungen zur Problembehandlung bei ereignisbasierten Add-Ins finden Sie unter Problembehandlung bei ereignisbasierten Add-Ins und Add-Ins mit Spambericht.

Bereitstellen Ihres Add-Ins

Je nach Office-Anwendung können ereignisbasierte Add-Ins über eine der folgenden Optionen bereitgestellt werden.

• Bereitstellung, die vom Admin verwaltet wird: Add-Ins werden über das Microsoft 365 Admin Center bereitgestellt.
• Eingeschränkte Auflistung auf Microsoft Marketplace: Add-In wird im Microsoft Marketplace veröffentlicht, aber nicht in den Suchergebnissen angezeigt. Für den Erwerb von Add-Ins ist eine Flightcode-URL erforderlich. Das Add-In muss weiterhin von einem Administrator bereitgestellt werden, damit das ereignisbasierte Aktivierungsfeature funktioniert.
• Uneingeschränktes Auflisten auf dem Microsoft Marketplace: Add-In wird im Microsoft Marketplace veröffentlicht und kann von Benutzern und Administratoren mithilfe des Namens oder der ID des Add-Ins gesucht werden. Die Bereitstellung durch den Admin ist nicht erforderlich, damit das ereignisbasierte Aktivierungsfeature funktioniert. Das Add-In muss bestimmte Anforderungen für eine uneingeschränkte Auflistung erfüllen.

In der folgenden Tabelle sind die Bereitstellungsoptionen für die ereignisbasierte Aktivierung über die Office-Anwendung aufgeführt.

Anweisungen zum Bereitstellen eines Add-Ins über das Microsoft 365 Admin Center finden Sie unter Bereitstellung durch Admins. Weitere Informationen zum Auflisten Ihres ereignisbasierten Add-Ins im Microsoft Marketplace finden Sie unter Auflistungsoptionen für Ihr ereignisbasiertes Add-In im Microsoft Marketplace.

Von Admins verwaltete Bereitstellung

Admin-Bereitstellungen erfolgen durch Hochladen des Manifests in das Microsoft 365 Admin Center. Führen Sie hierzu die folgenden Schritte aus.

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.

3. Die nächsten Schritte hängen davon ab, welches Manifest verwendet wird.

   • Einheitliches Manifest für Microsoft 365:

     1. Wählen Sie im Dropdownfeld "App-Typ " die Option Teams-App aus. NichtOffice-Add-In!
     2. Verwenden Sie das Dateiauswahlsteuerelement, um zur ZIP-Datei des App-Pakets zu navigieren und diese auszuwählen.
     3. Folgen Sie den Anweisungen auf der Seite, um die Installation abzuschließen.

   • Manifest nur für Add-Ins:

     1. Wählen Sie im Dropdownfeld "App-Typ " die Option "Office-Add-In" aus.
     2. Verwenden Sie das Dateiauswahlsteuerelement, um zum Manifest zu navigieren und es auszuwählen.
     3. Folgen Sie den Anweisungen auf der Seite, um die Installation abzuschließen.

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

Bereitstellen von Manifestupdates

Wenn ein ereignisbasiertes Add-In vom Administrator bereitgestellt wurde, ist für jede Änderung, die Sie am Manifest vornehmen, die Zustimmung des Administrators über das Microsoft 365 Admin Center erforderlich. Solange der Administrator Ihre Änderungen nicht akzeptiert, wird die Verwendung des Add-Ins für Benutzer in ihrer organization gesperrt. Weitere Informationen zum Prozess der Administratorzustimmung finden Sie unter Admin-Zustimmung zum Installieren von ereignisbasierten Add-Ins.

Siehe auch

• Problembehandlung bei ereignisbasierten Add-Ins und Spam-Berichts-Add-Ins
• Debuggen von ereignisbasierten Add-Ins und Spambericht-Add-Ins
• Auflistungsoptionen für Ihr ereignisbasiertes Add-In im Microsoft Marketplace
• Behandeln von OnMessageSend- und OnAppointmentSend-Ereignissen in Ihrem Outlook-Add-In mit intelligenten Benachrichtigungen