PowerApps 中的 IsMatch 函式IsMatch function in PowerApps

測試文字字串是否符合模式。Tests whether a text string matches a pattern.

說明Description

IsMatch 函式會測試文字字串是否符合某種模式,此模式可以包含一般字元、預先定義的模式或規則運算式The IsMatch function tests whether a text string matches a pattern that can comprise ordinary characters, predefined patterns, or a regular expression.

使用 IsMatch 可驗證使用者在文字輸入控制項中輸入的內容。Use IsMatch to validate what a user has typed in a Text input control. 例如,您可以先確認使用者所輸入的電子郵件地址是否有效,再將結果儲存至資料來源。For example, you can confirm whether the user has entered a valid email address before the result is saved to your data source. 如果輸入的內容不符合您的準則,則新增其他控制項來提示使用者更正其輸入內容。If the entry doesn't match your criteria, add other controls that prompt the user to correct the entry.

根據預設,IsMatch 會針對整個文字字串執行區分大小寫的比對。By default, IsMatch performs a case-sensitive match for the entire text string. 您可以藉由指定一或多個 MatchOptions 來修改此行為。You can modify this behavior by specifying one or more MatchOptions.

IsMatch 會在文字字串符合模式時傳回 true,若不符合則傳回 falseIsMatch returns true if the text string matches the pattern or false if it doesn't.

模式Patterns

IsMatch 的使用關鍵在於描述要比對的模式。The key to using IsMatch is in describing the pattern to match. 您可以透過下列項目的組合來描述文字字串的模式︰You describe the pattern in a text string as a combination of:

  • 一般字元,例如 "abc""123"Ordinary characters, such as "abc" or "123".
  • 預先定義的模式,例如 LetterMultipleDigitsEmail Predefined patterns, such as Letter, MultipleDigits, or Email. (Match 列舉會定義這些模式)。(The Match enum defines these patterns.)
  • 規則運算式程式碼,例如 "\d+\s+\d+""[a-z]+"Regular expressions codes, such as "\d+\s+\d+" or "[a-z]+".

請使用字串串連運算子 & 來結合這些元素。Combine these elements by using the string concatenation operator &. 例如,"abc" & Digit & "\s+" 便是有效的模式,它會比對字元 "a"、"b" 和 "c",接著比對數字 0 到 9,最後比對至少一個空白字元。For example, "abc" & Digit & "\s+" is a valid pattern that matches the characters "a", "b", and "c", followed by a digit from 0 to 9, followed by at least one whitespace character.

一般字元Ordinary characters

最簡單的模式是要完全符合的一般字元序列。The simplest pattern is a sequence of ordinary characters to be matched exactly.

例如,字串 "Hello" 便完全符合模式 "Hello"For example, the string "Hello" matches the pattern "Hello" exactly. 不多也不少。No more and no less. 字串 "hello!" The string "hello!" 則不符合該模式,因為該字串尾端有驚嘆號,而且字母 "h" 的大小寫錯誤doesn't match the pattern because of the exclamation point on the end and the case is wrong for the letter "h". (請參閱 MatchOptions 來了解此行為的修改方式)。(See MatchOptions for ways to modify this behavior.)

在模式語言中,某些字元已保留供特殊目的使用。In the pattern language, certain characters are reserved for special purposes. 若要使用這些字元,請在字元前面加上 \ (反斜線) 以指出其應該純粹當作字元,或使用其中一種預先定義的模式。To use these characters, either prefix the character with a \ (backslash) to indicate that the character should be taken literally or use one of the predefined patterns. 下表列出這些特殊字元︰This table lists the special characters:

特殊字元Special character 說明Description
.. 點或句號dot or period
?? 問號question mark
** 星號asterisk
+ 加號plus
( )( ) 括號parenthesis
[ ][ ] 方括號square brackets
{ }{ } 大括號curly braces
^ 插入號caret
$ 貨幣符號dollar sign
|| 分隔號或直立線符號vertical bar or pipe
\ 反斜線backslash

例如,您可以For example, you can match "Hello?" 使用問號前有反斜線的模式 "Hello\?" ()by using the pattern "Hello\?" 來比對 "Hello"。with a backslash before the question mark.

預先定義的模式Predefined patterns

