Export

Type class

Export allows downloading of current snapshot of the chart as an image, PDF, or its data in various formats.

The export functionality is enabled by default in charts and is accessible via API or optional export menu.

To enable menu, simply access export's menu property. E.g.:

chart.exporting.menu = new am4core.ExportMenu();
chart.exporting.menu = new am4core.ExportMenu();
{
  // ...
  "exporting": {
    "menu": {}
  }
}

To export via API, use export() method:

chart.exporting.export(type, [options]);
chart.exporting.export(type, [options]);

E.g.:

chart.exporting.export("png");
chart.exporting.export("png");

@todo Better loading indicator?
@todo Implement multiplier option
@todo Handling of hanged exports

Sources

Export can be used (imported) via one of the following packages.

// Export is available in all of the following modules.
// You only need to import one of them.

/**
 * --------------------------------------------------------
 * Import from: "core.ts"
 * Use like: am4core.Export
 * --------------------------------------------------------
 */
import * as am4core from "@amcharts/amcharts4/core";

// Export is available in all of the following modules.
// You only need to import one of them.

/**
 * --------------------------------------------------------
 * Include via: <script src="core.js"></script>
 * Access items like: am4core.Export
 * --------------------------------------------------------
 */

Inheritance

Export extends Validatable.

Export is not extended by any other symbol.

Properties

adapter
#

Type Adapter < Export, IExportAdapters >

Default new Adapter<Export,
IExportAdapters>(this)

Adapter.

backgroundColor
#

Type $type.Optional < Color >

A background color to be used for exported images. If set, this will override the automatically acquired background color.

clonedFrom
#

Type $type.Optional < this >

Inherited from BaseObject

Reference to the original object this object was cloned from. We need to keep this so we can disassociate it from source object when this object is disposed.

config
#

Type object

Inherited from BaseObject

Use this property to set JSON-based config. When set, triggers processing routine, which will go through all properties, and try to apply values, create instances, etc.

Use this with caution, as it is a time-consuming process. It's used for initialchart setup only, not routine operations.

container
#

Type HTMLElement

A reference to a container to be used to place ExportMenu in.

data
#

Type any

Data to export.

dataFields
#

Type any

Data fields in { field: fieldName } format. Those are used for exporting in data formats to name the columns.

dateFields
#

Type List < string >

A list of fields that hold date values.

dateFormat
#

Type $type.Optional < string >

A date format to use for exporting dates. Will use DateFormatter format if not set.

dateFormatter
#

Type any

A DateFormatter to use when formatting dates when exporting data.

durationFields
#

Type List < string >

A list of fields that hold duration values.

durationFormat
#

Type $type.Optional < string >

A format to use when formatting values from durationFields.

Will use DurationFormatter format if not set.

durationFormatter
#

Type any

A DurationFormatter to use when formatting duration values when exporting data.

events
#

Type EventDispatcher < AMEvent < this, IExportEvents > >

Default new EventDispatcher()

Inherited from BaseObjectEvents

An EventDispatcher instance

extraSprites
#

Type Array < Sprite | IExportCanvas >

An array of extra Sprite] elements to include in export.

It can be used to export any external elements, or even other charts.

E.g.:

chart.exporting.extraSprites.push(chart2);
chart.exporting.extraSprites.push(chart2);

@since 4.2.0

filePrefix
#

Type string

A file prefix to be used for all exported formats.

Export will apply format-related extension to it. E.g. if this is set to "myExport", the file name of the PNG exported image will be "myExport.png".

id
#

Type $type.Optional < string >

Inherited from BaseObject

Sets the user-defined id of the element.

language
#

Type Language

