Verwenden regulärer Ausdrücke für Aktivierungsregeln zum Anzeigen eines Outlook-Add-InsUse regular expression activation rules to show an Outlook add-in

Sie können festlegen, dass reguläre Ausdrucksregeln ein aktiviertes Kontext-Add-In haben müssen, wenn in bestimmten Feldern der Nachricht eine Übereinstimmung gefunden wird. Kontext-Add-Ins werden nur im Lesezugriff aktiviert, sie werden nicht aktiviert, wenn der Benutzer ein Element erstellt. Es gibt auch andere Szenarien, in denen Outlook Add-Ins nicht aktiviert, zum Beispiel wenn Elemente durch Information Rights Management (IRM) geschützt sind. Weitere Informationen finden Sie unter Aktivierungsregeln für Outlook Add-Ins.You can specify regular expression rules to have a contextual add-in activated when a match is found in specific fields of the message. Contextual add-ins activate only in read mode, Outlook does not activate contextual add-ins when the user is composing an item. There are also other scenarios where Outlook does not activate add-ins, for example, items protected by Information Rights Management (IRM). For more information, see Activation rules for Outlook add-ins.

Sie können einen regulären Ausdruck als Teil einer ItemHasRegularExpressionMatch -Regel oder ItemHasKnownEntity -Regel in der XML-Add-in-manifest. Die Regeln werden in einen Erweiterungspunkt DetectedEntity angegeben.You can specify a regular expression as part of an ItemHasRegularExpressionMatch rule or ItemHasKnownEntity rule in the add-in XML manifest. The rules are specified in a DetectedEntity extension point.

Outlook wertet reguläre Ausdrücke basierend auf den Regeln für den JavaScript-Interpreter aus, der vom Browser auf dem Client-Computer verwendet wird. Outlook unterstützt die gleiche Liste von Sonderzeichen, die alle gängigen XML-Prozessoren ebenfalls unterstützen. Die folgende Tabelle listet diese Sonderzeichen auf. Sie können diese Zeichen in einem regulären Ausdruck verwenden, indem Sie die Escape-Sequenz für das entsprechende Zeichen angeben, wie in der folgenden Tabelle beschrieben.Outlook evaluates regular expressions based on the rules for the JavaScript interpreter used by the browser on the client computer. Outlook supports the same list of special characters that all XML processors also support. The following table lists these special characters. You can use these characters in a regular expression by specifying the escaped sequence for the corresponding character, as described in the following table.


ZeichenCharacter BeschreibungDescription Zu verwendende Escape-SequenzEscape sequence to use
" Doppeltes AnführungszeichenDouble quotation mark "
& Kaufmännisches Und-ZeichenAmpersand &
' ApostrophApostrophe '
< Kleiner-als-ZeichenLess-than sign &lt;
> Größer-als-ZeichenGreater-than sign &gt;

„ItemHasRegularExpressionMatch“-RegelItemHasRegularExpressionMatch rule

Eine ItemHasRegularExpressionMatch-Regel eignet sich zum Steuern der Aktivierung eines Add-Ins basierend auf bestimmten Werten einer unterstützten Eigenschaft. Die ItemHasRegularExpressionMatch-Regel verfügt über die folgenden Attribute.An ItemHasRegularExpressionMatch rule is useful in controlling activation of an add-in based on specific values of a supported property. The ItemHasRegularExpressionMatch rule has the following attributes.


Name des AttributsAttribute name BeschreibungDescription
RegExName Gibt den Namen des regulären Ausdrucks an, damit Sie im Code Ihres Add-Ins auf den Ausdruck verweisen können.Specifies the name of the regular expression so that you can refer to the expression in the code for your add-in.
RegExValue Gibt den regulären Ausdruck an, der ausgewertet wird, um zu bestimmen, ob das Add-In angezeigt werden soll.Specifies the regular expression that will be evaluated to determine whether the add-in should be shown.
PropertyName Gibt den Namen der Eigenschaft, der der reguläre Ausdruck ausgewertet wird. Zulässige Werte sind BodyAsHTML, BodyAsPlaintext, SenderSMTPAddress und Subject.Specifies the name of the property that the regular expression will be evaluated against. The allowed values are BodyAsHTML, BodyAsPlaintext, SenderSMTPAddress, and Subject.

