Funções IsMatch, Match e MatchAll no Power Apps

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

Descrição

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

Utilize a função IsMatch para validar que um utilizador escreveu num controlo de Entrada de texto. Por exemplo, pode confirmar se o utilizador introduziu um endereço de e-mail válido antes de o resultado ser guardado na sua origem de dados. Se a entrada não corresponder aos critérios, adicione outros controlos que pedem ao utilizador para corrigir a entrada.

Utilize Match para extrair a primeira cadeia de texto que faz a correspondência a um padrão e MatchAll para extrair todas as cadeias de texto correspondentes. Também pode extrair subcorrespondências para analisar cadeias de caracteres complexas.

Match devolve um registo de informação para a primeira correspondência encontrada e MatchAll devolve uma tabela de registos para cada correspondência encontrada. O registo ou registos contêm:

Coluna Tipo Descrição
named sub‑match or sub‑matches Texto Cada subcorrespondência nomeada terá uma coluna própria. Crie uma subcorrespondência nomeada através de (?<name>...) na expressão regular. Se uma subcorrespondência nomeada tiver o mesmo nome que uma das colunas predefinidas (abaixo), a subcorrespondência assume a precedência e é gerado um aviso. Para evitar este aviso, mude o nome da subcorrespondência.
FullMatch Texto Toda a cadeia de texto que foi correspondida.
StartMatch Número A posição inicial da correspondência na cadeia de texto de entrada. O primeiro caráter da cadeia devolve 1.
Subcorrespondências Tabela de coluna única de Texto (Value de coluna) A tabela das subcorrespondências nomeadas e não nomeadas pela ordem em que são apresentadas na expressão regular. Normalmente, as subcorrespondências nomeadas são mais fáceis de trabalhar e são recomendadas. Utilize a função ForAll ou as funções Last( FirstN( ... ) ) para trabalhar com uma subcorrespondência individual. Se não forem definidas subcorrespondências na expressão regular, esta tabela estará presente, mas vazia.

Estas funções suportam MatchOptions. Por predefinição:

  • Estas funções fazem uma correspondência sensível a maiúsculas e minúsculas. Utilize IgnoreCase para efetuar correspondências sensíveis a maiúsculas e minúsculas.
  • IsMatch corresponde à cadeia de texto completa (Complete MatchOption), enquanto Match e MatchAll procuram uma correspondência em qualquer lugar na cadeia de texto (MatchOption Contains). Utilize Complete, Contains, BeginsWith ou EndsWith, conforme seja adequado ao seu cenário.

IsMatch devolve true se a cadeia de texto corresponder ao padrão ou false se não corresponder. Match devolve blank se não for encontrada nenhuma correspondência que possa ser testada com a função IsBlank. MatchAll devolve uma tabela vazia se não for encontrada nenhuma correspondência que possa ser testada com a função IsEmpty.

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

Padrões

A chave para utilizar estas funções reside em descrever o padrão para fazer a correspondência. Descreva o padrão numa cadeia de texto como uma combinação de:

  • Carateres comuns, como "abc" ou "123".
  • Padrões predefinidos, como Letra, MultipleDigits ou E-mail. (A enumeração Correspondência define estes padrões.)
  • Códigos de expressão regular, como "\d+\s+\d+" ou "[a-z]+".

Combine estes elementos através do operador de concatenação de cadeia &. Por exemplo, "abc" e dígito e "\s+" é um padrão válido que corresponde aos carateres "a", "b", e "c", seguido de um dígito de 0 a 9, seguido de pelo menos um espaço em branco.

Carateres comuns

O padrão mais simples é uma sequência de carateres comuns para corresponder exatamente.

Por exemplo, quando utilizado com a função IsMatch, a cadeia "Hello" corresponde exatamente ao padrão "Hello". Nem mais, nem menos. A cadeia "hello!" não corresponde ao padrão devido ao ponto de exclamação no fim e porque as maiúsculas e minúsculas estão incorretas para a letra "h". (Consulte MatchOptions para conhecer formas de alterar este comportamento.)

