文字控制項

文字控制件包含文字輸入方塊、密碼方塊、自動建議方塊和文字塊。 XAML 架構提供數個控件來轉譯、輸入和編輯文字，以及一組用於格式化文字的屬性。

• 顯示只讀文字的控件為 TextBlock 和 RichTextBlock。
• 文字輸入和編輯的控件包括：TextBox、RichEditBox、AutoSuggestBox 和 PasswordBox。

重要 API：TextBlock 類別、RichTextBlock 類別、TextBox 類別、RichEditBox 類別、AutoSuggestBox 類別、PasswordBox 類別

這是正確的控制項嗎？

您使用的文字控制件取決於您的案例。 使用此資訊來挑選應用程式中使用的正確文字控制件。

轉譯唯讀文字

使用 TextBlock 在您的應用程式中顯示大部分唯讀文字。 您可以使用它來顯示單行或多行文字、內嵌超連結，以及具有粗體、斜體或底線格式的文字。

TextBlock 通常更容易使用，並提供比 RichTextBlock 更好的文字轉譯效能，因此最適合大部分的應用程式 UI 文字。 您可以藉由取得 Text 屬性的值 ，輕鬆地從應用程式中的 TextBlock 存取和使用文字 。

它也提供許多相同的格式設定選項，以自定義文字的轉譯方式。 儘管您可以在文字中放置分行符號，但 TextBlock 是針對顯示單一段落而設計，不支援文字縮排。

當您需要支援多個段落、多欄文字或其他複雜文字版面配置，或影像等內嵌 UI 元素時，請使用 RichTextBlock。 RichTextBlock 提供數個進階文字配置功能。

RichTextBlock 的內容屬性是 Blocks 屬性，可透過 Paragraph 元素支援以段落 為基礎的文字。 它沒有 Text 屬性，您可用來輕鬆地存取應用程式中控件的文字內容。

文字輸入

使用者可使用 TextBox 控制項來輸入和編輯未格式化的文字 (例如在表單中)。 您可以使用 Text 屬性來取得 TextBox 中的文字，並在其中設定文字。

您可將 TextBox 設為唯讀，但此應為暫時性的條件狀態。 若該文字永遠無法編輯，請考慮改用 TextBlock。

使用 PasswordBox 控制項，以收集密碼或其他私人資料，例如身分證字號。 密碼方塊是一個文字輸入方塊，會為了隱私權而隱藏輸入的字元。 密碼方塊看起來就像文字輸入方塊，只不過它會將已輸入的文字轉譯成項目符號。 您可以自訂項目符號字元。

使用 AutoSuggestBox 控制件向使用者顯示建議清單，以在輸入時從中選擇。 自動建議方塊是觸發基本搜尋建議清單的文字框。 建議的字詞可以取自熱門搜尋字詞和歷史使用者輸入字詞的組合。

您也應該使用 AutoSuggestBox 控制項來實作搜尋方塊。

使用 RichEditBox 來顯示和編輯文字檔。 您不會使用 RichEditBox，以使用其他標準文字輸入方塊的方式，將使用者輸入到您的應用程式。 相反地，您可以使用它來處理與應用程式分開的文字檔。 您通常會將輸入至 RichEditBox 的文字儲存至.rtf檔案。

文字輸入是否為最佳選項？

有許多方式可讓您在應用程式中取得用戶輸入。 這些問題將有助於回答其中一個標準文字輸入方塊或其他控件是否最適合用於取得用戶輸入。

• 有效率地列舉所有有效的值是否實際？ 如果是，請考慮使用其中一個選取控件，例如複選框、下拉式清單、清單框、單選按鈕、滑桿、切換開關、日期選擇器或時間選擇器。
• 是否有一組相對小的有效值？ 如果是，請考慮 下拉式清單 或清單框，特別是值長度超過幾個字元時。
• 有效資料是否完全不受限制？ 或有效資料是否只有格式上的限制 (受限制的長度或字元類型)？ 如果是，請使用文字輸入控件。 您可以限制可以輸入的字元數，而且您可以在應用程式程式代碼中驗證格式。
• 該值代表的資料類型是否已經有特殊的通用控制項？ 如果是，請使用適當的控件，而不是文字輸入控件。 例如，使用 DatePicker ，而不是文字輸入控件來接受日期專案。
• 如果資料嚴格為數值：
  • 輸入的值是否為近似和 (或) 相對於相同頁面上的其他數量？ 如果是，請使用 滑桿。
  • 在變更設定時，獲得即時回應的效果是否為使用者帶來益處？ 如果是，請使用 滑桿，可能隨附控件。
  • 輸入的值是否可能在觀察結果後調整 (例如音量或螢幕亮度)？ 如果是，請使用 滑桿。

範例

WinUI 2 Gallery
	如果您已安裝 WinUI 2 資源庫 應用程式，請按下這裡開啟 應用程式並查看文字控制件的運作情形。 取得 WinUI 2 資源庫應用程式 (Microsoft Store) 取得原始程式碼 (GitHub)

Text box

自動建議方塊

密碼方塊

建立文字控制件

如需每個文字控件專屬的資訊和範例，請參閱這些文章。

• AutoSuggestBox
• PasswordBox
• RichEditBox
• RichTextBlock
• TextBlock
• TextBox

字型和樣式指導方針

如需字型指導方針，請參閱下列文章：

• 印刷樣式指導方針
• Segoe MDL2 圖示清單與指導方針

手寫筆輸入

適用於： TextBox、RichEditBox、AutoSuggestBox

