Testa se uma cadeia de caracteres de texto corresponde a um padrão.

Descrição

A função IsMatch testa se uma cadeia de caracteres de texto corresponde a um padrão que pode incluir caracteres comuns, padrões predefinidos, ou uma expressão regular.

Use IsMatch para validar o que um usuário digitou em um controle Entrada de texto. Por exemplo, você pode confirmar se o usuário inseriu um endereço de email válido antes de o 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.

Por padrão, IsMatch realiza uma correspondência que diferencia maiúsculas de minúsculas para toda a cadeia de caracteres de texto. Você pode modificar esse comportamento especificando um ou mais MatchOptions.

IsMatch retornará true se a cadeia de caracteres de texto corresponder ao padrão ou false se não corresponder.

Padrões

A chave para utilizar IsMatch está em descrever o padrão a ser correspondido. Você descreve o padrão em uma cadeia de caracteres 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, a cadeia de caracteres "Hello" corresponde ao padrão "Hello" exatamente. Nem mais, nem menos. A cadeia de caracteres "hello!" não corresponde ao padrão por causa do ponto de exclamação no final e o 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, Use \ (barra invertida) como prefixo do caractere para indicar que o caractere deve ser usar literalmente ou usar um dos padrões predefinidos. Esta tabela lista os caracteres especiais:

Caractere especial Descrição
. ponto
? ponto de interrogação
* asterisco
+ sinal de adição
( ) Parêntese
[ ] colchetes
{ } chaves
^ sinal de interpolação
$ cifrão
| barra vertical ou pipe
\ barra invertida

Por exemplo, você pode corresponder "Hello?" usando o padrão "Hello\?" 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 caracteres de texto com membros da enumeração Match:

Enumeração Match Descrição Expressão regular
Any Corresponde a qualquer caractere. .
Comma Corresponde a uma vírgula. ,
Digit Corresponde a um único dígito ("0" a "9"). \d
Email 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. \-
LeftParen Corresponde a um parêntese esquerdo “(“. \(
Letter Corresponde a uma letra. \p{L}
MultipleDigits Corresponde a um ou mais dígitos. \d+
MultipleLetters Corresponde a uma ou mais letras. \p{L}+
MultipleNonSpaces Corresponde a um ou mais caracteres que não adicionam espaço em branco (espaço, tabulação, nova linha). \S+
MultipleSpaces Corresponde a um ou mais caracteres que adicionam espaço em branco (espaço, tabulação, nova linha). \s+
NonSpace Corresponde a um único caractere que não adiciona espaço em branco. \S
OptionalDigits Corresponde a zero, um ou mais dígitos. \d
OptionalLetters 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
OptionalSpaces Corresponde a zero, um ou mais caracteres que adicionam espaço em branco. \s
Period Corresponde a um ponto ("."). \.
RightParen Corresponde a um parêntese direito “)”. \)
Space Corresponde a um caractere que adiciona o espaço em branco. \s

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 IsMatch é uma expressão regular. Os caracteres comuns e padrões predefinidos que são descritos acima ajudam a compilar expressões regulares.

Expressões regulares são muito poderosas, disponíveis em muitas linguagens de programação e usadas para uma ampla variedade de finalidades. Este artigo não descreve todos os aspectos de expressões regulares, mas uma grande quantidade de informações e tutoriais está publicada na web para ajudá-lo.

Expressões regulares têm diferentes dialetos e o PowerApps usa uma variante do dialeto do JavaScript. Para obter mais informações, consulte sintaxe de expressão regular.

Na tabela de enumeração Match acima, todas as enumerações expandem para uma expressão regular e a cadeia de caracteres de texto na coluna "Regular Expression" define essa expressão.

Opções de correspondência

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

Por padrão, IsMatch testa uma correspondência completa da cadeia de caracteres de texto completa.

Enumeração MatchOptions Descrição Impacto na expressão regular
BeginsWith O padrão deve corresponder desde o início do texto. Adiciona um ^ ao início da expressão regular.
Complete Padrão. O padrão deve corresponder a todo o texto, do início ao fim. Adiciona um ^ ao início e $ ao final da expressão regular.
Contém 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.
EndsWith O padrão deve corresponder com o final do texto. Adiciona um $ ao final da expressão regular.
IgnoreCase Trata a correspondência de letras de uma maneira que não diferencia maiúsculas de minúsculas. Por padrão, a correspondência diferencia maiúsculas de minúsculas. Não modifica a expressão regular.
Multiline Corresponde em várias linhas. Não modifica a expressão regular.

Sintaxe

IsMatch( Text, Pattern [, Options ] )

  • Texto – Obrigatório. A cadeia de caracteres de texto a ser testada.
  • Pattern – Obrigatório. O padrão para testar, como uma cadeia de caracteres de texto. Concatenar padrões predefinidos que a enumeração Match define ou fornece uma expressão regular.
  • Options – Opcional. Uma combinação de cadeia de caracteres de texto de valores de enumeração MatchOptions. Por padrão, MatchOptions.Complete é usado.

Exemplos

Caracteres comuns

Imagine que seu aplicativo contém um controle Entrada de texto 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" true
IsMatch( TextInput1.Text, "Good bye" ) Testa se a entrada do usuário corresponde, exatamente, à cadeia de caracteres "Good bye" false
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). false
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). true

Padrões predefinidos

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

Expressões regulares

Fórmula Descrição Resultado
IsMatch( "986", "\d+" ) Corresponde a um número inteiro maior que zero. true
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 é. true
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. true
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 3 caracteres numéricos seguidos por um traço e, em seguida, 2 caracteres numéricos seguidos por um traço e, em seguida, 4 caracteres numéricos. true
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( "weakpassword", "(?!^[0-9]*$)(?!^[a-zA-Z]*$)([a-zA-Z0-9]{8,10})" ) Valida uma senha forte, que deve conter 8, 9 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
IsMatch( "http://microsoft.com", "(ht|f)tp(s?):\/\/[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])*(:(0-9)*)*(\/?)([a-zA-Z0-9-.\?\,\'\/\+&%\$#_]*)?" ) Valida uma URL http, https ou ftp. true