Skip to content

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.

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.mdx
index 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 a
Chinese/Japanese/Korean composition renders **live in the field** (the preedit
string 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 the
diff --git a/sdk/src/ui/text/text-input-plugin.ts b/sdk/src/ui/text/text-input-plugin.ts
index 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.ts
index 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): n
return 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.ts
index 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 });
+ });
+});