识别用户的手写内容

借助手写识别 API,您可以在手写输入中实时识别文字。

什么是手写识别 API?

借助手写识别 API,您可以将用户的手写内容(手写)转换为文本。某些操作系统早已包含此类 API,借助这项新功能,您的 Web 应用终于可以使用此功能了。转化会直接在用户设备上进行,即使在离线模式下也能正常运行,而无需添加任何第三方库或服务。

此 API 实现了所谓的“在线”或近乎实时的识别。这意味着,系统会在用户绘制手写内容时捕获和分析单个笔触,从而识别手写输入内容。与光学字符识别 (OCR) 等“离线”流程(其中仅知道最终产品)相比,在线算法可以提供更高的精确度,因为它们会利用其他信号(例如单个墨水笔画的时间顺序和压力)来进行处理。

Handwriting Recognition API 的建议用例

用例示例包括:

  • 记事应用,用户希望捕获手写记事并将其转换为文本。
  • 表单应用,用户可以因时间限制而使用触控笔或手指输入。
  • 需要填写字母或数字的游戏,例如填字游戏、猜谜游戏或数独游戏。

当前状态

手写识别 API 从 (Chromium 99) 开始提供。

如何使用手写识别 API

功能检测

通过检查导航器对象上是否存在 createHandwritingRecognizer() 方法来检测浏览器支持情况:

if ('createHandwritingRecognizer' in navigator) {
  // 🎉 The Handwriting Recognition API is supported!
}

核心概念

无论输入方式(鼠标、触控、触控笔)如何,手写识别 API 都可以将手写输入转换为文本。该 API 包含四个主要实体:

  1. 表示指针在特定时间的位置。
  2. 笔触由一个或多个点组成。当用户放下指针(即点击鼠标主按钮,或者用钢笔/手指轻触屏幕)时,开始记录笔画,并在用户再次抬起指针时结束笔触记录。
  3. 绘制由一个或多个笔画组成。实际识别发生在此级别。
  4. 识别器已配置为使用预期的输入语言。它用于创建应用了识别器配置的绘图实例。

这些概念会以特定接口和字典的形式实现,我很快就会介绍。

手写识别 API 的核心实体:一个或多个点组成笔画,一个或多个笔画组成绘图,由识别程序创建。实际识别是在绘图级别进行的。

创建识别器

如需识别手写输入的文本,您需要通过调用 navigator.createHandwritingRecognizer() 并向其传递约束条件来获取 HandwritingRecognizer 的实例。约束条件决定了应使用的手写识别模型。目前,您可以按偏好顺序指定语言列表:

const recognizer = await navigator.createHandwritingRecognizer({
  languages: ['en'],
});

当浏览器可以执行您的请求时,该方法会返回一个 promise,由 HandwritingRecognizer 实例进行解析。否则,它会拒绝该 promise 并返回错误,并且手写识别功能将不可用。因此,您可能需要先查询识别器对特定识别功能的支持情况。

查询识别器支持

通过调用 navigator.queryHandwritingRecognizerSupport(),您可以检查目标平台是否支持您打算使用的手写识别功能。在以下示例中,开发者:

  • 想要检测英语文本
  • 获取可能性较低的备选预测结果(如果有)
  • 访问分割结果,即识别出的字符,包括构成这些字符的点和笔画
const { languages, alternatives, segmentationResults } =
  await navigator.queryHandwritingRecognizerSupport({
    languages: ['en'],
    alternatives: true,
    segmentationResult: true,
  });

console.log(languages); // true or false
console.log(alternatives); // true or false
console.log(segmentationResult); // true or false

该方法会返回一个 promise,由结果对象解析。如果浏览器支持开发者指定的功能,则其值将设置为 true。否则,该值将设置为 false。您可以使用这些信息在应用中启用或停用某些功能,或者调整查询并发送新的查询。

开始绘图

在应用中,您应提供一个输入区域,供用户进行手写输入。出于性能方面的原因,建议您借助画布对象来实现此操作。本文不涉及此部分的确切实现,但您可以参阅演示,了解具体实现方式。

