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(cocos): EditBox is a component over the platform text editor (mode and length rules, hint, password bullets, the four editing events), and the importer maps it

yhha66980ab42b2
diff --git a/pipeline/src/import/cocos/components.ts b/pipeline/src/import/cocos/components.ts
index 7aaf83315..5bcb125a4 100644
--- a/pipeline/src/import/cocos/components.ts
+++ b/pipeline/src/import/cocos/components.ts
@@ -638,6 +638,23 @@ function graphics(c: CocosComponent): ComponentData {
};
}
+/** `cc.EditBox`: the box and its two labels are the scene's own nodes; what is typed goes through the platform's text editor. */
+function editBox(c: CocosComponent, ctx: ComponentContext): ComponentData {
+ return {
+ type: `${LAYER}EditBox`,
+ data: {
+ ...renamed(c, {
+ _string: 'string_', _maxLength: 'maxLength', _inputMode: 'inputMode', _inputFlag: 'inputFlag', _returnType: 'returnType', _tabIndex: 'tabIndex',
+ _textLabel: 'textLabel', _placeholderLabel: 'placeholderLabel',
+ }),
+ ...handlerLists(c.data.editingDidBegan, 'editingDidBegan', ctx),
+ ...handlerLists(c.data.textChanged, 'textChanged', ctx),
+ ...handlerLists(c.data.editingDidEnded, 'editingDidEnded', ctx),
+ ...handlerLists(c.data.editingReturn, 'editingReturn', ctx),
+ },
+ };
+}
+
/** `cc.UIOpacity`: the alpha of the node and everything under it, which the engine's GroupOpacity is. */
function uiOpacity(c: CocosComponent, ctx: ComponentContext): ComponentData {
ctx.report.component('cc.UIOpacity', 'mapped');
@@ -761,6 +778,9 @@ export function convertNode(node: CocosNode, ctx: ComponentContext, where: strin
case 'cc.SkeletalAnimation':
out = skeletalAnimation(c, node, ctx, where);
break;
+ case 'cc.EditBox':
+ out = editBox(c, ctx);
+ break;
case 'cc.Graphics':
out = graphics(c);
break;
diff --git a/sdk/src/cocos/index.ts b/sdk/src/cocos/index.ts
index b5f2b555f..8431b25c4 100644
--- a/sdk/src/cocos/index.ts
+++ b/sdk/src/cocos/index.ts
@@ -26,7 +26,7 @@ export {
AnimationClip, SceneAsset, EffectAsset, Mesh,
} from './assets';
export { registerBuiltinComponent, type BuiltinAdapter } from './builtins';
-export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Button, EventHandler, Widget, Layout, Camera, RichText, Mask, Toggle, ToggleContainer, ProgressBar, Slider, BlockInputEvents, ScrollView, Graphics, getVisibleSize, setVisibleSize } from './ui';
+export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Button, EventHandler, Widget, Layout, Camera, RichText, Mask, Toggle, ToggleContainer, ProgressBar, Slider, BlockInputEvents, ScrollView, Graphics, EditBox, getVisibleSize, setVisibleSize } from './ui';
export { Touch, EventTouch } from './input';
export { tween, Tween, tweenUtil, easing, updateTweens } from './tween';
export { instantiate, loadPrefab, providePrefab } from './prefabs';
diff --git a/sdk/src/cocos/ui/editBox.ts b/sdk/src/cocos/ui/editBox.ts
new file mode 100644
index 000000000..115b2a4a7
--- /dev/null
+++ b/sdk/src/cocos/ui/editBox.ts
@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file cocos/ui/editBox.ts
+ * @brief `EditBox`: a text field whose box and labels are nodes of the scene, typed into through the platform's own text editor.
+ *
+ * The engine's `TextInput` composes its own flex-laid-out children, and an imported scene is world-space nodes: an EditBox here is the box a
+ * scene already drew, a `Label` that shows what was typed and one that shows the hint. A click on the box takes focus on the OS editing surface
+ * (a hidden textarea on the web, the soft keyboard and its IME on a device), whose value the labels follow. A host with no such surface shows the
+ * box and does not type, as the engine's own fields do.
+ */
+import { Component } from '../component';
+import { Node } from '../node';
+import { declareClass } from '../host';
+import type { EventTouch } from '../input';
+import { Label } from './label';
+import { UITransform } from './uiTransform';
+import { EventHandler, joinHandlers } from './button';
+import { platformCreateTextEditor } from '../../platform';
+import type { PlatformTextEditor } from '../../platform/types';
+
+type Handlers = Array<{ component: string; handler: string; customEventData: string }>;
+
+const InputMode = Object.freeze({ ANY: 0, EMAIL: 1, NUMERIC: 2, PHONE_NUMBER: 3, URL: 4, DECIMAL: 5, SINGLE_LINE: 6 });
+const InputFlag = Object.freeze({ PASSWORD: 0, SENSITIVE: 1, INITIAL_CAPS_WORD: 2, INITIAL_CAPS_SENTENCE: 3, INITIAL_CAPS_ALL_CHARACTERS: 4, DEFAULT: 5 });
+const KeyboardReturnType = Object.freeze({ DEFAULT: 0, DONE: 1, SEND: 2, SEARCH: 3, GO: 4, NEXT: 5 });
+const EventType = Object.freeze({
+ EDITING_DID_BEGAN: 'editing-did-began', EDITING_DID_ENDED: 'editing-did-ended', TEXT_CHANGED: 'text-changed', EDITING_RETURN: 'editing-return',
+});
+
+/** The characters a field of this input mode takes. */
+function allowed(mode: number, value: string): string {
+ switch (mode) {
+ case InputMode.NUMERIC: return value.replace(/[^0-9]/g, '');
+ case InputMode.DECIMAL: return value.replace(/[^0-9.\-]/g, '');
+ case InputMode.PHONE_NUMBER: return value.replace(/[^0-9+*#\-]/g, '');
+ case InputMode.EMAIL:
+ case InputMode.URL:
+ case InputMode.SINGLE_LINE: return value.replace(/[\r\n]/g, '');
+ default: return value;
+ }
+}
+
+const BULLET = '●';
+
+export class EditBox extends Component {
+ static readonly EventType = EventType;
+ static readonly InputMode = InputMode;
+ static readonly InputFlag = InputFlag;
+ static readonly KeyboardReturnType = KeyboardReturnType;
+
+ maxLength = 20;
+ inputMode: number = InputMode.ANY;
+ inputFlag: number = InputFlag.DEFAULT;
+ returnType: number = KeyboardReturnType.DEFAULT;
+ tabIndex = 0;
+ textLabel: Label | null = null;
+ placeholderLabel: Label | null = null;
+
+ editingDidBeganTargets: Array<Node | null> = [];
+ editingDidBeganHandlers: Handlers = [];
+ textChangedTargets: Array<Node | null> = [];
+ textChangedHandlers: Handlers = [];
+ editingDidEndedTargets: Array<Node | null> = [];
+ editingDidEndedHandlers: Handlers = [];
+ editingReturnTargets: Array<Node | null> = [];
+ editingReturnHandlers: Handlers = [];
+ editingDidBegan: EventHandler[] = [];
+ textChanged: EventHandler[] = [];
+ editingDidEnded: EventHandler[] = [];
+ editingReturn: EventHandler[] = [];
+
+ private string_ = '';
+ private editor_: PlatformTextEditor | null = null;
+ private unsubscribe_: (() => void) | null = null;
+
+ get string(): string { return this.string_; }
+ set string(value: string) {
+ this.string_ = this.fit_(value);
+ this.refresh_();
+ }
+
+ /** The hint shown while the field is empty. */
+ get placeholder(): string { return this.placeholderLabel?.string ?? ''; }
+ set placeholder(value: string) { if (this.placeholderLabel) this.placeholderLabel.string = value; }
+
+ isFocused(): boolean { return this.editor_ !== null; }
+
+ onLoad(): void {
+ if (this.editingDidBegan.length === 0) this.editingDidBegan = joinHandlers(this.editingDidBeganTargets, this.editingDidBeganHandlers);
+ if (this.textChanged.length === 0) this.textChanged = joinHandlers(this.textChangedTargets, this.textChangedHandlers);
+ if (this.editingDidEnded.length === 0) this.editingDidEnded = joinHandlers(this.editingDidEndedTargets, this.editingDidEndedHandlers);
+ if (this.editingReturn.length === 0) this.editingReturn = joinHandlers(this.editingReturnTargets, this.editingReturnHandlers);
+ }
+
+ onEnable(): void {
+ this.node.on(Node.EventType.TOUCH_END, this.onTouchEnd_, this);
+ this.refresh_();
+ }
+
+ onDisable(): void {
+ this.node.off(Node.EventType.TOUCH_END, this.onTouchEnd_, this);
+ this.blur();
+ }
+
+ private onTouchEnd_(event: EventTouch): void {
+ const inside = this.node.getComponent(UITransform)?.isHit(event.getUILocation()) ?? true;
+ if (inside) this.focus();
+ event.stopPropagation();
+ }
+
+ /** Take the keyboard, as a click on the box does. */
+ focus(): void {
+ if (this.editor_ || !this.enabledInHierarchy) return;
+ const editor = platformCreateTextEditor();
+ if (!editor) return; // a host with no text surface shows the field and does not type
+ this.editor_ = editor;
+ const end = this.string_.length;
+ editor.focus(
+ { value: this.string_, selectionStart: end, selectionEnd: end, backward: false },
+ { multiline: this.inputMode === InputMode.ANY, maxLength: this.maxLength > 0 ? this.maxLength : 0, password: this.inputFlag === InputFlag.PASSWORD },
+ );
+ this.unsubscribe_ = editor.subscribe((event) => {
+ if (event.kind === 'change') this.onChange_();
+ else if (event.kind === 'submit') { this.fire_(this.editingReturn, EventType.EDITING_RETURN); this.blur(); }
+ else if (event.kind === 'cancel' || event.kind === 'blur') this.blur();
+ });
+ this.refresh_();
+ this.fire_(this.editingDidBegan, EventType.EDITING_DID_BEGAN);
+ }
+
+ /** Give the keyboard back. */
+ blur(): void {
+ const editor = this.editor_;
+ if (!editor) return;
+ this.editor_ = null;
+ this.unsubscribe_?.();
+ this.unsubscribe_ = null;
+ editor.blur();
+ editor.dispose();
+ this.refresh_();
+ this.fire_(this.editingDidEnded, EventType.EDITING_DID_ENDED);
+ }
+
+ private onChange_(): void {
+ const editor = this.editor_;
+ if (!editor) return;
+ const state = editor.read();
+ const value = this.fit_(state.value);
+ if (value !== state.value) editor.write({ ...state, value, selectionStart: Math.min(state.selectionStart, value.length), selectionEnd: Math.min(state.selectionEnd, value.length) });
+ if (value === this.string_) return;
+ this.string_ = value;
+ this.refresh_();
+ EventHandler.emitEvents(this.textChanged, value, this);
+ this.node.emit(EventType.TEXT_CHANGED, this);
+ }
+
+ private fit_(value: string): string {
+ const text = allowed(this.inputMode, value);
+ return this.maxLength > 0 && text.length > this.maxLength ? text.slice(0, this.maxLength) : text;
+ }
+
+ private fire_(handlers: EventHandler[], type: string): void {
+ EventHandler.emitEvents(handlers, this);
+ this.node.emit(type, this);
+ }
+
+ /** What the labels show: the text (as bullets for a password), or the hint while there is none. */
+ private refresh_(): void {
+ const shown = this.inputFlag === InputFlag.PASSWORD ? BULLET.repeat(this.string_.length) : this.string_;
+ if (this.textLabel) this.textLabel.string = shown;
+ if (this.placeholderLabel) this.placeholderLabel.node.active = this.string_ === '';
+ }
+}
+
+export function declareEditBox(): void {
+ declareClass(EditBox as never, 'EditBox', [
+ { name: 'string_', kind: 'string' },
+ { name: 'maxLength', kind: 'number' },
+ { name: 'inputMode', kind: 'number' },
+ { name: 'inputFlag', kind: 'number' },
+ { name: 'returnType', kind: 'number' },
+ { name: 'tabIndex', kind: 'number' },
+ { name: 'textLabel', kind: 'component', type: Label },
+ { name: 'placeholderLabel', kind: 'component', type: Label },
+ { name: 'editingDidBeganTargets', kind: 'node', array: true },
+ { name: 'editingDidBeganHandlers', kind: 'json' },
+ { name: 'textChangedTargets', kind: 'node', array: true },
+ { name: 'textChangedHandlers', kind: 'json' },
+ { name: 'editingDidEndedTargets', kind: 'node', array: true },
+ { name: 'editingDidEndedHandlers', kind: 'json' },
+ { name: 'editingReturnTargets', kind: 'node', array: true },
+ { name: 'editingReturnHandlers', kind: 'json' },
+ ]);
+}
diff --git a/sdk/src/cocos/ui/index.ts b/sdk/src/cocos/ui/index.ts
index f820f8563..2986eb8c3 100644
--- a/sdk/src/cocos/ui/index.ts
+++ b/sdk/src/cocos/ui/index.ts
@@ -17,3 +17,4 @@ export { Camera } from './camera';
export { RichText } from './richText';
export { Mask } from './mask';
export { Graphics } from './graphics';
+export { EditBox } from './editBox';
diff --git a/sdk/src/cocos/ui/pass.ts b/sdk/src/cocos/ui/pass.ts
index 758180889..5743f8627 100644
--- a/sdk/src/cocos/ui/pass.ts
+++ b/sdk/src/cocos/ui/pass.ts
@@ -17,6 +17,7 @@ import { alignAllWidgets, declareWidget } from './widget';
import { layoutAll, declareLayout } from './layout';
import { declareControls } from './controls';
import { declareGraphics } from './graphics';
+import { declareEditBox } from './editBox';
import { declareScrollView } from './scrollView';
import { setUiCameraData, setVisibleSize, setWindowPixels } from './screen';
@@ -25,6 +26,7 @@ export function declareUiPass(): void {
declareLayout();
declareControls();
declareGraphics();
+ declareEditBox();
declareScrollView();
const system = defineSystem(
[Res(UICameraInfo), Res(ScreenLayout), GetWorld()],
diff --git a/sdk/tests/cocos/editbox-wasm.test.ts b/sdk/tests/cocos/editbox-wasm.test.ts
new file mode 100644
index 000000000..c5325a35a
--- /dev/null
+++ b/sdk/tests/cocos/editbox-wasm.test.ts
@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file EditBox: a click takes the platform's text editor, what is typed lands in the labels, and the field's rules (mode, length, hint) hold.
+ */
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { ESEngineModule } from '../../src/wasm';
+import { Transform, ensureBuiltinComponentsRegistered } from '../../src/ecs/component';
+import { EditBox, Label, Node, UITransform } from '../../src/cocos';
+import type { PlatformTextEditor, TextEditorEvent, TextEditorState } from '../../src/platform/types';
+import { HAS_WASM, loadWasmModule } from '../helpers/loadWasm';
+import { pointerApp, type PointerApp } from './helpers/pointerApp';
+
+/** A text surface the test types into. */
+class FakeEditor implements PlatformTextEditor {
+ state: TextEditorState = { value: '', selectionStart: 0, selectionEnd: 0, backward: false };
+ options: unknown = null;
+ focused = false;
+ disposed = false;
+ private handlers: Array<(e: TextEditorEvent) => void> = [];
+ focus(state: TextEditorState, options: unknown): void { this.state = { ...state }; this.options = options; this.focused = true; }
+ blur(): void { this.focused = false; }
+ read(): TextEditorState { return { ...this.state }; }
+ write(state: TextEditorState): void { this.state = { ...state }; }
+ subscribe(h: (e: TextEditorEvent) => void): () => void { this.handlers.push(h); return () => { this.handlers = this.handlers.filter((x) => x !== h); }; }
+ dispose(): void { this.disposed = true; }
+ type(value: string): void { this.state = { ...this.state, value, selectionStart: value.length, selectionEnd: value.length }; this.emit({ kind: 'change' }); }
+ emit(e: TextEditorEvent): void { for (const h of [...this.handlers]) h(e); }
+}
+
+let editor: FakeEditor | null;
+vi.mock('../../src/platform', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('../../src/platform')>()),
+ platformCreateTextEditor: () => editor,
+}));
+
+describe.skipIf(!HAS_WASM)('EditBox', () => {
+ let module: ESEngineModule;
+ let P: PointerApp | undefined;
+
+ beforeAll(async () => { ensureBuiltinComponentsRegistered(); module = await loadWasmModule(); });
+ beforeEach(() => { editor = new FakeEditor(); });
+ afterEach(() => { P?.dispose(); P = undefined; });
+
+ function box(name: string, x: number, y: number, w: number, h: number, parent?: Node): Node {
+ const n = new Node(name);
+ P!.app.world.insert(n._entity, Transform);
+ n.addComponent(UITransform)!.setContentSize(w, h);
+ n.setPosition(x, y, 0);
+ parent?.addChild(n);
+ return n;
+ }
+
+ async function field(configure: (e: EditBox) => void = () => {}): Promise<{ node: Node; edit: EditBox; text: Label; hint: Label }> {
+ P = pointerApp(module);
+ const node = box('input', 200, 200, 160, 40);
+ const text = box('text', 0, 0, 150, 30, node).addComponent(Label)!;
+ const hint = box('hint', 0, 0, 150, 30, node).addComponent(Label)!;
+ hint.string = 'type here';
+ const edit = node.addComponent<EditBox>('EditBox')!;
+ edit.textLabel = text;
+ edit.placeholderLabel = hint;
+ configure(edit);
+ await P.frame(1);
+ return { node, edit, text, hint };
+ }
+
+ it('takes the text editor on a click, and tells the field\'s listeners', async () => {
+ const { node, edit } = await field();
+ const seen: string[] = [];
+ node.on(EditBox.EventType.EDITING_DID_BEGAN, () => seen.push('began'));
+ await P!.tap(200, 200);
+ expect(editor!.focused).toBe(true);
+ expect(edit.isFocused()).toBe(true);
+ expect(seen).toEqual(['began']);
+ });
+
+ it('shows what is typed in its label and hides the hint, and brings the hint back when it is emptied', async () => {
+ const { node, edit, text, hint } = await field();
+ const changed: string[] = [];
+ node.on(EditBox.EventType.TEXT_CHANGED, (e: EditBox) => changed.push(e.string));
+ expect(hint.node.active).toBe(true);
+ await P!.tap(200, 200);
+ editor!.type('hello');
+ expect(edit.string).toBe('hello');
+ expect(text.string).toBe('hello');
+ expect(hint.node.active).toBe(false);
+ editor!.type('');
+ expect(hint.node.active).toBe(true);
+ expect(changed).toEqual(['hello', '']);
+ });
+
+ it('holds to the length and the characters its mode takes, writing the fit text back to the surface', async () => {
+ const { edit } = await field((e) => { e.maxLength = 4; e.inputMode = EditBox.InputMode.NUMERIC; });
+ await P!.tap(200, 200);
+ editor!.type('12ab3456');
+ expect(edit.string).toBe('1234');
+ expect(editor!.state.value).toBe('1234');
+ });
+
+ it('shows bullets for a password and keeps the real text', async () => {
+ const { edit, text } = await field((e) => { e.inputFlag = EditBox.InputFlag.PASSWORD; });
+ await P!.tap(200, 200);
+ editor!.type('secret');
+ expect(edit.string).toBe('secret');
+ expect(text.string).toBe('●●●●●●');
+ expect((editor!.options as { password: boolean }).password).toBe(true);
+ });
+
+ it('ends on submit with a return event and then an end event, giving the surface back', async () => {
+ const { node, edit } = await field();
+ const seen: string[] = [];
+ node.on(EditBox.EventType.EDITING_RETURN, () => seen.push('return'));
+ node.on(EditBox.EventType.EDITING_DID_ENDED, () => seen.push('ended'));
+ await P!.tap(200, 200);
+ editor!.emit({ kind: 'submit' });
+ expect(seen).toEqual(['return', 'ended']);
+ expect(edit.isFocused()).toBe(false);
+ expect(editor!.focused).toBe(false);
+ expect(editor!.disposed).toBe(true);
+ });
+
+ it('can be set from a script without an event, and shows the hint when empty', async () => {
+ const { edit, text, hint } = await field();
+ edit.string = 'preset';
+ expect(text.string).toBe('preset');
+ expect(hint.node.active).toBe(false);
+ });
+
+ it('does nothing on a host with no text editor', async () => {
+ editor = null;
+ const { edit } = await field();
+ await P!.tap(200, 200);
+ expect(edit.isFocused()).toBe(false);
+ });
+});
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 81bdaeb2d..6c300712b 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'feat(cocos): EditBox is a component over the platform text editor (mode and length rules, hint, password bullets, the four editing events), and the importer maps it':
+ {"internal":"The Cocos Creator compatibility layer and importer have not shipped; nothing a creator reaches without opting in."},
'feat(cocos): Graphics is a component over the engine Draw (rect, circle and stroked paths kept until clear), UIMeshRenderer folds into its host, and a Node has worldScale and worldRotation':
{"internal":"The Cocos Creator compatibility layer and importer have not shipped; nothing a creator reaches without opting in."},
'feat(animation): an animator state can play at the speed of a float parameter (speedParameter), and the Cocos animation graph is converted to an animator controller':