EditContext：updateCharacterBounds() 方法

有限可用性

此功能不是基线功能，因为它在一些最广泛使用的浏览器中无法正常工作。

实验性： 这是一个实验性技术
在生产环境中使用此功能之前，请仔细查看浏览器兼容性表格。

EditContext 接口的 EditContext.updateCharacterBounds() 方法应作为对 characterboundsupdate 事件的响应进行调用，以告知操作系统 EditContext 对象中字符的位置和大小。

characterboundsupdate 事件是您需要调用 updateCharacterBounds() 方法的唯一时间。

然后，操作系统会使用字符边界信息在需要时正确放置输入法编辑器 (IME) 窗口。这在操作系统无法自动检测字符的位置和大小的情况下尤其重要，例如在 <canvas> 元素中呈现文本时。

避免 IME 窗口位置突然跳动

在 characterboundsupdate 事件中同步计算字符边界并调用 updateCharacterBounds，可确保操作系统在显示 IME 窗口时拥有所需的信息。如果您没有在事件处理程序中同步调用 updateCharacterBounds()，则用户可能会观察到 IME 窗口在移动到正确位置之前显示在错误的位置。

包含哪些字符

仅当操作系统指示需要该信息时，并且仅对当前 IME 组合中包含的字符调用 updateCharacterBounds() 方法。

传递给 characterboundsupdate 事件处理程序的事件对象包含 rangeStart 和 rangeEnd 属性，它们指示当前正在组合的字符范围。updateCharacterBounds() 方法应仅对该范围内的字符调用。

语法

updateCharacterBounds(rangeStart, characterBounds)

参数

rangeStart: 表示提供字符边界的文本范围的起始位置的数字。
characterBounds: 一个包含 Array 对象的 DOMRect，表示字符边界。

异常

如果提供的参数少于两个，则会抛出 TypeError DOMException。
如果 rangeStart 不是数字或 characterBounds 不可迭代，则会抛出 TypeError DOMException。

示例

在需要时更新字符边界

此示例演示了如何在操作系统指示需要该信息时，使用 updateCharacterBounds 方法更新 <canvas> 元素的 EditContext 中的字符边界。请注意，此示例中的 characterboundsupdate 事件侦听器回调仅在使用 IME 窗口或其他特定于平台的编辑 UI 表面来组合文本时才会被调用。

html

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

const FONT_SIZE = 40;
const FONT = `${FONT_SIZE}px Arial`;

const canvas = document.getElementById("editor-canvas");
const ctx = canvas.getContext("2d");
ctx.font = FONT;

const editContext = new EditContext();
canvas.editContext = editContext;

function computeCharacterBound(offset) {
  // Measure the width from the start of the text to the character.
  const widthBeforeChar = ctx.measureText(
    editContext.text.substring(0, offset),
  ).width;

  // Measure the character width.
  const charWidth = ctx.measureText(editContext.text[offset]).width;

  const charX = canvas.offsetLeft + widthBeforeChar;
  const charY = canvas.offsetTop;

  // Return a DOMRect representing the character bounds.
  return DOMRect.fromRect({
    x: charX,
    y: charY - FONT_SIZE,
    width: charWidth,
    height: FONT_SIZE,
  });
}

editContext.addEventListener("characterboundsupdate", (e) => {
  const charBounds = [];
  for (let offset = e.rangeStart; offset < e.rangeEnd; offset++) {
    charBounds.push(computeCharacterBound(offset));
  }

  editContext.updateCharacterBounds(e.rangeStart, charBounds);
});

规范

规范
EditContext API # dom-editcontext-updatecharacterbounds

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅

它所属的 EditContext 接口。