next-flow-interface 0.26.19 → 0.26.21

package/index.d.ts

@@ -917,26 +917,6 @@ export declare interface ContextMenuCreateOptions {
  * 该服务提供了一个集中管理系统，用于创建、显示和控制右键菜单。
  * 采用单例模式，确保整个应用程序中只存在一个实例。
  *
- * @example
- * 基础用法：
- * ```typescript
- * const menuController = ContextMenuService.instance.create({
- *   x: 100,
- *   y: 200,
- *   lines: [
- *     {
- *       text: '复制',
- *       onClick: () => console.log('Copy clicked')
- *     },
- *     {
- *       text: '粘贴',
- *       onClick: () => console.log('Paste clicked')
- *     }
- *   ]
- * })
- * menuController.show()
- * ```
- *
  * @public
  */
 export declare class ContextMenuService {
@@ -1630,6 +1610,15 @@ export declare class DomNotFoundError extends NotFoundError {
   constructor(message: string);
 }
 
+declare interface DragNodeInfo {
+  nid: string;
+  location: StoredRhineVar<RvLocation>;
+  initialPosition: V3;
+  initialRotation?: V3;
+  initialRotationQuaternion?: V4;
+  initialScale: V3;
+}
+
 /**
  * @public
  */
@@ -5298,6 +5287,7 @@ export declare class RsSelectionService {
   branchMode: boolean;
   materialInfo: RsSelectionMaterialInfo;
   highlight: HighLightInfo[];
+  getSelectedNidList(): string[];
   changeBranchMode(value?: boolean, message?: boolean): void;
   toAllChildren(log?: boolean): boolean;
   subscribe(subscriber: SelectedSubscriber): () => void;
@@ -5318,44 +5308,104 @@ export declare interface RsSelectionState {
 }
 
 /**
- * @public
+ * 材质分离渲染服务
+ *
+ * 在 BabylonJS 渲染层执行实际的材质分离操作。
+ * 当多个 mesh 共享同一材质时，通过 clone 材质实现独立编辑，
+ * 避免修改一个节点的材质影响其他节点。
+ *
+ * @remarks
+ * 采用"按需分离"策略，只在需要独立编辑时才 clone 材质，节省内存。
+ *
+ * 典型流程：
+ * 1. 文件加载后调用 {@link analyzeByMeshes} 分析共享材质的节点
+ * 2. 编辑材质时调用 {@link get} 或 {@link getWithEnsureType} 获取独立材质
+ *
+ * @example
+ * ```typescript
+ * // 获取节点的独立材质（按需分离）
+ * const material = await RsSeparateService.instance.get(nid)
+ *
+ * // 获取并确保材质类型匹配
+ * const material = await RsSeparateService.instance.getWithEnsureType(nid, rvMaterial)
+ * ```
+ *
+ * @see {@link RvSeparateService} 协同数据层材质分离服务
  */
 export declare class RsSeparateService {
+  /**
+   * 获取单例实例
+   *
+   * @returns 服务单例
+   */
   static get instance(): RsSeparateService;
   private constructor();
+  /**
+   * 已完成材质分离的节点 nid 列表
+   *
+   * 记录在当前会话中已经执行过材质 clone 的节点，避免重复分离。
+   */
   separated: string[];
+  /**
+   * 检查节点是否已完成材质分离
+   *
+   * @param nid - 节点唯一标识符
+   * @returns 是否已分离
+   */
   has(nid: string): boolean;
+  /**
+   * 标记节点为已分离，并可选地设置材质
+   *
+   * @param nid - 节点唯一标识符
+   * @param mesh - 目标 mesh（可选）
+   * @param material - 要设置的材质（可选）
+   */
   add(nid: string, mesh?: AbstractMesh, material?: Material | null): void;
   /**
    * 获取节点分离后的材质
    *
-   * 如果材质已经分离，则返回分离后的材质，为分离则先复制并分离再返回新材质。
+   * 如果节点在分离组中但尚未分离，则 clone 原材质并赋给该 mesh。
+   * 如果已分离或不在分离组中，直接返回当前材质。
    *
-   * @param nid -
-   * @param node -
+   * @param nid - 节点唯一标识符
+   * @param node - 可选的已知节点，避免重复查找
+   * @returns 分离后的材质，若节点无材质则返回 null
    */
   get(nid: string, node?: Node_2): Promise<Material | null>;
   /**
-   * 获取节点分离后的材质
+   * 获取节点分离后的材质，并确保材质类型匹配
    *
-   * 会确保材质的类型符合数据，不符合则创建。
+   * 会检查当前材质类型是否与协同数据中定义的类型一致，
+   * 不一致则创建新的对应类型材质。
    *
-   * 如果材质已经分离，则返回分离后的材质，未分离则先复制并分离再返回新材质。
-   *
-   * @param nid -
-   * @param rvMaterial -
-   * @param node -
+   * @param nid - 节点唯一标识符
+   * @param rvMaterial - 协同数据中的材质定义
+   * @param node - 可选的已知节点，避免重复查找
+   * @returns 类型匹配的分离材质，若无法创建则返回 null
    */
   getWithEnsureType(
     nid: string,
     rvMaterial: RvMaterial,
     node?: Node_2,
   ): Promise<Material | null>;
+  /**
+   * 检查材质实例是否匹配指定类型
+   *
+   * @param material - BabylonJS 材质实例
+   * @param type - 期望的材质类型枚举值
+   * @returns 是否匹配
+   */
   checkMaterialType(material: Material, type: RvMaterialType): boolean;
   /**
-   * 分析所有模型，找到其中所有有使用相同材质的模型，分组他们的id
+   * 分析一组 mesh，找出共享材质的节点并写入协同数据
    *
-   * @param meshes
+   * 遍历所有 mesh，按材质 uniqueId 分组，将共享同一材质的节点 nid 记录到
+   * {@link RvSeparateService} 的协同数据中。
+   *
+   * @remarks
+   * 通常在文件加载完成后调用，用于初始化材质分离信息。
+   *
+   * @param meshes - 要分析的 mesh 数组
    */
   analyzeByMeshes(meshes: AbstractMesh[]): void;
 }
@@ -6422,7 +6472,64 @@ export declare class RvSceneService {
  * @public
  */
 export declare interface RvSeparate {
-  groups: RhineVarArray<RhineVarArray>;
+  groups: RhineVarArray<RhineVarArray<string>>;
+}
+
+/**
+ * 材质分离协同数据服务
+ *
+ * 管理材质分离相关的 RhineVar 协同数据，记录哪些节点共享同一材质。
+ * 当 GLB 文件中多个 mesh 共用材质时，需要记录这些共享关系，
+ * 以便在用户编辑某个节点材质时进行按需分离。
+ *
+ * @remarks
+ * 数据结构 `RvSeparate.groups: string[][]`，每个 group 是一组共享同一材质的节点 nid 列表。
+ *
+ * @example
+ * ```typescript
+ * // 检查节点是否与其他节点共享材质
+ * if (RvSeparateService.instance.has(nid)) {
+ *   // 需要分离材质
+ * }
+ * ```
+ *
+ * @see {@link RsSeparateService} 渲染层材质分离服务
+ */
+export declare class RvSeparateService {
+  private static _instance;
+  /**
+   * 获取单例实例
+   *
+   * @returns 服务单例
+   */
+  static get instance(): RvSeparateService;
+  private constructor();
+  /**
+   * 材质分离协同数据
+   *
+   * 包含 `groups` 字段，记录所有共享材质的节点分组。
+   */
+  separate: StoredRhineVar<RvSeparate>;
+  /**
+   * 检查节点是否在任意材质分离组中
+   *
+   * 若返回 true，表示该节点与其他节点共享材质，编辑前需要进行材质分离。
+   *
+   * @param nid - 节点唯一标识符
+   * @returns 是否在分离组中
+   */
+  has(nid: string): boolean;
+  /**
+   * 将新节点与源节点加入同一材质分离组
+   *
+   * 用于复制节点时，确保复制出的节点与原节点共享材质分离信息。
+   * 如果源节点已在某个分离组中，则将新节点加入该组；
+   * 否则创建一个新的分离组包含这两个节点。
+   *
+   * @param fromNid - 源节点 nid
+   * @param newNid - 新复制的节点 nid
+   */
+  addCopyToGroup(fromNid: string, newNid: string): void;
 }
 
 /**

package/package.json

@@ -36,7 +36,7 @@
     "valtio": "2.1.7",
     "rhine-var": "0.11.2"
   },
-  "version": "0.26.19",
+  "version": "0.26.21",
   "author": "NextFlow",
   "license": "Apache-2.0",
   "keywords": [