Usar regras de ativação de expressões regulares para mostrar um suplemento do Outlook

  • Artigo

Você poderá especificar regras de expressão regulares para ativar um suplemento contextual quando houver uma correspondência em campos específicos da mensagem. Os suplementos contextuais são ativados somente no modo de leitura. O Outlook não ativa suplementos contextuais quando o usuário está compondo um item. Há também outros cenários em que o Outlook não ativa suplementos, por exemplo, itens conectados digitalmente. Saiba mais em Regras de ativação para suplementos do Outlook.

Importante

Os suplementos contextuais do Outlook baseados em entidade serão desativados no segundo trimestre de 2024. O trabalho para aposentar esse recurso começará em maio e continuará até o final de junho. Após junho, os suplementos contextuais não poderão mais detectar entidades em itens de email para executar tarefas neles. As APIs a seguir também serão retiradas.

Para ajudar a minimizar possíveis interrupções, o seguinte ainda será suportado depois que os suplementos contextuais baseados em entidade forem retirados.

  • Uma implementação alternativa do botão Ingressar Reunião , que é ativado por suplementos de reunião online, está sendo desenvolvida. Depois que o suporte para suplementos contextuais baseados em entidade terminar, os suplementos de reunião online farão a transição automática para a implementação alternativa para ativar o botão Ingressar Reunião .
  • As regras de expressão regular continuarão a ser suportadas depois que os suplementos contextuais baseados em entidade forem retirados. Recomendamos atualizar seu suplemento contextual para usar regras de expressão regulares como uma solução alternativa.

Para obter mais informações, consulte Aposentadoria de suplementos contextuais do Outlook baseados em entidade.

Você pode especificar uma expressão regular como parte de uma regra ItemHasRegularExpressionMatch ou de uma regra ItemHasKnownEntity no manifesto XML do suplemento. As regras são especificadas em um ponto de extensão DetectedEntity.

Observação

Suplementos contextuais do Outlook não têm suporte quando o suplemento usa um manifesto unificado para o Microsoft 365 (versão prévia).

O Outlook avalia expressões regulares com base nas regras para o interpretador JavaScript usado pelo navegador ou controle webview no computador cliente. Para obter brevidade posteriormente, este artigo usa o "navegador" para se referir a "controle de navegador ou webview". O Outlook dá suporte à mesma lista de caracteres especiais que têm suporte em todos os processadores XML. A tabela a seguir lista os caracteres especiais. Você pode usar esses caracteres em uma expressão regular especificando a sequência de escape do caractere correspondente, conforme descrito na tabela a seguir.

Caractere Descrição Sequência de escape a ser usada
" Aspas duplas "
& E comercial &
' Apóstrofo '
< Sinal menor que &lt;
> Sinal maior que &gt;

Regra ItemHasRegularExpressionMatch

Uma ItemHasRegularExpressionMatch regra é útil no controle da ativação de um suplemento com base em valores específicos de uma propriedade com suporte. A regra ItemHasRegularExpressionMatch tem os seguintes atributos.

Nome do atributo Descrição
RegExName Especifica o nome da expressão regular para que você possa referir-se à expressão no código de seu suplemento.
RegExValue Especifica a expressão regular que será avaliada para determinar se o suplemento deve ser mostrado.
PropertyName Especifica o nome da propriedade em relação à qual a expressão regular será avaliada. Os valores permitidos são BodyAsHTML, BodyAsPlaintext, SenderSMTPAddress e Subject.

Se você especificar BodyAsHTML, o Outlook só aplicará a expressão regular se o corpo do item for HTML. Caso contrário, o Outlook não retornará nenhuma correspondência para essa expressão regular.

Se você especificar BodyAsPlaintext, o Outlook sempre aplicará a expressão regular no corpo do item.

Importante: Se você precisar especificar o atributo Highlight para o <elemento Regra> , deverá definir o atributo PropertyName como BodyAsPlaintext.
IgnoreCase Especifica se deve ignorar maiúsculas e minúsculas ao fazer a correspondência da expressão regular especificada por RegExName.
Highlight Especifica como o cliente deve realçar texto correspondente. Esse elemento só pode aplicado em Rule elementos dentro de ExtensionPoint elementos. Pode ser um dos seguintes: all ou none. Se não for especificado, o valor padrão será all.

Importante: Para especificar o atributo Highlight no <elemento Regra> , você deve definir o atributo PropertyName como BodyAsPlaintext.

Práticas recomendadas para usar expressões regulares em regras

Preste atenção especial ao seguinte quando você usa expressões regulares.

  • Se você especificar uma ItemHasRegularExpressionMatch regra no corpo de um item, a expressão regular deverá filtrar ainda mais o corpo e não deve tentar retornar todo o corpo do item. Usar uma expressão regular como .* tentar obter todo o corpo de um item nem sempre retorna os resultados esperados.

  • O corpo de texto sem formatação retornado em um navegador pode ser sutilmente diferente do retornado em outro. Se você usa uma regra ItemHasRegularExpressionMatch com BodyAsPlaintext como atributo PropertyName, teste sua expressão regular em todos os navegadores compatíveis com o suplemento.

    Como diferentes navegadores usam diferentes maneiras de obter o corpo de texto de um item selecionado, você deve se certificar de que sua expressão regular dê suporte a diferenças sutis que possam ser retornadas como parte do corpo de texto. Por exemplo, alguns navegadores, como o Internet Explorer 9, usam a propriedade innerText do DOM. Outros, como o Firefox, usam o método .textContent() para obter o corpo de texto de um item. Além disso, navegadores diferentes podem retornar quebras de linha diferentes: uma quebra de linha é \r\n no Internet Explorer e \n no Firefox e no Chrome. Para saber mais, confira Compatibilidade do DOM do W3C – HTML.

  • O corpo HTML de um item é ligeiramente diferente entre o Outlook no Windows ou no Mac e Outlook na Web, em dispositivos móveis ou o novo Outlook no Windows (versão prévia). Defina as expressões regulares com cuidado.

  • Dependendo do cliente do Outlook, do tipo de dispositivo ou da propriedade na qual uma expressão regular está sendo aplicada, há outras práticas recomendadas e limites para cada um dos clientes que você deve estar ciente ao projetar expressões regulares como regras de ativação. Confira Limites de ativação e API JavaScript para suplementos do Outlook para saber mais.

