Utiliser des règles d’activation d’expression régulière pour afficher un complément Outlook

  • Article

Vous pouvez spécifier des règles d’expressions régulières pour qu’un complément contextuel soit activé lorsqu’une correspondance est trouvée dans les champs spécifiques du message. Les compléments contextuels s’activent uniquement en mode lecture. Outlook n’active pas les compléments contextuels lorsque l’utilisateur compose un élément. Il existe également d’autres scénarios dans lesquels Outlook n’active pas les compléments, par exemple les éléments signés numériquement. Pour plus d’informations, reportez-vous à la rubrique Règles d’activation pour les compléments Outlook.

Importante

Les compléments Outlook contextuels basés sur des entités seront mis hors service au deuxième trimestre 2024. Le travail de mise hors service de cette fonctionnalité commencera en mai et se poursuivra jusqu’à la fin du mois de juin. Après juin, les compléments contextuels ne seront plus en mesure de détecter les entités dans les éléments de courrier pour effectuer des tâches sur ces derniers. Les API suivantes seront également mises hors service.

Pour réduire les interruptions potentielles, les éléments suivants seront toujours pris en charge une fois les compléments contextuels basés sur des entités mis hors service.

  • Une autre implémentation du bouton Participer à une réunion , qui est activé par les compléments de réunion en ligne, est en cours de développement. Une fois la prise en charge des compléments contextuels basés sur des entités terminée, les compléments de réunion en ligne passent automatiquement à l’implémentation alternative pour activer le bouton Participer à une réunion .
  • Les règles d’expression régulière continueront d’être prises en charge une fois les compléments contextuels basés sur des entités mis hors service. Nous vous recommandons de mettre à jour votre complément contextuel pour utiliser des règles d’expression régulière comme solution alternative.

Pour plus d’informations, consultez Retrait des compléments Outlook contextuels basés sur des entités.

Vous pouvez spécifier une expression régulière dans le cadre d’une règle ItemHasRegularExpressionMatch ou ItemHasKnownEntity dans le manifeste XML du complément. Les règles sont spécifiées dans un point d’extension DetectedEntity.

Remarque

Les compléments Outlook contextuels ne sont pas pris en charge lorsque le complément utilise un manifeste unifié pour Microsoft 365.

Outlook évalue les expressions régulières en fonction des règles de l’interpréteur JavaScript utilisé par le navigateur ou le contrôle webview sur l’ordinateur client. Par souci de concision ci-dessous, cet article utilise « navigateur » pour faire référence à « navigateur ou contrôle webview ». Outlook prend en charge la même liste de caractères spéciaux que tous les processeurs XML. Le tableau suivant répertorie ces caractères spéciaux. Vous pouvez utiliser ces caractères dans une expression régulière en spécifiant la séquence d’échappement du caractère correspondant, comme décrit dans le tableau suivant.

Caractère Description Séquence d’échappement à utiliser
" Guillemets doubles "
& Esperluette &
' Apostrophe '
< Signe inférieur à &lt;
> Signe supérieur à &gt;

Règle ItemHasRegularExpressionMatch

Une ItemHasRegularExpressionMatch règle est utile pour contrôler l’activation d’un complément en fonction des valeurs spécifiques d’une propriété prise en charge. La règle ItemHasRegularExpressionMatch contient les attributs suivants.

Nom de l’attribut Description
RegExName Spécifie le nom de l’expression régulière afin que vous puissiez vous référer à l’expression dans le code de votre complément.
RegExValue Spécifie l’expression régulière qui sera évaluée pour déterminer si le complément doit être affiché.
PropertyName Spécifie le nom de la propriété par rapport à laquelle l’expression sera évaluée. Les valeurs autorisées sont BodyAsHTML, BodyAsPlaintext, SenderSMTPAddress et Subject.

Si vous spécifiez BodyAsHTML, Outlook applique seulement l’expression régulière si le corps de l’élément est du code HTML. Si ce n’est pas le cas, Outlook ne renvoie aucune correspondance pour cette expression régulière.