Wenn Sie BodyAsHTML angeben, wendet Outlook den regulären Ausdruck nur an, wenn der Text des Elements HTML ist. Andernfalls gibt Outlook keine Übereinstimmungen für diesen regulären Ausdruck zurück.If you specify BodyAsHTML, Outlook applies the regular expression only if the item body is HTML, and otherwise Outlook returns no matches for that regular expression.

Wenn Sie BodyAsPlaintext angeben, wendet Outlook stets den regulären Ausdruck auf den Text des Elements an.If you specify BodyAsPlaintext, Outlook always applies the regular expression on the item body.
IgnoreCase Gibt an, ob die Schreibung ignoriert werden soll, wenn ein Abgleich mit dem von RegExName angegebenen regulären Ausdruck erfolgt.Specifies whether to ignore case when matching the regular expression specified by RegExName.

Bewährte Methoden für das Verwenden regulärer Ausdrücke in RegelnBest practices for using regular expressions in rules

Beachten Sie beim Verwenden regulärer Ausdrücke unbedingt Folgendes:Pay special attention to the following when you use regular expressions:

  • Wenn Sie eine ItemHasRegularExpressionMatch-Regel für den Text eines Elements festlegen, 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 wie .* zum Abrufen des gesamten Textes eines Elements liefert nicht immer die erwarteten Ergebnisse.If you specify an ItemHasRegularExpressionMatch rule on the body of an item, the regular expression should further filter the body and should not attempt to return the entire body of the item. Using a regular expression such as .* to attempt to obtain the entire body of an item does not always return the expected results.
  • Der Nur-Text, der in einem Browser zurückgegeben wird, kann in einem anderen Browser geringfügig anders sein. Wenn Sie eine ItemHasRegularExpressionMatch-Regel mit BodyAsPlaintext als Attribut PropertyName verwenden, testen Sie Ihren regulären Ausdruck in allen Browsern, die Ihr Add-in unterstützt.The plain text body returned on one browser can be different in subtle ways on another. If you use an ItemHasRegularExpressionMatch rule with BodyAsPlaintext as the PropertyName attribute, test your regular expression on all the browsers that your add-in supports.

    Da verschiedene Browser unterschiedliche Möglichkeiten verwenden, um den Text eines ausgewählten Elements zu erhalten, sollten Sie sicherstellen, dass Ihr regulärer Ausdruck diese minimalen Unterschiede unterstützt, die als Teil des Textes zurückgegeben werden können. Beispielsweise verwenden einige Browser wie Internet Explorer 9 die Eigenschaft innerText des DOM, und andere wie Firefox verwenden die Methode .textContent(), um den Text eines Elements zu erhalten. Außerdem können verschiedene Browser Zeilenumbrüche unterschiedlich ausgeben: Ein Zeilenumbruch ist \r\n im Internet Explorer und \n in Firefox und Chrome. Für weitere Informationen siehe W3C DOM Kompatibilität - HTML.Because different browsers use different ways to obtain the text body of a selected item, you should make sure that your regular expression supports the subtle differences that can be returned as part of the body text. For example, some browsers such as Internet Explorer 9 uses the innerText property of the DOM, and others such as Firefox uses the .textContent() method to obtain the text body of an item. Also, different browsers may return line breaks differently: a line break is \r\n on Internet Explorer, and \n on Firefox and Chrome. For more information, se W3C DOM Compatibility - HTML.

  • Der HTML-Text eines Elements unterscheidet sich leicht zwischen einem Outlook-Rich-Client und Outlook im Web oder Outlook Mobile. Definieren Sie Ihren regulären Ausdrücken sorgfältig.The HTML body of an item is slightly different between an Outlook rich client, and Outlook on the web or Outlook mobile. Define your regular expressions carefully.

  • 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.Depending on the host application, type of device, or property that a regular expression is being applied on, there are other best practices and limits for each of the hosts that you should be aware of when designing regular expressions as activation rules. See Limits for activation and JavaScript API for Outlook add-ins for details.

