0
# Core ZRender Management
1

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

4
## Core Functions
5

6
### Instance Creation and Management
7

8
```typescript { .api }
9
function init(dom?: HTMLElement | null, opts?: ZRenderInitOpt): ZRender;
10
```
11

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

14
**Parameters:**
15
- `dom` - HTML element to attach the renderer to (optional for SSR)
16
- `opts` - Configuration options for the renderer
17

18
**Returns:** New ZRender instance ready for use.
19

20
```typescript { .api }
21
function dispose(zr: ZRender): void;
22
```
23

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

26
```typescript { .api }
27
function disposeAll(): void;
28
```
29

30
Disposes all ZRender instances, useful for complete cleanup.
31

32
```typescript { .api }
33
function getInstance(id: number): ZRender;
34
```
35

36
Retrieves a ZRender instance by its internal ID.
37

38
```typescript { .api }
39
function registerPainter(name: string, Ctor: PainterBaseCtor): void;
40
```
41

42
Registers a new rendering backend (painter) with ZRender.
43

44
## ZRender Class
45

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

48
### Scene Management
49

50
```typescript { .api }
51
class ZRender {
52
  add(el: Element): void;
53
  remove(el: Element): void;
54
  clear(): void;
55
}
56
```
57

58
- `add()` - Adds an element to the scene
59
- `remove()` - Removes an element from the scene  
60
- `clear()` - Removes all elements and clears the canvas
61

62
### Rendering Control
63

64
```typescript { .api }
65
class ZRender {
66
  refresh(): void;
67
  refreshImmediately(fromInside?: boolean): void;
68
  flush(): void;
69
  setSleepAfterStill(stillFramesCount: number): void;
70
  wakeUp(): void;
71
}
72
```
73

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

80
### Canvas Configuration
81

82
```typescript { .api }
83
class ZRender {
84
  resize(opts?: { width?: number | string; height?: number | string }): void;
85
  getWidth(): number | undefined;
86
  getHeight(): number | undefined;
87
  setBackgroundColor(backgroundColor: string | LinearGradient | RadialGradient | Pattern): void;
88
  getBackgroundColor(): string | LinearGradient | RadialGradient | Pattern;
89
  configLayer(zLevel: number, config: LayerConfig): void;
90
}
91
```
92

93
### Dark Mode Support
94

95
```typescript { .api }
96
class ZRender {
97
  setDarkMode(darkMode: boolean): void;
98
  isDarkMode(): boolean;
99
}
100
```
101

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

104
### Animation Control
105

106
```typescript { .api }
107
class ZRender {
108
  clearAnimation(): void;
109
}
110
```
111

112
Stops and clears all running animations immediately.
113

114
### Event Handling
115

116
```typescript { .api }
117
class ZRender {
118
  on<Ctx>(eventName: ElementEventName, eventHandler: ElementEventCallback<Ctx>, context?: Ctx): this;
119
  on<Ctx>(eventName: string, eventHandler: Function, context?: Ctx): this;
120
  off(eventName?: string, eventHandler?: Function): void;
121
  trigger(eventName: string, event?: unknown): void;
122
  findHover(x: number, y: number): { target: Displayable; topTarget: Displayable } | undefined;
123
}
124
```
125

126
### Cursor Management
127

128
```typescript { .api }
129
class ZRender {
130
  setCursorStyle(cursorStyle: string): void;
131
}
132
```
133

134
Sets the default cursor style for the canvas.
135

136
### Hover Effects
137

138
```typescript { .api }
139
class ZRender {
140
  refreshHover(): void;
141
  refreshHoverImmediately(): void;
142
}
143
```
144

145
Controls hover state rendering for interactive elements.
146

147
## Configuration Types
148

149
```typescript { .api }
150
interface ZRenderInitOpt {
151
  renderer?: string;           // 'canvas' or 'svg'
152
  devicePixelRatio?: number;   // Device pixel ratio override
153
  width?: number | string;     // Canvas width ('auto', '100px', 400)
154
  height?: number | string;    // Canvas height
155
  useDirtyRect?: boolean;      // Enable dirty rectangle optimization
156
  useCoarsePointer?: 'auto' | boolean;  // Touch-friendly pointer handling
157
  pointerSize?: number;        // Pointer size for touch interfaces
158
  ssr?: boolean;              // Server-side rendering mode
159
}
160

161
interface LayerConfig {
162
  clearColor?: string;
163
  motionBlur?: boolean;
164
  lastFrameAlpha?: number;
165
}
166
```
167

168
## SSR Support
169

170
ZRender provides server-side rendering capabilities:
171

172
```typescript { .api }
173
function getElementSSRData(el: Element): ElementSSRData;
174
function registerSSRDataGetter<T>(getter: ElementSSRDataGetter<T>): void;
175

176
type ElementSSRData = Record<string, unknown>;
177
type ElementSSRDataGetter<T> = (el: Element) => Record<string, T>;
178
```
179

180
## Usage Examples
181

182
### Basic Initialization
183

184
```typescript
185
import { init } from "zrender";
186

187
// Create ZRender instance
188
const zr = init(document.getElementById('canvas'), {
189
  renderer: 'canvas',
190
  width: 800,
191
  height: 600
192
});
193

194
// Set background color
195
zr.setBackgroundColor('#f0f0f0');
196
```
197

198
### Advanced Configuration
199

200
```typescript
201
import { init } from "zrender";
202

203
const zr = init(document.getElementById('canvas'), {
204
  renderer: 'svg',
205
  useDirtyRect: true,
206
  useCoarsePointer: 'auto',
207
  devicePixelRatio: window.devicePixelRatio
208
});
209

210
// Configure performance settings
211
zr.setSleepAfterStill(10);
212

213
// Handle resize
214
window.addEventListener('resize', () => {
215
  zr.resize({
216
    width: window.innerWidth,
217
    height: window.innerHeight
218
  });
219
});
220

221
// Cleanup on page unload
222
window.addEventListener('beforeunload', () => {
223
  zr.dispose();
224
});
225
```
226

227
### Multi-instance Management
228

229
```typescript
230
import { init, getInstance, disposeAll } from "zrender";
231

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

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

239
// Cleanup all instances
240
disposeAll();
241
```