C

SvgExport

Show Usages
This class sets up an IRenderContext object for exporting the contents of a CanvasComponent (see createRenderContext).
Inheritance Hierarchy

Remarks

Also it provides ready-to-use methods to export the canvas contents to a standalone SVG.

See Also

Developer's Guide

Members

Show:

Constructors

SvgExport

(worldBounds: Rect, scale?: number)
Creates a new SvgExport instance for the given world bounds and scale.
When exporting content with a projection, the worldBounds are of little use. Instead, after creating the SvgExport a set of worldPoints should be set. The view coordinate bounds around those points then define the rectangular export area. Note that the projection property must also be set correctly for a projection to apply to the exported content.

Parameters

worldBounds: Rect
the bounds of the content to export, see worldBounds
scale?: number
the scale, see scale

Examples

Exports the contents of a GraphComponent to an SVG element
const exporter = new SvgExport(graphComponent.contentBounds)
// configure the export instance
exporter.encodeImagesBase64 = true
exporter.inlineSvgImages = true
// create the <svg> element
const element = exporter.exportSvg(graphComponent)

Properties

background

: Fill
Gets or sets the background color for the exported SVG.

For a value of null or TRANSPARENT, the exported SVG will have no background element. For all other values, the exported SVG will have a background element with corresponding fill.

The default value is null.

conversionfinal

copyDefsElements

: boolean
Gets or sets a value indicating whether children of the CanvasComponent's defs section that aren't known to the SvgDefsManager should be copied to the exported SVG.
The default value is false.
final

cssStyleSheet

: string
Gets or sets the CSS style sheet for the exported SVG.

If set to a non-empty string, this string will be added to the created SVG enclosed by a <style> element. If set to an empty string, no <style> element will be added to the created SVG. If set to null, the SvgExport will automatically extract all style sheets available to the document through the CSSStyleSheet API and filters all rules that don't match any elements in the created SVG.

Note that setting this property to null might affect the runtime performance of the export significantly. Copying and filtering the style rules has a runtime complexity of roughly the number of elements in the SVG times the number of CSS rules.

Note also, that all style sheets that cannot be accessed because of CORS policies are ignored.

The default value is "".

final

See Also

Developer's Guide

encodeImagesBase64

: boolean
Gets or sets a value indicating whether all external images should be inlined and encoded as Base64 data URIs in exportSvgAsync.

Override shouldEncodeImageBase64 to control the encoding and embedding for each image element separately.

Note that images with blob URLs are invalid outside the current document and should be Base64-encoded when using the exported SVG in a different context.

The default value is false.

final

See Also

Developer's Guide
API
exportSvgAsync, shouldEncodeImageBase64

ensureUniqueIds

: boolean
Gets or sets a value indicating whether the IDs of an inline SVG image should be scoped to ensure that they are unique for the given image.
This setting is enabled by default but affects only IDs of inlined images that do not contain an (optional) base IRI.
final

See Also

API
inlineSvgImages

inlineSvgImages

: boolean
Gets or sets a value indicating whether all SVG images should be inlined in the SVG element in exportSvgAsync.

Override shouldInlineSvgImage to control the inlining for each image separately.

The default value is false.

final

See Also

Developer's Guide
API
exportSvgAsync, shouldInlineSvgImage

margins

: Insets
Gets or sets the margins for the exported image.
The margins are added to the content. This means that an image with non-zero margins is larger than the export area even if the scale is 1.0. The margins are not scaled. They are interpreted to be in units (pixels for bitmaps) for the resulting image. The default is EMPTY.
conversionfinal

projection

: Matrix
Gets or sets the projection to apply to the exported image.

The Matrix must not have a translation component.

The default value is the identity Matrix.

When exporting content with a projection, the worldBounds are of little use. Instead, a set of worldPoints should be set. The view coordinate bounds around those points then defines the rectangular export area. Note that the projection property must also be set correctly for a projection to apply to the exported content.
final

rasterizeHtmlVisuals

: boolean
Gets or sets a value indicating whether HtmlVisuals should be converted to bitmap images in the resulting SVG.

