Voranstellen oder Anfügen von Inhalten an eine Nachricht oder einen Termintext beim Senden

  • Artikel

Mit den Funktionen prepend-on-send und append-on-send kann Ihr Outlook-Add-In Inhalte in den Textkörper einer Nachricht oder eines Termins einfügen, wenn das E-Mail-Element gesendet wird. Diese Features steigern die Produktivität und Sicherheit Ihrer Benutzer weiter, indem sie folgendes ermöglichen:

  • Fügen Sie ihren Nachrichten und Terminen Vertraulichkeits- und Klassifizierungsbezeichnungen hinzu, um die Identifizierung und organization von Elementen zu vereinfachen.
  • Haftungsausschlüsse für rechtliche Zwecke einfügen.
  • Fügen Sie standardisierte Header für Marketing- und Kommunikationszwecke hinzu.

In dieser exemplarischen Vorgehensweise entwickeln Sie ein Add-In, das einem Header vorangestellt und beim Senden einer Nachricht einen Haftungsausschluss anhängt.

Hinweis

Die Unterstützung für das Feature "Append-on-Send" wurde in Anforderungssatz 1.9 eingeführt, während die Unterstützung für das Prepend-on-Send-Feature in Anforderungssatz 1.13 eingeführt wurde. Weitere Informationen finden Sie unter Clients und Plattformen , die diese Anforderungssätze unterstützen.

Einrichten der Umgebung

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

Konfigurieren des Manifests

Wählen Sie zum Konfigurieren des Manifests die Registerkarte für den Typ des Manifests aus, das Sie verwenden möchten.

Im Folgenden wird gezeigt, wie Sie Ihr einheitliches Manifest so konfigurieren, dass die Features prepend-on-send und append-on-send aktiviert werden.

  1. Öffnen Sie die manifest.json Datei.

  2. Fügen Sie dem Array "extensions.runtimes" das folgende -Objekt hinzu. Beachten Sie die folgenden Aspekte in diesem Code.

    • Die "minVersion" des Postfachanforderungssatzes ist auf "1.13" festgelegt, sodass das Add-In nicht auf Plattformen und Office-Versionen installiert werden kann, auf denen dieses Feature nicht unterstützt wird.
    • Die "ID" der Laufzeit wird auf den beschreibenden Namen "function_command_runtime" festgelegt.
    • Die Eigenschaft "code.page" wird auf die URL der HTML-Datei ohne Benutzeroberfläche festgelegt, die den Funktionsbefehl lädt.
    • Die Eigenschaft "lifetime" ist auf "short" festgelegt. Dies bedeutet, dass die Laufzeit gestartet wird, wenn die Funktionsbefehlsschaltfläche ausgewählt ist, und nach Abschluss der Funktion heruntergefahren wird. (In bestimmten seltenen Fällen wird die Runtime heruntergefahren, bevor der Handler abgeschlossen ist. Siehe Runtimes in Office-Add-Ins.)
    • Es sind Aktionen angegeben, um die Funktionen "prependHeaderOnSend" und "appendDisclaimerOnSend" auszuführen. Sie erstellen diese Funktionen in einem späteren Schritt.
    {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.13"
            }
        ],
        "formFactors": [
            "desktop"
        ]
    },
    "id": "function_command_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "prependHeaderOnSend",
            "type": "executeFunction",
            "displayName": "prependHeaderOnSend"
        },
        {
            "id": "appendDisclaimerOnSend",
            "type": "executeFunction",
            "displayName": "appendDisclaimerOnSend"
        }
    ]
}

  3. Fügen Sie dem Array "extensions.ribbons" das folgende -Objekt hinzu. Beachten Sie die folgenden Aspekte in diesem Code.

    • Der Wert "mailCompose" wird dem Array "contexts" hinzugefügt, um die Schaltflächen prepend-on-send und append-on-send in einem Erstellfenster anzuzeigen.
    • Die "controls"-Objekte erstellen und konfigurieren die Schaltflächen für die Funktionen prepend-on-send und append-on-send. Die "actionId"-Eigenschaft jedes Objekts muss denselben Wert widerspiegeln, der in der anwendbaren "actions.id"-Eigenschaft des "extensions.runtimes"-Objekts angegeben ist.
    {
    "contexts": [
        "mailCompose"
    ],
    "tabs": [
        {
            "builtInTabId": "TabDefault",
            "groups": [
                {
                    "id": "msgComposeGroup",
                    "label": "Contoso Add-in",
                    "icons": [
                        {
                            "size": 16,
                            "url" "https://localhost:3000/assets/icon-16.png"
                        },
                        {
                            "size": 32,
                            "url" "https://localhost:3000/assets/icon-32.png"
                        },
                        {
                            "size": 80,
                            "url" "https://localhost:3000/assets/icon-80.png"
                        }
                    ],
                    "controls": [
                        {
                            "id": "PrependButton",
                            "type": "button",
                            "label": "Prepend header",
                            "icons": [
                                {
                                    "size": 16,
                                    "url" "https://localhost:3000/assets/icon-16.png"
                                },
                                {
                                    "size": 32,
                                    "url" "https://localhost:3000/assets/icon-32.png"
                                },
                                {
                                    "size": 80,
                                    "url" "https://localhost:3000/assets/icon-80.png"
                                }
                            ],
                            "supertip": {
                                "title": "Prepend header on send",
                                "description": "Prepend the Contoso header on send."
                            },
                            "actionId": "prependHeaderOnSend"
                        },
                        {
                            "id": "AppendButton",
                            "type": "button",
                            "label": "Add disclaimer",
                            "icons": [
                                {
                                    "size": 16,
                                    "url" "https://localhost:3000/assets/icon-16.png"
                                },
                                {
                                    "size": 32,
                                    "url" "https://localhost:3000/assets/icon-32.png"
                                },
                                {
                                    "size": 80,
                                    "url" "https://localhost:3000/assets/icon-80.png"
                                }
                            ],
                            "supertip": {
                                "title": "Append disclaimer on send",
                                "description": "Append the Contoso disclaimer on send."
                            },
                            "actionId": "appendDisclaimerOnSend"
                        }
                    ]
                }
            ]
        }
    ]
}

  4. Fügen Sie im Array "authorization.permissions.resourceSpecific" das folgende Objekt hinzu. Stellen Sie sicher, dass sie von anderen Objekten im Array durch ein Komma getrennt ist.

    {
  "name": "Mailbox.AppendOnSend.User",
  "type": "Delegated"
}

  5. Speichern Sie Ihre Änderungen.

