文本控件
文本控件由文本输入框、密码框、自动建议框和文本块组成。 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)
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