預先定義的模式提供簡單的方法來比對一組字元或多個字元的序列。Predefined patterns provide a simple way to match one of a set of characters, or a sequence of multiple characters. 使用字串串連運算子 & 可結合您自己的文字字串與 Match 列舉的成員:Use the string concatenation operator & to combine your own text strings with members of the Match enum:

Match 列舉Match Enum 說明Description 規則運算式Regular Expression
AnyAny 比對任何字元。Matches any character. ..
CommaComma 比對逗號。Matches a comma. ,,
DigitDigit 比對單一數字 ("0" 到 "9")。Matches a single digit ("0" through "9"). \d\d
EmailEmail 比對包含 "at" 符號 ("@") 的電子郵件地址以及包含點的網域名稱 (".")Matches an email address that contains an "at" symbol ("@") and a domain name that contains a dot (".") .+@.+\.[^\.]{2,}.+@.+\.[^\.]{2,}
HyphenHyphen 比對連字號。Matches a hyphen. \-
LeftParenLeftParen 比對左括號 "("。Matches a left parenthesis "(". \(\(
LetterLetter 比對字母。Matches a letter. \p{L}\p{L}
MultipleDigitsMultipleDigits 比對一或多個數字。Matches one or more digitis. \d+\d+
MultipleLettersMultipleLetters 比對一或多個字母。Matches one or more letters. \p{L}+\p{L}+
MultipleNonSpacesMultipleNonSpaces 比對一或多個不會新增空白字元 (空格、定位字元、新行字元) 的字元。Matches one or more characters that don't add whitespace (space, tab, newline). \S+\S+
MultipleSpacesMultipleSpaces 比對一或多個會新增空白字元 (空格、定位字元、新行字元) 的字元。Matches one or more characters that add whitespace (space, tab, newline). \s+\s+
NonSpaceNonSpace 比對不會新增空白字元的單一字元。Matches a single character that doesn't add whitespace. \S\S
OptionalDigitsOptionalDigits 比對零個、一個或多個數字。Matches zero, one, or more digits. \d\d
OptionalLettersOptionalLetters 比對零個、一個或多個字母。Matches zero, one, or more letters. \p{L}\p{L}
OptionalNonSpacesOptionalNonSpaces 比對零個、一個或多個不會新增空白字元的字元。Matches zero, one, or more characters that don't add whitespace. \S\S
OptionalSpacesOptionalSpaces 比對零個、一個或多個會新增空白字元的字元。Matches zero, one, or more characters that add whitespace. \s\s
PeriodPeriod 比對句號或點 (".")。Matches a period or dot ("."). \.\.
RightParenRightParen 比對右括號 ")"。Matches a right parenthesis ")". \)\)
SpaceSpace 比對會新增空白字元的字元。Matches a character that adds whitespace. \s\s

例如,模式 "A" & MultipleDigits 會比對字母 "A" 後面接著一或多個數字。For example, the pattern "A" & MultipleDigits will match the letter "A" followed by one or more digits.

規則運算式Regular expressions

IsMatch 所使用的模式是規則運算式The pattern used by IsMatch is a regular expression. 上面所說明的一般字元和預先定義的模式有助於建置規則運算式。The ordinary characters and predefined patterns that are described above help build regular expressions.

規則運算式非常強大,適用於許多程式設計語言,並可用於各種用途。Regular expressions are very powerful, available in many programming languages, and used for a wide variety of purposes. 本文無法說明規則運算式的所有層面,但我們在網路上發佈了大量的資訊和教學課程來協助您。This article can't describe all aspects of regular expressions, but a wealth of information and tutorials are published on the web to aid you.

規則運算式有不同方言,PowerApps 使用其中一種變化的 JavaScript 方言。Regular expressions have different dialects, and PowerApps uses a variant of the JavaScript dialect. 如需詳細資訊,請參閱規則運算式語法For more information, see regular expression syntax.

在上面的 Match 列舉資料表中,每個列舉都會展開成規則運算式,而且「規則運算式」資料行中的文字字串會定義該運算式。In the Match enum table above, each enum expands into a regular expression, and the text string in the "Regular Expression" column defines that expression.

比對選項Match options

