@realsee/five 5.0.0-alpha.12 → 5.0.0-alpha.120

package/react/index.d.ts

@@ -1,16 +1,18 @@
 import { EventCallback } from '@realsee/five';
 import { Five } from '@realsee/five';
 import { FiveInitArgs } from '@realsee/five';
-import { FiveScene } from '@realsee/five';
 import { Intersection } from '@realsee/five';
 import { Model } from '@realsee/five';
 import { Pose } from '@realsee/five';
 import * as React_2 from 'react';
+import { Scene } from '@realsee/five';
 import { State } from '@realsee/five';
 import * as THREE_2 from 'three';
 import { Vector2 } from 'three';
 import { Work } from '@realsee/five';
 
+export declare function createFiveFeature<T extends FiveInjectionFeature>(...features: T[]): T[];
+
 /**
  * 创建一个 FiveProvider
  * 在 React 的体系下，使用 Provider 的方式来组织组件结构。
@@ -22,24 +24,27 @@ import { Work } from '@realsee/five';
  * ```
  * const FiveProvider = createFiveProvider({...fiveInitArgs});
  * const App: React.FC = () => {
- *  return <FiveProvider initalWork={work}>
+ *  return <FiveProvider initialWork={work}>
  *    <FiveCanvas width={512} height={512} />
  *  </FiveProvider>
  * };
  * ReactDOM.render(<App/>, document.getElementById("app"));
  * ```
  */