BeispieleExamples

Die folgende ItemHasRegularExpressionMatch-Regel aktiviert das Add-In, wenn die SMTP-E-Mail-Adresse des Absenders @contoso entspricht, unabhängig von Groß-/Kleinschreibung.The following ItemHasRegularExpressionMatch rule activates the add-in whenever the sender's SMTP email address matches @contoso, regardless of uppercase or lowercase characters.

<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.The following is another way to specify the same regular expression using the IgnoreCase attribute.

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


Die folgende ItemHasRegularExpressionMatch-Regel aktiviert das Add-In, wenn der Text des aktuellen Elements ein Aktiensymbol enthält.The following ItemHasRegularExpressionMatch rule activates the add-in whenever a stock symbol is included in the body of the current item.

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

ItemHasKnownEntity-RegelItemHasKnownEntity rule

Eine ItemHasKnownEntity-Regel aktiviert ein Add-In, basierend auf der Existenz einer Entität im Subjekt oder Text des ausgewählten Elements. Der Typ EntityType definiert die unterstützten Entitäten. Das Anwenden eines regulären Ausdrucks auf eine ItemHasKnownEntity-Regel ist praktisch, wenn die Aktivierung auf einer Teilmenge von Werten für eine Entität basiert (z. B. eine bestimmte Menge von URLs oder Telefonnummern mit einer bestimmten Ortsvorwahl).An ItemHasKnownEntity rule activates an add-in based on the existence of an entity in the subject or body of the selected item. The EntityType type defines the supported entities. Applying a regular expression on an ItemHasKnownEntity rule provides the convenience where activation is based on a subset of values for an entity (for example, a specific set of URLs, or telephone numbers with a certain area code).

Hinweis

Outlook kann nur Entitätszeichenketten in englischer Sprache extrahieren, unabhängig von der im Manifest angegebenen Standardsprache. Der Entitätstyp MeetingSuggestion wird nur von Nachrichten unterstützt und nicht von Terminen. Sie können keine Entitäten aus Elementen im Ordner Sent Items extrahieren. Darüber hinaus können Sie keine ItemHasKnownEntity-Regel verwenden, um ein Add-In für Elemente im Ordner Sent Items zu aktivieren.Outlook can only extract entity strings in English regardless of the default locale specified in the manifest. Only messages support the MeetingSuggestion entity type; appointments do not. You cannot extract entities from items in the Sent Items folder, nor can you use an ItemHasKnownEntity rule to activate an add-in for items in the Sent Items folder.

Die Regel ItemHasKnownEntity unterstützt die Attribute in der folgenden Tabelle. Wenngleich die Angabe 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.The ItemHasKnownEntity rule supports the attributes in the following table. Note that while specifying a regular expression is optional in an ItemHasKnownEntity rule, if you choose to use a regular expression as an entity filter, you must specify both the RegExFilter and FilterName attributes.


Name des AttributsAttribute name BeschreibungDescription
EntityType Gibt den Entitätstyp an, der gefunden werden muss, damit die Regel true ausgibt. Verwenden Sie mehrere Regeln, um mehrere Entitätstypen anzugeben.Specifies the type of entity that must be found for the rule to evaluate to true. Use multiple rules to specify multiple types of entities.
RegExFilter Gibt einen regulären Ausdruck an, der Instanzen der von EntityType angegebenen Entität weiter filtert.Specifies a regular expression that further filters instances of the entity specified by EntityType.
FilterName Gibt den Namen des regulären Ausdrucks an, der von RegExFilter angegeben wird, damit anschließend auf diesen in Code verwiesen werden kann.Specifies the name of the regular expression specified by RegExFilter, so that it is subsequently possible to refer to it by code.
IgnoreCase Gibt an, ob die Schreibung ignoriert werden soll, wenn ein Abgleich mit dem von RegExFilter angegebenen regulären Ausdruck erfolgt.Specifies whether to ignore case when matching the regular expression specified by RegExFilter.

