tessl/npm-zrender

A lightweight 2D graphics library providing canvas and SVG rendering for Apache ECharts

Overview

Eval results

Files

Core ZRender Management

Name: tessl/npm-zrender
Author: tessl

The ZRender core provides the main rendering engine class and instance management functions. The ZRender class controls the canvas, manages the scene graph, handles rendering cycles, and provides the primary interface for all graphics operations.

Core Functions

Instance Creation and Management

function init(dom?: HTMLElement | null, opts?: ZRenderInitOpt): ZRender;

Creates a new ZRender instance attached to a DOM element. This is the primary way to start using ZRender.

Parameters:

dom - HTML element to attach the renderer to (optional for SSR)
opts - Configuration options for the renderer

Returns: New ZRender instance ready for use.

function dispose(zr: ZRender): void;

Disposes a specific ZRender instance, cleaning up resources and event handlers.

function disposeAll(): void;

Disposes all ZRender instances, useful for complete cleanup.

function getInstance(id: number): ZRender;

Retrieves a ZRender instance by its internal ID.

function registerPainter(name: string, Ctor: PainterBaseCtor): void;

Registers a new rendering backend (painter) with ZRender.

ZRender Class

The main ZRender class provides comprehensive control over the rendering engine:

Scene Management

class ZRender {
  add(el: Element): void;
  remove(el: Element): void;
  clear(): void;
}

add() - Adds an element to the scene
remove() - Removes an element from the scene
clear() - Removes all elements and clears the canvas

Rendering Control

class ZRender {
  refresh(): void;
  refreshImmediately(fromInside?: boolean): void;
  flush(): void;
  setSleepAfterStill(stillFramesCount: number): void;
  wakeUp(): void;
}

refresh() - Marks for repaint in the next animation frame
refreshImmediately() - Triggers immediate repaint
flush() - Performs all pending refreshes
setSleepAfterStill() - Sets animation sleep threshold for performance
wakeUp() - Wakes up the animation loop

Canvas Configuration

class ZRender {
  resize(opts?: { width?: number | string; height?: number | string }): void;
  getWidth(): number | undefined;
  getHeight(): number | undefined;
  setBackgroundColor(backgroundColor: string | LinearGradient | RadialGradient | Pattern): void;
  getBackgroundColor(): string | LinearGradient | RadialGradient | Pattern;
  configLayer(zLevel: number, config: LayerConfig): void;
}

Dark Mode Support

class ZRender {
  setDarkMode(darkMode: boolean): void;
  isDarkMode(): boolean;
}

Provides dark mode detection and override capabilities for theme-aware rendering.

Animation Control

class ZRender {
  clearAnimation(): void;
}

Stops and clears all running animations immediately.

Event Handling

class ZRender {
  on<Ctx>(eventName: ElementEventName, eventHandler: ElementEventCallback<Ctx>, context?: Ctx): this;
  on<Ctx>(eventName: string, eventHandler: Function, context?: Ctx): this;
  off(eventName?: string, eventHandler?: Function): void;
  trigger(eventName: string, event?: unknown): void;
  findHover(x: number, y: number): { target: Displayable; topTarget: Displayable } | undefined;
}

Cursor Management

class ZRender {
  setCursorStyle(cursorStyle: string): void;
}

Sets the default cursor style for the canvas.

Hover Effects

class ZRender {
  refreshHover(): void;
  refreshHoverImmediately(): void;
}

Controls hover state rendering for interactive elements.

Configuration Types

interface ZRenderInitOpt {
  renderer?: string;           // 'canvas' or 'svg'
  devicePixelRatio?: number;   // Device pixel ratio override
  width?: number | string;     // Canvas width ('auto', '100px', 400)
  height?: number | string;    // Canvas height
  useDirtyRect?: boolean;      // Enable dirty rectangle optimization
  useCoarsePointer?: 'auto' | boolean;  // Touch-friendly pointer handling
  pointerSize?: number;        // Pointer size for touch interfaces
  ssr?: boolean;              // Server-side rendering mode
}

interface LayerConfig {
  clearColor?: string;
  motionBlur?: boolean;
  lastFrameAlpha?: number;
}

SSR Support

ZRender provides server-side rendering capabilities:

function getElementSSRData(el: Element): ElementSSRData;
function registerSSRDataGetter<T>(getter: ElementSSRDataGetter<T>): void;

type ElementSSRData = Record<string, unknown>;
type ElementSSRDataGetter<T> = (el: Element) => Record<string, T>;

Usage Examples

Basic Initialization

import { init } from "zrender";

// Create ZRender instance
const zr = init(document.getElementById('canvas'), {
  renderer: 'canvas',
  width: 800,
  height: 600
});

// Set background color
zr.setBackgroundColor('#f0f0f0');

Advanced Configuration

import { init } from "zrender";

const zr = init(document.getElementById('canvas'), {
  renderer: 'svg',
  useDirtyRect: true,
  useCoarsePointer: 'auto',
  devicePixelRatio: window.devicePixelRatio
});

// Configure performance settings
zr.setSleepAfterStill(10);

// Handle resize
window.addEventListener('resize', () => {
  zr.resize({
    width: window.innerWidth,
    height: window.innerHeight
  });
});

// Cleanup on page unload
window.addEventListener('beforeunload', () => {
  zr.dispose();
});

Multi-instance Management

import { init, getInstance, disposeAll } from "zrender";

// Create multiple instances
const zr1 = init(document.getElementById('canvas1'));
const zr2 = init(document.getElementById('canvas2'));

// Get instance by ID later
const retrievedInstance = getInstance(zr1.id);

// Cleanup all instances
disposeAll();

Install with Tessl CLI