A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(ui): anchor the IME textarea at the caret so the candidate window pops there
yhh48af373ad1b1
diff --git a/docs/astro/src/content/docs/guides/ui-components.mdx b/docs/astro/src/content/docs/guides/ui-components.mdxindex 6abf1f65a..0e45c5cd4 100644--- a/docs/astro/src/content/docs/guides/ui-components.mdx+++ b/docs/astro/src/content/docs/guides/ui-components.mdx@@ -350,7 +350,9 @@ always matches what a native input would do.**IME / CJK input** works: the field drives a hidden native `<textarea>`, so aChinese/Japanese/Korean composition renders **live in the field** (the preeditstring shows at the caret as you type) and only fires `change` once the-composition commits — the same behavior as a native input.+composition commits — the same behavior as a native input. The textarea tracks+the caret's on-screen position, so the OS **candidate window pops up at the+caret**, not in a screen corner.A **`multiline`** field (Enter inserts a newline) stacks its lines from the top;the caret position, click-to-place and within-line selection track thediff --git a/sdk/src/ui/text/text-input-plugin.ts b/sdk/src/ui/text/text-input-plugin.tsindex 6feec7cd9..106cfe0e9 100644--- a/sdk/src/ui/text/text-input-plugin.ts+++ b/sdk/src/ui/text/text-input-plugin.ts@@ -24,8 +24,10 @@ import { SdfTextRenderer } from './text-renderer';import { measureWidth } from './layout';import {textFieldDisplay, maskedPrefix, fieldSelection, nearestCaretIndex,- splitLines, caretLineCol, lineSelections, type TextFieldDisplay,+ splitLines, caretLineCol, lineSelections, imeAnchorCss, type TextFieldDisplay,} from './text-input-view';+import { uiWorldToScreen } from '../util/ui-pick';+import { platformDevicePixelRatio } from '../../platform';import { CURSOR_BLINK_INTERVAL, TEXT_INPUT_LINE_HEIGHT_RATIO } from '../util/constants';import { SystemLabel, PluginName } from '../../systemLabels';import { log } from '../../logger';@@ -275,6 +277,33 @@ export class TextInputPlugin implements Plugin {textarea.blur();}+ /** Park the hidden textarea off-screen (no field focused). */+ function parkTextarea(): void {+ if (textarea.style.left !== '-9999px') {+ textarea.style.left = '-9999px';+ textarea.style.top = '-9999px';+ }+ }++ /** Move the hidden textarea onto the caret's on-screen position so the OS+ * IME candidate window pops just under the caret, not at the screen+ * corner. `caretBottom` is the caret's bottom edge in field-local px+ * (y-down from the box top). */+ function positionTextareaAtCaret(entity: Entity, caretX: number, caretBottom: number): void {+ const cam = app.getResource(UICameraInfo) as UICameraData | undefined;+ if (!cam || !cam.valid || !world.has(entity, Transform)) return;+ const tr = world.get(entity, Transform) as TransformData;+ const w = getUINodeWidth(entity);+ const h = getUINodeHeight(entity);+ // Box is centered on its Transform (pivot 0.5): left/top edges from it.+ const worldX = (tr.worldPosition.x - w / 2) + caretX;+ const worldY = (tr.worldPosition.y + h / 2) - caretBottom; // world y-up+ const scr = uiWorldToScreen(cam, worldX, worldY);+ const css = imeAnchorCss(scr.x, scr.y, cam.screenH, platformDevicePixelRatio());+ textarea.style.left = Math.round(css.left) + 'px';+ textarea.style.top = Math.round(css.top) + 'px';+ }+function resetCursorBlink(): void {cursorVisible = true;cursorTimer = 0;@@ -349,6 +378,8 @@ export class TextInputPlugin implements Plugin {cursorTimer -= CURSOR_BLINK_INTERVAL;cursorVisible = !cursorVisible;}+ } else {+ parkTextarea();}// Reap the child entities of removed inputs.@@ -435,6 +466,13 @@ export class TextInputPlugin implements Plugin {syncTextChild(ch.text, ti, disp, innerW, scrollX);// The blinking caret hides while a highlight is drawn.syncCaretChild(ch.caret, ti, caretX, caretTop, ti.focused && cursorVisible && !sshow);++ // Anchor the hidden textarea at the caret so the IME candidate+ // window pops there. Not while composing — moving it mid-+ // composition would yank an open candidate window.+ if (editing && !composing) {+ positionTextareaAtCaret(entity, caretX, caretTop + ti.fontSize);+ }}},{ name: 'TextInputRenderSystem' }@@ -571,12 +609,18 @@ function createHiddenTextarea(): HTMLTextAreaElement | null {}const textarea = document.createElement('textarea');textarea.style.position = 'fixed';+ // Parked off-screen until a field focuses, then moved to the caret so the IME+ // candidate window anchors there (see positionTextareaAtCaret). Invisible and+ // click-through so the on-screen textarea never shows or steals a pointer.textarea.style.left = '-9999px';textarea.style.top = '-9999px';textarea.style.width = '1px';textarea.style.height = '1px';textarea.style.opacity = '0';textarea.style.zIndex = '-1';+ textarea.style.pointerEvents = 'none';+ textarea.style.border = '0';+ textarea.style.padding = '0';textarea.autocomplete = 'off';textarea.setAttribute('autocorrect', 'off');textarea.setAttribute('autocapitalize', 'off');diff --git a/sdk/src/ui/text/text-input-view.ts b/sdk/src/ui/text/text-input-view.tsindex 0c8a35a38..aac5b64fb 100644--- a/sdk/src/ui/text/text-input-view.ts+++ b/sdk/src/ui/text/text-input-view.ts@@ -88,6 +88,16 @@ export function nearestCaretIndex(prefixWidths: readonly number[], x: number): nreturn best;}+/** Convert an on-screen point — device px, GL bottom-up, the space the UI+ * hit-test / camera use — into CSS pixels (top-down) for positioning the hidden+ * IME `<textarea>` so the OS candidate window anchors at the caret instead of+ * the screen corner. Inverse of the hit-test's `mouseX*dpr`, `screenH −+ * mouseY*dpr`. Pure. */+export function imeAnchorCss(screenX: number, screenY: number, screenH: number, dpr: number): { left: number; top: number } {+ const d = dpr > 0 ? dpr : 1;+ return { left: screenX / d, top: (screenH - screenY) / d };+}+/** A visual line of a multiline value: its text (no trailing `\n`) and the* index in the full value where it starts. */export interface VisualLine {diff --git a/sdk/tests/ui-text-input-view.test.ts b/sdk/tests/ui-text-input-view.test.tsindex 0cbb31264..ce657806d 100644--- a/sdk/tests/ui-text-input-view.test.ts+++ b/sdk/tests/ui-text-input-view.test.ts@@ -12,7 +12,7 @@import { describe, it, expect } from 'vitest';import {textFieldDisplay, maskedPrefix, fieldSelection, nearestCaretIndex,- splitLines, caretLineCol, lineSelections,+ splitLines, caretLineCol, lineSelections, imeAnchorCss,} from '../src/ui/text/text-input-view';const BULLET = '●';@@ -167,3 +167,26 @@ describe('lineSelections', () => {expect(lineSelections('abc', 2, 2)).toEqual([]);});});++describe('imeAnchorCss', () => {+ it('flips GL bottom-up device px into top-down CSS px (dpr 1)', () => {+ // screenH 600, a point 100px up from the bottom → 500px down from the top.+ expect(imeAnchorCss(200, 100, 600, 1)).toEqual({ left: 200, top: 500 });+ });++ it('divides by the device pixel ratio', () => {+ expect(imeAnchorCss(400, 200, 1200, 2)).toEqual({ left: 200, top: 500 });+ });++ it('is the exact inverse of the hit-test mapping (mouseX*dpr, screenH − mouseY*dpr)', () => {+ const cssX = 137, cssY = 88, screenH = 600, dpr = 1.5;+ const glX = cssX * dpr, glY = screenH - cssY * dpr;+ const back = imeAnchorCss(glX, glY, screenH, dpr);+ expect(back.left).toBeCloseTo(cssX, 6);+ expect(back.top).toBeCloseTo(cssY, 6);+ });++ it('guards a zero dpr', () => {+ expect(imeAnchorCss(200, 100, 600, 0)).toEqual({ left: 200, top: 500 });+ });+});