Funções IsMatch, Match e MatchAll
Aplica-se a:
Aplicações de tela Aplicações condicionadas por modelo CLI do Power Platform
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 Text input. 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:
| Column | Type | Description |
|---|---|---|
| subcorrespondência ou subcorrespondências nomeadas | 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 MatchOptions.IgnoreCase para efetuar correspondências não 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 "olá!" 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 "o". (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 |
| + | adição |
| ( ) | parênteses |
| [ ] | parênteses retos |
| { } | chavetas |
| ^ | acento circunflexo |
| $ | cifrão |
| | | barra vertical ou pipe |
| \ | barra invertida |
Por exemplo, pode corresponder a "Olá?" utilizando o padrão "Olá\?" 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 |
|---|---|---|
| Any | Corresponde a qualquer caráter. | . |
| Comma | Corresponde a uma vírgula. | , |
| Digit | Corresponde a um único dígito ("0" a "9"). | \d |
| 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 "(". | \( |
| 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 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* |
| Period | Corresponde a um período ou um ponto ("."). | \. |
| RightParen | Corresponde a um parêntese direito ")". | \) |
| Space | Corresponde a um caráter que adiciona espaço em branco. | \s |
| Tab | 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 | Description | Impacto numa expressão regular |
|---|---|---|
| MatchOptions.BeginsWith | O padrão tem de corresponder desde o início do texto. | Adiciona um ^ ao início da expressão regular. |
| MatchOptions.Complete | 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. |
| MatchOptions.Contains | 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. |
| MatchOptions.EndsWith | O padrão tem de corresponder ao final da cadeia de texto. | Adiciona um $ ao início da expressão regular. |
| MatchOptions.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. |
| MatchOptions.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 ] )
- Texto – 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 ] )
- Texto – 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 ] )
- Texto – 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. | { e-mail: "bob.jones@contoso.com", FullMatch: "<bob.jones@contoso.com>", Subcorrespondências: [ "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. | em branco |
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", Subcorrespondências: [ ], 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". | { entre: "salta por cima do", FullMatch: "raposa salta por cima do cão preguiçoso", SubMatches: [ "jumps over the lazy" ], StartMatch: 17 } |
Para ver os resultados de MatchAll numa galeria:
Num ecrã vazio, introduza um controlo Gallery vertical em branco.
Defina a propriedade Items da galeria como MatchAll( pangram, "\w+" ) ou MatchAll( pangram, MultipleLetters ).
Selecione "Adicionar um item do separador Inserir" no meio do controlo gallery para selecionar o modelo da galeria.
Adicione um controlo Label ao modelo da galeria.
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ã.
