大网数据广告活动
Web 标准与前端开发

EditContext: updateCharacterBounds() method

· 52CE 我爱测

The **`EditContext.updateCharacterBounds()`** method of the EditContext interface should be called as response to a EditContext.characterboundsupdate_event event to inform the operating system about the position and size of the characters in the `EditContext` object.

EditContext API

The EditContext.updateCharacterBounds() method of the EditContext interface should be called as response to a EditContext.characterboundsupdate_event event to inform the operating system about the position and size of the characters in the EditContext object.

The characterboundsupdate event is the only time you need to call the updateCharacterBounds() method.

The character bounds information is then used by the operating system to correctly position the Input Method Editor (IME) window when needed. This is especially important in situations where the operating system can't automatically detect the position and size of the characters, such as when rendering text in a <canvas> element.

Syntax

updateCharacterBounds(rangeStart, characterBounds)

Parameters

  • rangeStart
    • : A number representing the start of the range of text for which character bounds are provided.
  • characterBounds
    • : An Array containing DOMRect objects representing the character bounds.

Return value

None (undefined).

Exceptions

  • TypeError
    • : Thrown if the method is called with less than two arguments, or if the first argument is not a number or the second argument is not an iterable (like an array).

Usage notes

Avoid sudden jumps in the IME window position

Calculating the character bounds and calling updateCharacterBounds synchronously, within the characterboundsupdate event ensures that the operating system has the information it needs when it displays the IME window. If you don't call updateCharacterBounds() synchronously within the event handler, users may observe the IME window being displayed in the wrong position before being moved to the correct position.

Which characters to include

The updateCharacterBounds() method should only be called when the operating system indicates that it requires the information, and only for the characters that are included in the current IME composition.

The event object passed to the characterboundsupdate event handler contains a rangeStart and rangeEnd properties that indicate the range of characters that are currently being composed. The updateCharacterBounds() method should only be called for the characters in this range.

Examples

Updating the character bounds when needed

This example shows how to use the updateCharacterBounds method to update the character bounds in the EditContext of a <canvas> element when the operating system indicates that it requires the information. Note that the characterboundsupdate event listener callback in this example is only called when using an IME window, or other platform-specific editing UI surfaces, to compose text.

<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);
});

Specifications

Browser compatibility

See also

  • The EditContext interface it belongs to.

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。