Compartilhar via


Funções IsMatch, Match e MatchAll

Aplica-se a: Aplicativos Canvas Aplicativos baseados em modelo Power Pages Power Platform CLI

Testa uma correspondência ou extrai partes de uma cadeia de texto com base em um padrão.

Descrição

A função IsMatch testa se uma cadeia de texto corresponde a um padrão que pode incluir caracteres comuns, padrões predefinidos, ou uma expressão regular. As funções Match e MatchAll retornam o que foi correspondido, incluindo subcorrespondências.

Use IsMatch para validar o que um usuário digitou em um controle Text input. Por exemplo, você pode confirmar se o usuário inseriu um endereço de email válido antes do resultado ser salvo em sua fonte de dados. Se a entrada não corresponder aos seus critérios, adicione outros controles que solicitam que o usuário corrija a entrada.

Use Match para extrair a primeira cadeia de texto que corresponde a um padrão e MatchAll para extrair todas as cadeias de texto correspondentes. Você também pode extrair subcorrespondências para analisar cadeias de caracteres complexas.

Match retorna um registro de informações para a primeira correspondência encontrada e MatchAll retorna uma tabela de registros para cada correspondência encontrada. O registro ou os registros contêm:

Column Type Description
subcorrespondência nomeada ou subcorrespondências Texto Cada subcorrespondência nomeada terá sua própria coluna. Crie uma subcorrespondência nomeada usando (?<nome>...) na expressão regular. Se uma subcorrespondência nomeada tiver o mesmo nome que uma das colunas predefinidas (abaixo), a subcorrespondência terá precedência e um aviso será gerado. Para evitar esse aviso, renomeie a subcorrespondência.
Correspondência completa Text Toda a cadeia de texto que foi correspondida.
Começar a partida Número A posição inicial da correspondência na cadeia de texto de entrada. O primeiro caractere da cadeia de caracteres retorna 1.
Subcorrespondências Tabela de coluna única de texto (coluna Valor) A tabela de subcorrespondências nomeadas e sem nome na ordem em que aparecem na expressão regular. Geralmente, as subcorrespondências nomeadas são mais fáceis de trabalhar e são incentivadas. Use a função ForAll ou as funções Last( FirstN( ... ) ) para trabalhar com uma subcorrespondência individual. Se nenhuma subcorrespondência for definida na expressão regular, essa tabela estará presente, mas vazia.

Essas funções dão suporte a MatchOptions. Por padrão:

  • Essas funções executam uma correspondência que diferencia maiúsculas de minúsculas. Use MatchOptions.IgnoreCase para executar correspondências que não diferenciam maiúsculas de minúsculas.
  • IsMatch corresponde à sequência de texto inteira (Complete MatchOption), enquanto Match e MatchAll procuram uma correspondência em qualquer lugar da sequência de texto (Contains MatchOption). Use Complete, Contains, BeginsWith ou EndsWith conforme apropriado para seu cenário.

IsMatch retorna true se a sequência de texto corresponde ao padrão ou false se não corresponde. Match retorna em branco se nenhuma correspondência for encontrada que possa ser testada com a função IsBlank . MatchAll retorna uma tabela vazia se nenhuma correspondência for encontrada que possa ser testada com a função IsEmpty .

Se você estiver usando o MatchAll para dividir uma cadeia de texto, considere usar a função Split, que é mais simples de usar e mais rápida.

Padrões

A chave para usar essas funções é descrever o padrão para corresponder. Você descreve o padrão em uma cadeia de texto como uma combinação de:

  • Caracteres normais, como "abc" ou "123".
  • Padrões predefinidos, como letra, MultipleDigits, ou Email. (A enumeração Match define esses padrões.)
  • Códigos de expressões regulares, como "\d+\s+\d+" ou "[a-z] +".

Combinar esses elementos usando o operador de concatenação de cadeia de caracteres &. Por exemplo, "abc" & Digit & "\s+" é um padrão válido que corresponde aos caracteres "a", "b" e "c", seguido por um dígito de 0 a 9, seguido por, pelo menos, um caractere de espaço em branco.

Caracteres comuns

