@nocobase/flow-engine 2.1.0-beta.42 → 2.1.0-beta.44

package/src/flowContext.ts

@@ -400,6 +400,10 @@ export type FlowContextGetApiInfosOptions = {
    * RunJS 文档版本（默认 v1）。
    */
   version?: RunJSVersion;
+  /**
+   * Include editor completion metadata. Defaults to false so API-doc callers keep the compact public shape.
+   */
+  includeCompletion?: boolean;
 };
 
 export type FlowContextGetVarInfosOptions = {
@@ -704,10 +708,11 @@ export class FlowContext {
    * - 输出仅来自 RunJS doc 与 defineProperty/defineMethod 的 info
    * - 不读取/展开 PropertyMeta（变量结构）
    * - 不自动展开深层 properties
-   * - 不返回自动补全字段（例如 completion）
+   * - 默认不返回自动补全字段（例如 completion），传入 includeCompletion=true 时返回
    */
   async getApiInfos(options: FlowContextGetApiInfosOptions = {}): Promise<Record<string, FlowContextApiInfo>> {
     const version = (options.version as RunJSVersion) || ('v1' as RunJSVersion);
+    const includeCompletion = !!options.includeCompletion;
     const evalCtx = this.createProxy();
 
     const isPrivateKey = (key: string) => typeof key === 'string' && key.startsWith('_');
@@ -759,7 +764,14 @@ export class FlowContext {
       const src = toDocObject(obj);
       if (!src) return {};
       const out: any = {};
-      for (const k of ['description', 'examples', 'ref', 'params', 'returns']) {
+      for (const k of [
+        'description',
+        'examples',
+        ...(includeCompletion ? ['completion'] : []),
+        'ref',
+        'params',
+        'returns',
+      ]) {
         const v = (src as any)[k];
         if (typeof v !== 'undefined') out[k] = v;
       }
@@ -773,7 +785,17 @@ export class FlowContext {
       const src = toDocObject(obj);
       if (!src) return {};
       const out: any = {};
-      for (const k of ['title', 'type', 'interface', 'description', 'examples', 'ref', 'params', 'returns']) {
+      for (const k of [
+        'title',
+        'type',
+        'interface',
+        'description',
+        'examples',
+        ...(includeCompletion ? ['completion'] : []),
+        'ref',
+        'params',
+        'returns',
+      ]) {
         const v = (src as any)[k];
         if (typeof v !== 'undefined') out[k] = v;
       }
@@ -872,7 +894,7 @@ export class FlowContext {
       node = { ...node, ...pickPropertyInfo(docObj) };
       node = { ...node, ...pickPropertyInfo(infoObj) };
       delete (node as any).properties;
-      delete (node as any).completion;
+      if (!includeCompletion) delete (node as any).completion;
       if (!Object.keys(node).length) continue;
       const outKey = mapDocKeyToApiKey(key, docNode);
       // Avoid exposing ctx.React/ctx.ReactDOM/ctx.antd in api docs when mapping to ctx.libs.*.
@@ -890,7 +912,7 @@ export class FlowContext {
       node = { ...node, ...pickMethodInfo(docObj) };
       node = { ...node, ...pickMethodInfo(info) };
       delete (node as any).properties;
-      delete (node as any).completion;
+      if (!includeCompletion) delete (node as any).completion;
       if (!Object.keys(node).length) continue;
       node.type = 'function';
 
@@ -913,7 +935,7 @@ export class FlowContext {
         let node: FlowContextApiInfo = {};
         node = { ...node, ...pickPropertyInfo(childObj) };
         delete (node as any).properties;
-        delete (node as any).completion;
+        if (!includeCompletion) delete (node as any).completion;
         if (!node.description || !String(node.description).trim()) continue;
         out[outKey] = node;
       }
@@ -3075,6 +3097,17 @@ class BaseFlowEngineContext extends FlowContext {
         const jsCode = await prepareRunJsCode(String(code ?? ''), { preprocessTemplates: shouldPreprocessTemplates });
         return runner.run(jsCode);
       },
+      {
+        description: 'Execute a RunJS code string in the current Flow context.',
+        detail: '(code: string, variables?: Record<string, any>, options?: JSRunnerOptions) => Promise<RunJSResult>',
+        params: [
+          { name: 'code', type: 'string', description: 'RunJS code to execute.' },
+          { name: 'variables', type: 'Record<string, any>', optional: true, description: 'Additional globals.' },
+          { name: 'options', type: 'JSRunnerOptions', optional: true, description: 'Runner options.' },
+        ],
+        returns: { type: 'Promise<{ success: boolean; value?: any; error?: any; timeout?: boolean }>' },
+        completion: { insertText: `await ctx.runjs('return 1')` },
+      },
     );
   }
 }
@@ -3927,6 +3960,7 @@ export type FlowSettingsContext<TModel extends FlowModel = FlowModel> = FlowRunt
 
 export type RunJSDocCompletionDoc = {
   insertText?: string;
+  requires?: Array<'element'>;
 };
 
 export type RunJSDocHiddenDoc = boolean | ((ctx: any) => boolean | Promise<boolean>);

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,
@@ -135,6 +136,8 @@ export class FlowEngine {
    */
   private _savingModels = new Map<string, Promise<any>>();
 
+  private _loadedPageCache = createLoadedPageCache();
+
   /**
    * Flow engine context object.
    * @private
@@ -1339,7 +1342,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;
@@ -1350,15 +1354,24 @@ export class FlowEngine {
       }
     }
     const data = await this._modelRepository.findOne(options);
-    if (!data?.uid) return null;
-    await this.resolveModelTree(data);
-    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.createModelAsync<T>(data as any);
+    const model = await this.createModelAsync<T>(data as any);
+    if (bypassLoadedPageCache) {
+      this._loadedPageCache.mountModelToParent(model, true);
+      this._loadedPageCache.clear(options);
+    }
+    return model;
   }
 
   /**
@@ -1398,22 +1411,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 = await this.hydrateModelFromPreviousEngines<T>(options, extra);
-    if (hydrated) {
-      return hydrated;
+      const hydrated = await 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 = await this.createModelAsync<T>(data as any, extra);
     } else {
       model = await this.createModelAsync<T>(options, extra);
@@ -1421,18 +1443,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;
   }
@@ -1452,6 +1465,9 @@ export class FlowEngine {
     if (!this.ensureModelRepository()) return;
 
     const modelUid = model.uid;
+    const dirtyLoadedPageKey = this._loadedPageCache.getDirtyKeyForModel(model, {
+      force: !!options?.onlyStepParams,
+    });
 
     // 如果这个 model 正在保存中，返回现有的保存 Promise
     if (this._savingModels.has(modelUid)) {
@@ -1465,6 +1481,7 @@ export class FlowEngine {
 
     try {
       const result = await savePromise;
+      this._loadedPageCache.markDirty(dirtyLoadedPageKey);
       return result;
     } finally {
       // 无论成功还是失败，都要清除保存状态
@@ -1501,11 +1518,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);
@@ -1609,17 +1631,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.');
@@ -1649,6 +1679,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);
@@ -1663,10 +1695,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);
+      });
     });
   });
 
@@ -550,34 +563,6 @@ describe('FlowModel', () => {
 
         loggerSpy.mockRestore();
       });
-
-      test('should warn and skip step when use and handler are both missing', async () => {
-        const warnSpy = vi.spyOn(model.context.logger, 'warn').mockImplementation(() => {});
-        const errorSpy = vi.spyOn(model.context.logger, 'error').mockImplementation(() => {});
-
-        TestFlowModel.registerFlow({
-          key: 'settingsOnlyFlow',
-          steps: {
-            edit: {
-              title: 'Edit',
-              uiSchema: {},
-            },
-          },
-        });
-
-        const result = await model.applyFlow('settingsOnlyFlow');
-
-        expect(result).toEqual({});
-        expect(warnSpy).toHaveBeenCalledWith(
-          expect.stringContaining("Step 'edit' in flow 'settingsOnlyFlow' has neither 'use' nor 'handler'"),
-        );
-        expect(errorSpy).not.toHaveBeenCalledWith(
-          expect.stringContaining("Step 'edit' in flow 'settingsOnlyFlow' has neither 'use' nor 'handler'"),
-        );
-
-        warnSpy.mockRestore();
-        errorSpy.mockRestore();
-      });
     });
 
     describe('beforeRender flows', () => {

package/src/models/flowModel.tsx

@@ -56,6 +56,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>();
 
@@ -242,7 +261,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 = '';
@@ -511,11 +530,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);
       }
@@ -778,26 +795,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');
   }
@@ -1206,7 +1240,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);
@@ -1264,14 +1301,12 @@ export class FlowModel<Structure extends DefaultStructure = DefaultStructure> {
 
     const results: ArrayElementType<NonNullable<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;
   }
@@ -1288,12 +1323,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',