In the SVG document returned by exportSvg, HTML visuals will be included as nested <foreignObject> elements. For better portability of the exported SVG document, HTML visuals can be rendered as bitmaps, instead. This is achieved by rendering the individual <foreignObject>s as SVG images to a <canvas> and replacing the <foreignObject>s with an SVG image with the exported data url.

The default value is false

In Safari/WebKit, there is a bug that causes incorrect display of <foreignObject> children. This only affects rendering but the SVG document is still correct.
final

See Also

Developer's Guide

scale

: number
Gets or sets the scale for the export.

A scale of 1 preserves the original size, a scale of 0.5 results in a target image with half the original size and so on.

This value has to be strictly greater than 0 and finite. Its default value is 1.0

final

strictMode

: boolean
Gets or sets a value indicating whether the export should fail when images could not be inlined or encoded to Base64 or if it should continue and replace those elements with a fallback image.
The default setting is false, i.e. a fallback image is used.
final

viewHeight

: number
readonly
Gets the resulting height of the target image with respect to export area, scale and margins.
This property only returns the correct image height when exporting a CanvasComponent without a projection.
readonlyfinal

viewWidth

: number
readonly
Gets the resulting width of the target image with respect to export area, scale, and margins.
This property only returns the correct image width when exporting a CanvasComponent without a projection.
readonlyfinal

worldBounds

: Rect
Gets or sets the bounds of the content to export in world coordinates.
Setting the worldPoints will overwrite the bounds with a rectangle which encloses all worldPoints.
When exporting content with a projection, the worldBounds are of little use. Instead, a set of worldPoints should be set. The view coordinate bounds around those points then defines the rectangular export area. Note that the projection property must also be set correctly for a projection to apply to the exported content.
conversion

See Also

Developer's Guide

worldPoints

: IEnumerable<Point>
Gets or sets the points in world coordinates that are enclosed in the exported area.
Setting the worldBounds will overwrite previously set points with the corners of the bounds.
conversionfinal

See Also

Developer's Guide

zoom

: number
Gets or sets the zoom property to use during the creation of the visualization.

In contrast to the scale property, which works on the output graphics, this property determines what zoom value is to be assumed on the canvas when creating the visual. This can affect the rendering of zoom-dependent visuals, especially level-of-detail rendering.

This value has to be strictly greater than 0. Its default value is 1.0

final

Methods

calculateScaleForHeight

(height: number): number
Calculates the value to set the scale to in order to achieve the given target height (without margins).
This method returns 1.0 if the export area height is zero or negative.
final

Parameters

height: number
the height of the target image

Return Value

number
the scale value to use

calculateScaleForWidth

(width: number): number
Calculates the value to set the scale to in order to achieve the given target width (without margins).
This method returns 1.0 if the export area width is zero or negative.
final

Parameters

width: number
the width of the target image

Return Value

number
the scale value to use

createClip

(): Rect
Returns a suitable clip to use for the visual for this exporter.

createRenderContext

(canvasComponent: CanvasComponent): IRenderContext
Returns an initialized IRenderContext and changes the given transform and the clip bounds such that a part of the given CanvasComponent instance can be exported to an image.

Parameters

canvasComponent: CanvasComponent
The CanvasComponent instance to export.

Return Value

IRenderContext
An IRenderContext to use.

createWorldToIntermediateTransform

(): Matrix
Returns a suitable transform to use for the visual to paint in the world coordinate system for this export.

exportSvg

(canvas: CanvasComponent): SVGSVGElement
Exports the contents of the CanvasComponent to a single, standalone SVG element.
The asynchronous version of this method, exportSvgAsync, is capable of encoding and inlining images that are embedded in the SVG.
final

Parameters

canvas: CanvasComponent
The canvas to be exported.

Return Value

SVGSVGElement
An SVG element with the canvas contents.

See Also

Developer's Guide

exportSvgAsync

(canvas: CanvasComponent, renderCompletionCallback?: function): Promise<SVGSVGElement>
Exports the contents of the CanvasComponent to a single, standalone SVG element.

