diff --git a/AGENTS.md b/AGENTS.md index 6df40ea..07baf19 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,6 +47,7 @@ sapi-pro 是 Minecraft Bedrock ScriptAPI(SAPI)库,提供命令系统、表 - `core/src/Command/`:命令系统。**`.` 前缀模拟命令(`Command/parser/parser.ts`)、自定义 help(`Command/help.ts`,专门为 `.help` 准备的)与 chatBus 仅 beta 渠道存在**;stable 渠道这三个模块不进产物、`CommandManager.parser` 与 `help` 均为 `undefined`(通过 `SimulatedParserLike` / `HelpLike` 结构接口解耦)。**stable 只允许 `registerNative` 注册游戏原生命令**(customCommandRegistry + `NativeCommandParser`),`registerCommand`(模拟命令)在 stable 无效、不自动转原生,自定义 help 由游戏自带 `/help` 覆盖。 - **原生命令的 enum 参数按渠道分支(实机踩了三轮才对齐)**:两条运行时规则 —— ①枚举名**必须带命名空间**,否则 `registerEnum` 抛 `NamespaceNameError`;②stable `@minecraft/server`(2.10.0)的 `CustomCommandParameter` **没有 `enumName`**,运行时把**参数名逐字**当枚举名查表,所以 stable 下 enum/flag 参数的 `name` 必须写成 `命名空间:参数名`,枚举也用同一个名字注册(参数名不参与命令语法与参数解析,`NativeCommandParser` 是按位置映射的,所以无副作用)。beta 有 `enumName`(`@beta`),参数名保持短名、用唯一枚举名解耦,避免同包内不同命令的同名参数互相覆盖。逻辑在 `core/src/Command/enumName.ts`(`nativeEnumName` / `nativeEnumParamName`),回归测试 `core/test/command/enumName.test.ts`。另外 `CommandManager.registerNativeCommands` 对每条命令单独 try/catch(一条注册失败不再中断后续命令);枚举注册走 `core/src/Command/enumRegistry.ts` 的 `planEnumRegistrations()`:同名同值复用、**同名不同值自动改名成 `命名空间:命令名_参数名` 并同步改写参数引用**(stable 下参数名就是枚举名,不改名两条命令无法共存),测试见 `core/test/command/enumRegistry.test.ts`。 - `core/src/Form/`:表单导航,`formManager` 全局管理,支持跨包 `openExternal` 打开别的行为包的表单。 +- `core/src/Form/ddui/`:DDUI(`CustomForm`)响应式页面封装。`DDUI.page()` 返回的对象同时是 `SAPIProForm`,与传统表单共用同一个表单栈;`DDScope` 托管页面级订阅/定时器/外部资源,`ui.set` 区分程序写入与玩家输入,`formManager` 用导航代际令牌丢弃过期的异步展示。业务页面不写 `unsubscribe` / `cleanups` / `opening` / `activePlayers`,跳转统一用 `ui.push/back/replace/reopen/reset/close`。文档见 `tutorial/ddui.md`,测试在 `core/test/ddui/`。 - `core/src/DataBase/`:`DPDataBase` / `CompactDPDataBase` / `ScoreBoardJSONDataBase` / `ScoreBoardDataBase`。`CompactDPDataBase` 用固定 schema 的位置编码紧凑存储同构 DP 记录;超大文本继续复用 DP 分片。 - `core/src/Deferred/`:世界加载后才求值的延迟对象,`gameDeferredRegistry` 统一绑定。 - `core/src/Event.ts`:事件总线(聊天/间隔等);`Translate/`:i18n,`translator`;`utils/`:random / vector / chunk / logger,以及 `vanila-data.ts`(仅一个 `DimensionIds` 枚举)。 diff --git a/core/src/Form/ddui/context.ts b/core/src/Form/ddui/context.ts new file mode 100644 index 0000000..32fd1ea --- /dev/null +++ b/core/src/Form/ddui/context.ts @@ -0,0 +1,324 @@ +import type { Player } from "@minecraft/server"; +import { + CustomForm, + ObservableBoolean, + ObservableNumber, + ObservableString, + type ButtonOptions, + type DividerOptions, + type DropdownItemData, + type DropdownOptions, + type ImageOptions, + type SliderOptions, + type SpacingOptions, + type TextFieldOptions, + type TextOptions, + type ToggleOptions, + type UIRawMessage, +} from "@minecraft/server-ui"; +import type { SAPIProFormContext } from "../form"; +import type { contextArgs, FormLike } from "../interface"; +import { computedObservable, type ObservableOf, type ObservableValue } from "./observable"; +import type { DDScope, ObservableLike, SubscribableSource } from "./scope"; +import type { DDUIPage, DDUISession } from "./page"; + +/** 表单文本:原生支持字符串 / ObservableString / 原始消息 */ +export type DDText = string | ObservableString | UIRawMessage; + +/** 可托管的外部资源:只需要 retain/release 两个方法(例如共享 ViewModel) */ +export interface Retainable { + retain(): void; + release(): void; +} + +/** + * 单个 DDUI 页面的开发接口。 + * + * 页面内的 Observable 订阅、派生状态、定时器、外部信号都由页面作用域托管, + * 关闭/返回/替换时自动释放;业务代码只需要描述“状态是什么、变化时做什么”。 + */ +export class DDUIContext { + /** 页面作用域,特殊资源可以显式托管 */ + readonly scope: DDScope; + /** 原生 CustomForm,需要原生方法时直接使用;页面释放后为 undefined */ + form?: CustomForm; + /** 打开本页时的参数(返回时原样保留;页面释放后清空引用) */ + readonly args: TArgs; + private formContext?: SAPIProFormContext; + private owner: Player; + /** 本页创建的 Observable,释放时清空其中的文本,避免被原生表单继续留住 */ + private readonly created: Array> = []; + + constructor( + private readonly session: DDUISession, + formContext: SAPIProFormContext, + form: CustomForm, + args: TArgs + ) { + this.form = form; + this.args = args; + this.scope = session.scope; + this.formContext = formContext; + this.owner = formContext.player; + } + + get player(): Player { + return this.owner; + } + + /** 页面是否已经关闭(异步回调里可以用来提前退出) */ + get closed(): boolean { + return this.scope.isClosed; + } + + /** @internal 断开对原生表单与页面参数的引用,避免跨堆引用把页面留住 */ + release() { + // 先清空页面文本:即使引擎短暂保留已关闭的表单,也不会拖着一串行/标签字符串 + for (const observable of this.created) { + try { + if (typeof observable.getData() === "string") observable.setData(""); + } catch { + // 表单已关闭,忽略 + } + } + this.created.length = 0; + this.form = undefined; + (this as { args?: TArgs }).args = undefined; + this.formContext = undefined; + (this as unknown as { session?: DDUISession }).session = undefined; + // 未结算的 show() 可能仍持有本上下文;断开玩家 wrapper,避免 Players/Entity 句柄滞留。 + (this as unknown as { owner?: Player }).owner = undefined; + } + + // ───────────────────────── 状态 ───────────────────────── + + /** 创建一个可被玩家编辑的数字 Observable(默认 clientWritable) */ + number(initial: number, options?: { clientWritable?: boolean }): ObservableNumber { + const observable = new ObservableNumber(initial, { clientWritable: options?.clientWritable ?? true }); + this.created.push(observable); + return observable; + } + + /** 创建一个可被玩家编辑的文本 Observable(默认 clientWritable) */ + string(initial: string, options?: { clientWritable?: boolean }): ObservableString { + const observable = new ObservableString(initial, { clientWritable: options?.clientWritable ?? true }); + this.created.push(observable); + return observable; + } + + /** 创建一个可被玩家编辑的开关 Observable(默认 clientWritable) */ + boolean(initial: boolean, options?: { clientWritable?: boolean }): ObservableBoolean { + const observable = new ObservableBoolean(initial, { clientWritable: options?.clientWritable ?? true }); + this.created.push(observable); + return observable; + } + + /** + * 由若干 Observable 派生的只读 Observable,页面关闭后自动停止计算。 + * + * 依赖必须显式传入:这里不做自动依赖追踪,因此不提供省略 `deps` 的重载。 + */ + computed( + deps: readonly ObservableLike[], + compute: () => T + ): ObservableOf { + const observable = computedObservable(this.scope, deps, compute); + this.created.push(observable); + return observable; + } + + /** + * 监听变化(客户端输入,或业务代码直接 setData)。 + * + * 通过 `ui.set()` 做的程序写入不会触发;值没变也不会触发。 + */ + onChange(observable: ObservableLike, callback: (value: T) => void): void { + this.scope.track( + observable, + (value) => { + if (this.session?.writeGuard.isOwnWrite(observable)) return; + callback(value); + }, + "onChange" + ); + } + + /** 监听依赖变化(默认立即执行一次),用于“状态同步到别处”的副作用 */ + watch(deps: readonly ObservableLike[], callback: () => void, immediate = true): void { + if (immediate && !this.closed) callback(); + for (const dep of deps) this.scope.track(dep, () => callback(), "watch"); + } + + /** + * 程序写入:不触发本页通过 ui.onChange 注册的回调;值没变时不写回、不通知。 + * 用于同步服务器状态、纠正越界值、格式化显示文本。 + */ + set(observable: ObservableLike, value: T): void { + this.session?.writeGuard.write(observable, value); + } + + /** 读取 Observable 当前值(语法糖) */ + get(observable: ObservableLike): T { + return observable.getData(); + } + + /** + * 托管外部订阅:原生 Observable(用 unsubscribe 退订)或事件信号(用返回的退订函数)。 + * 页面关闭时一定会解除订阅,回调也不会再执行。 + */ + subscribe(source: SubscribableSource, listener: (value: T) => void): void { + this.scope.subscribe(source, listener); + } + + /** 托管清理函数(关闭时执行,重复关闭只执行一次) */ + own(cleanup: () => void, label?: string): () => void { + return this.scope.own(cleanup, label); + } + + /** 托管定时任务(页面关闭自动取消,关闭后不会执行) */ + timeout(callback: () => void, ticks = 1): () => void { + return this.scope.timeout(callback, ticks); + } + + /** 托管循环任务(页面关闭自动取消) */ + interval(callback: () => void, ticks = 1): () => void { + return this.scope.interval(callback, ticks); + } + + /** 页面关闭时执行一次(等价于 own,语义更直观) */ + onClose(callback: () => void): void { + this.scope.own(callback, "onClose"); + } + + /** 页面持有共享资源(ViewModel 等)的引用,关闭时自动 release */ + retain(resource: T): T { + resource.retain(); + this.scope.own(() => resource.release(), "retain"); + return resource; + } + + // ───────────────────────── 原生控件 ───────────────────────── + // + // 所有控件方法都返回 `ui` 本身,链式调用不会绕过按钮保护。 + // 需要原生 `CustomForm` 时用 `ui.form`。 + + label(text: DDText, options?: TextOptions): this { + this.form?.label(text, options); + return this; + } + + header(text: DDText, options?: TextOptions): this { + this.form?.header(text, options); + return this; + } + + toggle(label: DDText, value: ObservableBoolean, options?: ToggleOptions): this { + this.form?.toggle(label, value, options); + return this; + } + + slider( + label: DDText, + value: ObservableNumber, + min: number | ObservableNumber, + max: number | ObservableNumber, + options?: SliderOptions + ): this { + this.form?.slider(label, value, min, max, options); + return this; + } + + dropdown( + label: DDText, + value: ObservableNumber, + items: DropdownItemData[], + options?: DropdownOptions + ): this { + this.form?.dropdown(label, value, items, options); + return this; + } + + textField(label: DDText, text: ObservableString, options?: TextFieldOptions): this { + this.form?.textField(label, text, options); + return this; + } + + image(src: ObservableString | string, pack: string, options?: ImageOptions): this { + this.form?.image(src, pack, options); + return this; + } + + divider(options?: DividerOptions): this { + this.form?.divider(options); + return this; + } + + spacer(options?: SpacingOptions): this { + this.form?.spacer(options); + return this; + } + + closeButton(): this { + this.form?.closeButton(); + return this; + } + + /** + * 按钮:回调带页面失效保护,关闭后迟到的点击、快速连点都不会重复执行/重复导航。 + */ + button(label: DDText, onClick: () => void, options?: ButtonOptions): this { + // 回调放进可清空的盒子里:原生 CustomForm 可能被尚未结算的 show() 留住, + // 直接闭包捕获 onClick 会让整页参数/钢琴运行时随表单一起滞留。 + const holder: { callback?: () => void } = { callback: onClick }; + this.scope.own(() => { holder.callback = undefined; }, "button"); + this.form?.button(label, () => { + const callback = holder.callback; + if (callback) this.session?.invoke(callback); + }, options); + return this; + } + + // ───────────────────────── 导航 ───────────────────────── + + /** 页面释放后所有导航都变成无操作 */ + private navigate( + mutate: (formContext: SAPIProFormContext, settleTicks: number) => void + ): void { + const session = this.session; + const formContext = this.formContext; + if (!session || !formContext) return; + session.navigate(() => mutate(formContext, session.settleTicks)); + } + + /** 打开新页面(入栈);传统表单同样可以入栈 */ + push(form: FormLike, args?: T, delay?: number): void { + this.navigate((ctx, settle) => ctx.push(form, args, delay ?? settle)); + } + + /** 返回上一页(没有上一页时关闭界面) */ + back(delay?: number): void { + this.navigate((ctx, settle) => ctx.back(delay ?? settle)); + } + + /** 替换当前页(栈深度不变) */ + replace(form: FormLike, args?: T, delay?: number): void { + this.navigate((ctx, settle) => ctx.replace(form, args, delay ?? settle)); + } + + /** 用当前参数重新打开当前页(重建页面状态) */ + reopen(delay?: number): void { + this.navigate((ctx, settle) => ctx.reopen(delay ?? settle)); + } + + /** 清空栈并打开新页 */ + reset(form: FormLike, args?: T, delay?: number): void { + this.navigate((ctx, settle) => ctx.offAll(form, args, delay ?? settle)); + } + + /** 关闭界面并清空栈 */ + close(): void { + this.navigate((ctx) => ctx.close()); + } +} + +export type { DDUIPage }; diff --git a/core/src/Form/ddui/main.ts b/core/src/Form/ddui/main.ts new file mode 100644 index 0000000..cd7a658 --- /dev/null +++ b/core/src/Form/ddui/main.ts @@ -0,0 +1,56 @@ +import type { Player } from "@minecraft/server"; +import { formManager } from "../formManager"; +import type { contextArgs } from "../interface"; +import { activeDDUISession, dduiPage, dduiStats, type DDUIPage } from "./page"; + +export * from "./scope"; +export * from "./observable"; +export * from "./context"; +export * from "./page"; + +/** + * DDUI 响应式表单入口。 + * + * ```ts + * const settings = DDUI.page("钢琴设置", (ui, args) => { + * const volume = ui.number(100); + * ui.onChange(volume, value => saveVolume(value)); + * ui.label(ui.computed([volume], () => `当前音量:${volume.getData()}%`)); + * ui.slider("音量", volume, 0, 200, { step: 1 }); + * ui.button("曲谱设置", () => ui.push(scorePage, { piano: args.piano })); + * }); + * + * DDUI.open(player, settings, { piano }); + * ``` + */ +export const DDUI = { + /** 定义一个可复用、可入栈的页面 */ + page: dduiPage, + /** + * 清空表单栈并打开页面。 + * @param delay 等待的游戏刻;0 表示下一 tick 显示(`system.runTimeout(..., 0)`) + */ + open( + player: Player, + page: DDUIPage, + args?: TArgs, + delay = 0 + ) { + formManager.open(player, page, args, delay); + }, + /** 关闭当前界面并清空表单栈 */ + close(player: Player) { + formManager.close(player); + }, + /** 当前玩家正在显示的页面上下文(没有则为 undefined) */ + active(player: Player) { + return activeDDUISession(player)?.ui; + }, + /** + * 诊断:当前未释放的 DDUI 会话数(关闭后应为 0)。 + * 用于确认反复开关是否真的在累积资源。 + */ + stats() { + return { ...dduiStats(), ...formManager.dduiShowStats() }; + }, +}; diff --git a/core/src/Form/ddui/observable.ts b/core/src/Form/ddui/observable.ts new file mode 100644 index 0000000..1a17f20 --- /dev/null +++ b/core/src/Form/ddui/observable.ts @@ -0,0 +1,81 @@ +import { ObservableBoolean, ObservableNumber, ObservableString } from "@minecraft/server-ui"; +import type { DDScope, ObservableLike } from "./scope"; + +export type ObservableValue = string | number | boolean; + +/** 根据初始值类型创建对应的原生 Observable */ +export function createObservable(initial: T): ObservableLike { + if (typeof initial === "boolean") { + return new ObservableBoolean(initial) as unknown as ObservableLike; + } + if (typeof initial === "number") { + return new ObservableNumber(initial) as unknown as ObservableLike; + } + return new ObservableString(String(initial)) as unknown as ObservableLike; +} + +/** 值类型 → 原生 Observable 类型,用于 computed 的返回类型推导 */ +export type ObservableOf = T extends boolean + ? ObservableBoolean + : T extends number + ? ObservableNumber + : ObservableString; + +/** + * 由若干原生 Observable 派生的只读 Observable。 + * + * 依赖变化时同步重算,值没变就不写回(避免无意义的客户端同步)。 + * 订阅随页面释放,不需要调用方管理。 + */ +export function computedObservable( + scope: DDScope, + deps: readonly ObservableLike[], + compute: () => T +): ObservableOf { + const initial = compute(); + const out = createObservable(initial); + let updating = false; + const update = () => { + if (updating || scope.isClosed) return; + updating = true; + try { + const next = compute(); + if (next !== out.getData()) out.setData(next); + } finally { + updating = false; + } + }; + for (const dep of deps) scope.track(dep, update, "computed"); + return out as unknown as ObservableOf; +} + +/** + * 程序写入守卫。 + * + * 原生 Observable 只在值真正变化时同步通知订阅者(官方语义),因此不存在 + * “同一个值、来源不同”的歧义:唯一需要处理的是**本次 `setData` 自身触发的回调**。 + * 这里在写入期间打一个同步标记,`ui.onChange` 看到标记就跳过。 + * + * 不记录“最后写入值”,也不做时间窗口猜测:客户端后续回报的值如果与当前值相同, + * 原生层根本不会通知;如果不同,那就是一次真实的输入。 + */ +export class WriteGuard { + private writing = new WeakSet(); + + /** 程序写入:值没变时直接返回(不产生通知) */ + write(observable: ObservableLike, value: T) { + if (Object.is(observable.getData(), value)) return; + const key = observable as unknown as object; + this.writing.add(key); + try { + observable.setData(value); + } finally { + this.writing.delete(key); + } + } + + /** 当前是否处于本次程序写入的同步通知中 */ + isOwnWrite(observable: ObservableLike): boolean { + return this.writing.has(observable as unknown as object); + } +} diff --git a/core/src/Form/ddui/page.ts b/core/src/Form/ddui/page.ts new file mode 100644 index 0000000..b99b4f2 --- /dev/null +++ b/core/src/Form/ddui/page.ts @@ -0,0 +1,372 @@ +import type { Player } from "@minecraft/server"; +import { CustomForm, DataDrivenScreenClosedReason } from "@minecraft/server-ui"; +import { LibLogger } from "../../utils/logger"; +import type { SAPIProForm, SAPIProFormContext } from "../form"; +import type { contextArgs } from "../interface"; +import { DDUIContext } from "./context"; +import { WriteGuard } from "./observable"; +import { DDScope, safeInvoke } from "./scope"; +import { formStackManager } from "../stackManager"; + +/** 关闭旧表单到显示新表单之间等待的游戏刻(0 = 下一 tick 立即显示) */ +export const DDUI_SETTLE_TICKS = 0; + +/** 页面标题:可以按页面参数动态生成 */ +export type DDTitle = string | ((args: TArgs) => string); + +/** 构建页面的回调:在这里描述控件与状态依赖 */ +export type DDUIBuild = (ui: DDUIContext, args: TArgs) => void; + +/** + * 一个 DDUI 页面。 + * + * 它同时是一个 SAPIProForm,所以既能用 `DDUI.open()` / `ui.push()`, + * 也能直接交给 formManager 或传统表单的 `ctx.push()`,两种表单可以共存于同一个表单栈。 + */ +export interface DDUIPage extends SAPIProForm { + readonly title: DDTitle; + readonly build: DDUIBuild; + /** @internal 标记这是 DDUI 页面(CustomForm.show 不需要 player 参数) */ + readonly _ddui: true; +} + +/** 当前仍在显示的页面(每玩家最多一个) */ +const activeByPlayer = new Map(); +/** 会话直接挂在 formContext 上,随表单栈一起释放(不再用全局 WeakMap) */ +type DDContextWithSession = { _dduiSession?: DDUISession }; + +function takeSession(context: SAPIProFormContext): DDUISession | undefined { + const carrier = context as DDContextWithSession; + const session = carrier._dduiSession; + carrier._dduiSession = undefined; + return session; +} +/** 诊断用:尚未 dispose 的会话数(不持有引用) */ +let liveSessions = 0; +let createdSessions = 0; +let disposedSessions = 0; +let createdForms = 0; + +/** + * 单个玩家的单个页面会话。 + * + * 页面会话只负责:构建控件 → 显示 → 关闭后释放。 + * 页面跳转在关闭前写入表单栈,具体显示由 formManager 统一驱动,避免两套导航互相抢 UI。 + */ +export class DDUISession { + readonly scope = new DDScope(); + readonly writeGuard = new WriteGuard(); + readonly settleTicks = DDUI_SETTLE_TICKS; + + form?: CustomForm; + ui?: DDUIContext; + private navigating = false; + private disposed = false; + + constructor( + private readonly player: Player, + private readonly playerId: string, + private args: contextArgs, + private formContext: SAPIProFormContext, + private readonly page: DDUIPage + ) { + liveSessions++; + createdSessions++; + } + + /** 构建页面并返回要显示的原生表单 */ + build(): CustomForm { + const title = typeof this.page.title === "function" ? this.page.title(this.args) : this.page.title; + const form = new CustomForm(this.player, title); + createdForms++; + this.form = form; + const ui = new DDUIContext(this, this.formContext, form, this.args); + this.ui = ui; + activeByPlayer.set(this.playerId, this); + this.page.build(ui, this.args); + return form; + } + + /** 按钮回调入口:页面关闭后迟到的点击、同一次显示内的连点都会忽略 */ + invoke(callback: () => void) { + if (this.disposed || this.navigating || !this.player.isValid) return; + // 按钮回调可能是 async:同步 try/catch 抓不到 Promise 拒绝 + safeInvoke(callback, (e) => LibLogger.error("DDUI 按钮回调异常", e)); + } + + /** 修改表单栈后关闭当前表单,由 formManager 负责显示目标页面 */ + navigate(mutate: () => void) { + if (this.disposed || this.navigating) return; + this.navigating = true; + try { + mutate(); + } catch (e) { + LibLogger.error("DDUI 页面跳转失败", e); + } + // 先关原生表单,再释放页面资源:从点击跳转到 show() 结算之间, + // 页面不再接收订阅回调、也不再持有表单/页面状态(ui.closed 立刻为 true)。 + this.closeForm(); + this.dispose(); + } + + /** 关闭原生表单;已关闭或玩家已离线时静默忽略 */ + closeForm() { + const form = this.form; + if (!form) return; + try { + // 不先判断 isShowing:部分版本在玩家按 ESC 后仍报告 showing, + // 再 close 一次可以确保原生侧释放该表单(重复 close 只会在 catch 里忽略)。 + form.close(); + } catch { + // 已经关闭 / 玩家离开 / 表单已被其它路径关闭 + } + } + + /** @internal 玩家是否仍然有效(用于清理真正的掉线会话) */ + isPlayerValid() { + try { + return this.player.isValid; + } catch { + return false; + } + } + + /** show() 结束后调用:释放页面资源 */ + finish() { + this.dispose(); + } + + /** 释放页面资源;幂等,不抛错。释放后不再持有表单、页面参数与表单栈上下文。 */ + dispose() { + if (this.disposed) return; + this.disposed = true; + liveSessions--; + disposedSessions++; + // 玩家按 ESC 关闭时,引擎侧可能仍把表单记为 showing;显式 close 一次, + // 与迁移前手写面板的 dispose 一致,避免原生 UI 记录一直保留这个表单。 + this.closeForm(); + + // 顶层关闭:整个 UI 会话结束,换一条空栈。 + // 旧栈(含 context / args / 已 dispose 的 session 引用)成为不可达链, + // 立刻可回收。导航(push / back)时必须保留,上一页还要用 args 重建。 + if (!this.navigating) { + formStackManager.resetStack(this.player); + } + + if (activeByPlayer.get(this.playerId) === this) { + activeByPlayer.delete(this.playerId); + } + this.scope.dispose(); + // 断开跨堆引用:原生表单的回调会引用页面闭包,页面若再持有表单就形成 + // 原生 <-> JS 的环,JS GC 无法回收,表现为“关了表单内存不恢复”。 + this.ui?.release(); + this.ui = undefined; + this.form = undefined; + // 未结算的 show() 反应闭包会保留 formContext;把 args(通常是 + // {piano, block})和会话反向引用断开,否则 UI 关闭后这些对象仍被 + // 原生表单的 Promise 链钉住。 + const context = this.formContext as unknown as + { args?: unknown; _dduiSession?: unknown; _form?: unknown; _showData?: unknown; player?: unknown } | undefined; + this.args = undefined as never; + this.formContext = undefined as never; + // 导航(push/reopen)时旧 context 仍留在表单栈里,之后 back 需要用它 + // 的 args 重建父页面;只有真正离开栈的 context 才能清空参数。 + const queued = !!context && !!formStackManager.getStack(this.player)?.has(context as never); + if (context) { + context._dduiSession = undefined; + if (!queued) { + context.args = undefined; + context._form = undefined; + if (!context._showData) context.player = undefined; + } + } + } +} + +/** + * 定义一个 DDUI 页面。 + * + * @param title 标题,或根据参数生成标题的函数 + * @param build 页面构建函数,页面资源由作用域自动托管 + */ +export function dduiPage( + title: DDTitle, + build: DDUIBuild +): DDUIPage { + const page: DDUIPage = { + _ddui: true, + title, + build, + builder(player, args, context) { + const session = new DDUISession( + player, + player.id, + args as contextArgs, + context as SAPIProFormContext, + page as DDUIPage + ); + (context as DDContextWithSession)._dduiSession = session; + try { + return session.build(); + } catch (e) { + session.dispose(); + takeSession(context); + throw e; + } + }, + handler(reason, context) { + const session = takeSession(context); + if (!session) return; + // 玩家主动关闭(ESC / 客户端关闭按钮):还有上一页时回退一层, + // 而不是清空整个栈。根页面才关闭界面。 + if ( + (reason as unknown as string) === DataDrivenScreenClosedReason.ClientClosed && + context.depth > 1 + ) { + session.navigate(() => context.back()); + return; + } + session.finish(); + }, + }; + return page; +} + +/** 当前玩家正在显示的 DDUI 会话(供 formManager 关闭/清理) */ +export function activeDDUISession(player: Player): DDUISession | undefined { + return activeByPlayer.get(player.id); +} + +/** 释放指定表单上下文对应的页面会话(构建失败 / 展示被抢占时使用) */ +export function disposeDDUISession(context: SAPIProFormContext) { + const session = takeSession(context); + session?.dispose(); +} + +/** 强制关闭玩家的 DDUI 页面(不清空表单栈) */ +export function closeDDUIPage(player: Player): boolean { + const session = activeByPlayer.get(player.id); + if (!session) return false; + session.closeForm(); + session.dispose(); + return true; +} + +/** + * 清理真正掉线玩家的页面会话。 + * + * `show()` 通常会在玩家退出时结算并自行释放;这里作为兜底,避免 + * 客户端异常断开导致会话与页面作用域一直留在内存里。 + */ +export function disposeOfflineDDUISessions() { + for (const session of [...activeByPlayer.values()]) { + if (session.isPlayerValid()) continue; + session.closeForm(); + session.dispose(); + } +} + +/** + * 诊断:当前仍未释放的 DDUI 会话数。 + * + * 每次关闭表单后应为 0;反复开关若持续增长,就是真的泄漏。 + */ +export function dduiStats() { + return { + /** 尚未 dispose 的会话数 */ + sessions: liveSessions, + /** 正在显示的玩家数 */ + activePlayers: activeByPlayer.size, + /** 累计创建的会话 / 已 dispose 的会话 */ + created: createdSessions, + disposed: disposedSessions, + /** 累计创建的原生表单数 */ + forms: createdForms, + }; +} + +/** + * 用 Promise 回调完成 DDUI 页面的“构建 → 显示 → 处理 → 继续导航”。 + * + * 和传统表单共用 formManager 的调度,但 DDUI 的等待链不把表单/上下文 + * 挂在 async 帧上:show() 期间只保留回调需要的 session,关闭后立即释放。 + */ +export function showDDUIContext( + player: Player, + context: SAPIProFormContext, + isCurrent: () => boolean, + after: () => void +): void { + const page = context._form as DDUIPage | undefined; + if (!page) return; + + const start = page.beforeBuild + ? Promise.resolve() + .then(() => page.beforeBuild!(context)) + .catch((e) => LibLogger.error("DDUI beforeBuild 异常", e)) + : Promise.resolve(); + + void start.then(() => { + if (!isCurrent()) return; + + // 构建过程中页面主动关闭/重定向:不再显示 + if (!context._willBuild) { + after(); + return; + } + + let form: CustomForm; + try { + form = page.builder(player, context.args, context) as CustomForm; + } catch (e) { + LibLogger.error("DDUI 构建表单失败", e); + disposeDDUISession(context); + const top = formStackManager.getTop(player); + if (top === context) formStackManager.getStack(player)?.pop(); + return; + } + + if (!isCurrent()) { + disposeDDUISession(context); + return; + } + if (!context._willBuild) { + disposeDDUISession(context); + after(); + return; + } + + const close = () => { + disposeDDUISession(context); + if (isCurrent()) after(); + }; + + let shown: Promise; + try { + shown = form.show(); + } catch (e) { + // 官方 API 声明 show() 可能同步抛错;不能只依赖 Promise 拒绝回调, + // 否则会话、作用域与表单栈都不会释放。 + LibLogger.error("DDUI 展示表单异常", e); + close(); + return; + } + + void shown.then( + (response) => { + if (!isCurrent()) { + disposeDDUISession(context); + return; + } + try { + page.handler(response as never, context); + } catch (e) { + LibLogger.error("DDUI 表单处理异常", e); + } + if (isCurrent()) after(); + }, + // 玩家离开 / 表单被其它路径关闭:释放页面资源后继续 + close + ); + }).catch((e) => LibLogger.error("DDUI 展示流程异常", e)); +} diff --git a/core/src/Form/ddui/scope.ts b/core/src/Form/ddui/scope.ts new file mode 100644 index 0000000..5502c41 --- /dev/null +++ b/core/src/Form/ddui/scope.ts @@ -0,0 +1,167 @@ +import { system } from "@minecraft/server"; +import { LibLogger } from "../../utils/logger"; + +/** 订阅返回的清理句柄(函数 / 带 dispose / 带 unsubscribe),允许为空表示无法退订 */ +export type UnsubscribeLike = + | ((...args: any[]) => void) + | { dispose(): void } + | { unsubscribe(): void } + | void; + +/** 原生 Observable 的最小结构,方便测试替身与外部只读状态接入 */ +export interface ObservableLike { + getData(): T; + setData(value: T): void; + subscribe(callback: (value: T) => void): (value: T) => void; + unsubscribe(callback: (value: T) => void): boolean; +} + +/** 可订阅源:原生 Observable 或事件信号(Signal / world 事件) */ +export type SubscribableSource = { + subscribe(callback: (value: T) => void): UnsubscribeLike; + getData?: () => T; + unsubscribe?: (callback: (value: T) => void) => unknown; +}; + +/** 把任意形式的退订句柄归一成函数 */ +export function toCleanup(handle: UnsubscribeLike): (() => void) | undefined { + if (!handle) return; + if (typeof handle === "function") return handle as () => void; + const obj = handle as { dispose?: () => void; unsubscribe?: () => void }; + if (typeof obj.dispose === "function") return () => obj.dispose!(); + if (typeof obj.unsubscribe === "function") return () => obj.unsubscribe!(); + return; +} + +/** + * 统一执行回调:同步异常与 Promise 拒绝都交给 onError。 + * + * 业务回调常写成 async,调用点同步 try/catch 抓不到拒绝;在这里接住, + * 避免框架托管的回调产生未处理拒绝。 + */ +export function safeInvoke(run: () => unknown, onError: (e: unknown) => void) { + try { + const result = run(); + if (result && typeof (result as PromiseLike).then === "function") { + (result as PromiseLike).then(undefined, (e) => onError(e)); + } + } catch (e) { + onError(e); + } +} + +function safeRun(run: () => void, label: string) { + // 单个清理失败不能中断其余清理,也不能让表单关闭流程抛错 + safeInvoke(run, (e) => LibLogger.warn(`DDUI 清理失败: ${label}`, e)); +} + +/** + * 页面级资源容器。 + * + * 页面关闭时按登记顺序倒序释放,每项都单独 try/catch,重复释放安全。 + * 业务代码只需要 `ui.onChange` / `ui.subscribe` / `ui.timeout`,不需要自己维护 cleanups 数组。 + */ +export class DDScope { + private items: Array<{ label: string; run: () => void }> = []; + private closed = false; + + get isClosed() { + return this.closed; + } + + /** 托管一个清理函数;已关闭时立即执行(迟到的资源不会泄漏) */ + own(cleanup: () => void, label = "cleanup"): () => void { + if (this.closed) { + safeRun(cleanup, label); + return () => {}; + } + const item = { label, run: cleanup }; + this.items.push(item); + return () => { + const index = this.items.indexOf(item); + if (index < 0) return; + this.items.splice(index, 1); + safeRun(item.run, item.label); + }; + } + + /** 订阅原生 Observable;页面关闭或回调迟到时自动忽略 */ + track(observable: ObservableLike, callback: (value: T) => void, label = "observable"): () => void { + if (this.closed) return () => {}; + const handle = observable.subscribe((value) => { + if (this.closed) return; + safeRun(() => callback(value), label); + }); + return this.own(() => { + observable.unsubscribe(handle); + }, label); + } + + /** + * 订阅外部源(原生 Observable 或事件信号)。 + * + * 原生 Observable 的 `subscribe` 返回的是**回调本身**(不是退订函数), + * 用 `unsubscribe(回调)` 退订;事件信号返回的才是退订函数。 + * 两者在这里统一,页面关闭时都能真正解除订阅。 + */ + subscribe(source: SubscribableSource, listener: (value: T) => void, label = "signal"): () => void { + if (this.closed) return () => {}; + const wrapped = (value: T) => { + if (this.closed) return; + safeRun(() => listener(value), label); + }; + const handle = source.subscribe(wrapped); + if (typeof source.unsubscribe === "function") { + // 原生 Observable 和 Minecraft 事件信号均返回订阅回调, + // 不能把它当作清理函数执行;统一使用 unsubscribe(回调)。 + const unsubscribe = source.unsubscribe.bind(source); + return this.own(() => { + unsubscribe(wrapped); + }, label); + } + const cleanup = toCleanup(handle); + return cleanup ? this.own(cleanup, label) : () => {}; + } + + /** 托管一个定时任务;页面关闭后自动取消,也不会在关闭后再执行 */ + timeout(callback: () => void, ticks = 1, label = "timeout"): () => void { + if (this.closed) return () => {}; + let done = false; + let release: () => void = () => {}; + const id = system.runTimeout(() => { + if (done) return; + done = true; + // 定时任务已经完成,立即移除清理登记,避免长时间打开的 + // 页面不断累积已执行 timeout 的闭包和回调引用。 + release(); + if (this.closed) return; + safeRun(callback, label); + }, ticks); + release = this.own(() => { + if (done) return; + done = true; + system.clearRun(id); + }, label); + return release; + } + + /** 托管一个循环任务;页面关闭后自动取消 */ + interval(callback: () => void, ticks = 1, label = "interval"): () => void { + if (this.closed) return () => {}; + const id = system.runInterval(() => { + if (this.closed) return; + safeRun(callback, label); + }, ticks); + return this.own(() => system.clearRun(id), label); + } + + /** 释放全部资源;幂等且不抛错 */ + dispose() { + if (this.closed) return; + this.closed = true; + const items = this.items.splice(0); + for (let i = items.length - 1; i >= 0; i--) { + safeRun(items[i].run, items[i].label); + } + } +} diff --git a/core/src/Form/form.ts b/core/src/Form/form.ts index a34ab31..54fe171 100644 --- a/core/src/Form/form.ts +++ b/core/src/Form/form.ts @@ -1,8 +1,10 @@ +import type { Player } from "@minecraft/server"; import { contextArgs, formBeforeBuild, FormBuilder, formDataType, + FormLike, formHandler, showData, } from "./interface"; @@ -15,50 +17,71 @@ export interface SAPIProForm; /**处理函数 */ handler: formHandler; + /**@internal DDUI 页面标记:CustomForm.show() 不需要 player 参数 */ + _ddui?: true; } export class SAPIProFormContext { /**@internal 内部属性,勿改*/ - _form?: SAPIProForm; + _form?: FormLike; /**@internal 内部属性,勿改 */ _willBuild: boolean; /**@internal 内部属性,勿改 */ _showData?: showData; + /** + * 打开本页的玩家。 + * + * 上下文**不持有** `PlayerFormStack` 引用:导航时按玩家从全局表取。 + * 否则 `stack[] -> context -> stack` 会成环,运行时不会主动回收引用环, + * 每次关闭页面都会把 context 和它的 args 一起留在内存里。 + */ + readonly player: Player; + /** 当前表单所在栈的身份;只存数字,避免反向持有栈对象形成引用环。 */ + private readonly stackInstanceId: number; constructor( readonly args: U, - private readonly stack: PlayerFormStack, - form?: SAPIProForm + stack: PlayerFormStack, + form?: FormLike ) { + this.player = stack.getPlayer(); + this.stackInstanceId = stack.instanceId; this._form = form; this._willBuild = true; this._showData = undefined; } - get player() { - return this.stack.getPlayer(); + /** @internal 当前玩家的表单栈(按需获取,绝不反向持有) */ + private get stack(): PlayerFormStack | undefined { + const current = formStackManager.getStack(this.player); + // 旧异步 handler / beforeBuild 不得修改后来新开的页面, + // 历史页面还在栈中、但已不是栈顶时也不得抢占前台导航。 + return current?.instanceId === this.stackInstanceId && current.getTop() === this + ? current + : undefined; + } + + /**@internal 表单栈深度(DDUI 判断是否还有上一页) */ + get depth(): number { + return this.stack?.depth ?? 0; } /**打开表单 */ - push( - form: SAPIProForm, - args?: NoInfer, - delay = 0 - ) { + push(form: FormLike, args?: NoInfer, delay = 0) { this._willBuild = false; this._showData = { delay }; - this.stack.push(args ?? {}, form); + this.stack?.push(args ?? {}, form); } /**打开命名表单 */ pushNamed(name: string, args?: contextArgs, delay = 0) { this._willBuild = false; - this.stack.push(args ?? {}); + this.stack?.push(args ?? {}); this._showData = { delay, name }; } /**返回上一个表单 */ back(delay = 0) { this._willBuild = false; - this.stack.pop(); + this.stack?.pop(); this._showData = { delay }; } /**重新打开当前表单 */ @@ -69,69 +92,68 @@ export class SAPIProFormContext { /**关闭所有表单 */ close() { this._willBuild = false; - formStackManager.resetStack(this.player); + if (this.stack) formStackManager.resetStack(this.player); } /**替换当前表单为新的命名表单 */ - replace( - form: SAPIProForm, - args?: NoInfer, - delay = 0 - ) { + replace(form: FormLike, args?: NoInfer, delay = 0) { this._willBuild = false; - this.stack.pop(); - this.stack.push(args ?? {}, form as any); + const stack = this.stack; + stack?.pop(); + stack?.push(args ?? {}, form); this._showData = { delay }; } /**替换当前表单为新的命名表单 */ replaceNamed(name: string, args?: contextArgs, delay = 0) { this._willBuild = false; - this.stack.pop(); - this.stack.push(args ?? {}); + const stack = this.stack; + stack?.pop(); + stack?.push(args ?? {}); this._showData = { delay, name }; } /**清空堆栈,并打开表单 */ - offAll( - form: SAPIProForm, - args?: NoInfer, - delay = 0 - ) { + offAll(form: FormLike, args?: NoInfer, delay = 0) { + const stack = this.stack; + if (!stack) return; this._willBuild = false; - this.stack.clear(); - this.push(form, args, delay); + stack.clear(); + stack.push(args ?? {}, form); + this._showData = { delay }; } /**清空堆栈,并打开命名表单 */ offAllNamed(name: string, args?: contextArgs, delay = 0) { + const stack = this.stack; + if (!stack) return; this._willBuild = false; - this.stack.clear(); - this.pushNamed(name, args, delay); + stack.clear(); + stack.push(args ?? {}); + this._showData = { delay, name }; } /**一直返回到指定页 */ - until( - form: SAPIProForm, - delay = 0 - ) { + until(form: FormLike, delay = 0) { this._willBuild = false; - let top = this.stack.getTop(); - while (top?._form && top._form !== form) { - this.stack.pop(); - top = this.stack.getTop(); + const stack = this.stack; + let top = stack?.getTop(); + while (stack && top?._form && top._form !== form) { + stack.pop(); + top = stack.getTop(); } this._showData = { delay }; } /**一直返回到指定页并打开新页 */ - offUntil( - form: SAPIProForm, - newForm: SAPIProForm, + offUntil( + form: FormLike, + newForm: FormLike, args?: NoInfer, delay = 0 ) { this._willBuild = false; - let top = this.stack.getTop(); - while (top?._form && top._form !== form) { - this.stack.pop(); - top = this.stack.getTop(); + const stack = this.stack; + let top = stack?.getTop(); + while (stack && top?._form && top._form !== form) { + stack.pop(); + top = stack.getTop(); } - this.stack.push(args ?? {}, newForm); + stack?.push(args ?? {}, newForm); this._showData = { delay }; } } diff --git a/core/src/Form/formManager.ts b/core/src/Form/formManager.ts index b59b692..148ebbb 100644 --- a/core/src/Form/formManager.ts +++ b/core/src/Form/formManager.ts @@ -1,14 +1,15 @@ import { Player, ScriptEventCommandMessageAfterEvent, system } from "@minecraft/server"; -import { FormRejectError } from "@minecraft/server-ui"; +import { CustomForm, FormRejectError, uiManager } from "@minecraft/server-ui"; import { LibConfig } from "../Config"; import { ScriptEventBus, intervalBus } from "../Event"; import { LibErrorMes, getPlayerById } from "../func"; import { SAPIProForm, SAPIProFormContext } from "./form"; -import { contextArgs, formDataType, openFormData } from "./interface"; +import { contextArgs, formDataType, FormLike, openFormData } from "./interface"; import { formStackManager } from "./stackManager"; +import { DDUI_SETTLE_TICKS, activeDDUISession, closeDDUIPage, disposeDDUISession, disposeOfflineDDUISessions, showDDUIContext } from "./ddui/page"; interface SAPIProFormBatchRegister { - [key: string]: SAPIProForm; + [key: string]: FormLike; } class FormNotFoundError extends Error { @@ -19,10 +20,35 @@ class FormNotFoundError extends Error { } } +/** 正常的“表单结束”异常:玩家关窗、离开游戏、表单被另一条路径关闭 */ +function isBenignShowError(error: unknown) { + if (error instanceof FormRejectError) return true; + const e = error as { name?: string; reason?: string } | undefined; + return ( + e?.name === "PlayerLeftError" || + e?.name === "FormVisibilityError" || + e?.name === "InvalidEntityError" || + e?.reason === "PlayerQuit" || + e?.reason === "ServerShutdown" || + e?.reason === "AlreadyShowing" || + e?.reason === "NotShowing" + ); +} + +function closeAllForms(player: Player) { + try { + (uiManager as { closeAllForms?: (player: Player) => void } | undefined)?.closeAllForms?.(player); + } catch { + // 没有可关闭的表单 / 旧版本没有该 API + } +} + export class FormManagerClass { - private forms = new Map>(); + private forms = new Map>(); /**min 清理定时器是否已订阅(没开过表单的包就不会订阅) */ private minBound = false; + /** 正在显示传统表单的玩家,用于在重新打开时先关掉旧界面 */ + private showingLegacy = new Set(); /**有表单要展示时才订阅 min 清理,之后不再退订 */ private ensureMinTick() { @@ -30,6 +56,7 @@ export class FormManagerClass { this.minBound = true; intervalBus.subscribemin(() => { formStackManager.clearOff(); + disposeOfflineDDUISessions(); }); } @@ -39,7 +66,7 @@ export class FormManagerClass { } /**注册一个具名表单 */ - registerNamed(name: string, form: SAPIProForm) { + registerNamed(name: string, form: FormLike) { this.forms.set(name, form); } @@ -66,39 +93,145 @@ export class FormManagerClass { _showDelay(player: Player, delay = 0) { //任何一条展示表单的路径(open/具名/跳转)都会经过这里,借此按需启用 min 清理 this.ensureMinTick(); - system.runTimeout(() => { - this._show(player); - }, delay); + const stack = formStackManager.getStack(player); + if (!stack) return; + //代际令牌:同一玩家只允许最后一次调度生效,丢弃之前排队的旧任务 + const generation = stack.bumpGeneration(); + const show = () => { + if (formStackManager.getStack(player) !== stack) return; + if (stack.navGeneration !== generation) return; + void this._show(player); + }; + // 必须等至少一个游戏刻:玩家关闭旧表单后,客户端还需要时间结算, + // 立即 show() 下一张会被引擎拒绝(表现为“点按钮没反应”)。 + system.runTimeout(show, delay); + } + + /** 诊断:尚未结算的 show 次数;长时间不归零说明某次 show 没有走完 */ + private pendingShows = 0; + private completedShows = 0; + + /** @internal 诊断用 */ + dduiShowStats() { + return { pendingShows: this.pendingShows, completedShows: this.completedShows }; } /**显示form * @internal 不要调用 */ async _show(player: Player) { - const context = formStackManager.getTop(player); - if (!context?._form) return; - const form = context._form; - //重置 + this.pendingShows++; + try { + await this._showInner(player); + } finally { + this.pendingShows--; + this.completedShows++; + } + } + + private async _showInner(player: Player) { + const stack = formStackManager.getStack(player); + const context = stack?.getTop(); + const form = context?._form; + if (!stack || !context || !form) return; + if (!player.isValid) { + disposeDDUISession(context); + formStackManager.resetStack(player); + return; + } + + const generation = stack.navGeneration; + /** 本次展示是否仍然是当前导航(旧 show 不能操作新栈) */ + const isCurrent = () => formStackManager.getStack(player) === stack && stack.navGeneration === generation; + context._willBuild = true; + + // DDUI 页面:用 Promise 回调完成构建/显示/释放。 + // 不走下面的 async/await 链——`await show()` 期间帧会一直持有 + // context / form / builtForm,反复开关时表现为每次约 1KB 的残留。 + if (form._ddui === true) { + showDDUIContext( + player, + context as SAPIProFormContext, + isCurrent, + () => { + if (isCurrent()) this._handleShow(context); + } + ); + return; + } + if (form.beforeBuild) { - await form.beforeBuild(context); + try { + await form.beforeBuild(context); + } catch (e) { + LibErrorMes("表单 beforeBuild 异常", e); + } } + if (!isCurrent()) return; + //如果不build了就返回 if (!context._willBuild) { this._handleShow(context); return; } - const builtForm = await form.builder(context.player, context.args); - let response; + + let builtForm: formDataType; try { - response = await builtForm.show(player); - } catch (err) { - // A rejected form is expected when a player closes it or leaves the game. - if (err instanceof FormRejectError) return; - throw err; + builtForm = await form.builder(player, context.args, context); + } catch (e) { + LibErrorMes("构建表单失败", e); + disposeDDUISession(context); + if (formStackManager.getTop(player) === context) stack.pop(); + return; + } + + if (!isCurrent()) { + // 展示前栈已被新的导航替换:释放刚构建的页面资源,绝不显示旧页面 + disposeDDUISession(context); + return; + } + + // 构建过程中页面主动关闭/重定向:不再显示这个表单 + if (!context._willBuild) { + disposeDDUISession(context); + if (isCurrent()) this._handleShow(context); + return; + } + + // 到这里只剩传统表单(DDUI 页面在上面已提前返回) + this.showingLegacy.add(player.id); let response: unknown; + try { + response = await (builtForm as unknown as { show(player: Player): Promise }).show(player); + } catch (e) { + if (!isBenignShowError(e)) LibErrorMes("展示表单异常", e); + disposeDDUISession(context); + if (isCurrent()) this._handleShow(context); + return; + } finally { + // 旧表单 show() 可能晚于新表单结算;不能删除新表单的 showing 标记。 + if (isCurrent()) this.showingLegacy.delete(player.id); + } + + if (!isCurrent()) { + disposeDDUISession(context); + return; + } + + try { + await form.handler(response as never, context); + } catch (e) { + LibErrorMes("表单处理异常", e); + } + + if (!isCurrent()) return; + + // 顶层关闭:与 DDUI 一致,换一条空栈释放全部上下文。 + // 页面跳转(_showData 已设置)时保留,返回时还要用 args。 + if (!context._showData) { + formStackManager.resetStack(player); } - await form.handler(response, context); this._handleShow(context); } @@ -139,9 +272,36 @@ export class FormManagerClass { args?: NoInfer, delay = 0 ) { + if (!player.isValid) return; + //同一玩家只能有一个界面:先关掉仍在显示的表单,避免新旧表单互相抢 UI + const closed = this.closeCurrent(player); const stack = formStackManager.resetStack(player); stack.push(args ?? {}, form as any); - this._showDelay(player, delay); + this._showDelay(player, closed ? Math.max(delay, DDUI_SETTLE_TICKS) : delay); + } + + /** + * 关闭该玩家当前界面并清空表单栈(DDUI 与传统表单都适用)。 + * 运行时的对象销毁、玩家退出等场景直接调用即可。 + */ + close(player: Player) { + closeDDUIPage(player); + formStackManager.resetStack(player); + this.showingLegacy.delete(player.id); + closeAllForms(player); + } + + /** 该玩家当前是否有表单在显示(不区分 DDUI / 传统表单) */ + isShowing(player: Player) { + return this.showingLegacy.has(player.id) || activeDDUISession(player) !== undefined; + } + + /** 关闭仍在前台的表单,返回是否真的关了东西 */ + private closeCurrent(player: Player) { + if (closeDDUIPage(player)) return true; + if (!this.showingLegacy.delete(player.id)) return false; + closeAllForms(player); + return true; } /**打开指定名字的表单,需要先注册 diff --git a/core/src/Form/interface.ts b/core/src/Form/interface.ts index 1d31b2a..f2dda3f 100644 --- a/core/src/Form/interface.ts +++ b/core/src/Form/interface.ts @@ -2,6 +2,8 @@ import { Player } from "@minecraft/server"; import { ActionFormData, ActionFormResponse, + CustomForm, + DataDrivenScreenClosedReason, MessageFormData, MessageFormResponse, ModalFormData, @@ -9,7 +11,8 @@ import { } from "@minecraft/server-ui"; import { SAPIProFormContext } from "./form"; -export type formDataType = ActionFormData | ModalFormData | MessageFormData; +/** 传统表单与 DDUI(CustomForm)都可以放进同一个表单栈 */ +export type formDataType = ActionFormData | ModalFormData | MessageFormData | CustomForm; export type formResponse = MessageFormResponse | ModalFormResponse | ActionFormResponse; export type formResponseType = T extends MessageFormData @@ -18,12 +21,27 @@ export type formResponseType = T extends MessageFormData ? ModalFormResponse : T extends ActionFormData ? ActionFormResponse - : never; + : T extends CustomForm + ? DataDrivenScreenClosedReason + : never; export interface contextArgs { [key: string]: any; } +/** + * 任意表单(传统表单或 DDUI 页面)。 + * + * 用于只关心“能入栈/能返回”、不关心具体响应类型的导航 API, + * 避免把 `SAPIProForm` 的响应联合类型传染给调用方。 + */ +export interface FormLike { + builder(player: Player, args: TArgs, context: SAPIProFormContext): any; + handler(response: any, context: SAPIProFormContext): any; + beforeBuild?(context: SAPIProFormContext): any; + _ddui?: true; +} + export interface openFormData { name: string; nameSpace: string; @@ -34,7 +52,8 @@ export interface openFormData { export type FormBuilder = ( player: Player, - args: U + args: U, + context: SAPIProFormContext ) => Promise | T; export type formBeforeBuild = ( diff --git a/core/src/Form/main.ts b/core/src/Form/main.ts index 045b77c..f2ec4e0 100644 --- a/core/src/Form/main.ts +++ b/core/src/Form/main.ts @@ -1,4 +1,5 @@ export * from "./commonForm/main"; +export * from "./ddui/main"; export * from "./form"; export * from "./formManager"; export * from "./interface"; diff --git a/core/src/Form/stackManager.ts b/core/src/Form/stackManager.ts index 743350f..78b221b 100644 --- a/core/src/Form/stackManager.ts +++ b/core/src/Form/stackManager.ts @@ -1,12 +1,27 @@ import { Player } from "@minecraft/server"; -import { SAPIProForm, SAPIProFormContext } from "./form"; -import { contextArgs, formDataType } from "./interface"; +import { SAPIProFormContext } from "./form"; +import { contextArgs, FormLike } from "./interface"; + +// 栈身份只存原始数字,避免 FormContext 反向引用栈导致 QuickJS 引用环。 +let nextStackInstanceId = 0; export class PlayerFormStack { - private stack: SAPIProFormContext[] = []; + readonly instanceId = ++nextStackInstanceId; + private stack: SAPIProFormContext[] = []; + /** + * 导航代际:每次真正调度一次展示就自增。 + * 异步 show / 延迟打开的旧任务在代际变化后自行放弃,不会覆盖新的页面。 + */ + navGeneration = 0; + constructor(private readonly player: Player) {} - push(args: contextArgs, form?: SAPIProForm) { + /** @internal 标记一次新的展示调度,返回本次调度的代际 */ + bumpGeneration() { + return ++this.navGeneration; + } + + push(args: contextArgs, form?: FormLike) { const context = new SAPIProFormContext(args, this, form); this.stack.push(context); return context; @@ -14,13 +29,21 @@ export class PlayerFormStack { pop() { return this.stack.pop(); } - getTop() { + getTop(): SAPIProFormContext | undefined { if (this.stack.length == 0) return; return this.stack[this.stack.length - 1]; } + /** 栈深度(DDUI 页面可用来判断是否还有上一页) */ + get depth() { + return this.stack.length; + } clear() { this.stack = []; } + /** 表单上下文是否仍在栈里(导航后父页面还要用它的 args 重建)。 */ + has(context: SAPIProFormContext) { + return this.stack.includes(context); + } getPlayer() { return this.player; } diff --git a/core/test/ddui/ddui.test.ts b/core/test/ddui/ddui.test.ts new file mode 100644 index 0000000..3f9eb80 --- /dev/null +++ b/core/test/ddui/ddui.test.ts @@ -0,0 +1,1435 @@ +// ===================================================== +// DDUI 页面 / 表单栈测试 +// +// 用可控的假 system + 假 CustomForm 驱动 formManager, +// 覆盖订阅释放、派生状态、导航竞争、异常与混合表单栈。 +// ===================================================== +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +// ─── 假运行时(hoisted,供 vi.mock 使用)─────────────── +const env = vi.hoisted(() => { + let now = 0; + let nextId = 1; + let seq = 0; + const timers = new Map void; every?: number }>(); + + const system = { + get currentTick() { + return now; + }, + runTimeout(fn: () => void, ticks = 0) { + const id = nextId++; + timers.set(id, { at: now + Math.max(0, ticks), order: seq++, fn }); + return id; + }, + runInterval(fn: () => void, ticks = 1) { + const id = nextId++; + const every = Math.max(1, ticks); + timers.set(id, { at: now + every, order: seq++, fn, every }); + return id; + }, + clearRun(id: number) { + timers.delete(id); + }, + afterEvents: { + scriptEventReceive: { subscribe: () => () => {} }, + }, + sendScriptEvent: () => {}, + }; + + function advance(ticks = 1) { + for (let i = 0; i < ticks; i++) { + now++; + const due = [...timers.entries()] + .filter(([, t]) => t.at <= now) + .sort((a, b) => a[1].at - b[1].at || a[1].order - b[1].order); + for (const [id, timer] of due) { + if (!timers.has(id)) continue; + if (timer.every) { + timer.at = now + timer.every; + timer.order = seq++; + } else { + timers.delete(id); + } + timer.fn(); + } + } + } + + function reset() { + now = 0; + nextId = 1; + seq = 0; + timers.clear(); + } + + const world = { + afterEvents: { worldLoad: { subscribe: () => () => {} } }, + beforeEvents: {}, + getPlayers: () => [], + }; + + return { system, world, advance, reset }; +}); + +// ─── 假 @minecraft/server-ui ───────────────────────── +const ui = vi.hoisted(() => { + type Listener = (value: T) => void; + + class MockObservable { + private listeners = new Set>(); + constructor( + private value: T, + public options?: { clientWritable?: boolean } + ) {} + getData() { + return this.value; + } + setData(value: T) { + if (Object.is(value, this.value)) return; + this.value = value; + for (const listener of [...this.listeners]) listener(value); + } + subscribe(callback: Listener) { + this.listeners.add(callback); + return callback; + } + unsubscribe(callback: Listener) { + return this.listeners.delete(callback); + } + get listenerCount() { + return this.listeners.size; + } + } + + class MockForm { + static all: MockForm[] = []; + static showError: Error | undefined; + static showErrorSync: Error | undefined; + static busyCount = 0; + static buildCount = 0; + + static reset() { + MockForm.all = []; + MockForm.showError = undefined; + MockForm.showErrorSync = undefined; + MockForm.busyCount = 0; + MockForm.buildCount = 0; + } + + components: Array> = []; + showing = false; + showCalls = 0; + private resolveShow?: (reason: string) => void; + + constructor( + public player: any, + public title: any + ) { + MockForm.all.push(this); + } + + show(): Promise { + this.showCalls++; + if (MockForm.showErrorSync) { + const error = MockForm.showErrorSync; + MockForm.showErrorSync = undefined; + throw error; + } + if (MockForm.showError) { + const error = MockForm.showError; + MockForm.showError = undefined; + return Promise.reject(error); + } + if (MockForm.busyCount > 0) { + MockForm.busyCount--; + return Promise.resolve("UserBusy"); + } + this.showing = true; + return new Promise((resolve) => { + this.resolveShow = resolve; + }); + } + + close() { + if (!this.showing) throw new Error("FormVisibilityError: NotShowing"); + this.showing = false; + this.resolveShow?.("ServerClosed"); + } + + isShowing() { + return this.showing; + } + + /** 模拟玩家点 X */ + playerClose() { + this.showing = false; + this.resolveShow?.("ClientClosed"); + } + + private push(type: string, data: Record = {}) { + this.components.push({ type, ...data }); + return this; + } + + label(text: any, options?: any) { + return this.push("label", { text, options }); + } + header(text: any, options?: any) { + return this.push("header", { text, options }); + } + toggle(label: any, value: any, options?: any) { + return this.push("toggle", { label, value, options }); + } + slider(label: any, value: any, min: any, max: any, options?: any) { + return this.push("slider", { label, value, min, max, options }); + } + dropdown(label: any, value: any, items: any, options?: any) { + return this.push("dropdown", { label, value, items, options }); + } + textField(label: any, value: any, options?: any) { + return this.push("textField", { label, value, options }); + } + image(src: any, pack: any, options?: any) { + return this.push("image", { src, pack, options }); + } + divider(options?: any) { + return this.push("divider", { options }); + } + spacer(options?: any) { + return this.push("spacer", { options }); + } + closeButton() { + return this.push("closeButton"); + } + button(label: any, onClick: () => void, options?: any) { + return this.push("button", { label, onClick, options }); + } + + buttons() { + return this.components.filter((c) => c.type === "button"); + } + click(index = 0) { + this.buttons()[index]?.onClick(); + } + } + + class MockActionForm { + showing = false; + showCalls = 0; + private resolveShow?: (response: unknown) => void; + title() { + return this; + } + body() { + return this; + } + button() { + return this; + } + show(_player: any) { + this.showCalls++; + this.showing = true; + return new Promise((resolve) => { + this.resolveShow = resolve; + }); + } + playerClose() { + this.showing = false; + this.resolveShow?.({ canceled: true }); + } + } + + const closedReasons = { + ClientClosed: "ClientClosed", + ServerClosed: "ServerClosed", + UserBusy: "UserBusy", + } as const; + + return { + MockObservable, + MockForm, + MockActionForm, + closedReasons, + uiManager: { closeAllForms: vi.fn() }, + FormRejectError: class extends Error {}, + DataDrivenScreenClosedReason: closedReasons, + ObservableBoolean: MockObservable, + ObservableNumber: MockObservable, + ObservableString: MockObservable, + }; +}); + +vi.mock("@minecraft/server", () => ({ + system: env.system, + world: env.world, + Player: class {}, + PlayerPermissionLevel: { Operator: "operator", Member: "member" }, +})); + +vi.mock("@minecraft/server-ui", () => ({ + CustomForm: ui.MockForm, + ActionFormData: ui.MockActionForm, + ModalFormData: ui.MockActionForm, + MessageFormData: ui.MockActionForm, + ObservableBoolean: ui.ObservableBoolean, + ObservableNumber: ui.ObservableNumber, + ObservableString: ui.ObservableString, + ObservableUIRawMessage: ui.MockObservable, + FormRejectError: ui.FormRejectError, + DataDrivenScreenClosedReason: ui.DataDrivenScreenClosedReason, + uiManager: ui.uiManager, +})); + +// ─── Imports(必须在 mock 之后)──────────────────────── +import type { Player } from "@minecraft/server"; +import { DDUI, dduiPage, type DDUIContext } from "../../src/Form/ddui/main"; +import { DDScope } from "../../src/Form/ddui/scope"; +import { formManager } from "../../src/Form/formManager"; +import { formStackManager } from "../../src/Form/stackManager"; +import { LibLogger } from "../../src/utils/logger"; +import type { SAPIProForm } from "../../src/Form/form"; + +const MockForm = ui.MockForm; +const flush = () => new Promise((resolve) => setTimeout(resolve, 0)); + +/** 推进游戏刻并让 async show 链路跑完 */ +async function settle(ticks = 6) { + for (let i = 0; i < ticks; i++) { + env.advance(1); + await flush(); + } +} + +let playerSeq = 0; +function createPlayer() { + const id = `player-${++playerSeq}`; + return { + id, + isValid: true, + dimension: { id: "minecraft:overworld" }, + location: { x: 0, y: 0, z: 0 }, + sendMessage: vi.fn(), + setDynamicProperty: vi.fn(), + getDynamicProperty: vi.fn(() => undefined), + } as unknown as Player; +} + +function lastForm() { + return MockForm.all[MockForm.all.length - 1]; +} + +function stackDepth(player: Player) { + return formStackManager.getStack(player)?.depth ?? 0; +} + +/** 传统表单替身:记录实例,便于模拟玩家关窗 */ +const legacyInstances: Array> = []; + +function makeLegacyForm( + onHandler: (ctx: any) => void, + log: string[] = [] +): SAPIProForm { + return { + builder() { + log.push("legacy:show"); + const form = new ui.MockActionForm(); + legacyInstances.push(form); + return form as any; + }, + handler(_response, ctx) { + log.push("legacy:handler"); + onHandler(ctx); + }, + }; +} + +beforeEach(() => { + env.reset(); + MockForm.reset(); + legacyInstances.length = 0; + vi.clearAllMocks(); +}); + +afterEach(() => { + for (const form of MockForm.all) form.showing = false; + for (const form of legacyInstances) form.showing = false; +}); + +// ===================================================== +describe("DDUI 状态与作用域", () => { + it("已完成的 timeout 立即释放清理记录,长期页面不会累积回调", async () => { + const scope = new DDScope(); + let executed = 0; + const cleanups = () => (scope as unknown as { items: unknown[] }).items.length; + + for (let i = 0; i < 120; i++) scope.timeout(() => { executed++; }, 1); + expect(cleanups()).toBe(120); + env.advance(1); + await flush(); + expect(executed).toBe(120); + expect(cleanups()).toBe(0); + + const cancel = scope.timeout(() => { executed++; }, 10); + expect(cleanups()).toBe(1); + cancel(); + expect(cleanups()).toBe(0); + env.advance(20); + expect(executed).toBe(120); + scope.dispose(); + }); + + it("页面关闭后自动退订 Observable,迟到的回调不再执行", async () => { + const player = createPlayer(); + const calls: number[] = []; + let volume: any; + + const page = dduiPage("测试", (ctx) => { + volume = ctx.number(10); + ctx.onChange(volume, (value) => calls.push(value)); + }); + + DDUI.open(player, page); + await settle(); + const form = lastForm(); + + volume.setData(20); + expect(calls).toEqual([20]); + expect(volume.listenerCount).toBe(1); + + form.playerClose(); + await settle(); + + expect(volume.listenerCount).toBe(0); + volume.setData(30); + expect(calls).toEqual([20]); + expect(DDUI.active(player)).toBeUndefined(); + }); + + it("ui.set 的服务器写入不触发 onChange,客户端写入会", async () => { + const player = createPlayer(); + const calls: number[] = []; + let volume: any; + let ctxRef: DDUIContext | undefined; + + const page = dduiPage("测试", (ctx) => { + ctxRef = ctx; + volume = ctx.number(0); + ctx.onChange(volume, (value) => calls.push(value)); + }); + + DDUI.open(player, page); + await settle(); + + ctxRef!.set(volume, 42); + expect(volume.getData()).toBe(42); + expect(calls).toEqual([]); + + volume.setData(43); + expect(calls).toEqual([43]); + + // 程序写入:自身通知被屏蔽;同值再写不会产生通知 + ctxRef!.set(volume, 50); + volume.setData(50); + expect(calls).toEqual([43]); + + lastForm().playerClose(); + await settle(); + }); + + it("computed 跟随多个依赖更新,关闭后停止计算", async () => { + const player = createPlayer(); + const computedValues: string[] = []; + let volume: any; + let enabled: any; + let label: any; + + const page = dduiPage("测试", (ctx) => { + volume = ctx.number(100); + enabled = ctx.boolean(true); + label = ctx.computed([volume, enabled], () => + enabled.getData() ? `音量 ${volume.getData()}` : "已静音" + ); + ctx.onChange(label, (value) => computedValues.push(value)); + }); + + DDUI.open(player, page); + await settle(); + + expect(label.getData()).toBe("音量 100"); + volume.setData(120); + expect(label.getData()).toBe("音量 120"); + enabled.setData(false); + expect(label.getData()).toBe("已静音"); + expect(computedValues).toEqual(["音量 120", "已静音"]); + + lastForm().playerClose(); + await settle(); + // 页面文本在关闭时清空;之后依赖再变化也不会重算 + expect(label.getData()).toBe(""); + volume.setData(200); + expect(label.getData()).toBe(""); + expect(label.listenerCount).toBe(0); + }); + + it("页面关闭会取消定时器,关闭后不会执行", async () => { + const player = createPlayer(); + const fired: string[] = []; + + const page = dduiPage("测试", (ctx) => { + ctx.timeout(() => fired.push("late"), 5); + ctx.interval(() => fired.push("tick"), 10); + }); + + DDUI.open(player, page); + await settle(2); + expect(fired).toEqual([]); + + lastForm().playerClose(); + await settle(12); + expect(fired).toEqual([]); + }); + + it("作用域重复释放只执行一次,单个清理失败不影响其它清理", () => { + const scope = new DDScope(); + const calls: string[] = []; + scope.own(() => calls.push("a"), "a"); + scope.own(() => { + calls.push("boom"); + throw new Error("boom"); + }, "boom"); + scope.own(() => calls.push("c"), "c"); + + scope.dispose(); + scope.dispose(); + + expect(calls).toEqual(["c", "boom", "a"]); + expect(scope.isClosed).toBe(true); + }); + + it("外部 Signal 订阅随页面释放", async () => { + const player = createPlayer(); + const listeners = new Set<(value: void) => void>(); + const signal = { + subscribe(callback: (value: void) => void) { + listeners.add(callback); + return () => listeners.delete(callback); + }, + publish() { + for (const listener of [...listeners]) listener(); + }, + }; + let received = 0; + + const page = dduiPage("测试", (ctx) => { + ctx.subscribe(signal, () => received++); + }); + + DDUI.open(player, page); + await settle(); + expect(listeners.size).toBe(1); + + signal.publish(); + expect(received).toBe(1); + + lastForm().playerClose(); + await settle(); + expect(listeners.size).toBe(0); + }); + + it("原生事件信号返回回调时通过 unsubscribe 退订,反复开关不累积监听", async () => { + const player = createPlayer(); + const listeners = new Set<(value: number) => void>(); + let unexpectedCalls = 0; + const signal = { + subscribe(callback: (value: number) => void) { + listeners.add(callback); + return callback; // Minecraft 原生 EventSignal 返回回调,而不是清理函数 + }, + unsubscribe(callback: (value: number) => void) { + return listeners.delete(callback); + }, + publish(value: number) { + for (const listener of [...listeners]) listener(value); + }, + }; + let received = 0; + const page = dduiPage("事件订阅", (ctx) => { + ctx.subscribe(signal, (value) => { + if (value === -1) unexpectedCalls++; + received++; + }); + }); + + for (let i = 0; i < 20; i++) { + DDUI.open(player, page); + await settle(2); + expect(listeners.size).toBe(1); + signal.publish(i); + expect(received).toBe(i + 1); + + lastForm().playerClose(); + await settle(2); + expect(listeners.size).toBe(0); + signal.publish(-1); + expect(unexpectedCalls).toBe(0); + } + expect(DDUI.stats().sessions).toBe(0); + }); + + it("服务器周期性同步不会触发玩家输入回调", async () => { + const player = createPlayer(); + const calls: number[] = []; + let ctxRef: DDUIContext | undefined; + let volume: any; + + const page = dduiPage("同步", (ctx) => { + ctxRef = ctx; + volume = ctx.number(0); + ctx.onChange(volume, (value) => calls.push(value)); + }); + + DDUI.open(player, page); + await settle(); + + for (let i = 1; i <= 20; i++) ctxRef!.set(volume, i); + expect(volume.getData()).toBe(20); + expect(calls).toEqual([]); + + volume.setData(21); + expect(calls).toEqual([21]); + + lastForm().playerClose(); + await settle(); + }); + + it("反复打开关闭不会累积订阅或页面资源", async () => { + const player = createPlayer(); + const listeners = new Set<(value: void) => void>(); + const signal = { + subscribe(callback: (value: void) => void) { + listeners.add(callback); + return () => listeners.delete(callback); + }, + }; + let builds = 0; + + const page = dduiPage("循环", (ctx) => { + builds++; + ctx.subscribe(signal, () => {}); + }); + + for (let i = 0; i < 30; i++) { + DDUI.open(player, page); + await settle(2); + expect(listeners.size).toBe(1); + + lastForm().playerClose(); + await settle(2); + expect(listeners.size).toBe(0); + } + + expect(builds).toBe(30); + expect(MockForm.all).toHaveLength(30); + }); + + it("ui.subscribe 订阅原生 Observable:关闭后真正退订,不再留监听", async () => { + const player = createPlayer(); + const shared = new ui.MockObservable("a"); + let calls = 0; + + const page = dduiPage("原生订阅", (ctx) => { + ctx.subscribe(shared, () => calls++); + }); + + DDUI.open(player, page); + await settle(); + expect(shared.listenerCount).toBe(1); + + shared.setData("b"); + expect(calls).toBe(1); + + lastForm().playerClose(); + await settle(); + + // 关键:共享 Observable 上的监听必须归零,否则每次开页面都会累积 + expect(shared.listenerCount).toBe(0); + shared.setData("c"); + expect(calls).toBe(1); + }); + + it("反复开关不会在共享 Observable 上累积监听", async () => { + const player = createPlayer(); + const shared = new ui.MockObservable(0); + const baseline = DDUI.stats().sessions; + const page = dduiPage("反复订阅", (ctx) => { + ctx.subscribe(shared, () => {}); + }); + + for (let i = 0; i < 20; i++) { + DDUI.open(player, page); + await settle(2); + expect(shared.listenerCount).toBe(1); + expect(DDUI.stats().sessions).toBe(baseline + 1); + + lastForm().playerClose(); + await settle(2); + expect(shared.listenerCount).toBe(0); + // 会话必须回到基线,否则就是会话对象泄漏 + expect(DDUI.stats().sessions).toBe(baseline); + expect(DDUI.stats().activePlayers).toBe(0); + } + }); + + it("关闭后清空页面级文本 Observable,不把长字符串留给原生表单", async () => { + const player = createPlayer(); + let label: any; + const page = dduiPage("文本页", (ctx) => { + label = ctx.string("x".repeat(500), { clientWritable: false }); + }); + + DDUI.open(player, page); + await settle(); + expect(label.getData()).toHaveLength(500); + + lastForm().playerClose(); + await settle(); + + expect(label.getData()).toBe(""); + expect(DDUI.active(player)).toBeUndefined(); + }); + + it("共享 ViewModel 用 retain 托管,关闭时只 release 不销毁", async () => { + const player = createPlayer(); + const viewModel = { + refs: 0, + disposed: false, + retain() { + this.refs++; + }, + release() { + this.refs--; + }, + dispose() { + this.disposed = true; + }, + }; + + const page = dduiPage("测试", (ctx) => { + ctx.retain(viewModel); + }); + + DDUI.open(player, page); + await settle(); + expect(viewModel.refs).toBe(1); + + lastForm().playerClose(); + await settle(); + expect(viewModel.refs).toBe(0); + expect(viewModel.disposed).toBe(false); + }); +}); + +// ===================================================== +describe("DDUI 表单栈与导航", () => { + function plainPage(name: string) { + return dduiPage(name, (ctx) => ctx.label(name)); + } + + it("open 会显示页面并按标题创建表单", async () => { + const player = createPlayer(); + + DDUI.open(player, plainPage("主页"), {}); + await settle(); + + expect(MockForm.all).toHaveLength(1); + expect(lastForm().title).toBe("主页"); + expect(lastForm().isShowing()).toBe(true); + expect(DDUI.active(player)).toBeDefined(); + expect(stackDepth(player)).toBe(1); + + lastForm().playerClose(); + await settle(); + }); + + it("push / back 保留父页面参数并重建页面状态", async () => { + const player = createPlayer(); + const builds: string[] = []; + let volume: any; + let parentUi: DDUIContext<{ volume: number }> | undefined; + + const child = dduiPage("子页", (ctx) => { + ctx.button("返回", () => ctx.back()); + }); + + const parent = dduiPage<{ volume: number }>("父页", (ctx) => { + builds.push(`parent:${ctx.args.volume}`); + parentUi = ctx; + volume = ctx.number(ctx.args.volume); + ctx.onChange(volume, (value) => { + ctx.args.volume = value; + }); + ctx.button("打开子页", () => ctx.push(child)); + }); + + DDUI.open(player, parent, { volume: 30 }); + await settle(); + const parentForm = lastForm(); + + volume.setData(45); + expect(parentUi!.args.volume).toBe(45); + + parentForm.click(0); + await settle(); + + expect(parentForm.isShowing()).toBe(false); + expect(lastForm().isShowing()).toBe(true); + expect(stackDepth(player)).toBe(2); + + lastForm().click(0); // 子页「返回」 + await settle(); + + expect(stackDepth(player)).toBe(1); + expect(builds).toEqual(["parent:30", "parent:45"]); + expect(lastForm().isShowing()).toBe(true); + expect(volume.getData()).toBe(45); + + lastForm().playerClose(); + await settle(); + }); + + it("子页面被玩家关闭时回退上一层,根页面关闭才清空栈", async () => { + const player = createPlayer(); + let builds = 0; + const child = dduiPage("子页", (ctx) => ctx.label("child")); + const parent = dduiPage("父页", (ctx) => { + builds++; + ctx.button("子页", () => ctx.push(child)); + }); + + DDUI.open(player, parent); + await settle(); + lastForm().click(0); + await settle(); + expect(stackDepth(player)).toBe(2); + const childForm = lastForm(); + + // 玩家按 ESC / 关闭按钮:只回退一层,父页面重建并重新显示 + childForm.playerClose(); + await settle(); + expect(childForm.isShowing()).toBe(false); + expect(stackDepth(player)).toBe(1); + expect(builds).toBe(2); + expect(lastForm().title).toBe("父页"); + expect(lastForm().isShowing()).toBe(true); + + // 根页面关闭:清空栈并结束界面 + lastForm().playerClose(); + await settle(); + expect(stackDepth(player)).toBe(0); + expect(DDUI.active(player)).toBeUndefined(); + }); + + it("快速连续点击只会执行一次导航", async () => { + const player = createPlayer(); + const child = plainPage("子页"); + const parent = dduiPage("父页", (ctx) => { + ctx.button("子页", () => ctx.push(child)); + }); + + DDUI.open(player, parent); + await settle(); + const form = lastForm(); + + form.click(0); + form.click(0); + form.click(0); + await settle(); + + expect(stackDepth(player)).toBe(2); + expect(MockForm.all).toHaveLength(2); + expect(DDUI.active(player)).toBeDefined(); + + // 子页关闭会回到父页;这里直接结束整个界面做清理 + formManager.close(player); + await settle(); + }); + + it("replace 不增加栈深度", async () => { + const player = createPlayer(); + const second = plainPage("第二页"); + const first = dduiPage("第一页", (ctx) => { + ctx.button("replace", () => ctx.replace(second)); + }); + + DDUI.open(player, first); + await settle(); + lastForm().click(0); + await settle(); + + expect(stackDepth(player)).toBe(1); + expect(lastForm().title).toBe("第二页"); + expect(lastForm().isShowing()).toBe(true); + + lastForm().playerClose(); + await settle(); + }); + + it("reset 清空栈并打开新页", async () => { + const player = createPlayer(); + const third = plainPage("第三页"); + const first = dduiPage("第一页", (ctx) => { + ctx.button("reset", () => ctx.reset(third)); + }); + + DDUI.open(player, first); + await settle(); + lastForm().click(0); + await settle(); + + expect(stackDepth(player)).toBe(1); + expect(lastForm().title).toBe("第三页"); + expect(lastForm().isShowing()).toBe(true); + + lastForm().playerClose(); + await settle(); + }); + + it("reopen 用当前参数重建当前页", async () => { + const player = createPlayer(); + let builds = 0; + const page = dduiPage("重开", (ctx) => { + builds++; + ctx.button("重建", () => ctx.reopen()); + }); + + DDUI.open(player, page); + await settle(); + expect(builds).toBe(1); + + lastForm().click(0); + await settle(); + expect(builds).toBe(2); + expect(stackDepth(player)).toBe(1); + + lastForm().playerClose(); + await settle(); + }); + + it("关闭后的按钮回调不会再次导航", async () => { + const player = createPlayer(); + const child = plainPage("子页"); + const parent = dduiPage("父页", (ctx) => { + ctx.button("子页", () => ctx.push(child)); + }); + + DDUI.open(player, parent); + await settle(); + const form = lastForm(); + const onClick = form.buttons()[0].onClick; + + form.playerClose(); + await settle(); + expect(DDUI.active(player)).toBeUndefined(); + + onClick(); + await settle(); + // 顶层关闭后栈已重置,迟到的按钮回调也没有可操作页面 + expect(stackDepth(player)).toBe(0); + expect(MockForm.all).toHaveLength(1); + }); + + it("外部重复 open 会先关掉旧界面,不会有两个表单抢 UI", async () => { + const player = createPlayer(); + + DDUI.open(player, plainPage("A")); + await settle(); + const formA = lastForm(); + expect(formA.isShowing()).toBe(true); + + DDUI.open(player, plainPage("B")); + await settle(); + + expect(formA.isShowing()).toBe(false); + expect(lastForm().title).toBe("B"); + expect(lastForm().isShowing()).toBe(true); + expect(stackDepth(player)).toBe(1); + + lastForm().playerClose(); + await settle(); + }); + + it("两次 open 竞争时只有后一次生效", async () => { + const player = createPlayer(); + + DDUI.open(player, plainPage("A")); + DDUI.open(player, plainPage("B")); + await settle(); + + expect(MockForm.all.filter((form) => form.isShowing())).toHaveLength(1); + expect(lastForm().title).toBe("B"); + expect(stackDepth(player)).toBe(1); + + lastForm().playerClose(); + await settle(); + }); + + it("show 抛出异常时释放页面资源且不抛给调用方", async () => { + const player = createPlayer(); + let cleaned = 0; + const page = dduiPage("异常", (ctx) => { + ctx.onClose(() => cleaned++); + }); + + MockForm.showError = new Error("boom"); + DDUI.open(player, page); + await settle(); + + expect(cleaned).toBe(1); + expect(DDUI.active(player)).toBeUndefined(); + + DDUI.open(player, plainPage("正常")); + await settle(); + expect(lastForm().title).toBe("正常"); + lastForm().playerClose(); + await settle(); + }); + + it("show 同步抛出异常时也释放页面资源", async () => { + const player = createPlayer(); + let cleaned = 0; + const page = dduiPage("同步异常", (ctx) => { + ctx.onClose(() => cleaned++); + }); + + MockForm.showErrorSync = new Error("sync-boom"); + const errorSpy = vi.spyOn(LibLogger, "error").mockImplementation(() => {}); + DDUI.open(player, page); + await settle(); + + expect(cleaned).toBe(1); + expect(DDUI.active(player)).toBeUndefined(); + expect(MockForm.all.filter((form) => form.isShowing())).toHaveLength(0); + errorSpy.mockRestore(); + + // 同步异常不能把栈/会话留在“显示中”,后续还能正常打开 + DDUI.open(player, plainPage("正常")); + await settle(); + expect(lastForm().title).toBe("正常"); + lastForm().playerClose(); + await settle(); + }); + + it("按钮异步回调的拒绝被捕获,不产生未处理拒绝", async () => { + const player = createPlayer(); + const page = dduiPage("异步异常", (ctx) => { + ctx.button("go", async () => { + throw new Error("async-boom"); + }); + }); + + const errorSpy = vi.spyOn(LibLogger, "error").mockImplementation(() => {}); + DDUI.open(player, page); + await settle(); + lastForm().click(0); + await flush(); + await flush(); + + expect(errorSpy).toHaveBeenCalledWith("DDUI 按钮回调异常", expect.any(Error)); + errorSpy.mockRestore(); + + lastForm().playerClose(); + await settle(); + }); + + it("作用域异步清理的拒绝被捕获", async () => { + const warnSpy = vi.spyOn(LibLogger, "warn").mockImplementation(() => {}); + const scope = new DDScope(); + scope.own(async () => { + throw new Error("cleanup-boom"); + }); + scope.dispose(); + await flush(); + await flush(); + + expect(warnSpy).toHaveBeenCalledWith("DDUI 清理失败: cleanup", expect.any(Error)); + warnSpy.mockRestore(); + }); + + it("DDUI.open 支持逐次 delay:到点前不构建,到点后显示", async () => { + const player = createPlayer(); + let builds = 0; + const page = dduiPage("延迟", (ctx) => { + builds++; + ctx.label("x"); + }); + + DDUI.open(player, page, undefined, 4); + await settle(3); + expect(builds).toBe(0); + expect(MockForm.all).toHaveLength(0); + + await settle(2); + expect(builds).toBe(1); + expect(lastForm().isShowing()).toBe(true); + + lastForm().playerClose(); + await settle(); + }); + + it("顶层关闭后立即重置表单栈,args 立刻释放", async () => { + const player = createPlayer(); + const heavy = { payload: new Array(64).fill("x") }; + const page = dduiPage("清理", (ctx) => ctx.label("x")); + + DDUI.open(player, page, heavy as any); + await settle(); + expect(formStackManager.getTop(player)?.args).toBe(heavy); + + lastForm().playerClose(); + await settle(); + + expect(stackDepth(player)).toBe(0); + expect(formStackManager.getTop(player)).toBeUndefined(); + }); + + it("UserBusy 不重试:本次打开直接结束", async () => { + const player = createPlayer(); + let builds = 0; + const page = dduiPage("忙", (ctx) => { + builds++; + ctx.label("busy"); + }); + + MockForm.busyCount = 5; + DDUI.open(player, page); + await settle(20); + + expect(builds).toBe(1); + expect(MockForm.all).toHaveLength(1); + expect(MockForm.all.every((form) => !form.isShowing())).toBe(true); + expect(DDUI.active(player)).toBeUndefined(); + }); + + it("玩家离线时不构建表单", async () => { + const player = createPlayer(); + (player as unknown as { isValid: boolean }).isValid = false; + let builds = 0; + + DDUI.open( + player, + dduiPage("离线", (ctx) => { + builds++; + ctx.label("x"); + }) + ); + await settle(); + + expect(builds).toBe(0); + expect(MockForm.all).toHaveLength(0); + }); + + it("构建时主动关闭不会显示空表单", async () => { + const player = createPlayer(); + const page = dduiPage("空页", (ctx) => { + ctx.close(); + }); + + DDUI.open(player, page); + await settle(); + + expect(MockForm.all.filter((form) => form.isShowing())).toHaveLength(0); + expect(DDUI.active(player)).toBeUndefined(); + }); + + it("导航排队期间被外部关闭时,旧页面不会再显示", async () => { + const player = createPlayer(); + const child = plainPage("子页"); + const parent = dduiPage("父页", (ctx) => { + ctx.button("子页", () => ctx.push(child)); + }); + + DDUI.open(player, parent); + await settle(); + lastForm().click(0); + await flush(); + + // 子页在 2 tick 后才会显示,这之前清空栈 + formManager.close(player); + await settle(6); + + expect(MockForm.all).toHaveLength(1); + expect(MockForm.all.filter((form) => form.isShowing())).toHaveLength(0); + expect(formManager.isShowing(player)).toBe(false); + }); + + it("点击跳转后页面立即失效,订阅与状态写入都已停止", async () => { + const player = createPlayer(); + const child = plainPage("子页"); + let closedInClick: boolean | undefined; + let volume: any; + const calls: number[] = []; + + const parent = dduiPage("父页", (ctx) => { + volume = ctx.number(0); + ctx.onChange(volume, (value) => calls.push(value)); + ctx.button("子页", () => { + ctx.push(child); + closedInClick = ctx.closed; + }); + }); + + DDUI.open(player, parent); + await settle(); + volume.setData(5); + expect(calls).toEqual([5]); + + lastForm().click(0); + expect(closedInClick).toBe(true); + expect(volume.listenerCount).toBe(0); + + await settle(); + // 旧页面的 Observable 再变化也不会触发回调 + volume.setData(6); + expect(calls).toEqual([5]); + expect(lastForm().title).toBe("子页"); + }); + + it("构建时 push 新页面会直接显示新页面(构建期重定向)", async () => { + const player = createPlayer(); + const target = plainPage("目标"); + const page = dduiPage("构建期跳转", (ctx) => { + ctx.push(target); + }); + + DDUI.open(player, page); + await settle(); + + expect(stackDepth(player)).toBe(2); + expect(lastForm().title).toBe("目标"); + expect(lastForm().isShowing()).toBe(true); + expect(MockForm.all.filter((form) => form.isShowing())).toHaveLength(1); + }); + + it("重复关闭安全,清理只执行一次", async () => { + const player = createPlayer(); + let cleaned = 0; + const page = dduiPage("关闭", (ctx) => { + ctx.onClose(() => cleaned++); + }); + + DDUI.open(player, page); + await settle(); + + formManager.close(player); + formManager.close(player); + await settle(); + + expect(cleaned).toBe(1); + expect(MockForm.all.every((form) => !form.isShowing())).toBe(true); + }); +}); + +// ===================================================== +describe("DDUI 与传统表单混合入栈", () => { + it("DDUI 页面 push 传统表单,传统表单 back 回到 DDUI 页面", async () => { + const player = createPlayer(); + const log: string[] = []; + const child = makeLegacyForm((ctx) => ctx.back(), log); + const parent = dduiPage("父页", (ctx) => { + log.push("parent:build"); + ctx.button("传统表单", () => ctx.push(child)); + }); + + DDUI.open(player, parent); + await settle(); + expect(log).toEqual(["parent:build"]); + + lastForm().click(0); + await settle(); + + expect(log).toContain("legacy:show"); + expect(stackDepth(player)).toBe(2); + + legacyInstances[legacyInstances.length - 1].playerClose(); + await settle(); + + expect(log).toContain("legacy:handler"); + expect(stackDepth(player)).toBe(1); + expect(log.filter((item) => item === "parent:build")).toHaveLength(2); + expect(lastForm().isShowing()).toBe(true); + + lastForm().playerClose(); + await settle(); + }); + + it("传统表单可以 push DDUI 页面", async () => { + const player = createPlayer(); + const log: string[] = []; + const target = dduiPage("目标页", (ctx) => { + log.push("target:build"); + ctx.label("target"); + }); + const legacy = makeLegacyForm((ctx) => ctx.push(target)); + + formManager.open(player, legacy); + await settle(); + legacyInstances[legacyInstances.length - 1].playerClose(); + await settle(); + + expect(log).toContain("target:build"); + expect(lastForm().title).toBe("目标页"); + expect(lastForm().isShowing()).toBe(true); + expect(stackDepth(player)).toBe(2); + + lastForm().playerClose(); + await settle(); + }); + + it("传统表单异步 handler 迟到时不能修改后来打开的页面或关闭它", async () => { + const player = createPlayer(); + let releaseHandler!: () => void; + const pending = new Promise((resolve) => { releaseHandler = resolve; }); + const unwanted = dduiPage("过期跳转", (ctx) => ctx.label("旧任务")); + const oldForm: SAPIProForm = { + builder() { + const form = new ui.MockActionForm(); + legacyInstances.push(form); + return form as any; + }, + async handler(_response, ctx) { + await pending; + ctx.push(unwanted); + ctx.close(); + }, + }; + + formManager.open(player, oldForm); + await settle(); + legacyInstances[legacyInstances.length - 1].playerClose(); + await settle(); + + const latest = dduiPage("最新页面", (ctx) => ctx.label("current")); + DDUI.open(player, latest); + await settle(); + releaseHandler(); + await settle(); + + expect(stackDepth(player)).toBe(1); + expect(formStackManager.getTop(player)?._form).toBe(latest); + expect(lastForm().title).toBe("最新页面"); + expect(lastForm().isShowing()).toBe(true); + lastForm().playerClose(); + await settle(); + }); + + it("过期 beforeBuild 的迟到导航不能污染新表单栈", async () => { + const player = createPlayer(); + let releaseBeforeBuild!: () => void; + const pending = new Promise((resolve) => { releaseBeforeBuild = resolve; }); + const unwanted = dduiPage("无效跳转", (ctx) => ctx.label("旧任务")); + const stale: SAPIProForm = { + async beforeBuild(ctx) { + await pending; + ctx.push(unwanted); + }, + builder() { + const form = new ui.MockActionForm(); + legacyInstances.push(form); + return form as any; + }, + handler() {}, + }; + formManager.open(player, stale); + await settle(2); + + const latest = dduiPage("最新页面", (ctx) => ctx.label("current")); + DDUI.open(player, latest); + await settle(); + releaseBeforeBuild(); + await settle(); + + expect(stackDepth(player)).toBe(1); + expect(formStackManager.getTop(player)?._form).toBe(latest); + expect(lastForm().isShowing()).toBe(true); + lastForm().playerClose(); + await settle(); + }); + + it("旧传统表单延迟结算不能清除新传统表单的 showing 状态", async () => { + const player = createPlayer(); + const first = makeLegacyForm(() => {}); + const second = makeLegacyForm(() => {}); + formManager.open(player, first); + await settle(); + const firstInstance = legacyInstances[legacyInstances.length - 1]; + + // 旧 show() 尚未结算,但新页面已经显示。 + formManager.open(player, second); + await settle(); + const secondInstance = legacyInstances[legacyInstances.length - 1]; + expect(secondInstance).not.toBe(firstInstance); + expect(formManager.isShowing(player)).toBe(true); + + // 此时旧 show() 才完成,不能覆盖新页面的 showing 状态。 + firstInstance.playerClose(); + await settle(); + expect(formManager.isShowing(player)).toBe(true); + expect(stackDepth(player)).toBe(1); + + secondInstance.playerClose(); + await settle(); + expect(formManager.isShowing(player)).toBe(false); + }); + + it("DDUI / 传统表单多层混合入栈后可以逐层返回", async () => { + const player = createPlayer(); + const log: string[] = []; + const pageB = dduiPage("B", (ctx) => { + log.push("B"); + ctx.button("返回", () => ctx.back()); + }); + // 第一次关闭进入 B,第二次关闭返回 A(模拟“子页面返回”与“关闭返回上级”两种语义) + let legacyCloses = 0; + const legacy = makeLegacyForm((ctx) => { + legacyCloses++; + if (legacyCloses === 1) ctx.push(pageB); + else ctx.back(); + }, log); + let buildsA = 0; + const pageA = dduiPage("A", (ctx) => { + buildsA++; + log.push("A"); + ctx.button("传统表单", () => ctx.push(legacy)); + }); + + DDUI.open(player, pageA); + await settle(); + expect(stackDepth(player)).toBe(1); + + lastForm().click(0); // A → 传统表单 + await settle(); + expect(stackDepth(player)).toBe(2); + expect(log).toContain("legacy:show"); + + legacyInstances[legacyInstances.length - 1].playerClose(); // 传统表单 → B + await settle(); + expect(stackDepth(player)).toBe(3); + expect(lastForm().title).toBe("B"); + + lastForm().click(0); // B → 返回传统表单 + await settle(); + expect(stackDepth(player)).toBe(2); + expect(log.filter((item) => item === "legacy:show")).toHaveLength(2); + + legacyInstances[legacyInstances.length - 1].playerClose(); // 传统表单 → 返回 A + await settle(); + expect(stackDepth(player)).toBe(1); + expect(lastForm().title).toBe("A"); + expect(buildsA).toBe(2); + expect(lastForm().isShowing()).toBe(true); + + lastForm().playerClose(); + await settle(); + }); +}); diff --git a/core/test/ddui/writeGuard.test.ts b/core/test/ddui/writeGuard.test.ts new file mode 100644 index 0000000..a931789 --- /dev/null +++ b/core/test/ddui/writeGuard.test.ts @@ -0,0 +1,100 @@ +// ===================================================== +// WriteGuard - 程序写入 / 客户端输入语义 +// ===================================================== +import { describe, expect, it, vi } from "vitest"; + +vi.mock("@minecraft/server-ui", () => ({ + ObservableBoolean: class {}, + ObservableNumber: class {}, + ObservableString: class {}, +})); + +import { WriteGuard } from "../../src/Form/ddui/observable"; + +/** 与原生 Observable 语义一致:同值不通知、通知同步派发 */ +class FakeObservable { + private listeners = new Set<(value: T) => void>(); + constructor(private value: T) {} + getData() { + return this.value; + } + setData(value: T) { + if (Object.is(value, this.value)) return; + this.value = value; + for (const listener of [...this.listeners]) listener(value); + } + subscribe(callback: (value: T) => void) { + this.listeners.add(callback); + return callback; + } + unsubscribe(callback: (value: T) => void) { + return this.listeners.delete(callback); + } +} + +function setup(initial: T) { + const guard = new WriteGuard(); + const observable = new FakeObservable(initial); + const events: Array<{ value: T; own: boolean }> = []; + observable.subscribe((value) => events.push({ value, own: guard.isOwnWrite(observable) })); + return { guard, observable, events }; +} + +describe("WriteGuard", () => { + it("同步触发的回调用程序写入标记屏蔽", () => { + const { guard, observable, events } = setup(0); + guard.write(observable, 50); + expect(events).toEqual([{ value: 50, own: true }]); + }); + + it("写入相同值不产生通知", () => { + const { guard, observable, events } = setup(0); + guard.write(observable, 0); + expect(events).toEqual([]); + }); + + it("写入返回后,客户端输入不会被抑制", () => { + const { guard, observable, events } = setup(0); + guard.write(observable, 50); + // 客户端通过原生通道写入(不经过 guard) + observable.setData(51); + expect(events).toEqual([ + { value: 50, own: true }, + { value: 51, own: false }, + ]); + }); + + it("连续程序写入的每一次自身通知都被屏蔽", () => { + const { guard, observable, events } = setup(0); + guard.write(observable, 10); + guard.write(observable, 20); + guard.write(observable, 30); + expect(events.map((event) => event.own)).toEqual([true, true, true]); + observable.setData(10); + expect(events.at(-1)).toEqual({ value: 10, own: false }); + }); + + it("写入过程中业务代码嵌套写入另一个值也按程序写入处理", () => { + const { guard, observable, events } = setup(0); + // 模拟 computed / 联动:程序写入触发的回调里再写一次 + observable.subscribe(() => { + if (observable.getData() === 50 && !guard.isOwnWrite(observable)) return; + }); + guard.write(observable, 50); + guard.write(observable, 60); + expect(events.map((event) => event.value)).toEqual([50, 60]); + expect(events.every((event) => event.own)).toBe(true); + }); + + it("文本:程序同步后清空再输入相同文本都会正常触发", () => { + const { guard, observable, events } = setup(""); + guard.write(observable, "abc"); + observable.setData(""); + observable.setData("abc"); + expect(events.map((event) => `${event.value}:${event.own}`)).toEqual([ + "abc:true", + ":false", + "abc:false", + ]); + }); +}); diff --git a/skills/sapi-pro-dev/reference/form.md b/skills/sapi-pro-dev/reference/form.md index 63db71a..f412b81 100644 --- a/skills/sapi-pro-dev/reference/form.md +++ b/skills/sapi-pro-dev/reference/form.md @@ -177,3 +177,48 @@ builder ↓ handler ``` + +--- + +# DDUI(CustomForm 响应式表单) + +需要滑块/输入框/开关实时联动、页面栈或多页面跳转时优先使用 DDUI,不要手写 `CustomForm` 会话。 + +```ts +import { DDUI } from "sapi-pro"; + +const Page = DDUI.page<{ piano: PianoRuntime }>("标题", (ui, args) => { + const volume = ui.number(100); // 默认 clientWritable + const label = ui.computed([volume], () => `音量 ${volume.getData()}%`); + + ui.set(volume, args.piano.volume); // 服务器同步,不触发 onChange + ui.onChange(volume, (v) => args.piano.setVolume(v)); + + ui.subscribe(args.piano.disposedSignal, () => ui.close()); + ui.onClose(() => args.piano.flush()); + ui.retain(sharedViewModel); // 关闭时自动 release + + ui.label(label) + .slider("音量", volume, 0, 200, { step: 1 }) + .button("子页", () => ui.push(ChildPage, { piano: args.piano })) + .closeButton(); +}); + +DDUI.open(player, Page, { piano }); +``` + +要点: + +- 页面关闭时自动释放:Observable 订阅、`ui.subscribe` 的外部信号、`ui.timeout` / `ui.interval`、`ui.retain`。 +- 导航:`ui.push / back / replace / reopen / reset / close`,默认 0 tick(下一游戏刻)显示,可按需传 `delay`,禁止再写“关闭 + runTimeout + 重新 open”。 +- 传统表单与 DDUI 共用一个表单栈:`ctx.push(dduiPage, args)` 和 `ui.push(CommonForm, args)` 都可用。 +- `ui.set()` 用于程序写入(同步服务器状态、纠正越界值),不触发 `ui.onChange`;值不变时不写回。 +- `ui.onChange()` 响应其余变化(客户端输入或业务代码直接 `setData`)。 +- 控件方法返回 `ui` 本身,链式调用不会绕过按钮保护;需要原生表单用 `ui.form`。 +- `DDUI.open()` 会自动关闭该玩家正在显示的旧表单;`UserBusy` 表示本次无法显示,直接结束、不重试。 +- 页面构建函数里 `ui.close()` 会取消本次显示,`ui.push()` 可以构建期重定向。 +- `DDUI.page()` 的返回值也是 `SAPIProForm`,可以直接 `formManager.open()`。 +- 点击跳转后 `ui.closed` 立即为 true,订阅/定时器已释放,异步回调不要再写状态。 + +详细文档:`tutorial/ddui.md`。 + diff --git a/tutorial/README.md b/tutorial/README.md index b26b6ac..37dfaf9 100644 --- a/tutorial/README.md +++ b/tutorial/README.md @@ -8,6 +8,8 @@ - [表单系统入门](form.md) +- [DDUI 响应式表单](ddui.md) + - [数据存储](database.md) - [事件订阅](event.md) diff --git a/tutorial/ddui.md b/tutorial/ddui.md new file mode 100644 index 0000000..82dfba2 --- /dev/null +++ b/tutorial/ddui.md @@ -0,0 +1,197 @@ +# DDUI 响应式表单 + +DDUI 是 `@minecraft/server-ui` 的 `CustomForm` 封装:直接使用原生 Observable 与原生控件,只补齐三件事: + +1. 页面级资源托管(订阅、定时器、外部信号、ViewModel 引用自动释放); +2. 派生状态(`ui.computed` / `ui.watch`,不需要手写多个订阅); +3. 真正的表单栈(`push` / `back` / `replace` / `reopen` / `reset` / `close`),并和传统表单共用同一个栈。 + +不需要理解生命周期概念:**页面关闭时,页面里登记的东西都会自动释放**。 + +--- + +## 最小例子 + +```ts +import { DDUI } from "sapi-pro"; + +export const SettingsPage = DDUI.page<{ save: (volume: number) => void }>( + "设置", + (ui, args) => { + // 默认 clientWritable:绑定到输入控件后可被玩家修改 + const volume = ui.number(100); + + // 服务器写入(不会触发下面的 onChange) + ui.set(volume, 100); + + // 派生文本:依赖变化时自动重算 + const label = ui.computed([volume], () => `当前音量:${volume.getData()}%`); + + // 玩家输入:关闭页面后不会再执行 + ui.onChange(volume, (value) => args.save(value)); + + ui.label(label).slider("音量", volume, 0, 200, { step: 1 }); + ui.closeButton(); + } +); + +DDUI.open(player, SettingsPage, { save: (v) => piano.setVolume(v) }); +``` + +--- + +## 页面与参数 + +```ts +const page = DDUI.page("标题", (ui, args) => { ... }); +DDUI.open(player, page, args); // 清空表单栈后打开 +ui.push(page, args); // 入栈打开(可返回) +``` + +- 标题可以是字符串,也可以是 `(args) => string`。 +- `args` 是**同一个对象**:返回上一页时原样传回,适合保存“页面参数”和需要跨页面保留的状态。 +- 页面里的 Observable 属于页面:返回后重新构建(重新调用 build),因此页面本地状态会重建。 + 需要跨页面保留的状态请写进 `args` 或共享 ViewModel。 +- `DDUI.page()` 的返回值同时是一个 `SAPIProForm`,可以直接交给 `formManager.open()`、传统表单的 `ctx.push()`。 + +--- + +## 状态 API + +| 方法 | 说明 | +|---|---| +| `ui.number(initial)` | 创建 `ObservableNumber`(默认 `clientWritable: true`) | +| `ui.string(initial)` | 创建 `ObservableString` | +| `ui.boolean(initial)` | 创建 `ObservableBoolean` | +| `ui.computed(deps, fn)` | 由其他 Observable 派生的只读 Observable,值不变不写回;依赖必须显式列出,不做自动追踪 | +| `ui.onChange(obs, fn)` | 变化回调(客户端输入或业务代码直接 `setData`);`ui.set()` 不触发 | +| `ui.watch(deps, fn, immediate?)` | 依赖变化时执行副作用(默认立即执行一次) | +| `ui.set(obs, value)` | 程序写入:不触发 `onChange`,值不变时不写回、不通知 | +| `ui.get(obs)` | 读取当前值 | + +`ui.number/string/boolean` 的第二个参数可传 `{ clientWritable: false }`,用于只由服务器更新的值。 + +> 原生 Observable 只在值真正变化时通知订阅者。因此 `ui.set()` 只需要在写入期间做同步标记, +> 就能把自己触发的回调排除掉;不需要记录“最后写入值”,也不会误吞玩家随后的合法输入。 +> **同步服务器状态一律用 `ui.set()`;直接 `setData()` 会被当作一次业务变更。** + +--- + +## 控件 + +`ui.label / header / toggle / slider / dropdown / textField / image / divider / spacer / button / closeButton` +参数与原生 `CustomForm` 完全一致,返回 `ui` 本身,可以继续链式调用(按钮保护不会因为链式调用丢失)。 +需要原生表单对象时使用 `ui.form`。 + +```ts +ui.label(status) + .toggle("显示文字", visible, { visible: hasScreen }) + .slider("字号", scale, 25, 250, { step: 1, visible: hasScreen }) + .button("返回", () => ui.back()); +``` + +`ui.button` 的回调自带保护:页面已关闭、或本次显示内已经触发过导航时,后续点击会被忽略(防连点重复入栈)。 + +--- + +## 资源托管 + +```ts +ui.onClose(() => piano.flushSettings(id)); // 关闭时执行一次 +ui.subscribe(piano.disposedSignal, () => ui.close()); // 外部 Signal / 事件 +ui.timeout(() => { ... }, 5); // 关闭自动取消,关闭后不执行 +ui.interval(() => { ... }, 20); +ui.own(() => something.dispose()); // 任意清理函数 +ui.retain(viewModel); // retain() 现在,release() 关闭时 +``` + +- 所有清理按登记顺序倒序执行,单个清理抛错不影响其它清理;重复关闭只执行一次。 +- 页面关闭后,`ui.onChange` / `ui.subscribe` 的回调不会再执行。 +- **共享对象不会被销毁**:`ui.retain(vm)` 只做引用计数,是否销毁由对象自己的所有者决定。 + +--- + +## 导航 + +| 方法 | 说明 | +|---|---| +| `ui.push(form, args?, delay?)` | 入栈打开(DDUI 页面或传统表单都可以) | +| `ui.back(delay?)` | 返回上一页;栈为空时关闭界面 | +| `ui.replace(form, args?)` | 替换当前页,栈深度不变 | +| `ui.reopen()` | 用当前参数重建当前页 | +| `ui.reset(form, args?)` | 清空栈并打开新页 | +| `ui.close()` | 关闭界面并清空栈 | + +```ts +const ScorePage = DDUI.page("曲谱", (ui) => { + ui.button("返回", () => ui.back()); // 不需要 runTimeout / 重新 open +}); +``` + +- 跳转会先修改表单栈再关闭当前表单,由 `formManager` 在下一个调度点显示目标页(默认 0 tick,即下一游戏刻;需要时可传 `delay`)。 +- `UserBusy` 表示本次无法显示,页面直接结束,不自动重试。 +- 同一玩家永远只有一个界面:`DDUI.open()` / `formManager.open()` 会先关掉正在显示的旧表单。 +- **混合导航**:传统 `CommonForm` 页面里 `ctx.push(dduiPage, args)`,DDUI 页面里 `ui.push(CommonForm, args)`,`back()` 都能正确回到上一页。 + +```ts +// DDUI → 传统表单 +ui.button("点歌", () => ui.push(MidiListForm, { midiPlayer, p: 1 })); + +// 传统表单 → DDUI +onSubmit(data, ctx) { + ctx.push(SomeDDUIPage, { id: data.id }); +} +``` + +> 传统表单回调里不要再用“关闭 + `system.runTimeout` 再打开”的写法,直接入栈即可。 + +--- + +## 生命周期与失效 + +- `show()` 抛异常、玩家离线、表单被强制关闭、`UserBusy` 都是正常结束路径:页面资源会释放,不会抛给调用方,也不会留下显示中的空表单。 +- 页面构建函数里调用 `ui.close()` 会取消本次显示;调用 `ui.push()` 会在构建完成后直接显示新页面(适合“目标对象已失效,跳到提示页”)。 +- 点击跳转后 `ui.closed` **立即**变为 true,订阅与定时器已经释放;异步回调里应提前退出: + +```ts +ui.onChange(search, async (keyword) => { + const result = await searchRemote(keyword); + if (ui.closed) return; // 页面已关闭,别把旧结果写进新页面 + status.setData(result); +}); +``` + +- 迟到的导航不会生效:每次展示都有导航代际,旧 `show()`、旧定时器、被替换页面的回调都被丢弃。 + +--- + +## 原生限制(需要在实机确认) + +- `CustomForm` 的 `show()` 不需要 `player` 参数,返回关闭原因(`ClientClosed` / `ServerClosed` / `UserBusy`),失败时抛 `FormVisibilityError` / `PlayerLeftError` 等。 +- 原生 Observable 的 `subscribe` 是同步回调,`setData` 写入相同值不会通知。 +- 关闭后继续使用已关闭表单的组件会抛错;DDUI 已避免这种调用,但自定义原生代码需要自行判断 `ui.closed`。 +- 客户端写入来源、`Observable` 的 `dispose` 都不存在,不要依赖。 +- 传统表单(`ActionFormData` 等)没有服务端 `close()`,只能通过 `uiManager.closeAllForms(player)` 关闭;DDUI 只在重新打开界面时使用它。 + +--- + +## 从手写 Session 迁移 + +手写模式(每页重复): + +```ts +private cleanups: Array<() => void> = []; +private opening = false; +async show() { this.opening = true; try { await form.show(); } finally { this.opening = false; this.close(); } } +close() { for (const c of this.cleanups.splice(0)) c(); } +``` + +DDUI 模式: + +```ts +DDUI.page("标题", (ui, args) => { + ui.onChange(value, ...); // 关闭自动退订 + ui.timeout(..., 20); // 关闭自动取消 +}); +DDUI.open(player, page, args); // 并发、重复打开、异常、离线由框架处理 +```