Tipp

  • Die Features prepend-on-send und append-on-send müssen vom Benutzer über einen Aufgabenbereich oder eine Funktionsbefehlsschaltfläche aktiviert werden. Wenn Inhalte beim Senden ohne zusätzliche Aktion des Benutzers vorangestellt oder angefügt werden sollen, können Sie diese Features in einem ereignisbasierten Aktivierungs-Add-In implementieren.
  • Weitere Informationen zu Manifesten für Outlook-Add-Ins finden Sie unter Office-Add-In-Manifeste.

Implementieren des Prepend-on-Send-Handlers

In diesem Abschnitt implementieren Sie den JavaScript-Code, um einem E-Mail-Element beim Senden eine Beispiel-Firmenkopfzeile voran zu stellen.

  1. Navigieren Sie zum Ordner ./src/commands Ihres Projekts, und öffnen Sie die dateicommands.js .

  2. Fügen Sie die folgende Funktion am Ende der Datei ein.

    function prependHeaderOnSend(event) {
  // It's recommended to call the getTypeAsync method and pass its returned value to the options.coercionType parameter of the prependOnSendAsync call.
  Office.context.mailbox.item.body.getTypeAsync(
    {
      asyncContext: event
    },
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
      }

      // Sets the header to be prepended to the body of the message on send.
      const bodyFormat = asyncResult.value;
      // Because of the various ways in which HTML text can be formatted, the content may render differently when it's prepended to the mail item body.
      // In this scenario, a <br> tag is added to the end of the HTML string to preserve its format.
      const header = '<div style="border:3px solid #000;padding:15px;"><h1 style="text-align:center;">Contoso Limited</h1></div><br>';

      Office.context.mailbox.item.body.prependOnSendAsync(
        header,
        {
          asyncContext: asyncResult.asyncContext,
          coercionType: bodyFormat
        },
        (asyncResult) => {
          if (asyncResult.status === Office.AsyncResultStatus.Failed) {
            console.log(asyncResult.error.message);
            return;
          }

          console.log("The header will be prepended when the mail item is sent.");
          asyncResult.asyncContext.completed();
        }
      );
  });
}

  3. Speichern Sie Ihre Änderungen.

