@progress/kendo-angular-charts
Version:
Kendo UI Charts for Angular - A comprehensive package for creating beautiful and interactive data visualization. Every chart type, stock charts, and sparklines are included.
526 lines (525 loc) • 25.7 kB
TypeScript
/**-----------------------------------------------------------------------------------------
* Copyright © 2025 Progress Software Corporation. All rights reserved.
* Licensed under commercial license. See LICENSE.md in the project root for more information
*-------------------------------------------------------------------------------------------*/
import { drawing } from '@progress/kendo-drawing';
import { SeriesErrorBars } from './series-item/error-bars.interface';
import { SeriesExtremes } from './series-item/extremes.interface';
import { SeriesHighlight } from './series-item/highlight.interface';
import { SeriesLabels } from './series-item/labels.interface';
import { SeriesMarkers } from './series-item/markers.interface';
import { SeriesNotes } from './series-item/notes.interface';
import { SeriesOutliers } from './series-item/outliers.interface';
import { SeriesTooltip } from './series-item/tooltip.interface';
import { Border, BulletTarget, DashType, LabelConnectors, LegendItem, SeriesTrendline } from '../common/property-types';
import { Margin, NegativeBubbleValues, Overlay, SeriesLine, SeriesType, SeriesWhiskers } from '../common/property-types';
import { LineStyle, SeriesStack, SeriesVisualArgs } from '../common/property-types';
import { SeriesMedian } from '../field-types/series-median.interface';
import { SeriesPattern } from '@progress/kendo-charts';
/**
* Represents the configuration options of the series.
*/
export interface Series {
/**
* Specifies the aggregate function for the date series.
* Apply this function when a category (year, month, or other) contains two or more points.
* The Chart displays the return value of the function instead of the individual points.
* This option is supported for Categorical Chart axis only.
*
* Aggregate functions support the following values:
* - `"avg"`—Calculates the average of all values for the date period.
* - `"count"`—Counts the number of values for the date period.
* - `"max"`—Finds the highest value for the date period.
* - `"min"`—Finds the lowest value for the date period.
* - `"sum"`—Sums all values for the date period. Uses `0` when no data points are defined.
* - `"sumOrNull"`—Sums all values for the date period. Uses `null` when no data points are
* defined.
* - `"first"`—Uses the first value.
* - function (values, series, dataItems, category)—A user-defined aggregate function that returns a single
* value or a data item.
* - object (compound aggregate)—Applies to the Candlestick, Box Plot, and OHLC series.
* Sets the aggregate for each data item field.
*/
aggregate?: any;
/**
* Determines whether the Chart automatically scales down to fit the content area.
* Applicable for the Pie and Donut series. ([See example](slug:donut_seriestypes_charts#displaying-labels-in-angular-donut-chart))
*/
autoFit?: boolean;
/**
* Specifies the name of the value axis.
* This option is supported for Scatter plots. For more information on Scatter plots, refer to
* [`xAxis`]({% slug api_charts_xaxis %}) and [`yAxis`]({% slug api_charts_yaxis %}).
*/
axis?: string;
/**
* Specifies the border of the Chart series.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to
* `"bar"`, `"column"`, `"donut"`, `"pie"`, `"bubble"`, `"boxPlot"`, `"candlestick"`, or `"ohlc"`.
*/
border?: Border;
/**
* Specifies the name of the category axis that the series uses.
* If you do not specify a [`categoryAxis`]({% slug api_charts_categoryaxis %}), the Chart uses the first axis.
*/
categoryAxis?: string;
/**
* Specifies the data item field which contains the category name or date.
* When the category is a date, renders the points in chronological order.
*/
categoryField?: string;
/**
* Specifies the data field that contains the `close` value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"candlestick"` or `"ohlc"`.
*/
closeField?: string;
/**
* Specifies the series base color.
*
* Accepts CSS color string (including HEX and RGB) and function (point). The function, which is user-defined and evaluated for each point, assumes the default series color when it returns `undefined`.
*/
color?: any;
/**
* Specifies the data item field which contains the series color.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type)
* is set to `"bar"`, `"column"`, `"rangeBar"`, `"rangeColumn"`, `"bubble"`, `"donut"`, `"pie"`, `"candlestick"`,
* `"ohlc"`, or `"waterfall"`.
*/
colorField?: string;
/**
* Specifies the label connectors options.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"donut"` or `"pie"` and
* [`series.labels.visible`]({% slug api_charts_serieslabels %}#toc-visible) is set to `true`.
*/
connectors?: LabelConnectors;
/**
* Specifies the data item field which contains the current value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"bullet"` or `"verticalBullet"`.
*/
currentField?: string;
/**
* Specifies the dash type of line Chart.
* Use this option only when the [`series.type`]({% slug api_charts_series %}#toc-type) option is set to `"line"`.
*/
dashType?: DashType;
/**
* Specifies the array of data items which represent the series data.
*
* You can set it to:
* - Array of objects. Each point is bound to the field specified through the [`series.field`]({% slug api_charts_series %}#toc-field) option.
* - Array of numbers. Supported when the [`series.type`]({% slug api_charts_series %}#toc-type) option is set to `"area"`, `"bar"`, `"column"`, `"donut"`, `"pie"`, `"line"`, or `"waterfall"`.
* - Array of arrays of numbers. Supported when the [`series.type`]({% slug api_charts_series %}#toc-type) option is set to `"bubble"`, `"scatter"`, `"scatterLine"`, `"ohlc"`, `"polar"`, `"rangeBar"`, or `"rangeArea"`.
*
* Bubble series need arrays of three values—X value, Y value, and Size value—for example, `[1, 1, 10]`.
*
* Scatter and ScatterLine series need arrays of two values—X value and Y value.
*
* OHLC and Candlestick series need arrays of four values—open, high, low, and close.
*
* RangeBar and RangeArea series need arrays of two values—the from and to value.
*/
data?: any[];
/**
* Specifies the series color when the open value is greater than the close value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"candlestick"`.
*/
downColor?: string;
/**
* Specifies the data field which contains the color that applies when the `open` value is greater than the `close` value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"candlestick"`.
*/
downColorField?: string;
/**
* Specifies the data field which contains the value to use to [drill down]({% slug drilldown_chart_charts %}) into detailed data for the point.
*/
drilldownField?: string;
/**
* Determines whether the segments have the same height.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"funnel"` or `"pyramid"`.
* Setting it to `false` makes all segments have the same height.
* Setting it to `true` bases the height of each segment on its value.
*/
dynamicHeight?: boolean;
/**
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"funnel"`.
* Setting it to `true` makes the ratio of the bases of each segment calculate based on the ratio of
* `currentDataItem.value`/`nextDataItem.value`.
* Charts always create the last element as a rectangle since there is no following element.
*/
dynamicSlope?: boolean;
/**
* Specifies the data item field which contains the [`series.errorBars`]({% slug api_charts_series %}#toc-errorbars) high value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"bar"`, `"column"`, `"line"`, or `"area"`.
*/
errorHighField?: string;
/**
* Specifies the data item field which contains the [`series.errorBars`]({% slug api_charts_series %}#toc-errorbars) low value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"bar"`, `"column"`, `"line"`, or `"area"`.
*/
errorLowField?: string;
/**
* Specifies the data item field which contains a Boolean value indicating whether the sector is exploded.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"donut"` or `"pie"`.
*/
explodeField?: string;
/**
* Specifies the data item field which contains the series value.
*/
field?: string;
/**
* Specifies the name of the parent series of the trendline.
*
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to
* "`linearTrendline`", "`exponentialTrendline`", "`logarithmicTrendline`", "`powerTrendline`", "`polynomialTrendline`" or "`movingAverageTrendline`".
*/
for?: string;
/**
* Specifies the data item field which contains the series from value.
*/
fromField?: string;
/**
* Specifies the distance between the categories expressed as a percentage of the bar width.
* See the related spacing setting.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"bar"`, `"column"`, `"candlestick"`, `"ohlc"`,
* `"radarColumn"`, or `"waterfall"`.
*/
gap?: number;
/**
* Specifies the data field which contains the high value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"candlestick"` or `"ohlc"`.
*/
highField?: string;
/**
* Specifies the diameter of the donut hole in pixels.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"donut"`.
*/
holeSize?: number;
/**
* Specifies the Chart line configuration options.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"area"`, `"candlestick"`, `"ohlc"`, or
* `"waterfall"`.
*/
line?: SeriesLine;
/**
* Specifies the data field containing the low value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"candlestick"` or `"ohlc"`.
*/
lowField?: string;
/**
* Specifies the data item field which contains the series lower value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"boxPlot"`.
*/
lowerField?: string;
/**
* Specifies the margin around each donut series (ring). A numeric value sets all margins.
*/
margin?: Margin | number;
/**
* Specifies the maximum size of the Chart bubble series marker.
*/
maxSize?: number;
/**
* Specifies the configuration of the mean value indicator (line) for [Box Plot series]({% slug boxplot_seriestypes_charts %}).
* This option is not supported by other series types.
*/
mean?: SeriesMedian;
/**
* Specifies the data item field which contains the series mean value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"boxPlot"`.
*/
meanField?: string;
/**
* Specifies the configuration of the median value indicator (line) for [Box Plot series]({% slug boxplot_seriestypes_charts %}).
* This option is not supported by other series types.
*/
median?: SeriesMedian;
/**
* Specifies the data item field which contains the series median value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"boxPlot"`.
*/
medianField?: string;
/**
* Specifies the minimum size of the Chart bubble series marker.
*/
minSize?: number;
/**
* Specifies the behavior for handling missing values.
* This option is available when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"area"`, `"rangeArea"`, `"line"`, `"scatterLine"`,
* `"radarLine"`, `"radarArea"`, `"polarLine"`, or `"polarArea"`.
*
* Supports the following values:
* - `"gap"`—The plot stops before the missing point and continues after it.
* - `"interpolate"`—Interpolates the value from neighboring points. Represents the default value for all series except for the `"area"` and stacked series. Area and stacked series default to `"zero"`.
* - `"zero"`—Assumes the value to be zero.
*/
missingValues?: 'gap' | 'interpolate' | 'zero';
/**
* Specifies the name of the Chart series which is visible in the legend.
*/
name?: string;
/**
* Specifies the top-base/bottom-base ratio of the whole Funnel Chart. If the `neckRatio` is set to `3`,
* it means the top base is three times smaller than the bottom base.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"funnel"` and `dynamicSlope` is set to `false`.
*/
neckRatio?: number;
/**
* Specifies the color to use for the Bar, Column, or Waterfall series with negative values.
* Accepts valid CSS color string, including HEX and RGB.
*/
negativeColor?: string;
/**
* Specifies the options for displaying the Chart negative bubble values.
*/
negativeValues?: NegativeBubbleValues;
/**
* Specifies the data item field which contains the series note text.
*/
noteTextField?: string;
/**
* Specifies the opacity of the series. Series are opaque by default.
*/
opacity?: number;
/**
* Specifies the data field which contains the open value.
* This option is available when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"candlestick"` or `"ohlc"`.
*/
openField?: string;
/**
* Specifies the data item field which contains the series outliers value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"boxPlot"`.
*/
outliersField?: string;
/**
* Specifies the overlay options of the Chart series.
*/
overlay?: Overlay;
/**
* Specifies the padding around the Chart (equal on all sides).
* This option is available when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"donut"` or `"pie"`.
*/
padding?: number;
/**
* Specifies the data item field which contains the series `q1` value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"boxPlot"`.
*/
q1Field?: string;
/**
* Specifies the data item field which contains the series `q3` value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"boxPlot"`.
*/
q3Field?: string;
/**
* Specifies the space in pixels between the different segments of the Funnel or Pyramid Chart.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"funnel"` or `"pyramid"`.
*/
segmentSpacing?: number;
/**
* Specifies the radius of the Chart Donut series in pixels. When not set, Charts split the available space evenly
* between the series.
*/
size?: number;
/**
* Specifies the data field which contains the bubble size value.
*/
sizeField?: string;
/**
* Specifies the distance between series points within a category expressed as a percentage of the bar width.
* See the related `gap` setting.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"bar"`, `"column"`, `"candlestick"`, `"ohlc"`, or
* `"radarColumn"`.
*/
spacing?: number;
/**
* Determines whether the series stacks.
* Interprets a string value as [`series.stack.group`]({% slug api_charts_seriesstack %}#toc-group).
*
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"bar"`, `"column"`, `"line"`, `"area"`,
* `"verticalLine"`, `"verticalArea"`, `"radarLine"`, `"radarArea"`, and `"radarColumn"`.
* If not overridden, inherits the stack settings of the first series as a default value for the rest of the series.
*/
stack?: boolean | string | SeriesStack;
/**
* Specifies the start angle (in degrees) of the first Donut or Pie segment.
* Increases clockwise with zero to the left. You can use negative values.
*/
startAngle?: number;
/**
* Specifies the style options for the series.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to
* `"line"`, `"scatterLine"`, `"radarLine"`, or `"polarLine"`.
*/
style?: LineStyle;
/**
* Specifies the data item field which contains the summary type for the Waterfall series.
* Discards the value (if any) of a data item marked as a summary point.
*
* Summary columns are optional and take one of two types:
*
* `"runningTotal"`—Displays the sum of all items since the last `"runningTotal"` point.
* `"total"`—Displays the sum of all previous items.
*/
summaryField?: string;
/**
* Specifies the configuration options of the target.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"bullet"` or `"verticalBullet"`.
*/
target?: BulletTarget;
/**
* Specifies the data item field which contains the series to value.
*/
toField?: string;
/**
* Specifies the type of the series.
*/
type?: SeriesType;
/**
* Specifies the data item field which contains the series upper value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"boxPlot"`.
*/
upperField?: string;
/**
* Specifies the visible property of a Chart series.
*/
visible?: boolean;
/**
* Determines whether to show the point category (for Funnel, Pyramid, Donut, and Pie series)
* or the series name (for other available series types) in the legend.
*/
visibleInLegend?: boolean;
/**
* Specifies the data item field which indicates whether to show the point category name in the legend.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"funnel"`, `"pyramid"`, `"donut"`, or `"pie"`.
*/
visibleInLegendField?: string;
/**
* Specifies a function that creates a custom visual for the points. Applicable for the Bar, Column,
* Pie, Donut, Funnel, Pyramid, Range Bar, Range Column, Line, ScatterLine, and Waterfall series.
*/
visual?: (e: SeriesVisualArgs) => drawing.Element;
/**
* Specifies the line width.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"line"`, `"scatterLine"`, `"radarLine"`, or
* `"polarLine"`.
*/
width?: number;
/**
* Specifies the name of the X axis.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"bubble"`, `"scatter"`, `"scatterLine"`, or `"polar"` series.
* For the Polar series, Charts express the [`xAxis`]({% slug api_charts_xaxis %}) range in degrees.
*/
xAxis?: string;
/**
* Specifies the data item field which contains the [`series.errorBars`]({% slug api_charts_series %}#toc-errorbars) xAxis high value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"scatter"`, `"scatterLine"`, or
* `"bubble"`.
*/
xErrorHighField?: string;
/**
* Specifies the data item field which contains the [`series.errorBars`]({% slug api_charts_series %}#toc-errorbars) xAxis low value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"scatter"`, `"scatterLine"`, or
* `"bubble"`.
*/
xErrorLowField?: string;
/**
* Specifies the data item field containing the x value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"bubble"`, `"scatter"`, `"scatterLine"`, or
* `"polar"` series.
*/
xField?: string;
/**
* Specifies the name of the Y axis to use.
* Available for the Bubble, Scatter, Scatter Line, and Polar series.
*/
yAxis?: string;
/**
* Specifies the data item field which contains the [`series.errorBars`]({% slug api_charts_series %}#toc-errorbars) yAxis high value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"scatter"`, `"scatterLine"`, or
* `"bubble"`.
*/
yErrorHighField?: string;
/**
* Specifies the data item field which contains the [`series.errorBars`]({% slug api_charts_series %}#toc-errorbars) yAxis low value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"scatter"`, `"scatterLine"`, or
* `"bubble"`.
*/
yErrorLowField?: string;
/**
* Specifies the data item field containing the y value.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"bubble"`, `"scatter"`, or `"scatterLine"`.
*/
yField?: string;
/**
* Specifies an optional Z-index that changes the default stacking order of series.
* Series with the highest Z-index appear on top.
* Series with no Z-index use the default stacking order based on the series type.
* For example, Line series appear on top with the Bar and Area following after.
*/
zIndex?: number;
/**
* Specifies the error bars of the Chart series.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"bar"`, `"column"`, `"line"`, `"area"`,
* `"scatter"`, `"scatterLine"`, or `"bubble"`.
*/
errorBars?: SeriesErrorBars;
/**
* Specifies the configuration of the Chart series extremes. Applies to extreme outliers.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"boxPlot"`.
*/
extremes?: SeriesExtremes;
/**
* Specifies the configuration of the Chart series highlight.
*/
highlight?: SeriesHighlight;
/**
* Specifies the configuration of the Chart series label.
* Displays the series labels when the [`series.labels.visible`]({% slug api_charts_serieslabels %}#toc-visible) option is set to `true`.
*/
labels?: SeriesLabels;
/**
* Specifies the configuration of the Chart series marker.
* Displays the series labels when the [`series.markers.visible`]({% slug api_charts_seriesmarkers %}#toc-visible) option is set to `true`.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"area"`, `"rangeArea"`, `"line"`, `"scatter"`, `"scatterLine"`,
* `"radarLine"`, `"radarArea"`, `"polarLine"`, `"polarScatter"`, or `"polarArea"`.
*/
markers?: SeriesMarkers;
/**
* Specifies the configuration of the Chart legend item.
* Inherits the Legend item type and markers from the series by default.
*/
legendItem?: LegendItem;
/**
* Specifies the configuration of the series notes.
*/
notes?: SeriesNotes;
/**
* Specifies the configuration of the Chart series outliers. Applies to mild outliers.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"boxPlot"`.
*/
outliers?: SeriesOutliers;
/**
* Specifies the configuration options of the Chart series tooltip.
*/
tooltip?: SeriesTooltip;
/**
* Specifies the trendline configuration options.
*
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to
* "`linearTrendline`", "`exponentialTrendline`", "`logarithmicTrendline`", "`powerTrendline`", "`polynomialTrendline`" or "`movingAverageTrendline`".
*/
trendline?: SeriesTrendline;
/**
* Specifies the configuration of the whiskers for the Chart series.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"boxPlot"`.
*/
whiskers?: SeriesWhiskers;
/**
* Specifies the configuration options of the series pattern.
*/
pattern?: SeriesPattern | ((point: any) => SeriesPattern);
/**
* Specifies the data item field which contains the series pattern.
* This option is supported when [`series.type`]({% slug api_charts_series %}#toc-type) is set to `"pie"`, `"donut"`, `"funnel"`, `"heatmap"`, or `"pyramid"`.
*/
patternField?: string;
}