文本控件由文本输入框、密码框、自动建议框和文本块组成。 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 元素支持基于段落的文本。 它没有可用于在应用中轻松访问控件的文本内容的文本属性。
文本输入
使用 TextBox 控件允许用户输入和编辑未格式化的文本，例如在窗体中。 可以使用 Text 属性获取和设置 TextBox 中的文本。
你可以使 TextBox 只读，但这应该是一个临时的条件状态。 如果文本永远不可编辑，请考虑改用 TextBlock。
使用 PasswordBox 控件收集密码或其他私人数据，例如社会安全号码。 密码框是一个文本输入框，用于隐藏为隐私而键入的字符。 密码框类似于文本输入框，只是它呈现项目符号代替已输入的文本。 可以自定义项目符号字符。
使用 AutoSuggestBox 控件向用户显示键入时要从中选择的建议列表。 自动建议框是触发基本搜索建议列表的文本输入框。 建议的字词可以从热门搜索词和历史用户输入字词的组合中抽出。
还应使用 AutoSuggestBox 控件来实现搜索框。
使用 RichEditBox 显示和编辑文本文件。 你不使用 RichEditBox 将用户输入获取到应用中的方式，就像使用其他标准文本输入框一样。 而是使用它来处理与应用分开的文本文件。 通常将输入到 RichEditBox 中的文本保存到.rtf文件中。
文本输入是否是最佳选项？
可通过多种方式在应用中获取用户输入。 这些问题将有助于回答标准文本输入框之一或其他控件是否最适合获取用户输入。
- 高效枚举所有有效值是否可行？ 如果是这样，请考虑使用其中一个选择控件，例如 复选框、 下拉列表、列表框、 单选按钮、 滑块、 切换开关、 日期选取器或时间选取器。
- 是否有一组相当小的有效值？ 如果是这样，请考虑 下拉列表 或列表框，尤其是值长度超过几个字符时。
- 有效数据是否完全不受约束？ 还是有效数据仅受格式约束（受约束长度或字符类型）？ 如果是，请使用文本输入控件。 可以限制可输入的字符数，并且可以在应用代码中验证格式。
- 该值是否表示具有专用通用控件的数据类型？ 如果是，请使用适当的控件而不是文本输入控件。 例如，使用 DatePicker 而不是文本输入控件来接受日期条目。
- 如果数据严格为数值：
例子
| WinUI 2 库 | |
|---|---|
|
如果已安装 WinUI 2 库 应用，请单击此处 打开该应用并查看作中的文本控件。 |
文本框
自动建议框
密码框
创建文本控件
有关特定于每个文本控件的信息和示例，请参阅以下文章。
字体和样式指南
有关字体指南，请参阅以下文章：
笔输入
适用于： 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 表情符号字体定义表情符号和其他表情符号字符的颜色版本。
标准文本控件和富文本控件支持显示颜色字体。 默认情况下， IsColorFontEnabled 属性为 true ，并且这些附加层的字体以颜色呈现。 系统上的默认颜色字体是 Segoe UI 表情符号，控件将回退到此字体以显示颜色字形。
<TextBlock FontSize="30">Hello ☺⛄☂♨⛅</TextBlock>
呈现的文本如下所示：
有关详细信息，请参阅 IsColorFontEnabled 属性。
行分隔符和段落分隔符指南
适用于： TextBlock、RichTextBlock、多行 TextBox、RichEditBox
使用行分隔符（0x2028）和段落分隔符（0x2029）分隔纯文本。 在每行分隔符之后开始一个新行。 在每个段落分隔符之后开始新的段落。
不必用这些字符启动文件中的第一行或段落，或者用它们结束最后一行或段落：这样做表示该位置中存在空行或段落。
你的应用可以使用行分隔符来指示无条件的行尾。 但是，行分隔符与单独的回车符和换行符或这些字符的组合不对应。 行分隔符必须独立于回车符和换行符进行处理。
应用可以在文本段落之间插入段落分隔符。 使用此分隔符可以创建纯文本文件，这些文件可在不同的作系统上使用不同的行宽进行格式设置。 目标系统可以忽略任何行分隔符，并且仅在段落分隔符处中断段落。
拼写检查指南
适用于： TextBox、RichEditBox
在文本输入和编辑过程中，拼写检查会通知用户单词拼写错误，方法是用红色波浪线突出显示该单词，并为用户提供更正拼写错误的方法。
下面是内置拼写检查器的示例：
将拼写检查与文本输入控件一起使用，以实现以下两个目的：
自动更正拼写错误
拼写检查引擎在对更正充满信心时自动更正拼写错误的单词。 例如，引擎会自动将“the”更改为“the”。
显示备用拼写
当拼写检查引擎对更正不有信心时，它会在拼写错误的单词下添加一条红线，并在点击或右键单击该单词时在上下文菜单中显示备用项。
使用拼写检查帮助用户在文本输入控件中输入字词或句子时提供帮助。 拼写检查适用于触摸、鼠标和键盘输入。
当单词可能不在字典中或用户不重视拼写检查时，请勿使用拼写检查。 例如，如果文本框旨在捕获电话号码或名称，请不要打开它。
不要仅因为当前拼写检查引擎不支持应用语言而禁用拼写检查。 当拼写检查器不支持某个语言时，它不会执行任何作，因此在离开选项时不会造成任何伤害。 此外，某些用户可能使用输入法编辑器（IME）将其他语言输入到应用中，并且可能支持该语言。 例如，生成日语应用时，即使拼写检查引擎当前无法识别该语言，也不会关闭拼写检查。 用户可以切换到英语 IME，并在应用中键入英语;如果启用了拼写检查，英语将进行拼写检查。
对于 TextBox 和 RichEditBox 控件，拼写检查默认处于打开状态。 可以通过将 IsSpellCheckEnabled 属性设置为 false 来将其关闭。
相关文章
对于设计人员
面向开发人员（XAML）
