@nocobase/flow-engine 2.0.0-alpha.7 → 2.0.0-alpha.71

package/lib/scheduler/ModelOperationScheduler.d.ts

@@ -0,0 +1,53 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import type { FlowEngine } from '../flowEngine';
+import type { FlowModel } from '../models/flowModel';
+type LifecycleType = 'created' | 'mounted' | 'unmounted' | 'destroyed' | `event:${string}:start` | `event:${string}:end` | `event:${string}:error`;
+export type ScheduleWhen = LifecycleType | ((e: LifecycleEvent) => boolean);
+export interface ScheduleOptions {
+    when?: ScheduleWhen;
+}
+export type ScheduledCancel = () => boolean;
+export interface LifecycleEvent {
+    type: LifecycleType;
+    uid: string;
+    model?: FlowModel;
+    runId?: string;
+    error?: any;
+    inputArgs?: Record<string, any>;
+    result?: any;
+    flowKey?: string;
+    stepKey?: string;
+}
+export declare class ModelOperationScheduler {
+    private engine;
+    private itemsByTargetUid;
+    private itemIdsByFromUid;
+    private itemsById;
+    private unbindHandlers;
+    private subscribedEventNames;
+    constructor(engine: FlowEngine);
+    /** 外部调用入口 */
+    schedule(fromModelOrUid: FlowModel | string, toUid: string, fn: (model: FlowModel) => Promise<void> | void, options?: ScheduleOptions): ScheduledCancel;
+    cancel(filter: {
+        fromUid?: string;
+        toUid?: string;
+    }): void;
+    /** 引擎关闭时释放 */
+    dispose(): void;
+    private bindEngineLifecycle;
+    private ensureEventSubscriptionIfNeeded;
+    private parseEventWhen;
+    private processLifecycleEvent;
+    private shouldTrigger;
+    private tryExecuteOnce;
+    private internalCancel;
+    private takeItem;
+}
+export default ModelOperationScheduler;

package/lib/scheduler/ModelOperationScheduler.js