您可以藉由指定一或多個選項來修改 IsMatch 的行為,若要結合這些選項,您可以使用字串串連運算子 (&)。You can modify the behavior of IsMatch by specifying one or more options, which you can combine by using the string concatenation operator (&).

根據預設,IsMatch 會測試整個文字字串的完整比對。By default, IsMatch tests for a complete match of the entire text string.

MatchOptions 列舉MatchOptions Enum 說明Description 對規則運算式的影響Impact on regular expression
BeginsWithBeginsWith 模式必須從文字開頭來比對。The pattern must match from the beginning of the text. 在規則運算式的開頭新增 ^Adds a ^ to the start of the regular expression.
CompleteComplete 預設值。Default. 模式必須從頭到尾比對整個文字。The pattern must match the entire text, from beginning to end. 在規則運算式的開頭新增 ^,並在結尾新增 $Adds a ^ to the start and $ to the end of the regular expression.
ContainsContains 模式必須出現在文字中的某處,但開頭或結尾不必是此模式。The pattern must appear somewhere in the text but doesn't need to begin or end it. 不會修改規則運算式。Doesn't modify the regular expression.
EndsWithEndsWith 模式必須比對文字的結尾。The pattern must match the end of the text. 在規則運算式的結尾新增 $Adds a $ to the end of the regular expression.
IgnoreCaseIgnoreCase 會以不區分大小寫的方式處理字母的比對。Treats the matching of letters in a case-insensitive manner. 根據預設,比對會區分大小寫。By default, matching is case sensitive. 不會修改規則運算式。Doesn't modify the regular expression.
MultilineMultiline 跨多行進行比對。Matches across multiple lines. 不會修改規則運算式。Doesn't modify the regular expression.

語法Syntax

IsMatch( Text, Pattern [, Options ] )IsMatch( Text, Pattern [, Options ] )

  • Text – 必要項目。Text – Required. 要測試的文字字串。The text string to test.
  • Pattern – 必要項目。Pattern – Required. 要當成文字字串來測試的模式。The pattern to test, as a text string. 串連 Match 列舉所定義的預先定義模式,或提供規則運算式。Concatenate predefined patterns that the Match enum defines or provide a regular expression.
  • Options – 選擇性項目。Options – Optional. MatchOptions 列舉值的文字字串組合。A text string combination of MatchOptions enum values. 系統預設會使用 MatchOptions.CompleteBy default, MatchOptions.Complete is used.

範例Examples

一般字元Ordinary characters

假設您的應用程式包含名為 TextInput1文字輸入控制項。Imagine that your app contains a Text input control named TextInput1. 使用者會在這個控制項中輸入值以便儲存到資料庫。The user enters values into this control to be stored in a database.

使用者在 TextInput1 中輸入 Hello worldThe user types Hello world into TextInput1.

公式Formula 說明Description 結果Result
IsMatch( TextInput1.Text, "Hello world" )IsMatch( TextInput1.Text, "Hello world" ) 測試使用者的輸入是否完全符合字串 "Hello world"Tests whether the user's input matches, exactly, the string "Hello world" truetrue
IsMatch( TextInput1.Text, "Good bye" )IsMatch( TextInput1.Text, "Good bye" ) 測試使用者的輸入是否完全符合字串 "Good bye"Tests whether the user's input matches, exactly, the string "Good bye" falsefalse
IsMatch( TextInput1.Text, "hello", Contains )IsMatch( TextInput1.Text, "hello", Contains ) 測試使用者的輸入是否包含 "hello" (區分大小寫) 這個單字。Tests whether the user's input contains the word "hello" (case sensitive). falsefalse
IsMatch( TextInput1.Text, "hello", Contains & IgnoreCase )IsMatch( TextInput1.Text, "hello", Contains & IgnoreCase ) 測試使用者的輸入是否包含 "hello" (不區分大小寫) 這個單字。Tests whether the user's input contains the word "hello" (case insensitive). truetrue

預先定義的模式Predefined patterns

