IsMatch、 和MatchMatchAll函數

適用於： 畫布應用程式 Copilot Studio 模型導向應用程式 Power Platform CLI Dataverse 函數 Power Pages

測試相符項，或根據型樣擷取文字字串的一部分。

描述

此 IsMatch 函式會測試文字字串是否符合可包含一般字元、預先定義型樣或 正規表示式的型樣。 和MatchAll函數會Match傳回比對的內容，包括子比對專案。

用 IsMatch 來驗證使用者在 文字輸入 控制項中輸入的內容。 例如，在將結果儲存至資料來源之前，請確認使用者是否輸入了有效的電子郵件地址。 如果項目不符合您的條件，請新增其他控制項，提示使用者修正項目。

用 Match 來擷取符合型樣的第一個文字字串，以及 MatchAll 擷取所有相符的文字字串。 擷取子相符項以剖析複雜字串。

Match 傳回找到的第一個相符項目的資訊記錄，並 MatchAll 針對找到的每一個相符項目傳回記錄表格。 記錄或各記錄包含如下：

這些函式支援 MatchOptions。 預設情況：

• 這些函式執行區分大小寫的相配。 使用 MatchOptions.IgnoreCase 執行不區分大小寫的比對。
• IsMatch 符合整個文字字串 （Complete MatchOption），而 Match 並在 MatchAll 文字字串中的任何位置搜尋相符專案 （Contains MatchOption）。 依適當情況針對您的案例使用 Complete、Contains、BeginsWith、或 EndsWith。

IsMatch 如果文字字串與模式相符，則傳回 true ，如果不符合，則傳回 false 。 Match如果找不到可以使用 IsBlank 函式測試的相符專案，則會傳回空白。 MatchAll 如果找不到可以使用 IsEmpty 函式測試的相符專案，則會傳回空的資料表。

如果您用於 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」的大小寫錯誤。 （如需修改此行為的方法，請參閱 Match 選項 。

在型樣語言中，字元 . ? * + ( ) [ ] ^ $ | \ 是保留用於特殊用途的。 若要使用這些字元，請在字 \ 元前加上 （反斜線） 以指出字元應該按字面意思理解，或使用其中一個預先定義的模式。 例如，您可以使用問號前帶有反斜線的模式"Hello?"來比對字串"Hello\\?"。

預先定義的型態

預先定義的型態提供簡單的方法來相配其中一組字元或多個字元的順序。 使用 字串串連運算子 & 將您自己的文字字串與列舉的 Match 成員結合：

例如，模式 “A” &; MultipleDigits 會比對字母 “A” ，後面接著一或多個數字。

Power Apps 會針對 Match使用不同的定義。EMail 和 Match.連字號。 評估以 Text( Match.Email ) 查看主機使用的正規表示式。

規則運算式

這些函數使用的模式稱為 正則表達式。 Power Fx 的特定規則運算式方言詳見 Power Fx 中的規則運算式。

正規表示式功能強大，用途廣泛。 它們也可能看起來像隨機的標點符號序列。 本文並未描述正規表示式的所有方面，但網路上提供了豐富的資訊、教學和工具。

正則表達式有著悠久的歷史，並且有多種程式語言版本。 每種程式語言都有自己的正則表達式方言，而且標準很少。 我們努力確保相同的規則運算式在所有 Power Fx 實作中提供相同的結果。 相容性並不容易實現，因為 Power Fx 在 JavaScript 和 .NET 之上執行，兩者有顯著差異。 為了適應在不同平台上的運行，Power Fx 正則運算式僅限於整個行業廣泛支援的功能子集。

因此，某些可能在其他環境中運作的正則運算式可能會遭到封鎖，或需要在 Power Fx 中進行調整。 當遇到不支援的功能時，會報告編寫時間錯誤。 這是正規表示式和選項必須是編寫時間常數且非動態 （例如，在變數中提供） 的原因之一。

以下是正則表達式的一些基本元素，這些元素會增加解析數字的複雜性。

這些範例僅提供正則運算式可以執行的一小部分動作。 它們通常用於驗證身分證號碼、電子郵件地址、電話號碼、日期和時間，以及從各種文字檔案中提取資訊。 閱讀 Power Fx 中的規則運算式、實驗並使用 Web 以深入瞭解，繼續您的旅程。

