@nocobase/flow-engine 2.1.0-beta.9 → 2.2.0-alpha.1

package/src/reactive/observer.tsx

@@ -10,7 +10,7 @@
 import { observer as originalObserver, IObserverOptions, ReactFC } from '@formily/reactive-react';
 import React, { useMemo, useEffect, useRef } from 'react';
 import { useFlowContext } from '../FlowContextProvider';
-import { autorun } from '@formily/reactive';
+import { reaction } from '@formily/reactive';
 import { FlowEngineContext } from '..';
 
 type ObserverComponentProps<P, Options extends IObserverOptions> = Options extends {
@@ -30,12 +30,67 @@ export const observer = <P, Options extends IObserverOptions = IObserverOptions>
     const ctxRef = useRef(ctx);
     ctxRef.current = ctx;
 
-    // Store the pending disposer to avoid creating multiple listeners
+    // 保存延迟更新的监听器，避免重复创建监听。
     const pendingDisposerRef = useRef<(() => void) | null>(null);
+    // 保存延迟创建监听器的定时器，避免组件卸载后仍继续调度。
+    const pendingTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-    // Cleanup on unmount
+    /**
+     * 清理挂起的可见性监听器。
+     *
+     * @example
+     * ```typescript
+     * clearPendingDisposer();
+     * ```
+     */
+    const clearPendingDisposer = () => {
+      if (pendingDisposerRef.current) {
+        pendingDisposerRef.current();
+        pendingDisposerRef.current = null;
+      }
+    };
+
+    /**
+     * 清理挂起的定时器。
+     *
+     * @example
+     * ```typescript
+     * clearPendingTimer();
+     * ```
+     */
+    const clearPendingTimer = () => {
+      if (pendingTimerRef.current) {
+        clearTimeout(pendingTimerRef.current);
+        pendingTimerRef.current = null;
+      }
+    };
+
+    /**
+     * 判断当前页面与标签页是否允许立即更新。
+     *
+     * @returns 当前上下文是否处于可更新状态。
+     * @example
+     * ```typescript
+     * if (isContextActive()) {
+     *   updater();
+     * }
+     * ```
+     */
+    const isContextActive = () => {
+      const pageActive = getPageActive(ctxRef.current);
+      const tabActive = ctxRef.current?.tabActive?.value;
+
+      return pageActive !== false && tabActive !== false;
+    };
+
+    // 组件卸载时统一清理所有挂起任务，避免异步回调在卸载后继续运行。
     useEffect(() => {
       return () => {
+        if (pendingTimerRef.current) {
+          clearTimeout(pendingTimerRef.current);
+          pendingTimerRef.current = null;
+        }
+
         if (pendingDisposerRef.current) {
           pendingDisposerRef.current();
           pendingDisposerRef.current = null;
@@ -47,38 +102,45 @@ export const observer = <P, Options extends IObserverOptions = IObserverOptions>
       () =>
         originalObserver(Component, {
           scheduler(updater) {
-            const pageActive = getPageActive(ctxRef.current);
-            const tabActive = ctxRef.current?.tabActive?.value;
+            if (!isContextActive()) {
+              if (pendingTimerRef.current || pendingDisposerRef.current) {
+                return;
+              }
+
+              // 通过异步任务打断同步调度，避免连续触发时形成递归更新。
+              pendingTimerRef.current = setTimeout(() => {
+                pendingTimerRef.current = null;
 
-            if (pageActive === false || tabActive === false) {
-              // Avoid stack overflow
-              setTimeout(() => {
-                // If there is already a pending updater, do nothing
                 if (pendingDisposerRef.current) {
                   return;
                 }
 
-                // Delay the update until the page and tab become active
-                const disposer = autorun(() => {
-                  if (
-                    ctxRef.current?.pageActive?.value &&
-                    (ctxRef.current?.tabActive?.value === true || ctxRef.current?.tabActive?.value === undefined)
-                  ) {
+                if (isContextActive()) {
+                  updater();
+                  return;
+                }
+
+                // 只监听组合后的“是否可更新”状态，条件恢复后执行一次并立即销毁。
+                pendingDisposerRef.current = reaction(
+                  () => isContextActive(),
+                  (active) => {
+                    if (!active) {
+                      return;
+                    }
+
+                    clearPendingDisposer();
                     updater();
-                    disposer?.();
-                    pendingDisposerRef.current = null;
-                  }
-                });
-                pendingDisposerRef.current = disposer;
+                  },
+                  {
+                    name: 'FlowObserverPendingUpdate',
+                  },
+                );
               });
               return;
             }
 
-            // If we are updating immediately, clear any pending disposer
-            if (pendingDisposerRef.current) {
-              pendingDisposerRef.current();
-              pendingDisposerRef.current = null;
-            }
+            clearPendingTimer();
+            clearPendingDisposer();
 
             updater();
           },

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

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

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

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

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

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

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

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

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

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

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

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