EditContext API

概念

在应用程序的可编辑区域中输入文本时，会涉及多个参与者。

用户

用户通过输入法提供文本：键盘、鼠标、语音或其他输入法。

输入法软件

输入法软件将用户的输入转换为文本。例如，这可能是一个 输入法编辑器 (IME)，它将标准键盘的击键转换为日语、中文或韩语字符。

操作系统文本输入服务

操作系统的文本输入服务充当输入法软件和应用程序之间的链接。

应用程序文本编辑上下文

应用程序文本编辑上下文提供了正在编辑的文本的状态。该状态包含文本本身、当前选定范围、文本在应用程序 UI 中的位置等信息。

应用程序可编辑区域

应用程序可编辑区域是应用程序中显示文本的 UI 元素。

虽然前三个参与者由操作系统提供，但应用程序负责提供可编辑区域和文本编辑上下文。

在 Web 上，可编辑区域通常是 <textarea> 元素、<input> 元素，或将 contenteditable 属性设置为 true 的元素。对于这些元素，浏览器会自动提供文本编辑上下文，Web 作者无需编写任何代码来支持文本输入。

创建自定义可编辑区域

Web 作者还可以使用 EditContext API 创建自定义可编辑区域。例如，Web 作者可以使用 <canvas> 元素来渲染文本，从而创建一个富文本编辑器。在这种情况下，Web 作者需要编写代码来支持文本输入。

作者的职责

如果您决定实现自己的可编辑区域，无论是将文本绘制到 <canvas> 中还是将其渲染到一系列 DOM 元素中，您都将负责提供通常情况下如果使用 <textarea> 而不是自定义区域，浏览器会为您提供的功能。这包括：

• 渲染文本。
• 渲染选定范围（如果您使用 DOM 元素而不是 <canvas> 来构建可编辑区域，则浏览器会为您渲染选定范围）。
• 在选定范围更改时通知操作系统文本输入服务。
• 告知操作系统文本输入服务文本在 UI 中的位置，以便输入法软件可以在正确的位置显示 IME 组合窗口。
• 在用户在 IME 组合窗口中组合文本时应用某些文本格式。

作为回报，EditContext API 会使您选择的 DOM 元素成为可编辑的，并将其纳入文档的焦点顺序。此外，EditContext API 还提供有关正在编辑的文本状态的信息，这允许您以自定义方式渲染它。提供给您的信息包括：

• 当前文本内容。
• 当前选定范围。
• IME 组合是否正在进行，以及是否需要应用文本格式。

无障碍

如果您将 EditContext API 与 <canvas> 元素一起使用，请确保文本也对辅助技术可访问。屏幕阅读器无法读取 <canvas> 元素中的文本。例如，您可以维护一个位于屏幕外 DOM 元素中的文本的单独视图，该视图会呈现给屏幕阅读器。

基本用法

要使用 EditContext API，您需要创建一个 EditContext 接口的实例，然后使用 editContext 属性将其附加到您想要使其可编辑的 DOM 元素上。DOM 元素可以是任何元素，包括 <div> 或 <canvas> 元素。

<canvas id="editor-canvas"></canvas>

const canvas = document.getElementById("editor-canvas");
const editContext = new EditContext();
canvas.editContext = editContext;

一个 EditContext 实例一次只能附加到一个 DOM 元素。

将 EditContext 实例附加到 DOM 元素会使其成为可聚焦的，并成为文档焦点顺序的一部分。用户可以使用他们选择的输入法向该元素输入文本，您可以使用 EditContext 实例触发的事件来渲染文本和选定范围。

模型和视图架构

使用 EditContext API 时，将其编辑体验构建为模型和视图架构会有所帮助。

EditContext 实例代表您可编辑区域的模型。当接收到文本输入或选定范围更改时，其内部状态会更新。

然后，您可以使用 EditContext 实例提供的信息在视图中渲染文本和选定范围，但您的视图不需要与模型完全匹配。您可以自由地以任何您想要的方式渲染文本。

接口

EditContext 实验性

EditContext 接口是对文本编辑上下文的 JavaScript 反射，该上下文在使​​用 textarea 等标准可编辑区域时通常由浏览器透明地提供。EditContext 提供了正在编辑的文本的状态，其中包含文本本身、当前选定范围或文本在应用程序 UI 中的位置等信息。

TextFormat 实验性

当用户在 IME 组合窗口中组合文本时，TextFormat 接口用于表示应应用于文本范围的特定格式。

TextUpdateEvent 实验性

TextUpdateEvent 接口是一个 DOM 事件，表示附加到 EditContext 实例的可编辑文本区域中的文本或选定范围的更新。

TextFormatUpdateEvent 实验性

TextFormatUpdateEvent 接口是一个 DOM 事件，表示一个 输入法编辑器 (IME) 窗口希望应用于附加到 EditContext 实例的可编辑区域中正在组合的文本的文本格式列表。

CharacterBoundsUpdateEvent 实验性

CharacterBoundsUpdateEvent 接口是一个 DOM 事件，表示来自操作系统的请求，要求了解附加到 EditContext 实例的可编辑区域中特定字符的边界。

其他接口的扩展

HTMLElement.editContext 实验性

HTMLElement 接口的 editContext 属性获取和设置元素的关联 EditContext 对象。

规范

浏览器兼容性

另见

• 使用 EditContext API