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");

Sources

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

TypeScript
JavaScript

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

/**
 * 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.

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.

More info: Exporting Charts: changing order and names of columns for examples and details

dataFieldsOrder

Type string[]Default []Since 4.9.7

Holds an array of data field names. If set, exported data fields will try to maintain this order.

If not set (default), the export will try to maintain the same order as in source data, or as in dataFields (if set).

dateFields

Type List <string>

A list of fields that hold date values.

dateFormat

Type $type.Optional <string | DateTimeFormatOptions>

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

dateFormatter

Type DateFormatter

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 DurationFormatter

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

extraSprites

Type Array <Sprite | IExportCanvas>Since 4.2.0

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);

IMPORTANT: This setting is ignored when exporting to SVG format.

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".

formatOptions

Type Dictionary <string, ExportOptions>Since 4.9.12

A Dictionary object containing format-specific options.

May be used to change specific option for the format:

chart.exporting.formatOptions.getKey("csv").disabled = true;

chart.exporting.formatOptions.getKey("csv").disabled = true;

{
  // ...
  "exporting": {
    // ...
    "formatOptions": {
      "csv": {
        "disabled": true
      }
    }
  }
}

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": {}
  }
}

numberFields

Type List <string>Since 4.5.15

A list of fields that hold number values.

numberFormat

Type $type.Optional <string>Since 4.5.15

A number format to use for exporting dates. Will use NumberFormatter format if not set.

numberFormatter

Type NumberFormatterSince 4.5.15

A NumberFormatter to use when formatting dates when exporting data.

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 numberDefault 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.

useRetina

Type booleanDefault 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.

useSimplifiedExport

Type booleanDefault trueSince 4.2.5

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.

useWebFonts

Type booleanDefault 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.

validateSprites

Type Array <Sprite>Since 4.6.8

An array of Sprite elements that need to be valid before export commences.

If any of those elements is not completely ready when export is triggered, the export will wait until they are (their validated event triggers) before going through with the export opertaion.

This is useful if you need to modify chart appearance for the export.

E.g.:

// Add watermark
let watermark = chart.createChild(am4core.Label);
watermark.text = "Copyright (C) 2019";
watermark.disabled = true;

// Add watermark to validated sprites
chart.exporting.validateSprites.push(watermark);

// Enable watermark on export
chart.exporting.events.on("exportstarted", function(ev) {
  watermark.disabled = false;
});

// Disable watermark when export finishes
chart.exporting.events.on("exportfinished", function(ev) {
  watermark.disabled = true;
});

// Add watermark
var watermark = chart.createChild(am4core.Label);
watermark.text = "Copyright (C) 2019";
watermark.disabled = true;

// Add watermark to validated sprites
chart.exporting.validateSprites.push(watermark);

// Enable watermark on export
chart.exporting.events.on("exportstarted", function(ev) {
  watermark.disabled = false;
});

// Disable watermark when export finishes
chart.exporting.events.on("exportfinished", function(ev) {
  watermark.disabled = true;
});

webFontFilter

Type RegExpSince 4.10.17

A regular expression that will be matched against each URL of an external font being loaded. Font will only be loaded of regular expression matches.

Has no effect of useWebFonts is set to false.

chart.exporting.webFontFilter = /pacifico|roboto/;

chart.exporting.webFontFilter = /pacifico|roboto/;

{
  // ...
  "exporting": {
    // ...
    "webFontFilter": /pacifico|roboto/
  }
}

5 inherited items

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 objectInherited 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.

events

Type EventDispatcher <AMEvent <this, IBaseObjectEvents>>Inherited from BaseObjectEvents

An EventDispatcher instance

id

Type $type.Optional <string>Inherited from BaseObject

Sets the user-defined id of the element.

uid

Type stringInherited from BaseObject

Returns object's internal unique ID.

Methods

constructor(container: HTMLElement)

Returns Export

Constructor

download(uri: string, fileName: string, addBOM: boolean)

Returns Promise <boolean>

Triggers download of the file.

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

downloadSupport()

Returns boolean

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

export(type: Key, options?: IExportOptions[""])

Returns Promise <boolean>

Initiates export procedure.

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.

getCSV(type: "csv", options?: IExportCSVOptions, encodeURI: boolean)

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.

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.

getFormatOptions(type: Key)

Returns IExportOptions[""]

Returns current options for a format.

getHTML(type: "html", options?: IExportHTMLOptions, encodeURI: boolean)

Returns Promise <string>Since 4.7.0

Returns chart's data formatted as HTML table.

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

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, encodeURI: boolean)

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.

getPDF(type: "pdf" | "pdfdata", 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.

getPDFData(type: "pdf", options?: IExportPDFOptions)

Returns Promise <any>Since 4.7.0

Returns chart's data formatted suitable for PDF export (pdfmake).

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

getPrint(type: string, options?: IExportPrintOptions)

Returns Promise <string>

Requests a Print of the chart.

getSVG(type: "svg", options?: IExportSVGOptions, encodeURI: boolean)

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.

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.

setFormatOptions(type: Key, options: IExportOptions[""])

Returns void

Sets options for a format.

typeSupported(type: Key)

Returns boolean

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

7 inherited items

clone(cloneId?: string)

Returns thisInherited 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 voidInherited from BaseObjectEvents

Copies all parameters from another Sprite.

dispatch(eventType: Key, data?: any)

Returns voidInherited 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 voidInherited from BaseObjectEvents

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

dispose()

Returns voidInherited from Validatable

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.

isDisposed()

Returns booleanInherited from BaseObject

Returns if this object has been already been disposed.

Events

error

Param { type: "error", target: Export } & ExportOperation

Invoked when export operation encounters error.

exportfinished

Param { type: "exportfinished", target: Export } & ExportOperation

Invoked when export operation finishes.

exportstarted

Param { type: "exportstarted", target: Export } & ExportOperation

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: Export } & ExportOperation

Invoked when export operation times out.

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

inited

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

Invoked when Export initializes.

menucreated

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

Invoked when Export menu is created.

Adapters

backgroundColor: Param { backgroundColor: $type.Optional <Color> }
charset: Param { charset: string, options: IExportOptions[""], type: Keys }
container: Param { container: HTMLElement }
contentType: Param { contentType: string, type: Keys }
data: Param { data: Array <any> }
dataFieldName: Param { field: string, name: string }
dataFields: Param { dataFields: any }
dataFieldsOrder: Param { dataFieldsOrder: string[], format: string }
dateFields: Param { dateFields: any }
dateFormat: Param { dateFormat: $type.Optional <string | DateTimeFormatOptions> }
dateFormatter: Param { dateFormatter: DateFormatter }
durationFields: Param { durationFields: any }
durationFormat: Param { durationFormat: $type.Optional <string> }
durationFormatter: Param { durationFormatter: DurationFormatter }
exportFunction: Param { func: (type: Key, options: IExportOptions[""]) => Promise <any>, options: IExportOptions[""], type: Keys }
extraSprites: Param { extraSprites: Array <Sprite | IExportCanvas> }
filePrefix: Param { filePrefix: string }
formatDataFields: Param { dataFields: any, format: string }
getCSV: Param { data: string, options: IExportOptions[""] }
getExcel: Param { data: string, options: IExportOptions[""] }
getHTML: Param { data: string, options: IExportOptions[""] }
getJSON: Param { data: string, options: IExportOptions[""] }
getSVG: Param { data: string, options: IExportOptions[""] }
isDateField: Param { field: string, isDateField: boolean }
isDurationField: Param { field: string, isDurationField: boolean }
isNumberField: Param { field: string, isNumberField: boolean }
normalizeSVG: Param { data: string, options: IExportOptions[""] }
numberFields: Param { numberFields: any }
numberFormat: Param { numberFormat: $type.Optional <string> }
numberFormatter: Param { numberFormatter: NumberFormatter }
options: Param { options: IExportOptions[""], type: Keys }
pdfmakeDocument: Param { doc: any, options: IExportOptions[""] }
pdfmakeTable: Param { options: IExportOptions[""], table: any }
sprite: Param { sprite: Sprite }
supported: Param { options: IExportOptions[""], supported: boolean, type: Keys }
svgToDataURI: Param { data: string, options: IExportOptions[""] }
timeoutMessage: Param { message: string }
title: Param { options: IExportOptions[""], title: $type.Optional <string> }
validateSprites: Param { validateSprites: Array <Sprite> }
xlsxSheetName: Param { name: string, xlsx: any }
xlsxWorkbook: Param { options: IExportOptions[""], workbook: any, xlsx: any }Since 4.9.28
xlsxWorkbookOptions: Param { options: any, xlsx: any }