Na linguagem padrão, determinados carateres estão reservados para fins especiais. Para utilizar estes carateres, adicione um prefixo de caráter com uma \ (barra invertida) para indicar que o caráter deve ser executado literalmente ou utilize um dos padrões predefinidos, descritos mais à frente neste tópico. Esta tabela lista os carateres especiais:

Caráter especial Descrição
. ponto ou período
? ponto de interrogação
***** asterisco
+ plus
( ) parênteses
[ ] parênteses retos
{ } chavetas
^ acento circunflexo
$ cifrão
| barra vertical ou pipe
\ barra invertida

Por exemplo, pode corresponder a "Hello?" ao utilizar o padrão "Hello\?" com uma barra invertida antes do ponto de interrogação.

Padrões predefinidos

Os padrões predefinidos oferecem uma forma simples de corresponder a um conjunto de carateres, ou uma sequência de vários carateres. Utilize o operador de concatenação de cadeia & para combinar as suas próprias cadeias de texto com os membros da enumeração Correspondência:

Enumeração de correspondência Descrição Expressão regular
Qualquer Corresponde a qualquer caráter. .
Vírgula Corresponde a uma vírgula. ,
Digit Corresponde a um único dígito ("0" a "9"). \d
Correio Eletrónico Corresponde a um endereço de e-mail que contém um símbolo de "arroba" ("@") e um nome de domínio que contém um ponto (".") .+\@.+\\.[^\\.]{2,}
Hyphen Corresponde a um hífen. \-
LeftParen Corresponde a um parêntese esquerdo "(". \(
Carta 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 carateres que não adicionam espaços em branco (não espaço, separador ou nova linha). \S+
MultipleSpaces Corresponde a um ou mais carateres que adicionam espaços em branco (espaço, separador ou nova linha). \s+
NonSpace Corresponde a um único caráter 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 carateres que não adicionam espaços em branco. \S*
OptionalSpaces Corresponde a zero, um ou mais carateres que adicionam espaços em branco. \s*
Ponto Corresponde a um período ou um ponto ("."). \.
RightParen Corresponde a um parêntese direito ")". \)
Espaço Corresponde a um caráter que adiciona espaço em branco. \s
Tabulação Corresponde um caráter de separador. \t

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

Expressões regulares

O padrão utilizado por estas funções é uma expressão regular. Os carateres comuns e padrões predefinidos que são descritos anteriormente neste tópico ajudam a criar expressões regulares.

As expressões regulares são muito poderosas, estão disponíveis em muitas linguagens de programação e são utilizadas para uma grande variedade de objetivos. Muitas vezes, também podem ter a aparência de uma sequência aleatória de sinais de pontuação. Este artigo não descreve todos os aspetos das expressões regulares, mas estão disponíveis na Web uma série de informações, tutoriais e ferramentas.

As expressões regulares estão em diferentes dialetos e o Power Apps utiliza uma variante do dialeto JavaScript. Consulte sintaxe de expressões regulares para uma introdução à sintaxe. São suportadas subcorrespondências nomeadas (por vezes denominadas grupos de captura nomeados):

  • Subcorrespondências nomeadas: (?<name> ...)
  • Referências posteriores nomeadas: \k<name>

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

Opções de correspondência

Pode modificar o comportamento destas funções ao especificar uma ou mais opções que pode combinar ao utilizar o operador de concatenação de cadeia (&).

Enumeração MatchOptions Descrição Impacto numa expressão regular
BeginsWith O padrão tem de corresponder desde o início do texto. Adiciona um ^ ao início da expressão regular.
Concluída Predefinição para IsMatch. O padrão tem de corresponder a todo o texto da cadeia, desde o início ao fim. Adiciona um ^ no início e $ no fim da expressão regular.
Contém Predefinição para Match e MatchAll. O padrão tem de aparecer algures no texto, mas não tem de começá-lo ou terminá-lo. Não altera a expressão regular.
EndsWith O padrão tem de corresponder ao final da cadeia de texto. Adiciona um $ ao início da expressão regular.
IgnoreCase Trata as letras maiúsculas e minúsculas como idênticas. Por predefinição, a correspondência é sensível a maiúsculas e minúsculas. Não altera a expressão regular. Esta opção é o equivalente do modificador "i" padrão para expressões regulares.
Multiline Correspondências entre várias linhas. Não altera a expressão regular. Esta opção é o equivalente do modificador "m" padrão para expressões regulares.