-export declare function createFiveProvider(fiveInitArgs: Omit<FiveInitArgs, "renderer" | "scissor">): {
+export declare function createFiveProvider(fiveInitArgs?: Omit<FiveInitArgs, "renderer" | "scissor">): {
     new (props: FiveProviderPropTypes): {
         /**
          * five 实例，可以通过 FiveProvider 的 ref.five 获取得到
          * 在一些外部调用方面可以尝试使用
          */
         five?: Five;
-        loadWork(work: Work, state?: "inherit" | "initial" | Partial<Omit<State, "offset">>, duration?: number): void;
+        loadWork(work: Work, state?: "inherit" | "initial" | Partial<Omit<State, "offset">>, duration?: number, userAction?: boolean): Promise<void>;
         shouldComponentUpdate(nextProps: FiveProviderPropTypes): boolean;
         componentWillUnmount(): void;
-        render(): JSX.Element;
+        render(): React_2.FunctionComponentElement<React_2.ProviderProps<{
+            five: Five;
+            loadWork: (work: Work, state?: "inherit" | "initial" | Partial<Omit<State, "offset">>, duration?: number, userAction?: boolean) => Promise<void>;
+        }>>;
         context: any;
         setState<K extends never>(state: {} | ((prevState: Readonly<{}>, props: Readonly<FiveProviderPropTypes>) => {} | Pick<{}, K>) | Pick<{}, K>, callback?: () => void): void;
         forceUpdate(callback?: () => void): void;
@@ -65,93 +70,99 @@ export declare function createFiveProvider(fiveInitArgs: Omit<FiveInitArgs, "ren
 };
 
 export declare function createStore<T extends StoreValueMapType, A extends StoreActionMapType = {}>(actionHandler: StoreActionMapHanlder<T, keyof T, A>): {
-    new (props: {
-        initalValue: T;
-        onValuesChange?: (value: T, prevValue: T) => void;
-        children: React_2.ReactNode;
-    }): {
-        store: Store<T>;
-        shouldComponentUpdate(nextProps: {
-            initalValue: T;
-            onValuesChange?: (value: T, prevValue: T) => void;
-            children: React_2.ReactNode;
-        }): boolean;
-        render(): JSX.Element;
-        context: any;
-        setState<K extends never>(state: {} | ((prevState: Readonly<{}>, props: Readonly<{
-            initalValue: T;
-            onValuesChange?: (value: T, prevValue: T) => void;
-            children: React_2.ReactNode;
-        }>) => {} | Pick<{}, K>) | Pick<{}, K>, callback?: () => void): void;
-        forceUpdate(callback?: () => void): void;
-        readonly props: Readonly<{
-            initalValue: T;
-            onValuesChange?: (value: T, prevValue: T) => void;
-            children: React_2.ReactNode;
-        }> & Readonly<{
-            children?: React_2.ReactNode;
-        }>;
-        state: Readonly<{}>;
-        refs: {
-            [key: string]: React_2.ReactInstance;
-        };
-        componentDidMount?(): void;
-        componentWillUnmount?(): void;
-        componentDidCatch?(error: Error, errorInfo: React_2.ErrorInfo): void;
-        getSnapshotBeforeUpdate?(prevProps: Readonly<{
-            initalValue: T;
-            onValuesChange?: (value: T, prevValue: T) => void;
-            children: React_2.ReactNode;
-        }>, prevState: Readonly<{}>): any;
-        componentDidUpdate?(prevProps: Readonly<{
-            initalValue: T;
-            onValuesChange?: (value: T, prevValue: T) => void;
-            children: React_2.ReactNode;
-        }>, prevState: Readonly<{}>, snapshot?: any): void;
-        componentWillMount?(): void;
-        UNSAFE_componentWillMount?(): void;
-        componentWillReceiveProps?(nextProps: Readonly<{
-            initalValue: T;
-            onValuesChange?: (value: T, prevValue: T) => void;
-            children: React_2.ReactNode;
-        }>, nextContext: any): void;
-        UNSAFE_componentWillReceiveProps?(nextProps: Readonly<{
-            initalValue: T;
-            onValuesChange?: (value: T, prevValue: T) => void;
-            children: React_2.ReactNode;
-        }>, nextContext: any): void;
-        componentWillUpdate?(nextProps: Readonly<{
-            initalValue: T;
-            onValuesChange?: (value: T, prevValue: T) => void;
-            children: React_2.ReactNode;
-        }>, nextState: Readonly<{}>, nextContext: any): void;
-        UNSAFE_componentWillUpdate?(nextProps: Readonly<{
-            initalValue: T;
-            onValuesChange?: (value: T, prevValue: T) => void;
-            children: React_2.ReactNode;
-        }>, nextState: Readonly<{}>, nextContext: any): void;
-    };
     /**
      * 使用 Store
      * @param names - 获取的 Store 字段
      * @returns [值, 修改值方法]
      */
-    useStore<K_1 extends keyof T>(names: K_1[]): [values: Pick<T, K_1>, setValues: (values: Pick<T, K_1>) => void];
+    useStore<K extends keyof T>(names: K[]): [values: Pick<T, K>, setValues: (values: Pick<T, K>) => void];
     /**
      * 使用 Store (仅设置值)
      * @param names - 获取的 Store 字段
      * @returns 修改值方法
      */
-    useStoreSetter<K_2 extends keyof T>(names: K_2[]): (values: Pick<T, K_2>) => void;
+    useStoreSetter<K_1 extends keyof T>(names: K_1[]): (values: Pick<T, K_1>) => void;
     /**
      * 监听 Store 变化
      * @param names - Store 字段
      * @param callback - 监听变化的回调函数
      * @param deps - 依赖对象
      */
-    watchStore<K_3 extends keyof T>(names: K_3[], callback: (values: Pick<T, K_3>, prevValues: Pick<T, K_3>) => void, deps?: React_2.DependencyList | undefined): void;
+    watchStore<K_2 extends keyof T>(names: K_2[], callback: (values: Pick<T, K_2>, prevValues: Pick<T, K_2>) => void, deps?: React_2.DependencyList | undefined): void;
     useStoreAction<N extends keyof A, F extends A[N]>(actionName: N): F;
-    contextType?: React_2.Context<any>;
+    /**
+     * Store Provider.
+     * 内部组件均可和 store 交互
+     */
+    StoreProvider: {
+        new (props: {
+            initialValue: T;
+            onValuesChange?: (value: T, prevValue: T) => void;
+            children: React_2.ReactNode;
+        }): {
+            store: Store<T>;
+            shouldComponentUpdate(nextProps: {
+                initialValue: T;
+                onValuesChange?: (value: T, prevValue: T) => void;
+                children: React_2.ReactNode;
+            }): boolean;
+            render(): React_2.FunctionComponentElement<React_2.ProviderProps<Store<T>>>;
+            context: any;
+            setState<K_3 extends never>(state: {} | ((prevState: Readonly<{}>, props: Readonly<{
+                initialValue: T;
+                onValuesChange?: (value: T, prevValue: T) => void;
+                children: React_2.ReactNode;
+            }>) => {} | Pick<{}, K_3>) | Pick<{}, K_3>, callback?: () => void): void;
+            forceUpdate(callback?: () => void): void;
+            readonly props: Readonly<{
+                initialValue: T;
+                onValuesChange?: (value: T, prevValue: T) => void;
+                children: React_2.ReactNode;
+            }> & Readonly<{
+                children?: React_2.ReactNode;
+            }>;
+            state: Readonly<{}>;
+            refs: {
+                [key: string]: React_2.ReactInstance;
+            };
+            componentDidMount?(): void;
+            componentWillUnmount?(): void;
+            componentDidCatch?(error: Error, errorInfo: React_2.ErrorInfo): void;
+            getSnapshotBeforeUpdate?(prevProps: Readonly<{
+                initialValue: T;
+                onValuesChange?: (value: T, prevValue: T) => void;
+                children: React_2.ReactNode;
+            }>, prevState: Readonly<{}>): any;
+            componentDidUpdate?(prevProps: Readonly<{
+                initialValue: T;
+                onValuesChange?: (value: T, prevValue: T) => void;
+                children: React_2.ReactNode;
+            }>, prevState: Readonly<{}>, snapshot?: any): void;
+            componentWillMount?(): void;
+            UNSAFE_componentWillMount?(): void;
+            componentWillReceiveProps?(nextProps: Readonly<{
+                initialValue: T;
+                onValuesChange?: (value: T, prevValue: T) => void;
+                children: React_2.ReactNode;
+            }>, nextContext: any): void;
+            UNSAFE_componentWillReceiveProps?(nextProps: Readonly<{
+                initialValue: T;
+                onValuesChange?: (value: T, prevValue: T) => void;
+                children: React_2.ReactNode;
+            }>, nextContext: any): void;
+            componentWillUpdate?(nextProps: Readonly<{
+                initialValue: T;
+                onValuesChange?: (value: T, prevValue: T) => void;
+                children: React_2.ReactNode;
+            }>, nextState: Readonly<{}>, nextContext: any): void;
+            UNSAFE_componentWillUpdate?(nextProps: Readonly<{
+                initialValue: T;
+                onValuesChange?: (value: T, prevValue: T) => void;
+                children: React_2.ReactNode;
+            }>, nextState: Readonly<{}>, nextContext: any): void;
+        };
+        contextType?: React_2.Context<any>;
+    };
 };
 
 /**
@@ -237,7 +248,7 @@ export declare interface FiveActionReactCallbacks {
  * @returns React 元素
  * @example
  * ```typescript
- * <FiveProvider initalWork={work}>
+ * <FiveProvider initialWork={work}>
  *  <FiveCanvas width={512} height={512}/>
  * </FiveProvider>
  * ```
@@ -247,9 +258,9 @@ export declare const FiveCanvas: React_2.FC<{
     height: number;
 }>;
 
-export declare type FiveInjectionActionFeature = "loadWork" | "setState" | "on" | "off" | "intersectRaycaster" | "project2d" | "updateCamera" | "initBasisLoader" | "getPixels" | "render" | "needsRender" | "preloadPano";
+export declare type FiveInjectionActionFeature = "loadWork" | "setState" | "on" | "off" | "intersectRaycaster" | "project2d" | "updateCamera" | "initBasisLoader" | "getPixels" | "render" | "needsRender" | "preloadPano" | "showFloor" | "toggleHelperVisible";
 
-export declare type FiveInjectionDataFeature = "unsafe__fiveInstance" | "currentState" | "state" | "work" | "scene" | "cameraDirection" | "cameraRaycaster" | "modelReadyState";
+export declare type FiveInjectionDataFeature = "unsafe__fiveInstance" | "currentState" | "currentObserver" | "state" | "work" | "model" | "scene" | "cameraDirection" | "cameraRaycaster" | "modelReadyState" | "shownFloor" | "totalFloorLength" | "helperVisible";
 
 export declare type FiveInjectionFeature = FiveInjectionDataFeature | FiveInjectionActionFeature;
 
@@ -452,26 +463,38 @@ export declare interface FiveInjectionTypes extends Record<FiveInjectionFeature,
      * @returns 加载完成的 Promise 参数同 callback
      */
     preloadPano: Five["preloadPano"];
+    /**
+     * 显示楼层
+     * @param floorIndex - 楼层，如果不传则都显示
+     */
+    showFloor: (floorIndex?: number) => void;
+    /**
+     * 帮助元素的隐藏/显示
+     * @param visible - 隐藏/显示
+     */
+    toggleHelperVisible: (visible: boolean) => void;
 }
 
 export declare type FiveProviderPropTypes = {
     work?: Work;
-    initalWork?: Work;
-    initalState?: "inherit" | "initial" | Partial<Omit<State, "offset">>;
+    initialWork?: Work | Promise<Work>;
+    initialState?: "inherit" | "initial" | Partial<Omit<State, "offset">>;
+    initialUserAction?: boolean;
     onWorkChange?: (work: Work) => void;
     onStateChange?: (state: State, userAction: boolean) => void;
     onCurrentStateChange?: (state: State, userAction: boolean) => void;
+    onError?: (error: Error) => void;
     children: React_2.ReactNode;
 };
 
 export declare type FiveProviderType = ReturnType<typeof createFiveProvider>;
 
-export declare interface InjectFiveToProps<F extends FiveInjectionFeature> {
-    [INJECTION_PROPNAME]: Pick<FiveInjectionTypes, F>;
-}
-
 export declare const INJECTION_PROPNAME = "$five";
 
+export declare interface PropTypeOfFiveFeatures<F extends FiveInjectionFeature[]> {
+    [INJECTION_PROPNAME]: Pick<FiveInjectionTypes, F[number]>;
+}
+
 /**
  * 监听者模式
  * @template T - 预设的监听回调类型
@@ -489,7 +512,7 @@ export declare class Store<T extends StoreValueMapType> {
     /** 全局的数据变化钩子 */
     onValuesChange?: (values: T, prevValues: T) => void;
     private listeners;
-    constructor(initalValue: T, onValuesChange?: (values: T, prevValues: T) => void);
+    constructor(initialValue: T, onValuesChange?: (values: T, prevValues: T) => void);
     /**
      * 监听数据变化
      * @param names - 监听的字段名称
@@ -520,7 +543,7 @@ export declare type StoreActionMapType = {
     [name: string]: (...args: any[]) => any;
 };
 
-export declare type StoreProviderType = ReturnType<typeof createStore>;
+export declare type StoreProviderType = ReturnType<typeof createStore>["StoreProvider"];
 
 export declare type StoreValueMapType = Record<string, any>;
 
@@ -623,6 +646,16 @@ export declare function useFiveCameraDirection(): THREE_2.Vector3;
  */
 export declare function useFiveCameraRaycaster(): THREE_2.Raycaster;
 
+/**
+ * Five React Hooks: Five 的当前观测点
+ * @returns Work.observers[number] 当前观测点, 如果 work 未加载则为 null
+ * @example
+ * ```
+ * const observer = useFiveCurrentObserver();
+ * ```
+ */
+export declare function useFiveCurrentObserver(): Work["observers"][number] | null;
+
 /**
  * Five React Hooks: Five 的实时状态
  * @returns
@@ -634,7 +667,7 @@ export declare function useFiveCameraRaycaster(): THREE_2.Raycaster;
  */
 export declare function useFiveCurrentState(): [
 currentState: State,
-setState: (state: Partial<State>, immediately?: boolean) => void
+setState: (state: Partial<State> | ((prevState: State) => Partial<State>), immediately?: boolean, userAction?: boolean) => void
 ];
 
 /**
@@ -645,7 +678,36 @@ setState: (state: Partial<State>, immediately?: boolean) => void
  * useFiveEvent("cameraUpdate", pose => {});
  * ```
  */
-export declare function useFiveEvent<T extends keyof EventCallback>(name: T, callback: EventCallback[T], deps?: React_2.DependencyList | undefined): void;
+export declare function useFiveEventCallback<T extends keyof EventCallback>(name: T, callback: EventCallback[T], deps?: React_2.DependencyList | undefined): void;
+
+/**
+ * Five React Hooks: Five 楼层
+ * @returns
+ * [ shownFloor: Five 当前显示的楼层， null 为都显示, showFloor: 设置显示楼层，不传参数为都显示 ]
+ * @example
+ * ```
+ * const [ shownFloor, showFloor ] = useFiveFloor;
+ * ```
+ */
+export declare function useFiveFloor(): [
+shownFloor: number | null,
+totalFloorLength: number,
+showFloor: (floorIndex?: number) => void
+];
+
+/**
+ * Five React Hooks: Five 帮助元素的隐藏/显示
+ * @returns
+ * [ helperVisible: Five 帮助元素是否显示显示, toggleHelperVisible: 设置 帮助元素的隐藏/显示 ]
+ * @example
+ * ```
+ * const [ helperVisible, toggleHelperVisible ] = useFiveHelper;
+ * ```
+ */
+export declare function useFiveHelper(): [
+helperVisible: boolean,
+toggleHelperVisible: (visible: boolean) => void
+];
 
 /**
  * Five React Hooks: 获取当前模型碰撞检测方法
@@ -668,7 +730,7 @@ export declare function useFiveEvent<T extends keyof EventCallback>(name: T, cal
 export declare function useFiveModelIntersectRaycaster(): (raycaster: THREE_2.Raycaster) => Intersection[];
 
 /**
- * Five React Hooks: 获取当前模型碰加载状态
+ * Five React Hooks: 获取当前模型加载状态
  * @returns
  * "Loaded": 加载完成
  * "Empty" 加载未完成
@@ -695,23 +757,29 @@ export declare function useFiveModelReadyState(): "Loaded" | "Empty";
  */
 export declare function useFiveProject2d(): (vector: THREE.Vector3, testModel: boolean) => Vector2;
 
+/**
+ * @deprecated
+ * 请使用 `useFiveSceneEffect` 替代
+ */
+export declare const useFiveScene: typeof useFiveSceneEffect;
+
 /**
  * Five React Hooks: 操作 Five 的 Scene
  * @param callback - 获取 Five 的 Scene 的回调函数
  * @example
  * ```
- * useFiveScene(scene => {
+ * useFiveSceneEffect(scene => {
  *  // object is a THREE.Object3D
  *  scene.add(object);
- *  return () => scene.remove(object);
+ *  return () => scene.remove(object); // 析构函数
  * });
  * ```
  */
-export declare function useFiveScene(callback: (scene: FiveScene) => void | (() => void), deps?: React_2.DependencyList | undefined): void;
+export declare function useFiveSceneEffect(callback: (scene: Scene) => void | (() => void), deps?: React_2.DependencyList | undefined): void;
 
 export declare function useFiveState(): [
 state: State,
-setState: (state: Partial<State>, immediately?: boolean) => void
+setState: (state: Partial<State> | ((prevState: State) => Partial<State>), immediately?: boolean, userAction?: boolean) => void
 ];
 
 /**
@@ -738,10 +806,10 @@ setState: (state: Partial<State>, immediately?: boolean) => void
  * ```
  */
 export declare function useFiveWork(): [
-work: Work,
-loadWork: (work: Work, state?: "inherit" | "initial" | Partial<Omit<State, "offset">>, duration?: number) => void
+work: Work | undefined,
+loadWork: (work: Work, state?: "inherit" | "initial" | Partial<Omit<State, "offset">>, duration?: number, userAction?: boolean) => Promise<void>
 ];
 
-export declare function withFive<F extends FiveInjectionFeature>(...features: F[]): <P extends InjectFiveToProps<F>, C extends React_2.ComponentClass<P, any>>(Component: C & React_2.ComponentClass<P, any>) => React_2.ForwardRefExoticComponent<React_2.PropsWithoutRef<Omit<P, "$five">> & React_2.RefAttributes<Omit<InstanceType<C>, "state" | "setState" | "render" | "componentDidMount" | "shouldComponentUpdate" | "componentWillUnmount" | "componentDidCatch" | "getSnapshotBeforeUpdate" | "componentDidUpdate" | "componentWillMount" | "UNSAFE_componentWillMount" | "componentWillReceiveProps" | "UNSAFE_componentWillReceiveProps" | "componentWillUpdate" | "UNSAFE_componentWillUpdate" | "context" | "forceUpdate" | "props" | "refs">>>;
+export declare function withFive<F extends FiveInjectionFeature[]>(features: F): <P extends PropTypeOfFiveFeatures<F>, C extends React_2.ComponentClass<P, any>>(Component: C & React_2.ComponentClass<P, any>) => React_2.ForwardRefExoticComponent<React_2.PropsWithoutRef<Omit<P, "$five">> & React_2.RefAttributes<Omit<InstanceType<C>, "state" | "setState" | "render" | "componentDidMount" | "shouldComponentUpdate" | "componentWillUnmount" | "componentDidCatch" | "getSnapshotBeforeUpdate" | "componentDidUpdate" | "componentWillMount" | "UNSAFE_componentWillMount" | "componentWillReceiveProps" | "UNSAFE_componentWillReceiveProps" | "componentWillUpdate" | "UNSAFE_componentWillUpdate" | "context" | "forceUpdate" | "props" | "refs">>>;
 
 export { }