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 Regeln mit regulären Ausdrücken angeben, damit ein Kontext-Add-In aktiviert wird, wenn eine Übereinstimmung in bestimmten Feldern der Nachricht gefunden wird.You can specify regular expression rules to have a contextual add-in activated when a match is found in specific fields of the message. Kontext-Add-Ins werden nur im Lesemodus aktiviert. Kontext-Add-Ins werden von Outlook nicht aktiviert, wenn der Benutzer ein Element verfasst.Contextual add-ins activate only in read mode, Outlook does not activate contextual add-ins when the user is composing an item. 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.There are also other scenarios where Outlook does not activate add-ins, for example, items protected by Information Rights Management (IRM). Weitere Informationen finden Sie unter Aktivierungsregeln für Outlook-Add-Ins.For more information, see Activation rules for Outlook add-ins.

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

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 evaluates regular expressions based on the rules for the JavaScript interpreter used by the browser on the client computer. Outlook unterstützt dieselbe Liste von Sonderzeichen, die alle XML-Prozessoren ebenfalls unterstützen.Outlook supports the same list of special characters that all XML processors also support. Die folgende Tabelle enthält diese Sonderzeichen.The following table lists these special characters. Sie können diese Zeichen in einem regulären Ausdruck verwenden, indem Sie die Escapesequenz für das entsprechende Zeichen angeben, wie in der folgenden Tabelle beschrieben.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 EscapesequenzEscape 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.An ItemHasRegularExpressionMatch rule is useful in controlling activation of an add-in based on specific values of a supported property. Die ItemHasRegularExpressionMatch-Regel hat die folgenden Attribute.The ItemHasRegularExpressionMatch rule has the following attributes.

AttributnameAttribute 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 an, für die der reguläre Ausdruck ausgewertet wird.Specifies the name of the property that the regular expression will be evaluated against. Die zulässigen Werte sind BodyAsHTML, BodyAsPlaintext, SenderSMTPAddress und Subject.The allowed values are BodyAsHTML, BodyAsPlaintext, SenderSMTPAddress, and 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.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 Textkörper 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 Textkörper eines Elements festlegen, sollte der reguläre Ausdruck den Textkörper weiter filtern und nicht versuchen, den gesamten Textkörper des Elements zurückzugeben.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. Wenn mit einem regulären Ausdruck wie .* der gesamte Textkörper eines Elements abgerufen werden soll, werden nicht immer die gewünschten Ergebnisse erzielt.Using a regular expression such as .* to attempt to obtain the entire body of an item does not always return the expected results.
  • Der in einem Browser zurückgegebene Nur-Text-Körper kann sich in einem anderen geringfügig unterscheiden.The plain text body returned on one browser can be different in subtle ways on another. 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.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 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.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. 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.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. Unterschiedliche Browser geben möglicherweise auch Zeilenumbrüche unterschiedlich zurück: In Internet Explorer ist ein Zeilenumbruch \r\n, in Firefox und Chrome \n.Also, different browsers may return line breaks differently: a line break is \r\n on Internet Explorer, and \n on Firefox and Chrome. Weitere Informationen finden Sie unter W3C-DOM-Kompatibilität – HTML.For more information, se W3C DOM Compatibility - HTML.

  • Der HTML-Text eines Elements unterscheidet sich zwischen einem Outlook-Rich-Client und Outlook im Web oder Outlook Mobile leicht.The HTML body of an item is slightly different between an Outlook rich client, and Outlook on the web or Outlook mobile. Definieren Sie Ihre regulären Ausdrücke sorgfältig.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 Textkörper 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 dem Vorhandensein einer Entität im Betreff oder Textkörper des ausgewählten Elements.An ItemHasKnownEntity rule activates an add-in based on the existence of an entity in the subject or body of the selected item. Der KnownEntityType-Typ definiert die unterstützten Entitäten.The KnownEntityType type defines the supported entities. 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).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 ungeachtet des in der Manifestdatei angegebenen Standardgebietsschemas nur Entitätszeichenfolgen in Englisch extrahieren.Outlook can only extract entity strings in English regardless of the default locale specified in the manifest. Nur Nachrichten unterstützen den MeetingSuggestion-Entitätstyp; für Termine gilt dies nicht.Only messages support the MeetingSuggestion entity type; appointments do not. Sie können keine Entitäten aus Elementen im Ordner Gesendete Elemente extrahieren. Sie können auch keine ItemHasKnownEntity-Regel verwenden, um ein Add-In für Elemente im Ordner Gesendete Elemente zu aktivieren.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 ItemHasKnownEntity-Regel unterstützt die Attribute in der folgenden Tabelle.The ItemHasKnownEntity rule supports the attributes in the following table. 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.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.

AttributnameAttribute name BeschreibungDescription
EntityType Gibt den Entitätstyp an, der gefunden werden muss, damit die Regel true ausgibt.Specifies the type of entity that must be found for the rule to evaluate to true. Verwenden Sie mehrere Regeln, um mehrere Entitätstypen anzugeben.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 Textkörper 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.When the regular expressions are evaluated, the matches are returned to your add-in in an array object. Bei getRegExMatches hat dieses Objekt als ID den Namen des regulären Ausdrucks.For getRegExMatches, that object has the identifier of the name of the regular expression.

Hinweis

Outlook gibt die Übereinstimmungen in keiner bestimmten Reihenfolge im Array zurück.Outlook does not return matches in any particular order in the array. Sie können auch nicht davon ausgehen, dass die Übereinstimmungen bei Ausführung des Add-Ins auf jedem dieser Clients für das gleiche Element im selben Postfach in derselben Reihenfolge in diesem Array zurückgegeben werden.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;
}

Im Folgenden finden Sie ein Beispiel für eine ItemHasKnownEntity-Regel, die die MeetingSuggestion-Entität und einen regulären Ausdruck namens CampSuggestion angibt.The following is an example of an ItemHasKnownEntity rule that specifies the MeetingSuggestion entity and a regular expression named CampSuggestion. 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.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