Freigeben über

Aktivieren Ihres Outlook-Add-Ins für mehrere Nachrichten

  • Artikel

Mit der Mehrfachauswahlfunktion für Elemente kann Ihr Outlook-Add-In jetzt mehrere ausgewählte Nachrichten auf einmal aktivieren und Vorgänge ausführen. Bestimmte Vorgänge, z. B. das Hochladen von Nachrichten in Ihr CRM-System (Customer Relationship Management) oder das Kategorisieren zahlreicher Elemente, können jetzt problemlos mit einem einzigen Klick abgeschlossen werden.

In den folgenden Abschnitten wird gezeigt, wie Sie Ihr Add-In so konfigurieren, dass die Betreffzeile und die E-Mail-Adresse des Absenders mehrerer Nachrichten im Lesemodus abgerufen werden.

Hinweis

Die Unterstützung für die Mehrfachauswahl von Elementen wurde in Anforderungssatz 1.13 eingeführt, wobei zusätzliche Elementeigenschaften jetzt in nachfolgenden Anforderungssätzen verfügbar sind. Siehe Clients und Plattformen, die diese Anforderungsgruppe unterstützen.

Einrichten der Umgebung

Schließen Sie den Outlook-Schnellstart ab, um ein Add-In-Projekt mit dem Yeoman-Generator für Office-Add-Ins zu erstellen.

Konfigurieren des Manifests

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

  2. Öffnen Sie die manifest.json Datei, die sich im Stammverzeichnis des Projekts befindet.

  3. Ändern Sie im Array "authorization.permissions.resourceSpecific" den Wert der Eigenschaft "name" in "Mailbox.ReadWrite.User". Wenn Sie fertig sind, sollte es wie folgt aussehen.

    "authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "Mailbox.ReadWrite.User",
                "type": "Delegated"
            }
        ]
    }
},

  4. Nehmen Sie im ersten Objekt des Arrays "extensions.runtimes" die folgenden Änderungen vor.

    1. Ändern Sie die Eigenschaft "requirements.capabilities.minVersion" in "1.13".
    2. Fügen Sie im gleichen "actions"-Objekt die Eigenschaft "supportsNoItemContext" hinzu, und legen Sie sie auf fest true.
    3. Fügen Sie im gleichen "actions"-Objekt die Eigenschaft "multiselect" hinzu, und legen Sie sie auf fest true.

    Ihr Code sollte wie folgt aussehen, nachdem Sie die Änderungen vorgenommen haben.

    "runtimes": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.13"
                }
            ]
        },
        "id": "TaskPaneRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/taskpane.html"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "TaskPaneRuntimeShow",
                "type": "openPage",
                "pinnable": false,
                "view": "dashboard",
                "supportsNoItemContext": true,
                "multiselect": true
            }
        ]
    },
    ...
]

  5. Löschen Sie das zweite Objekt des Arrays "extensions.runtimes", dessen "id" "CommandsRuntime" ist.

  6. Löschen Sie im Array "extensions.ribbons.tabs.controls" das zweite Objekt, dessen "id" "ActionButton" ist.

  7. Speichern Sie Ihre Änderungen.

Hinweis

Wenn Sie das Feature für die Mehrfachauswahl von Elementen in Ihrem Add-In aktivieren, unterstützt Ihr Add-In automatisch das Feature "Kein Elementkontext ", auch wenn es nicht explizit im Manifest konfiguriert ist. Weitere Informationen zum Anheften des Aufgabenbereichs in Mehrfachauswahl-Add-Ins finden Sie unter Anheften von Aufgabenbereichs-Add-Ins mit mehrfacher Auswahl.

Konfigurieren des Aufgabenbereichs