O padrão mais simples é uma sequência de caracteres comuns a ser correspondida exatamente.

Por exemplo, quando usado com a função IsMatch , a cadeia de caracteres "Hello" corresponde ao padrão "Hello" exatamente. Nem mais, nem menos. A cadeia de caracteres "olá!" não corresponde ao padrão por causa do ponto de exclamação no final e porque a correspondência de maiúscula e minúscula é incorreta para a letra "h". (Consulte MatchOptions para maneiras de modificar esse comportamento.)

No idioma padrão, determinados caracteres são reservados para fins especiais. Para usar esses caracteres, prefixe o caractere com \ (barra invertida) para indicar que o caractere deve ser levado literalmente ou use um dos padrões predefinidos descritos posteriormente neste tópico. Esta tabela lista os caracteres especiais:

Caractere especial Descrição
. ponto
? ponto de interrogação
* asterisco
+ positivo
( ) parênteses
[ ] colchetes
{ } chaves
^ caret
$ cifrão
| barra vertical ou pipe
\ barra invertida

Por exemplo, você pode corresponder "Olá?" usando o padrão "Olá\?" com uma barra invertida antes do ponto de interrogação.

Padrões predefinidos

Padrões predefinidos fornecem uma maneira simples para corresponder a um conjunto de caracteres ou uma sequência de vários caracteres. Use o operador de concatenação de cadeia de caracteres& para combinar suas próprias cadeias de texto com membros da enumeração Match:

Enumeração Match Descrição Expressão regular
Qualquer Corresponde a qualquer caractere. .
Vírgula Corresponde a uma vírgula. ,
Dígito Corresponde a um único dígito ("0" a "9"). \d
E-mail Corresponde a um endereço de email que contém um símbolo de "arroba" ("@") e um nome de domínio que contém um ponto (".") .+\@.+\\.[^\\.]{2,}
Hífen Corresponde a um hífen. \-
Parênteses Esquerdos Corresponde a um parêntese esquerdo “(“. \(
Carta Corresponde a uma letra. \p{L}
Vários dígitos Corresponde a um ou mais dígitos. \d+
LetrasMúltiplas Corresponde a uma ou mais letras. \p{L}+
Vários Não Espaços Corresponde a um ou mais caracteres que não adicionam espaço em branco (não a espaço, tabulação ou nova linha). \S+
Espaços Múltiplos Corresponde a um ou mais caracteres que adicionam espaço em branco (espaço, tabulação ou nova linha). \s+
Não-espaço Corresponde a um único caractere que não adiciona espaço em branco. \S
Dígitos opcionais Corresponde a zero, um ou mais dígitos. \d*
Letras Opcionais Corresponde a zero, uma ou mais letras. \p{L}*
OptionalNonSpaces Corresponde a zero, um ou mais caracteres que não adicionam espaço em branco. \S*
Espaços Opcionais Corresponde a zero, um ou mais caracteres que adicionam espaço em branco. \s*
Período Corresponde a um ponto ("."). \.
Parênteses Direitas Corresponde a um parêntese direito “)”. \)
Espaço Corresponde a um caractere que adiciona o espaço em branco. \s
Aba Corresponde a um caractere de tabulação. \t

Por exemplo, o padrão "A" & MultipleDigits corresponderá à letra "A" seguida por um ou mais dígitos.

Expressões regulares

O padrão usado por essas funções é uma expressão regular. Os caracteres comuns e padrões predefinidos descritos anteriormente neste tópico ajudam a criar expressões regulares.

Expressões regulares são muito poderosas, disponíveis em muitas linguagens de programação e usadas em uma ampla variedade de finalidades. Geralmente, eles também podem parecer uma sequência aleatória de sinais de pontuação. Este artigo não descreve todos os aspectos de expressões regulares, mas uma infinidade de informações, tutoriais e ferramentas estão disponíveis na Web.

As expressões regulares vêm em dialetos diferentes, e os Power Apps usam uma variante do dialeto do JavaScript. Consulte a sintaxe de expressão regular para obter uma introdução à sintaxe. Há suporte para subcorrespondências nomeadas (às vezes chamadas de grupos de captura nomeados):

  • Sub-correspondências nomeadas: (?<nome> ...)
  • Referências anteriores nomeadas: \k<nome>

