on / once / off 接口定义；BaseEvent / BaseExtendableEvent 事件对象。preventDefault / waitUntil）、Gesture Events, State Events, Pano Events, Model Events, Lifecycle Events.preventDefault 拦截默认行为；使用 waitUntil 延迟点位切换。Definition: Five, EventTypes
Five 实例提供了以下方法来管理事件监听：
注册持久化事件监听器。
five.on(
name: string,
callback: (...args: any[]) => void,
once?: boolean
): () => void
false。注册一次性事件监听器（触发一次后自动销毁）。
five.once(
name: string,
callback: (...args: any[]) => void
): () => void
取消事件监听。
five.off(
name?: string,
callback?: (...args: any[]) => void
): void
Definition: BaseEvent / BaseExtendableEvent
Five 中所有事件回调的参数都是一个 Event 对象，分为两种基础类型：
所有事件的基础接口，包含以下属性和方法：
interface BaseEvent {
/** 事件类型名称 */
type: string;
/** 事件触发时的时间戳 */
timeStamp: number;
/** 阻止事件的默认行为 */
preventDefault(): void;
/** 是否已调用过 preventDefault */
readonly defaultPrevented: boolean;
}
继承自 BaseEvent，额外提供 waitUntil 方法，用于在事件处理中插入异步等待逻辑：
interface BaseExtendableEvent extends BaseEvent {
waitUntil(f: Promise<any>): void;
}
目前 pano.prepare 事件使用 BaseExtendableEvent（对应 PanoPrepareEvent），其余事件均基于 BaseEvent。
调用 event.preventDefault() 可以阻止事件的默认行为。Five 内部会在触发事件后检查 event.defaultPrevented，若为 true 则跳过后续的默认处理逻辑。
比如：
gesture.tap：阻止默认的点位跳转或相机弹跳动画。intersect.update：阻止默认的交互高亮行为。// 示例：阻止点击时的默认点位跳转
five.on("gesture.tap", (event) => {
if (shouldBlockNavigation()) {
event.preventDefault();
// 执行自定义逻辑
showCustomMenu(event);
}
});
// 示例：阻止拖拽时的默认相机旋转
five.on("gesture.pan", (event) => {
event.preventDefault();
// 用拖拽手势实现自定义交互（如绘制标注）
drawAnnotation(event);
});
waitUntil(promise) 仅在 ExtendableEvent 上可用。调用后，Five 会等待传入的 Promise 完成后再继续后续流程。可多次调用，所有 Promise 会被并行等待。
目前仅 pano.prepare 事件支持 waitUntil。
// 示例：在切换点位前预加载资源
five.on("pano.prepare", (event) => {
// 等待自定义资源加载完成后再继续点位切换
event.waitUntil(
loadCustomResources(event.pano)
);
// 可以多次调用，所有 Promise 会被并行等待
event.waitUntil(
preloadTextures(event.pano)
);
});
// 示例：通过 waitUntil reject 来取消走点
five.on("pano.prepare", (event) => {
event.waitUntil(
showConfirmDialog("是否前往该点位？").then((confirmed) => {
if (!confirmed) {
throw new Error("用户取消走点");
}
})
);
});
注意:
preventDefault和waitUntil必须在事件回调的同步执行阶段调用，不能放在await之后。
Five 的事件系统将事件主要分为以下几类：
监听用户的鼠标或触摸操作。
gesture.tap: 点击/轻触。gesture.dbltap: 双击/双击轻触。gesture.press: 长按。gesture.pan: 平移/拖拽。gesture.pinch: 缩放（双指或滚轮）。gesture.mousewheel: 鼠标滚轮滚动。gesture.mousemove: 鼠标移动。监听全景图的点位切换过程。
pano.prepare: 准备切换到新点位。这是一个 ExtendableEvent，支持通过 waitUntil(promise) 延迟后续加载流程（如预加载资源），以及通过 preventDefault() 取消本次走点。pano.arrived: 成功到达新点位（移动动画结束）。pano.moving: 正在移动到新点位（动画进行中）。pano.willChange: 即将发生点位变更（旧版兼容）。pano.error: 点位加载或移动出错。监听 Five 内部状态（State）的变化，常用于 UI 同步或数据记录。
state.change: 状态发生变更（可能是用户操作或代码触发）。currentState.change: 当前状态发生变更（通常指即时状态）。state.synced: 状态已同步。监听场景数据（Work）或模型（Model）的加载生命周期。
works.load: Work 数据开始加载。works.ready: Work 数据加载完成且 Controller 就绪。model.load: 模型开始加载。models.load: 所有模型加载完成。监听每一帧的渲染过程。
render: 每一帧渲染后触发。render.prepare: 每一帧渲染前触发。监听点击事件并打印日志。
import { Five } from "@realsee/five";
const five = new Five();
// 监听点击事件
five.on("gesture.tap", (event) => {
console.log("User tapped at:", event);
});
// 监听点位变更完成
five.on("pano.arrived", (event) => {
console.log("Arrived at pano:", event.pano);
});
使用 once 监听一次性初始化事件，使用返回值取消监听。
// 1. 等待首次数据加载完成
five.once("works.ready", () => {
console.log("Five is ready!");
// 执行初始化逻辑，如自动巡游
});
// 2. 动态绑定与解绑
const onRender = () => {
// 每一帧执行的逻辑
updateUI();
};
// 开始监听
five.on("render", onRender);
// 在某个时刻取消监听（例如组件销毁时）
// five.off("render", onRender);
five.on("error", (err) => console.error(err)) 捕获全局错误。tags: [事件监听, 点击, 拖拽, 加载完成, 渲染回调, 生命周期, 回调, events, interaction, lifecycle, gesture, state, preventDefault, waitUntil, on, off, subscribe]