Implementieren des Append-on-Send-Handlers

In diesem Abschnitt implementieren Sie den JavaScript-Code, um einen Beispielausschluss eines Unternehmens an ein E-Mail-Element anzufügen, wenn es gesendet wird.

  1. Fügen Sie in derselben commands.js Datei die folgende Funktion nach der prependHeaderOnSend -Funktion ein.

    function appendDisclaimerOnSend(event) { 
  // Calls the getTypeAsync method and passes its returned value to the options.coercionType parameter of the appendOnSendAsync call.
  Office.context.mailbox.item.body.getTypeAsync(
    {
      asyncContext: event
    }, 
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
    }

    // Sets the disclaimer to be appended to the body of the message on send.
    const bodyFormat = asyncResult.value;
    const disclaimer =
      '<p style = "color:blue"> <i>This and subsequent emails on the same topic are for discussion and information purposes only. Only those matters set out in a fully executed agreement are legally binding. This email may contain confidential information and should not be shared with any third party without the prior written agreement of Contoso. If you are not the intended recipient, take no action and contact the sender immediately.<br><br>Contoso Limited (company number 01624297) is a company registered in England and Wales whose registered office is at Contoso Campus, Thames Valley Park, Reading RG6 1WG</i></p>';  

    Office.context.mailbox.item.body.appendOnSendAsync(
      disclaimer,
      {
        asyncContext: asyncResult.asyncContext,
        coercionType: bodyFormat
      },
      (asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          console.log(asyncResult.error.message);
          return;
        }

        console.log("The disclaimer will be appended when the mail item is sent.");
        asyncResult.asyncContext.completed();
      }
    );
  });
}

  2. Speichern Sie Ihre Änderungen.

Registrieren der JavaScript-Funktionen

  1. Fügen Sie in derselben commands.js Datei folgendes nach der appendDisclaimerOnSend -Funktion ein. Diese Aufrufe ordnen den im Manifest angegebenen Funktionsnamen seiner JavaScript-Entsprechung zu. Der Speicherort des Funktionsnamens im Manifest variiert je nach Art des Manifests, das ihr Add-In verwendet.

  • Nur Add-In-Manifest: Der im <FunctionName-Element> angegebene Funktionsname.

  • Einheitliches Manifest für Microsoft 365: Der Funktionsname, der in der Eigenschaft "id" der Objekte im Array "extensions.runtimes.actions" angegeben ist.

    Office.actions.associate("prependHeaderOnSend", prependHeaderOnSend);
Office.actions.associate("appendDisclaimerOnSend", appendDisclaimerOnSend);
  1. Speichern Sie Ihre Änderungen.

Probieren Sie es aus

  1. Führen Sie den folgenden Befehl im Stammverzeichnis Ihres Projekts aus. Wenn Sie diesen Befehl ausführen, wird der lokale Webserver gestartet, wenn er noch nicht ausgeführt wird, und Ihr Add-In wird quergeladen.

    npm start

    Hinweis

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

  2. Erstellen Sie eine neue Nachricht, und fügen Sie sich der Zeile An hinzu.

  3. (Optional) Geben Sie Text im Textkörper der Nachricht ein.

  4. Wählen Sie im Menüband oder Überlaufmenü Kopfzeile voranstellen aus.

  5. Wählen Sie im Menüband oder Überlaufmenü Haftungsausschluss hinzufügen aus.

  6. Senden Sie die Nachricht, und öffnen Sie sie dann im Ordner Posteingang oder Gesendete Elemente , um den eingefügten Inhalt anzuzeigen.

    Ein Beispiel für eine gesendete Nachricht mit vorangestelltem Contoso-Header und dem an den Text angefügten Haftungsausschluss.

    Tipp

    Da Inhalte erst vorangestellt oder angefügt werden, nachdem die Nachricht gesendet wurde, kann der Absender nur den hinzugefügten Inhalt aus dem Ordner "Posteingang" oder " Gesendete Elemente " anzeigen. Wenn Der Absender den hinzugefügten Inhalt anzeigen muss, bevor die Nachricht gesendet wird, lesen Sie Einfügen von Daten in den Textkörper beim Verfassen eines Termins oder einer Nachricht in Outlook.

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

