Verwenden regulärer Ausdrücke für Aktivierungsregeln zum Anzeigen eines Outlook-Add-Ins

  • Artikel

Sie können Regeln mit regulären Ausdrücken angeben, damit ein Kontext-Add-In aktiviert wird, wenn eine Übereinstimmung in bestimmten Feldern der Nachricht gefunden wird. Kontextbezogene Add-Ins werden nur im Lesemodus aktiviert. Outlook aktiviert keine Kontext-Add-Ins, wenn der Benutzer ein Element erstellt. Es gibt auch andere Szenarien, in denen Outlook keine Add-Ins aktiviert, z. B. digital signierte Elemente. Weitere Informationen finden Sie unter Aktivierungsregeln für Outlook-Add-Ins.

Wichtig

Entitätsbasierte kontextbezogene Outlook-Add-Ins werden im 2. Quartal 2024 eingestellt. Die Arbeiten zur Einstellung dieses Features beginnen im Mai und werden bis Ende Juni fortgesetzt. Nach Juni können Kontext-Add-Ins keine Entitäten mehr in E-Mail-Elementen erkennen, um Aufgaben für sie auszuführen. Die folgenden APIs werden ebenfalls eingestellt.

Um potenzielle Unterbrechungen zu minimieren, werden die folgenden Elemente weiterhin unterstützt, nachdem entitätsbasierte Kontext-Add-Ins eingestellt wurden.

  • Eine alternative Implementierung der Schaltfläche " An Besprechung teilnehmen ", die von Onlinebesprechungs-Add-Ins aktiviert wird, wird entwickelt. Sobald die Unterstützung für entitätsbasierte Kontext-Add-Ins endet, werden Onlinebesprechungs-Add-Ins automatisch zur alternativen Implementierung übergehen, um die Schaltfläche An Besprechung teilnehmen zu aktivieren.
  • Regeln für reguläre Ausdrücke werden weiterhin unterstützt, nachdem entitätsbasierte Kontext-Add-Ins eingestellt wurden. Es wird empfohlen, Ihr Kontext-Add-In zu aktualisieren, um Regeln für reguläre Ausdrücke als alternative Lösung zu verwenden.

Weitere Informationen finden Sie unter Außerbetriebnahme entitätsbasierter kontextbezogener Outlook-Add-Ins.

Sie können einen regulären Ausdruck im XML-Manifest des Add-Ins als Teil einer ItemHasRegularExpressionMatch- oder ItemHasKnownEntity-Regel angeben. Die Regeln werden in einem DetectedEntity-Erweiterungspunkt angegeben.

Hinweis

Kontextbezogene Outlook-Add-Ins werden nicht unterstützt, wenn das Add-In ein einheitliches Manifest für Microsoft 365 (Vorschau) verwendet.

Outlook wertet reguläre Ausdrücke basierend auf den Regeln für den JavaScript-Interpreter aus, der vom Browser- oder Webview-Steuerelement auf dem Clientcomputer verwendet wird. Aus Gründen der Übersichtlichkeit wird in diesem Artikel "Browser" verwendet, um auf "Browser- oder Webansichtssteuerelement" zu verweisen. Outlook unterstützt dieselbe Liste von Sonderzeichen, die alle XML-Prozessoren ebenfalls unterstützen. Die folgende Tabelle enthält diese Sonderzeichen. Sie können diese Zeichen in einem regulären Ausdruck verwenden, indem Sie die Escapesequenz des entsprechenden Zeichens angeben, wie in der folgenden Tabelle beschrieben.

Zeichen Beschreibung Zu verwendende Escapesequenz
" Doppeltes Anführungszeichen "
& Kaufmännisches Und-Zeichen &
' Apostroph '
< Kleiner-als-Zeichen &lt;
> Größer-als-Zeichen &gt;

"ItemHasRegularExpressionMatch"-Regel

Eine ItemHasRegularExpressionMatch Regel ist nützlich, um die Aktivierung eines Add-Ins basierend auf bestimmten Werten einer unterstützten Eigenschaft zu steuern. Die ItemHasRegularExpressionMatch-Regel hat die folgenden Attribute.

