IsMatch、Match 和 MatchAll 函式
適用於：
畫布應用 模型驅動應用 Power Pages Power Platform CLI
根據模式測試是否符合或抽取文字字串的部分。
描述
IsMatch 函式測試文字字串是否符合某種可包含一般字元、預先定義型態或 規則運算式 的型態。 Match 和 MatchAll 函式會傳回符合的項目，包括子相配項目。
使用 IsMatch 驗證使用者在 Text input 控制項中輸入的內容。 例如您可以先確認使用者輸入的電子郵件地址是否有效，再將結果儲存至資料來源。 如果輸入的內容不符合您的準則，則新增其他控制項來提示使用者更正其輸入內容。
使用 Match 提取符合型態和 MatchAll 的第一個文字字串，以提取符合的所有文字字串。 您也可以提取子相配剖析複雜的字串。
Match 返回找到的第一個匹配項的信息記錄， 而 MatchAll 返回找到的每個匹配項的記錄表。 記錄或各記錄包含如下：
| 資料行 | 類型 | 名描述 |
|---|---|---|
| 命名的 Sub-Match 或 Sub-Matches | 文字 | 每個命名的子相配都將有自己的欄位。 藉由在正則運算式中使用 (?<name>...) 建立具名的子相配。 如果具名的子相配與其中一個預先定義的欄位相同 (如下)，則子相配會優先並產生警告。 若要避免此警告，請重新命名子相配。 |
| FullMatch 全面匹配 | 文字 | 所有符合的文字字串。 |
| StartMatch 開始 | 號碼 | 輸入文字字串中的相配起始位置。 字串的第一個字元傳回 1。 |
| 子匹配項 | 文字的單欄資料表 (欄位 值) | 以其在正則運算式順序相配的具名和未具名子相配資料表。 一般而言，具名的子相配比較容易搭配，也鼓勵您使用。 使用 ForAll 函式或 Last( FirstN( ... ) ) 函式處理個別子相配。 若正則運算式中未定義子相配，此資料表將會存在，但為空白的。 |
這些函式支援 MatchOptions。 預設情況：
- 這些函數執行區分大小寫的相配。 使用 MatchOptions.IgnoreCase 執行不區分大小寫的比對。
- IsMatch 匹配整個文本字串 (Complete MatchOption)，而 Match 和 MatchAll 在文本字串中的任意位置搜索匹配項 (Contains MatchOption)。 依適當情況針對您的案例使用 Complete、Contains、BeginsWith、或 EndsWith。
如果文本字串與模式匹配，則 IsMatch 返回 true ， 如果不匹配，則返回 false 。 如果未找到可以使用 IsBlank 函數測試 的匹配項，則 Match 返回 空白 。 如果未找到可以使用 IsEmpty 函數進行測試 的匹配項，則 MatchAll 將返回一個空表。
如果您使用 MatchAll 分割文字字串，請考慮使用 Split 函式，使用起來較簡單也較快。
型態
這些函數的使用關鍵在於描述要相配的型態。 您可以透過下列項目的組合描述文字字串的型態︰
- 一般字元如 "abc" 或 "123"。
- 預先定義的型態，例如 Letter、MultipleDigits 或 Email。 (Match 列舉定義這些型態。)
- 規則運算式程式碼，例如 "\d+\s+\d+" 或 "[a-z]+"。
藉由使用字串串連運算子 & 結合這些元素。 例如，"abc" & Digit & "\s+" 是有效符合字元 "a"、"b" 和 "c"，接著符合數字 0 到 9，最後符合至少一個空白字元的型態。
一般字元
最簡單的型態是完全符合的一般字元順序。
例如，當與 IsMatch 函式搭配使用時，字串 "Hello" 會完全符合 "Hello" 的型態。 不多也不少。 「hello!」字串不符合該型態，因為該字串結尾有驚嘆號，而且字母 "h" 的大小寫有誤。 (請參閱 MatchOptions 了解此行為的修改方式。)
在型態語言中，特定字元已保留供特殊用途。 若要使用這些字元，請在字元前面加上 \ (反斜線) 以指出應該純粹當作字元，或使用其中一種本主題稍候描述的預先定義型態。 此資料表列出特殊字元︰
| 特殊字元 | 名描述 |
|---|---|
| . | 點或句點 |
| ? | 問號 |
| * | 星號 |
| + | plus |
| ( ) | 括號 |
| [ ] | 中括號 |
| { } | 大括號 |
| ^ | caret |
| $ | 貨幣符號 |
| | | 分隔號或直立線符號 |
| \ | 反斜線 |
例如，您可以使用模式 "Hello?" (問號前面加上反斜線) 來比對 "Hello?"。
預先定義的型態
預先定義的型態提供簡單的方法來相配其中一組字元或多個字元的順序。 使用字串串連運算子 & 結合您自己的文字字串與 Match 列舉的成員：
| Match 列舉 | 描述 | 規則運算式 |
|---|---|---|
| 任何 | 相配任何字元。 | . |
| 逗點 | 相配逗號。 | , |
| 數位 | 相配單一位數 ("0" 到 "9")。 | \d |
| 電子郵件 | 相配包含 "at" 符號 ("@") 的電子郵件地址以及包含點 (".") 的網域名稱 | .+\@.+\\.[^\\.]{2,} |
| 連字型大小 | 相配連字號。 | \- |
| 左帕倫 | 相配左括號 "("。 | \( |
| 信 | 相配字母。 | \p{L} |
| 多位數 | 相配一或多位數。 | \d+ |
| 多字母 | 相配一或多個字母。 | \p{L}+ |
| MultipleNonSpaces | 相配一或多個不會新增空白字元 (非空白、定位、或新行) 的字元。 | \S+ |
| 多空間 | 相配一或多個會新增空白字元 (空格、定位、或新行) 的字元。 | \s+ |
| 非空格 | 相配不會新增空白字元的單一字元。 | \S |
| OptionalDigits | 相配零、一或多位數。 | \d* |
| 可選信件 | 相配零、一或多字母。 | \p{L}* |
| OptionalNonSpaces | 相配零、一或多個不會新增空白字元的字元。 | \S* |
| OptionalSpaces | 相配零、一或多個會新增空白字元的字元。 | \s* |
| 時期 | 相配句號或點 (".")。 | \. |
| 右帕倫 | 相配右括號 ")"。 | \) |
| 空間 | 相配會新增空白字元的字元。 | \s |
| 標籤 | 比對 Tab 字元。 | \t |
例如，型態 "A" & MultipleDigits 將相配字母 "A" 後面接著一或多位數。
規則運算式
這些函式使用的型態為 正則運算式 。 本主題稍早描述的一般字元和預先定義型態有助於組建正規運算式。
正則運算式非常強大，適用許多程式設計語言和各種用途。 它們也往往看起來像是標點符號的隨機序列。 本文並不描述正則運算式的所有層面，但我們在網路上發佈大量的資訊、教學課程和工具來協助您。
正則運算式有不同方言，Power Apps 使用其中一種變化的 JavaScript 方言。 如需語法簡介，請參閱 一般運算式語法。 支援具名的子相配 (有時稱為具名擷取群組)：
- 具名的子匹配：(?<name> ...)
- 具名的反向參照：\k<name>
在本主題稍早的 Match 列舉資料表中，每個列舉都會顯示在與其對應的正則運算式同一列。
相配選項
您可以藉由指定一或多個選項修改這些函式的行為，為了結合這些選項，您可以使用字串串連運算子 (&)。
| MatchOptions 列舉 | 名描述 | 對正則運算式的影響 |
|---|---|---|
| MatchOptions.BeginsWith | 型態必須從文字開頭相配。 | 在正則運算式的開頭新增 ^。 |
| MatchOptions.Complete | IsMatch 預設值。 模式必須從頭到尾相配整個文字字串。 | 在正則運算式的開頭新增 ^，並在結尾新增 $。 |
| MatchOptions.Contains | Match 和 MatchAll 的預設值。 型態必須出現在文字中的某處，但不必在開頭或結尾處。 | 不修改正則運算式。 |
| MatchOptions.EndsWith | 型態必須從文字結尾相配。 | 在規則運算式的結尾新增 $。 |
| MatchOptions.IgnoreCase | 將大寫與小寫字母視為相同。 根據預設，相配會區分大小寫。 | 不修改正則運算式。 此選項與適用正則運算式之標準 "i" 修飾字相等。 |
| MatchOptions.多行 | 跨多行相配。 | 不修改正則運算式。 此選項與適用正則運算式之標準 "m" 修飾字相等。 |
使用 MatchAll 等於使用標準 "g" 修飾字於正則運算式。
語法
IsMatch（ 文本， 模式 [， 選項 ]）
- Text –必需。 要測試的文字字串。
- pattern –必需。 要當成文字字串測試的型態。 串連 Match 列舉定義的預先定義型態，或提供正則運算式。 Pattern 必須是一個常量公式，不包含任何變數、數據源或其他隨著應用程式運行而變化的動態引用。
- Options（選項） –可選。 MatchOptions 列舉值的文字字串組合。 系統預設會使用 MatchOptions.Complete。
符合（ 文字， 模式 [， 選項 ]）
- Text –必需。 要相配的文字字串。
- pattern –必需。 要當成文字字串相配的型態。 串連 Match 列舉定義的預先定義型態，或提供正則運算式。 Pattern 必須是一個常量公式，不包含任何變數、數據源或其他隨著應用程式運行而變化的動態引用。
- Options（選項） –可選。 MatchOptions 列舉值的文字字串組合。 系統預設會使用 MatchOptions.Contains。
MatchAll（ 文本， 模式 [， 選項 ]）
- Text –必需。 要相配的文字字串。
- pattern –必需。 要當成文字字串相配的型態。 串連 Match 列舉定義的預先定義型態，或提供正則運算式。 Pattern 必須是一個常量公式，不包含任何變數、數據源或其他隨著應用程式運行而變化的動態引用。
- Options（選項） –可選。 MatchOptions 列舉值的文字字串組合。 系統預設會使用 MatchOptions.Contains。
IsMatch 範例
一般字元
假設您的應用程式包含名為 TextInput1 的 Text input 控制項。 使用者在這個控制項輸入值以便儲存到資料庫。
使用者在 TextInput1 中輸入 Hello world。
| 公式 | 描述 | 結果 |
|---|---|---|
IsMatch( TextInput1.Text, "Hello world" ) |
測試使用者的輸入是否完全符合字串 "Hello world"。 | 真 |
IsMatch( TextInput1.Text, "Good bye" ) |
測試使用者的輸入是否完全符合字串 "Good bye"。 | 假 |
IsMatch( TextInput1.Text, "hello", Contains ) |
測試使用者的輸入是否包含 "hello" (區分大小寫)。 | 假 |
IsMatch( TextInput1.Text, "hello", Contains & IgnoreCase ) |
測試使用者的輸入是否包含 "hello" (不區分大小寫)。 | 真 |
預先定義的型態
| 公式 | 描述 | 結果 |
|---|---|---|
IsMatch( "123-45-7890", Digit & Digit & Digit & Hyphen & Digit & Digit & Hyphen & Digit & Digit & Digit & Digit ) |
相配美國的社會安全號碼 | 真 |
IsMatch( "joan@contoso.com", Email ) |
相配電子郵件地址 | 真 |
IsMatch( "123.456", MultipleDigits & Period & OptionalDigits ) |
相配一連串數字、句號，然後零個或多位數。 | 真 |
IsMatch( "123", MultipleDigits & Period & OptionalDigits ) |
相配一連串數字、句號，然後零個或多位數。 文字中沒有相配的句號，因此這個型態未相配成功。 | 假 |
規則運算式
| 公式 | 描述 | 結果 |
|---|---|---|
IsMatch( "986", "\d+" ) |
相配大於零的整數。 | 真 |
IsMatch( "1.02", "\d+(\.\d\d)?" ) |
相配正數貨幣金額。 如果輸入中包含小數點，輸入值也必須在小數點後面 2 個數字字元。 例如，3.00 有效，但 3.1 無效。 | 真 |
IsMatch( "-4.95", "(-)?\d+(\.\d\d)?" ) |
相配正數或負數的貨幣金額。 如果輸入中包含小數點，輸入值也必須在小數點後面 2 個數字字元。 | 真 |
IsMatch( "111-11-1111", "\d{3}-\d{2}-\d{4}" ) |
相配美國的社會安全號碼。 驗證提供輸入欄位的格式、類型和長度。 要相配的字串必須包含 3 個數字字元，後接一個連字號，再來是 2 個數字字元，後接一個連字號，然後是 4 個數字字元。 | 真 |
IsMatch( "111-111-111", "\d{3}-\d{2}-\d{4}" ) |
和前一個範例相同，但輸入的其中一個連字號位置不對。 | 假 |
IsMatch( "AStrongPasswordNot", "(?!^[0-9]\*$)(?!^[a-zA-Z]\*$)([a-zA-Z0-9]{8,10})" ) |
驗證強式密碼，此密碼必須包含 8 個、9 個或 10 個字元，此外要有至少一個數字和至少一個字母字元。 字串中不能包含特殊字元。 | 假 |
Match 和 MatchAll 範例
| 公式 | 描述 | 結果 |
|---|---|---|
Match( "Bob Jones <bob.jones@contoso.com>", "<(?<email>" & Match.Email & ")>" |
只提取連絡人資訊的電子郵件部分。 | { email: "bob.jones@contoso.com", FullMatch: "<bob.jones@contoso.com>", SubMatches: [ "bob.jones@contoso.com" ], StartMatch: 11 } |
Match( "Bob Jones <InvalidEmailAddress>", "<(?<email>" & Match.Email & ")>" |
只提取連絡人資訊的電子郵件部分。 找不到合法位址 (沒有 @ 符號)，因此函式會傳回 blank。 | 空白 |
Match( Language(), "(<language>\w{2})(?:-(?<script>\w{4}))?(?:-(?<region>\w{2}))?" ) |
提取 Language 函式傳回的語言標記中，語言、程式碼及區域部份。 這些結果會反映美國；如需更多範例，請參閱 Language 函式文件。 (?: 運算子群組字元，不會建立另一個子相配。 | { 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)?" ) |
從 ISO 8601 延續期間值提取小時、分鐘和秒。 提取的數字仍然位於文字字串中；在執行數學運算之前，請使用 Value 函式將其轉換為數字。 | { hours: "2", minutes: "1", seconds: "39", FullMatch: "PT2H1M39S", SubMatches:["2","1","39"], StartMatch: 1 } |
讓我們深入瞭解最後一個範例。 如果您想要使用 Time 函式將這個字串轉換成日期/時間，您必須分別傳入具名的子相配。 若要這樣做，您可以使用在 Match 傳回記錄上執行的 With 函式：
With(
Match( "PT2H1M39S", "PT(?:(?<hours>\d+)H)?(?:(?<minutes>\d+)M)?(?:(?<seconds>\d+)S)?" ),
Time( Value( hours ), Value( minutes ), Value( seconds ) )
)
對於這些範例，新增 Button 控制項，並將其 OnSelect 屬性設定為下列公式，然後選取按鈕：
Set( pangram, "The quick brown fox jumps over the lazy dog." )
| 公式 | 描述 | 結果 |
|---|---|---|
Match( pangram, "THE", IgnoreCase ) |
在 pangram 變數包含的文字字串中尋找所有符合 "THE" 的項目。 字串包含兩個符合項目，但只會傳回第一個，因為您使用的是 Match 和非 MatchAll。 因為未定義子相配，所以 SubMatches 欄位是空白的。 | { FullMatch: "The", SubMatches: [ ], StartMatch: 32 } |
MatchAll( pangram, "the" ) |
在 pangram 變數包含的文字字串中尋找所有符合 "the" 的項目。 測試是區分大小寫的，因此只會找到第二個 "the" 的執行個體。 因為未定義子相配，所以 SubMatches 欄位是空白的。 |  |
MatchAll( pangram, "the", IgnoreCase ) |
在 pangram 變數包含的文字字串中尋找所有符合 "the" 的項目。 本案例中，測試是不區分大小寫的，因此會找到該單字的兩個執行個體。 因為未定義子相配，所以 SubMatches 欄位是空白的。 |  |
MatchAll( pangram, "\b\wo\w\b" ) |
會在中間尋找 "o" 的所有三字母單字。 請注意，因為它不是三字母單字，因此不符合 "\b" (單字邊界)，因而排除 "brown"。 |  |
Match( pangram, "\b\wo\w\b\s\*(?<between>\w.+\w)\s\*\b\wo\w\b" ) |
符合 "fox" 與 "dog" 之間的所有字元。 | { between: "jumps over the lazy", FullMatch: "fox jumps over the lazy dog", SubMatches: [ "jumps over the lazy" ], StartMatch: 17 } |
若要查看資源庫中的 MatchAll 結果：