Si vous spécifiez BodyAsPlaintext, Outlook applique toujours l’expression régulière au corps de l’élément.

Important: Si vous devez spécifier l’attribut Highlight pour l’élément <Rule> , vous devez définir l’attribut PropertyName sur BodyAsPlaintext.
IgnoreCase Spécifie s’il faut ignorer la casse pour la correspondance avec l’expression régulière spécifiée par RegExName.
Highlight Spécifie la façon dont le client doit mettre en évidence le texte correspondant. Cet élément peut uniquement s’appliquer à des éléments Rule au sein d’éléments ExtensionPoint. Peut correspondre à l’une des valeurs suivantes : all ou none. Si non spécifié, la valeur par défaut est all.

Important: Pour spécifier l’attribut Highlight dans l’élément <Rule> , vous devez définir l’attribut PropertyName sur BodyAsPlaintext.

Meilleures pratiques pour l’utilisation d’expressions régulières dans les règles

Portez une attention particulière aux éléments suivants lorsque vous utilisez des expressions régulières.

  • Si vous spécifiez une ItemHasRegularExpressionMatch règle sur le corps d’un élément, l’expression régulière doit filtrer davantage le corps et ne doit pas tenter de retourner l’intégralité du corps de l’élément. L’utilisation d’une expression régulière telle que .* pour tenter d’obtenir l’intégralité du corps d’un élément ne retourne pas toujours les résultats attendus.

  • Le corps en texte brut renvoyé sur un navigateur peut être légèrement différent sur un autre. Si vous utilisez une règle ItemHasRegularExpressionMatch avec BodyAsPlaintext comme attribut PropertyName, testez votre expression régulière sur tous les navigateurs pris en charge par votre complément.

    Comme différents navigateurs utilisent diverses méthodes pour obtenir le corps du texte d’un élément sélectionné, vous devez vous assurer que votre expression régulière prend en charge les fines différences qui peuvent être renvoyées dans le cadre du corps de texte. Par exemple, certains navigateurs, comme Internet Explorer 9, utilisent la propriété innerText du DOM, tandis que d’autres, comme Firefox, utilisent la méthode .textContent() afin d’obtenir le corps du texte d’un élément. En outre, différents navigateurs peuvent renvoyer des sauts de ligne de manière différente : un saut de ligne correspond à \r\n sur Internet Explorer, et \n dans Firefox et Chrome. Pour plus d’informations, consultez la page sur la compatibilité DOM W3C - HTML.

  • Le corps HTML d’un élément est légèrement différent entre outlook classique sur Windows ou Outlook sur Mac, et Outlook sur le web, sur les appareils mobiles ou nouveau Outlook sur Windows (préversion). Définissez attentivement vos expressions régulières.

  • Selon le client Outlook, le type d’appareil ou la propriété sur lequel une expression régulière est appliquée, il existe d’autres bonnes pratiques et limites pour chacun des clients que vous devez connaître lors de la conception d’expressions régulières en tant que règles d’activation. Pour plus d’informations, voir Limites d’activation et d’API JavaScript des compléments Outlook.

Exemples

La règle ItemHasRegularExpressionMatch suivante active le complément chaque fois que l’adresse de messagerie SMTP de l’expéditeur correspond à @contoso, indépendamment des caractères majuscules et minuscules.

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

Voici une autre façon de spécifier la même expression régulière à l’aide de l’attribut IgnoreCase .

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

La règle ItemHasRegularExpressionMatch suivante active le complément chaque fois qu’un symbole de valeur est inclus dans le corps de l’élément actuel.

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

Règle ItemHasKnownEntity

Une règle ItemHasKnownEntity active un complément en fonction de l'existence d'une entité dans le sujet ou le corps de l'élément sélectionné. Le type EntityType définit les entités prises en charge. L’application d’une expression régulière sur une règle ItemHasKnownEntity convient lorsque l’activation est basée sur un sous-ensemble de valeurs pour une entité (par exemple, un ensemble spécifique d’URL, ou des numéros de téléphone avec un certain code régional).

Remarque

