feat: support render contributions for line graphic

common/changes/@visactor/vrender-core/feat-line-render-contribution_2026-09-15-08-00.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@visactor/vrender-core",
+      "comment": "feat: support render contributions for line graphic",
+      "type": "none"
+    }
+  ],
+  "packageName": "@visactor/vrender-core"
+}

packages/vrender-core/__tests__/perf/line-render-contribution-performance.test.ts

@@ -0,0 +1,112 @@
+import { createLine } from '../../src/graphic/line';
+import { DefaultCanvasLineRender } from '../../src/render/contributions/render/line-render';
+
+declare const process: {
+  env: Record<string, string | undefined>;
+  stdout: {
+    write: (message: string) => void;
+  };
+};
+
+// 默认跳过，和 attribute-model-performance 一样按需开：VRENDER_LINE_RENDER_PERF=1
+const runPerf = process.env.VRENDER_LINE_RENDER_PERF === '1' ? describe : describe.skip;
+
+const POINT_COUNT = 200;
+const ITERATIONS = 2000;
+const ROUNDS = 9;
+
+function createNoopContext() {
+  const noop = (): void => undefined;
+  return {
+    beginPath: noop,
+    closePath: noop,
+    moveTo: noop,
+    lineTo: noop,
+    stroke: noop,
+    fill: noop,
+    setCommonStyle: noop,
+    setStrokeStyle: noop,
+    setShadowBlendStyle: noop
+  };
+}
+
+function createBenchmarkLine() {
+  const points: { x: number; y: number }[] = [];
+  for (let i = 0; i < POINT_COUNT; i++) {
+    points.push({ x: i, y: (i * 7) % 100 });
+  }
+  return createLine({ points, stroke: '#1664ff', lineWidth: 1, curveType: 'linear' });
+}
+
+/** 把两个钩子改成空实现，用来隔离「多出来的那点活」到底值多少 */
+class NoHookLineRender extends DefaultCanvasLineRender {
+  beforeRenderStep(): void {
+    return undefined;
+  }
+  afterRenderStep(): void {
+    return undefined;
+  }
+}
+
+function warmUp(render: DefaultCanvasLineRender): void {
+  const line = createBenchmarkLine();
+  const context = createNoopContext();
+  for (let i = 0; i < 500; i++) {
+    render.drawShape(line as any, context as any, 0, 0, {} as any);
+  }
+}
+
+function measure(render: DefaultCanvasLineRender): number {
+  const line = createBenchmarkLine();
+  const context = createNoopContext();
+  const start = performance.now();
+  for (let i = 0; i < ITERATIONS; i++) {
+    render.drawShape(line as any, context as any, 0, 0, {} as any);
+  }
+  return performance.now() - start;
+}
+
+/**
+ * 两个变体交替测、各取最小值。
+ * 顺序测会把 JIT 预热成本算到先测的那个头上，实测能让开销算出负数。
+ */
+function compare(a: DefaultCanvasLineRender, b: DefaultCanvasLineRender): { a: number; b: number } {
+  warmUp(a);
+  warmUp(b);
+  let bestA = Infinity;
+  let bestB = Infinity;
+  for (let round = 0; round < ROUNDS; round++) {
+    bestA = Math.min(bestA, measure(a));
+    bestB = Math.min(bestB, measure(b));
+  }
+  return { a: bestA, b: bestB };
+}
+
+runPerf('line render contribution overhead on the high-performance path', () => {
+  it('measures the cost added by the render contribution hooks', () => {
+    const emptyProvider = { getContributions: (): any[] => [] } as any;
+    // init() 无条件塞两个内置裁剪贡献，所以「没有自定义贡献」并不是空列表
+    const withHooks = new DefaultCanvasLineRender(emptyProvider);
+    const withoutHooks = new NoHookLineRender(emptyProvider);
+
+    expect((withHooks as any)._beforeRenderContribitions.length).toBe(1);
+    expect((withHooks as any)._afterRenderContribitions.length).toBe(1);
+
+    const { a: baseline, b: actual } = compare(withoutHooks, withHooks);
+
+    process.stdout.write(
+      JSON.stringify({
+        benchmark: 'line-render-contribution-overhead',
+        pointCount: POINT_COUNT,
+        iterations: ITERATIONS,
+        rounds: ROUNDS,
+        hooksStubbedMinMs: Number(baseline.toFixed(3)),
+        hooksActiveMinMs: Number(actual.toFixed(3)),
+        overheadPerDrawUs: Number((((actual - baseline) / ITERATIONS) * 1000).toFixed(4)),
+        overheadPct: Number((((actual - baseline) / baseline) * 100).toFixed(2))
+      }) + '\n'
+    );
+
+    expect(actual).toBeGreaterThan(0);
+  });
+});