Na tabela de enumeração Match anteriormente neste tópico, cada enumeração aparece na mesma linha que a sua expressão regular correspondente.

Opções de correspondência

Você pode modificar o comportamento dessas funções especificando uma ou mais opções, que podem ser combinadas usando o operador de concatenação de cadeia de caracteres (&).

Enumeração MatchOptions Description Impacto em uma expressão regular
MatchOptions.ComeçaCom O padrão deve corresponder desde o início do texto. Adiciona um ^ ao início da expressão regular.
MatchOptions.Complete Padrão para IsMatch. O padrão deve aparecer em algum lugar no texto, mas não precisa começar ou terminar com ele. Adiciona um ^ ao início e um $ ao final da expressão regular.
MatchOptions.Contém Padrão para Match e MatchAll. O padrão deve aparecer em algum lugar no texto, mas não precisa começar ou terminar com ele. Não modifica a expressão regular.
MatchOptions.TerminaCom O padrão deve corresponder ao fim da cadeia de texto. Adiciona um $ ao final da expressão regular.
MatchOptions.IgnorarCaso Trata letras maiúsculas e minúsculas como idênticas. Por padrão, a correspondência diferencia maiúsculas de minúsculas. Não modifica a expressão regular. Essa opção é equivalente ao modificador "i" padrão para expressões regulares.
MatchOptions.Multilinha Corresponde em várias linhas. Não modifica a expressão regular. Essa opção é equivalente ao modificador "m" padrão para expressões regulares.

O uso de MatchAll é equivalente ao uso do modificador "g" padrão para expressões regulares.

Sintaxe

IsMatch( Texto, Padrão [, Opções ] )

  • Texto – Obrigatório. A cadeia de texto a ser testada.
  • Padrão – Obrigatório. O padrão a ser testado como uma cadeia de texto. Concatenar padrões predefinidos que a enumeração Match define ou fornece uma expressão regular. O padrão deve ser uma fórmula constante, sem variáveis, fontes de dados ou outras referências dinâmicas que mudam à medida que o aplicativo é executado.
  • Opções – Opcional. Uma combinação de cadeia de texto de valores de enumeração MatchOptions. Por padrão, MatchOptions.Complete é usado.

Correspondência( Texto, Padrão [, Opções ] )

  • Texto – Obrigatório. A cadeia de texto a ser correspondida.
  • Padrão – Obrigatório. O padrão a ser correspondido como uma cadeia de texto. Concatenar padrões predefinidos que a enumeração Match define ou fornece uma expressão regular. O padrão deve ser uma fórmula constante, sem variáveis, fontes de dados ou outras referências dinâmicas que mudam à medida que o aplicativo é executado.
  • Opções – Opcional. Uma combinação de cadeia de texto de valores de enumeração MatchOptions. Por padrão, MatchOptions.Contains é usado.

MatchAll( Texto, Padrão [, Opções ] )

  • Texto – Obrigatório. A cadeia de texto a ser correspondida.
  • Padrão – Obrigatório. O padrão a ser correspondido como uma cadeia de texto. Concatenar padrões predefinidos que a enumeração Match define ou fornece uma expressão regular. O padrão deve ser uma fórmula constante, sem variáveis, fontes de dados ou outras referências dinâmicas que mudam à medida que o aplicativo é executado.
  • Opções – Opcional. Uma combinação de cadeia de texto de valores de enumeração MatchOptions. Por padrão, MatchOptions.Contains é usado.

Exemplos de IsMatch

Caracteres comuns

Imagine que seu aplicativo contém um controle Text input chamado TextInput1. O usuário insere valores neste controle para ser armazenado em um banco de dados.

O usuário digita Hello world em TextInput1.

