自定义文本输入

Windows.UI.Text.Core 命名空间中的核心文本 API 支持 UWP 应用通过 Windows 设备上受支持的任何文本服务接收文本输入。 这些 API 类似于 文本服务框架 API，该应用不需要详细了解文本服务。 这使应用能够接收任何语言和任何输入类型（如键盘、语音或笔）的文本。

重要 API：Windows.UI.Text.Core、CoreTextEditContext

为何使用核心文本 API？

对于许多应用，XAML 或 HTML 文本框控件足以用于文本输入和编辑。 但是，如果应用处理复杂的文本方案（如字处理应用），则可能需要自定义文本编辑控件的灵活性。 可以使用 CoreWindow 键盘 API 创建文本编辑控件，但这些 API 不提供接收基于合成的文本输入的方法，这是支持东亚语言所必需的。

需要创建自定义文本编辑控件时，请改用 Windows.UI.Text.Core API。 这些 API 旨在让你灵活地处理文本输入（采用任何语言）并提供最适合应用的文本体验。 使用核心文本 API 生成的文本输入和编辑控件可以从 Windows 设备上的所有现有文本输入法、 基于文本服务框架 的输入法编辑器（IME）以及电脑上的手写到 WordFlow 键盘（在移动设备上提供自动更正、预测和听写）接收文本输入。

体系结构

下面是文本输入系统的简单表示形式。

• “应用程序”表示托管使用核心文本 API 生成的自定义编辑控件的 Windows 应用。
• Windows.UI.Text.Core API 有助于通过 Windows 与文本服务进行通信。 文本编辑控件与文本服务之间的通信主要通过 CoreTextEditContext 对象进行处理，该对象提供用于促进通信的方法和事件。

文本范围和选择

编辑控件为文本输入提供空间，用户希望在此空间中的任何位置编辑文本。 在这里，我们将介绍核心文本 API 使用的文本定位系统，以及如何在此系统中表示范围和选择。

应用程序插入点位置

与核心文本 API 一起使用的文本范围以插入点位置表示。 “Application Caret Position （ACP）”是一个从零开始的数字，指示插入符号前文本流开头的字符计数，如下所示。

文本范围和选择

文本范围和选择由 CoreTextRange 结构表示，其中包含两个字段：

字段	数据类型	描述
StartCaretPosition	Number [JavaScript] | System.Int32 [.NET] | int32 [C++]	范围的起始位置是紧邻第一个字符之前的 ACP。
EndCaretPosition	Number [JavaScript] | System.Int32 [.NET] | int32 [C++]	范围的结束位置是紧接在最后一个字符之后的 ACP。

 

例如，在前面显示的文本范围中，范围 [0, 5] 可指定单词 “Hello”。 StartCaretPosition 必须始终小于或等于 EndCaretPosition。 范围 [5, 0] 无效。

插入点

当前插入点（通常称为插入点）通过将 StartCaretPosition 设置为等于 EndCaretPosition 来表示。

非连续选择

某些编辑控件支持非连续选择。 例如，Microsoft 办公室应用支持多个任意选择，许多源代码编辑器支持列选择。 但是，核心文本 API 并不支持非连续选择。 编辑控件必须仅报告单个连续选择，通常是非连续选择的活动子范围。

例如，下图显示了包含两个非连续选择的文本流：[0, 1] 和 [6, 11]，编辑控件只能针对其中一个报告（[0, 1] 或 [6, 11]）。

使用文本

CoreTextEditContext 类允许 Windows 之间的文本流，并通过 TextUpdating 事件、TextRequested 事件和 NotifyTextChanged 方法编辑控件。

编辑控件通过 TextUpdating 事件接收文本，这些事件是在用户与键盘、语音或 IME 等文本输入方法交互时生成的。

更改编辑控件中的文本（例如，通过将文本粘贴到控件中）时，需要通过调用 NotifyTextChanged 通知 Windows。