@@ -0,0 +1,262 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ModelOperationScheduler_exports = {};
+__export(ModelOperationScheduler_exports, {
+  ModelOperationScheduler: () => ModelOperationScheduler,
+  default: () => ModelOperationScheduler_default
+});
+module.exports = __toCommonJS(ModelOperationScheduler_exports);
+var import_secure = require("uid/secure");
+const _ModelOperationScheduler = class _ModelOperationScheduler {
+  constructor(engine) {
+    this.engine = engine;
+    this.bindEngineLifecycle();
+  }
+  itemsByTargetUid = /* @__PURE__ */ new Map();
+  itemIdsByFromUid = /* @__PURE__ */ new Map();
+  itemsById = /* @__PURE__ */ new Map();
+  unbindHandlers = [];
+  subscribedEventNames = /* @__PURE__ */ new Set();
+  /** 外部调用入口 */
+  schedule(fromModelOrUid, toUid, fn, options) {
+    const fromUid = typeof fromModelOrUid === "string" ? fromModelOrUid : fromModelOrUid == null ? void 0 : fromModelOrUid.uid;
+    if (!fromUid) {
+      throw new Error("scheduleModelOperation: invalid from model or uid");
+    }
+    if (!toUid || typeof toUid !== "string") {
+      throw new Error("scheduleModelOperation: invalid target uid");
+    }
+    const item = {
+      id: (0, import_secure.uid)(),
+      fromUid,
+      toUid,
+      fn,
+      options: {
+        // 默认语义：仅当 when === 'created' 时，对“已存在的目标”进行一次立即执行；
+        // 其它 when 不做立即执行，需等待后续真实生命周期事件。
+        when: (options == null ? void 0 : options.when) ?? "created"
+      }
+    };
+    let targetMap = this.itemsByTargetUid.get(toUid);
+    if (!targetMap) {
+      targetMap = /* @__PURE__ */ new Map();
+      this.itemsByTargetUid.set(toUid, targetMap);
+    }
+    targetMap.set(item.id, item);
+    let fromSet = this.itemIdsByFromUid.get(fromUid);
+    if (!fromSet) {
+      fromSet = /* @__PURE__ */ new Set();
+      this.itemIdsByFromUid.set(fromUid, fromSet);
+    }
+    fromSet.add(item.id);
+    this.itemsById.set(item.id, item);
+    this.ensureEventSubscriptionIfNeeded(item.options.when);
+    const modelNow = this.engine.getModel(toUid);
+    if (modelNow && item.options.when === "created") {
+      void this.tryExecuteOnce(item.id, { type: "created", uid: toUid, model: modelNow });
+    }
+    return () => this.internalCancel(item.id);
+  }
+  cancel(filter) {
+    const { fromUid, toUid } = filter || {};
+    if (toUid && this.itemsByTargetUid.has(toUid)) {
+      const map = this.itemsByTargetUid.get(toUid);
+      if (map)
+        for (const item of map.values()) {
+          if (fromUid && item.fromUid !== fromUid) continue;
+          this.internalCancel(item.id);
+        }
+      return;
+    }
+    if (fromUid && this.itemIdsByFromUid.has(fromUid)) {
+      const set = this.itemIdsByFromUid.get(fromUid);
+      if (set)
+        for (const id of Array.from(set)) {
+          const it = this.itemsById.get(id);
+          if (!it) continue;
+          if (toUid && it.toUid !== toUid) continue;
+          this.internalCancel(id);
+        }
+    }
+  }
+  /** 引擎关闭时释放 */
+  dispose() {
+    try {
+      for (const unbind of this.unbindHandlers) {
+        try {
+          unbind();
+        } catch (err) {
+        }
+      }
+    } finally {
+      this.unbindHandlers = [];
+    }
+    for (const map of this.itemsByTargetUid.values()) {
+      for (const item of map.values()) this.internalCancel(item.id);
+    }
+    this.itemsByTargetUid.clear();
+    this.itemIdsByFromUid.clear();
+  }
+  bindEngineLifecycle() {
+    const emitter = this.engine.emitter;
+    if (!emitter || typeof emitter.on !== "function") return;
+    const onCreated = /* @__PURE__ */ __name(async (e) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: "created" });
+    }, "onCreated");
+    emitter.on("model:created", onCreated);
+    this.unbindHandlers.push(() => emitter.off("model:created", onCreated));
+    const onMounted = /* @__PURE__ */ __name(async (e) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: "mounted" });
+    }, "onMounted");
+    emitter.on("model:mounted", onMounted);
+    this.unbindHandlers.push(() => emitter.off("model:mounted", onMounted));
+    const onGenericBeforeStart = /* @__PURE__ */ __name(async (e) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: "event:beforeRender:start" });
+    }, "onGenericBeforeStart");
+    emitter.on("model:event:beforeRender:start", onGenericBeforeStart);
+    this.unbindHandlers.push(() => emitter.off("model:event:beforeRender:start", onGenericBeforeStart));
+    const onGenericBeforeEnd = /* @__PURE__ */ __name(async (e) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: "event:beforeRender:end" });
+    }, "onGenericBeforeEnd");
+    emitter.on("model:event:beforeRender:end", onGenericBeforeEnd);
+    this.unbindHandlers.push(() => emitter.off("model:event:beforeRender:end", onGenericBeforeEnd));
+    const onUnmounted = /* @__PURE__ */ __name(async (e) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: "unmounted" });
+    }, "onUnmounted");
+    emitter.on("model:unmounted", onUnmounted);
+    this.unbindHandlers.push(() => emitter.off("model:unmounted", onUnmounted));
+    const onDestroyed = /* @__PURE__ */ __name(async (e) => {
+      const targetBucket = this.itemsByTargetUid.get(e.uid);
+      const event = { ...e, type: "destroyed" };
+      if (targetBucket && targetBucket.size) {
+        const ids = Array.from(targetBucket.keys());
+        for (const id of ids) {
+          const it = this.itemsById.get(id);
+          if (!it) continue;
+          if (this.shouldTrigger(it.options.when, event)) {
+            await this.tryExecuteOnce(id, event);
+          } else {
+            this.internalCancel(id);
+          }
+        }
+      }
+    }, "onDestroyed");
+    emitter.on("model:destroyed", onDestroyed);
+    this.unbindHandlers.push(() => emitter.off("model:destroyed", onDestroyed));
+  }
+  ensureEventSubscriptionIfNeeded(when) {
+    if (!when || typeof when !== "string") return;
+    const parsed = this.parseEventWhen(when);
+    if (!parsed) return;
+    const { name } = parsed;
+    if (this.subscribedEventNames.has(name)) return;
+    this.subscribedEventNames.add(name);
+    const emitter = this.engine.emitter;
+    const onStart = /* @__PURE__ */ __name(async (e) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:start` });
+    }, "onStart");
+    const onEnd = /* @__PURE__ */ __name(async (e) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:end` });
+    }, "onEnd");
+    const onError = /* @__PURE__ */ __name(async (e) => {
+      await this.processLifecycleEvent(e.uid, { ...e, type: `event:${name}:error` });
+    }, "onError");
+    emitter.on(`model:event:${name}:start`, onStart);
+    emitter.on(`model:event:${name}:end`, onEnd);
+    emitter.on(`model:event:${name}:error`, onError);
+    this.unbindHandlers.push(() => emitter.off(`model:event:${name}:start`, onStart));
+    this.unbindHandlers.push(() => emitter.off(`model:event:${name}:end`, onEnd));
+    this.unbindHandlers.push(() => emitter.off(`model:event:${name}:error`, onError));
+  }
+  parseEventWhen(when) {
+    if (!when || typeof when !== "string") return null;
+    const m = /^event:(.+):(start|end|error)$/.exec(when);
+    if (!m) return null;
+    return { name: m[1], phase: m[2] };
+  }
+  async processLifecycleEvent(targetUid, event) {
+    const targetBucket = this.itemsByTargetUid.get(targetUid);
+    if (!targetBucket || targetBucket.size === 0) return;
+    const ids = Array.from(targetBucket.keys());
+    for (const id of ids) {
+      const item = this.itemsById.get(id);
+      if (!item) continue;
+      const should = this.shouldTrigger(item.options.when, event);
+      if (!should) continue;
+      await this.tryExecuteOnce(id, event);
+    }
+  }
+  shouldTrigger(when, event) {
+    if (!when) return false;
+    if (typeof when === "function") return !!when(event);
+    return when === event.type;
+  }
+  async tryExecuteOnce(id, event) {
+    var _a, _b;
+    const item = this.takeItem(id);
+    if (!item) return;
+    try {
+      const model = event.model || this.engine.getModel(item.toUid);
+      if (!model) return;
+      await Promise.resolve(item.fn(model));
+    } catch (err) {
+      (_b = (_a = this.engine.logger) == null ? void 0 : _a.error) == null ? void 0 : _b.call(
+        _a,
+        { err, id, fromUid: item.fromUid, toUid: item.toUid, when: item.options.when },
+        "ModelOperationScheduler: operation execution failed"
+      );
+    }
+  }
+  internalCancel(id) {
+    return !!this.takeItem(id);
+  }
+  takeItem(id) {
+    const it = this.itemsById.get(id);
+    if (!it) return void 0;
+    const { toUid, fromUid } = it;
+    const map = this.itemsByTargetUid.get(toUid);
+    if (map) {
+      map.delete(id);
+      if (map.size === 0) this.itemsByTargetUid.delete(toUid);
+    }
+    const set = this.itemIdsByFromUid.get(fromUid);
+    if (set) {
+      set.delete(id);
+      if (set.size === 0) this.itemIdsByFromUid.delete(fromUid);
+    }
+    this.itemsById.delete(id);
+    return it;
+  }
+};
+__name(_ModelOperationScheduler, "ModelOperationScheduler");
+let ModelOperationScheduler = _ModelOperationScheduler;
+var ModelOperationScheduler_default = ModelOperationScheduler;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ModelOperationScheduler
+});

