適用於：
畫布應用程式 Copilot Studio 模型導向應用程式 Power Platform CLI Dataverse 函數 Power Pages
測試相符項，或根據型樣擷取文字字串的一部分。
描述
此 IsMatch 函式會測試文字字串是否符合可包含一般字元、預先定義型樣或 正規表示式的型樣。 和MatchAll函數會Match傳回比對的內容，包括子比對專案。
用 IsMatch 來驗證使用者在 文字輸入 控制項中輸入的內容。 例如，在將結果儲存至資料來源之前，請確認使用者是否輸入了有效的電子郵件地址。 如果項目不符合您的條件，請新增其他控制項，提示使用者修正項目。
用 Match 來擷取符合型樣的第一個文字字串，以及 MatchAll 擷取所有相符的文字字串。 擷取子相符項以剖析複雜字串。
Match 傳回找到的第一個相符項目的資訊記錄，並 MatchAll 針對找到的每一個相符項目傳回記錄表格。 記錄或各記錄包含如下：
| Column | 類型 | 描述 |
|---|---|---|
| 命名的 Sub-Match 或 Sub-Matches | 文字 | 每個具名子相符專案都有自己的資料行。 使用 （？<名字>...） 在正則表達式中。 如果具名子相符項與其中一個預先定義直欄的名稱相同，則子相符項優先，並產生警告。 重新命名子相符專案以避免此警告。 |
| FullMatch 全面匹配 | 文字 | 所有符合的文字字串。 |
| StartMatch 開始 | 號碼 | 輸入文字字串中的相配起始位置。 字串的第一個字元傳回 1。 |
| SubMatches，只有在使用 MatchOptions.NumberedSubMatches 時。 | 文字的單欄資料表 (欄位 值) | 編號子相符項目的表格，其顯示順序為規則運算式。 一般而言，具名子相符專案較容易使用，並受到鼓勵。 使用 ForAll 函式或 Index 函式來處理個別子相符專案。 如果未在正則運算式中定義子相符項，則此表格將存在但為空。 |
這些函式支援 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 成員結合：
| Match 列舉 | 描述 | 規則運算式 |
|---|---|---|
| 任何 | 相配任何字元。 | . |
| 逗點 | 匹配逗號 ,。 |
, |
| 數位 | 相配單一位數 ("0" 到 "9")。 | \d |
| 相配包含 "at" 符號 ("@") 的電子郵件地址以及包含點 (".") 的網域名稱 | 請參閱註釋 | |
| 連字型大小 | 相配連字號。 |
-
請參閱註釋 |
| 左帕倫 | 符合左括號 (。 |
\( |
| 信 | 相配字母。 | \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 會針對 Match使用不同的定義。EMail 和 Match.連字號。 評估以 Text( Match.Email ) 查看主機使用的正規表示式。
規則運算式
這些函數使用的模式稱為 正則表達式。 Power Fx 的特定規則運算式方言詳見 Power Fx 中的規則運算式。
正規表示式功能強大，用途廣泛。 它們也可能看起來像隨機的標點符號序列。 本文並未描述正規表示式的所有方面，但網路上提供了豐富的資訊、教學和工具。
正則表達式有著悠久的歷史，並且有多種程式語言版本。 每種程式語言都有自己的正則表達式方言，而且標準很少。 我們努力確保相同的規則運算式在所有 Power Fx 實作中提供相同的結果。 相容性並不容易實現，因為 Power Fx 在 JavaScript 和 .NET 之上執行，兩者有顯著差異。 為了適應在不同平台上的運行，Power Fx 正則運算式僅限於整個行業廣泛支援的功能子集。
因此，某些可能在其他環境中運作的正則運算式可能會遭到封鎖，或需要在 Power Fx 中進行調整。 當遇到不支援的功能時，會報告編寫時間錯誤。 這是正規表示式和選項必須是編寫時間常數且非動態 （例如，在變數中提供） 的原因之一。
備註
Power Apps 使用舊版的 Power Fx 正規表示式，其限制較少，但功能也較少。 MatchOptions.DotAll 和 MatchOptions.FreeSpacing 無法使用，而且 的定義 Match。電子郵件和Match.連字符 是不同的。 Unicode 代理組不會被視為單一字元。 MatchOptions.NumberedSubMatches 是預設值。 此處描述的正則運算式版本將很快在 Power Apps 中以「Power Fx V1.0 相容性」參數提供。
以下是正則表達式的一些基本元素，這些元素會增加解析數字的複雜性。
| 特徵 / 功能 | Example | 描述 |
|---|---|---|
| 預先定義的字元類別 | \d |
此規則運算式會符合單一數字，例如 1。 字元類別會\d比對一組字元，並將0標準數字比對至 9 Unicode 字元類別 “Nd” 中定義的數字。 有字母和數字的字符類，包括 \w 帶有的換行 \s符。 還有大寫的反向字元類別： \D 匹配所有不大寫的字 \d 元類別。 |
| 一個或多個 | \d+ |
此規則運算式會符合一或多個數字，例如 123。 元素後面的 A + 表示最後一個元素的「一個或多個」。 |
| 零或一 | \+?\d |
此正則運算式會符合選用 + 符號，後面接著一個或多個數字，例如 +123 ，以及 123。 元素後面的 a 說 ? 「這是可選的，它可以發生零次或一次」。 前面 + 有一個反斜線，以將其區分為文字字符，而不是“一個或多個”用法。 |
| 分組和交替 | (-|\+)?\d+ |
此規則運算式會比對符號或 ，選擇性地比對，然後是+一連串數字，例如 -、 -123和 +123。123 我們在這裡介紹兩個經常一起使用的概念。 首先，我們有一個括號，它將元素組合在一起，以便 採取行動 ? 。 其次，我們有 | “要么這個，要么那個”。 |
| 自訂字元類別 | (-|\+)?\d+[eE][\-\+]?\d+ |
此正則運算式會將指數新增至具有兩個字元類別的混合，比對 +123e-12。 角色類別就像交替以 | 更緊湊的形式提供「匹配其中一項」。 與 +一樣，在 - 正則表達式字元類別中具有特殊意義，因此我們需要轉義它。 |
| 零或多個 | (-|\+)?\d+\.?\d*[eE][\-\+]?\d+ |
此規則運算式會在數字的整數部分之後加上小數，例如 -123.456e-89 或 -123.E+32。 小數點\d後有一個*量詞，表示十進制數字的「零次或多次」. |
| 擷取群組 | (?<number>(-|\+)?\d+\.?\d*)[eE](?<exponent>[\-\+]?\d+) |
最後，我們新增 和 number的exponent擷取群組。 正規表示式不僅可以比對整個字串，還可以擷取部分以用於公式，在本例中為 （或e） 之前E的部分和之後的部分。 |
這些範例僅提供正則運算式可以執行的一小部分動作。 它們通常用於驗證身分證號碼、電子郵件地址、電話號碼、日期和時間，以及從各種文字檔案中提取資訊。 閱讀 Power Fx 中的規則運算式、實驗並使用 Web 以深入瞭解，繼續您的旅程。
Match 選項
指定一或多個選項來修改這些函式的行為，您可以使用字串串連運算子 （&） 來組合這些選項。
| MatchOptions 列舉 | 描述 | 對正則運算式的影響 |
|---|---|---|
| MatchOptions.BeginsWith | 型態必須從文字開頭相配。 | 在正則運算式的開頭新增 ^。 |
| MatchOptions.Complete | Power Apps 上的預設值 IsMatch 。 模式會從頭到尾與整個文字字串相符。 | 在正則運算式的開頭新增 ^，並在結尾新增 $。 |
| MatchOptions.Contains | 預設值為 Match 和 MatchAll，以及 IsMatch Power Apps 外部。 型態必須出現在文字中的某處，但不必在開頭或結尾處。 | 不修改正則運算式。 |
| MatchOptions.點所有 | 變更 （點） 運算子的 . 行為，以符合所有字元，包括換行字元。 在 Power Apps 中不可用。 |
不修改正則運算式。 此選項相當於正規表示式的標準「s」修飾符。 |
| MatchOptions.EndsWith | 型態必須從文字結尾相配。 | 在規則運算式的結尾新增 $。 |
| MatchOptions.FreeSpacing | 空格字元（包括換行符）在正則表達式中被忽略。 以 a # 開頭的行尾註解會被忽略。 在 Power Apps 中不可用。 |
僅更改正規表示式語法的方式。 此選項相當於正則運算式的標準「x」修飾符。 |
| MatchOptions.IgnoreCase | 將大寫與小寫字母視為相同。 根據預設，相配會區分大小寫。 | 不修改正則運算式。 此選項與適用正則運算式之標準 "i" 修飾字相等。 |
| MatchOptions.多行 | 變更 和 ^ 的$行為，以符合 aline 結尾。 |
不修改正則運算式。 此選項與適用正則運算式之標準 "m" 修飾字相等。 |
| MatchOptions.NumberedSubMatches | 具名擷取是偏好的，因為它們更容易理解和維護。 效能也會改善，因為不會保留不需要的擷取。 但對於較舊的正規表示式，會將每組括弧視為結果中 SubMatches 表格中包含的編號擷取。 Power Apps 中的預設值。 | 不修改正則運算式。 已停用具名擷取，並 \1 啟用型式回參考。 |
使用 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。
| 公式 | 描述 | 結果 |
|---|---|---|
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", Match.Digit & Match.Digit & Match.Digit & Match.Digit & Match.Digit & Match.Digit & Match.Digit & Match.Digit & Match.Digit & Match.Digit & Match.Digit ) |
相配美國的社會安全號碼 | 真 |
IsMatch( "joan@contoso.com", Match.Email ) |
相配電子郵件地址 | 真 |
IsMatch( "123.456", Match.MultipleDigits & Match.Period & Match.OptionalDigits ) |
相配一連串數字、句號，然後零個或多位數。 | 真 |
IsMatch( "123", Match.MultipleDigits & Match.Period & Match.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})" ) |
驗證必須包含八個、九個或 10 個字元、至少一個數字和至少一個字母字元的強式密碼。 字串不能包含特殊字元。 | 假 |
Match 和 MatchAll 範例
| 公式 | 描述 | 結果 |
|---|---|---|
Match( "Bob Jones <bob.jones@contoso.com>", "<(?<email>" & Match.Email & ")>") |
只提取連絡人資訊的電子郵件部分。 | { 電子郵件：“bob.jones@contoso.com”， FullMatch： “<bob.jones@contoso.com>”， 開始比賽：11 } |
Match( "Bob Jones <InvalidEmailAddress>", "<(?<email>" & Match.Email & ")>" |
只提取連絡人資訊的電子郵件部分。 找不到合法位址 (沒有 @ 符號)，因此函式會傳回 blank。 | 空白 |
Match( Language(), "(<language>\w{2})(?:-(?<script>\w{4}))?(?:-(?<region>\w{2}))?" ) |
提取 Language 函式傳回的語言標記中，語言、程式碼及區域部份。 這些結果會反映美國；如需更多範例，請參閱 Language 函式文件。 (?: 運算子群組字元，不會建立另一個子相配。 | { 語言：“en”， script: blank, 地區：“美國”， FullMatch：「en-US」、 開始比賽：1 } |
Match( "PT2H1M39S", "PT(?:(?<hours>\d+)H)?(?:(?<minutes>\d+)M)?(?:(?<seconds>\d+)S)?" ) |
從 ISO 8601 延續期間值提取小時、分鐘和秒。 提取的數字仍然位於文字字串中；在執行數學運算之前，請使用 Value 函式將其轉換為數字。 | { 小時：“2”， 分鐘：“1”， 秒：“39”， FullMatch：「PT2H1M39S」， 開始比賽：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。 | { 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 ：