Attributname Beschreibung
RegExName Gibt den Namen des regulären Ausdrucks an, damit Sie im Code Ihres Add-Ins auf den Ausdruck verweisen können.
RegExValue Gibt den regulären Ausdruck an, der ausgewertet wird, um zu bestimmen, ob das Add-In angezeigt werden soll.
PropertyName Gibt den Namen der Eigenschaft an, für die der reguläre Ausdruck ausgewertet wird. Die zulässigen Werte sind BodyAsHTML, BodyAsPlaintext, SenderSMTPAddress und Subject.

Wenn Sie BodyAsHTML angeben, wendet Outlook den regulären Ausdruck nur an, wenn der Textkörper HTML ist. Andernfalls gibt Outlook keine Übereinstimmungen für diesen regulären Ausdruck zurück.

Wenn Sie BodyAsPlaintext angeben, wendet Outlook stets den regulären Ausdruck auf den Textkörper des Elements an.

Wichtig: Wenn Sie das Highlight-Attribut für das <Rule-Element> angeben müssen, müssen Sie das PropertyName-Attribut auf BodyAsPlaintextfestlegen.
IgnoreCase Gibt an, ob die Schreibung ignoriert werden soll, wenn ein Abgleich mit dem von RegExName angegebenen regulären Ausdruck erfolgt.
Highlight Gibt an, wie der Client übereinstimmenden Text hervorheben soll. Dieses Element kann nur auf Rule-Elemente innerhalb von ExtensionPoint-Elementen angewendet werden. Folgende Werte sind möglich: all oder none. Falls keine Angabe erfolgt, ist der Standardwert all.

Wichtig: Um das Highlight-Attribut im <Rule-Element> anzugeben, müssen Sie das PropertyName-Attribut auf BodyAsPlaintextfestlegen.

Bewährte Methoden für das Verwenden regulärer Ausdrücke in Regeln

Achten Sie besonders auf folgendes, wenn Sie reguläre Ausdrücke verwenden.

  • Wenn Sie eine ItemHasRegularExpressionMatch Regel für den Textkörper eines Elements angeben, sollte der reguläre Ausdruck den Text weiter filtern und nicht versuchen, den gesamten Text des Elements zurückzugeben. Die Verwendung eines regulären Ausdrucks, z .* . B. zum Abrufen des gesamten Textkörpers eines Elements, gibt nicht immer die erwarteten Ergebnisse zurück.

  • Der in einem Browser zurückgegebene Nur-Text-Körper kann sich in einem anderen geringfügig unterscheiden. Wenn Sie eine ItemHasRegularExpressionMatch-Regel mit BodyAsPlaintext als PropertyName-Attribut verwenden, sollten Sie Ihren regulären Ausdruck in allen Browsern testen, die Ihr Add-In unterstützt.

    Da unterschiedliche Browser unterschiedliche Methoden zum Abrufen des Textkörpers eines ausgewählten Elements verwenden, sollten Sie sicherstellen, dass Ihr regulärer Ausdruck die feinen Unterschiede unterstützt, die als Teil des Textkörpers zurückgegeben werden können. Einige Browser wie Internet Explorer 9 verwenden z. B. die innerText-Eigenschaft des DOM, andere Browser wiederum, z. B. Firefox, verwenden die .textContent()-Methode, um den Textkörper eines Elements abzurufen. Unterschiedliche Browser geben möglicherweise auch Zeilenumbrüche unterschiedlich zurück: In Internet Explorer ist ein Zeilenumbruch \r\n, in Firefox und Chrome \n. Weitere Informationen finden Sie unter W3C-DOM-Kompatibilität – HTML.

  • Der HTML-Text eines Elements unterscheidet sich geringfügig zwischen Outlook unter Windows oder macos und Outlook im Web, auf mobilen Geräten oder neuen Outlook unter Windows (Vorschau). Definieren Sie Ihre regulären Ausdrücke sorgfältig.

  • Je nach Outlook-Client, Gerätetyp oder Eigenschaft, auf den ein regulärer Ausdruck angewendet wird, gibt es weitere bewährte Methoden und Grenzwerte für jeden der Clients, die Sie beachten sollten, wenn Sie reguläre Ausdrücke als Aktivierungsregeln entwerfen. Weitere Informationen finden Sie unter Grenzwerte für Aktivierung und JavaScript-API für Outlook-Add-Ins.