package/lib/types.d.ts

@@ -9,6 +9,7 @@
 /// <reference types="react" />
 import { ISchema } from '@formily/json-schema';
 import { SubModelItem } from './components';
+import type { PropertyOptions } from './flowContext';
 import { FlowContext, FlowModelContext, FlowRuntimeContext, FlowSettingsContext } from './flowContext';
 import type { FlowEngine } from './flowEngine';
 import type { FlowModel } from './models';
@@ -93,6 +94,8 @@ export interface FlowDefinitionOptions<TModel extends FlowModel = FlowModel> {
      * 仅填补缺失，不覆盖已有。固定返回形状：{ [stepKey]: params }
      */
     defaultParams?: Record<string, any> | ((ctx: FlowModelContext) => StepParam | Promise<StepParam>);
+    enableTitle?: boolean;
+    divider?: 'top' | 'bottom';
 }
 export interface IModelComponentProps {
     [key: string]: any;
@@ -110,12 +113,14 @@ export declare enum ActionScene {
     BLOCK_LINKAGE_RULES = 1,
     /** 表单字段级联动规则可用 */
     FIELD_LINKAGE_RULES = 2,
+    /** 子表单字段级联动规则可用 */
+    SUB_FORM_FIELD_LINKAGE_RULES = 3,
     /** 详情字段级联动规则可用 */
-    DETAILS_FIELD_LINKAGE_RULES = 3,
+    DETAILS_FIELD_LINKAGE_RULES = 4,
     /** 按钮级联动规则可用 */
-    ACTION_LINKAGE_RULES = 4,
+    ACTION_LINKAGE_RULES = 5,
     /** 动态事件流可用 */
-    DYNAMIC_EVENT_FLOW = 5
+    DYNAMIC_EVENT_FLOW = 6
 }
 /**
  * Defines a reusable action with generic model type support.
@@ -132,6 +137,28 @@ export interface ActionDefinition<TModel extends FlowModel = FlowModel, TCtx ext
     uiMode?: StepUIMode | ((ctx: FlowRuntimeContext<TModel>) => StepUIMode | Promise<StepUIMode>);
     scene?: ActionScene | ActionScene[];
     sort?: number;
+    /**
+     * Whether the step/action requires params to be configured before use.
+     */
+    paramsRequired?: boolean;
+    /**
+     * Whether to hide this step/action from settings menus.
+     * - Supports static boolean and dynamic decision based on runtime context.
+     * - StepDefinition.hideInSettings can override the ActionDefinition value.
+     */
+    hideInSettings?: boolean | ((ctx: TCtx) => boolean | Promise<boolean>);
+    /**
+     * 在执行 Action 前为 ctx 定义临时属性。
+     * - 仅支持 PropertyOptions 形态（例如：{ foo: { value: 5 } }）；
+     * - 或函数形式（接收 ctx，返回 PropertyOptions 对象；支持 Promise）。
+     */
+    defineProperties?: Record<string, PropertyOptions> | ((ctx: TCtx) => Record<string, PropertyOptions> | Promise<Record<string, PropertyOptions>>);
+    /**
+     * 在执行 Action 前为 ctx 定义临时方法。
+     * - 支持 JSON 形式（对象的值应为函数）
+     * - 或函数形式（接收 ctx，返回方法对象；支持 Promise）
+     */
+    defineMethods?: Record<string, (this: TCtx, ...args: any[]) => any> | ((ctx: TCtx) => Record<string, (this: TCtx, ...args: any[]) => any> | Promise<Record<string, (this: TCtx, ...args: any[]) => any>>);
 }
 /**
  * Flow 事件名称集合。
@@ -139,20 +166,45 @@ export interface ActionDefinition<TModel extends FlowModel = FlowModel, TCtx ext
  * - 允许扩展字符串以保持向后兼容。
  */
 export type FlowEventName = 'click' | 'submit' | 'reset' | 'remove' | 'openView' | 'dropdownOpen' | 'popupScroll' | 'search' | 'customRequest' | 'collapseToggle' | (string & {});