Exemplos

A regra ItemHasRegularExpressionMatch a seguir ativa o suplemento sempre que o endereço de email SMTP do remetente corresponde a @contoso, independentemente dos caracteres em maiúsculas ou minúsculas.

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

A seguir está outra maneira de especificar a mesma expressão regular usando o IgnoreCase atributo.

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

A regra ItemHasRegularExpressionMatch a seguir ativa o suplemento sempre que um símbolo de ação estiver incluso no corpo do item atual.

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

Regra ItemHasKnownEntity

Uma regra ItemHasKnownEntity ativa um suplemento com base na existência de uma entidade no assunto ou no corpo do item selecionado. O tipo EntityType define as entidades compatíveis. A aplicação de uma expressão regular em uma regra ItemHasKnownEntity traz praticidade quando a ativação é baseada em um subconjunto de valores de uma entidade (por exemplo, um conjunto específico de URLs ou números de telefone com determinado código de área).

Observação

O Outlook só pode extrair cadeias de caracteres de entidade em inglês, independentemente da localidade padrão especificada no manifesto. Somente mensagens dão suporte ao MeetingSuggestion tipo de entidade; compromissos não dão suporte a isso. Você não pode extrair entidades de itens na pasta Itens Enviados , nem pode usar uma ItemHasKnownEntity regra para ativar um suplemento para itens na pasta Itens Enviados .

A regra ItemHasKnownEntity é compatível com os atributos da tabela a seguir. Embora a especificação de uma expressão regular seja opcional em uma regra ItemHasKnownEntity, se você optar por usar uma expressão regular como filtro de entidade, deverá especificar ambos os atributos RegExFilter e FilterName.

Nome do atributo Descrição
EntityType Especifica o tipo de entidade que deve ser encontrado para que a regra seja avaliada como true. Use várias regras para especificar vários tipos de entidades.
RegExFilter Especifica uma expressão regular que filtra mais instâncias da entidade especificada por EntityType.
FilterName Especifica o nome das expressões regulares especificadas por RegExFilter para que seja possível consultá-lo posteriormente por código.
IgnoreCase Especifica se deve ignorar maiúsculas e minúsculas ao fazer a correspondência da expressão regular especificada por RegExFilter.

Exemplos

A regra ItemHasKnownEntity a seguir ativa o suplemento sempre que há uma URL no assunto ou no corpo do item atual e a URL contém a cadeia de caracteres youtube, independentemente de maiúsculas e minúsculas na cadeia de caracteres.

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

Usar resultados de expressões regulares no código

Você pode obter correspondências com uma expressão regular usando os seguintes métodos no item atual.

  • getRegExMatches retorna correspondências no item atual para todas as expressões regulares especificadas nas regras ItemHasRegularExpressionMatch e ItemHasKnownEntity do suplemento.

  • getRegExMatchesByName retorna correspondências no item atual para a expressão regular especificada na regra ItemHasRegularExpressionMatch do suplemento.

  • getFilteredEntitiesByName retorna instâncias inteiras de entidades que contêm correspondências para a expressão regular identificada especificada em uma regra ItemHasKnownEntity do suplemento.

Quando as expressões regulares são avaliadas, as correspondências são retornadas para seu suplemento em um objeto de matriz. Para getRegExMatches, esse objeto tem o identificador do nome da expressão regular.

Observação

O Outlook não retorna correspondências em nenhuma ordem específica na matriz. Além disso, você não deve assumir que as correspondências são retornadas na mesma ordem nesta matriz, mesmo quando você executa o mesmo suplemento em cada um desses clientes no mesmo item na mesma caixa de correio.

Exemplos

A seguir está um exemplo de uma coleção de regras que contém uma ItemHasRegularExpressionMatch regra com uma expressão regular chamada 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>

O exemplo a seguir usa getRegExMatches do item atual para definir uma variável videos nos resultados da regra ItemHasRegularExpressionMatch anterior.

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

Várias correspondências são armazenadas como elementos de matriz nesse objeto. O exemplo de código a seguir mostra como iterar sobre as correspondências para uma expressão regular nomeada reg1 para criar uma cadeia de caracteres a ser exibida 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;
}

A seguir temos um exemplo de uma regra ItemHasKnownEntity que especifica a entidade MeetingSuggestion e uma expressão regular denominada CampSuggestion. O Outlook ativará o suplemento se detectar que o atual item selecionado contém uma sugestão de reunião e o assunto ou corpo contêm o termo WonderCamp.

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

O exemplo de código a seguir usa getFilteredEntitiesByName do item atual para definir uma variável suggestions para uma matriz de sugestões de reunião detectadas para a regra ItemHasKnownEntity anterior.

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

Confira também