@nocobase/flow-engine 2.0.0-alpha.35 → 2.0.0-alpha.36

package/lib/components/FlowModelRenderer.d.ts

@@ -24,7 +24,7 @@ export interface FlowModelRendererProps {
         /**
          * @default 'inside'
          */
-        toolbarPosition?: 'inside' | 'above';
+        toolbarPosition?: 'inside' | 'above' | 'below';
     };
     /** 流程设置的交互风格 */
     flowSettingsVariant?: 'dropdown' | 'contextMenu' | 'modal' | 'drawer';

package/lib/components/settings/wrappers/contextual/FlowsFloatContextMenu.d.ts

@@ -45,7 +45,7 @@ interface ModelProvidedProps {
     /**
      * @default 'inside'
      */
-    toolbarPosition?: 'inside' | 'above';
+    toolbarPosition?: 'inside' | 'above' | 'below';
 }
 interface ModelByIdProps {
     uid: string;
@@ -79,7 +79,7 @@ interface ModelByIdProps {
     /**
      * @default 'inside'
      */
-    toolbarPosition?: 'inside' | 'above';
+    toolbarPosition?: 'inside' | 'above' | 'below';
 }
 type FlowsFloatContextMenuProps = ModelProvidedProps | ModelByIdProps;
 /**

package/lib/components/settings/wrappers/contextual/FlowsFloatContextMenu.js

@@ -83,7 +83,24 @@ const renderToolbarItems = /* @__PURE__ */ __name((model, showDeleteButton, show
     return /* @__PURE__ */ import_react.default.createElement(ItemComponent, { key: itemConfig.key, model });
   });
 }, "renderToolbarItems");