packages/vrender-core/__tests__/unit/entries/runtime-renderer-contributions.test.ts

@@ -39,6 +39,11 @@ describe('runtime graphic renderer contributions', () => {
       rendererName: 'DefaultCanvasAreaRender',
       contributionExport: 'AreaRenderContribution'
     },
+    {
+      moduleExport: 'lineModule',
+      rendererName: 'DefaultCanvasLineRender',
+      contributionExport: 'LineRenderContribution'
+    },
     {
       moduleExport: 'pathModule',
       rendererName: 'DefaultCanvasPathRender',

packages/vrender-core/__tests__/unit/render/line-render-contribution.test.ts

@@ -0,0 +1,199 @@
+import { createLine } from '../../../src/graphic/line';
+import { DefaultCanvasLineRender } from '../../../src/render/contributions/render/line-render';
+import { DefaultIncrementalCanvasLineRender } from '../../../src/render/contributions/render/incremental-line-render';
+import { BaseRenderContributionTime } from '../../../src/common/enums';
+
+type RecordingContext = ReturnType<typeof createRecordingContext>;
+
+/** 记录画布调用序列，用来判「最后 stroke 的到底是折线还是裁剪形状」 */
+function createRecordingContext() {
+  const calls: string[] = [];
+  const record = (name: string) => (): void => {
+    calls.push(name);
+  };
+  return {
+    calls,
+    beginPath: record('beginPath'),
+    closePath: record('closePath'),
+    moveTo: record('moveTo'),
+    lineTo: record('lineTo'),
+    rect: record('rect'),
+    clip: record('clip'),
+    save: record('save'),
+    restore: record('restore'),
+    fill: record('fill'),
+    stroke: record('stroke'),
+    setCommonStyle: jest.fn(),
+    setStrokeStyle: jest.fn(),
+    setShadowBlendStyle: jest.fn(),
+    nativeContext: {
+      moveTo: record('moveTo'),
+      lineTo: record('lineTo'),
+      closePath: record('closePath')
+    }
+  };
+}
+
+function createRender(contributions: any[] = []) {
+  return new DefaultCanvasLineRender({ getContributions: () => contributions } as any);
+}
+
+/** 画布调用序列里，最后一次 stroke 之前那一段路径指令 */
+function pathBeforeLastStroke(context: RecordingContext) {
+  const strokeAt = context.calls.lastIndexOf('stroke');
+  const beginAt = context.calls.lastIndexOf('beginPath', strokeAt);
+  return context.calls.slice(beginAt, strokeAt);
+}
+
+describe('line render contributions', () => {
+  it('keeps the base drawing sequence when no contribution is registered', () => {
+    const line = createLine({
+      points: [
+        { x: 0, y: 0 },
+        { x: 10, y: 10 },
+        { x: 20, y: 0 }
+      ],
+      stroke: '#000',
+      lineWidth: 1
+    });
+    const context = createRecordingContext();
+
+    createRender().drawShape(line as any, context as any, 0, 0, {} as any);
+
+    expect(context.calls).toEqual(['beginPath', 'moveTo', 'lineTo', 'lineTo', 'stroke']);
+    expect(context.calls).not.toContain('clip');
+  });
+
+  it('strokes the line itself, not the clip shape, when clipConfig is set', () => {
+    const line = createLine({
+      points: [
+        { x: 0, y: 0 },
+        { x: 10, y: 10 },
+        { x: 20, y: 0 }
+      ],
+      stroke: '#000',
+      lineWidth: 1,
+      clipConfig: { shape: 'rect' }
+    } as any);
+    // 只关心内置裁剪贡献会 beginPath 冲掉图元路径这件事，裁剪形状本身用最小桩
+    Object.defineProperty(line, 'AABBBounds', {
+      get: () => ({ width: () => 20, height: () => 20 })
+    });
+    (line as any).getClipPath = () => ({
+      draw: (ctx: any) => {
+        ctx.rect(0, 0, 20, 20);
+        return true;
+      }
+    });
+    const context = createRecordingContext();
+
+    createRender().drawShape(line as any, context as any, 0, 0, {} as any);
+
+    expect(context.calls).toContain('clip');
+    // 裁剪生效之后重建了折线路径，stroke 画的是折线而不是裁剪矩形
+    expect(pathBeforeLastStroke(context)).toEqual(['beginPath', 'moveTo', 'lineTo', 'lineTo']);
+    expect(pathBeforeLastStroke(context)).not.toContain('rect');
+  });
+
+  it('passes computed visibility booleans rather than opacity numbers', () => {
+    const drawShape = jest.fn();
+    const line = createLine({
+      points: [
+        { x: 0, y: 0 },
+        { x: 10, y: 10 }
+      ],
+      fill: false,
+      stroke: '#000',
+      strokeOpacity: 0.5,
+      lineWidth: 1
+    });
+    const context = createRecordingContext();
+
+    createRender([
+      { time: BaseRenderContributionTime.beforeFillStroke, useStyle: false, order: 1, drawShape }
+    ]).drawShape(line as any, context as any, 0, 0, {} as any);
+
+    expect(drawShape).toHaveBeenCalledTimes(1);
+    const [, , , , doFill, doStroke, fVisible, sVisible] = drawShape.mock.calls[0];
+    expect([doFill, doStroke, fVisible, sVisible]).toEqual([false, true, false, true]);
+  });
+
+  it('exposes the active segment attributes to per-segment contributions', () => {
+    const drawShape = jest.fn();
+    const line = createLine({
+      stroke: '#000',
+      lineWidth: 1,
+      segments: [
+        {
+          points: [
+            { x: 0, y: 0 },
+            { x: 10, y: 10 }
+          ],
+          stroke: 'red'
+        },
+        {
+          points: [
+            { x: 10, y: 10 },
+            { x: 20, y: 0 }
+          ],
+          stroke: 'blue'
+        }
+      ]
+    } as any);
+    const context = createRecordingContext();
+
+    createRender([
+      { time: BaseRenderContributionTime.beforeFillStroke, useStyle: false, order: 1, drawShape }
+    ]).drawShape(line as any, context as any, 0, 0, {} as any);
+
+    const strokes = drawShape.mock.calls.map(args => args[args.length - 1]?.attribute?.stroke);
+    expect(strokes).toEqual(['red', 'blue']);
+  });
+
+  it('wires contributions through the incremental renderer', () => {
+    const drawShape = jest.fn();
+    const afterDrawShape = jest.fn();
+    const render = new DefaultIncrementalCanvasLineRender({
+      getContributions: () => [
+        { time: BaseRenderContributionTime.beforeFillStroke, useStyle: false, order: 1, drawShape },
+        {
+          time: BaseRenderContributionTime.afterFillStroke,
+          useStyle: false,
+          order: 1,
+          drawShape: afterDrawShape
+        }
+      ]
+    } as any);
+    const line = createLine({
+      stroke: '#000',
+      lineWidth: 1,
+      segments: [
+        {
+          points: [
+            { x: 0, y: 0 },
+            { x: 10, y: 10 }
+          ]
+        },
+        {
+          points: [
+            { x: 10, y: 10 },
+            { x: 20, y: 0 }
+          ]
+        }
+      ]
+    } as any);
+    (line as any).incremental = 1;
+    const context = createRecordingContext();
+
+    render.drawShape(line as any, context as any, 0, 0, {
+      context,
+      multiGraphicOptions: { startAtIdx: 1, length: 1 }
+    } as any);
+
+    expect(context.calls).toContain('stroke');
+    expect(drawShape).toHaveBeenCalledTimes(1);
+    expect(afterDrawShape).toHaveBeenCalledTimes(1);
+    const [, , , , doFill, doStroke, fVisible, sVisible] = drawShape.mock.calls[0];
+    expect([doFill, doStroke, fVisible, sVisible]).toEqual([false, true, false, true]);
+  });
+});

packages/vrender-core/src/entries/runtime-installer.ts

@@ -1,6 +1,7 @@
 import type {
   IContributionProvider,
   IAreaRenderContribution,
+  ILineRenderContribution,
   IDrawItemInterceptorContribution,
   IEnvContribution,
   IGlobal,
@@ -21,7 +22,10 @@ import graphicModule from '../graphic/graphic-service/graphic-module';
 import type { ILegacyBindingContext } from '../legacy/binding-context';
 import { getLegacyBindingContext, preLoadAllModule } from '../legacy/bootstrap';
 import pickModule from '../picker/pick-modules';
-import { AreaRenderContribution } from '../render/contributions/render/contributions/constants';
+import {
+  AreaRenderContribution,
+  LineRenderContribution
+} from '../render/contributions/render/contributions/constants';
 import { DrawItemInterceptor } from '../render/contributions/render/draw-interceptor';
 import { DefaultIncrementalCanvasAreaRender } from '../render/contributions/render/incremental-area-render';
 import { DefaultIncrementalDrawContribution } from '../render/contributions/render/incremental-draw-contribution';
@@ -169,7 +173,9 @@ export function configureRuntimeApplicationForApp(app: IApp): void {
   application.incrementalDrawContributionFactory = () =>
     new DefaultIncrementalDrawContribution(
       [],
-      new DefaultIncrementalCanvasLineRender(),
+      new DefaultIncrementalCanvasLineRender(
+        createContributionProvider<ILineRenderContribution>(LineRenderContribution, bindingContext)
+      ),
       new DefaultIncrementalCanvasAreaRender(
         createContributionProvider<IAreaRenderContribution>(AreaRenderContribution, bindingContext)
       ),

packages/vrender-core/src/interface/contribution.ts

@@ -6,6 +6,7 @@ import type { ISymbol, ISymbolGraphicAttribute } from './graphic/symbol';
 import type { BaseRenderContributionTime } from '../common/enums';
 import type { IArc, IArcGraphicAttribute } from './graphic/arc';
 import type { IArea, IAreaGraphicAttribute } from './graphic/area';
+import type { ILine, ILineGraphicAttribute } from './graphic/line';
 import type { IText, ITextGraphicAttribute } from './graphic/text';
 import type { ICircle, ICircleGraphicAttribute } from './graphic/circle';
 import type { IGroup, IGroupGraphicAttribute } from './graphic/group';
@@ -75,6 +76,8 @@ export type IPolygonRenderContribution = IBaseRenderContribution<IPolygon, IPoly
 
 export type IRectRenderContribution = IBaseRenderContribution<IRect, IRectGraphicAttribute>;
 
+export type ILineRenderContribution = IBaseRenderContribution<ILine, ILineGraphicAttribute>;
+
 export interface IContributionProvider<T> {
   getContributions: () => T[];
 }

packages/vrender-core/src/render/contributions/render/contributions/constants.ts

@@ -6,6 +6,7 @@ export const ImageRenderContribution = Symbol.for('ImageRenderContribution');
 export const PathRenderContribution = Symbol.for('PathRenderContribution');
 export const PolygonRenderContribution = Symbol.for('PolygonRenderContribution');
 export const RectRenderContribution = Symbol.for('RectRenderContribution');
+export const LineRenderContribution = Symbol.for('LineRenderContribution');
 export const SymbolRenderContribution = Symbol.for('SymbolRenderContribution');
 export const TextRenderContribution = Symbol.for('TextRenderContribution');
 export const StarRenderContribution = Symbol.for('StarRenderContribution');