@manycore/custom-sdk 1.0.1-rc.5 → 1.0.1-rc.8

package/index.d.ts

@@ -2,40 +2,69 @@ import { ELineType as ELineType_2 } from '@manycore/custom-miniapp-sdk';
 import { IExportModelData } from '@manycore/custom-miniapp-sdk';
 import { Number3 } from '@manycore/custom-miniapp-sdk';
 
+/**
+ * 对接2.0主应用
+ *
+ * @example
+ * ```typescript
+ *  const application = new Application();
+ * ```
+ */
 export declare class Application {
     constructor();
     /**
-     * 启动当前应用
+     * 启动对接2.0应用
+     *
+     * 当前，在启动对接2.0应用时，默认会自动把酷家乐主工具当中，选中的模型，加载至对接2.0场景当中。
+     *
+     * @example
+     * ```typescript
+     * await application.start();
+     * ```
      */
     start(): Promise<void>;
     /**
-     * 初始化语言类型
+     * 初始化语言类型(默认不需要处理)
+     *
+     * 如果你有多语言的诉求，可能会用到此功能
+     *
      * @param lang
      * @param resource
      */
     initLange(lang?: string, resource?: {}): void;
+    /**
+     * 停止对接2.0应用
+     *
+     * 当停用时，会让主工具当中，更新模型最新的锁定状态。
+     *
+     * @example
+     * ```typescript
+     * await application.stop();
+     * ```
+     */
     stop(): Promise<void>;
+    /**
+     *
+     * 对接2.0中，获取相关的service
+     *
+     * 如果需要调用此方法，需要确保`Application`调用过`start`方法
+     *
+     * @example
+     * ```typescript
+     * const s = application.getService(FittingDesignService);
+     * ```
+     *
+     * @param serv
+     */
     getService<T extends BaseService>(serv: {
         new (): T;
     }): T;
 }
 
-declare class BaseService {
-}
-
 /**
- * 配件附加参数数据类型
+ * @private
  */