+/**
+ * 事件流的执行时机（phase）。
+ *
+ * 说明：
+ * - 缺省（phase 未配置）表示保持现有行为；
+ * - 当配置了 phase 时，运行时会将其映射为 `scheduleModelOperation` 的 `when` 锚点；
+ * - phase 同时适用于动态事件流（实例级）与静态流（内置）。
+ */
+export type FlowEventPhase = 'beforeAllFlows' | 'afterAllFlows' | 'beforeFlow' | 'afterFlow' | 'beforeStep' | 'afterStep';
 /**
  * Flow 事件类型（供 FlowDefinitionOptions.on 使用）。
  */
 export type FlowEvent<TModel extends FlowModel = FlowModel> = FlowEventName | {
     eventName: FlowEventName;
     defaultParams?: Record<string, any>;
+    /** 动态事件流的执行时机（默认 beforeAllFlows） */
+    phase?: FlowEventPhase;
+    /** phase 为 beforeFlow/afterFlow/beforeStep/afterStep 时使用 */
+    flowKey?: string;
+    /** phase 为 beforeStep/afterStep 时使用 */
+    stepKey?: string;
 };
+/**
+ * 事件分发选项。
+ */
+export interface DispatchEventOptions {
+    /** 是否顺序执行（默认并行） */
+    sequential?: boolean;
+    /** 是否使用缓存（默认 false；beforeRender 的默认值为 true，可覆盖） */
+    useCache?: boolean;
+}
 /**
  * 事件定义：用于事件注册表（全局/模型类级）。
  */
 export type EventDefinition<TModel extends FlowModel = FlowModel, TCtx extends FlowContext = FlowContext> = ActionDefinition<TModel, TCtx>;
 export type StepUIMode = 'dialog' | 'drawer' | 'embed' | {
-    type?: 'dialog' | 'drawer' | 'embed';
+    type?: 'dialog' | 'drawer' | 'embed' | 'select' | 'switch';
     props?: Record<string, any>;
+    key?: string;
 };
 /**
  * Step definition with unified support for both registered actions and inline handlers
@@ -164,8 +216,6 @@ export interface StepDefinition<TModel extends FlowModel = FlowModel> extends Pa
     use?: string;
     sort?: number;
     preset?: boolean;
-    paramsRequired?: boolean;
-    hideInSettings?: boolean;
     uiMode?: StepUIMode | ((ctx: FlowRuntimeContext<TModel>) => StepUIMode | Promise<StepUIMode>);
 }
 /**
@@ -216,6 +266,14 @@ export type ParamObject = {
  * 已注册模型的类名
  */
 export type RegisteredModelClassName = string;