BeispieleExamples

Die folgende ItemHasKnownEntity-Regel aktiviert das Add-In, wenn es eine URL im Betreff oder Text des aktuellen Elements gibt und die URL die Zeichenfolge youtube ungeachtet von Groß-/Kleinschreibung enthält.The following ItemHasKnownEntity rule activates the add-in whenever there is a URL in the subject or body of the current item, and the URL contains the string youtube, regardless of the case of the string.

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

Verwenden der Ergebnisse regulärer Ausdrücke in CodeUsing regular expression results in code

Sie können Übereinstimmungen mit einem regulären Ausdruck erhalten, indem Sie die folgenden Methoden auf das aktuelle Element anwenden:You can obtain matches to a regular expression by using the following methods on the current item:

  • 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.getRegExMatches returns matches in the current item for all regular expressions specified in ItemHasRegularExpressionMatch and ItemHasKnownEntity rules of the add-in.

  • 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.getRegExMatchesByName returns matches in the current item for the identified regular expression specified in an ItemHasRegularExpressionMatch rule of the add-in.

  • 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.getFilteredEntitiesByName returns entire instances of entities that contain matches for the identified regular expression specified in an ItemHasKnownEntity rule of the add-in.

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 Bezeichner den Namen des regulären Ausdrucks.When the regular expressions are evaluated, the matches are returned to your add-in in an array object. For getRegExMatches, that object has the identifier of the name of the regular expression.

Hinweis

Outlook gibt im Array Übereinstimmungen nicht in einer bestimmten Reihenfolge zurück. Außerdem sollten Sie nicht davon ausgehen, dass Übereinstimmungen in diesem Array in der gleichen Reihenfolge zurückgegeben werden, auch wenn Sie das gleiche Add-In auf jedem dieser Clients auf demselben Element im selben Postfach ausführen.Outlook does not return matches in any particular order in the array. Also, you should not assume that matches are returned in the same order in this array even when you run the same add-in on each of these clients on the same item in the same mailbox.

BeispieleExamples

Es folgt ein Beispiel einer Regelsammlung, die eine ItemHasRegularExpressionMatch-Regel mit einem regulären Ausdruck namens videoURL enthält.The following is an example of a rule collection that contains an ItemHasRegularExpressionMatch rule with a regular expression named videoURL.

<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.The following example uses getRegExMatches of the current item to set a variable videos to the results of the preceding ItemHasRegularExpressionMatch rule.

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.Multiple matches are stored as array elements in that object. The following code example shows how to iterate over the matches for a regular expression named reg1 to build a string to display as HTML.

function initDialer() 
{
    var myEntities;
    var myString;
    var myCell;
    myEntities = Office.context.mailbox.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;
}


Nachfolgend ein Beispiel für eine ItemHasKnownEntity-Regel, die die Entität MeetingSuggestion und einen regulären Ausdruck namens CampSuggestion angibt. Outlook aktiviert das Add-In, wenn es erkennt, dass das aktuell ausgewählte Element einen Besprechungsvorschlag enthält und der Betreff oder der Text den Begriff WonderCamp enthält.The following is an example of an ItemHasKnownEntity rule that specifies the MeetingSuggestion entity and a regular expression named CampSuggestion. Outlook activates the add-in if it detects that the currently selected item contains a meeting suggestion, and the subject or body contains the term WonderCamp.

<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.The following code example uses getFilteredEntitiesByName on the current item to set a variable suggestions to an array of detected meeting suggestions for the preceding ItemHasKnownEntity rule.

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

Siehe auchSee also