Die Mehrfachauswahl von Elementen basiert auf dem SelectedItemsChanged-Ereignis , um zu bestimmen, wann Nachrichten ausgewählt oder deaktiviert werden. Dieses Ereignis erfordert eine Aufgabenbereichsimplementierung.

  1. Öffnen Sie im Ordner ./src/taskpanetaskpane.html.

  2. Ersetzen Sie im <body-Element> das gesamte <Standard-Element> durch das folgende Markup.

    <main id="app-body" class="ms-welcome__main">
    <h2 class="ms-font-l">Get information about each selected message</h2>
    <ul id="selected-items"></ul>
    <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
        <span class="ms-Button-label">Get information</span>
    </div>
</main>

  3. Nur für klassisches Outlook unter Windows. Ersetzen Sie das vorhandene Skriptelement durch das folgende Markup. Dies verweist auf die Vorschauversion der Office JavaScript-API.

    <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js"></script>

    Hinweis

    Die Vorschauversion der Office JavaScript-API wird verwendet, da diese exemplarische Vorgehensweise die loadItemByIdAsync Methoden und unloadAsync implementiert, die sich derzeit in der Vorschau befinden. Wenn Ihr Mehrfachauswahl-Add-In diese Methoden nicht implementiert, verwenden Sie https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js stattdessen. Weitere Informationen finden Sie unter Verweisen auf die Office JavaScript-API-Bibliothek.

  4. Speichern Sie Ihre Änderungen.

Implementieren eines Handlers für das SelectedItemsChanged-Ereignis

Um Ihr Add-In zu benachrichtigen, wenn das SelectedItemsChanged Ereignis eintritt, müssen Sie einen Ereignishandler mithilfe der addHandlerAsync -Methode registrieren.

  1. Öffnen Sie im Ordner ./src/taskpanetaskpane.js.

  2. Ersetzen Sie die Office.onReady() Funktion durch Folgendes:

    let list;

Office.onReady((info) => {
  if (info.host === Office.HostType.Outlook) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";
    document.getElementById("run").onclick = run;
    list = document.getElementById("selected-items");

    // Register an event handler to identify when messages are selected.
    Office.context.mailbox.addHandlerAsync(Office.EventType.SelectedItemsChanged, run, (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
      }

      console.log("Event handler added.");
    });
  }
});

  3. Speichern Sie Ihre Änderungen.

Abrufen von Eigenschaften und Ausführen von Vorgängen für ausgewählte Nachrichten

Nachdem Sie nun einen Ereignishandler registriert haben, kann Ihr Add-In eigenschaften abrufen oder Vorgänge für mehrere ausgewählte Nachrichten ausführen. Es gibt zwei Möglichkeiten, ausgewählte Nachrichten zu verarbeiten. Die Verwendung der einzelnen Optionen hängt von den Eigenschaften und Vorgängen ab, die Sie für Ihr Szenario benötigen.

  • Rufen Sie die getSelectedItemsAsync-Methode auf, um die folgenden Eigenschaften abzurufen.

    • Boolescher Anhang
    • Unterhaltungs-ID
    • Internetnachrichten-ID
    • Element-ID
    • Elementmodus (Read oder Compose)
    • Elementtyp (Message ist derzeit der einzige unterstützte Typ)
    • Betreffzeile

  • Rufen Sie die loadItemByIdAsync-Methode (Vorschau) auf, um Eigenschaften abzurufen, die nicht von getSelectedItemsAsync bereitgestellt werden, oder um Vorgänge für die ausgewählten Nachrichten auszuführen. Die loadItemByIdAsync -Methode lädt jeweils eine ausgewählte Nachricht mit der EWS-ID (Exchange Web Services) der Nachricht. Um die EWS-IDs der ausgewählten Nachrichten abzurufen, wird empfohlen, aufzurufen getSelectedItemsAsync. Nachdem Sie eine ausgewählte Nachricht mit loadItemByIdAsyncverarbeitet haben, müssen Sie die unloadAsync-Methode (Vorschau) aufrufen, bevor Sie für eine andere ausgewählte Nachricht aufrufen loadItemByIdAsync .

    Tipp

    Bevor Sie die loadItemByIdAsync -Methode verwenden, ermitteln Sie, ob Sie bereits mit getSelectedItemsAsyncauf die benötigten Eigenschaften zugreifen können. Wenn möglich, müssen Sie nicht aufrufen loadItemByIdAsync.

