0
# ZRender
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: zrender
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install zrender`
10

11
## Core Imports
12

13
```typescript
14
import { init, ZRender } from "zrender";
15
```
16

17
For tree-shakable imports:
18

19
```typescript
20
import { init, Circle, LinearGradient, Text } from "zrender";
21
```
22

23
CommonJS:
24

25
```javascript
26
const { init, Circle, LinearGradient } = require("zrender");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { init, Circle, LinearGradient } from "zrender";
33

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

37
// Create a circle with gradient fill
38
const circle = new Circle({
39
  shape: { cx: 100, cy: 100, r: 50 },
40
  style: {
41
    fill: new LinearGradient(0, 0, 0, 1, [
42
      { offset: 0, color: "#ff0000" },
43
      { offset: 1, color: "#0000ff" }
44
    ])
45
  }
46
});
47

48
// Add to scene and render
49
zr.add(circle);
50
```
51

52
## Architecture
53

54
ZRender is built around several key components:
55

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

63
## Capabilities
64

65
### Core ZRender Management
66

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

69
```typescript { .api }
70
function init(dom?: HTMLElement | null, opts?: ZRenderInitOpt): ZRender;
71
function dispose(zr: ZRender): void;
72
function disposeAll(): void;
73
function getInstance(id: number): ZRender;
74

75
interface ZRenderInitOpt {
76
  renderer?: string;   // 'canvas' or 'svg'
77
  devicePixelRatio?: number;
78
  width?: number | string;
79
  height?: number | string;
80
  useDirtyRect?: boolean;
81
  useCoarsePointer?: 'auto' | boolean;
82
  pointerSize?: number;
83
  ssr?: boolean;
84
}
85
```
86

87
[Core ZRender Management](./core-zrender.md)
88

89
### Graphics Primitives
90

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

93
```typescript { .api }
94
class Element {
95
  add(el: Element): void;
96
  remove(el: Element): void;
97
  animate(props: any, duration?: number): Animator;
98
  on(eventName: string, handler: Function): this;
99
  off(eventName?: string, handler?: Function): void;
100
}
101

102
class Group extends Element {
103
  children(): Element[];
104
}
105

106
class Circle extends Path {
107
  constructor(opts: CircleProps);
108
}
109

110
interface CircleProps {
111
  shape: CircleShape;
112
  style?: PathStyleProps;
113
}
114

115
interface CircleShape {
116
  cx: number;
117
  cy: number;
118
  r: number;
119
}
120
```
121

122
[Graphics Primitives](./graphics-primitives.md)
123

124
### Shape Library
125

126
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.
127

128
```typescript { .api }
129
class Rect extends Path {
130
  constructor(opts: RectProps);
131
}
132

133
class Arc extends Path {
134
  constructor(opts: ArcProps);
135
}
136

137
class Polygon extends Path {
138
  constructor(opts: PolygonProps);
139
}
140

141
class Star extends Path {
142
  constructor(opts: StarProps);
143
}
144

145
interface RectShape {
146
  x: number;
147
  y: number;
148
  width: number;
149
  height: number;
150
  r?: number | number[];
151
}
152
```
153

154
[Shape Library](./shapes.md)
155

156
### Text and Image Rendering
157

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

160
```typescript { .api }
161
class Text extends Displayable {
162
  constructor(opts: TextProps);
163
}
164

165
class Image extends Displayable {
166
  constructor(opts: ImageProps);
167
}
168

169
interface TextStyleProps {
170
  text?: string;
171
  fontSize?: number;
172
  fontFamily?: string;
173
  fill?: string;
174
  textAlign?: 'left' | 'center' | 'right';
175
  textVerticalAlign?: 'top' | 'middle' | 'bottom';
176
}
177
```
178

179
[Text and Image Rendering](./text-images.md)
180

181
### Styling and Gradients
182

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

185
```typescript { .api }
186
class LinearGradient {
187
  constructor(x1: number, y1: number, x2: number, y2: number, colorStops: ColorStop[]);
188
}
189

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

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

198
interface ColorStop {
199
  offset: number;
200
  color: string;
201
}
202
```
203

204
[Styling and Gradients](./styling.md)
205

206
### Animation System
207

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

210
```typescript { .api }
211
interface Animator {
212
  when(time: number, props: any): Animator;
213
  during(callback: (percent: number) => void): Animator;
214
  done(callback: () => void): Animator;
215
  start(easing?: string | Function): Animator;
216
  stop(): void;
217
}
218

219
function easeInOut(t: number): number;
220
function easeInQuad(t: number): number;
221
function easeOutBounce(t: number): number;
222
```
223

224
[Animation System](./animation.md)
225

226
### Utility Libraries
227

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

230
```typescript { .api }
231
namespace util {
232
  function clone<T>(obj: T): T;
233
  function merge<T, S>(target: T, source: S): T & S;
234
  function guid(): number;
235
  function isArray(value: any): value is any[];
236
  function isObject(value: any): value is object;
237
}
238

239
namespace matrix {
240
  function create(): number[];
241
  function translate(m: number[], tx: number, ty: number): number[];
242
  function rotate(m: number[], rad: number): number[];
243
  function scale(m: number[], sx: number, sy: number): number[];
244
}
245

246
namespace vector {
247
  function create(x?: number, y?: number): number[];
248
  function add(out: number[], a: number[], b: number[]): number[];
249
  function distance(a: number[], b: number[]): number;
250
  function normalize(out: number[], a: number[]): number[];
251
}
252

253
namespace color {
254
  function parse(colorStr: string): number[];
255
  function toHex(color: string): string;
256
  function lerp(t: number, a: string, b: string): string;
257
}
258
```
259

260
[Utility Libraries](./utilities.md)
261

262
### Event Handling
263

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

266
```typescript { .api }
267
interface ZRender {
268
  on<Ctx>(eventName: string, eventHandler: Function, context?: Ctx): this;
269
  off(eventName?: string, eventHandler?: Function): void;
270
  trigger(eventName: string, event?: unknown): void;
271
  findHover(x: number, y: number): { target: Displayable; topTarget: Displayable } | undefined;
272
}
273

274
type ElementEventName = 'click' | 'mousedown' | 'mouseup' | 'mousemove' | 'mouseover' | 'mouseout' | 'drag' | 'dragstart' | 'dragend';
275
```
276

277
[Event Handling](./events.md)
278

279
## Types
280

281
Core type definitions used throughout the ZRender API:
282

283
```typescript { .api }
284
interface Point {
285
  x: number;
286
  y: number;
287
}
288

289
interface BoundingRect {
290
  x: number;
291
  y: number;
292
  width: number;
293
  height: number;
294
}
295

296
interface ElementProps {
297
  position?: number[];
298
  rotation?: number;
299
  scale?: number[];
300
  origin?: number[];
301
  zlevel?: number;
302
  z?: number;
303
  invisible?: boolean;
304
  ignore?: boolean;
305
  silent?: boolean;
306
}
307

308
interface PathStyleProps {
309
  fill?: string | LinearGradient | RadialGradient | Pattern;
310
  stroke?: string;
311
  lineWidth?: number;
312
  lineDash?: number[];
313
  opacity?: number;
314
  shadowBlur?: number;
315
  shadowColor?: string;
316
  shadowOffsetX?: number;
317
  shadowOffsetY?: number;
318
}
319
```