Beispiele

Die folgende ItemHasRegularExpressionMatch-Regel aktiviert das Add-In, wenn die SMTP-E-Mail-Adresse des Absenders @contoso entspricht, unabhängig von Groß-/Kleinschreibung.

<Rule xsi:type="ItemHasRegularExpressionMatch"
    RegExName="addressMatches"
    RegExValue="@[cC][oO][nN][tT][oO][sS][oO]"
    PropertyName="SenderSMTPAddress"
/>

Es folgt eine weitere Möglichkeit, denselben regulären Ausdruck mithilfe des IgnoreCase -Attributs anzugeben.

<Rule xsi:type="ItemHasRegularExpressionMatch"
    RegExName="addressMatches"
    RegExValue="@contoso"
    PropertyName="SenderSMTPAddress"
    IgnoreCase="true"
/>

Die folgende ItemHasRegularExpressionMatch-Regel aktiviert das Add-In, wenn der Textkörper des aktuellen Elements ein Aktiensymbol enthält.

<Rule xsi:type="ItemHasRegularExpressionMatch"
    PropertyName="BodyAsPlaintext"
    RegExName="TickerSymbols"
    RegExValue="\b(NYSE|NASDAQ|AMEX):\s*[A-Za-z]+\b"/>

ItemHasKnownEntity-Regel

Eine ItemHasKnownEntity-Regel aktiviert ein Add-In basierend auf dem Vorhandensein einer Entität im Betreff oder Textkörper des ausgewählten Elements. Der EntityType-Typ definiert die unterstützten Entitäten. Das Anwenden eines regulären Ausdrucks auf eine ItemHasKnownEntity-Regel bewirkt die bequeme Aktivierung basierend auf einer Untermenge von Werten für eine Entität (z. B. einer bestimmten Gruppe von URLs oder von Telefonnummern mit einer bestimmten Vorwahl).

Hinweis

Outlook kann ungeachtet des in der Manifestdatei angegebenen Standardgebietsschemas nur Entitätszeichenfolgen in Englisch extrahieren. Nur Nachrichten unterstützen den MeetingSuggestion Entitätstyp; Termine unterstützen dies nicht. Sie können keine Entitäten aus Elementen im Ordner "Gesendete Elemente " extrahieren und auch ItemHasKnownEntity keine Regel verwenden, um ein Add-In für Elemente im Ordner "Gesendete Elemente " zu aktivieren.

Die ItemHasKnownEntity-Regel unterstützt die Attribute in der folgenden Tabelle. Wenngleich das Angeben eines regulären Ausdrucks in einer ItemHasKnownEntity-Regel optional ist, müssen Sie bei Verwendung eines regulären Ausdrucks als Entitätsfilter die beiden Attribute RegExFilter und FilterName angeben.

Attributname Beschreibung
EntityType Gibt den Entitätstyp an, der gefunden werden muss, damit die Regel true ausgibt. Verwenden Sie mehrere Regeln, um mehrere Entitätstypen anzugeben.
RegExFilter Gibt einen regulären Ausdruck an, der Instanzen der von EntityType angegebenen Entität weiter filtert.
FilterName Gibt den Namen des regulären Ausdrucks an, der von RegExFilter angegeben wird, damit anschließend auf diesen in Code verwiesen werden kann.
IgnoreCase Gibt an, ob die Schreibung ignoriert werden soll, wenn ein Abgleich mit dem von RegExFilter angegebenen regulären Ausdruck erfolgt.

Beispiele

Die folgende ItemHasKnownEntity-Regel aktiviert das Add-In, wenn es eine URL im Betreff oder Textkörper des aktuellen Elements gibt und die URL die Zeichenfolge youtube ungeachtet von Groß-/Kleinschreibung enthält.

<Rule xsi:type="ItemHasKnownEntity"
    EntityType="Url"
    RegExFilter="youtube"
    FilterName="youtube"
    IgnoreCase="true"/>

Verwenden der Ergebnisse regulärer Ausdrücke in Code