-export declare enum EFittingParametersType {
-    /**
-     * 字符串
-     */
-    string = "string",
-    double = "double",
-    long = "long",
-    int = "int",
-    float2 = "float2",
-    float3 = "float3"
+declare class BaseService {
 }
 
 /**
@@ -79,7 +108,7 @@ export declare enum EIntersectedCreatedType {
 }
 
 /**
- * 交接面、交接体数据类型
+ * 交接数据的数据类型
  */
 export declare enum EIntersectedType {
     /**
@@ -92,6 +121,9 @@ export declare enum EIntersectedType {
     FACE = "2"
 }
 
+/**
+ * 语言
+ */
 export declare enum ELanguage {
     ZH_CN = "zh_CN",
     EN_US = "en_US",
@@ -121,6 +153,7 @@ export declare enum ELineType {
     CIRCLE_ARC = 1,
     /**
      * 椭圆
+     * 当前代码中，暂不支持
      */
     ELLIPSE_ARC = 3
 }
@@ -147,6 +180,9 @@ export declare enum EPointType {
     CUT_CIRCLE = 3
 }
 
+/**
+ * 处理选中的内容
+ */
 export declare enum ESelectedType {
     /**
      * 未选中模型
@@ -192,35 +228,73 @@ export declare enum EToolType {
     DOOR_WINDOW_COPY = "DW_COPY"
 }
 
+/**
+ * 孔槽方案相关数据的管理
+ *
+ * @example
+ * ```typescript
+ * const fittingDesignService = application.getService(FittingDesignService);
+ * ```
+ */
 export declare class FittingDesignService extends BaseService {
     /**
      * 设置孔槽方案自动保存
      *
+     * 当你调用`appendFittingDesign`时，如果开启自动保存，就会将当前数据与之前数据作合并，并保存至后台。如果不开启，那只会临时暂存在状态中，后续调用`saveDesign`时，才会保存至后端。
+     *
+     * @default true 自动保存
+     *
+     * @example
+     * ```typescript
+     * fittingDesignService.toggleAutoSave(false);
+     * ```
+     *
      * @param autoSave 默认开启自动保存
      */
     toggleAutoSave(autoSave?: boolean): void;
     /**
-     * 是否开启了自动保存功能
+     * 获取当前是否开启了自动保存
+     *
+     * @example
+     * ```typescript
+     * fittingDesignService.isAutoSave();
+     * ```
      */
     isAutoSave(): boolean;
     /**
      * 获取孔/槽方案数据
-     * @param modelId
+     *
+     * @example
+     * ```typescript
+     * fittingDesignService.getFittingDesignData();
+     * ```
+     *
+     * @param modelId 方案模型的ID，当没传时，就是获取场景中，正在预览的模型ID的方案数据
      */
-    getFittingDesignDesign(modelId?: string): Promise<IFittingDesignData | null>;
+    getFittingDesignData(modelId?: string): Promise<IFittingDesignData | null>;
     /**
      *
-     * 孔槽方案数据
+     * 获取某个元件关联的孔/槽方案数据（仅作用于当前正在处理的模型）
      *
-     * @param modelid 模型ID，如果为空时，则表示传递的为查询当前模型的数据
+     * @example
+     * ```typescript
+     * // 获取当前正在编辑的方案信息
+     * fittingDesignService.getConnectedFittingDesign();
+     *
+     * // 获取某块板上关联的孔/槽数据
+     * fittingDesignService.getConnectedFittingDesign('id');
+     *
+     * ```
+     *
+     * @param modelid 模型ID，如果为空时，则表示传递的为查询当前正在编辑的模型的方案数据
      * @param casbin 是否为五金，当modelid为五金的id时，需要为true
      */
     getConnectedFittingDesign(modelid?: string, casbin?: boolean): Promise<IFittingDesignData | null>;
     /**
-     * 简单的路径验证
+     * 五金槽路径验证API(非稳定API，暂不建议使用)
      *
-     * @param path
-     * @param linkModelId
+     * @param path 待验证的路径
+     * @param linkModelId 关联的模型ID
      */
     validateFittingDesign(path: IHardwareGrooveData, linkModelId: string): IFittingDesignValidateResult;
     /**
@@ -228,27 +302,56 @@ export declare class FittingDesignService extends BaseService {
      *
      * 会自动merge数据，但同一块板上，会进行覆盖
      *
-     * @param design
+     * > 如果没有开启自动保存，调用此API只影响视图展示，不会立即存储至后端。
+     *
+     * @example
+     * ```typescript
+     * await fittingDesignService.save({
+     *     ...
+     * })
+     * ```
+     *
+     * @param design 孔/槽方案信息
      * @param option { timeout, save} 调用超时，save 是否立即保存至后端，默认为true
          */
      appendFittingDesign(design: Partial<IFittingDesignData>, option?: {
+         /**
+          * 超时时间（只有在往后端保存时，才有效）
+          */
          timeout?: number;
+         /**
+          * 是否强制立即保存（即覆盖是否自动保存参数）
+          */
          save?: boolean;
      }): Promise<void>;
      /**
       * 保存孔/槽数据至方案
-      * 如果design不传，即表示将分步保存数据保存至后端
+      * 如果design不传，即表示将分步保存数据存储至后端
+      *
+      * @example
+      * ```typescript
+      * await fittingDesignService.saveDesign({
+      *     ...
+      * })
+      * ```
       *
-      * @param design
+      * @param design 需要保存的方案信息
       * @param option
       */
      saveDesign(design?: IFittingDesignData, option?: {
          timeout?: number;
      }): Promise<void>;
      /**
-      * 清空当前孔槽方案
+      * 删除当前孔槽方案(解锁主工具模型)
       *
-      * @param timeout
+      * 主工具当中，模型的锁定与解锁，与当前模型是不存在孔槽方案有关
+      * 默认情况下，option不传时，清空当前正在编辑的模型的孔槽方案，当传入modelId时，表示清空指定模型的孔槽方案数据
+      *
+      * * @example
+      * ```typescript
+      * await fittingDesignService.clearDesign();
+      * ```
+      * @param options
       */
      clearDesign(options?: IBaseOptions): Promise<void>;
     }
@@ -258,15 +361,15 @@ export declare class FittingDesignService extends BaseService {
      */
     export declare interface IBaseFittingData {
         /**
-         * 孔槽的id
+         * 开发者自己生成的孔、槽信息标识ID（自行区分）
          */
         id: string;
         /**
-         * 类型
+         * 当前数据类型
          */
         fittingType: EFittingType;
         /**
-         * 附加通用参数
+         * 附加通用参数，开发者可以自己存储一些数据
          */
         params?: IBaseFittingParameters[];
     }
@@ -311,33 +414,40 @@ export declare class FittingDesignService extends BaseService {
         end: Number3;
     }
 
+    /**
+     * 交接信息
+     */
     export declare interface IBaseIntersected {
         /**
-         * 板面
+         * 当前交接信息所处的板面信息
          */
         plankFaceId: number;
         /**
-         * 所有点的信息
+         * 当前交接信息所有顶点的信息
+         * * 如果为交接面，length为4
+         * * 如果为交接体，length为8
          */
         points: Number3[];
         /**
-         * 关联的模型ID
+         * 当前交接信息产生的元件ID
          */
         linkedModelId: string;
         /**
-         * 关联的父级模型ID
+         * 交接信息产生元件的父母ID
          */
         linkedParentModelId: string;
         /**
-         * 交接类型
+         * 交接数据的数据类型
          */
         '@type': EIntersectedType;
         /**
+         * @ignore
          * 交接体的shell数据
          */
         shell?: string;
         /**
          * 交接体板面是否需要开槽
+         * 当五金与板面产生的交接信息，为板面的部分，则为true
          */
         needGroove?: boolean;
     }
@@ -347,7 +457,8 @@ export declare class FittingDesignService extends BaseService {
      */
     export declare interface IBaseOptions {
         /**
-         * 超时时间
+         * 最长等待时间(以ms为单位)
+         * @default 500000
          */
         timeout?: number;
         /**
@@ -468,25 +579,31 @@ export declare class FittingDesignService extends BaseService {
         diameter: number;
     }
 
+    /**
+     * 一组交接信息
+     */
     export declare interface IIntersectedGroup {
         /**
-         * 交接面ID
+         * 交接信息的唯一标识ID
          */
         id: string;
         /**
-         * 交接信息产生的方式
+         * 交接信息的产生来源
          */
         intersectType: EIntersectedCreatedType;
         /**
-         * 交接面信息
+         * 关联元素产生的多组交接信息
          */
         intersecteds: IBaseIntersected[];
     }
 
     /**
-     * 交接面信息
+     * 交接信息
      */
     export declare interface IIntersectedResult {
+        /**
+         * 交接信息集合
+         */
         intersectedGroups: IIntersectedGroup[];
     }
 
@@ -518,9 +635,22 @@ export declare class FittingDesignService extends BaseService {
         radius: number;
     }
 
+    /**
+     * 获取交接信息
+     *
+     * @example
+     * ```typescript
+     * const intersectedService = application.getService(IntersectedService);
+     * ```
+     */
     export declare class IntersectedService extends BaseService {
         /**
-         * 是否显示交接面信息
+         * 是否展示交接信息
+         *
+         * @example
+         * ```typescript
+         * intersectedService.toggleModelViewIntersected(true);
+         * ```
          *
          * @param flag
          */
@@ -528,17 +658,19 @@ export declare class FittingDesignService extends BaseService {
         /**
          * 切换展示的交接面、交接体坐标
          *
+         * @example
+         * ```typescript
+         * intersectedService.toggleModelViewedIntersected({
+         *     references: true,
+         *     plankFaceIds: [1],
+         * });
+         * ```
+         *
          * @param option
          */
         toggleModelViewedIntersected(option?: IToggleIntersectedViewOption): void;
     }
 
-    export declare interface IPoint3d {
-        x: number;
-        y: number;
-        z: number;
-    }
-
     /**
      * 点的基本类型
      */
@@ -632,13 +764,35 @@ export declare class FittingDesignService extends BaseService {
         roomName?: string;
     }
 
+    /**
+     * 当前选中的数据
+     */
     export declare interface ISelected {
+        /**
+         * 选中的数据内容
+         */
         data: IExportModelData[] | IHardwareData[];
+        /**
+         * 选中的数据类型
+         */
         type: ESelectedType;
     }
 
     /**
-     * 处理场景当中
+     * 场景中，模型的颜色配置能力
+     *
+     * @example
+     * ```json
+     * {
+     *   // 交接页数据信息
+     *   intersectedColor: 0xff4500,
+     *   // 交接体颜色
+     *   intersectedBodyColor: 0xff00ff,
+     *   holeColor: 0x00ff00,
+     *   grooveColor: 0x1e90ff,
+     * }
+     * ```
+     *
      */
     export declare interface ISettingColor {
         /**
@@ -667,12 +821,22 @@ export declare class FittingDesignService extends BaseService {
         grooveColor: number;
     }
 
+    /**
+     * 展示交接信息时的筛选行为
+     */
     export declare interface IToggleIntersectedViewOption {
         /**
-         * 是否展示
-         * 默认为false
+         * 切换展示交接信息数据
+         *
+         * * `true` 显示第一组交接数据
+         * * `false`: 显示第二组交接数据
+         *
+         * @default false
          */
         references?: boolean;
+        /**
+         * 根据板面信息来筛选展示内容,null 表示空板面
+         */
         plankFaceIds?: Array<number | null>;
     }
 
@@ -757,17 +921,53 @@ export declare class FittingDesignService extends BaseService {
         pageNum?: number;
     }
 
+    /**
+     * 主要提供了获取当前模型的 JSON 输出数据，以及当前模型的交接信息的功能。
+     *
+     * @example
+     * ```typescript
+     * const modelService = application.getService(ModelService);
+     * ```
+     */
     export declare class ModelService extends BaseService {
         /**
-         * 获取当前整个模型数据信息
+         * 开发者，通常需要来获取某个模型的 JSON 数据，所以需要用此 API。当前 API 获取 JSON 数据，主要是拿的是当前正在编辑的模型的 JSON 数据。
+         * 如果传入modelId，则表示获取其他模型的JSON输出数据。
+         *
+         * 底层其实是通过`servkit`服务实现的。使用的是`MiniAppParamModelJsonDataService`服务。
+         *
+         * 使用servkit实现示例如下：
+         *
+         * @example
+         * ```typescript
+         * import { MiniAppParamModelJsonDataService } from '@manycore/custom-miniapp-sdk';
+         * import { sappSDK } from 'servkit';
+         *
+         * const service = sappSDK.getServiceUnsafe(MiniAppParamModelJsonDataService);
          *
-         * @param timeout
+         * const json = await service.getModelJsonDataByModelId('请输入模型ID');
+         * ```
+         *
+         * > 以上 API 暂不建议在非对接 2.0 环境下使用，主要是与孔/槽方案数据存在关联关系。
+         > > 替代的 service 为`CustomDesignExportService`，将会在 9 月底最新的`@manycore/custom-miniapp-sdk`中提供。
+         *
+         * @example
+         * ```typescript
+         * await modelService.getParamData();
+         * ```
+         *
+         * @param options
          */
         getParamData(options?: IBaseOptions): Promise<any>;
         /**
-         * 获取交接面信息
+         * 获取模型的交接数据
+         *
+         * @example
+         * ```typescript
+         * await modelService.getParamData();
+         * ```
          *
-         * @param timeout
+         * @param options
          */
         getParamIntersected(options?: IBaseOptions): Promise<IIntersectedResult>;
         /**
@@ -777,56 +977,94 @@ export declare class FittingDesignService extends BaseService {
         getTopParamModels(options?: ITopParamModelListOption): Promise<ITopParamModelDataResponse>;
     }
 
+    /**
+     * 主要是用来与场景交互的，监听当前选中的对象, 获取选中的内容
+     *
+     * @example
+     * ```typescript
+     * const viewerSelectionService = application.getService(ModelViewerSelectionService);
+     * ```
+     */
     export declare class ModelViewerSelectionService extends BaseService {
         constructor();
         /**
-         * 获取当前选中模型
+         * 获取当前选中的数据
          */
         getSelected(): ISelected;
         /**
+         * @ignore
          * 设置当前选中内容
          */
         select(selected: any[]): void;
         /**
-         * 取消选中所有内容
+         * 取消场景当中选中内容
          */
         unSelect(): void;
+        /**
+         * @ignore
+         */
         private onSelectedChanged;
+        /**
+         * 监听当前选中内容
+         * @param fn
+         */
         on(fn: (param: ISelected) => any): void;
+        /**
+         * 取消监听选中变化
+         * @param fn
+         */
         off(fn?: (param: ISelected) => any): void;
+        /**
+         * 监听当前选中的内容(触发一次后自动取消)
+         * @param fn
+         */
         once(fn: (param: ISelected) => any): void;
+        /**
+         * @ignore
+         */
         __onDestroy(): void;
     }
 
     /**
-     * 模型展示的服务
+     * 主要提供了模型展示的控制能力：重置视角，边框，半透明，以及展示颜色配置
+     *
+     * @example
+     * ```typescript
+     * const modelViewerService = application.getService(ModelViewerService);
+     * ```
      */
     export declare class ModelViewerService extends BaseService {
         /**
-         * 查看当前选中的模型
+         * 将工具方案中，选中的模型，加载到对接 2.0 小程序中展示
+         *
+         * 此方法，会成Application.start方法中，默认执行
+         *
          */
         viewSelected(): Promise<void>;
         /**
-         * 通过模型的ID来显示某个模型
+         * 指定模型的 ID，将当前模型加载到工具方案当中
+         *
          * @param id 模型ID
          */
         viewModelById(id: string | string[]): Promise<void>;
         /**
-         * 重置视角
+         * 重置视图展示视角
          */
         resetPerspective(): void;
         /**
-         * 模型渲染是都显示边框
+         * 模型渲染是否显示边框
          * @param flag
          */
         toggleModelBorder(flag: boolean): void;
         /**
-         * 模型渲染是否半透明
+         * 模型渲染是否为半透明
          * @param flag
          */
         toggleModelTransparent(flag: boolean): void;
         /**
-         * 配置场景展示界面
+         * 设置交接信息展示颜色
+         *
+         * > `settings`,需要在application.start()后，立即被设置，否则展示会读取至之前配置信息，展示可能存在异常。
          */
         setting(settings: Partial<ISettingColor>): void;
     }