Überprüfen des Featureverhaltens und der Einschränkungen

Beachten Sie beim Implementieren von prepend-on-send und append-on-send in Ihrem Add-In Folgendes:

  • Prepend-on-Send und append-on-send werden nur im Verfassenmodus unterstützt.

  • Die Zeichenfolge, die vorangestellt oder angefügt werden soll, darf 5.000 Zeichen nicht überschreiten.

  • HTML kann nicht vorangestellt oder an einen Nur-Text-Text einer Nachricht oder eines Termins angefügt werden. Nur-Text kann jedoch einem HTML-formatierten Textkörper einer Nachricht oder eines Termins hinzugefügt werden.

  • Jede Formatierung, die auf vorangestellte oder angefügte Inhalte angewendet wird, wirkt sich nicht auf den Stil des restlichen Textkörpers des E-Mail-Elements aus.

  • Prepend-on-Send und append-on-send können nicht in dem add-in implementiert werden, das das On-Send-Feature implementiert. Alternativ können Sie stattdessen intelligente Warnungen implementieren.

  • Bei der Implementierung von intelligenten Warnungen im selben Add-In erfolgen die Vorgänge prepend-on-send und append-on-send vor den OnMessageSend Ereignishandlervorgängen und OnAppointmentSend .

  • Wenn mehrere aktive Add-Ins prepend-on-send oder append-on-send verwenden, hängt die Reihenfolge des einzufügenden Inhalts von der Reihenfolge ab, in der das Add-In ausgeführt wurde. Für prepend-on-send wird der Inhalt des Add-Ins, das zuletzt ausgeführt wird, oben im Textkörper des E-Mail-Elements vor dem zuvor vorangestellten Inhalt angezeigt. Für append-on-send wird der Inhalt des Add-Ins, das zuletzt ausgeführt wird, am unteren Rand des E-Mail-Elementtexts nach dem zuvor angefügten Inhalt angezeigt.

  • Szenarien für Stellvertretungen und freigegebene Postfächer werden unterstützt, solange das Add-In, das prepend-on-send oder append-on-send implementiert, für das freigegebene Postfach oder das Konto des Besitzers aktiviert ist.

Problembehandlung für Ihr Add-In

Wenn beim Implementieren der Features prepend-on-send und append-on-send ein Fehler auftritt, finden Sie anleitungen in der folgenden Tabelle.

Fehler Beschreibung Lösung
DataExceedsMaximumSize Der Inhalt, der angefügt oder vorangestellt werden soll, ist länger als 5.000 Zeichen. Kürzen Sie die Zeichenfolge, die Sie an den data -Parameter ihres prependOnSendAsync - oder appendOnSendAsync -Aufrufs übergeben.
InvalidFormatError Der Nachrichten- oder Termintext ist im Nur-Text-Format, aber das coercionType an die prependOnSendAsync -Methode oder appendOnSendAsync -Methode übergebene ist auf Office.CoercionType.Htmlfestgelegt. Nur Nur-Text kann in einen Nur-Text-Text einer Nachricht oder eines Termins eingefügt werden. Um das Format des zu erstellenden E-Mail-Elements zu überprüfen, rufen Sie Office.context.mailbox.item.body.getTypeAsyncauf, und übergeben Sie dann den zurückgegebenen Wert an Ihren prependOnSendAsyncappendOnSendAsync Oder -Aufruf.

Siehe auch