A [[Language instance to be used for translations.

menu
#

Type $type.Optional < ExportMenu >

An instance of ExportMenu.

To add an export menu to a chart, set this to a new instance of ExportMenu.

chart.exporting.menu = new am4core.ExportMenu();
chart.exporting.menu = new am4core.ExportMenu();
{
  // ...
  "exporting": {
    "menu": {}
  }
}

preloader
#

Type Preloader

Returns a an instance of Preloader associated with the Sprite being exported.

sprite
#

Type Sprite

A reference to Sprite to export. Can be any Sprite, including some internal elements.

timeoutDelay
#

Type number

Default 2000

If export operation takes longer than milliseconds in this second, we will show a modal saying export operation took longer than expected.

title
#

Type $type.Optional < string >

A title to be used when printing.

uid
#

Type string

Inherited from BaseObject

Returns object's internal unique ID.

useRetina
#

Type boolean

Default true

Many modern displays have use more actual pixels per displayed pixel. This results in sharper images on screen. Unfortunately, when exported to a bitmap image of the sam width/height size it will lose those extra pixels, resulting in somewhat blurry image.

This is why we are going to export images larger than they are, so that we don't lose any details.

If you'd rather export images without change in size, set this to false.

@default true

useSimplifiedExport
#

Type boolean

Default true

By default Export will try to use built-in method for transforming chart into an image for download, then fallback to external library (canvg) for conversion if failed.

Setting this to false will force use of external library for all export operations.

It might be useful to turn off simplified export if you are using strict content security policies, that disallow images with blobs as their source.

@default true
@since 4.2.5

useWebFonts
#

Type boolean

Default true

If you are using web fonts (such as Google Fonts), your chart might be using them as well.

Normally, exporting to image will require to download these fonts so the are carried over to exported image.

This setting can be used to disable or enable this functionality.

@default true

There are 5 inherited items currently hidden from this list.

Methods

constructor(

container: HTMLElement

)

#

Returns Export

Constructor

clone(

cloneId?: string

)

#

Returns this

Inherited from BaseObject

Makes a copy of this object and returns the clone. Try to avoid cloning complex objects like chart, create new instances if you need them.

copyFrom(

source: this

)

#

Returns void

Inherited from BaseObjectEvents

Copies all parameters from another Sprite.

dispatch(

eventType: Key,
data?: any

)

#

Returns void

Inherited from BaseObjectEvents

Dispatches an event using own event dispatcher. Will automatically populate event data object with event type and target (this element).

It also checks if there are any handlers registered for this sepecific event.

dispatchImmediately(

eventType: Key,
data?: any

)

#

Returns void

Inherited from BaseObjectEvents

Works like dispatch, except event is triggered immediately, without waiting for the next frame cycle.

dispose()

#

Returns void

Inherited from BaseObject

Destroys this object and all related data.

download(

uri: string,
fileName: string

)

#

Returns Promise < boolean >

Triggers download of the file.

This is an asynchronous function. Check the description of getImage() for description and example usage.

@async

downloadSupport()

#

Returns boolean

Returns true if browser has any supported methods to trigger download of a binary file.

export(

type: Key,
options?: IExportOptions[Key]

)

#

Returns Promise < boolean >

Initiates export procedure.

@async

getCSV(

type: "csv",
options?: IExportCSVOptions

)

#

Returns Promise < string >

Returns chart's data formatted as CSV.

This is an asynchronous function. Check the description of getImage() for description and example usage.

@async

getCanvas(

options?: IExportImageOptions

)

#

Returns Promise < HTMLCanvasElement >

Returns canvas representation of the Sprite.

getCanvasAdvanced(

options?: IExportImageOptions

)

#

Returns Promise < HTMLCanvasElement >

Returns canvas representation of the Sprite using canvg.

getContentType(

type: Key

)

#

Returns string

Returns proper content type for the export type.

getCurrentThemes()

#

Returns ITheme[]

Inherited from BaseObject

Returns a list of themes that should be applied to this element. It could either be a list of themes set explicitly on this element, or system-wide.

getExcel(

type: "xlsx",
options?: IExportExcelOptions

)

#

Returns Promise < string >

Returns an Excel file of chart's data.

This is an asynchronous function. Check the description of getImage() for description and example usage.

@async
@todo Handle dates
@todo Support for multi-sheet

getFormatOptions(

type: Key

)

#

Returns IExportOptions[Key]

Returns current options for a format.

getImage(

type: Key,
options?: IExportImageOptions,
includeExtras?: boolean

)

#

Returns Promise < string >

Produces image output from the element.

Converts to a Canvas first, then produces an image to download.

This is an asynchronous function. Rather than returning a result, it returns a Promise.

You can use await notion from other async functions, or then() anywhere else.

let img;

// Async
img = await chart.exporting.getImage( "png" );

// Sync
chart.exporting.getImage( "png" ).then( ( data ) => {
  img = data;
} );
var img;
chart.exporting.getImage( "png" ).then( ( data ) => {
  img = data;
} );

getImageAdvanced(

type: imageFormats,
options?: IExportImageOptions,
includeExtras?: boolean

)

#

Returns Promise < string >

Tries to dynamically load canvg.js and export an image using its functions.

This is an asynchronous function. Check the description of getImage() for description and example usage.

getJSON(

type: "json",
options?: IExportJSONOptions

)

#

Returns Promise < string >

Returns chart's data in JSON format.

This is an asynchronous function. Check the description of getImage() for description and example usage.

@async

getPDF(

type: "pdf",
options?: IExportPDFOptions

)

#

Returns Promise < string >

Returns a PDF containing chart image.

This is an asynchronous function. Check the description of getImage() for description and example usage.

@async
@todo Account for header when calculating vertical fit

getPrint(

type: string,
options?: IExportPrintOptions

)

#

Returns Promise < string >

Requests a Print of the chart.

@async

getSVG(

type: "svg",
options?: IExportSVGOptions

)

#

Returns Promise < string >

Returns an SVG representation of the chart.

This is an asynchronous function. Check the description of getImage() for description and example usage.

handleDataUpdated()

#

Returns void

isDisposed()

#

Returns boolean

Inherited from BaseObject

Returns if this object has been already been disposed.

print(

data: string,
options?: IExportPrintOptions,
title?: string

)

#

Returns Promise < boolean >

Initiates print of the chart.

This is an asynchronous function. Check the description of getImage() for description and example usage.

@async

setFormatOptions(

type: Key,
options: IExportOptions[Key]

)

#

Returns void

Sets options for a format.

typeSupported(

type: Key

)

#

Returns boolean

Checks if this specific menu item type is supported by current system.

There are 7 inherited items currently hidden from this list.

Events

#error

Param { type: "error",
  target: this }

Invoked when export operation encounters error.

#exportfinished

Param { type: "exportfinished",
  target: this }

Invoked when export operation finishes.

#exportstarted

Param { type: "exportstarted",
  target: this }

Invoked when the Export starts export procedure.

You can use event handlers here to modify config before actual export starts.

#exporttimedout

Param { type: "exporttimedout",
  target: this }

Invoked when export operation times out.

Use Export's timeoutDelay setting to set timeout. (default: 2000ms)

#inited

Param { type: "inited",
  target: this }

Invoked when Export initializes.

#menucreated

Param { type: "menucreated",
  target: this }

Invoked when Export menu is created.

Adapters

#backgroundColor

Param object

#charset

Param object

#container

Param object

#contentType

Param object

#data

Param object

#dataFieldName

Param object

#dataFields

Param object

#dateFields

Param object

#dateFormat

Param object

#dateFormatter

Param object

#durationFields

Param object

#durationFormat

Param object

#durationFormatter

Param object

#exportFunction

Param object

#extraSprites

Param object

#filePrefix

Param object

#getCSV

Param object

#getExcel

Param object

#getJSON

Param object

#getSVG

Param object

#isDateField

Param object

#isDurationField

Param object

#normalizeSVG

Param object

#options

Param object

#pdfmakeDocument

Param object

#sprite

Param object

#supported

Param object

#svgToDataURI

Param object

#timeoutMessage

Param object

#title

Param object

#xlsxSheetName

Param object

#xlsxWorkbookOptions

Param object