A utilização de MatchAll é equivalente a utilizar o modificador "g" padrão para expressões regulares.

Sintaxe

IsMatch( Text, Pattern [, Options ] )

  • Text – Obrigatório. A cadeia de texto a testar.
  • Pattern – Obrigatório. O padrão a testar como uma cadeia de texto. Concatene padrões predefinidos que a enumeração Match define ou indique uma expressão regular. Pattern tem de ser uma fórmula constante sem quaisquer variáveis, origens de dados ou outras referências dinâmicas que são alteradas à medida que a aplicação é executada.
  • Options – Opcional. Uma combinação de cadeia de texto de valores de enumeração MatchOptions. Por predefinição, é utilizado MatchOptions.Complete.

Match( Text, Pattern [, Options ] )

  • Text – Obrigatório. A cadeia de texto a corresponder.
  • Pattern – Obrigatório. O padrão a corresponder como uma cadeia de texto. Concatene padrões predefinidos que a enumeração Match define ou indique uma expressão regular. Pattern tem de ser uma fórmula constante sem quaisquer variáveis, origens de dados ou outras referências dinâmicas que são alteradas à medida que a aplicação é executada.
  • Options – Opcional. Uma combinação de cadeia de texto de valores de enumeração MatchOptions. Por predefinição, é utilizado MatchOptions.Contains.

MatchAll( Text, Pattern [, Options ] )

  • Text – Obrigatório. A cadeia de texto a corresponder.
  • Pattern – Obrigatório. O padrão a corresponder como uma cadeia de texto. Concatene padrões predefinidos que a enumeração Match define ou indique uma expressão regular. Pattern tem de ser uma fórmula constante sem quaisquer variáveis, origens de dados ou outras referências dinâmicas que são alteradas à medida que a aplicação é executada.
  • Options – Opcional. Uma combinação de cadeia de texto de valores de enumeração MatchOptions. Por predefinição, é utilizado MatchOptions.Contains.

Exemplos de IsMatch

Carateres comuns

Imagine que a sua aplicação contém um controlo Text input com o nome TextInput1. O utilizador introduz os valores neste controlo a serem armazenados numa base de dados.

O utilizador escreve Hello world em TextInput1.

Fórmula Descrição Resultado
IsMatch( TextInput1.Text, "Hello world" ) Testa se a entrada do utilizador corresponde, exatamente, à cadeia "Hello world". true
IsMatch( TextInput1.Text, "Good bye" ) Testa se a entrada do utilizador corresponde, exatamente, à cadeia "Good bye". false
IsMatch( TextInput1.Text, "hello", Contains ) Testa se a entrada do utilizador contém a palavra "hello" (sensível a maiúsculas e minúsculas). false
IsMatch( TextInput1.Text, "hello", Contains & IgnoreCase ) Testa se a entrada do utilizador contém a palavra "hello" (não é sensível a 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 ) Corresponde a um Número de Segurança Social dos Estados Unidos true
IsMatch( "joan@contoso.com", Email ) Corresponde a um endereço de e-mail 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 a corresponder, pelo que este 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 uma quantidade monetária positiva. Se a entrada tiver uma vírgula decimal, a entrada também tem de conter dois carateres numéricos após a vírgula decimal. Por exemplo, 3,00 é válido, mas 3,1 não é. true
IsMatch( "-4.95", "(-)?\d+(\.\d\d)?" ) Corresponde a uma quantidade monetária positiva ou negativa. Se a entrada tiver uma vírgula decimal, a entrada também tem de conter dois carateres numéricos após a vírgula decimal. true
IsMatch( "111-11-1111", "\d{3}-\d{2}-\d{4}" ) Corresponde a um Número de Segurança Social dos Estados Unidos Valida o formato, o tipo e o comprimento do campo de entrada apresentado. A cadeia a corresponder deve consistir em três carateres numéricos seguidos por um traço e, em seguida, dois carateres seguidos por um traço e, em seguida, quatro carateres. true
IsMatch( "111-111-111", "\d{3}-\d{2}-\d{4}" ) O mesmo que o exemplo anterior, mas um dos hífenes está fora do local na entrada. false
IsMatch( "AStrongPasswordNot", "(?!^[0-9]\*$)(?!^[a-zA-Z]\*$)([a-zA-Z0-9]{8,10})" ) Valida uma palavra-passe segura, que tem de conter oito, nove ou 10 carateres, além de, pelo menos, um dígito e um caráter alfabético. A cadeia não pode conter carateres especiais. false