Sie können Übereinstimmungen mit einem regulären Ausdruck mithilfe der folgenden Methoden für das aktuelle Element abrufen.

  • getRegExMatches gibt Übereinstimmungen im aktuellen Element für alle regulären Ausdrücke zurück, die in den Regeln ItemHasRegularExpressionMatch und ItemHasKnownEntity des Add-Ins angegeben sind.

  • getRegExMatchesByName gibt Übereinstimmungen im aktuellen Element für den angegebenen regulären Ausdruck zurück, der in einer ItemHasRegularExpressionMatch-Regel des Add-Ins angegeben ist.

  • getFilteredEntitiesByName gibt gesamte Instanzen von Entitäten mit Übereinstimmungen mit dem angegebenen regulären Ausdruck zurück, der in einer ItemHasKnownEntity-Regel des Add-Ins angegeben ist.

Wenn die regulären Ausdrücke ausgewertet werden, erfolgt die Rückgabe der Übereinstimmungen an Ihr Add-In in einem Arrayobjekt. Bei getRegExMatches hat dieses Objekt als ID den Namen des regulären Ausdrucks.

Hinweis

Outlook gibt keine Übereinstimmungen in einer bestimmten Reihenfolge im Array zurück. Außerdem sollten Sie nicht davon ausgehen, dass Übereinstimmungen in derselben Reihenfolge in diesem Array zurückgegeben werden, auch wenn Sie dasselbe Add-In auf jedem dieser Clients für dasselbe Element im selben Postfach ausführen.

Beispiele

Im Folgenden finden Sie ein Beispiel für eine Regelauflistung, die eine ItemHasRegularExpressionMatch Regel mit einem regulären Ausdruck namens videoURLenthält.

<Rule xsi:type="RuleCollection" Mode="And">
    <Rule xsi:type="ItemIs" ItemType="Message"/>
    <Rule xsi:type="ItemHasRegularExpressionMatch" RegExName="videoURL" RegExValue="http://www\.youtube\.com/watch\?v=[a-zA-Z0-9_-]{11}" PropertyName="BodyAsPlaintext"/>
</Rule>

Im folgenden Beispiel wird getRegExMatches des aktuellen Elements verwendet, um die Variable videos auf das Ergebnis der vorherigen ItemHasRegularExpressionMatch-Regel festzulegen.

const videos = Office.context.mailbox.item.getRegExMatches().videoURL;

Mehrere Übereinstimmungen werden als Arrayelemente in diesem Objekt gespeichert. Das folgende Codebeispiel zeigt, wie die Übereinstimmungen für einen regulären Ausdruck mit dem Namen reg1 durchlaufen werden, um eine Zeichenfolge zu erstellen, die als HTML angezeigt werden soll.

function initDialer()
{
    let myEntities;
    let myString;
    let myCell;
    myEntities = Office.context.mailbox.item.getRegExMatches();

    myString = "";
    myCell = document.getElementById('dialerholder');
    // Loop over the myEntities collection.
    for (let i in myEntities.reg1) {
        myString += "<p><a href='callto:tel:" + myEntities.reg1[i] + "'>" + myEntities.reg1[i] + "</a></p>";
    }

    myCell.innerHTML = myString;
}

Im Folgenden finden Sie ein Beispiel für eine ItemHasKnownEntity-Regel, die die MeetingSuggestion-Entität und einen regulären Ausdruck namens CampSuggestion angibt. Outlook aktiviert das Add-In, wenn erkannt wird, dass das aktuell ausgewählte Element einen Besprechungsvorschlag enthält und der Betreff oder Textkörper den Begriff WonderCamp enthält.

<Rule xsi:type="ItemHasKnownEntity"
    EntityType="MeetingSuggestion"
    RegExFilter="WonderCamp"
    FilterName="CampSuggestion"
    IgnoreCase="false"/>

Im folgenden Codebeispiel wird getFilteredEntitiesByName für das aktuelle Element verwendet, um die Variable suggestions auf ein Array erkannter Besprechungsvorschläge für die vorherige ItemHasKnownEntity-Regel festzulegen.

const suggestions = Office.context.mailbox.item.getFilteredEntitiesByName("CampSuggestion");

Siehe auch