Implementieren eines anheftbaren Aufgabenbereichs in Outlook

  • Artikel

Das Aufgabenbereich-UX-Shape für Add-In-Befehle öffnet einen vertikalen Aufgabenbereich rechts neben einer geöffneten Nachricht oder Besprechungsanfrage. Dadurch kann ein Add-In eine Benutzeroberfläche für detailliertere Interaktionen bereitstellen, z. B. das Ausfüllen mehrerer Textfelder. Dieser Aufgabenbereich kann im Lesebereich angezeigt werden, wenn eine Liste von Nachrichten angezeigt wird, sodass eine Nachricht schnell verarbeitet werden kann.

Wenn ein Benutzer jedoch einen Add-In-Aufgabenbereich für eine Nachricht im Lesebereich geöffnet hat und dann eine neue Nachricht auswählt, wird der Aufgabenbereich automatisch geschlossen. Bei einem häufig verwendeten Add-In möchte der Benutzer diesen Bereich möglicherweise geöffnet lassen, sodass das Add-In nicht bei jeder Nachricht erneut aktiviert werden muss. Mit anheftbaren Aufgabenbereichen kann Ihr Add-In dem Benutzer diese Option bereitstellen.

Hinweis

Obwohl das Feature zum anheftbaren Aufgabenbereich in Anforderungssatz 1.5 eingeführt wurde, ist es derzeit nur für Microsoft 365-Abonnenten verfügbar, die Folgendes verwenden:

  • Modernes Outlook im Web
  • Neues Outlook unter Windows (Vorschau)
  • Klassische Outlook 2016 oder höher unter Windows (Build 7668.2000 oder höher für Benutzer in den aktuellen oder Microsoft 365 Insider-Kanälen, Build 7900.xxxx oder höher für Benutzer in verzögerten Kanälen)
  • Outlook für Mac (Version 16.13.503 oder höher)

Wichtig

Anheftbare Aufgabenbereiche sind für Folgendes nicht verfügbar:

  • Termine/Besprechungen
  • Outlook.com

Unterstützen des Anheftens des Aufgabenbereichs

Der erste Schritt besteht darin, die Unterstützung zum Anheften hinzuzufügen, was über das Add-In-Manifest erfolgt. Das Markup variiert je nach Art des Manifests, das ihr Add-In verwendet.

Fügen Sie dem Objekt im Array "actions", das die Schaltfläche oder das Menüelement definiert, das den Aufgabenbereich öffnet, eine "pinnable"-Eigenschaft hinzu, die auf truefestgelegt ist. Es folgt ein Beispiel.

"actions": [
    {
        "id": "OpenTaskPane",
        "type": "openPage",
        "view": "TaskPaneView",
        "displayName": "OpenTaskPane",
        "pinnable": true
    }
]

Ein vollständiges Beispiel finden Sie im msgReadOpenPaneButton-Steuerelement im command-demo-Beispielmanifest.

Hinweis

Das Anheften von Aufgabenbereichen wird automatisch in einem Add-In unterstützt, das aktiviert wird, ohne dass der Lesebereich aktiviert oder eine Nachricht zuerst ausgewählt wurde. Weitere Informationen finden Sie unter Aktivieren Ihres Outlook-Add-Ins ohne aktivierten Lesebereich oder ausgewählte Nachricht.

Umgang mit Updates der Benutzeroberfläche basierend auf der aktuell ausgewählten Nachricht

Um die Benutzeroberfläche Ihres Aufgabenbereichs oder interne Variablen basierend auf dem aktuellen Element zu aktualisieren, müssen Sie einen Ereignishandler registrieren, um bezüglich der Änderung benachrichtigt zu werden.

Implementieren des Ereignishandlers

Der Ereignishandler sollte einen einzelnen Parameter akzeptieren, der ein Objektliteral ist. Die type-Eigenschaft dieses Objekts wird durch Office.EventType.ItemChanged festgelegt. Wenn das Ereignis aufgerufen wird, ist das Office.context.mailbox.item-Objekt bereits so aktualisiert, dass das derzeit ausgewählte Element widergespiegelt wird.

function itemChanged(eventArgs) {
  // Update UI based on the new current item.
  updateTaskPaneUI(Office.context.mailbox.item);
}

Wichtig

Die Implementierung von Ereignishandlern für ein ItemChanged-Ereignis sollte überprüfen, ob das Office.content.mailbox.item null ist.

// Example implementation.
function updateTaskPaneUI(item) {
  // Assuming that item is always a read item (instead of a compose item).
  if (item != null) console.log(item.subject);
}

Registrieren des Ereignishandlers

Verwenden Sie die Office.context.mailbox.addHandlerAsync-Methode, um Ihren Ereignishandler für das Office.EventType.ItemChanged-Ereignis zu registrieren. Dies sollte in der Office.onReady Funktion Ihres Aufgabenbereichs erfolgen.

Office.onReady(() => {
  $(document).ready(() => {
    // Set up the ItemChanged event.
    Office.context.mailbox.addHandlerAsync(Office.EventType.ItemChanged, itemChanged);
    updateTaskPaneUI(Office.context.mailbox.item);
  });
});

Anheften des Aufgabenbereichs in Mehrfachauswahl

In Outlook im Web und dem neuen Outlook unter Windows (Vorschau) wird der Aufgabenbereich eines Add-Ins, das die Mehrfachauswahlfunktion für Elemente implementiert, automatisch an den Outlook-Client angeheftet. Sie bleibt auch dann angeheftet, wenn ein Benutzer zu einem anderen E-Mail-Element wechselt oder das Stecknadelsymbol im Aufgabenbereich auswählt. Der Aufgabenbereich kann nur durch Auswählen der Schaltfläche Schließen im Aufgabenbereich geschlossen werden.

Umgekehrt wird im klassischen Outlook unter Windows und Outlook auf Mac der Aufgabenbereich eines Add-Ins mit mehrfacher Auswahl nicht automatisch angeheftet und geschlossen, wenn ein Benutzer zu einem anderen E-Mail-Element wechselt.

Bereitstellen für Benutzer

Wenn Sie Planen, Ihr Outlook-Add-In in AppSource zu veröffentlichen, und es mit einem anheftbaren Aufgabenbereich konfiguriert ist, darf ihr Add-In-Inhalt nicht statisch sein und muss eindeutig Daten im Zusammenhang mit der Nachricht anzeigen, die im Postfach geöffnet oder ausgewählt ist. Dadurch wird sichergestellt, dass Ihr Add-In die AppSource-Überprüfung erfolgreich ist.

Siehe auch

Ein Beispiel-Add-In, das einen anheftbaren Aufgabenbereich implementiert, finden Sie unter command-demo auf GitHub.