Im folgenden Beispiel werden die getSelectedItemsAsync Methoden und loadItemByIdAsync implementiert, um die Betreffzeile und die E-Mail-Adresse des Absenders aus jeder ausgewählten Nachricht abzurufen.

Hinweis

Die loadItemByIdAsync Methode befindet sich derzeit in der Vorschauphase im klassischen Outlook unter Windows. Um eine Vorschau dieser API anzuzeigen, installieren Sie Version 2405 (Build 17606.10000) oder höher. Nehmen Sie dann am Microsoft 365 Insider-Programm teil, und wählen Sie die Option Betakanal aus.

  1. Ersetzen Sie intaskpane.jsdie vorhandene run Funktion durch den folgenden Code.

    export async function run() {
  // Clear the list of previously selected messages, if any.
  clearList(list);

  // Get the subject line and sender's email address of each selected message and log it to a list in the task pane.
  Office.context.mailbox.getSelectedItemsAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
      console.log(asyncResult.error.message);
      return;
    }

    const selectedItems = asyncResult.value;
    getItemInfo(selectedItems);
  });
}

// Gets the subject line and sender's email address of each selected message.
async function getItemInfo(selectedItems) {
  for (const item of selectedItems) {
    addToList(item.subject);
    // The loadItemByIdAsync method is currently only available to preview in classic Outlook on Windows.
    if (Office.context.diagnostics.platform === Office.PlatformType.PC) {
      await getSenderEmailAddress(item);
    }
  }
}

// Gets the sender's email address of each selected message.
async function getSenderEmailAddress(item) {
  const itemId = item.itemId;
  await new Promise((resolve) => {
    Office.context.mailbox.loadItemByIdAsync(itemId, (result) => {
      if (result.status === Office.AsyncResultStatus.Failed) {
        console.log(result.error.message);
        return;
      }

      const loadedItem = result.value;
      const sender = loadedItem.from.emailAddress;
      appendToListItem(sender);

      // Unload the current message before processing another selected message.
      loadedItem.unloadAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          console.log(asyncResult.error.message);
          return;
        }

        resolve();
      });
    });
  });
}

// Clears the list in the task pane.
function clearList(list) {
  while (list.firstChild) {
    list.removeChild(list.firstChild);
  }
}

// Adds an item to a list in the task pane.
function addToList(item) {
  const listItem = document.createElement("li");
  listItem.textContent = item;
  list.appendChild(listItem);
}

// Appends data to the last item of the list in the task pane.
function appendToListItem(data) {
  const listItem = list.lastChild;
  listItem.textContent += ` (${data})`;
}

  2. Speichern Sie Ihre Änderungen.