從 Windows 10 版本 1803 開始，XAML 文字輸入方塊使用 Windows Ink 特別提供手寫筆輸入的內嵌支援。 當使用者使用 Windows 手寫筆點選文字輸入方塊時，文字方塊會改變形式，讓使用者使用手寫筆直接在其中書寫，而不是開啟另一個輸入面板。

如需詳細資訊，請參閱含手寫檢視的文字輸入。

選擇文字控制項的正確鍵盤

適用於： TextBox、PasswordBox RichEditBox

為協助使用者使用觸控式鍵盤或螢幕輸入面板 (SIP) 輸入資料，您可以設定文字控制項的輸入範圍，使其符合使用者要輸入的資料類型。

提示 此資訊僅適用於 SIP。 它不適用於 Windows 簡易存取選項中可用的硬體鍵盤或螢幕小鍵盤。

當您的應用程式在具備觸控式螢幕的裝置上執行時，可以使用觸控式鍵盤輸入文字。 當使用者點選可編輯的輸入欄位 (例如 TextBox 或 RichEditBox) 時，就會叫用觸控式鍵盤。 您可以設定文字控制項的輸入範圍，使其符合您預期使用者輸入的資料類型，讓使用者在您的應用程式中輸入資料時更加快速方便。 輸入範圍會提供控制項所預期之文字輸入類型的提示給系統，讓系統可以為該輸入類型提供專用的觸控式鍵盤配置。

例如，如果文字方塊只用來輸入 4 位數 PIN，請將 InputScope 屬性設定為 Number。 這會告訴系統顯示數字小鍵盤，方便使用者輸入 PIN。

重要
輸入範圍不會執行任何輸入驗證，也不會防止使用者透過硬體鍵盤或其他輸入設備提供任何輸入。 您仍然必須視需要在程式碼中驗證輸入。

如需詳細資訊，請參閱 使用輸入範圍來變更觸控式鍵盤。

色彩字型

適用於： TextBlock、RichTextBlock、TextBox、RichEditBox

Windows 能夠讓字型包含每個圖像的多個彩色圖層。 例如，Segoe UI Emoji 字型會定義 Emoticon 和其他 Emoji 字元的色彩版本。

標準和 RTF 控制件支援顯示色彩字型。 根據預設， IsColorFontEnabled 屬性為 true ，且具有這些額外圖層的字型會以色彩呈現。 系統上的預設色彩字型為 Segoe UI Emoji，控件會回復到此字型，以以色彩顯示字元。

<TextBlock FontSize="30">Hello ☺⛄☂♨⛅</TextBlock>

轉譯的文字看起來像這樣：

如需詳細資訊，請參閱 IsColorFontEnabled 屬性。

行和段落分隔符的指導方針

適用於： TextBlock、RichTextBlock、多行 TextBox、RichEditBox

使用行分隔符 （0x2028） 和段落分隔符 （0x2029） 來分割純文字。 每一行分隔符之後就會開始新的一行。 新的段落會在每個段落分隔符之後開始。

不需要在檔案中以這些字元啟動第一行或段落，或結束最後一行或結尾的段落;這樣做表示該位置中有空行或段落。

您的應用程式可以使用行分隔符來表示無條件行尾。 不過，行分隔符不會對應至個別的歸位字元和換行字元，或這些字元的組合。 行分隔符必須與歸位字元和換行字元分開處理。

您的應用程式可以在文字段落之間插入段落分隔符。 使用此分隔符可讓您建立純文本檔案，以不同作業系統上的不同行寬格式化。 目標系統可以忽略任何行分隔符，並只在段落分隔符中斷段落。

拼字檢查指導方針

適用於： TextBox、RichEditBox

在文字輸入和編輯期間，拼字檢查會通知使用者文字拼錯，方法是以紅色波浪線反白顯示文字，併為使用者提供更正拼字錯誤的方法。

以下是內建拼字檢查的範例：

針對這兩個用途，請搭配文字輸入控件使用拼字檢查：

• 自動校正拼字錯誤

  拼字檢查引擎會在對更正充滿信心時，自動更正拼錯字組。 例如，引擎會自動將 「the」 變更為 「the」。

• 顯示替代拼法

  當拼字檢查引擎對更正不有信心時，它會在拼錯字底下新增一條紅線，並在您點選或以滑鼠右鍵按下該字時，在操作功能表中顯示替代專案。

• 使用拼字檢查，協助使用者在文字輸入控件中輸入單字或句子時協助使用者。 拼字檢查適用於觸控、滑鼠和鍵盤輸入。

• 當單字可能不在字典中，或使用者不會重視拼字檢查時，請勿使用拼字檢查。 例如，如果文本框是要擷取電話號碼或名稱，請勿開啟它。

• 請勿停用拼字檢查，只是因為目前的拼字檢查引擎不支援您的應用程式語言。 當拼字檢查工具不支援語言時，它不會執行任何動作，因此在離開選項時不會造成任何傷害。 此外，某些使用者可能會使用輸入法編輯器 （IME） 將另一種語言輸入您的應用程式，而且可能支援該語言。 例如，建置日文語言應用程式時，即使拼字檢查引擎目前無法辨識該語言，也不會關閉拼字檢查。 用戶可以切換至英文輸入法，並在應用程式中輸入英文;如果已啟用拼字檢查，則英文將會收到拼字檢查。

針對 TextBox 和 RichEditBox 控制件，預設會開啟拼字檢查。 您可以將IsSpellCheckEnabled 屬性設定為 false 來關閉它。

相關文章

適用於設計人員

• 印刷樣式指導方針
• Segoe MDL2 圖示清單與指導方針
• 新增搜尋

適用於開發人員 (XAML)

• TextBox 類別 \(英文\)
• Windows.UI.Xaml.Controls PasswordBox 類別
• String.Length 屬性 \(部分機器翻譯\)