three-base 2.0.142 → 2.0.166

package/threeUtils.d.ts

@@ -1,53 +1,71 @@
-import { Box3, BufferGeometry, Clock, EventDispatcher, Material, Object3D, Vector3 } from "three";
-import type { ThreeUtilsEventTypeMap } from "./EventMap";
-declare class ThreeUtils extends EventDispatcher<ThreeUtilsEventTypeMap> {
-    constructor();
-    isProd: boolean;
-    isDev: boolean;
-    _timeTemp: number;
-    _accumulate: number;
-    _box3: Box3;
-    _size: Vector3;
-    _center: Vector3;
-    _clock: Clock;
-    requestAnimationFrame(): void;
-    private _keepZoomDoms;
-    /**
-     *计算需要保持比例的元素
-     */
-    private _computerDomZoom;
-    /**
-     * dom元素保持比例
-     */
-    keepZoom(dom: HTMLElement | null, width?: number, height?: number): void;
-    workList: Array<() => void>;
-    clock: Clock;
-    /**
-     * @param {() => void} [callback]
-     * @param {boolean} [first=true] 需要优先执行
-     */
-    addWork(work?: () => void, first?: boolean): void;
-    /**
-     *判断一个元素是否在页面上
-     */
-    inDocument(dom: ParentNode | null): boolean;
-    getCenter(object3d: Object3D | BufferGeometry): Vector3;
-    getSize(object3d: Object3D | BufferGeometry): Vector3;
-    alignBottom(object3d: Object3D | BufferGeometry, y?: number): void;
-    centerObject3D(object3d: Object3D | BufferGeometry): void;
-    center(object3d: Object3D | BufferGeometry): void;
-    scaleTo(object3d: Object3D | BufferGeometry, size?: number, key?: Array<"x" | "y" | "z">): void;
-    applyAllTranstion(object3d: Object3D): void;
-    exportGLB(input: Object3D, fileName?: string, maxTextureSize?: number): void;
-    exportUsdz(): void;
-    getVolume(geometry: BufferGeometry): number;
-    signedVolumeOfTriangle(p1: Vector3, p2: Vector3, p3: Vector3): number;
-    dipose(object3d: Object3D): void;
-    getSuffix(filename: string): string;
-    getFilename(url: string): string;
-    fileToBloburl(file: File): Promise<string>;
-    toMeshBasicMaterial<P extends Material | Material[]>(material: P): P;
-    toMeshLambertMaterial<P extends Material | Material[]>(material: P): P;
-}
-declare const threeUtils: ThreeUtils;
-export default threeUtils;
+import { Box3, BufferGeometry, Clock, EventDispatcher, Material, Object3D, Vector3 } from "three";
+import type { ThreeUtilsEventTypeMap } from "./EventMap";
+declare class ThreeUtils extends EventDispatcher<ThreeUtilsEventTypeMap> {
+    constructor();
+    isProd: boolean;
+    isDev: boolean;
+    _timeTemp: number;
+    _accumulate: number;
+    _box3: Box3;
+    _size: Vector3;
+    _center: Vector3;
+    _clock: Clock;
+    requestAnimationFrame(): void;
+    /**
+     * 等下一帧（**本库唯一的「等一帧」入口**，皇上 2026-10-09 旨）。
+     *
+     * ⛔ 为什么不再用原生 `await new Promise(r => requestAnimationFrame(r))`：
+     *   那是**独立于本类主循环的另一个 rAF 回调**，同一帧里与主循环并行跑 ⇒ 每帧多一次调度，
+     *   模型多时（如同时加载十几个 GLB，每个都 `awaitLoaded`）会积成每帧几十个回调 ⇒ 卡顿。
+     *   走本方法则**全部挂在本类这一条链上**（本类已把节流控到 30ms/帧），零额外调度。
+     *
+     * 典型用法（原三处`await new Promise(r => requestAnimationFrame(r))` 逐字替换即可）：
+     * ```ts
+     * import threeUtils from "three-base/threeUtils";
+     * await threeUtils.waitNextFrame();
+     * ```
+     */
+    waitNextFrame(): Promise<void>;
+    /** 结算所有 `waitNextFrame` 的挂起项（每帧由 `requestAnimationFrame` 调一次） */
+    private _nextFrameWaiters;
+    private _flushNextFrameWaiters;
+    private _keepZoomDoms;
+    /**
+     *计算需要保持比例的元素
+     */
+    private _computerDomZoom;
+    /**
+     * dom元素保持比例
+     */
+    keepZoom(dom: HTMLElement | null, width?: number, height?: number): void;
+    workList: Array<() => void>;
+    clock: Clock;
+    /**
+     * @param {() => void} [callback]
+     * @param {boolean} [first=true] 需要优先执行
+     */
+    addWork(work?: () => void, first?: boolean): void;
+    /**
+     *判断一个元素是否在页面上
+     */
+    inDocument(dom: ParentNode | null): boolean;
+    getCenter(object3d: Object3D | BufferGeometry): Vector3;
+    getSize(object3d: Object3D | BufferGeometry): Vector3;
+    alignBottom(object3d: Object3D | BufferGeometry, y?: number): void;
+    centerObject3D(object3d: Object3D | BufferGeometry): void;
+    center(object3d: Object3D | BufferGeometry): void;
+    scaleTo(object3d: Object3D | BufferGeometry, size?: number, key?: Array<"x" | "y" | "z">): void;
+    applyAllTranstion(object3d: Object3D): void;
+    exportGLB(input: Object3D, fileName?: string, maxTextureSize?: number): void;
+    exportUsdz(): void;
+    getVolume(geometry: BufferGeometry): number;
+    signedVolumeOfTriangle(p1: Vector3, p2: Vector3, p3: Vector3): number;
+    dipose(object3d: Object3D): void;
+    getSuffix(filename: string): string;
+    getFilename(url: string): string;
+    fileToBloburl(file: File): Promise<string>;
+    toMeshBasicMaterial<P extends Material | Material[]>(material: P): P;
+    toMeshLambertMaterial<P extends Material | Material[]>(material: P): P;
+}
+declare const threeUtils: ThreeUtils;
+export default threeUtils;