Usar reglas de activación de expresiones regulares para mostrar un complemento de Outlook

  • Artículo

Puede especificar reglas de expresiones regulares para que se active un complemento contextual cuando se encuentre una coincidencia en campos específicos del mensaje. Los complementos contextuales solo se activan en modo de lectura. Outlook no activa complementos contextuales cuando el usuario está redactando un elemento. También hay otros escenarios en los que Outlook no activa complementos, por ejemplo, elementos firmados digitalmente. Para obtener más información, vea Reglas de activación para complementos de Outlook.

Importante

Los complementos contextuales de Outlook basados en entidades se retirarán en el segundo trimestre de 2024. El trabajo para retirar esta característica comenzará en mayo y continuará hasta finales de junio. Después de junio, los complementos contextuales ya no podrán detectar entidades en elementos de correo para realizar tareas en ellos. También se retirarán las siguientes API.

Para ayudar a minimizar las posibles interrupciones, se seguirá admitiendo lo siguiente después de que se retiren los complementos contextuales basados en entidades.

  • Se está desarrollando una implementación alternativa del botón Unirse a la reunión , que se activa mediante complementos de reunión en línea. Una vez finalizada la compatibilidad con complementos contextuales basados en entidades, los complementos de reunión en línea pasarán automáticamente a la implementación alternativa para activar el botón Unirse a la reunión .
  • Las reglas de expresión regular seguirán siendo compatibles después de retirar los complementos contextuales basados en entidades. Se recomienda actualizar el complemento contextual para usar reglas de expresión regular como solución alternativa.

Para obtener más información, vea Retirada de complementos contextuales de Outlook basados en entidades.

Puede especificar una expresión regular como parte de una regla de ItemHasRegularExpressionMatch o una regla de ItemHasKnownEntity en el manifiesto XML del complemento. Las reglas se especifican en un punto de extensión de DetectedEntity.

Nota:

Los complementos contextuales de Outlook no se admiten cuando el complemento usa un manifiesto unificado para Microsoft 365 (versión preliminar).

Outlook evalúa las expresiones regulares en función de las reglas para el intérprete de JavaScript que usa el explorador o el control webview en el equipo cliente. Para mayor brevedad, en este artículo se usa "browser" para hacer referencia al "control browser o webview". Outlook admite la misma lista de caracteres especiales admitidos por todos los procesadores de XML. En la tabla siguiente, se muestra una lista de estos caracteres especiales. Puede usar estos caracteres en una expresión regular especificando la secuencia de escape del carácter correspondiente, como se describe en la tabla siguiente.

Carácter Descripción Secuencia de escape que se usará
" Comillas dobles "
& Y comercial &
' Apóstrofo '
< Signo de menor que &lt;
> Signo de mayor que &gt;

Regla ItemHasRegularExpressionMatch

Una ItemHasRegularExpressionMatch regla es útil para controlar la activación de un complemento en función de valores específicos de una propiedad admitida. La regla ItemHasRegularExpressionMatch tiene los atributos siguientes.

Nombre del atributo Descripción
RegExName Especifica el nombre de una expresión regular para que pueda hacer referencia a esa expresión en el código del complemento.
RegExValue Especifica la expresión regular que se evaluará para determinar si se tiene que mostrar el complemento.
PropertyName Especifica el nombre de la propiedad que se evaluará con la expresión regular. Los valores permitidos son BodyAsHTML, BodyAsPlaintext, SenderSMTPAddress y Subject.

Si especifica BodyAsHTML, Outlook solo aplicará la expresión regular si el cuerpo del elemento es HTML. En caso contrario, Outlook no devuelve ninguna coincidencia de esa expresión regular.

Si especifica BodyAsPlaintext, Outlook siempre aplicará la expresión regular en el cuerpo del elemento.

Importante: Si necesita especificar el atributo Highlight para el <elemento Rule> , debe establecer el atributo PropertyName en BodyAsPlaintext.
IgnoreCase Especifica si se distingue mayúsculas de minúsculas al buscar resultados coincidentes con la expresión regular especificada por RegExName.
Highlight Especifica cómo debe resaltar el cliente el texto coincidente. Este elemento solo puede aplicarse para elementos Rule dentro de elementos ExtensionPoint. Puede ser uno de los siguientes: all o none. Si no se especifica, el valor predeterminado es all.

Importante: Para especificar el atributo Highlight en el <elemento Rule>, debe establecer el atributo BodyAsPlaintextPropertyName en .

Procedimientos recomendados para usar expresiones regulares en reglas

Preste especial atención a lo siguiente cuando use expresiones regulares.

  • Si especifica una ItemHasRegularExpressionMatch regla en el cuerpo de un elemento, la expresión regular debe filtrar aún más el cuerpo y no debe intentar devolver todo el cuerpo del elemento. El uso de una expresión regular como .* para intentar obtener todo el cuerpo de un elemento no siempre devuelve los resultados esperados.

  • El cuerpo del texto sin formato que se muestre en un explorador puede ser ligeramente distinto en otro. Si usa una regla ItemHasRegularExpressionMatch con BodyAsPlaintext como el atributo de PropertyName, pruebe la expresión regular en todos los exploradores compatibles con el complemento.

    Dado que los distintos exploradores usan diferentes formas de obtener el cuerpo del texto de un elemento seleccionado, debe asegurarse de que la expresión regular es compatible con las diferencias sutiles que pueden devolverse como parte del texto del cuerpo. Por ejemplo, algunos exploradores (como Internet Explorer 9) usan la propiedad innerText del DOM, mientras que otros (como Firefox) usan el método .textContent() para obtener el cuerpo del texto de un elemento. Además, cada explorador puede devolver los saltos de línea de manera diferente: un salto de línea es \r\n en Internet Explorer, y \n en Firefox y Chrome. Para obtener más información, vea Compatibilidad de DOM del W3C: HTML.

  • El cuerpo HTML de un elemento es ligeramente diferente entre outlook clásico en Windows o Outlook en Mac, y Outlook en la Web, en dispositivos móviles o nuevo Outlook en Windows (versión preliminar). Defina con cuidado las expresiones regulares.

  • En función del cliente de Outlook, el tipo de dispositivo o la propiedad en la que se está aplicando una expresión regular, hay otros procedimientos recomendados y límites para cada uno de los clientes que debe tener en cuenta al diseñar expresiones regulares como reglas de activación. Vea Límites de activación y API de JavaScript para complementos de Outlook para más información.

