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

Sie können Regeln mit regulären Ausdrücken angeben, damit ein Outlook-Add-In in Leseszenarios aktiviert wird; wenn der Benutzer eine Nachricht oder einen Termin im Lesebereich oder im Inspektor anzeigt, wertet Outlook Regeln mit regulären Ausdrücke aus, um festzustellen, ob das Add-In aktiviert werden soll. Diese Regeln werden von Outlook nicht ausgewertet, wenn der Benutzer ein Element verfasst. Es gibt auch andere Szenarios, in denen Add-Ins von Outlook nicht aktiviert werden, z. B. wenn Elemente durch Information Rights Management (IRM) geschützt sind. Weitere Informationen finden Sie unter Aktivierungsregeln für Outlook-Add-Ins.

Sie können einen regulären Ausdruck im XML-Manifest des Add-ins als Teil einer ItemHasRegularExpressionMatch- oder ItemHasKnownEntity-Regel angeben. Outlook wertet reguläre Ausdrücke auf Basis der Regeln für den JavaScript-Interpreter aus, der vom Browser auf dem Clientcomputer verwendet wird. 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 für das entsprechende Zeichen eingeben (siehe folgende Tabelle).

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 eignet sich zum Steuern der Aktivierung eines Add-Ins basierend auf bestimmten Werten einer unterstützten Eigenschaft. 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 Elementtext HTML ist. Andernfalls gibt Outlook keine Übereinstimmungen für diesen regulären Ausdruck zurück. Da Termine stets im RTF-Format gespeichert werden, stimmt ein regulärer Ausdruck, der BodyAsHTML angibt, nicht mit Zeichenfolgen im Textköper von Terminelementen überein.Wenn Sie BodyAsPlaintext angeben, wendet Outlook stets den regulären Ausdruck auf den Textköper des Elements an.
IgnoreCase Gibt an, ob die Schreibung ignoriert werden soll, wenn ein Abgleich mit dem von RegExName angegebenen regulären Ausdruck erfolgt.

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

Beachten Sie beim Verwenden regulärer Ausdrücke unbedingt Folgendes:

  • Wenn Sie eine ItemHasRegularExpressionMatch-Regel auf den Textkörper eines Elements anwenden, sollte der reguläre Ausdruck den Textkörper weiter filtern und nicht versuchen, den gesamten Textkörper des Elements zurückgeben. Das Verwenden eines regulären Ausdrucks wie .*, um zu versuchen, den gesamten Textkörper eines Elements abzurufen, liefert nicht immer die erwarteten Ergebnisse.

  • Der in einem Browser zurückgegebene Nur-Text-Körper kann in einem anderen geringfügig anders sein. Wenn Sie eine ItemHasRegularExpressionMatch-Regel mit BodyAsPlaintext als PropertyName-Attribut verwenden, testen Sie Ihren regulären Ausdruck in allen Browsern, 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 zwischen einem Outlook-Rich-Client und Outlook im Web oder OWA für Geräte leicht. Definieren Sie Ihre regulären Ausdrücke sorgfältig. Sehen Sie sich als Beispil den folgenden regulären Ausdruck an, der in einer ItemHasRegularExpressionMatch-Regel mit BodyAsHTML als PropertyName-Attributwert verwendet wird:

      http.*\.contoso\.com
A rule with this regular expression would match the string "http-equiv="Content-Type" which exists in the HTML body of an item in an Outlook rich client, as part of the following  **META** tag:
      <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">

In Outlook im Web und OWA für Geräten gibt dieselbe Regel nicht diesen Treffer zurück, da der HTML-Text in diesen Hosts nicht dieses META-Tag umfasst. Dies kann Auswirkungen darauf haben, ob das Add-In für die unterschiedlichen Outlook-Clients korrekt aktiviert wird. Verwenden Sie stattdessen den folgenden regulären Ausdruck:

      http://.*\.contoso\.com/
  • Je nach Hostanwendung, Gerätetyp oder Eigenschaft, auf die/den ein regulärer Ausdruck angewendet wird, gibt es andere bewährte Methoden und Einschränkungen für jeden der Hosts, die Sie kennen 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 andere 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 KnownEntityType-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 Standardgebietsschema nur Entitätszeichenfolgen in Englisch extrahieren. Der Entitätstyp MeetingSuggestion wird nur für Nachrichten, nicht aber für Termine unterstützt.Sie können keine Entitäten aus Elementen im Ordner „Gesendete Objekte“ extrahieren. Sie können auch nicht die ItemHasKnownEntity-Regel verwenden, um ein Add-In für Elemente im Ordner „Gesendete Objekte“ 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 beim Auswählen eines regulären Ausdrucks als Entitätsfilter die beiden Attribute RegExFilter und FilterName angeben.

Attributname Beschreibung
EntityType Gibt den Typ der Entität an, der gefunden werden muss, damit die Regel mit true ausgewertet wird. Verwenden Sie mehrere Regeln, um mehrere Entitätstypen anzugeben.
RegExFilter Gibt einen regulären Ausdruck an, der Vorkommen 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 erhalten, indem Sie die folgenden Methoden auf das aktuelle Elements anwenden:

  • 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 Ein Outlook-Rich-Client gibt keine Treffer in der jeweiligen Reihenfolge im Array zurück. Außerdem sollten Sie nicht davon ausgehen, dass der Outlook-Rich-Client Treffer in derselben Reihenfolge in diesem Array wie Outlook im Web oder OWA für Geräte zurückgibt, selbst dann nicht, wenn Sie dasselbe Add-In in jedem dieser Clients für dasselbe Element im gleichen Postfach ausführen. Weitere Unterschiede bei der Verarbeitung regulärer Ausdrücke zwischen einem Outlook-Rich-Client und Outlook im Web oder OWA für Geräte finden Sie unter Einschränkungen für die Aktivierung und die JavaScript-API für Outlook-Add-Ins.

Beispiele

Es folgt ein Beispiel einer Regelsammlung, die die ItemHasRegularExpressionMatch-Regel mit dem regulären Ausdruck videoURL enthä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="Body"/>
</Rule>

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

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

Mehrere Übereinstimmungen werden als Arrayelemente in diesem Objekt gespeichert. Das folgende Codebeispiel veranschaulicht das Durchlaufen der Übereinstimmungen des regulären Ausdrucks reg1 zum Erstellen einer Zeichenfolge, die als HTML angezeigt wird.

function initDialer() 
{
    var myEntities;
    var myString;
    var myCell;
    myEntities = _Item.getRegExMatches();

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

Es folgt ein Beispiel der ItemHasKnownEntity-Regel, die die Entität MeetingSuggestion und den regulären Ausdruck 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(name) des aktuellen Elements verwendet, um die Variable suggestions so festzulegen, dass ein Array erkannter Besprechungsvorschläge für die vorherige ItemHasKnownEntity-Regel abgerufen wird.

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

Zusätzliche Ressourcen