Match 選項

指定一或多個選項來修改這些函式的行為，您可以使用字串串連運算子 （&） 來組合這些選項。

使用 MatchAll 與對規則運算式使用標準「g」修飾符相同。

語法

IsMatch（ 文字， 圖案 [， 選項 ] ）

• Text –必需。 要測試的文字字串。
• pattern –必需。 要當成文字字串測試的型態。 串連列舉定義的 Match 預先定義模式，或提供正則運算式。 模式 必須是常數公式，沒有變數、資料來源或其他動態參照，這些會隨著應用程式執行而變更。 請注意，公式必須表示為“Match.PredefinedPattern“， Match例如 .電子郵件
• Options（選項） –可選。 MatchOptions 列舉值的文字字串組合。 系統預設會使用 MatchOptions.Complete。 選項 必須是常數公式，沒有變數、資料來源或其他隨著應用程式執行而變更的動態參照。

Match（ 文字， 圖案 [， 選項 ] ）

• Text –必需。 要相配的文字字串。
• pattern –必需。 要當成文字字串相配的型態。 串連列舉定義的 Match 預先定義模式，或提供正規表示式。 Pattern 必須是一個常量公式，不包含任何變數、數據源或其他隨著應用程式運行而變化的動態引用。
• Options（選項） –可選。 MatchOptions 列舉值的文字字串組合。 系統預設會使用 MatchOptions.Contains。 選項 必須是常數公式，沒有任何變數、資料來源或其他動態參考，這些變數會隨著應用程式執行而變更。

MatchAll（ 文字， 圖案 [， 選項 ] ）

• Text –必需。 要相配的文字字串。
• pattern –必需。 要當成文字字串相配的型態。 串連列舉定義的 Match 預先定義模式，或提供正則運算式。 模式 必須是常數公式，沒有變數、資料來源或其他動態參照，這些會隨著應用程式執行而變更。
• Options（選項） –可選。 MatchOptions 列舉值的文字字串組合。 系統預設會使用 MatchOptions.Contains。 選項 必須是常數公式，沒有變數、資料來源或其他隨著應用程式執行而變更的動態參照。

IsMatch 範例

一般字元

假設您的應用程式有一個名為 TextInput1 的文字輸入控制項。 使用者在此控制項中輸入值，以將它們儲存在資料庫中。

使用者在 TextInput1 中輸入 Hello world。

預先定義的型態

規則運算式

Match 和 MatchAll 範例

讓我們深入瞭解最後一個範例。 如果您想要使用 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。	{ FullMatch：「The」， 開始比賽：32 }
MatchAll( pangram, "the" )	在 pangram 變數包含的文字字串中尋找所有符合 "the" 的項目。 測試是區分大小寫的，因此只會找到第二個 "the" 的執行個體。
MatchAll( pangram, "the", IgnoreCase )	在 pangram 變數包含的文字字串中尋找所有符合 "the" 的項目。 本案例中，測試是不區分大小寫的，因此會找到該單字的兩個執行個體。
MatchAll( pangram, "\b\wo\w\b" )	會在中間尋找 "o" 的所有三字母單字。 「brown」被排除在外，因為它不是三個字母的單詞，因此無法匹配 “\b” （單詞邊界）。
Match( pangram, "\b\wo\w\b\s\*(?<between>\w.+\w)\s\*\b\wo\w\b" )	符合 "fox" 與 "dog" 之間的所有字元。	{ 之間：“跳過懶惰”， FullMatch：「狐狸跳過懶狗」， 開始比賽：17 }

若要在圖庫中查看結果 MatchAll ：

1. 在空白畫面中，插入空白的垂直 資源庫 控制項。

2. 將資源庫的 Items 屬性設定為 MatchAll（ pangram， “\w+” ） 或 MatchAll（ pangram， MultipleLetters ）。

   

3. 在資源庫控制項中間，選取從 "Add an item from the Insert tab" 以選取資源庫範本。

4. 新增 Label 控制項到資源庫的範本。

5. 將標籤的 Text 屬性設定為 ThisItem.FullMatch。

   資源庫會填入範例文字中的每個字。 若要在一個畫面上查看所有單字，請調整資源庫的範本和標籤控制項的大小。