or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

animation.mdcore-zrender.mdevents.mdgraphics-primitives.mdindex.mdshapes.mdstyling.mdtext-images.mdutilities.md
tile.json

tessl/npm-zrender

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/zrender@6.0.x

To install, run

npx @tessl/cli install tessl/npm-zrender@6.0.0

index.mddocs/

ZRender

ZRender is a comprehensive 2D graphics rendering library that serves as the foundational graphics engine for Apache ECharts. It provides a lightweight, cross-platform solution for creating interactive vector graphics through multiple rendering backends including Canvas, SVG, and VML. The library offers a rich set of graphical primitives, advanced features like animation support, event handling, transformations, and gradient fills, all wrapped in a clean TypeScript API.

Package Information

  • Package Name: zrender
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install zrender

Core Imports

import { init, ZRender } from "zrender";

For tree-shakable imports:

import { init, Circle, LinearGradient, Text } from "zrender";

CommonJS:

const { init, Circle, LinearGradient } = require("zrender");

Basic Usage

import { init, Circle, LinearGradient } from "zrender";

// Initialize ZRender instance
const zr = init(document.getElementById("canvas"));

// Create a circle with gradient fill
const circle = new Circle({
  shape: { cx: 100, cy: 100, r: 50 },
  style: {
    fill: new LinearGradient(0, 0, 0, 1, [
      { offset: 0, color: "#ff0000" },
      { offset: 1, color: "#0000ff" }
    ])
  }
});

// Add to scene and render
zr.add(circle);

Architecture

ZRender is built around several key components:

  • ZRender Instance: Main controller managing canvas, rendering pipeline, and event handling
  • Graphics System: Hierarchical scene graph with Element base class, Groups for organization, and specialized shape primitives
  • Rendering Backends: Pluggable painter system supporting Canvas (high performance), SVG (vector output), and VML (legacy IE)
  • Animation System: Frame-based animation engine with easing functions, clips, and morphing capabilities
  • Event System: Mouse, touch, and custom event handling with hit testing and event delegation
  • Utility Libraries: Math operations (matrix, vector), color manipulation, path processing, and platform abstractions

Capabilities

Core ZRender Management

Primary ZRender class and instance management for controlling the rendering engine, managing scenes, and handling the rendering lifecycle.

function init(dom?: HTMLElement | null, opts?: ZRenderInitOpt): ZRender;
function dispose(zr: ZRender): void;
function disposeAll(): void;
function getInstance(id: number): ZRender;

interface ZRenderInitOpt {
  renderer?: string;   // 'canvas' or 'svg'
  devicePixelRatio?: number;
  width?: number | string;
  height?: number | string;
  useDirtyRect?: boolean;
  useCoarsePointer?: 'auto' | boolean;
  pointerSize?: number;
  ssr?: boolean;
}

Core ZRender Management

Graphics Primitives

Complete set of 2D graphics elements including shapes, paths, text, images, and container groups. All elements support styling, transformations, and event handling.

class Element {
  add(el: Element): void;
  remove(el: Element): void;
  animate(props: any, duration?: number): Animator;
  on(eventName: string, handler: Function): this;
  off(eventName?: string, handler?: Function): void;
}

class Group extends Element {
  children(): Element[];
}

class Circle extends Path {
  constructor(opts: CircleProps);
}

interface CircleProps {
  shape: CircleShape;
  style?: PathStyleProps;
}

interface CircleShape {
  cx: number;
  cy: number;
  r: number;
}

Graphics Primitives

Shape Library

Built-in geometric shapes including basic primitives (Circle, Rect, Line) and complex shapes (Star, Heart, Trochoid). Each shape provides complete type definitions and configurable properties.

class Rect extends Path {
  constructor(opts: RectProps);
}

class Arc extends Path {
  constructor(opts: ArcProps);
}

class Polygon extends Path {
  constructor(opts: PolygonProps);
}

class Star extends Path {
  constructor(opts: StarProps);
}

interface RectShape {
  x: number;
  y: number;
  width: number;
  height: number;
  r?: number | number[];
}

Shape Library

Text and Image Rendering

Text rendering with rich typography support and image display capabilities. Includes text styling, multi-line text, and bitmap image handling.

class Text extends Displayable {
  constructor(opts: TextProps);
}

class Image extends Displayable {
  constructor(opts: ImageProps);
}

interface TextStyleProps {
  text?: string;
  fontSize?: number;
  fontFamily?: string;
  fill?: string;
  textAlign?: 'left' | 'center' | 'right';
  textVerticalAlign?: 'top' | 'middle' | 'bottom';
}

Text and Image Rendering

Styling and Gradients

Visual styling system including solid colors, linear and radial gradients, and pattern fills. Complete control over appearance and visual effects.

class LinearGradient {
  constructor(x1: number, y1: number, x2: number, y2: number, colorStops: ColorStop[]);
}

class RadialGradient {
  constructor(x: number, y: number, r: number, colorStops: ColorStop[]);
}

class Pattern {
  constructor(image: HTMLImageElement | HTMLCanvasElement, repeat: string);
}

interface ColorStop {
  offset: number;
  color: string;
}

Styling and Gradients

Animation System

Comprehensive animation framework with property interpolation, easing functions, and advanced features like path morphing and timeline control.

interface Animator {
  when(time: number, props: any): Animator;
  during(callback: (percent: number) => void): Animator;
  done(callback: () => void): Animator;
  start(easing?: string | Function): Animator;
  stop(): void;
}

function easeInOut(t: number): number;
function easeInQuad(t: number): number;
function easeOutBounce(t: number): number;

Animation System

Utility Libraries

Mathematical operations, color manipulation, path processing, and platform abstractions. Essential utilities for graphics programming and cross-platform compatibility.

namespace util {
  function clone<T>(obj: T): T;
  function merge<T, S>(target: T, source: S): T & S;
  function guid(): number;
  function isArray(value: any): value is any[];
  function isObject(value: any): value is object;
}

namespace matrix {
  function create(): number[];
  function translate(m: number[], tx: number, ty: number): number[];
  function rotate(m: number[], rad: number): number[];
  function scale(m: number[], sx: number, sy: number): number[];
}

namespace vector {
  function create(x?: number, y?: number): number[];
  function add(out: number[], a: number[], b: number[]): number[];
  function distance(a: number[], b: number[]): number;
  function normalize(out: number[], a: number[]): number[];
}

namespace color {
  function parse(colorStr: string): number[];
  function toHex(color: string): string;
  function lerp(t: number, a: string, b: string): string;
}

Utility Libraries

Event Handling

Mouse, touch, and custom event system with hit testing, event delegation, and interaction handling. Complete support for user interactions and custom event types.

interface ZRender {
  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;
}

type ElementEventName = 'click' | 'mousedown' | 'mouseup' | 'mousemove' | 'mouseover' | 'mouseout' | 'drag' | 'dragstart' | 'dragend';

Event Handling

Types

Core type definitions used throughout the ZRender API:

interface Point {
  x: number;
  y: number;
}

interface BoundingRect {
  x: number;
  y: number;
  width: number;
  height: number;
}

interface ElementProps {
  position?: number[];
  rotation?: number;
  scale?: number[];
  origin?: number[];
  zlevel?: number;
  z?: number;
  invisible?: boolean;
  ignore?: boolean;
  silent?: boolean;
}

interface PathStyleProps {
  fill?: string | LinearGradient | RadialGradient | Pattern;
  stroke?: string;
  lineWidth?: number;
  lineDash?: number[];
  opacity?: number;
  shadowBlur?: number;
  shadowColor?: string;
  shadowOffsetX?: number;
  shadowOffsetY?: number;
}