+/**
+ * resolveUse 返回类型：可返回目标 use，或 { use, stop } 包含中断标志。
+ */
+export type ResolveUseResult = RegisteredModelClassName | ModelConstructor | {
+    use: RegisteredModelClassName | ModelConstructor;
+    /** 标记是否终止后续 resolveUse 链；默认 false（继续解析） */
+    stop?: boolean;
+};
 /**
  * Options for creating a model instance
  */
@@ -240,6 +298,7 @@ export interface IFlowModelRepository<T extends FlowModel = FlowModel> {
     }): Promise<Record<string, any>>;
     destroy(uid: string): Promise<boolean>;
     move(sourceId: string, targetId: string, position: 'before' | 'after'): Promise<void>;
+    duplicate(uid: string): Promise<Record<string, any> | null>;
 }
 /**
  * 步骤设置对话框的属性接口
@@ -341,7 +400,7 @@ export type FlowModelMeta = Pick<SubModelItem, 'key' | 'label' | 'icon' | 'child
      * 是否在菜单中隐藏该模型类
      * @default false
      */
-    hide?: boolean;
+    hide?: boolean | ((context: FlowModelContext) => boolean);
     eventList?: {
         label: string;
         value: string;

package/lib/types.js

@@ -32,9 +32,10 @@ module.exports = __toCommonJS(types_exports);
 var ActionScene = /* @__PURE__ */ ((ActionScene2) => {
   ActionScene2[ActionScene2["BLOCK_LINKAGE_RULES"] = 1] = "BLOCK_LINKAGE_RULES";
   ActionScene2[ActionScene2["FIELD_LINKAGE_RULES"] = 2] = "FIELD_LINKAGE_RULES";
-  ActionScene2[ActionScene2["DETAILS_FIELD_LINKAGE_RULES"] = 3] = "DETAILS_FIELD_LINKAGE_RULES";
-  ActionScene2[ActionScene2["ACTION_LINKAGE_RULES"] = 4] = "ACTION_LINKAGE_RULES";
-  ActionScene2[ActionScene2["DYNAMIC_EVENT_FLOW"] = 5] = "DYNAMIC_EVENT_FLOW";
+  ActionScene2[ActionScene2["SUB_FORM_FIELD_LINKAGE_RULES"] = 3] = "SUB_FORM_FIELD_LINKAGE_RULES";
+  ActionScene2[ActionScene2["DETAILS_FIELD_LINKAGE_RULES"] = 4] = "DETAILS_FIELD_LINKAGE_RULES";
+  ActionScene2[ActionScene2["ACTION_LINKAGE_RULES"] = 5] = "ACTION_LINKAGE_RULES";
+  ActionScene2[ActionScene2["DYNAMIC_EVENT_FLOW"] = 6] = "DYNAMIC_EVENT_FLOW";
   return ActionScene2;
 })(ActionScene || {});
 // Annotate the CommonJS export names for ESM import in node:

package/lib/utils/associationObjectVariable.d.ts

@@ -0,0 +1,32 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+import type { Collection } from '../data-source';
+import type { FlowContext, PropertyMetaFactory } from '../flowContext';
+/**
+ * 创建一个用于“对象类变量”（如 formValues / currentObject）的 `resolveOnServer` 判定函数。
+ * 仅当访问路径以“关联字段名”开头（且继续访问其子属性）时，返回 true 交由服务端解析；
+ * 否则在前端解析即可。
+ *
+ * @param collectionAccessor 返回当前对象所在 collection
+ * @param valueAccessor 可选，本地值访问器。若本地已存在目标子路径的值，则认为无需走后端，优先使用本地值。
+ * @returns `(subPath) => boolean` 判断是否需要服务端解析
+ */
+export declare function createAssociationSubpathResolver(collectionAccessor: () => Collection | null, valueAccessor?: () => unknown): (subPath: string) => boolean;
+/**
+ * 构建“对象类变量”的 PropertyMetaFactory：
+ * - 暴露集合字段结构（通过 createCollectionContextMeta）用于变量选择器；
+ * - 提供 buildVariablesParams：基于对象当前值，收集所有“已选择的关联字段”
+ *   以便服务端在 variables:resolve 时按需补全关联数据。
+ *
+ * @param collectionAccessor 获取集合对象，用于字段/元信息来源
+ * @param title 变量组标题（用于 UI 展示）
+ * @param valueAccessor 获取当前对象值（如 ctx.form.getFieldsValue() / ctx.currentObject）
+ * @returns PropertyMetaFactory
+ */
+export declare function createAssociationAwareObjectMetaFactory(collectionAccessor: () => Collection | null, title: string, valueAccessor: (ctx: FlowContext) => any): PropertyMetaFactory;

package/lib/utils/associationObjectVariable.js

@@ -0,0 +1,157 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var associationObjectVariable_exports = {};
+__export(associationObjectVariable_exports, {
+  createAssociationAwareObjectMetaFactory: () => createAssociationAwareObjectMetaFactory,
+  createAssociationSubpathResolver: () => createAssociationSubpathResolver
+});
+module.exports = __toCommonJS(associationObjectVariable_exports);
+var import_lodash = __toESM(require("lodash"));
+var import_createCollectionContextMeta = require("./createCollectionContextMeta");
+function baseFieldNameOf(subPath) {
+  if (!subPath) return void 0;
+  const m = subPath.match(/^([^.[]+)/);
+  return m == null ? void 0 : m[1];
+}
+__name(baseFieldNameOf, "baseFieldNameOf");
+function findFieldByName(collection, name) {
+  var _a;
+  if (!collection || !name) return void 0;
+  const direct = collection.getField(name);
+  if (direct) return direct;
+  const fields = ((_a = collection.getFields) == null ? void 0 : _a.call(collection)) || [];
+  return fields.find((f) => f.name === name);
+}
+__name(findFieldByName, "findFieldByName");
+function toFilterByTk(value, primaryKey) {
+  if (value == null) return void 0;
+  if (Array.isArray(primaryKey)) {
+    if (typeof value !== "object" || !value) return void 0;
+    const out = {};
+    for (const k of primaryKey) {
+      const v = value[k];
+      if (typeof v === "undefined" || v === null) return void 0;
+      out[k] = v;
+    }
+    return out;
+  }
+  if (typeof value === "string" || typeof value === "number") return value;
+  if (typeof value === "object") {
+    return value[primaryKey];
+  }
+  return void 0;
+}
+__name(toFilterByTk, "toFilterByTk");
+function createAssociationSubpathResolver(collectionAccessor, valueAccessor) {
+  return (p) => {
+    if (!p || !p.includes(".")) return false;
+    const base = baseFieldNameOf(p);
+    if (!base) return false;
+    const collection = collectionAccessor();
+    const field = findFieldByName(collection, base);
+    const isAssoc = !!(field == null ? void 0 : field.isAssociationField());
+    if (!isAssoc) return false;
+    if (typeof valueAccessor === "function") {
+      const local = valueAccessor();
+      if (local && typeof local === "object") {
+        const v = import_lodash.default.get(local, p);
+        if (typeof v !== "undefined") return false;
+      }
+    }
+    return true;
+  };
+}
+__name(createAssociationSubpathResolver, "createAssociationSubpathResolver");
+function createAssociationAwareObjectMetaFactory(collectionAccessor, title, valueAccessor) {
+  const baseFactory = (0, import_createCollectionContextMeta.createCollectionContextMeta)(collectionAccessor, title, true);
+  const factory = /* @__PURE__ */ __name(async () => {
+    const base = await baseFactory();
+    if (!base) return null;
+    const meta = {
+      ...base,
+      buildVariablesParams: /* @__PURE__ */ __name((ctx) => {
+        var _a;
+        const collection = collectionAccessor();
+        const obj = valueAccessor(ctx);
+        if (!collection || !obj || typeof obj !== "object") return {};
+        const params = {};
+        const fields = ((_a = collection.getFields) == null ? void 0 : _a.call(collection)) || [];
+        for (const field of fields) {
+          const name = field.name;
+          if (!name) continue;
+          if (!field.isAssociationField()) continue;
+          const target = field.target;
+          const targetCollection = field.targetCollection;
+          if (!target || !targetCollection) continue;
+          const primaryKey = targetCollection.filterTargetKey;
+          const associationValue = obj[name];
+          if (associationValue == null) continue;
+          if (Array.isArray(associationValue)) {
+            const ids = associationValue.map((item) => toFilterByTk(item, primaryKey)).filter((v) => v != null);
+            if (ids.length) {
+              params[name] = {
+                collection: target,
+                dataSourceKey: targetCollection.dataSourceKey,
+                filterByTk: ids
+              };
+            }
+          } else {
+            const id = toFilterByTk(associationValue, primaryKey);
+            if (id != null) {
+              params[name] = {
+                collection: target,
+                dataSourceKey: targetCollection.dataSourceKey,
+                filterByTk: id
+              };
+            }
+          }
+        }
+        return params;
+      }, "buildVariablesParams")
+    };
+    return meta;
+  }, "factory");
+  factory.title = title;
+  return factory;
+}
+__name(createAssociationAwareObjectMetaFactory, "createAssociationAwareObjectMetaFactory");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createAssociationAwareObjectMetaFactory,
+  createAssociationSubpathResolver
+});

package/lib/utils/createCollectionContextMeta.d.ts

@@ -8,4 +8,4 @@
  */
 import type { Collection } from '../data-source';
 import type { PropertyMetaFactory } from '../flowContext';
-export declare function createCollectionContextMeta(collectionOrFactory: Collection | (() => Collection | null), title?: string): PropertyMetaFactory;
+export declare function createCollectionContextMeta(collectionOrFactory: Collection | (() => Collection | null), title?: string, includeNonFilterable?: boolean): PropertyMetaFactory;