Ejemplos

La regla ItemHasRegularExpressionMatch siguiente activa el complemento cada vez que la dirección de correo electrónico SMTP del remitente coincida con @contoso, independientemente del uso de caracteres en mayúsculas o minúsculas.

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

La siguiente es otra manera de especificar la misma expresión regular mediante el IgnoreCase atributo .

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

La siguiente regla ItemHasRegularExpressionMatch activa el complemento siempre que se incluya el símbolo de un valor en el cuerpo del elemento actual.

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

Regla ItemHasKnownEntity

Una regla ItemHasKnownEntity activa un complemento basándose en la existencia de una entidad en el asunto o el cuerpo del elemento seleccionado. El tipo EntityType define las entidades admitidas. Aplicar una expresión regular en una regla ItemHasKnownEntity permite realizar una activación basándose en un subconjunto de valores de una entidad (por ejemplo, un conjunto específico de direcciones URL, o bien números de teléfono con un código de área concreto).

Nota:

Outlook solo puede extraer cadenas de entidad en inglés, independientemente de la configuración regional predeterminada que se especifique en el manifiesto. Solo los mensajes admiten el MeetingSuggestion tipo de entidad; las citas no admiten esto. No puede extraer entidades de elementos de la carpeta Elementos enviados ni puede usar una ItemHasKnownEntity regla para activar un complemento para los elementos de la carpeta Elementos enviados .

La regla ItemHasKnownEntity admite los atributos de la tabla siguiente. Tenga en cuenta que, aunque especificar una expresión regular es opcional en una regla ItemHasKnownEntity, si decide usar una expresión regular como un filtro de entidades, tendrá que especificar los atributos RegExFilter y FilterName.

Nombre del atributo Descripción
EntityType Especifica el tipo de entidad que se tiene que encontrar para que la regla dé como resultado true. Permite usar varias reglas para especificar distintos tipos de entidades.
RegExFilter Especifica una expresión regular que filtra aún más las instancias de la entidad especificada por EntityType.
FilterName Especifica el nombre de la expresión regular especificada por RegExFilter para que, posteriormente, se pueda hacer referencia a esta con código.
IgnoreCase Especifica si se distingue mayúsculas de minúsculas al buscar resultados con la expresión regular especificada por RegExFilter.

Ejemplos

En el siguiente ejemplo de regla ItemHasKnownEntity, se activa el complemento siempre que el asunto o el cuerpo del elemento actual contenga una dirección URL con la cadena youtube, independientemente del uso de mayúsculas.

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

Usar resultados de expresiones regulares en el código

Puede obtener coincidencias con una expresión regular mediante los métodos siguientes en el elemento actual.

  • getRegExMatches muestra resultados en el elemento actual de todas las expresiones regulares especificadas en las reglas ItemHasRegularExpressionMatch y ItemHasKnownEntity del complemento.

  • getRegExMatchesByName muestra resultados en el elemento actual de la expresión regular identificada que se especifica en una regla ItemHasRegularExpressionMatch del complemento.

  • getFilteredEntitiesByName muestra instancias enteras de entidades que contengan resultados de la expresión regular identificada que se especifica en una regla ItemHasKnownEntity del complemento.

Al evaluar las expresiones regulares, los resultados se devuelven al complemento en un objeto de matriz. Para getRegExMatches, ese objeto tiene el identificador del nombre de la expresión regular.

Nota:

Outlook no devuelve coincidencias en ningún orden determinado de la matriz. Además, no debe suponer que las coincidencias se devuelven en el mismo orden en esta matriz, incluso cuando se ejecuta el mismo complemento en cada uno de estos clientes en el mismo elemento del mismo buzón.

Ejemplos

A continuación se muestra un ejemplo de una colección de reglas que contiene una ItemHasRegularExpressionMatch regla con una expresión regular denominada 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>

En el ejemplo siguiente, se usa getRegExMatches del elemento actual para establecer una variable videos para los resultados de la regla ItemHasRegularExpressionMatch anterior.

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

Varios resultados se almacenan como elementos de matriz en dicho objeto. En el ejemplo de código siguiente se muestra cómo recorrer en iteración las coincidencias de una expresión regular denominada reg1 para compilar una cadena que se muestre como 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;
}

Este es un ejemplo de una regla ItemHasKnownEntity que especifica la entidad MeetingSuggestion y una expresión regular llamada CampSuggestion. Outlook activa el complemento si identifica que el elemento seleccionado actualmente contiene una sugerencia de reunión, y que el asunto o el cuerpo contienen el término WonderCamp.

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

En el ejemplo de código siguiente, se usa getFilteredEntitiesByName del elemento actual para establecer una variable suggestions con el fin de obtener una matriz de las sugerencias de reunión identificadas para la regla ItemHasKnownEntity anterior.

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

Vea también