如需开始新绘制,请对识别器调用 startDrawing() 方法。此方法接受包含不同提示的对象,以微调识别算法。所有提示均为选填:

  • 输入的文本类型:文本、电子邮件地址、数字或单个字符 (recognitionType)
  • 输入设备的类型:鼠标、触控或触控笔输入 (inputType)
  • 前文 (textContext)
  • 应返回的概率更低的替代预测数量 (alternatives)
  • 用户最有可能输入的用户可识别字符(“字形”)的列表 (graphemeSet)

手写识别 API 与指针事件配合使用效果非常好,指针事件提供了一个抽象接口,用于使用来自任何指针设备的输入。指针事件参数包含所用指针的类型。这意味着,您可以使用指针事件自动确定输入类型。在以下示例中,当手写区域上首次发生 pointerdown 事件时,系统会自动创建用于手写识别的绘制操作。由于 pointerType 可能为空或设为专有值,因此我引入了一致性检查,以确保仅为绘图的输入类型设置受支持的值。

let drawing;
let activeStroke;

canvas.addEventListener('pointerdown', (event) => {
  if (!drawing) {
    drawing = recognizer.startDrawing({
      recognitionType: 'text', // email, number, per-character
      inputType: ['mouse', 'touch', 'pen'].find((type) => type === event.pointerType),
      textContext: 'Hello, ',
      alternatives: 2,
      graphemeSet: ['f', 'i', 'z', 'b', 'u'], // for a fizz buzz entry form
    });
  }
  startStroke(event);
});

添加描边

pointerdown 事件也是开始新笔触的合适位置。为此,请创建一个新的 HandwritingStroke 实例。此外,您应将当前时间存储为添加到其后的点的参考点:

function startStroke(event) {
  activeStroke = {
    stroke: new HandwritingStroke(),
    startTime: Date.now(),
  };
  addPoint(event);
}

添加一个点

创建笔触后,您应直接向其添加第一个点。由于您稍后还会添加更多积分,因此最好在单独的方法中实现积分创建逻辑。在以下示例中,addPoint() 方法根据参考时间戳计算已用时间。时间信息是可选的,但可以提高识别质量。然后,它会从指针事件中读取 X 和 Y 坐标,并将相应点添加到当前描边。

function addPoint(event) {
  const timeElapsed = Date.now() - activeStroke.startTime;
  activeStroke.stroke.addPoint({
    x: event.offsetX,
    y: event.offsetY,
    t: timeElapsed,
  });
}

当指针在屏幕上移动时,系统会调用 pointermove 事件处理脚本。这些点也需要添加到描边中。如果指针未处于“按下”状态,例如在未按下鼠标按钮的情况下在屏幕上移动光标时,系统也可能会触发此事件。以下示例中的事件处理脚本会检查是否存在有效的笔触,并向其添加新点。

canvas.addEventListener('pointermove', (event) => {
  if (activeStroke) {
    addPoint(event);
  }
});

识别文字

当用户再次抬起指针时,您可以通过调用其 addStroke() 方法将笔触添加到绘制内容中。以下示例还会重置 activeStroke,因此 pointermove 处理脚本不会向已完成的笔画添加点。

接下来,是时候通过对绘图调用 getPrediction() 方法来识别用户的输入了。识别过程通常不到几百毫秒,因此您可以根据需要重复运行预测。以下示例会在每次完成笔画后运行新的预测。

canvas.addEventListener('pointerup', async (event) => {
  drawing.addStroke(activeStroke.stroke);
  activeStroke = null;

  const [mostLikelyPrediction, ...lessLikelyAlternatives] = await drawing.getPrediction();
  if (mostLikelyPrediction) {
    console.log(mostLikelyPrediction.text);
  }
  lessLikelyAlternatives?.forEach((alternative) => console.log(alternative.text));
});