公式Formula 說明Description 結果Result
IsMatch( "123-45-7890", Digit & Digit & Digit & Hyphen & Digit & Digit & Hyphen & Digit & Digit & Digit & Digit & Digit )IsMatch( "123-45-7890", Digit & Digit & Digit & Hyphen & Digit & Digit & Hyphen & Digit & Digit & Digit & Digit & Digit ) 比對美國的社會安全號碼Matches a United States Social Security Number truetrue
IsMatch( "joan@contoso.com", Email )IsMatch( "joan@contoso.com", Email ) 比對電子郵件地址Matches an email address truetrue
IsMatch( "123.456", MultipleDigits & Period & OptionalDigits )IsMatch( "123.456", MultipleDigits & Period & OptionalDigits ) 比對一連串數字、句號,然後零個或多個數字。Matches a sequence of digits, a period, and then zero or more digits. truetrue
IsMatch( "123", MultipleDigits & Period & OptionalDigits )IsMatch( "123", MultipleDigits & Period & OptionalDigits ) 比對一連串數字、句號,然後零個或多個數字。Matches a sequence of digits, a period, and then zero or more digits. 文字中沒有句號,因此這個模式未比對成功。A period doesn't appear in the text, so this pattern isn't matched. falsefalse

規則運算式Regular expressions

公式Formula 說明Description 結果Result
IsMatch( "986", "\d+" )IsMatch( "986", "\d+" ) 比對大於零的整數。Matches a an integer greater than zero. truetrue
IsMatch( "1.02", "\d+(.\d\d)?" )IsMatch( "1.02", "\d+(.\d\d)?" ) 比對正數貨幣金額。Matches a positive currency amount. 如果輸入中包含小數點,輸入的值還必須在小數點後面包含 2 個數字字元。If the input contains a decimal point, the input must also contain 2 numeric characters after the decimal point. 例如,3.00 有效,但 3.1 無效。For example, 3.00 is valid, but 3.1 isn't. truetrue
IsMatch( "-4.95", "(-)?\d+(.\d\d)?" )IsMatch( "-4.95", "(-)?\d+(.\d\d)?" ) 比對正數或負數的貨幣金額。Matches a positive or negative currency amount. 如果輸入中包含小數點,輸入的值還必須在小數點後面包含 2 個數字字元。If the input contains a decimal point, the input must also contain 2 numeric characters after the decimal point. truetrue
IsMatch( "111-11-1111", "\d{3}-\d{2}-\d{4}" )IsMatch( "111-11-1111", "\d{3}-\d{2}-\d{4}" ) 比對美國的社會安全號碼。Matches a United States Social Security number. 驗證所提供輸入欄位的格式、類型和長度。Validates the format, type, and length of the supplied input field. 要比對的字串必須包含 3 個數字字元,後接一個連字號,再來是 2 個數字字元,後接一個連字號,然後是 4 個數字字元。The string to match must consist of 3 numeric characters followed by a dash, then 2 numeric characters followed by a dash, and then 4 numeric characters. truetrue
IsMatch( "111-111-111", "\d{3}-\d{2}-\d{4}" )IsMatch( "111-111-111", "\d{3}-\d{2}-\d{4}" ) 和前一個範例相同,但輸入中的其中一個連字號位置不對。Same as the previous example, but one of the hyphens is out of place in the input. falsefalse
IsMatch( "weakpassword", "(?!^[0-9]*$)(?!^[a-zA-Z]*$)([a-zA-Z0-9]{8,10})" )IsMatch( "weakpassword", "(?!^[0-9]*$)(?!^[a-zA-Z]*$)([a-zA-Z0-9]{8,10})" ) 驗證強式密碼,此密碼必須包含 8 個、9 個或 10 個字元,此外要有至少一個數字和至少一個字母字元。Validates a strong password, which must contain 8, 9, or 10 characters, in addition to at least one digit and at least one alphabetic character. 字串中不能包含特殊字元。The string must not contain special characters. falsefalse
IsMatch( "http://microsoft.com", "(ht|f)tp(s?)://[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])*(:(0-9)*)*(/?)([a-zA-Z0-9-.?,'/\+&%$#_]*)?" )IsMatch( "http://microsoft.com", "(ht|f)tp(s?)://[0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])*(:(0-9)*)*(/?)([a-zA-Z0-9-.?,'/\+&%$#_]*)?" ) 驗證 http、https 或 ftp URL。Validates an http, https, or ftp URL. truetrue