Fórmula Descrição Resultado
IsMatch( TextInput1.Text, "Hello world" ) Testa se a entrada do usuário corresponde, exatamente, à cadeia de caracteres "Hello world". verdadeiro
IsMatch( TextInput1.Text, "Good bye" ) Testa se a entrada do usuário corresponde, exatamente, à cadeia de caracteres "Good bye". falso
IsMatch( TextInput1.Text, "hello", Contains ) Testa se a entrada do usuário contém a palavra "hello" (com distinção entre maiúsculas e minúsculas). falso
IsMatch( TextInput1.Text, "hello", Contains & IgnoreCase ) Testa se a entrada do usuário contém a palavra "hello" (sem distinção entre maiúsculas e minúsculas). verdadeiro

Padrões predefinidos

Fórmula Descrição Resultado
IsMatch( "123-45-7890", Digit & Digit & Digit & Hyphen & Digit & Digit & Hyphen & Digit & Digit & Digit & Digit ) Corresponde a um número do Seguro Social dos Estados Unidos verdadeiro
IsMatch( "joan@contoso.com", Email ) Corresponde a um endereço de email verdadeiro
IsMatch( "123.456", MultipleDigits & Period & OptionalDigits ) Corresponde a uma sequência de dígitos, um ponto e, em seguida, zero ou mais dígitos. verdadeiro
IsMatch( "123", MultipleDigits & Period & OptionalDigits ) Corresponde a uma sequência de dígitos, um ponto e, em seguida, zero ou mais dígitos. Um ponto não aparece no texto para corresponder, portanto, esse padrão não é correspondido. falso

Expressões regulares

Fórmula Descrição Resultado
IsMatch( "986", "\d+" ) Corresponde a um número inteiro maior que zero. verdadeiro
IsMatch( "1.02", "\d+(\.\d\d)?" ) Corresponde a um valor de moeda positivo. Se a entrada contiver um ponto decimal, a entrada também deverá conter dois caracteres numéricos após o ponto decimal. Por exemplo, 3,00 é válido, mas 3,1 não é. verdadeiro
IsMatch( "-4.95", "(-)?\d+(\.\d\d)?" ) Corresponde a um valor de moeda positivo ou negativo. Se a entrada contiver um ponto decimal, a entrada também deverá conter dois caracteres numéricos após o ponto decimal. verdadeiro
IsMatch( "111-11-1111", "\d{3}-\d{2}-\d{4}" ) Corresponde a um número do Seguro Social dos Estados Unidos. Valida o formato, o tipo e o comprimento do campo de entrada fornecido. A cadeia de caracteres a ser correspondida deve conter três caracteres numéricos seguidos por um traço e, em seguida, dois caracteres numéricos seguidos por um traço e, em seguida, quatro caracteres numéricos. verdadeiro
IsMatch( "111-111-111", "\d{3}-\d{2}-\d{4}" ) Mesmo que no exemplo anterior, mas um hífen está fora do lugar na entrada. falso
IsMatch( "AStrongPasswordNot", "(?!^[0-9]\*$)(?!^[a-zA-Z]\*$)([a-zA-Z0-9]{8,10})" ) Valida uma senha forte, que deve conter oito, nove ou 10 caracteres, além de pelo menos um dígito e pelo menos um caractere alfabético. A cadeia de caracteres não deve conter caracteres especiais. falso

Exemplos de Match e MatchAll

