DataItem – amCharts 4 Documentation

Type class

DataItem represents single element in data, for example a data point in a Serial Chart Series, e.g. a column.

DataItem defines relationship between structured data, required for specific chart type or task, and raw source data.

It also implements required calculations, updates related visual elements, etc.

@todo Description

Sources

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

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

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

Inheritance

DataItem extends BaseObjectEvents.

DataItem is extended by LegendDataItem, ChartDataItem, SeriesDataItem, AxisDataItem, NavigationBarDataItem.

Properties

adapter #	Type `Adapter` < `this`, `IDataItemAdapters` > Holds Adapter.
animations #	Type `Array` < `Animation` > A list of `Animations` objects currently mutating Data Item's values.
categories #	Type `object` An object containing categories.
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.
dataContext #	Type `Object` Sets to a reference to an original object from Component's data. A reference to an original object in Component's data, that this Data Item is derived from.
dates #	Type `object` An object containing dates.
depth #	Type `number` Depth of the Data Item. In nested data structures, like TreeMap, this indicates the level this data point is at, in relation to the parent Data Item.
events #	Type `EventDispatcher` < `AMEvent` < `this`, `IDataItemEvents` > > Inherited from `BaseObjectEvents` An `EventDispatcher` instance
hasProperties #	Type `boolean` Default `false` Indicates whether Data Item has any properties set. If it does not have any, the code can use this property to check whether they need to apply costly operation of re-applying properties, whenever Data Item-related element is redrawn, e.g. series.
hidden #	Type `boolean` Sets hidden flag for data item. Mostly used to initially hide data item. Returns `true` if this Data Item is currently hidden.
id #	Type `$type.Optional` < `string` > Inherited from `BaseObject` Sets the user-defined id of the element.
ignoreMinMax #	Type `boolean` Sets whether this data point should not be included in the scale and minimum/maximum calculations. Exclude from min/max calculations? E.g. some we may want to exclude a particular data point from influencing `ValueAxis` scale.
index #	Type `number` Data Item's position index in Component's data.
isHiding #	Type `boolean` Default `false` Indicates whether Data Item is currently animiting from visible to hidden state.
isTemplate #	Type `boolean` Default `false` Identifies if this object is a "template" and should not be treated as real object that is drawn or actually used in the chart.
locations #	Type `object` An object containing locations for the Data Item. A location is a position within date or category, or, in some other cases, where there is no single point but rather some period. Click here for info how data item locations work
opacity #	Type `number` Sets opacity for all Data Item's related elements (Sprites).
parent #	Type `$type.Optional` < `this` > When we are using a nested data structure, like for example in a TreeMap, this property points to a parent Data Item of this one.
properties #	Type `object` An object containing Data Item specific appearance properties in key-value pairs. Sometimes a single Data Item needs to apply different properties than the rest of the data `Series` it is part of. E.g. a single column, represented by a Data Item needs to be filled with a different color than the reset of the `ColumnSeries` it belongs to. That's where Data Item's `properties` come into play. Please note that you should set Data Item-specific properties using `setProperty()` method, rather than access `properties` object directly.
sprites #	Type `Sprite[]` Default `[]` A list of `Sprite` elements that are associated with this Data Item. E.g. an `Axis` Data Item has several separate elements associated with it, like `AxisTick`, `AxisLabel`, and `Grid`. Data Item keeps track of all of them, so it can toggle all related visual elements when it itself is toggled.
uid #	Type `string` Inherited from `BaseObject` Returns object's internal unique ID.
values #	Type `object` An object containing calculated values.
visible #	Type `boolean` Sets visibility of the Data Item. Returns `true` if this Data Item is currently visible.
workingLocations #	Type `object` Current working locations.
There are 5 inherited items currently hidden from this list.

Methods

