repository·master·Indexed 27 days ago
https://github.com/ecomfe/zrenderA lightweight 2D graphics library serving as the underlying drawing engine for Apache ECharts. Version 6.1.0 provides capabilities for web-based visualizations, including a state system for Displayable objects, incremental rendering for large datasets, and utilities for SVG virtual node creation and serialization.
Only zrender.js is officially exported for user consumption. While other entries in the package.json exports field are accessible for backward compatibility, they are considered internal and their usage is not recommended.
When importing, ensure you use the official entry point to avoid issues with internal file access.
For elements that need to render incrementally (like a very large path), use the incremental property and the beforeBrush hook. Setting notClear: true can prevent the incremental layer from clearing even when a redraw is triggered, allowing you to manage the drawing index manually.
Typical Pattern:
incremental to a non-zero value.beforeBrush(param), check param.contentRetained. If false, reset your internal drawing index.notClear = true to retain the existing canvas content.class LargePath extends Path {
reset() {
this._idx = 0;
this.notClear = false;
}
beforeBrush(param: BeforeBrushParam) {
if (!param.contentRetained) { this.reset(); }
}
buildPath() {
for (this._idx; this._idx < this.shape.points.length; this._idx++) {
// draw logic here
}
this.notClear = true;
}
}v5.5.0, ZRender uses `Displayable objects support a state system to manage different visual configurations (e.g., 'hover' or 'pressed').
getState(stateName: string): Retrieves the state by name.ensureState(stateName: string): Ensures the state exists and returns it.states: A dictionary containing all defined states.stateProxy(stateName: string): A proxy function to access states.You can animate changes to an element's style using the animate() or animateStyle() methods. animateStyle(loop?: boolean) is a convenient alias for animate('style', loop).
By default, the following common style properties are animatable:
shadowBlurshadowOffsetXshadowOffsetYshadowColoropacityUse getCssString to generate a CSS string wrapped in a <![CDATA[ block from provided selector and animation nodes. This is typically used for embedding styles within an SVG.
Parameters:
selectorNodes: Record<string, CSSSelectorVNode> mapping class names to attribute sets.animationNodes: Record<string, CSSAnimationVNode> mapping animation names to keyframe percentages and their respective styles.opts: { newline?: boolean }ZRender provides utilities to create Virtual DOM nodes (SVGVNode) for SVG rendering.
createVNode(tag, key, attrs, children, text): Creates a generic virtual node.createSVGVNode(width, height, children, useViewBox): A specialized helper to create the root <svg> element with standard attributes like xmlns and version already configured.SVGVNode structure:
tag: stringattrs: Record<string, string | number | undefined | boolean>children: SVGVNode[] (optional)text: string (optional)key: stringDisplayable objects use a style property to define visual attributes. You can set styles using setStyle() or by passing a style object to the constructor. Common style properties include shadowBlur, shadowOffsetX, shadowOffsetY, shadowColor, opacity, and blend (the CSS globalCompositeOperation).
To ensure a style object has all necessary default values, use createStyle().
A BrushScope is a container used during the SVG generation process to manage caches (shadows, gradients, patterns, clipPaths), definitions (defs), and CSS nodes/animations. Use createBrushScope(zrId) to initialize a new scope.
Key properties in BrushScope:
defs: Record<string, SVGVNode>cssNodes: Record<string, CSSSelectorVNode>cssAnims: Record<string, Record<string, Record<string, string>>>shadowCache, gradientCache, patternCache, clipPathCache: Caches for reusable SVG definitions.The vNodeToString function converts an SVGVNode tree into a raw SVG string. This is useful for serialization or SSR (Server Side Rendering).
Options:
newline: boolean (default false). If true, inserts newlines between elements.When working with text elements, you can specify alignment using the following types:
TextVerticalAlign: 'top' | 'middle' | 'bottom'TextAlign: 'left' | 'center' | 'right'FontWeight: 'normal' | 'bold' | 'bolder' | 'lighter' | numberFontStyle: 'normal' | 'italic' | 'oblique'The following properties are available on Displayable objects to control rendering and interaction:
| Property | Type | Description |
|---|---|---|
style | Dictionary<any> | Visual attributes (opacity, shadow, etc.) |
zlevel | number | Determines which layer canvas the object is drawn in |
z | number | Z-order within a layer |
z2 | number | Secondary Z-order |
invisible | boolean | If true, the object is not drawn but can still trigger mouse events |
culling | boolean | If true, enables culling (skipping drawing if outside view) |
cursor | string | Mouse cursor style when hovered |
rectHover | boolean | If true, the hover area is the bounding rectangle |
incremental | IncrementalIdCompat | Configuration for incremental rendering |
ignoreCoarsePointer | boolean | Prevents increasing to target size |
batch | boolean | Batching flag |
progressive | boolean | Progressive rendering flag |
notClear | boolean | Used for incremental elements to retain layer content |