Fórmula Descrição Resultado
Match( "Bob Jones <bob.jones@contoso.com>", "<(?<email>" & Match.Email & ")>" Extrai apenas a parte de email das informações de contato. {
email: "bob.jones@contoso.com",
FullMatch: "<bob.jones@contoso.com>",
SubMatches: [ "bob.jones@contoso.com" ],
StartMatch: 11
}
Match( "Bob Jones <InvalidEmailAddress>", "<(?<email>" & Match.Email & ")>" Extrai apenas a parte de email das informações de contato. Nenhum endereço legal foi encontrado (não há nenhum sinal de @), portanto, a função retorna blank. em branco
Match( Language(), "(<language>\w{2})(?:-(?<script>\w{4}))?(?:-(?<region>\w{2}))?" ) Extrai as partes de idioma, script e região da marca de idioma que a função Language retorna. Esses resultados refletem o Estados Unidos; consulte a documentação da função Language para obter mais exemplos. O operador (?: agrupa caracteres sem criar outra subcorrespondência. {
language: "en",
script: blank,
region: "US",
FullMatch: "en-US",
SubMatches: [ "en", "", "US" ],
StartMatch: 1
}
Match( "PT2H1M39S", "PT(?:<hours>\d+)H)?(?:(?<minutes>\d+)M)?(?:(?<seconds>\d+)S)?" ) Extrai as horas, os minutos e os segundos de um valor de duração ISO 8601. Os números extraídos ainda estão em uma cadeia de texto; Use a função Value para convertê-la em um número antes que as operações matemáticas sejam executadas nela. {
hours: "2",
minutes: "1",
seconds: "39",
FullMatch: "PT2H1M39S",
Subcorrespondências:["2","1","39"],
StartMatch: 1
}

Vamos analisar o último exemplo. Se você quisesse converter essa cadeia de caracteres em um valor de data/hora usando a função Time, deverá passar as subcorrespondências nomeadas individualmente. Para fazer isso, você pode usar a função With operando no registro que o Match retorna:

With(
    Match( "PT2H1M39S", "PT(?:(?<hours>\d+)H)?(?:(?<minutes>\d+)M)?(?:(?<seconds>\d+)S)?" ),
   Time( Value( hours ), Value( minutes ), Value( seconds ) )
)

Para esses exemplos, adicione um controle Button, defina sua propriedade OnSelect como esta fórmula e, em seguida, selecione o botão:

Set( pangram, "The quick brown fox jumps over the lazy dog." )
Fórmula Descrição Resultado
Match( pangram, "THE", IgnoreCase ) Localiza todas as correspondências de "THE" na cadeia de texto que a variável pangram contém. A cadeia de caracteres contém duas correspondências, mas somente a primeira é retornada porque você está usando Match e não MatchAll. A coluna de subcorrespondências está vazia porque nenhuma subcorrespondência foi definida. {
FullMatch: "o",
SubMatches: [ ],
StartMatch: 32
}
MatchAll( pangram, "the" ) Localiza todas as correspondências de "the" na cadeia de texto que a variável pangram contém. O teste diferencia maiúsculas de minúsculas, portanto, somente a segunda instância de "the" é encontrada. A coluna de subcorrespondências está vazia porque nenhuma subcorrespondência foi definida. MatchAll para pangram.
MatchAll( pangram, "the", IgnoreCase ) Localiza todas as correspondências de "the" na cadeia de texto que a variável pangram contém. Nesse caso, o teste não diferencia maiúsculas de minúsculas, portanto, ambas as instâncias da palavra são encontradas. A coluna de subcorrespondências está vazia porque nenhuma subcorrespondência foi definida. MatchAll com IgnoreCase.
MatchAll( pangram, "\b\wo\w\b" ) Localiza todas as palavras de três letras com um "o" no meio. Observe que "brown" é excluído porque não é uma palavra de três letras e, portanto, não corresponde a "\b" (limite de palavras). MatchAll para pangram com b, wo, w e b.
Match( pangram, "\b\wo\w\b\s\*(?<between>\w.+\w)\s\*\b\wo\w\b" ) Corresponde a todos os caracteres entre "raposa" e "cão". {
between: "jumps over the lazy",
FullMatch: "fox jumps over the lazy dog",
SubMatches: [ "jumps over the lazy" ],
StartMatch: 17
}

Para ver os resultados de MatchAll em uma galeria:

  1. Em uma tela vazia, insira um controle Gallery vertical em branco.

  2. Defina a propriedade Items da galeria como MatchAll( pangram, "\w+" ) ou MatchAll( pangram, MultipleLetters ).

    Galeria de itens.

  3. Selecione "Adicionar um item da guia Inserir" no meio do controle da galeria para selecionar o modelo da galeria.

  4. Adicione um controle Label ao modelo da galeria.

  5. Defina a propriedade Text do rótulo como ThisItem.FullMatch.

    A galeria é preenchida com cada palavra em nosso texto de exemplo. Redimensione o modelo da galeria e o controle de rótulo para ver todas as palavras em uma tela.

    Propriedade Text.