此方法会返回一个 promise,并通过一组按概率排序的预测结果进行解析。元素数量取决于您传递给 alternatives 提示的值。您可以使用此数组向用户显示可能的匹配选项,并让用户选择一个选项。或者,您也可以直接使用最有可能的预测,就像我在本示例中所做的那样。

预测对象包含识别出的文本和可选的分段结果,我将在下一部分中对此进行讨论。

包含细分结果的详细数据分析

如果目标平台支持,则预测对象还可以包含细分结果。这是一个包含所有已识别的手写区段的数组,其中包含识别出的用户可识别字符 (grapheme) 及其在识别出的文本中的位置 (beginIndex, endIndex) 以及创建该手写区的笔画和点。

if (mostLikelyPrediction.segmentationResult) {
  mostLikelyPrediction.segmentationResult.forEach(
    ({ grapheme, beginIndex, endIndex, drawingSegments }) => {
      console.log(grapheme, beginIndex, endIndex);
      drawingSegments.forEach(({ strokeIndex, beginPointIndex, endPointIndex }) => {
        console.log(strokeIndex, beginPointIndex, endPointIndex);
      });
    },
  );
}

您可以使用这些信息再次跟踪画布上识别出的字符图元。

系统会在每个识别出的字符周围绘制方框

完成识别

完成识别后,您可以通过对 HandwritingDrawing 调用 clear() 方法并在 HandwritingRecognizer 上调用 finish() 方法释放资源:

drawing.clear();
recognizer.finish();

演示

网络组件 <handwriting-textarea> 实现了可识别手写内容的逐步增强型编辑控件。点击编辑控件右下角的按钮,即可启用绘制模式。当您完成绘制后,Web 组件会自动开始识别,并将识别出的内容添加回编辑控件。如果系统完全不支持手写识别 API,或者平台不支持请求的功能,系统会隐藏“修改”按钮。但基本编辑控件仍可用作 <textarea>

Web 组件提供了用于从外部定义识别行为的属性,包括 languagesrecognitiontype。您可以通过 value 属性设置控件的内容:

<handwriting-textarea languages="en" recognitiontype="text" value="Hello"></handwriting-textarea>

如需了解该值的任何更改,您可以监听 input 事件。

您可以使用 Glitch 上的此演示试用该组件。此外,请务必查看源代码。如需在应用中使用该控件,请从 npm 获取该控件

安全与权限

Chromium 团队根据控制对强大的 Web 平台功能的访问权限(包括用户控制、透明度和人体工程学)中定义的核心原则设计和实现了手写识别 API。

用户控制

用户无法关闭手写识别 API。此 API 仅适用于通过 HTTPS 提供的网站,并且只能从顶级浏览上下文调用。

透明度

系统不会指明手写识别功能是否处于启用状态。为了防止数字“指纹”收集,浏览器会采取相应对策,例如在检测到可能的滥用行为时向用户显示权限提示。

权限持久性

手写识别 API 目前不会显示任何权限提示。因此,无需以任何方式保留权限。

反馈

Chromium 团队希望了解您使用 Handwriting Recognition API 的体验。

请向我们说明 API 设计

API 是否存在某些方面未按预期运行?或者,您是否缺少实现想法所需的方法或属性?对安全模型有疑问或意见?在相应的 GitHub 代码库中提交规范问题,或在现有问题中添加您的想法。

报告实现方面的问题

您是否发现了 Chromium 实现方面的错误?或者实现方式是否与规范不同? 在 new.crbug.com 上提交 bug。请务必提供尽可能多的详情以及有关重现的简单说明,并在组件框中输入 Blink>HandwritingGlitch 非常适用于分享轻松快速的重现问题。

表示对 API 的支持

您打算使用手写识别 API 吗?您的公开支持有助于 Chromium 团队确定功能的优先级,并向其他浏览器供应商表明支持这些功能的重要性。

WICG Discourse 会话中分享您打算如何使用该工具。使用 # 标签 #HandwritingRecognition@ChromiumDev 发送一条推文,告诉我们您在何处以及如何使用它。

致谢

本文档由 Joe Medley、Honglin Yu 和 Jiewei Qian 审核。