docs: update docs

Author: yvonneyx

site/docs/en/guide/start/_meta.json

@@ -1 +1 @@
-["getting-started", "installation", "data-mapping", "layout-configuration"]
+["getting-started", "installation", "webworker", "data-mapping", "layout-configuration"]

site/docs/en/guide/start/webworker.mdx

@@ -0,0 +1,62 @@
+import { Badge } from '@theme';
+
+# Using WebWorker <Badge text="Performance" type="info" />
+
+When `enableWorker: true` and `Worker` is available, layout computation runs in a WebWorker to reduce main-thread blocking.
+
+However, if you pass **function callbacks** in options (e.g. `(node) => ...`), Worker mode may throw errors like:
+
+```txt
+DataCloneError: Failed to execute 'postMessage' on 'Worker': function could not be cloned
+```
+
+## Why it happens
+
+The library transfers `data/options` between the main thread and the Worker via structured clone. **Functions are not structured-cloneable**, so any function inside options can break the transfer.
+
+## How to fix
+
+### Option 1: Use `Expr` (string expressions) instead of callbacks
+
+`@antv/layout` supports `Expr` (powered by `@antv/expr`) for many numeric/size fields. If a field’s type includes `Expr`, you can pass a string expression instead of a function.
+
+Example (ForceLayout):
+
+```ts
+import { ForceLayout } from '@antv/layout';
+
+const layout = new ForceLayout({
+  enableWorker: true,
+  nodeStrength: 'node.data.strength ?? -30',
+  edgeStrength: 'edge.data.weight ?? 0.1',
+  nodeSize: 'node.data.size ?? 10',
+});
+
+await layout.execute(data);
+```
+
+Expression variable names depend on the field:
+
+- Node fields usually use `node`
+- Edge fields usually use `edge`
+- Combo fields usually use `combo`
+
+### Option 2: Pre-compute values into your data
+
+If you used to do:
+
+```ts
+nodeSize: (node) => node.data.size
+```
+
+You can pre-fill `data.nodes[i].data.size` and then use `nodeSize: 'node.data.size'` (or rely on defaults).
+
+### Option 3: If you need callbacks, don’t enable Worker
+
+Some capabilities inherently require functions and cannot be passed into Workers:
+
+- `onTick`-style callbacks
+- `node` / `edge` mapping functions
+- Any custom logic without an `Expr` alternative
+
+In these cases, run the layout on the main thread by keeping `enableWorker` off.

site/docs/zh/guide/start/_meta.json

@@ -1 +1 @@
-["getting-started", "installation", "data-mapping", "layout-configuration"]
+["getting-started", "installation", "webworker", "data-mapping", "layout-configuration"]

site/docs/zh/guide/start/webworker.mdx

@@ -0,0 +1,62 @@
+import { Badge } from '@theme';
+
+# 使用 WebWorker <Badge text="Performance" type="info" />
+
+当你配置 `enableWorker: true` 且运行环境支持 `Worker` 时，布局计算会在 Worker 中执行，从而减少主线程阻塞。
+
+但如果你在配置项里传入了**回调函数**（例如 `(node) => ...`），在 Worker 模式下可能会直接报错，常见报错类似：
+
+```txt
+DataCloneError: Failed to execute 'postMessage' on 'Worker': function could not be cloned
+```
+
+## 为什么会报错
+
+库在主线程与 Worker 之间传递 `data/options` 时依赖结构化克隆（structured clone）。**函数无法被结构化克隆**，因此当 options 中包含函数时，就会触发 `postMessage`/Comlink 的传输错误。
+
+## 怎么解决
+
+### 方案 1：用 `Expr`（字符串表达式）替代回调
+
+`@antv/layout` 内置了基于 `@antv/expr` 的表达式能力：对于类型里标注为 `Expr` 的字段，你可以传入字符串表达式来代替函数。
+
+示例（ForceLayout）：
+
+```ts
+import { ForceLayout } from '@antv/layout';
+
+const layout = new ForceLayout({
+  enableWorker: true,
+  nodeStrength: 'node.data.strength ?? -30',
+  edgeStrength: 'edge.data.weight ?? 0.1',
+  nodeSize: 'node.data.size ?? 10',
+});
+
+await layout.execute(data);
+```
+
+表达式里的变量名取决于字段类型：
+
+- 节点相关字段通常使用 `node`（例如 `nodeStrength` / `nodeSize`）
+- 边相关字段通常使用 `edge`（例如 `edgeStrength` / `edgeLabelOffset`）
+- combo 相关字段通常使用 `combo`
+
+### 方案 2：把自定义计算结果“提前算好”放进数据里
+
+例如你原本想写：
+
+```ts
+nodeSize: (node) => node.data.size;
+```
+
+可以改为在业务数据里把 `size` 填好，直接传 `nodeSize: 'node.data.size'` 或者不传（让布局从 data 读取）。
+
+### 方案 3：需要回调就不要开 Worker
+
+以下类型的能力天然需要函数回调，Worker 模式下无法传入：
+
+- `onTick` 这类过程回调
+- `node` / `edge` 数据映射函数
+- 任何只有函数形态的自定义逻辑（未提供 `Expr` 字段的场景）
+
+此时建议把 `enableWorker` 关掉，或者只在主线程跑布局。

