@nocobase/plugin-ui-templates 2.0.0-alpha.58 → 2.0.0-alpha.60

package/dist/client/models/ReferenceFormGridModel.d.ts

@@ -8,8 +8,6 @@
  */
 import React from 'react';
 import { type CreateModelOptions, FlowModel } from '@nocobase/flow-engine';
-import { REF_HOST_CTX_KEY } from '../constants';
-export { REF_HOST_CTX_KEY };
 export type ReferenceFormGridTargetSettings = {
     /** 模板 uid（flowModelTemplates.uid） */
     templateUid: string;
@@ -22,15 +20,31 @@ export type ReferenceFormGridTargetSettings = {
 };
 export declare class ReferenceFormGridModel extends FlowModel {
     private _scopedEngine?;
+    private _targetRoot?;
     private _targetGrid?;
     private _resolvedTargetUid?;
     private _invalidTargetUid?;
+    /**
+     * 字段模板场景下，模板内 FormItemModel/CollectionFieldModel 的 onInit 会调用 ctx.blockModel.addAppends(fieldPath)。
+     * 但模板 root 自身也是一个 CollectionBlockModel，会在未桥接宿主上下文时被识别为 blockModel，导致 appends 写到模板 root 的 resource，
+     * 从而宿主表单（如 ApplyFormModel）在刷新记录时缺少关联 appends（例如 users.roles）。
+     *
+     * 这里在目标 grid 解析完成后扫描字段路径，并把需要的 appends 同步到宿主 block（master + forks），确保关系数据可展示。
+     */
+    private _syncHostResourceAppends;
     constructor(options: any);
     private _ensureScopedEngine;
     private _getTargetSettings;
     private _syncHostExtraTitle;
     addSubModel<T extends FlowModel>(subKey: string, options: CreateModelOptions | T): T;
     setSubModel(subKey: string, options: CreateModelOptions | FlowModel): FlowModel<import("@nocobase/flow-engine").DefaultStructure>;
+    getStepParams(flowKey: string, stepKey: string): any | undefined;
+    getStepParams(flowKey: string): Record<string, any> | undefined;
+    getStepParams(): Record<string, any>;
+    setStepParams(flowKey: string, stepKey: string, params: any): void;
+    setStepParams(flowKey: string, stepParams: Record<string, any>): void;
+    setStepParams(allParams: Record<string, any>): void;
+    saveStepParams(): Promise<any>;
     onDispatchEventStart(eventName: string): Promise<void>;
     clearForks(): void;
     destroy(): Promise<boolean>;

package/dist/client/models/SubModelTemplateImporterModel.d.ts

@@ -6,27 +6,14 @@
  * 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 { CommonItemModel } from '@nocobase/client';
 import { FlowModel, FlowContext } from '@nocobase/flow-engine';
 type ImporterProps = {
-    /** 默认从模板根取片段的路径 */
-    defaultSourcePath?: string;
-    /** 模板根 use 过滤（可选），支持多个候选 */
     expectedRootUse?: string | string[];
-    /** 期望的数据源 key（可选，用于禁用不匹配的模板） */
     expectedDataSourceKey?: string;
-    /** 期望的 collectionName（可选，用于禁用不匹配的模板） */
     expectedCollectionName?: string;
-    /** 默认挂载到当前模型的 subModels 键（可选），否则使用 importer.subKey */
-    defaultMountSubKey?: string;
-    /**
-     * 引入片段时挂载到第几层父级：
-     * - 0：挂载到 importer.parent（默认）
-     * - 1：挂载到 importer.parent.parent
-     * - 2：以此类推
-     */
-    mountToParentLevel?: number;
 };
-export declare class SubModelTemplateImporterModel extends FlowModel {
+export declare class SubModelTemplateImporterModel extends CommonItemModel {
     props: ImporterProps;
     resolveExpectedResourceInfo(ctx?: FlowContext, start?: FlowModel): {
         dataSourceKey?: string;

package/dist/client/models/referenceShared.d.ts

@@ -7,8 +7,9 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 import React from 'react';
-import { type FlowEngine, type FlowModel } from '@nocobase/flow-engine';
+import { FlowContext, type FlowEngine, type FlowModel } from '@nocobase/flow-engine';
 export declare function ensureBlockScopedEngine(flowEngine: FlowEngine, scopedEngine?: FlowEngine): FlowEngine;
+export declare function ensureScopedEngineView(engine: FlowEngine, hostContext?: FlowContext): void;
 export declare function unlinkScopedEngine(engine?: FlowEngine): void;
 export declare function renderReferenceTargetPlaceholder(model: {
     translate?: (key: string, options?: any) => string;

package/dist/client/utils/templateCopy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 { FlowModel } from '@nocobase/flow-engine';
+/**
+ * 字段模板 copy 模式只会 duplicate `subModels.grid`，而历史模板可能把部分配置（如布局/连动规则）
+ * 存在模板 root 上。reference 模式通过 getStepParams 的 fallback 能读到这些值，但 copy 模式需要
+ * 主动把这些 stepParams 合并进 grid 的 stepParams，避免丢失。
+ *
+ * - 仅在 grid 上缺失对应 stepKey 时才回填（不覆盖 grid 上已有值）
+ * - 返回 patched 标记，方便调用方决定是否需要 `saveStepParams()`
+ */
+export declare function patchGridOptionsFromTemplateRoot(templateRoot: FlowModel | undefined, gridOptions: any): {
+    options: any;
+    patched: boolean;
+};

package/dist/externalVersion.js

@@ -8,17 +8,17 @@
  */
 
 module.exports = {
-  "@nocobase/client": "2.0.0-alpha.58",
-  "@nocobase/flow-engine": "2.0.0-alpha.58",
+  "@nocobase/client": "2.0.0-alpha.60",
+  "@nocobase/flow-engine": "2.0.0-alpha.60",
   "react": "18.2.0",
   "antd": "5.24.2",
   "@ant-design/icons": "5.6.1",
   "lodash": "4.17.21",
   "@formily/react": "2.3.7",
-  "@nocobase/server": "2.0.0-alpha.58",
-  "@nocobase/plugin-flow-engine": "2.0.0-alpha.58",
-  "@nocobase/utils": "2.0.0-alpha.58",
+  "@nocobase/server": "2.0.0-alpha.60",
+  "@nocobase/plugin-flow-engine": "2.0.0-alpha.60",
+  "@nocobase/utils": "2.0.0-alpha.60",
   "@formily/core": "2.3.7",
-  "@nocobase/database": "2.0.0-alpha.58",
-  "@nocobase/actions": "2.0.0-alpha.58"
+  "@nocobase/database": "2.0.0-alpha.60",
+  "@nocobase/actions": "2.0.0-alpha.60"
 };

package/dist/locale/zh-CN.json

@@ -1,5 +1,5 @@
 {
-  "UI templates": "界面模板",
+  "UI templates": "UI 模板",
   "Block templates (v2)": "区块模板 (v2)",
   "Popup templates (v2)": "弹窗模板 (v2)",
   "Actions": "操作",

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@nocobase/plugin-ui-templates",
   "displayName": "UI templates",
-  "displayName.zh-CN": "界面模板",
+  "displayName.zh-CN": "UI 模板",
   "description": "Provides block templates and popup templates for UI reuse.",
   "description.zh-CN": "提供区块模板和弹窗模板复用的能力。",
-  "version": "2.0.0-alpha.58",
+  "version": "2.0.0-alpha.60",
   "license": "AGPL-3.0",
   "main": "./dist/server/index.js",
   "types": "./dist/index.d.ts",
@@ -33,5 +33,5 @@
     "block",
     "popup"
   ],
-  "gitHead": "be3acea2fb2a6538a8dbe5b6cc7fa0fd5e15e43b"
+  "gitHead": "9113d61ce85b60b7ba3d0e5ca64182d92a15ece4"
 }

package/src/client/index.ts

@@ -15,7 +15,6 @@ import { BlockTemplatesPage, PopupTemplatesPage } from './components/FlowModelTe
 // @ts-ignore
 import pkg from '../../package.json';
 import { registerMenuExtensions } from './menuExtensions';
-import { registerSubModelMenuExtensions } from './subModelMenuExtensions';
 import { registerOpenViewPopupTemplateAction } from './openViewActionExtensions';
 
 const NAMESPACE = 'ui-templates';
@@ -27,7 +26,6 @@ export class PluginBlockReferenceClient extends Plugin {
       ReferenceFormGridModel,
       SubModelTemplateImporterModel,
     });
-    registerSubModelMenuExtensions(this.flowEngine);
     registerOpenViewPopupTemplateAction(this.flowEngine);
 
     // 父级菜单（只有标题，无组件）

package/src/client/menuExtensions.tsx

@@ -22,6 +22,7 @@ import {
   resolveActionScene,
   type PopupTemplateContextFlags,
 } from './utils/templateCompatibility';
+import { patchGridOptionsFromTemplateRoot } from './utils/templateCopy';
 
 type MenuItem = {
   key: string;
@@ -389,18 +390,22 @@ async function handleConvertFieldsToCopy(model: FlowModel, _t: (k: string, opt?:
       }
 
       const duplicated = await model.flowEngine.duplicateModel(gridModel.uid);
+      const merged = patchGridOptionsFromTemplateRoot(root, duplicated);
 
       // 将复制出的 grid（默认脱离父级）移动到当前表单 grid 位置，避免再走 save 重建整棵树
       await model.flowEngine.modelRepository.move(duplicated.uid, currentGrid.uid, 'after');
 
       const newGrid = model.flowEngine.createModel<FlowModel>({
-        ...(duplicated as any),
+        ...(merged.options as any),
         parentId: model.uid,
         subKey: 'grid',
         subType: 'object',
       });
       model.setSubModel('grid', newGrid);
       await newGrid.afterAddAsSubModel();
+      if (merged.patched) {
+        await newGrid.saveStepParams();
+      }
 
       // 引用已清理，回退临时标题（移除“字段模板”标记）
       const clearTemplateTitle = (m: FlowModel) => {
@@ -531,6 +536,49 @@ async function handleSavePopupAsTemplate(model: FlowModel, _t: (k: string, opt?:
     const s = String(val).trim();
     return s ? s : undefined;
   };
+  const resolveDefaultOpenViewResource = (): {
+    dataSourceKey?: string;
+    collectionName?: string;
+    associationName?: string;
+  } => {
+    const ctx = model.context;
+    const field = ctx.collectionField;
+    const associationPathName = model.parent?.['associationPathName'];
+    const blockModel = ctx.blockModel;
+    const fieldCollection = ctx.collection || blockModel?.collection;
+    const isAssociationField = (f): boolean => !!f?.isAssociationField?.();
+    const associationField =
+      !isAssociationField(field) && associationPathName && typeof fieldCollection?.getFieldByPath === 'function'
+        ? fieldCollection.getFieldByPath(associationPathName)
+        : undefined;
+    const assocField = isAssociationField(field) ? field : associationField;
+
+    if (isAssociationField(assocField)) {
+      const targetCollection = assocField?.targetCollection;
+      return {
+        dataSourceKey: toNonEmptyString(targetCollection?.dataSourceKey),
+        collectionName: toNonEmptyString(targetCollection?.name),
+        associationName: toNonEmptyString(assocField?.resourceName),
+      };
+    }
+
+    const collection = ctx.collection;
+    const association = ctx.association;
+    return {
+      dataSourceKey: toNonEmptyString(collection?.dataSourceKey),
+      collectionName: toNonEmptyString(collection?.name),
+      associationName: toNonEmptyString(field?.target || association?.resourceName),
+    };
+  };
+
+  // 兼容历史数据：openViewParams 里固化的 associationName 可能是错的。
+  // 当能从上下文推导出 associationName 时（关联字段/关联字段属性），优先使用推导值。
+  const defaultOpenViewResource = resolveDefaultOpenViewResource();
+  const templateDataSourceKey =
+    defaultOpenViewResource.dataSourceKey || toNonEmptyString(openViewParams?.dataSourceKey);
+  const templateCollectionName =
+    defaultOpenViewResource.collectionName || toNonEmptyString(openViewParams?.collectionName);
+  const templateAssociationName = defaultOpenViewResource.associationName;
   const getDefaultFilterByTkExpr = (): string | undefined => {
     // 与 openView 默认行为对齐：尽量落表达式而非具体值
     const recordKeyPath = model.context?.collection?.filterTargetKey || 'id';
@@ -538,7 +586,7 @@ async function handleSavePopupAsTemplate(model: FlowModel, _t: (k: string, opt?:
   };
   const getDefaultSourceIdExpr = (): string | undefined => {
     // 如果有 associationName，说明是关系资源弹窗，默认需要 sourceId
-    if (toNonEmptyString(openViewParams?.associationName)) {
+    if (templateAssociationName) {
       return `{{ ctx.resource.sourceId }}`;
     }
     try {
@@ -585,9 +633,9 @@ async function handleSavePopupAsTemplate(model: FlowModel, _t: (k: string, opt?:
       targetUid: values.targetUid,
       useModel: model.use,
       type: 'popup',
-      dataSourceKey: openViewParams?.dataSourceKey,
-      collectionName: openViewParams?.collectionName,
-      associationName: openViewParams?.associationName,
+      dataSourceKey: templateDataSourceKey,
+      collectionName: templateCollectionName,
+      associationName: templateAssociationName,
       filterByTk: templateFilterByTk,
       sourceId: templateSourceId,
     };

package/src/client/models/ReferenceBlockModel.tsx

@@ -25,6 +25,7 @@ import {
   ensureBlockScopedEngine,
   ReferenceScopedRenderer,
   renderReferenceTargetPlaceholder,
+  ensureScopedEngineView,
   unlinkScopedEngine,
 } from './referenceShared';
 
@@ -133,6 +134,9 @@ export class ReferenceBlockModel extends BlockModel {
 
   private _ensureScopedEngine(): FlowEngine {
     this._scopedEngine = ensureBlockScopedEngine(this.flowEngine, this._scopedEngine);
+    // 引用区块会在 scoped engine 中 loadModel，目标模型的 onInit 可能会读取 ctx.view。
+    // 部分场景（如审批配置）view 仅存在于宿主模型上下文而非 engine.context，需要显式桥接。
+    ensureScopedEngineView(this._scopedEngine, this.context as any);
     return this._scopedEngine;
   }
 

package/src/client/models/ReferenceFormGridModel.tsx

@@ -9,21 +9,22 @@
 
 import React from 'react';
 import _ from 'lodash';
-import { type CreateModelOptions, FlowEngine, FlowModel } from '@nocobase/flow-engine';
-import { FormGridModel } from '@nocobase/client';
+import { type CreateModelOptions, FlowContext, FlowEngine, FlowModel } from '@nocobase/flow-engine';
 import { REF_HOST_CTX_KEY } from '../constants';
 import { NAMESPACE } from '../locale';
 import {
   ensureBlockScopedEngine,
   ReferenceScopedRenderer,
   renderReferenceTargetPlaceholder,
+  ensureScopedEngineView,
   unlinkScopedEngine,
 } from './referenceShared';
 
 const SETTINGS_FLOW_KEY = 'referenceSettings';
 const SETTINGS_STEP_KEY = 'useTemplate';
 
-export { REF_HOST_CTX_KEY };
+/** 标记已添加 host context bridge，避免重复添加 */
+const BRIDGE_MARKER = Symbol.for('nocobase.refGridHostBridge');
 
 export type ReferenceFormGridTargetSettings = {
   /** 模板 uid（flowModelTemplates.uid） */
@@ -36,25 +37,58 @@ export type ReferenceFormGridTargetSettings = {
   targetPath?: string;
 };
 
-type ReferenceHostInfo = {
-  hostUid?: string;
-  hostUse?: string;
-  ref: {
-    templateUid: string;
-    templateName?: string;
-    targetUid: string;
-    targetPath: string;
-    mountSubKey: 'grid';
-    mode: 'reference';
-  };
-};
-
 export class ReferenceFormGridModel extends FlowModel {
   private _scopedEngine?: FlowEngine;
+  private _targetRoot?: FlowModel;
   private _targetGrid?: FlowModel;
   private _resolvedTargetUid?: string;
   private _invalidTargetUid?: string;
 
+  /**
+   * 字段模板场景下，模板内 FormItemModel/CollectionFieldModel 的 onInit 会调用 ctx.blockModel.addAppends(fieldPath)。
+   * 但模板 root 自身也是一个 CollectionBlockModel，会在未桥接宿主上下文时被识别为 blockModel，导致 appends 写到模板 root 的 resource，
+   * 从而宿主表单（如 ApplyFormModel）在刷新记录时缺少关联 appends（例如 users.roles）。
+   *
+   * 这里在目标 grid 解析完成后扫描字段路径，并把需要的 appends 同步到宿主 block（master + forks），确保关系数据可展示。
+   */
+  private _syncHostResourceAppends(host: FlowModel, targetGrid: FlowModel) {
+    if (!host['addAppends']) {
+      return;
+    }
+    const candidates = new Set<string>();
+    const addCandidate = (val: unknown) => {
+      const s = typeof val === 'string' ? val.trim() : '';
+      if (!s) return;
+      candidates.add(s);
+      const top = s.split('.')[0]?.trim();
+      if (top) candidates.add(top);
+    };
+
+    const visit = (m: FlowModel) => {
+      const init = m.getStepParams?.('fieldSettings', 'init') as
+        | { fieldPath?: string; associationPathName?: string }
+        | undefined;
+      if (init) {
+        addCandidate(init.fieldPath);
+        addCandidate(init.associationPathName);
+      }
+      const subs = m.subModels || {};
+      for (const v of Object.values(subs)) {
+        if (Array.isArray(v)) {
+          v.forEach((c) => c instanceof FlowModel && visit(c));
+        } else if (v instanceof FlowModel) {
+          visit(v);
+        }
+      }
+    };
+
+    visit(targetGrid);
+    if (candidates.size === 0) return;
+    for (const fieldPath of candidates) {
+      (host as any).addAppends?.(fieldPath);
+    }
+  }
+
   constructor(options: any) {
     super(options);
 
@@ -167,12 +201,100 @@ export class ReferenceFormGridModel extends FlowModel {
     return this._targetGrid.setSubModel(subKey, options);
   }
 
+  getStepParams(flowKey: string, stepKey: string): any | undefined;
+  getStepParams(flowKey: string): Record<string, any> | undefined;
+  getStepParams(): Record<string, any>;
+  getStepParams(flowKey?: string, stepKey?: string): any {
+    if (!flowKey || flowKey === SETTINGS_FLOW_KEY) {
+      return super.getStepParams(flowKey, stepKey);
+    }
+
+    if (!this._targetGrid) {
+      // 未解析完成：允许读取本地 stepParams，避免配置对话框/中间态丢值
+      return super.getStepParams(flowKey, stepKey);
+    }
+
+    if (stepKey) {
+      const fromGrid = this._targetGrid.getStepParams(flowKey, stepKey);
+      if (typeof fromGrid !== 'undefined') return fromGrid;
+      return this._targetRoot?.getStepParams?.(flowKey, stepKey);
+    }
+
+    const gridFlow = this._targetGrid.getStepParams(flowKey) as any;
+    const rootFlow = this._targetRoot?.getStepParams?.(flowKey) as any;
+    if (rootFlow && typeof rootFlow === 'object') {
+      return { ...rootFlow, ...(gridFlow || {}) };
+    }
+    return gridFlow;
+  }
+
+  setStepParams(flowKey: string, stepKey: string, params: any): void;
+  setStepParams(flowKey: string, stepParams: Record<string, any>): void;
+  setStepParams(allParams: Record<string, any>): void;
+  setStepParams(flowKeyOrAllParams: any, stepKeyOrStepsParams?: any, params?: any): void {
+    if (typeof flowKeyOrAllParams === 'string') {
+      const flowKey = flowKeyOrAllParams;
+      if (flowKey === SETTINGS_FLOW_KEY || !this._targetGrid) {
+        super.setStepParams(flowKeyOrAllParams, stepKeyOrStepsParams, params);
+        return;
+      }
+      if (typeof stepKeyOrStepsParams === 'string' && params !== undefined) {
+        this._targetGrid.setStepParams(flowKey, stepKeyOrStepsParams, params);
+        return;
+      }
+      if (typeof stepKeyOrStepsParams === 'object' && stepKeyOrStepsParams !== null) {
+        this._targetGrid.setStepParams(flowKey, stepKeyOrStepsParams);
+      }
+      return;
+    }
+
+    if (typeof flowKeyOrAllParams === 'object' && flowKeyOrAllParams !== null) {
+      const allParams = flowKeyOrAllParams as Record<string, any>;
+      const localAll: Record<string, any> = {};
+      const delegatedAll: Record<string, any> = {};
+      for (const [fk, steps] of Object.entries(allParams)) {
+        if (fk === SETTINGS_FLOW_KEY || !this._targetGrid) {
+          localAll[fk] = steps;
+        } else {
+          delegatedAll[fk] = steps;
+        }
+      }
+      if (Object.keys(localAll).length > 0) {
+        super.setStepParams(localAll);
+      }
+      if (Object.keys(delegatedAll).length > 0 && this._targetGrid) {
+        this._targetGrid.setStepParams(delegatedAll);
+      }
+    }
+  }
+
+  async saveStepParams() {
+    // 如果目标尚未解析，先触发解析
+    if (!this._targetGrid) {
+      await this.dispatchEvent('beforeRender');
+    }
+    // 将本地非 settings 参数刷新到目标 grid
+    if (this._targetGrid && this.stepParams) {
+      for (const [flowKey, steps] of Object.entries(this.stepParams)) {
+        if (flowKey === SETTINGS_FLOW_KEY || typeof steps !== 'object' || steps === null) continue;
+        this._targetGrid.setStepParams(flowKey, steps as Record<string, any>);
+        delete (this.stepParams as Record<string, any>)[flowKey];
+      }
+    }
+    const res = await super.saveStepParams();
+    if (this._targetGrid) {
+      await this._targetGrid.saveStepParams();
+    }
+    return res;
+  }
+
   public async onDispatchEventStart(eventName: string): Promise<void> {
     if (eventName !== 'beforeRender') return;
 
     const settings = this._getTargetSettings();
     if (!settings) {
       this._syncHostExtraTitle(undefined);
+      this._targetRoot = undefined;
       this._targetGrid = undefined;
       this._resolvedTargetUid = undefined;
       this._invalidTargetUid = undefined;
@@ -195,6 +317,8 @@ export class ReferenceFormGridModel extends FlowModel {
     }
 
     const engine = this._ensureScopedEngine();
+    const host = this.parent as FlowModel | undefined;
+    ensureScopedEngineView(engine, (host?.context as any) || (this.context as any));
     const targetUid = settings.targetUid;
     const prevTargetGrid = this._targetGrid;
     const prevResolvedTargetUid = this._resolvedTargetUid;
@@ -205,12 +329,12 @@ export class ReferenceFormGridModel extends FlowModel {
     // 在“模板引用”切换的中间态（例如模型树刚替换、上下文尚未稳定）下，
     // 可能出现首次解析不到目标（短暂返回 null/undefined）。这里做一次轻量重试，
     // 避免界面闪现 “Target block is invalid” 占位。
-    const tryResolveTargetGrid = async (): Promise<FlowModel | undefined> => {
+    const tryResolveTargetGrid = async (): Promise<{ root: FlowModel; grid: FlowModel } | undefined> => {
       const root = await engine.loadModel<FlowModel>({ uid: targetUid });
       if (!root) return undefined;
 
-      const host = this.parent as FlowModel | undefined;
-      const hostInfo: ReferenceHostInfo = {
+      root.setParent(host);
+      const hostInfo = {
         hostUid: host?.uid,
         hostUse: host?.use,
         ref: {
@@ -224,23 +348,43 @@ export class ReferenceFormGridModel extends FlowModel {
       };
       root.context.defineProperty(REF_HOST_CTX_KEY, { value: hostInfo });
 
-      const fragment = _.get(root as any, targetPath);
-      const gridModel =
-        fragment instanceof FlowModel ? fragment : _.castArray(fragment).find((m) => m instanceof FlowModel);
-      return gridModel || undefined;
+      const fragment = root.subModels?.grid;
+      let gridModel: FlowModel | undefined;
+      if (fragment instanceof FlowModel) {
+        gridModel = fragment;
+      }
+      // 将宿主区块上下文注入到被引用的 grid：
+      // - Details 区块字段渲染依赖 ctx.record/resource/blockModel 等（定义在宿主 block context 上）；
+      // - 但同时要保留 scoped engine（ctx.engine）指向，避免丢失实例/缓存隔离。
+      // 注意：使用 Symbol 标记避免重复添加 delegate（beforeRender 可能多次触发）
+      const contextWithMarker = gridModel?.context as (FlowContext & { [BRIDGE_MARKER]?: boolean }) | undefined;
+      if (gridModel && host?.context && !contextWithMarker?.[BRIDGE_MARKER]) {
+        const bridge = new FlowContext();
+        bridge.defineProperty('engine', { value: engine });
+        bridge.addDelegate(host.context);
+        gridModel.context.addDelegate(bridge);
+        (gridModel.context as FlowContext & { [BRIDGE_MARKER]?: boolean })[BRIDGE_MARKER] = true;
+      }
+      if (!gridModel) return undefined;
+      // 同步模板字段需要的关联 appends 到宿主 block 的 resource（避免 users.roles 等关系字段为空）
+      if (host) {
+        this._syncHostResourceAppends(host, gridModel);
+      }
+      return { root, grid: gridModel };
     };
 
-    let gridModel = await tryResolveTargetGrid();
-    if (!gridModel) {
+    let resolved = await tryResolveTargetGrid();
+    if (!resolved) {
       await new Promise((resolve) => setTimeout(resolve, 50));
       const latest = this._getTargetSettings();
       if (latest?.targetUid !== targetUid) {
         return;
       }
-      gridModel = await tryResolveTargetGrid();
+      resolved = await tryResolveTargetGrid();
     }
 
-    if (!gridModel) {
+    if (!resolved) {
+      this._targetRoot = undefined;
       this._targetGrid = undefined;
       this._resolvedTargetUid = undefined;
       this._invalidTargetUid = targetUid;
@@ -250,10 +394,12 @@ export class ReferenceFormGridModel extends FlowModel {
       return;
     }
 
-    this._targetGrid = gridModel;
+    this._targetRoot = resolved.root;
+    this._targetGrid = resolved.grid;
     this._resolvedTargetUid = targetUid;
     this._invalidTargetUid = undefined;
-    if (prevTargetGrid !== gridModel || prevResolvedTargetUid !== targetUid || prevInvalidTargetUid) {
+
+    if (prevTargetGrid !== resolved.grid || prevResolvedTargetUid !== targetUid || prevInvalidTargetUid) {
       this.rerender();
     }
   }