Probieren Sie es aus

  1. Führen Sie in einem Terminal den folgenden Code im Stammverzeichnis Ihres Projekts aus. Dadurch wird der lokale Webserver gestartet und das Add-In querladen.

    npm start

    Tipp

    Wenn Ihr Add-In nicht automatisch querladen wird, befolgen Sie die Anweisungen unter Querladen von Outlook-Add-Ins zum Testen , um es manuell in Outlook querzuladen.

  2. Stellen Sie in Outlook sicher, dass der Lesebereich aktiviert ist. Informationen zum Aktivieren des Lesebereichs finden Sie unter Verwenden und Konfigurieren des Lesebereichs für eine Vorschau von Nachrichten.

  3. Navigieren Sie zu Ihrem Posteingang, und wählen Sie mehrere Nachrichten aus, indem Sie strg gedrückt halten, während Sie Nachrichten auswählen.

  4. Wählen Sie Aufgabenbereich anzeigen aus. Der Speicherort des Add-Ins variiert je nach Outlook-Client. Eine Anleitung finden Sie unter Verwenden von Add-Ins in Outlook.

  5. Wählen Sie im Aufgabenbereich Informationen abrufen aus. Eine Liste der Betreffzeilen und Absender-E-Mail-Adressen der ausgewählten Nachrichten wird im Aufgabenbereich angezeigt.

    Eine Beispielliste von Betreffzeilen, die aus mehreren ausgewählten Nachrichten abgerufen wurden.

  6. Wenn Sie den lokalen Webserver beenden und das Add-In deinstallieren möchten, befolgen Sie die entsprechenden Anweisungen:

    • Führen Sie den folgenden Befehl aus, um den Server zu beenden. Wenn Sie verwendet haben npm start, sollte auch der folgende Befehl das Add-In deinstallieren.

      npm stop

    • Wenn Sie das Add-In manuell quergeladen haben, lesen Sie Entfernen eines quergeladenen Add-Ins.

Multiauswahlverhalten und Einschränkungen von Elementen

Die Mehrfachauswahl von Elementen unterstützt nur Nachrichten innerhalb eines Exchange-Postfachs sowohl im Lese- als auch im Verfassenmodus. Ein Outlook-Add-In wird nur für mehrere Nachrichten aktiviert, wenn die folgenden Bedingungen erfüllt sind.

  • Die Nachrichten müssen jeweils aus einem Exchange-Postfach ausgewählt werden. Nicht-Exchange-Postfächer werden nicht unterstützt.
  • Die Nachrichten müssen jeweils aus einem Postfachordner ausgewählt werden. Ein Add-In wird nicht für mehrere Nachrichten aktiviert, wenn sie sich in verschiedenen Ordnern befinden, es sei denn, die Unterhaltungsansicht ist aktiviert. Weitere Informationen finden Sie unter Mehrfachauswahl in Unterhaltungen.
  • Ein Add-In muss einen Aufgabenbereich implementieren, um das SelectedItemsChanged Ereignis zu erkennen.
  • Der Lesebereich in Outlook muss aktiviert sein. Eine Ausnahme besteht darin, wenn die Mehrfachauswahlfunktion des Elements über das Feature "Kein Elementkontext" im Manifest aktiviert ist. Weitere Informationen finden Sie unter Aktivieren Ihres Outlook-Add-Ins ohne aktivierten Lesebereich oder ausgewählte Nachricht.
  • Es können maximal 100 Nachrichten gleichzeitig ausgewählt werden.
  • Die loadItemByIdAsync -Methode verarbeitet jeweils nur eine ausgewählte Nachricht. Denken Sie daran, nach loadItemByIdAsync Abschluss der Verarbeitung der Nachricht aufzurufenunloadAsync. Auf diese Weise kann das Add-In die nächste ausgewählte Nachricht laden und verarbeiten.
  • In der Regel können Sie get-Vorgänge nur für eine ausgewählte Nachricht ausführen, die mit der loadItemByIdAsync -Methode geladen wird. Die Verwaltung der Kategorien einer geladenen Nachricht ist jedoch eine Ausnahme. Sie können Kategorien aus einer geladenen Nachricht hinzufügen, abrufen und daraus entfernen.
  • Die loadItemByIdAsync -Methode wird in Aufgabenbereich- und Funktionsbefehls-Add-Ins unterstützt. Diese Methode wird in ereignisbasierten Aktivierungs-Add-Ins nicht unterstützt.

Hinweis

Besprechungseinladungen und -antworten werden als Nachrichten und nicht als Termine betrachtet und können daher in eine Auswahl aufgenommen werden.

Mehrfachauswahl in Unterhaltungen