Exemplos de Match e MatchAll

Fórmula Descrição Resultado
Match( "Bob Jones <bob.jones@contoso.com>", "<(?<email>" & Match.Email & ")>" Extrai apenas a parte do e-mail das informações de contacto. {
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 do e-mail das informações de contacto. Não foi encontrado nenhum endereço legal (não existe sinal @), pelo que a função devolve blank. blank
Match( Language(), "(<language>\w{2})(?:-(?<script>\w{4}))?(?:-(?<region>\w{2}))?" ) Extrai a linguagem, o script e as partes da região da tag da linguagem que a função Language devolve. Estes resultados refletem os 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 numa cadeia de texto; utilize a função Value para convertê-la num número antes de serem efetuadas operações matemáticas nela. {
hours: "2",
minutes: "1",
seconds: "39",
FullMatch: "PT2H1M39S",
SubMatches: [ "2", "1", "39" ],
StartMatch: 1
}

Vamos analisar este último exemplo. Se pretender converter esta cadeia de caracteres num valor de data/hora com a função Time, tem de transmitir individualmente as subcorrespondências nomeadas. Para tal, pode utilizar a função With que opera no registo que Match devolve:

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

Para estes exemplos, adicione um controlo Button, defina a respetiva propriedade OnSelect nesta fórmula e selecione o botão:

Set( pangram, "The quick brown fox jumps over the lazy dog." )
Fórmula Descrição Resultado
Match( pangram, "THE", IgnoreCase ) Localize 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 apenas a primeira é devolvida porque está a utilizar Match e não MatchAll. A coluna SubMatches está vazia porque não foram definidas subcorrespondências. {
FullMatch: "The",
SubMatches: [ ],
StartMatch: 32
}
MatchAll( pangram, "the" ) Localize todas as correspondências de "the" na cadeia de texto que a variável pangram contém. O teste é sensível a maiúsculas e minúsculas, pelo que só é encontrada a segunda instância de "the". A coluna SubMatches está vazia porque não foram definidas subcorrespondências.
MatchAll( pangram, "the", IgnoreCase ) Localize todas as correspondências de "the" na cadeia de texto que a variável pangram contém. Neste caso, o teste é sensível a maiúsculas e minúsculas, pelo que ambas as instâncias da palavra são encontradas. A coluna SubMatches está vazia porque não foram definidas subcorrespondências.
MatchAll( pangram, "\b\wo\w\b" ) Localiza todas as palavras de três letras com um "o" no meio. Tenha em atenção que "brown" está excluído porque não é uma palavra de três letras, pelo que falha a correspondência com "\b" (limite da palavra).
Match( pangram, "\b\wo\w\b\s\*(?<between>\w.+\w)\s\*\b\wo\w\b" ) Corresponde a todos os caracteres entre "fox" e "dog". {
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 numa galeria:

  1. Num ecrã vazio, introduza um controlo Gallery vertical em branco.

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

  3. Selecione "Adicionar um item do separador Inserir" no meio do controlo de galeria para selecionar o modelo da galeria.

  4. Adicione um controlo Label ao modelo da galeria.

  5. Defina a propriedade Text da etiqueta como ThisItem.FullMatch.

    A galeria é preenchida com cada palavra no nosso texto de exemplo. Redimensione o modelo da galeria e o controlo da etiqueta para ver todas as palavras num único ecrã.

Nota

Pode indicar-nos as suas preferências no que se refere ao idioma da documentação? Responda a um breve inquérito. (tenha em atenção que o inquérito está em inglês)

O inquérito irá demorar cerca de sete minutos. Não são recolhidos dados pessoais (declaração de privacidade).