-const floatContainerStyles = /* @__PURE__ */ __name(({ showBackground, showBorder, ctx, toolbarPosition }) => import_css.css`
+const toolbarPositionToCSS = {
+  inside: `
+    top: 2px;
+  `,
+  above: `
+    top: 0px;
+    transform: translateY(-100%);
+    padding-bottom: 2px;
+    margin-bottom: -2px;
+  `,
+  below: `
+    top: 0px;
+    transform: translateY(100%);
+    padding-top: 2px;
+    margin-top: -2px;
+  `
+};
+const floatContainerStyles = /* @__PURE__ */ __name(({ showBackground, showBorder, ctx, toolbarPosition = "inside" }) => import_css.css`
   position: relative;
   display: inline;
 
@@ -149,10 +166,7 @@ const floatContainerStyles = /* @__PURE__ */ __name(({ showBackground, showBorde
       display: none; // 防止遮挡其它 icons
       position: absolute;
       right: 2px;
-      top: ${toolbarPosition === "above" ? "0px" : "2px"};
-      ${toolbarPosition === "above" ? "transform: translateY(-100%);" : ""}
-      ${toolbarPosition === "above" ? "padding-bottom: 2px;" : ""}
-      ${toolbarPosition === "above" ? "margin-bottom: -2px;" : ""}
+      ${toolbarPositionToCSS[toolbarPosition] || ""}
       line-height: 16px;
       pointer-events: all;
 

package/lib/flowContext.js

@@ -1054,7 +1054,7 @@ const _FlowModelContext = class _FlowModelContext extends BaseFlowModelContext {
       }, "get")
     });
     this.defineMethod("openView", async function(uid, options) {
-      var _a, _b, _c, _d, _e, _f, _g;
+      var _a, _b, _c, _d, _e, _f;
       const opts = { ...options };
       if (opts.defineProperties || opts.defineMethod) {
         opts.navigation = false;
@@ -1072,28 +1072,29 @@ const _FlowModelContext = class _FlowModelContext extends BaseFlowModelContext {
           stepParams: {
             popupSettings: {
               openView: {
-                ...import_lodash.default.pick(opts, ["dataSourceKey", "collectionName", "associationName"])
+                // 持久化首次传入的关键展示/数据参数，供后续路由与再次打开复用
+                ...import_lodash.default.pick(opts, ["dataSourceKey", "collectionName", "associationName", "mode", "size"])
               }
             }
           }
         });
         await model2.save();
       }
-      if ((_b = (_a = model2.getStepParams("popupSettings")) == null ? void 0 : _a.openView) == null ? void 0 : _b.dataSourceKey) {
-        model2.setStepParams("popupSettings", {
-          openView: {
-            ...(_c = model2.getStepParams("popupSettings")) == null ? void 0 : _c.openView,
-            ...import_lodash.default.pick(opts, ["dataSourceKey", "collectionName", "associationName"])
-          }
-        });
-        await model2.save();
+      if ((_a = model2.getStepParams("popupSettings")) == null ? void 0 : _a.openView) {
+        const prevOpenView = ((_b = model2.getStepParams("popupSettings")) == null ? void 0 : _b.openView) || {};
+        const incoming = import_lodash.default.pick(opts, ["dataSourceKey", "collectionName", "associationName", "mode", "size"]);
+        const nextOpenView = { ...prevOpenView, ...incoming };
+        if (!import_lodash.default.isEqual(prevOpenView, nextOpenView)) {
+          model2.setStepParams("popupSettings", { openView: nextOpenView });
+          await model2.save();
+        }
       }
-      const viewUid = (opts == null ? void 0 : opts.routeViewUid) ?? (opts == null ? void 0 : opts.viewUid) ?? (((_e = (_d = model2.stepParams) == null ? void 0 : _d.popupSettings) == null ? void 0 : _e.openView) ? model2.uid : this.model.uid);
+      const viewUid = (opts == null ? void 0 : opts.routeViewUid) ?? (opts == null ? void 0 : opts.viewUid) ?? (((_d = (_c = model2.stepParams) == null ? void 0 : _c.popupSettings) == null ? void 0 : _d.openView) ? model2.uid : this.model.uid);
       const parentView = this.view;
       const pendingType = (opts == null ? void 0 : opts.isMobileLayout) ? "embed" : (opts == null ? void 0 : opts.mode) || "drawer";
       const pendingInputArgs = { ...opts, viewUid, navigation: opts.navigation };
-      pendingInputArgs.filterByTk = pendingInputArgs.filterByTk || ((_f = this.inputArgs) == null ? void 0 : _f.filterByTk);
-      pendingInputArgs.sourceId = pendingInputArgs.sourceId || ((_g = this.inputArgs) == null ? void 0 : _g.sourceId);
+      pendingInputArgs.filterByTk = pendingInputArgs.filterByTk || ((_e = this.inputArgs) == null ? void 0 : _e.filterByTk);
+      pendingInputArgs.sourceId = pendingInputArgs.sourceId || ((_f = this.inputArgs) == null ? void 0 : _f.sourceId);
       const pendingView = {
         type: pendingType,
         inputArgs: pendingInputArgs,

package/lib/resources/multiRecordResource.js

@@ -145,12 +145,28 @@ const _MultiRecordResource = class _MultiRecordResource extends import_baseRecor
     return data;
   }
   async update(filterByTk, data, options) {
+    const collection = this.context.collection;
+    const filterTargetKey = collection.filterTargetKey;
+    let result = data;
+    const tkData = collection == null ? void 0 : collection.getFilterByTK(this.context.record);
+    if (Array.isArray(filterTargetKey)) {
+      result = {
+        ...data,
+        ...tkData || {}
+      };
+    } else {
+      result = {
+        ...data,
+        [filterTargetKey]: tkData
+      };
+    }
+    console.log(result);
     const config = this.mergeRequestConfig(
       {
         params: {
           filterByTk
         },
-        data
+        data: result
       },
       this.updateActionOptions,
       options

package/lib/resources/singleRecordResource.js

@@ -60,14 +60,29 @@ const _SingleRecordResource = class _SingleRecordResource extends import_baseRec
   async save(data, options) {
     const config = this.mergeRequestConfig(this.saveActionOptions, import_lodash.default.omit(options, ["refresh"]));
     let actionName = "create";
+    let result = data;
     if (!this.isNewRecord) {
       config.params = config.params || {};
       config.params.filterByTk = this.getFilterByTk();
       actionName = "update";
+      const collection = this.context.collection;
+      const filterTargetKey = collection.filterTargetKey;
+      const tkData = collection == null ? void 0 : collection.getFilterByTK(this.context.record);
+      if (Array.isArray(filterTargetKey)) {
+        result = {
+          ...data,
+          ...tkData || {}
+        };
+      } else {
+        result = {
+          ...data,
+          [filterTargetKey]: tkData
+        };
+      }
     }
     await this.runAction(actionName, {
       ...config,
-      data
+      data: result
     });
     this.emit("saved", data);
     if ((options == null ? void 0 : options.refresh) !== false) {

package/lib/utils/associationObjectVariable.d.ts

@@ -13,10 +13,11 @@ import type { FlowContext, PropertyMetaFactory } from '../flowContext';
  * 仅当访问路径以“关联字段名”开头（且继续访问其子属性）时，返回 true 交由服务端解析；
  * 否则在前端解析即可。
  *
- * @param collectionAccessor 返回当前对象所在collection
+ * @param collectionAccessor 返回当前对象所在 collection
+ * @param valueAccessor 可选，本地值访问器。若本地已存在目标子路径的值，则认为无需走后端，优先使用本地值。
  * @returns `(subPath) => boolean` 判断是否需要服务端解析
  */
-export declare function createAssociationSubpathResolver(collectionAccessor: () => Collection | null): (subPath: string) => boolean;
+export declare function createAssociationSubpathResolver(collectionAccessor: () => Collection | null, valueAccessor?: () => unknown): (subPath: string) => boolean;
 /**
  * 构建“对象类变量”的 PropertyMetaFactory：
  * - 暴露集合字段结构（通过 createCollectionContextMeta）用于变量选择器；

package/lib/utils/associationObjectVariable.js

@@ -7,9 +7,11 @@
  * 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) => {
@@ -24,6 +26,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   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, {
@@ -31,6 +41,7 @@ __export(associationObjectVariable_exports, {
   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;
@@ -66,14 +77,23 @@ function toFilterByTk(value, primaryKey) {
   return void 0;
 }
 __name(toFilterByTk, "toFilterByTk");
-function createAssociationSubpathResolver(collectionAccessor) {
+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);
-    return !!(field == null ? void 0 : field.isAssociationField());
+    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");

package/lib/utils/parsePathnameToViewParams.d.ts

@@ -12,7 +12,7 @@ export interface ViewParam {
     /** 标签页唯一标识符 */
     tabUid?: string;
     /** 弹窗记录的 id */
-    filterByTk?: string;
+    filterByTk?: string | Record<string, string | number>;
     /** source Id */
     sourceId?: string;
 }

package/lib/utils/parsePathnameToViewParams.js

@@ -54,16 +54,52 @@ const parsePathnameToViewParams = /* @__PURE__ */ __name((pathname) => {
         break;
       }
     } else if (currentView && i + 1 < segments.length) {
-      const value = segments[i + 1];
+      const rawValue = segments[i + 1];
+      let decoded = rawValue;
+      try {
+        decoded = decodeURIComponent(rawValue);
+      } catch (_) {
+      }
       switch (segment) {
         case "tab":
-          currentView.tabUid = value;
+          currentView.tabUid = decoded;
           break;
-        case "filterbytk":
-          currentView.filterByTk = value;
+        case "filterbytk": {
+          const parseKeyValuePairs = /* @__PURE__ */ __name((s) => {
+            const obj = {};
+            s.split("&").forEach((pair) => {
+              const [k, v = ""] = pair.split("=");
+              if (!k) return;
+              try {
+                const key = decodeURIComponent(k);
+                const val = decodeURIComponent(v);
+                obj[key] = val;
+              } catch (_) {
+                obj[k] = v;
+              }
+            });
+            return obj;
+          }, "parseKeyValuePairs");
+          let parsed = decoded;
+          if (decoded && (decoded.startsWith("{") || decoded.startsWith("["))) {
+            try {
+              const maybe = JSON.parse(decoded);
+              if (maybe && typeof maybe === "object" && !Array.isArray(maybe)) {
+                parsed = maybe;
+              } else {
+                parsed = decoded;
+              }
+            } catch (_) {
+              parsed = decoded;
+            }
+          } else if (decoded && decoded.includes("=") && decoded.includes("&")) {
+            parsed = parseKeyValuePairs(decoded);
+          }
+          currentView.filterByTk = parsed;
           break;
+        }
         case "sourceid":
-          currentView.sourceId = value;
+          currentView.sourceId = decoded;
           break;
         default:
           break;

package/lib/views/ViewNavigation.d.ts

@@ -7,16 +7,10 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 import { FlowEngineContext } from '../flowContext';
-interface ViewParam {
-    /** 视图唯一标识符，一般为某个 Model 实例的 uid */
+import { ViewParam as SharedViewParam } from '../utils';
+type ViewParam = Omit<SharedViewParam, 'viewUid'> & {
     viewUid?: string;
-    /** 标签页唯一标识符 */
-    tabUid?: string;
-    /** 弹窗记录的 id */
-    filterByTk?: string;
-    /** source Id */
-    sourceId?: string;
-}
+};
 /**
  * 将 ViewParam 数组转换为 pathname
  *

package/lib/views/ViewNavigation.js

@@ -31,6 +31,17 @@ __export(ViewNavigation_exports, {
   generatePathnameFromViewParams: () => generatePathnameFromViewParams
 });
 module.exports = __toCommonJS(ViewNavigation_exports);
+function encodeFilterByTk(val) {
+  if (val === void 0 || val === null) return "";
+  if (val && typeof val === "object" && !Array.isArray(val)) {
+    const pairs = Object.entries(val).map(([k, v]) => {
+      return `${encodeURIComponent(String(k))}=${encodeURIComponent(String(v))}`;
+    });
+    return encodeURIComponent(pairs.join("&"));
+  }
+  return encodeURIComponent(String(val));
+}
+__name(encodeFilterByTk, "encodeFilterByTk");
 function generatePathnameFromViewParams(viewParams) {
   if (!viewParams || viewParams.length === 0) {
     return "/admin";
@@ -44,8 +55,11 @@ function generatePathnameFromViewParams(viewParams) {
     if (viewParam.tabUid) {
       segments.push("tab", viewParam.tabUid);
     }
-    if (viewParam.filterByTk) {
-      segments.push("filterbytk", viewParam.filterByTk);
+    if (viewParam.filterByTk != null) {
+      const encoded = encodeFilterByTk(viewParam.filterByTk);
+      if (encoded) {
+        segments.push("filterbytk", encoded);
+      }
     }
     if (viewParam.sourceId) {
       segments.push("sourceid", viewParam.sourceId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/flow-engine",
-  "version": "2.0.0-alpha.35",
+  "version": "2.0.0-alpha.36",
   "private": false,
   "description": "A standalone flow engine for NocoBase, managing workflows, models, and actions.",
   "main": "lib/index.js",
@@ -8,8 +8,8 @@
   "dependencies": {
     "@formily/antd-v5": "1.x",
     "@formily/reactive": "2.x",
-    "@nocobase/sdk": "2.0.0-alpha.35",
-    "@nocobase/shared": "2.0.0-alpha.35",
+    "@nocobase/sdk": "2.0.0-alpha.36",
+    "@nocobase/shared": "2.0.0-alpha.36",
     "ahooks": "^3.7.2",
     "dompurify": "^3.0.2",
     "lodash": "^4.x",
@@ -35,5 +35,5 @@
   ],
   "author": "NocoBase Team",
   "license": "AGPL-3.0",
-  "gitHead": "e60da9bab9fd4c8ba9457e9806d5428054cefa7a"
+  "gitHead": "c1170bac3ba2325b7420ce65e732c1ba8bbb7767"
 }

package/src/__tests__/objectVariable.test.ts

@@ -400,4 +400,65 @@ describe('objectVariable utilities', () => {
     expect(resolved).toEqual({ a: 7 });
     expect((ctx as any).api.request).not.toHaveBeenCalled();
   });
+
+  it('local-first: toOne association subpath uses local value and skips server', async () => {
+    const { engine, collection } = setupEngineWithCollections();
+    const obj = { author: { id: 7, name: 'LocalName' } };
+    const ctx = engine.context as any;
+
+    (ctx as any).api = { request: vi.fn() };
+
+    const metaFactory = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj,
+    );
+
+    ctx.defineProperty('obj', {
+      get: () => obj,
+      cache: false,
+      meta: metaFactory,
+      // 启用“本地优先”：传入 valueAccessor，以便当本地已有该子路径时跳过服务端
+      resolveOnServer: createAssociationSubpathResolver(
+        () => collection,
+        () => obj,
+      ),
+      serverOnlyWhenContextParams: true,
+    });
+
+    const template = { x: '{{ ctx.obj.author.name }}' } as any;
+    const resolved = await (ctx as any).resolveJsonTemplate(template);
+    expect(resolved).toEqual({ x: 'LocalName' });
+    expect((ctx as any).api.request).not.toHaveBeenCalled();
+  });
+
+  it('local-first: toMany association subpath (index + dot) uses local value and skips server', async () => {
+    const { engine, collection } = setupEngineWithCollections();
+    const obj = { tags: [{ id: 11, name: 'T1' }] };
+    const ctx = engine.context as any;
+
+    (ctx as any).api = { request: vi.fn() };
+
+    const metaFactory = createAssociationAwareObjectMetaFactory(
+      () => collection,
+      'Current object',
+      () => obj,
+    );
+
+    ctx.defineProperty('obj', {
+      get: () => obj,
+      cache: false,
+      meta: metaFactory,
+      resolveOnServer: createAssociationSubpathResolver(
+        () => collection,
+        () => obj,
+      ),
+      serverOnlyWhenContextParams: true,
+    });
+
+    const template = { x: '{{ ctx.obj.tags[0].name }}' } as any;
+    const resolved = await (ctx as any).resolveJsonTemplate(template);
+    expect(resolved).toEqual({ x: 'T1' });
+    expect((ctx as any).api.request).not.toHaveBeenCalled();
+  });
 });

package/src/components/FlowModelRenderer.tsx

@@ -74,7 +74,7 @@ export interface FlowModelRendererProps {
         /**
          * @default 'inside'
          */
-        toolbarPosition?: 'inside' | 'above';
+        toolbarPosition?: 'inside' | 'above' | 'below';
       }; // 默认 false
 
   /** 流程设置的交互风格 */
@@ -114,7 +114,7 @@ const FlowModelRendererWithAutoFlows: React.FC<{
         /**
          * @default 'inside'
          */
-        toolbarPosition?: 'inside' | 'above';
+        toolbarPosition?: 'inside' | 'above' | 'below';
       };
   flowSettingsVariant: string;
   hideRemoveInSettings: boolean;
@@ -181,7 +181,7 @@ const FlowModelRendererCore: React.FC<{
         /**
          * @default 'inside'
          */
-        toolbarPosition?: 'inside' | 'above';
+        toolbarPosition?: 'inside' | 'above' | 'below';
       };
   flowSettingsVariant: string;
   hideRemoveInSettings: boolean;

package/src/components/settings/wrappers/contextual/FlowsFloatContextMenu.tsx

@@ -80,8 +80,26 @@ const renderToolbarItems = (
     });
 };
 
+const toolbarPositionToCSS = {
+  inside: `
+    top: 2px;
+  `,
+  above: `
+    top: 0px;
+    transform: translateY(-100%);
+    padding-bottom: 2px;
+    margin-bottom: -2px;
+  `,
+  below: `
+    top: 0px;
+    transform: translateY(100%);
+    padding-top: 2px;
+    margin-top: -2px;
+  `,
+};
+
 // 使用与 NocoBase 一致的悬浮工具栏样式
-const floatContainerStyles = ({ showBackground, showBorder, ctx, toolbarPosition }) => css`
+const floatContainerStyles = ({ showBackground, showBorder, ctx, toolbarPosition = 'inside' }) => css`
   position: relative;
   display: inline;
 
@@ -147,10 +165,7 @@ const floatContainerStyles = ({ showBackground, showBorder, ctx, toolbarPosition
       display: none; // 防止遮挡其它 icons
       position: absolute;
       right: 2px;
-      top: ${toolbarPosition === 'above' ? '0px' : '2px'};
-      ${toolbarPosition === 'above' ? 'transform: translateY(-100%);' : ''}
-      ${toolbarPosition === 'above' ? 'padding-bottom: 2px;' : ''}
-      ${toolbarPosition === 'above' ? 'margin-bottom: -2px;' : ''}
+      ${toolbarPositionToCSS[toolbarPosition] || ''}
       line-height: 16px;
       pointer-events: all;
 
@@ -297,7 +312,7 @@ interface ModelProvidedProps {
   /**
    * @default 'inside'
    */
-  toolbarPosition?: 'inside' | 'above';
+  toolbarPosition?: 'inside' | 'above' | 'below';
 }
 
 interface ModelByIdProps {
@@ -332,7 +347,7 @@ interface ModelByIdProps {
   /**
    * @default 'inside'
    */
-  toolbarPosition?: 'inside' | 'above';
+  toolbarPosition?: 'inside' | 'above' | 'below';
 }
 
 type FlowsFloatContextMenuProps = ModelProvidedProps | ModelByIdProps;

package/src/flowContext.ts

@@ -1422,21 +1422,24 @@ export class FlowModelContext extends BaseFlowModelContext {
           stepParams: {
             popupSettings: {
               openView: {
-                ..._.pick(opts, ['dataSourceKey', 'collectionName', 'associationName']),
+                // 持久化首次传入的关键展示/数据参数，供后续路由与再次打开复用
+                ..._.pick(opts, ['dataSourceKey', 'collectionName', 'associationName', 'mode', 'size']),
               },
             },
           },
         });
         await model.save();
       }
-      if (model.getStepParams('popupSettings')?.openView?.dataSourceKey) {
-        model.setStepParams('popupSettings', {
-          openView: {
-            ...model.getStepParams('popupSettings')?.openView,
-            ..._.pick(opts, ['dataSourceKey', 'collectionName', 'associationName']),
-          },
-        });
-        await model.save();
+      // 若已存在 openView 配置，则按需合并更新（仅覆盖本次显式传入的字段）
+      if (model.getStepParams('popupSettings')?.openView) {
+        const prevOpenView = model.getStepParams('popupSettings')?.openView || {};
+        const incoming = _.pick(opts, ['dataSourceKey', 'collectionName', 'associationName', 'mode', 'size']);
+        const nextOpenView = { ...prevOpenView, ...incoming };
+        // 仅当有变更时才保存，避免不必要的写入
+        if (!_.isEqual(prevOpenView, nextOpenView)) {
+          model.setStepParams('popupSettings', { openView: nextOpenView });
+          await model.save();
+        }
       }
 
       // 路由层级的 viewUid：优先使用 routeViewUid（仅用于路由展示）；

package/src/resources/multiRecordResource.ts

@@ -130,12 +130,29 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
   }
 
   async update(filterByTk: string | number, data: Partial<TDataItem>, options?: AxiosRequestConfig): Promise<void> {
+    const collection = this.context.collection;
+    const filterTargetKey = collection.filterTargetKey;
+    let result = data;
+    const tkData = collection?.getFilterByTK(this.context.record);
+    if (Array.isArray(filterTargetKey)) {
+      result = {
+        ...data,
+        ...(tkData || {}),
+      };
+    } else {
+      result = {
+        ...data,
+        [filterTargetKey]: tkData,
+      };
+    }
+    console.log(result);
+
     const config = this.mergeRequestConfig(
       {
         params: {
           filterByTk,
         },
-        data,
+        data: result,
       },
       this.updateActionOptions,
       options,

package/src/resources/singleRecordResource.ts

@@ -33,15 +33,30 @@ export class SingleRecordResource<TData = any> extends BaseRecordResource<TData>
   async save(data: TData, options?: AxiosRequestConfig & { refresh?: boolean }): Promise<void> {
     const config = this.mergeRequestConfig(this.saveActionOptions, _.omit(options, ['refresh']));
     let actionName = 'create';
+    let result = data;
     // 如果有 filterByTk，则表示是更新操作
     if (!this.isNewRecord) {
       config.params = config.params || {};
       config.params.filterByTk = this.getFilterByTk();
       actionName = 'update';
+      const collection = this.context.collection;
+      const filterTargetKey = collection.filterTargetKey;
+      const tkData = collection?.getFilterByTK(this.context.record);
+      if (Array.isArray(filterTargetKey)) {
+        result = {
+          ...data,
+          ...(tkData || {}),
+        };
+      } else {
+        result = {
+          ...data,
+          [filterTargetKey]: tkData,
+        };
+      }
     }
     await this.runAction(actionName, {
       ...config,
-      data,
+      data: result,
     });
     this.emit('saved', data);
     if (options?.refresh !== false) {

package/src/utils/__tests__/parsePathnameToViewParams.test.ts

@@ -101,4 +101,29 @@ describe('parsePathnameToViewParams', () => {
     const result = parsePathnameToViewParams('///admin//xxx//tab//yyy//');
     expect(result).toEqual([{ viewUid: 'xxx', tabUid: 'yyy' }]);
   });
+
+  test('should parse filterByTk from key-value encoded segment into object', () => {
+    const kv = encodeURIComponent('id=1&tenant=ac');
+    const path = `/admin/xxx/filterbytk/${kv}`;
+    const result = parsePathnameToViewParams(path);
+    expect(result).toEqual([{ viewUid: 'xxx', filterByTk: { id: '1', tenant: 'ac' } }]);
+  });
+
+  test('should parse filterByTk from JSON object segment', () => {
+    const json = encodeURIComponent('{"id":"1","tenant":"ac"}');
+    const path = `/admin/xxx/filterbytk/${json}`;
+    const result = parsePathnameToViewParams(path);
+    expect(result).toEqual([{ viewUid: 'xxx', filterByTk: { id: '1', tenant: 'ac' } }]);
+  });
+
+  test('should keep non-object JSON (array/number) as string for filterByTk', () => {
+    const arr = encodeURIComponent('["a"]');
+    const num = encodeURIComponent('123');
+    const t = encodeURIComponent('true');
+    expect(parsePathnameToViewParams(`/admin/xxx/filterbytk/${arr}`)).toEqual([
+      { viewUid: 'xxx', filterByTk: '["a"]' },
+    ]);
+    expect(parsePathnameToViewParams(`/admin/xxx/filterbytk/${num}`)).toEqual([{ viewUid: 'xxx', filterByTk: '123' }]);
+    expect(parsePathnameToViewParams(`/admin/xxx/filterbytk/${t}`)).toEqual([{ viewUid: 'xxx', filterByTk: 'true' }]);
+  });
 });

package/src/utils/associationObjectVariable.ts

@@ -8,6 +8,7 @@
  */
 
 import type { Collection, CollectionField } from '../data-source';
+import _ from 'lodash';
 import type { FlowContext, PropertyMeta, PropertyMetaFactory } from '../flowContext';
 import { createCollectionContextMeta } from './createCollectionContextMeta';
 
@@ -74,19 +75,34 @@ function toFilterByTk(value: unknown, primaryKey: string | string[]) {
  * 仅当访问路径以“关联字段名”开头（且继续访问其子属性）时，返回 true 交由服务端解析；
  * 否则在前端解析即可。
  *
- * @param collectionAccessor 返回当前对象所在collection
+ * @param collectionAccessor 返回当前对象所在 collection
+ * @param valueAccessor 可选，本地值访问器。若本地已存在目标子路径的值，则认为无需走后端，优先使用本地值。
  * @returns `(subPath) => boolean` 判断是否需要服务端解析
  */
 export function createAssociationSubpathResolver(
   collectionAccessor: () => Collection | null,
+  valueAccessor?: () => unknown,
 ): (subPath: string) => boolean {
   return (p: string) => {
-    if (!p || !p.includes('.')) return false; // 只在访问子属性时才需要后端
+    // 仅在访问子属性时才考虑后端
+    if (!p || !p.includes('.')) return false;
     const base = baseFieldNameOf(p);
     if (!base) return false;
     const collection = collectionAccessor();
     const field = findFieldByName(collection, base);
-    return !!field?.isAssociationField();
+    const isAssoc = !!field?.isAssociationField();
+    if (!isAssoc) return false;
+
+    // 可选：本地优先。当提供 valueAccessor 时，若本地已有该子路径值，则不走后端
+    if (typeof valueAccessor === 'function') {
+      const local = valueAccessor();
+      if (local && typeof local === 'object') {
+        const v = _.get(local as Record<string, unknown>, p);
+        if (typeof v !== 'undefined') return false;
+      }
+    }
+
+    return true;
   };
 }
 

package/src/utils/parsePathnameToViewParams.ts

@@ -13,7 +13,7 @@ export interface ViewParam {
   /** 标签页唯一标识符 */
   tabUid?: string;
   /** 弹窗记录的 id */
-  filterByTk?: string;
+  filterByTk?: string | Record<string, string | number>;
   /** source Id */
   sourceId?: string;
 }
@@ -70,17 +70,61 @@ export const parsePathnameToViewParams = (pathname: string): ViewParam[] => {
     }
     // 处理参数
     else if (currentView && i + 1 < segments.length) {
-      const value = segments[i + 1];
+      const rawValue = segments[i + 1];
+      // 尝试对路径段进行解码
+      let decoded: string = rawValue;
+      try {
+        decoded = decodeURIComponent(rawValue);
+      } catch (_) {
+        // ignore
+      }
 
       switch (segment) {
         case 'tab':
-          currentView.tabUid = value;
+          // tab/sourceId 仅作为字符串处理
+          currentView.tabUid = decoded;
           break;
-        case 'filterbytk':
-          currentView.filterByTk = value;
+        case 'filterbytk': {
+          // 仅在 filterByTk 分支支持对象/JSON/键值对解析
+          const parseKeyValuePairs = (s: string): Record<string, string | number> => {
+            const obj: Record<string, string | number> = {};
+            s.split('&').forEach((pair) => {
+              const [k, v = ''] = pair.split('=');
+              if (!k) return;
+              try {
+                const key = decodeURIComponent(k);
+                const val = decodeURIComponent(v);
+                obj[key] = val;
+              } catch (_) {
+                obj[k] = v;
+              }
+            });
+            return obj;
+          };
+
+          let parsed: string | Record<string, string | number> = decoded;
+          if (decoded && (decoded.startsWith('{') || decoded.startsWith('['))) {
+            try {
+              const maybe = JSON.parse(decoded);
+              if (maybe && typeof maybe === 'object' && !Array.isArray(maybe)) {
+                parsed = maybe as Record<string, string | number>;
+              } else {
+                // 非对象 JSON（如数组/数字）按字符串保留
+                parsed = decoded;
+              }
+            } catch (_) {
+              // 解析失败，按字符串保留
+              parsed = decoded;
+            }
+          } else if (decoded && decoded.includes('=') && decoded.includes('&')) {
+            // 形如 a=b&c=d 的整体段
+            parsed = parseKeyValuePairs(decoded);
+          }
+          currentView.filterByTk = parsed;
           break;
+        }
         case 'sourceid':
-          currentView.sourceId = value;
+          currentView.sourceId = decoded;
           break;
         default:
           // 未知参数，跳过

package/src/views/ViewNavigation.ts

@@ -8,16 +8,21 @@
  */
 
 import { FlowEngineContext } from '../flowContext';
-
-interface ViewParam {
-  /** 视图唯一标识符，一般为某个 Model 实例的 uid */
-  viewUid?: string;
-  /** 标签页唯一标识符 */
-  tabUid?: string;
-  /** 弹窗记录的 id */
-  filterByTk?: string;
-  /** source Id */
-  sourceId?: string;
+import { ViewParam as SharedViewParam } from '../utils';
+
+type ViewParam = Omit<SharedViewParam, 'viewUid'> & { viewUid?: string };
+
+function encodeFilterByTk(val: SharedViewParam['filterByTk']): string {
+  if (val === undefined || val === null) return '';
+  // 1.x 兼容：对象按 key1=v1&key2=v2 拼接后整体 encodeURIComponent
+  if (val && typeof val === 'object' && !Array.isArray(val)) {
+    const pairs = Object.entries(val).map(([k, v]) => {
+      return `${encodeURIComponent(String(k))}=${encodeURIComponent(String(v))}`;
+    });
+    return encodeURIComponent(pairs.join('&'));
+  }
+  // 其它情况按原单值编码（字符串）
+  return encodeURIComponent(String(val));
 }
 
 /**
@@ -53,8 +58,11 @@ export function generatePathnameFromViewParams(viewParams: ViewParam[]): string
     if (viewParam.tabUid) {
       segments.push('tab', viewParam.tabUid);
     }
-    if (viewParam.filterByTk) {
-      segments.push('filterbytk', viewParam.filterByTk);
+    if (viewParam.filterByTk != null) {
+      const encoded = encodeFilterByTk(viewParam.filterByTk);
+      if (encoded) {
+        segments.push('filterbytk', encoded);
+      }
     }
     if (viewParam.sourceId) {
       segments.push('sourceid', viewParam.sourceId);

package/src/views/__tests__/ViewNavigation.test.ts

@@ -173,6 +173,16 @@ describe('generatePathnameFromViewParams', () => {
     );
   });
 
+  it('should encode object filterByTk as encoded key-value string', () => {
+    const path = generatePathnameFromViewParams([{ viewUid: 'xxx', filterByTk: { id: 1, tenant: 'ac' } }]);
+    expect(path).toBe('/admin/xxx/filterbytk/' + encodeURIComponent('id=1&tenant=ac'));
+  });
+
+  it('should omit filterByTk segment for empty string or when absent', () => {
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }])).toBe('/admin/xxx');
+    expect(generatePathnameFromViewParams([{ viewUid: 'xxx', filterByTk: '' }])).toBe('/admin/xxx');
+  });
+
   it('should match parsePathnameToViewParams test cases', () => {
     // Test cases from parsePathnameToViewParams.test.ts
     expect(generatePathnameFromViewParams([{ viewUid: 'xxx' }])).toBe('/admin/xxx');