@nocobase/flow-engine 2.0.0-alpha.4 → 2.0.0-alpha.41

package/src/models/forkFlowModel.ts

@@ -12,6 +12,7 @@ import { FlowForkModelContext, FlowModelContext } from '../flowContext';
 import type { IModelComponentProps } from '../types';
 import { FlowModel } from './flowModel';
 import { FlowEngine } from '../flowEngine';
+import { uid } from 'uid/secure';
 
 /**
  * ForkFlowModel 作为 FlowModel 的独立实例：
@@ -38,7 +39,7 @@ export class ForkFlowModel<TMaster extends FlowModel = FlowModel> {
   private disposed = false;
 
   /** fork 在 master.forks 中的索引 */
-  public readonly forkId: number;
+  public readonly forkId: string;
 
   /** 需要与 master 共享的属性列表 */
   private static readonly SHARED_PROPERTIES = ['stepParams', 'sortIndex'];
@@ -67,12 +68,12 @@ export class ForkFlowModel<TMaster extends FlowModel = FlowModel> {
   // 不需要定义自己的属性了，现在是SHARED_PROPERTIES中指定的少数几个属性，所有属性设置时会自动添加自己的fork内的独有属性
   #flowContext: FlowModelContext;
 
-  constructor(master: TMaster, initialProps: IModelComponentProps = {}, forkId = 0) {
+  constructor(master: TMaster, initialProps: IModelComponentProps = {}, forkId?: string) {
     void this.localProperties; // 避免 IDE 提示 unused
     this.master = master;
     this.uid = master.uid;
     this.localProps = { ...initialProps };
-    this.forkId = forkId;
+    this.forkId = forkId || uid();
     this.hidden = this.master.hidden;
 
     define(this, {
@@ -206,6 +207,13 @@ export class ForkFlowModel<TMaster extends FlowModel = FlowModel> {
     }
   }
 
+  /**
+   * 清理局部 props，仅影响当前 fork
+   */
+  clearProps() {
+    return (this.localProps = {});
+  }
+
   /**
    * render 依旧使用 master 的方法，但合并后的 props 需要透传
    */
@@ -224,10 +232,10 @@ export class ForkFlowModel<TMaster extends FlowModel = FlowModel> {
   }
 
   /**
-   * 自动流程缓存的作用域标识（fork 专用）。
+   * 事件缓存的作用域标识（fork 专用）。
    */
-  public getAutoFlowCacheScope(): string {
-    return String(this.forkId);
+  public getFlowCacheScope(eventName: string): string {
+    return `${String(eventName)}:${String(this.forkId)}`;
   }
 
   // onUnmount() {
@@ -250,9 +258,41 @@ export class ForkFlowModel<TMaster extends FlowModel = FlowModel> {
   dispose() {
     if (this.disposed) return;
     this.disposed = true;
+    // 统一按事件缓存命名规则清理当前 fork 的所有缓存项（覆盖所有事件）
+    try {
+      const cache = this.flowEngine?.applyFlowCache;
+      if (cache && cache.size > 0) {
+        const uidSuffixes = [`:${this.uid}`, `-${this.uid}`];
+        const forkIdColon = `:${this.forkId}:`;
+        const forkIdHyphen = `-${this.forkId}-`;
+
+        for (const key of cache.keys()) {
+          // 事件缓存统一以 event: 或 event- 开头
+          const isEventCache = key.startsWith('event:') || key.startsWith('event-');
+          if (!isEventCache) continue;
+
+          // 仅删除当前 fork + 当前 uid 的键
+          const endMatches = uidSuffixes.some((s) => key.endsWith(s));
+          if (!endMatches) continue;
+
+          // 限定在去除 uid 后缀的范围内匹配 forkId 片段，避免误伤
+          let trimmed = key;
+          for (const suf of uidSuffixes) {
+            if (trimmed.endsWith(suf)) {
+              trimmed = trimmed.slice(0, -suf.length);
+              break;
+            }
+          }
+          if (trimmed.includes(forkIdColon) || trimmed.includes(forkIdHyphen)) {
+            cache.delete(key);
+          }
+        }
+      }
+    } catch {
+      // 忽略清理阶段异常，避免影响后续释放
+    }
+
     if (this.master && (this.master as any).forks) {
-      const forkCacheKey = FlowEngine.generateApplyFlowCacheKey(`${this.forkId}`, 'all', this.uid);
-      this.flowEngine.applyFlowCache.delete(forkCacheKey);
       (this.master as any).forks.delete(this as any);
     }
     // 从 master 的 forkCache 中移除自己

package/src/provider.tsx

@@ -14,6 +14,7 @@ import { FlowContextProvider } from './FlowContextProvider';
 import { FlowEngine } from './flowEngine';
 import { useDialog, useDrawer, usePage, usePopover } from './views';
 import { FlowViewer } from './views/FlowView';
+import { observer } from '@formily/reactive-react';
 
 interface FlowEngineProviderProps {
   engine: FlowEngine;
@@ -22,7 +23,7 @@ interface FlowEngineProviderProps {
 
 const FlowEngineReactContext = createContext<FlowEngine | null>(null);
 
-export const FlowEngineProvider: React.FC<FlowEngineProviderProps> = (props) => {
+export const FlowEngineProvider: React.FC<FlowEngineProviderProps> = React.memo((props) => {
   const { engine, children } = props;
   if (!engine) {
     throw new Error('FlowEngineProvider must be supplied with an engine.');
@@ -32,7 +33,9 @@ export const FlowEngineProvider: React.FC<FlowEngineProviderProps> = (props) =>
       <FlowContextProvider context={engine.context}>{children}</FlowContextProvider>
     </FlowEngineReactContext.Provider>
   );
-};
+});
+
+FlowEngineProvider.displayName = 'FlowEngineProvider';
 
 export const FlowEngineGlobalsContextProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
   const { modal, message, notification } = App.useApp();
@@ -72,20 +75,20 @@ export const FlowEngineGlobalsContextProvider: React.FC<{ children: React.ReactN
   }, [engine, drawer, modal, message, notification, config, popover, token, dialog, embed]);
 
   return (
-    <>
+    <ConfigProvider {...config} locale={engine.context.locales?.antd} popupMatchSelectWidth={false}>
       {children}
       {contextHolder as any}
       {popoverContextHolder as any}
       {pageContextHolder as any}
       {dialogContextHolder as any}
       {/* The modal context is provided by App.useApp() */}
-    </>
+    </ConfigProvider>
   );
 };
-
-export const useFlowEngine = (): FlowEngine => {
+// 不 throw Error 怎么处理？
+export const useFlowEngine = ({ throwError = true } = {}): FlowEngine => {
   const context = useContext(FlowEngineReactContext);
-  if (!context) {
+  if (!context && throwError) {
     // This error should ideally not be hit if FlowEngineProvider is used correctly at the root
     // and always supplied with an engine.
     throw new Error(

package/src/resources/multiRecordResource.ts

@@ -113,6 +113,7 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
   async create(data: TDataItem, options?: AxiosRequestConfig): Promise<void> {
     const config = this.mergeRequestConfig({ data }, this.createActionOptions, options);
     await this.runAction('create', config);
+    this.emit('saved', data);
     await this.refresh();
   }
 
@@ -129,17 +130,38 @@ 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;
+    const tkData = collection?.getFilterByTK(this.context.record);
+    let result = data;
+
+    // 安全处理 filterTargetKey & tkData
+    if (collection && filterTargetKey) {
+      if (Array.isArray(filterTargetKey)) {
+        result = {
+          ...data,
+          ...(tkData || {}),
+        };
+      } else {
+        result = {
+          ...data,
+          [filterTargetKey]: tkData,
+        };
+      }
+    }
+
     const config = this.mergeRequestConfig(
       {
         params: {
           filterByTk,
         },
-        data,
+        data: result,
       },
       this.updateActionOptions,
       options,
     );
     await this.runAction('update', config);
+    this.emit('saved', data);
     await this.refresh();
   }
 
@@ -166,6 +188,11 @@ export class MultiRecordResource<TDataItem = any> extends BaseRecordResource<TDa
       options,
     );
     await this.runAction('destroy', config);
+    const currentPage = this.getPage();
+    const lastPage = Math.ceil((this.getCount() - _.castArray(filterByTk).length) / this.getPageSize());
+    if (currentPage > lastPage) {
+      this.setPage(lastPage);
+    }
     await this.refresh();
   }
 

package/src/resources/singleRecordResource.ts

@@ -33,16 +33,34 @@ 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 (collection && filterTargetKey) {
+        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) {
       await this.refresh();
     }

package/src/resources/sqlResource.ts

@@ -11,6 +11,7 @@ import { observable } from '@formily/reactive';
 import _ from 'lodash';
 import { FlowContext, FlowEngineContext } from '../flowContext';
 import { BaseRecordResource } from './baseRecordResource';
+import { parseLiquidContext, transformSQL } from '@nocobase/utils/client';
 
 type SQLRunOptions = {
   bind?: Record<string, any>;
@@ -25,20 +26,6 @@ type SQLSaveOptions = {
   dataSourceKey?: string;
 };
 
-function transformSQL(template: string) {
-  let index = 1;
-  const bind = {};
-
-  const sql = template.replace(/{{\s*([^}]+)\s*}}/g, (_, expr) => {
-    const key = `__var${index}`;
-    bind[key] = `{{${expr.trim()}}}`;
-    index++;
-    return `$${key}`;
-  });
-
-  return { sql, bind };
-}
-
 export class FlowSQLRepository {
   protected ctx: FlowEngineContext;
 
@@ -56,16 +43,17 @@ export class FlowSQLRepository {
   }
 
   async run(sql: string, options: SQLRunOptions = {}) {
-    const result = transformSQL(sql);
-    const bind = await this.ctx.resolveJsonTemplate(result.bind);
+    const { sql: transformedSQL, bind, liquidContext } = await transformSQL(sql);
+    const resolved = await this.ctx.resolveJsonTemplate({ bind, liquidContext });
+    const parsedSQL = await parseLiquidContext(transformedSQL, resolved.liquidContext);
     const { data } = await this.ctx.api.request({
       method: 'POST',
       url: 'flowSql:run',
       data: {
-        sql: result.sql,
+        sql: parsedSQL,
         ...options,
         bind: {
-          ...bind,
+          ...resolved.bind,
           ...options.bind,
         },
       },
@@ -91,7 +79,7 @@ export class FlowSQLRepository {
         uid,
       },
     });
-    const bind = await this.ctx.resolveJsonTemplate(response.data.data || {});
+    const { bind, liquidContext } = await this.ctx.resolveJsonTemplate(response.data.data || {});
     const { data } = await this.ctx.api.request({
       method: 'POST',
       url: 'flowSql:runById',
@@ -100,8 +88,9 @@ export class FlowSQLRepository {
         ...options,
         bind: {
           ...bind,
-          ...options.bind,
+          ...options?.bind,
         },
+        liquidContext,
       },
     });
     return data?.data;
@@ -233,20 +222,25 @@ export class SQLResource<TData = any> extends BaseRecordResource<TData> {
     return this;
   }
 
+  setLiquidContext(liquidContext: Record<string, any>) {
+    this.request.data.liquidContext = liquidContext;
+    return this;
+  }
+
   async run() {
     return this._debugEnabled ? await this.runBySQL() : await this.runById();
   }
 
   async runBySQL() {
     const sql = this._sql;
-    const result = transformSQL(sql);
-    const bind = await this.context.resolveJsonTemplate(result.bind);
+    const { sql: transformedSQL, bind, liquidContext } = await transformSQL(sql);
+    const resolved = await this.context.resolveJsonTemplate({ bind, liquidContext });
     const options = _.cloneDeep({
       method: 'post',
       ...this.getRefreshRequestOptions(),
     });
-    options.data.bind = bind;
-    options.data.sql = result.sql;
+    options.data.sql = await parseLiquidContext(transformedSQL, resolved.liquidContext);
+    options.data.bind = resolved.bind;
     return await this.runAction<TData, any>('run', options);
   }
 
@@ -257,8 +251,9 @@ export class SQLResource<TData = any> extends BaseRecordResource<TData> {
         uid: this.request.data.uid,
       },
     });
-    const bind = await this.context.resolveJsonTemplate(data);
+    const { bind, liquidContext } = await this.context.resolveJsonTemplate(data);
     this.setBind(bind);
+    this.setLiquidContext(liquidContext);
     return await this.runAction<TData, any>('runById', {
       method: 'post',
       ...this.getRefreshRequestOptions(),

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

@@ -7,33 +7,40 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { FlowRunJSContext } from './FlowRunJSContext';
-import { createSafeDocument, createSafeWindow } from '../../utils';
+import { FlowRunJSContext } from '../../flowContext';
 
-export class FormJSFieldItemRunJSContext extends FlowRunJSContext {
-  static injectDefaultGlobals() {
-    return { window: createSafeWindow(), document: createSafeDocument() };
-  }
-  constructor(delegate: any) {
-    super(delegate);
-    this.defineProperty('element', { get: () => (this as any)._delegate['element'] });
-    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
-    this.defineProperty('value', { get: () => (this as any)._delegate['value'] });
-  }
-}
+export class FormJSFieldItemRunJSContext extends FlowRunJSContext {}
 
 FormJSFieldItemRunJSContext.define({
   label: 'FormJSFieldItem RunJS context',
   properties: {
-    element: 'ElementProxy，表单字段容器',
-    value: '字段值（读/受控场景需通过 setProps 修改）',
-    record: '当前记录（只读）',
+    element: `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.`,
   },
   methods: {
-    onRefReady: '容器就绪回调',
-    setProps: '设置表单项属性：`setProps(fieldModel, { value })`（由联动/表单上下文提供）',
-  },
-  snipastes: {
-    显示字段值: { $ref: 'scene/jsfield/innerHTML-value', prefix: 'sn-form-value' },
+    onRefReady: `Wait for form field container DOM element to be ready before executing callback.
+      Parameters: (ref: React.RefObject, callback: (element: HTMLElement) => void, timeout?: number) => void`,
+    setProps: `Set form field properties programmatically.
+      Parameters: (fieldModel: any, props: { value?: any, disabled?: boolean, visible?: boolean }) => void
+      Example: ctx.setProps(fieldModel, { value: "new value" })`,
   },
 });
+
+FormJSFieldItemRunJSContext.define(
+  {
+    label: '表单 JS 字段项 RunJS 上下文',
+    properties: {
+      element: 'ElementProxy，表单字段容器',
+      value: '字段值（展示模式为只读；受控场景用 setProps 修改）',
+      record: '当前记录（只读）',
+    },
+    methods: {
+      onRefReady: '容器就绪回调',
+      setProps: '设置表单项属性：`setProps(fieldModel, { value })`（由联动/表单上下文提供）',
+    },
+  },
+  { locale: 'zh-CN' },
+);

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

@@ -7,46 +7,58 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { FlowRunJSContext } from './FlowRunJSContext';
-import { createSafeDocument, createSafeWindow } from '../../utils';
+import { FlowRunJSContext } from '../../flowContext';
 
-export class JSBlockRunJSContext extends FlowRunJSContext {
-  static injectDefaultGlobals() {
-    return { window: createSafeWindow(), document: createSafeDocument() };
-  }
-  constructor(delegate: any) {
-    super(delegate);
-    // 显式暴露本场景所需属性
-    this.defineProperty('element', { get: () => (this as any)._delegate['element'] });
-    this.defineProperty('record', { get: () => (this as any)._delegate['record'] });
-    this.defineProperty('value', { get: () => (this as any)._delegate['value'] });
-  }
-}
+export class JSBlockRunJSContext extends FlowRunJSContext {}
 
 JSBlockRunJSContext.define({
-  label: 'JSBlock RunJS context',
+  label: 'RunJS context',
   properties: {
-    element: 'ElementProxy，安全 DOM 容器。支持 innerHTML/append 等',
-    record: '当前记录（只读，存在于数据块/详情等场景）',
-    value: '当前值（若存在）',
-    React: 'React（已注入）',
-    antd: 'AntD（已注入）',
+    element: {
+      description: `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.',
+      },
+    },
+    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.',
+    React: 'React library',
+    antd: 'Ant Design library',
   },
   methods: {
-    onRefReady: 'Container ref ready callback:\n```js\nctx.onRefReady(ctx.ref, el => { /* ... */ })\n```',
+    onRefReady: `Wait for container DOM element to be ready before executing callback.
+      Parameters: (ref: React.RefObject, callback: (element: HTMLElement) => void, timeout?: number) => void
+      Example: ctx.onRefReady(ctx.ref, (el) => { el.innerHTML = "Ready!" })`,
     requireAsync: 'Load external library: `const lib = await ctx.requireAsync(url)`',
-  },
-  snipastes: {
-    'Render HTML': { $ref: 'scene/jsblock/render-basic', prefix: 'sn-jsb-html' },
-    'Render React': { $ref: 'scene/jsblock/render-react', prefix: 'sn-jsb-react' },
-    'Init ECharts': { $ref: 'libs/echarts-init', prefix: 'sn-echarts' },
-    'Render card': { $ref: 'scene/jsblock/render-card', prefix: 'sn-jsb-card' },
-    'Button handler': { $ref: 'scene/jsblock/render-button-handler', prefix: 'sn-jsb-button' },
-    'JSX mount': { $ref: 'scene/jsblock/jsx-mount', prefix: 'sn-jsx-mount' },
-    'JSX unmount': { $ref: 'scene/jsblock/jsx-unmount', prefix: 'sn-jsx-unmount' },
-    Notification: { $ref: 'global/notification-open', prefix: 'sn-notify' },
-    'Window open': { $ref: 'global/window-open', prefix: 'sn-window-open' },
-    'Add click listener': { $ref: 'scene/jsblock/add-event-listener', prefix: 'sn-jsb-click' },
-    'Append style': { $ref: 'scene/jsblock/append-style', prefix: 'sn-jsb-style' },
+    importAsync: 'Dynamically import ESM module: `const mod = await ctx.importAsync(url)`',
   },
 });
+
+JSBlockRunJSContext.define(
+  {
+    label: 'RunJS 上下文',
+    properties: {
+      element: {
+        description: 'ElementProxy，安全的 DOM 容器，支持 innerHTML/append 等',
+        detail: 'ElementProxy',
+        properties: {
+          innerHTML: '读取或设置容器的 HTML 内容',
+        },
+      },
+      record: '当前记录（只读，用于数据区块/详情等场景）',
+      value: '当前值（若存在）',
+      React: 'React 库',
+      antd: 'Ant Design 库',
+    },
+    methods: {
+      onRefReady: '容器 ref 就绪回调：\n```js\nctx.onRefReady(ctx.ref, el => { /* ... */ })\n```',
+      requireAsync: '加载外部库：`const lib = await ctx.requireAsync(url)`',
+      importAsync: '按 URL 动态导入 ESM 模块：`const mod = await ctx.importAsync(url)`',
+    },
+  },
+  { locale: 'zh-CN' },
+);

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

@@ -7,26 +7,25 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { FlowRunJSContext } from './FlowRunJSContext';
+import { FlowRunJSContext } from '../../flowContext';
 
-export class JSCollectionActionRunJSContext extends FlowRunJSContext {
-  constructor(delegate: any) {
-    super(delegate);
-    this.defineProperty('resource', { get: () => (this as any)._delegate['resource'] });
-  }
-}
+export class JSCollectionActionRunJSContext extends FlowRunJSContext {}
 
 JSCollectionActionRunJSContext.define({
   label: 'JSCollectionAction RunJS context',
   properties: {
-    resource: '列表资源（选中行/分页等）',
-  },
-  methods: {
-    runAction: 'Run action',
-    message: 'Message API',
-  },
-  snipastes: {
-    'Selected count': { $ref: 'scene/actions/collection-selected-count', prefix: 'sn-act-selected-count' },
-    'Iterate selected rows': { $ref: 'scene/actions/iterate-selected-rows', prefix: 'sn-act-iterate' },
+    resource: `Collection resource instance providing access to selected rows, pagination, and data operations.
+      Use ctx.resource.selectedRows to get selected records.
+      Use ctx.resource.pagination for page info.`,
   },
 });
+
+JSCollectionActionRunJSContext.define(
+  {
+    label: 'JS 集合动作 RunJS 上下文',
+    properties: {
+      resource: '列表资源（包含选中行/分页信息等）',
+    },
+  },
+  { locale: 'zh-CN' },
+);

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

@@ -0,0 +1,58 @@
+/**
+ * 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 { FlowRunJSContext } from '../../flowContext';
+
+/**
+ * RunJS context for JSColumnModel (table custom column).
+ * Focused on per-row rendering with access to current record and cell element.
+ */
+export class JSColumnRunJSContext extends FlowRunJSContext {}
+
+JSColumnRunJSContext.define({
+  label: 'JSColumn RunJS context',
+  properties: {
+    element:
+      '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).',
+    viewer:
+      'View controller providing dialog/drawer/embed helpers for interactions initiated from the cell (e.g., open details).',
+    React: 'React library',
+    antd: 'Ant Design library',
+  },
+  methods: {
+    onRefReady:
+      'Wait for cell DOM element to be ready before executing callback. Parameters: (ref, callback, timeout?) => void',
+    requireAsync: 'Load external library by URL: `const lib = await ctx.requireAsync(url)`',
+    importAsync: 'Dynamically import ESM module by URL: `const mod = await ctx.importAsync(url)`',
+  },
+});
+
+JSColumnRunJSContext.define(
+  {
+    label: 'JS 列 RunJS 上下文',
+    properties: {
+      element: 'ElementProxy，表格单元格的安全 DOM 容器，支持 innerHTML/append 等',
+      record: '当前行记录对象（只读）',
+      recordIndex: '当前行索引（从 0 开始）',
+      collection: '集合定义元数据（只读）',
+      viewer: '视图控制器，可用于在单元格中触发抽屉/对话框/内嵌等交互',
+      React: 'React 库',
+      antd: 'Ant Design 库',
+    },
+    methods: {
+      onRefReady: '等待单元格 DOM 就绪后执行回调。参数：(ref, callback, timeout?)',
+      requireAsync: '按 URL 异步加载外部库：`const lib = await ctx.requireAsync(url)`',
+      importAsync: '按 URL 动态导入 ESM 模块：`const mod = await ctx.importAsync(url)`',
+    },
+  },
+  { locale: 'zh-CN' },
+);