如果文本服务需要新文本，则会 引发 TextRequested 事件。 必须在 TextRequested 事件处理程序中提供新文本。

接受文本更新

编辑控件通常应接受文本更新请求，因为它们表示用户想要输入的文本。 在 TextUpdating 事件处理程序中，这些操作需要编辑控件：

1. 在 CoreTextTextUpdatingEventArgs.Text 中指定的位置插入 CoreTextTextUpdatingEventArgs.Range 中指定的文本。
2. 将所选内容置于 CoreTextTextUpdatingEventArgs.NewSelection 中指定的位置。
3. 通过将 CoreTextTextUpdatingEventArgs.Result 设置为 CoreTextTextUpdatingResult.Succeeded，通知系统更新成功。

例如，这是用户键入“d”之前编辑控件的状态。 该插入点位于 [10, 10]。

当用户键入“d”时，将引发 TextUpdating 事件并带有以下 CoreTextTextUpdatingEventArgs 数据：

• Range = [10, 10]
• Text = “d”
• NewSelection = [11, 11]

在编辑控件中，应用指定的更改并将结果设置为“成功”。 下面是应用更改后控件的状态。

拒绝文本更新

有时，无法应用文本更新，因为请求的范围位于不应更改的编辑控件区域中。 在这种情况下，不应应用任何更改。 相反，通过将 CoreTextTextUpdatingEventArgs.Result 设置为 CoreTextTextUpdatingResult.Failed，通知系统更新失败。

例如，请考虑仅接受电子邮件地址的编辑控件。 应拒绝空格，因为电子邮件地址不能包含空格，因此，当为空间键引发 TextUpdating 事件时，应该在编辑控件中将结果设置为“失败”。

通知文本更改

有时，编辑控件会更改文本，例如文本粘贴或自动更正的时间。 在这些情况下，必须通过调用 NotifyTextChanged 方法通知文本服务这些更改。

例如，这是用户粘贴“World”之前编辑控件的状态。 该插入点位于 [6, 6]。

应用更改后，用户执行粘贴操作并编辑控件：

当发生此情况时，应调用带有以下参数的 NotifyTextChanged：

• modifiedRange = [6, 6]
• newLength = 5
• newSelection = [11, 11]

将遵循一个或多个 TextRequested 事件，你处理这些事件以更新文本服务正在使用的文本。

重写文本更新

在编辑控件中，你可能想要重写文本更新以提供自动更正功能。

例如，请考虑一个编辑控件，该控件提供正式化收缩的更正功能。 这是用户键入用于触发更正的空间键之前编辑控件的状态。 该插入点位于 [3, 3]。

用户按空格键，将引发相应的 TextUpdating 事件。 编辑控件接受文本更新。 这是编辑控件在完成更正前的短暂状态。 该插入点位于 \[4, 4\]。

在 TextUpdating 事件处理程序之外，编辑控件将进行以下更正。 这是更正完成后编辑控件的状态。 该插入点位于 [5, 5]。

当发生此情况时，应调用带有以下参数的 NotifyTextChanged：

• modifiedRange = [1, 2]
• newLength = 2
• newSelection = [5, 5]

将遵循一个或多个 TextRequested 事件，你处理这些事件以更新文本服务正在使用的文本。

提供请求的文本

文本服务必须具有正确的文本来提供自动更正或预测等功能，尤其是对于编辑控件中已存在的文本，从加载文档（例如）或编辑控件插入的文本（如上一节中所述）。 因此，每当 引发 TextRequested 事件时，都必须为指定的范围提供当前编辑控件中的文本。

CoreTextTextRequest 中的 Range 将指定编辑控件无法按原样容纳的范围。 例如，Range 大于 TextRequested 事件时编辑控件的大小，或者 Range 的末尾超出边界。 在这些情况下，应返回任何有意义的范围，这通常是所请求范围的子集。

相关文章

示例

• 自定义编辑控件示例

存档示例

• XAML 文本编辑示例