@nocobase/flow-engine 2.0.59 → 2.0.61

package/src/flowEngine.ts

@@ -20,6 +20,7 @@ import { APIResource, FlowResource, MultiRecordResource, SingleRecordResource, S
 import { Emitter } from './emitter';
 import ModelOperationScheduler from './scheduler/ModelOperationScheduler';
 import type { ScheduleOptions, ScheduledCancel } from './scheduler/ModelOperationScheduler';
+import { createLoadedPageCache } from './utils/loadedPageCache';
 import type {
   ActionDefinition,
   ApplyFlowCacheEntry,
@@ -105,6 +106,8 @@ export class FlowEngine {
    */
   private _savingModels = new Map<string, Promise<any>>();
 
+  private _loadedPageCache = createLoadedPageCache();
+
   /**
    * Flow engine context object.
    * @private
@@ -938,7 +941,8 @@ export class FlowEngine {
   async loadModel<T extends FlowModel = FlowModel>(options): Promise<T | null> {
     if (!this.ensureModelRepository()) return;
     const refresh = !!options?.refresh;
-    if (!refresh) {
+    const bypassLoadedPageCache = this._loadedPageCache.shouldBypass(options, () => this.context.flowSettingsEnabled);
+    if (!refresh && !bypassLoadedPageCache) {
       const model = this.findModelByParentId(options.parentId, options.subKey);
       if (model) {
         return model as T;
@@ -949,14 +953,24 @@ export class FlowEngine {
       }
     }
     const data = await this._modelRepository.findOne(options);
-    if (!data?.uid) return null;
-    if (refresh) {
+    if (!data?.uid) {
+      if (bypassLoadedPageCache) {
+        this._loadedPageCache.clear(options);
+      }
+      return null;
+    }
+    if (refresh || bypassLoadedPageCache) {
       const existing = this.getModel(data.uid);
       if (existing) {
         this.removeModelWithSubModels(existing.uid);
       }
     }
-    return this.createModel<T>(data as any);
+    const model = this.createModel<T>(data as any);
+    if (bypassLoadedPageCache) {
+      this._loadedPageCache.mountModelToParent(model, true);
+      this._loadedPageCache.clear(options);
+    }
+    return model;
   }
 
   /**
@@ -996,22 +1010,31 @@ export class FlowEngine {
   ): Promise<T | null> {
     if (!this.ensureModelRepository()) return;
     const { uid, parentId, subKey } = options;
-    if (uid && this._modelInstances.has(uid)) {
+    const bypassLoadedPageCache = this._loadedPageCache.shouldBypass(options, () => this.context.flowSettingsEnabled);
+    if (uid && !bypassLoadedPageCache && this._modelInstances.has(uid)) {
       return this._modelInstances.get(uid) as T;
     }
-    const m = this.findModelByParentId<T>(parentId, subKey);
-    if (m) {
-      return m;
-    }
+    if (!bypassLoadedPageCache) {
+      const m = this.findModelByParentId<T>(parentId, subKey);
+      if (m) {
+        return m;
+      }
 
-    const hydrated = this.hydrateModelFromPreviousEngines<T>(options, extra);
-    if (hydrated) {
-      return hydrated;
+      const hydrated = this.hydrateModelFromPreviousEngines<T>(options, extra);
+      if (hydrated) {
+        return hydrated;
+      }
     }
 
     const data = await this._modelRepository.findOne(options);
     let model: T | null = null;
     if (data?.uid) {
+      if (bypassLoadedPageCache) {
+        const existing = this.getModel(data.uid);
+        if (existing) {
+          this.removeModelWithSubModels(existing.uid);
+        }
+      }
       model = this.createModel<T>(data as any, extra);
     } else {
       model = this.createModel<T>(options, extra);
@@ -1019,18 +1042,9 @@ export class FlowEngine {
         await model.save();
       }
     }
-    if (model.parent) {
-      const subModel = model.parent.findSubModel(model.subKey, (m) => {
-        return m.uid === model.uid;
-      });
-      if (subModel) {
-        return model;
-      }
-      if (model.subType === 'array') {
-        model.parent.addSubModel(model.subKey, model);
-      } else {
-        model.parent.setSubModel(model.subKey, model);
-      }
+    this._loadedPageCache.mountModelToParent(model, bypassLoadedPageCache);
+    if (bypassLoadedPageCache) {
+      this._loadedPageCache.clear(options);
     }
     return model;
   }
@@ -1050,6 +1064,7 @@ export class FlowEngine {
     if (!this.ensureModelRepository()) return;
 
     const modelUid = model.uid;
+    const dirtyLoadedPageKey = this._loadedPageCache.getDirtyKeyForModel(model);
 
     // 如果这个 model 正在保存中，返回现有的保存 Promise
     if (this._savingModels.has(modelUid)) {
@@ -1063,6 +1078,7 @@ export class FlowEngine {
 
     try {
       const result = await savePromise;
+      this._loadedPageCache.markDirty(dirtyLoadedPageKey);
       return result;
     } finally {
       // 无论成功还是失败，都要清除保存状态
@@ -1099,11 +1115,16 @@ export class FlowEngine {
    * @returns {Promise<boolean>} Whether destroyed successfully
    */
   async destroyModel(uid: string) {
-    if (this.ensureModelRepository()) {
+    const modelInstance = this._modelInstances.get(uid) as FlowModel;
+    const dirtyLoadedPageKey = this._loadedPageCache.getDirtyKeyForModel(modelInstance);
+    const hasModelRepository = this.ensureModelRepository();
+    if (hasModelRepository) {
       await this._modelRepository.destroy(uid);
     }
 
-    const modelInstance = this._modelInstances.get(uid) as FlowModel;
+    if (hasModelRepository) {
+      this._loadedPageCache.markDirty(dirtyLoadedPageKey);
+    }
     const parent = modelInstance?.parent;
     const result = this.removeModel(uid);
     parent && parent.emitter.emit('onSubModelDestroyed', modelInstance);
@@ -1207,17 +1228,25 @@ export class FlowEngine {
 
   /**
    * Move a model instance within its parent model.
-   * @param {any} sourceId Source model UID
-   * @param {any} targetId Target model UID
+   * @param {string | number} sourceId Source model UID
+   * @param {string | number} targetId Target model UID
    * @returns {Promise<void>} No return value
    */
-  async moveModel(sourceId: any, targetId: any, options?: PersistOptions): Promise<void> {
-    const sourceModel = this.getModel(sourceId);
-    const targetModel = this.getModel(targetId);
+  async moveModel(sourceId: string | number, targetId: string | number, options?: PersistOptions): Promise<void> {
+    const sourceUid = String(sourceId);
+    const targetUid = String(targetId);
+    if (!sourceUid || !targetUid || sourceUid === targetUid) {
+      return;
+    }
+
+    const sourceModel = this.getModel(sourceUid);
+    const targetModel = this.getModel(targetUid);
     if (!sourceModel || !targetModel) {
       console.warn(`FlowEngine: Cannot move model. Source or target model not found.`);
       return;
     }
+    let position: 'before' | 'after' = 'after';
+    const dirtyLoadedPageKey = this._loadedPageCache.getDirtyKeyForModel(sourceModel);
     const move = (sourceModel: FlowModel, targetModel: FlowModel) => {
       if (!sourceModel.parent || !targetModel.parent || sourceModel.parent !== targetModel.parent) {
         console.error('FlowModel.moveTo: Both models must have the same parent to perform move operation.');
@@ -1247,6 +1276,8 @@ export class FlowEngine {
         return false;
       }
 
+      position = currentIndex < targetIndex ? 'after' : 'before';
+
       // 使用splice直接移动数组元素（O(n)比排序O(n log n)更快）
       const [movedModel] = subModelsCopy.splice(currentIndex, 1);
       subModelsCopy.splice(targetIndex, 0, movedModel);
@@ -1261,10 +1292,14 @@ export class FlowEngine {
 
       return true;
     };
-    move(sourceModel, targetModel);
+    const moved = move(sourceModel, targetModel);
+    if (!moved) {
+      return;
+    }
+
     if (options?.persist !== false && this.ensureModelRepository()) {
-      const position = sourceModel.sortIndex - targetModel.sortIndex > 0 ? 'after' : 'before';
-      await this._modelRepository.move(sourceId, targetId, position);
+      await this._modelRepository.move(sourceUid, targetUid, position);
+      this._loadedPageCache.markDirty(dirtyLoadedPageKey);
     }
     // 触发事件以通知其他部分模型已移动
     sourceModel.parent.emitter.emit('onSubModelMoved', { source: sourceModel, target: targetModel });

package/src/models/__tests__/flowModel.test.ts

@@ -313,6 +313,19 @@ describe('FlowModel', () => {
 
         model.emitter.off('onStepParamsChanged', listener);
       });
+
+      test('should not emit onStepParamsChanged when params are unchanged', () => {
+        const listener = vi.fn();
+        model.emitter.on('onStepParamsChanged', listener);
+
+        model.setStepParams('testFlow', 'step1', { param1: 'value1' });
+        model.setStepParams('testFlow', { step1: { param1: 'value1' } });
+        model.setStepParams({ testFlow: { step1: { param1: 'value1' } } });
+
+        expect(listener).not.toHaveBeenCalled();
+
+        model.emitter.off('onStepParamsChanged', listener);
+      });
     });
   });
 

package/src/models/flowModel.tsx

@@ -58,6 +58,25 @@ const classEventRegistries = new WeakMap<typeof FlowModel, ModelEventRegistry>()
 // 使用WeakMap存储每个类的meta
 const modelMetas = new WeakMap<typeof FlowModel, FlowModelMeta>();
 
+type SortableModelLike = {
+  sortIndex?: number | null;
+};
+
+function getStableSortIndex(item: SortableModelLike, fallbackIndex: number) {
+  return typeof item?.sortIndex === 'number' && Number.isFinite(item.sortIndex) ? item.sortIndex : fallbackIndex + 1;
+}
+
+function sortByStableSortIndex<T extends SortableModelLike>(items: T[]) {
+  return items
+    .map((item, index) => ({
+      item,
+      index,
+      sortIndex: getStableSortIndex(item, index),
+    }))
+    .sort((a, b) => a.sortIndex - b.sortIndex || a.index - b.index)
+    .map(({ item }) => item);
+}
+
 // 使用WeakMap存储每个类的 GlobalFlowRegistry
 const modelGlobalRegistries = new WeakMap<typeof FlowModel, GlobalFlowRegistry>();
 
@@ -178,7 +197,7 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     };
     this.stepParams = options.stepParams || {};
     this.subModels = {};
-    this.sortIndex = options.sortIndex || 0;
+    this.sortIndex = getStableSortIndex({ sortIndex: options.sortIndex }, -1);
     this._options = options;
     this._title = '';
     this._extraTitle = '';
@@ -447,11 +466,9 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
 
     Object.entries(mergedSubModels || {}).forEach(([key, value]) => {
       if (Array.isArray(value)) {
-        value
-          .sort((a, b) => (a.sortIndex || 0) - (b.sortIndex || 0))
-          .forEach((item) => {
-            this.addSubModel(key, item);
-          });
+        sortByStableSortIndex(value).forEach((item) => {
+          this.addSubModel(key, item);
+        });
       } else {
         this.setSubModel(key, value);
       }
@@ -712,26 +729,43 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     stepKeyOrStepsParams?: string | Record<string, ParamObject>,
     params?: ParamObject,
   ): void {
+    let hasChanged = false;
+
     if (typeof flowKeyOrAllParams === 'string') {
       const flowKey = flowKeyOrAllParams;
       if (typeof stepKeyOrStepsParams === 'string' && params !== undefined) {
-        if (!this.stepParams[flowKey]) {
-          this.stepParams[flowKey] = {};
+        const currentStepParams = this.stepParams[flowKey]?.[stepKeyOrStepsParams] || {};
+        const nextStepParams = { ...currentStepParams, ...params };
+        if (!_.isEqual(currentStepParams, nextStepParams)) {
+          if (!this.stepParams[flowKey]) {
+            this.stepParams[flowKey] = {};
+          }
+          this.stepParams[flowKey][stepKeyOrStepsParams] = nextStepParams;
+          hasChanged = true;
         }
-        this.stepParams[flowKey][stepKeyOrStepsParams] = {
-          ...this.stepParams[flowKey][stepKeyOrStepsParams],
-          ...params,
-        };
       } else if (typeof stepKeyOrStepsParams === 'object' && stepKeyOrStepsParams !== null) {
-        this.stepParams[flowKey] = { ...(this.stepParams[flowKey] || {}), ...stepKeyOrStepsParams };
+        const currentFlowParams = this.stepParams[flowKey] || {};
+        const nextFlowParams = { ...currentFlowParams, ...stepKeyOrStepsParams };
+        if (!_.isEqual(currentFlowParams, nextFlowParams)) {
+          this.stepParams[flowKey] = nextFlowParams;
+          hasChanged = true;
+        }
       }
     } else if (typeof flowKeyOrAllParams === 'object' && flowKeyOrAllParams !== null) {
       for (const fk in flowKeyOrAllParams) {
         if (Object.prototype.hasOwnProperty.call(flowKeyOrAllParams, fk)) {
-          this.stepParams[fk] = { ...(this.stepParams[fk] || {}), ...flowKeyOrAllParams[fk] };
+          const currentFlowParams = this.stepParams[fk] || {};
+          const nextFlowParams = { ...currentFlowParams, ...flowKeyOrAllParams[fk] };
+          if (!_.isEqual(currentFlowParams, nextFlowParams)) {
+            this.stepParams[fk] = nextFlowParams;
+            hasChanged = true;
+          }
         }
       }
     }
+    if (!hasChanged) {
+      return;
+    }
     // 发起配置修改事件
     this.emitter.emit('onStepParamsChanged');
   }
@@ -1140,7 +1174,10 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
     if (!Array.isArray(subModels[subKey])) {
       subModels[subKey] = observable.shallow([]);
     }
-    const maxSortIndex = Math.max(...(subModels[subKey] as FlowModel[]).map((item) => item.sortIndex || 0), 0);
+    const maxSortIndex = Math.max(
+      ...(subModels[subKey] as FlowModel[]).map((item, index) => getStableSortIndex(item, index)),
+      0,
+    );
     model.sortIndex = maxSortIndex + 1;
     subModels[subKey].push(model);
     actualParent.emitter.emit('onSubModelAdded', model);
@@ -1198,14 +1235,12 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
 
     const results: ArrayElementType<Structure['subModels'][K]>[] = [];
 
-    _.castArray(model)
-      .sort((a, b) => (a.sortIndex || 0) - (b.sortIndex || 0))
-      .forEach((item, index) => {
-        const result = (callback as (model: any, index: number) => boolean)(item, index);
-        if (result) {
-          results.push(item);
-        }
-      });
+    sortByStableSortIndex(_.castArray(model)).forEach((item, index) => {
+      const result = (callback as (model: any, index: number) => boolean)(item, index);
+      if (result) {
+        results.push(item);
+      }
+    });
 
     return results;
   }
@@ -1222,12 +1257,10 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
 
     const results: R[] = [];
 
-    _.castArray(model)
-      .sort((a, b) => (a.sortIndex || 0) - (b.sortIndex || 0))
-      .forEach((item, index) => {
-        const result = (callback as (model: any, index: number) => R)(item, index);
-        results.push(result);
-      });
+    sortByStableSortIndex(_.castArray(model)).forEach((item, index) => {
+      const result = (callback as (model: any, index: number) => R)(item, index);
+      results.push(result);
+    });
 
     return results;
   }

package/src/runjs-context/contexts/FormJSFieldItemRunJSContext.ts

@@ -8,14 +8,15 @@
  */
 
 import { FlowRunJSContext } from '../../flowContext';
+import { createElementPropertyDoc, createZhCNElementPropertyDoc } from './elementDoc';
 
 export class FormJSFieldItemRunJSContext extends FlowRunJSContext {}
 
 FormJSFieldItemRunJSContext.define({
   label: 'FormJSFieldItem RunJS context',
   properties: {
-    element: `ElementProxy instance providing a safe DOM container for form field rendering.
-      Supports innerHTML, append, and other DOM manipulation methods.`,
+    element: createElementPropertyDoc(`ElementProxy instance providing a safe DOM container for form field rendering.
+      Supports innerHTML, append, and other DOM manipulation methods.`),
     value: `Current field value (read-only in display mode; in controlled scenarios, use setProps to modify).`,
     record: `Current record data object (read-only).
       Contains all field values of the parent record.`,
@@ -38,7 +39,7 @@ FormJSFieldItemRunJSContext.define(
   {
     label: '表单 JS 字段项 RunJS 上下文',
     properties: {
-      element: 'ElementProxy，表单字段容器',
+      element: createZhCNElementPropertyDoc('ElementProxy，表单字段容器'),
       value: '字段值（展示模式为只读；受控场景用 setProps 修改）',
       record: '当前记录（只读）',
       formValues: {

package/src/runjs-context/contexts/JSBlockRunJSContext.ts

@@ -8,21 +8,16 @@
  */
 
 import { FlowRunJSContext } from '../../flowContext';
+import { createElementPropertyDoc, createZhCNElementPropertyDoc } from './elementDoc';
 
 export class JSBlockRunJSContext extends FlowRunJSContext {}
 
 JSBlockRunJSContext.define({
   label: 'RunJS context',
   properties: {
-    element: {
-      description: `ElementProxy instance providing a safe DOM container.
+    element: createElementPropertyDoc(`ElementProxy instance providing a safe DOM container.
       Supports innerHTML, append, and other DOM manipulation methods.
-      Use this to render content in the JS block.`,
-      detail: 'ElementProxy',
-      properties: {
-        innerHTML: 'Set or read the HTML content of the container element.',
-      },
-    },
+      Use this to render content in the JS block.`),
     record: `Current record data object (read-only).
       Available when the JS block is within a data block or detail view context.`,
     value: 'Current value of the field or component, if available in the current context.',
@@ -44,13 +39,7 @@ JSBlockRunJSContext.define(
   {
     label: 'RunJS 上下文',
     properties: {
-      element: {
-        description: 'ElementProxy，安全的 DOM 容器，支持 innerHTML/append 等',
-        detail: 'ElementProxy',
-        properties: {
-          innerHTML: '读取或设置容器的 HTML 内容',
-        },
-      },
+      element: createZhCNElementPropertyDoc('ElementProxy，安全的 DOM 容器，支持 innerHTML/append 等'),
       record: '当前记录（只读，用于数据区块/详情等场景）',
       value: '当前值（若存在）',
       React: 'React 库',

package/src/runjs-context/contexts/JSColumnRunJSContext.ts

@@ -8,6 +8,7 @@
  */
 
 import { FlowRunJSContext } from '../../flowContext';
+import { createElementPropertyDoc, createZhCNElementPropertyDoc } from './elementDoc';
 
 /**
  * RunJS context for JSColumnModel (table custom column).
@@ -18,8 +19,9 @@ export class JSColumnRunJSContext extends FlowRunJSContext {}
 JSColumnRunJSContext.define({
   label: 'JSColumn RunJS context',
   properties: {
-    element:
+    element: createElementPropertyDoc(
       'ElementProxy instance providing a safe DOM container for the current table cell. Supports innerHTML/append and basic DOM APIs.',
+    ),
     record: 'Current row record object (read-only).',
     recordIndex: 'Index of the current row in the page (0-based).',
     collection: 'Collection definition metadata (read-only).',
@@ -40,7 +42,7 @@ JSColumnRunJSContext.define(
   {
     label: 'JS 列 RunJS 上下文',
     properties: {
-      element: 'ElementProxy，表格单元格的安全 DOM 容器，支持 innerHTML/append 等',
+      element: createZhCNElementPropertyDoc('ElementProxy，表格单元格的安全 DOM 容器，支持 innerHTML/append 等'),
       record: '当前行记录对象（只读）',
       recordIndex: '当前行索引（从 0 开始）',
       collection: '集合定义元数据（只读）',

package/src/runjs-context/contexts/JSEditableFieldRunJSContext.ts

@@ -8,6 +8,7 @@
  */
 
 import { FlowRunJSContext } from '../../flowContext';
+import { createElementPropertyDoc, createZhCNElementPropertyDoc } from './elementDoc';
 
 /**
  * RunJS context for JSEditableFieldModel (form editable custom field).
@@ -19,11 +20,9 @@ export class JSEditableFieldRunJSContext extends FlowRunJSContext {}
 JSEditableFieldRunJSContext.define({
   label: 'JSEditableField RunJS context',
   properties: {
-    element: {
-      description:
-        'ElementProxy instance providing a safe DOM container for field rendering. In editable mode this container is typically a <span> element.',
-      detail: 'ElementProxy',
-    },
+    element: createElementPropertyDoc(
+      'ElementProxy instance providing a safe DOM container for field rendering. In editable mode this container is typically a <span> element.',
+    ),
     value: {
       description:
         'Current field value (read-only snapshot). In editable scenarios, prefer ctx.getValue()/ctx.setValue(v) for two-way binding.',
@@ -69,10 +68,7 @@ JSEditableFieldRunJSContext.define(
   {
     label: 'JS 可编辑字段 RunJS 上下文',
     properties: {
-      element: {
-        description: 'ElementProxy，字段渲染的安全容器（通常为 <span> 容器）。',
-        detail: 'ElementProxy',
-      },
+      element: createZhCNElementPropertyDoc('ElementProxy，字段渲染的安全容器（通常为 <span> 容器）。'),
       value: {
         description: '字段当前值（只读快照）。可编辑场景建议使用 ctx.getValue()/ctx.setValue(v) 做双向绑定。',
         detail: 'any',

package/src/runjs-context/contexts/JSFieldRunJSContext.ts

@@ -8,14 +8,15 @@
  */
 
 import { FlowRunJSContext } from '../../flowContext';
+import { createElementPropertyDoc, createZhCNElementPropertyDoc } from './elementDoc';
 
 export class JSFieldRunJSContext extends FlowRunJSContext {}
 
 JSFieldRunJSContext.define({
   label: 'JSField RunJS context',
   properties: {
-    element: `ElementProxy instance providing a safe DOM container for field rendering.
-      Supports innerHTML, append, and other DOM manipulation methods.`,
+    element: createElementPropertyDoc(`ElementProxy instance providing a safe DOM container for field rendering.
+      Supports innerHTML, append, and other DOM manipulation methods.`),
     value: `Current value of the field (read-only).
       Contains the data value stored in this field.`,
     record: `Current record data object (read-only).
@@ -34,7 +35,7 @@ JSFieldRunJSContext.define(
   {
     label: 'JS 字段 RunJS 上下文',
     properties: {
-      element: 'ElementProxy，字段渲染容器，支持 innerHTML/append 等 DOM 操作',
+      element: createZhCNElementPropertyDoc('ElementProxy，字段渲染容器，支持 innerHTML/append 等 DOM 操作'),
       value: '字段当前值（只读）',
       record: '当前记录对象（只读，包含父记录全部字段值）',
       collection: '集合定义元数据（只读，描述字段所属集合的 Schema）',

package/src/runjs-context/contexts/JSItemRunJSContext.ts

@@ -8,14 +8,15 @@
  */
 
 import { FlowRunJSContext } from '../../flowContext';
+import { createElementPropertyDoc, createZhCNElementPropertyDoc } from './elementDoc';
 
 export class JSItemRunJSContext extends FlowRunJSContext {}
 
 JSItemRunJSContext.define({
   label: 'JSItem RunJS context',
   properties: {
-    element: `ElementProxy instance providing a safe DOM container for form item rendering.
-      Supports innerHTML, append, and other DOM manipulation methods.`,
+    element: createElementPropertyDoc(`ElementProxy instance providing a safe DOM container for form item rendering.
+      Supports innerHTML, append, and other DOM manipulation methods.`),
     resource: `Current resource instance (read-only).
       Provides access to the data resource associated with the current form context.`,
     record: `Current record data object (read-only).
@@ -36,7 +37,7 @@ JSItemRunJSContext.define(
   {
     label: 'JS 表单项 RunJS 上下文',
     properties: {
-      element: 'ElementProxy，表单项渲染容器，支持 innerHTML/append 等 DOM 操作',
+      element: createZhCNElementPropertyDoc('ElementProxy，表单项渲染容器，支持 innerHTML/append 等 DOM 操作'),
       resource: '当前资源（只读）',
       record: '当前记录（只读）',
       formValues: {