Implementieren eines anheftbaren Aufgabenbereichs in Outlook

Artikel
10/02/2024

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
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 (18050300) oder höher)

Wichtig

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

Termine/Besprechungen
Outlook.com

Unterstützte Outlook-Modi

Anheftbare Aufgabenbereiche werden sowohl im Nachrichten-Compose- als auch im Nachrichtenlesemodus in Outlook unterstützt. Das Anheften wird jedoch in verschiedenen Modi nicht unterstützt. Dies liegt daran, dass ein Add-In in jedem Modus unterschiedliche Benutzeroberflächen für Schaltflächen und Aufgabenbereiche aufweisen kann. Wenn ein Benutzer beispielsweise den Aufgabenbereich eines Add-Ins anheftet, während er eine Nachricht liest und dann eine neue Nachricht erstellt, wird der Aufgabenbereich des Add-Ins in der Nachricht, die er erstellt, nicht angezeigt. Um den Aufgabenbereich anzuzeigen, muss der Benutzer das Add-In aus der Nachricht aktivieren, die er erstellt. Wenn der Benutzer dann den Aufgabenbereich anheftet, bleibt der Aufgabenbereich angeheftet, wenn der Benutzer das nächste Mal eine weitere Nachricht verfasst.

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.

Einheitliches Manifest für Microsoft 365
Manifest nur für Add-Ins

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
    }
]

Fügen Sie das SupportsPinning-Element dem <Action-Element> hinzu, das die Schaltfläche "Aufgabenbereich" beschreibt. Es folgt ein Beispiel.

<!-- Task pane button. -->
<Control xsi:type="Button" id="msgReadOpenPaneButton">
  <Label resid="paneReadButtonLabel" />
  <Supertip>
    <Title resid="paneReadSuperTipTitle" />
    <Description resid="paneReadSuperTipDescription" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="green-icon-16" />
    <bt:Image size="32" resid="green-icon-32" />
    <bt:Image size="80" resid="green-icon-80" />
  </Icon>
  <Action xsi:type="ShowTaskpane">
    <SourceLocation resid="readTaskPaneUrl" />
    <SupportsPinning>true</SupportsPinning>
  </Action>
</Control>

Das <SupportsPinning-Element> ist im VersionOverrides v1.1-Schema definiert, sodass Sie ein VersionOverrides-Element sowohl für v1.0 als auch für v1.1 einschließen müssen.

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 Office.content.mailbox.item NULL ist oder nicht.

// 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

Wenn in Outlook im Web und dem neuen Outlook unter Windows der Aufgabenbereich eines Add-Ins geöffnet wird, das die Mehrfachauswahlfunktion für Elemente implementiert, wird er 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 Ihr Outlook-Add-In in AppSource veröffentlichen möchten und es mit einem anheftbaren Aufgabenbereich konfiguriert ist, darf der angeheftete Inhalt des Add-Ins nicht statisch sein. Das heißt, der angeheftete Inhalt muss sich abhängig von der Nachricht oder dem Termin ändern, die derzeit 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.

Freigeben über