animate( animationOptions: `IAnimationOptions[]` \| `IAnimationOptions`, duration: `number`, easing?: ( value: `number`) => `number` ) #	Returns `Animation` Creates and starts an `Animation` to interpolate (morph) Data Item's properties and/or values. `Animation`
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.
constructor() #	Returns `DataItem` Constructor @todo Adding events to disposers produces errors in some cases, which means that chart is using disposed Data Items which is not right
copyFrom( source: `this` ) #	Returns `void` Copies all properties and related data from different data item.
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` Destroys this object and all related data.
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.
getDate( name: `string` ) #	Returns `Date` Returns a Date value of the data field.
getDuration( duration?: `number` ) #	Returns `$type.Optional` < `number` > Returns a duration (ms) the Data Item should take to animate from one value to another. If the duration is not specified via parameter, this method will try to request a default duration from the related `Component`.
getValue( name: `string`, calculated?: `CalculatedValue` ) #	Returns `$type.Optional` < `number` > Returns a numeric value for specific data field. If `calculated` is not set, it will return a raw value, as it is in source data. If `calculated` is set, it will return a pre-calculated specific value.
getWorkingValue( name: `string` ) #	Returns `$type.Optional` < `number` > Returns a current working value for a specific data field. The actual value may differ from the one returned by `getValue()`. The latter returns static values from the data source. `getWorkingValue()` returns current value, which is usually different if Data Item is animating from one state to another.
hide( duration?: `number`, delay?: `number`, toValue?: `number`, fields?: `string[]` ) #	Returns `$type.Optional` < `Animation` > Hides the Data Item and related visual elements.
isDisposed() #	Returns `boolean` Inherited from `BaseObject` Returns if this object has been already been disposed.
setCalculatedValue( name: `string`, value: `number`, calculated: `CalculatedValue` ) #	Returns `void`
setCategory( name: `string`, value: `string` ) #	Returns `void` Sets a related category for this Data Item. @todo Review description
setDate( name: `string`, date: `Date`, duration?: `number` ) #	Returns `void` Sets Date value to a data field.
setLocation( name: `string`, value: `number`, duration?: `number`, delay?: `number` ) #	Returns `void` Sets a relative location for a data field. A location is always relative on a 0 to 1 scale, with 0 being beginning, 0.5 middle and 1 end. @todo Rewiew description
setProperty( name: `string`, value: `any` ) #	Returns `void` Sets a Data Item-specific visual properties to apply to related elements.
setValue( name: `string`, value: `number`, duration?: `number`, delay?: `number` ) #	Returns `void` Sets a numeric value for specific data field.
setVisibility( value: `boolean`, noChangeValues?: `boolean` ) #	Returns `void` Sets visibility of the Data Item.
setWorkingLocation( name: `string`, value: `number`, duration?: `number`, delay?: `number` ) #	Returns `$type.Optional` < `Animation` > Sets a current working location for a data field. @todo Rewiew description
setWorkingValue( name: `string`, value: `number`, duration?: `number`, delay?: `number` ) #	Returns `$type.Optional` < `Animation` > Set current working numeric value for a specific data field.
show( duration?: `number`, delay?: `number`, fields?: `string[]` ) #	Returns `$type.Optional` < `Animation` > Shows the Data Item and related visual elements.
There are 5 inherited items currently hidden from this list.

animate(

animationOptions: IAnimationOptions[] | IAnimationOptions,
duration: number,
easing?: ( value: number) => number

)

Returns Animation

Creates and starts an Animation to interpolate (morph) Data Item's properties and/or values.

Animation

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.

constructor()

Returns DataItem

Constructor

@todo Adding events to disposers produces errors in some cases, which means that chart is using disposed Data Items which is not right

copyFrom(

source: this

)

Returns void

Copies all properties and related data from different data item.

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

Destroys this object and all related data.

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.

getDate(

)

Returns Date

Returns a Date value of the data field.

getDuration(

duration?: number

)

Returns $type.Optional < number >

Returns a duration (ms) the Data Item should take to animate from one value to another.

If the duration is not specified via parameter, this method will try to request a default duration from the related Component.

getValue(

)

Returns $type.Optional < number >

Returns a numeric value for specific data field.

If calculated is not set, it will return a raw value, as it is in source data.

If calculated is set, it will return a pre-calculated specific value.

getWorkingValue(

)

Returns $type.Optional < number >

Returns a current working value for a specific data field.

The actual value may differ from the one returned by getValue(). The latter returns static values from the data source.

getWorkingValue() returns current value, which is usually different if Data Item is animating from one state to another.

hide(

duration?: number,
delay?: number,
toValue?: number,
fields?: string[]

)

Returns $type.Optional < Animation >

Hides the Data Item and related visual elements.

isDisposed()

Returns boolean

Inherited from BaseObject

Returns if this object has been already been disposed.

setCalculatedValue(

)

Returns void

setCategory(

)

Returns void

Sets a related category for this Data Item.

@todo Review description

setDate(

)

Returns void

Sets Date value to a data field.

setLocation(

)

Returns void

Sets a relative location for a data field.

A location is always relative on a 0 to 1 scale, with 0 being beginning, 0.5 middle and 1 end.

@todo Rewiew description

setProperty(

)

Returns void

Sets a Data Item-specific visual properties to apply to related elements.

setValue(

)

Returns void

Sets a numeric value for specific data field.

setVisibility(

value: boolean,
noChangeValues?: boolean

)

Returns void

Sets visibility of the Data Item.

setWorkingLocation(

)

Returns $type.Optional < Animation >

Sets a current working location for a data field.

@todo Rewiew description

setWorkingValue(

)

Returns $type.Optional < Animation >

Set current working numeric value for a specific data field.

show(

duration?: number,
delay?: number,
fields?: string[]

)

Returns $type.Optional < Animation >

Shows the Data Item and related visual elements.

There are 5 inherited items currently hidden from this list.

Events

#calculatedvaluechanged	Param { property: `string`, type: `"calculatedvaluechanged"`, target: `this` } Invoked when the calculated value has changed
#locationchanged	Param { property: `string`, type: `"locationchanged"`, target: `this` } Invoked when the location of Data Item changes
#propertychanged	Param { property: `string`, value: `any`, type: `"propertychanged"`, target: `this` } Invoked when a property of the Data Item changes
#valuechanged	Param { property: `string`, type: `"valuechanged"`, target: `this` } Invoked when the value is changed
#visibilitychanged	Param { visible: `boolean`, type: `"visibilitychanged"`, target: `this` } Invoked when the visibility of the Data Item changes, i.e. Series is hidden
#workinglocationchanged	Param { property: `string`, type: `"workinglocationchanged"`, target: `this` } Invoked when working location of Data Item changes
#workingvaluechanged	Param { property: `string`, type: `"workingvaluechanged"`, target: `this` } Invoked when the internal/intermediate value has changed

Adapters

#date	Param { date: `Date`, field: `string` }
#duration	Param `number`
#value	Param { field: `string`, value: `number` }
#workingValue	Param { field: `string`, workingValue: `number` }