Outlook peut extraire uniquement des chaînes d’entité en anglais, indépendamment des paramètres régionaux par défaut spécifiés dans le manifeste. Seuls les messages prennent en charge le MeetingSuggestion type d’entité ; les rendez-vous ne le prennent pas en charge. Vous ne pouvez pas extraire d’entités à partir d’éléments du dossier Éléments envoyés , ni utiliser une ItemHasKnownEntity règle pour activer un complément pour les éléments du dossier Éléments envoyés .

La règle ItemHasKnownEntity prend en charge les attributs dans le tableau suivant. Notez que, bien que la spécification d’une expression régulière soit facultative dans une règle ItemHasKnownEntity, si vous choisissez d’utiliser une expression régulière comme filtre d’entité, vous devez spécifier à la fois l’attribut RegExFilter et FilterName.

Nom de l’attribut Description
EntityType Spécifie le type d’entité à rechercher pour que la règle donne la valeur true. Utilisez plusieurs règles pour spécifier plusieurs types d’entités.
RegExFilter Spécifie une expression régulière qui filtre les instances de l’entité spécifiée par EntityType.
FilterName Spécifie le nom de l’expression régulière spécifiée par RegExFilter, afin qu’il soit possible d’y faire référence ultérieurement par code.
IgnoreCase Spécifie s’il faut ignorer la casse pour la correspondance avec l’expression régulière spécifiée par RegExFilter.

Exemples

La règle ItemHasKnownEntity suivante active le complément chaque fois qu’une URL se trouve dans l’objet ou le corps de l’élément actuel, et qu’elle contient la chaîne youtube, indépendamment de la casse de cette chaîne.

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

Utilisation des résultats d’expressions régulières dans le code

Vous pouvez obtenir des correspondances à une expression régulière à l’aide des méthodes suivantes sur l’élément actif.

  • getRegExMatches renvoie les correspondances dans l’élément actuel pour toutes les expressions régulières spécifiées dans les règles ItemHasRegularExpressionMatch et ItemHasKnownEntity du complément.

  • getRegExMatchesByName renvoie les correspondances dans l’élément actuel pour l’expression régulière identifiée, spécifiée dans une règle ItemHasRegularExpressionMatch du complément.

  • getFilteredEntitiesByName renvoie les instances complètes des entités qui contiennent des correspondances avec l’expression régulière identifiée, spécifiée dans une règle ItemHasKnownEntity du complément.

Lorsque les expressions régulières sont évaluées, les correspondances sont renvoyées vers votre complément dans un objet tableau. Pour getRegExMatches, cet objet a un identifiant correspondant au nom de l’expression régulière.

Remarque

Outlook ne retourne aucune correspondance dans un ordre particulier dans le tableau. En outre, vous ne devez pas supposer que les correspondances sont retournées dans le même ordre dans ce tableau, même lorsque vous exécutez le même complément sur chacun de ces clients sur le même élément dans la même boîte aux lettres.

Exemples

Voici un exemple de collection de règles qui contient une ItemHasRegularExpressionMatch règle avec une expression régulière nommée 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="BodyAsPlaintext"/>
</Rule>

L’exemple suivant utilise getRegExMatches dans l’élément actuel pour définir une variable videos pour les résultats de la règle ItemHasRegularExpressionMatch précédente.

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

Plusieurs correspondances sont stockées comme éléments d’un tableau dans cet objet. L’exemple de code suivant montre comment itérer sur les correspondances pour une expression régulière nommée reg1 afin de générer une chaîne à afficher au format HTML.

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;
}

Voici un exemple de règle ItemHasKnownEntity qui spécifie l’entité MeetingSuggestion et une expression régulière nommée CampSuggestion. Outlook active le complément s’il détecte que l’élément sélectionné contient une suggestion de réunion, et que l’objet ou le corps contient le terme WonderCamp.

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

L’exemple de code suivant utilise getFilteredEntitiesByName sur l’élément actuel pour définir une variable suggestions pour un tableau des suggestions de réunion détectées pour la règle ItemHasKnownEntity précédente.

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

Voir aussi