In addition, images are inlined into the SVG using base64 encoding if encodeImagesBase64 is set to true. Image inlining can be controlled for each image individually by overwriting the predicate method shouldEncodeImageBase64. Note that images with blob URLs are invalid outside the current document and should be Base64-encoded when using the exported SVG in a different context.

SVG image elements are replaced with a copy of the referenced SVG element if inlineSvgImages is set to true. Image encoding can be controlled for each image individually by overwriting the predicate method shouldInlineSvgImage.

When rasterizeHtmlVisuals is enabled, HTML Visuals will be exported as bitmap images rather than wrapped in <foreignObject> elements.

The renderCompletionCallback parameter can be used to await any asynchronous rendering tasks to be finished before the optional post-processing steps are applied. This can be useful in case you are using styles that rely on frameworks like Angular or React, which render asynchronously by default, so you might need to wait for the framework to generate the final DOM structure.

final

Parameters

canvas: CanvasComponent
The canvas to be exported.
renderCompletionCallback?: function
An optional callback that will be called after the initial SVG is generated. The returned promise is awaited before any optional post-processing steps are applied.

Return Value

Promise<SVGSVGElement>
A Promise that will resolve to an SVG element with the canvas contents.

See Also

Developer's Guide

fixViewBoxAttribute

(importedSvg: Element, originalImage: any): Promise<void>
protected
Fixes the viewBox attribute on SVG images that have been inlined for export.
If an SVG image tag should be inlined, but doesn't have a viewBox attribute, the resulting element might be rendered with wrong dimensions. This specific implementation sets the viewBox attribute to the natural dimensions of the original image.
protected

Parameters

importedSvg: Element
The root element of the SVG file that's referenced by the original image element.
originalImage: any
The original image element that has been inlined.

Return Value

Promise<void>
A Promise that will be fulfilled once the viewBox attribute has been set.

See Also

API
inlineSvgImages, exportSvgAsync, shouldInlineSvgImage

prepareInlinedImage

(importedSvg: Element, originalImage: any): Element
protected
Prepares the imported SVG element before it is placed in the DOM as a replacement for the original image.
This method can be used to modify the element that is placed in the DOM. If the original image was an SVG <image> element, this implementation copies the values of the x, y, width, height, and preserveAspectRatio attributes from the original image element to the imported SVG element, and wraps the SVG element in a g element to support the transform of the original image. For HTML <img> elements, the style and class attributes are copied to a wrapping <div> element. If the original image element has an id attribute, it is also copied to the new container element.
protected

Parameters

importedSvg: Element
The root element of the SVG file that's referenced by the original image element.
originalImage: any
The original image element that will be replaced.

Return Value

Element
The element that's actually placed in the DOM as a replacement of the originalImage.

See Also

API
inlineSvgImages, exportSvgAsync, shouldInlineSvgImage

shouldEncodeImageBase64

(image: SVGImageElement): boolean
protected
Specifies whether or not a given external image should be encoded and inlined as a Base64 data-url in the resulting SVG document.
This implementation returns the value of encodeImagesBase64 for all values of image.
protected

Parameters

image: SVGImageElement
The image element that refers to the image to be encoded.

Return Value

boolean
Whether the given image should be encoded.

See Also

Developer's Guide

shouldInlineSvgImage

(image: SVGImageElement): boolean
protected
Specifies whether or not an SVG image should be inlined.
This implementation returns the value of inlineSvgImages for all values of image.
protected

Parameters

image: SVGImageElement
The image to be inlined.

Return Value

boolean
Whether the given image should be inlined.

See Also

Developer's Guide

Static Methods

encodeSvgDataUrl

(svgXml: string): string
static
Encodes the given SVG document as Data URI.
This method escapes non-Latin1 characters, does a base64 encoding, and returns the result as data URI.
static

Parameters

svgXml: string
A string containing the SVG document.

Return Value

string
A data URI of the SVG document.

exportSvgString

(svg: Element): string
static
Serializes the given SVG element to a string.
This method adds SVG namespace and xlink namespace declarations and replaces href with xlink:href.
static

Parameters

svg: Element
The SVG element to export.

Return Value

string
A string representation of the SVG.