src/algorithm/antv-dagre/types.ts

@@ -1,4 +1,4 @@
-import { Expr, ID, NodeData, Point } from '../../types';
+import type { Expr, ID, NodeData, Point } from '../../types';
 import { BaseLayoutOptions } from '../base-layout';
 
 export type DagreRankdir =

src/algorithm/d3-force-3d/types.ts

@@ -1,4 +1,4 @@
-import { Expr } from '../../types';
+import type { Expr } from '../../types';
 import type {
   D3ForceCommonOptions,
   EdgeDatum as _EdgeDatum,

src/algorithm/dagre/types.ts

@@ -1,5 +1,5 @@
 import type { GraphLabel } from 'dagre';
-import type { EdgeData, Size } from '../../types';
+import type { EdgeData, Expr, Size } from '../../types';
 import type { EdgeLabelPos } from '../../types/edge-label';
 import type { BaseLayoutOptions } from '../types';
 
@@ -44,33 +44,33 @@ export interface DagreLayoutOptions extends BaseLayoutOptions, GraphLabel {
    * <en/> Sets minimum number of layers an edge spans; larger values create more distance between nodes, controlling layout compactness
    * @defaultValue 1
    */
-  edgeMinLen?: number | ((edge: EdgeData) => number);
+  edgeMinLen?: number | Expr | ((edge: EdgeData) => number);
 
   /**
    * <zh/> 边的权重，影响边的长度优化优先级，权重大的边倾向于更短
    *
    * <en/> Edge weight affecting length optimization priority; higher weight edges tend to be shorter
    */
-  edgeWeight?: number | ((edge: EdgeData) => number);
+  edgeWeight?: number | Expr | ((edge: EdgeData) => number);
 
   /**
    * <zh/> 边标签的尺寸，用于为标签预留空间，避免与节点重叠
    *
    * <en/> Size of edge labels for reserving space to prevent overlap with nodes
    */
-  edgeLabelSize?: Size | ((edge: EdgeData) => Size);
+  edgeLabelSize?: Size | Expr | ((edge: EdgeData) => Size);
 
   /**
    * <zh/> 标签在边上的位置，控制标签相对于边的对齐方式
    *
    * <en/> Label position on edge, controlling label alignment relative to the edge
    */
-  edgeLabelPos?: EdgeLabelPos | ((edge: EdgeData) => EdgeLabelPos);
+  edgeLabelPos?: EdgeLabelPos | Expr | ((edge: EdgeData) => EdgeLabelPos);
 
   /**
    * <zh/> 标签与边的偏移距离，用于微调标签位置避免视觉重叠
    *
    * <en/> Offset distance between label and edge for fine-tuning label position to avoid visual overlap
    */
-  edgeLabelOffset?: number | ((edge: EdgeData) => number);
+  edgeLabelOffset?: number | Expr | ((edge: EdgeData) => number);
 }

src/types/common.ts

@@ -2,13 +2,24 @@ export type PlainObject = Record<string, any>;
 
 export type Matrix = number[][];
 
+/**
+ * String expression evaluated by `@antv/expr`.
+ *
+ * Notes:
+ * - `Expr` is structured-cloneable and can be passed into WebWorkers.
+ * - Function callbacks cannot be structured-cloned; prefer `Expr` when `enableWorker: true`.
+ */
 export type Expr = string;
 
 /**
  * CallableExpr<(node: NodeData) => number>
  *
  * => 'node.degree' | (node: NodeData) => number
  */
-export type CallableExpr<T = any> = Expr | ((data: T) => any);
+export type CallableExpr<TData = any, TResult = any> =
+  | Expr
+  | ((data: TData) => TResult);
+
+export type ExprContext = Record<string, any>;
 
 export type Sorter<T = any> = (a: T, b: T) => -1 | 0 | 1;

src/util/expr.ts

@@ -1,5 +1,5 @@
 import { compile, evaluate } from '@antv/expr';
-import type { Context } from '@antv/expr/dist/interpreter';
+import type { ExprContext } from '../types';
 
 /**
  * Evaluate an expression if (and only if) it's a valid string expression.
@@ -10,8 +10,8 @@ import type { Context } from '@antv/expr/dist/interpreter';
  */
 export function evaluateExpression(
   expression: unknown,
-  context: Context,
-): Function | undefined {
+  context: ExprContext,
+): unknown | undefined {
   if (typeof expression !== 'string') return undefined;
 
   const source = expression.trim();