Die Mehrfachauswahl von Elementen unterstützt die Unterhaltungsansicht unabhängig davon, ob sie für Ihr Postfach oder für bestimmte Ordner aktiviert ist. In der folgenden Tabelle werden die erwarteten Verhaltensweisen beschrieben, wenn Unterhaltungen erweitert oder reduziert werden, wenn die Unterhaltungskopfzeile ausgewählt ist und sich Unterhaltungsnachrichten in einem anderen Ordner befinden als der aktuell angezeigte.

Selection Erweiterte Unterhaltungsansicht Reduzierte Unterhaltungsansicht
Der Unterhaltungsheader ist ausgewählt. Wenn der Unterhaltungsheader das einzige ausgewählte Element ist, wird ein Add-In, das die Mehrfachauswahl unterstützt, nicht aktiviert. Wenn jedoch auch andere Nachrichten ohne Header ausgewählt sind, wird das Add-In nur für diese aktiviert und nicht für den ausgewählten Header. Das Verhalten unterscheidet sich je nach Outlook-Client.

Outlook unter Windows (klassisch) und auf Mac:
Die neueste Nachricht (d. h. die erste Nachricht im Konversationsstapel) ist in der Nachrichtenauswahl enthalten.

Wenn sich die neueste Nachricht in der Unterhaltung in einem anderen Ordner befindet, der sich in dem aktuell angezeigten Ordner befindet, wird die nachfolgende Nachricht im Stapel im aktuellen Ordner in die Auswahl aufgenommen.

Outlook im Web und neues Outlook unter Windows:
Alle Nachrichten im Konversationsstapel sind ausgewählt. Dies schließt Nachrichten in der Unterhaltung ein, die sich in anderen Ordnern als dem aktuell angezeigten befinden.
Mehrere ausgewählte Nachrichten in einem Konversationsstapel befinden sich im selben Ordner wie die aktuell angezeigte Nachricht. Alle ausgewählten Nachrichten in derselben Unterhaltung sind in der Auswahl enthalten. Nicht zutreffend Sie müssen den Konversationsstapel erweitern, um mehrere Nachrichten daraus auszuwählen.
Mehrere ausgewählte Nachrichten in einem Konversationsstapel befinden sich in unterschiedlichen Ordnern als dem aktuell angezeigten Ordner. Alle ausgewählten Nachrichten in derselben Unterhaltung sind in der Auswahl enthalten. Nicht zutreffend Sie müssen den Konversationsstapel erweitern, um mehrere Nachrichten daraus auszuwählen.

Hinweis

Auf allen Outlook-Clients können Sie nicht mehrere Nachrichten auswählen, die zu verschiedenen Unterhaltungen gehören. Wenn Sie eine andere Unterhaltung erweitern, während eine andere Unterhaltung erweitert wird, wird die Ansicht der aktuell erweiterten Unterhaltung reduziert, und alle ausgewählten Nachrichten werden deaktiviert. Sie können jedoch mehrere Nachrichten aus derselben erweiterten Unterhaltung und Nachrichten auswählen, die nicht Teil einer Unterhaltung sind.

Anheften des Aufgabenbereichs in Add-Ins mit mehrfacher Auswahl

In Outlook im Web und im neuen Outlook unter Windows wird der Aufgabenbereich eines Add-Ins mit mehrfacher Auswahl 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 in Outlook unter Windows (klassisch) und auf Mac der Aufgabenbereich nicht automatisch angeheftet und geschlossen, wenn ein Benutzer zu einem anderen E-Mail-Element wechselt.

Nächste Schritte

Nachdem Sie Ihr Add-In nun für die Verwendung mehrerer ausgewählter Nachrichten aktiviert haben, können Sie die Funktionen Ihres Add-Ins erweitern und die Benutzerfreundlichkeit weiter verbessern. Erkunden Sie die Durchführung komplexerer Vorgänge mithilfe der Element-IDs der ausgewählten Nachrichten mit Diensten wie Microsoft Graph.

Siehe auch