ExcelScript.ChartSeries interface

Adds a new trendline to trendline collection.

addChartTrendline(type?: ChartTrendlineType): ChartTrendline;

Parameters

Returns

Deletes the chart series.

delete(): void;

Returns

Specifies the group for the specified series.

getAxisGroup(): ChartAxisGroup;

Returns

Encapsulates the bin options for histogram charts and pareto charts.

getBinOptions(): ChartBinOptions;

Returns

Encapsulates the options for the box and whisker charts.

getBoxwhiskerOptions(): ChartBoxwhiskerOptions;

Returns

This can be an integer value from 0 (zero) to 300, representing the percentage of the default size. This property only applies to bubble charts.

getBubbleScale(): number;

Returns

Gets a trendline object by index, which is the insertion order in the items array.

getChartTrendline(index: number): ChartTrendline;

Parameters

Returns

Represents the chart type of a series. See ExcelScript.ChartType for details.

getChartType(): ChartType;

Returns

Represents a collection of all data labels in the series.

getDataLabels(): ChartDataLabels;

Returns

Gets the string representation of the data source of the chart series. The string representation could be information such as a cell address.

getDimensionDataSourceString(dimension: ChartSeriesDimension): string;

Parameters

Returns

Gets the data source type of the chart series.

getDimensionDataSourceType(
            dimension: ChartSeriesDimension
        ): ChartDataSourceType;

Parameters

Returns

Gets the values from a single dimension of the chart series. These could be either category values or data values, depending on the dimension specified and how the data is mapped for the chart series.

getDimensionValues(dimension: ChartSeriesDimension): string[];

Parameters

Returns

Represents the doughnut hole size of a chart series. Only valid on doughnut and doughnut exploded charts. Throws an InvalidArgument error on invalid charts.

getDoughnutHoleSize(): number;

Returns

Specifies the explosion value for a pie-chart or doughnut-chart slice. Returns 0 (zero) if there's no explosion (the tip of the slice is in the center of the pie).

getExplosion(): number;

Returns

Specifies if the series is filtered. Not applicable for surface charts.

getFiltered(): boolean;

Returns

Specifies the angle of the first pie-chart or doughnut-chart slice, in degrees (clockwise from vertical). Applies only to pie, 3-D pie, and doughnut charts. Can be a value from 0 through 360.

getFirstSliceAngle(): number;

Returns

Represents the formatting of a chart series, which includes fill and line formatting.

getFormat(): ChartSeriesFormat;

Returns

Represents the gap width of a chart series. Only valid on bar and column charts, as well as specific classes of line and pie charts. Throws an invalid argument exception on invalid charts.

getGapWidth(): number;

Returns

Specifies the color for maximum value of a region map chart series.

getGradientMaximumColor(): string;

Returns

Specifies the type for maximum value of a region map chart series.

getGradientMaximumType(): ChartGradientStyleType;

Returns

Specifies the maximum value of a region map chart series.

getGradientMaximumValue(): number;

Returns

Specifies the color for the midpoint value of a region map chart series.

getGradientMidpointColor(): string;

Returns

Specifies the type for the midpoint value of a region map chart series.

getGradientMidpointType(): ChartGradientStyleType;

Returns

Specifies the midpoint value of a region map chart series.

getGradientMidpointValue(): number;

Returns

Specifies the color for the minimum value of a region map chart series.

getGradientMinimumColor(): string;

Returns

Specifies the type for the minimum value of a region map chart series.

getGradientMinimumType(): ChartGradientStyleType;

Returns

Specifies the minimum value of a region map chart series.

getGradientMinimumValue(): number;

Returns

Specifies the series gradient style of a region map chart.

getGradientStyle(): ChartGradientStyle;

Returns

Specifies if the series has data labels.

getHasDataLabels(): boolean;

Returns

Specifies the fill color for negative data points in a series.

getInvertColor(): string;

Returns

True if Excel inverts the pattern in the item when it corresponds to a negative number.

getInvertIfNegative(): boolean;

Returns

Encapsulates the options for a region map chart.

getMapOptions(): ChartMapOptions;

Returns

Specifies the marker background color of a chart series.

getMarkerBackgroundColor(): string;

Returns

Specifies the marker foreground color of a chart series.

getMarkerForegroundColor(): string;

Returns

Specifies the marker size of a chart series. The supported size range is 2 to 72. This method returns an InvalidArgument error if it's set with a size outside of the supported range.

getMarkerSize(): number;

Returns

Specifies the marker style of a chart series. See ExcelScript.ChartMarkerStyle for details.

getMarkerStyle(): ChartMarkerStyle;

Returns

Specifies the name of a series in a chart. The name's length should not be greater than 255 characters.

getName(): string;

Returns

Examples

/**
 * This sample logs the names of each of the chart series in a chart named "ColumnClusteredChart".
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get an existing chart named "ColumnClusteredChart".
  let chart = selectedSheet.getChart("ColumnClusteredChart");

  // Log the name of each chart series in the chart.
  let seriesList = chart.getSeries();
  seriesList.forEach((series) => {
    console.log(series.getName());
  });
}

Specifies how bars and columns are positioned. Can be a value between -100 and 100. Applies only to 2-D bar and 2-D column charts.

getOverlap(): number;

Returns

Specifies the series parent label strategy area for a treemap chart.

getParentLabelStrategy(): ChartParentLabelStrategy;

Returns

Specifies the plot order of a chart series within the chart group.

getPlotOrder(): number;

Returns

Returns a collection of all points in the series.

getPoints(): ChartPoint[];

Returns

Specifies the size of the secondary section of either a pie-of-pie chart or a bar-of-pie chart, as a percentage of the size of the primary pie. Can be a value from 5 to 200.

getSecondPlotSize(): number;

Returns

Specifies whether connector lines are shown in waterfall charts.

getShowConnectorLines(): boolean;

Returns

Specifies whether leader lines are displayed for each data label in the series.

getShowLeaderLines(): boolean;

Returns

Specifies if the series has a shadow.

getShowShadow(): boolean;

Returns

Specifies if the series is smooth. Only applicable to line and scatter charts.

getSmooth(): boolean;

Returns

Specifies the way the two sections of either a pie-of-pie chart or a bar-of-pie chart are split.

getSplitType(): ChartSplitType;

Returns

Specifies the threshold value that separates two sections of either a pie-of-pie chart or a bar-of-pie chart.

getSplitValue(): number;

Returns

The collection of trendlines in the series.

getTrendlines(): ChartTrendline[];

Returns

True if Excel assigns a different color or pattern to each data marker. The chart must contain only one series.

getVaryByCategories(): boolean;

Returns

Represents the error bar object of a chart series.

getXErrorBars(): ChartErrorBars;

Returns

Represents the error bar object of a chart series.

getYErrorBars(): ChartErrorBars;

Returns

Examples

/**
 * This script adds error bars for the standard error of each chart series point.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the range for the chart.
  const worksheet = workbook.getWorksheet("Sample");
  const dataRange = worksheet.getRange("A1:B15");

  // Create a line chart.
  const chart = worksheet.addChart(ExcelScript.ChartType.line, dataRange);

  // For each series, add error bars for the standard error on each point
  const allSeries = chart.getSeries();
  allSeries.forEach((series) => {
    series.getYErrorBars().setType(ExcelScript.ChartErrorBarsType.stError);
    series.getYErrorBars().setVisible(true);
  });
}

Specifies the group for the specified series.

setAxisGroup(axisGroup: ChartAxisGroup): void;

Parameters

Returns

This can be an integer value from 0 (zero) to 300, representing the percentage of the default size. This property only applies to bubble charts.

setBubbleScale(bubbleScale: number): void;

Parameters

Returns

Sets the bubble sizes for a chart series. Only works for bubble charts.

setBubbleSizes(sourceData: Range): void;

Parameters

Returns

Represents the chart type of a series. See ExcelScript.ChartType for details.

setChartType(chartType: ChartType): void;

Parameters

Returns

Represents the doughnut hole size of a chart series. Only valid on doughnut and doughnut exploded charts. Throws an InvalidArgument error on invalid charts.

setDoughnutHoleSize(doughnutHoleSize: number): void;

Parameters

Returns

Specifies the explosion value for a pie-chart or doughnut-chart slice. Returns 0 (zero) if there's no explosion (the tip of the slice is in the center of the pie).

setExplosion(explosion: number): void;

Parameters

Returns

Specifies if the series is filtered. Not applicable for surface charts.

setFiltered(filtered: boolean): void;

Parameters

Returns

Specifies the angle of the first pie-chart or doughnut-chart slice, in degrees (clockwise from vertical). Applies only to pie, 3-D pie, and doughnut charts. Can be a value from 0 through 360.

setFirstSliceAngle(firstSliceAngle: number): void;

Parameters

Returns

Represents the gap width of a chart series. Only valid on bar and column charts, as well as specific classes of line and pie charts. Throws an invalid argument exception on invalid charts.

setGapWidth(gapWidth: number): void;

Parameters

Returns

Specifies the color for maximum value of a region map chart series.

setGradientMaximumColor(gradientMaximumColor: string): void;

Parameters

Returns

Specifies the type for maximum value of a region map chart series.

setGradientMaximumType(
            gradientMaximumType: ChartGradientStyleType
        ): void;

Parameters

Returns

Specifies the maximum value of a region map chart series.

setGradientMaximumValue(gradientMaximumValue: number): void;

Parameters

Returns

Specifies the color for the midpoint value of a region map chart series.

setGradientMidpointColor(gradientMidpointColor: string): void;

Parameters

Returns

Specifies the type for the midpoint value of a region map chart series.

setGradientMidpointType(
            gradientMidpointType: ChartGradientStyleType
        ): void;

Parameters

Returns

Specifies the midpoint value of a region map chart series.

setGradientMidpointValue(gradientMidpointValue: number): void;

Parameters

Returns

Specifies the color for the minimum value of a region map chart series.

setGradientMinimumColor(gradientMinimumColor: string): void;

Parameters

Returns

Specifies the type for the minimum value of a region map chart series.

setGradientMinimumType(
            gradientMinimumType: ChartGradientStyleType
        ): void;

Parameters

Returns

Specifies the minimum value of a region map chart series.

setGradientMinimumValue(gradientMinimumValue: number): void;

Parameters

Returns

Specifies the series gradient style of a region map chart.

setGradientStyle(gradientStyle: ChartGradientStyle): void;

Parameters

Returns

Specifies if the series has data labels.

setHasDataLabels(hasDataLabels: boolean): void;

Parameters

Returns

Specifies the fill color for negative data points in a series.

setInvertColor(invertColor: string): void;

Parameters

Returns

True if Excel inverts the pattern in the item when it corresponds to a negative number.

setInvertIfNegative(invertIfNegative: boolean): void;

Parameters

Returns

Specifies the marker background color of a chart series.

setMarkerBackgroundColor(markerBackgroundColor: string): void;

Parameters

Returns

Specifies the marker foreground color of a chart series.

setMarkerForegroundColor(markerForegroundColor: string): void;

Parameters

Returns

Specifies the marker size of a chart series. The supported size range is 2 to 72. This method returns an InvalidArgument error if it's set with a size outside of the supported range.

setMarkerSize(markerSize: number): void;

Parameters

Returns

Specifies the marker style of a chart series. See ExcelScript.ChartMarkerStyle for details.

setMarkerStyle(markerStyle: ChartMarkerStyle): void;

Parameters

Returns

Specifies the name of a series in a chart. The name's length should not be greater than 255 characters.

setName(name: string): void;

Parameters

Returns

Specifies how bars and columns are positioned. Can be a value between -100 and 100. Applies only to 2-D bar and 2-D column charts.

setOverlap(overlap: number): void;

Parameters

Returns

Examples

/**
 * This sample sets the overlap of the columns in a chart named "ColumnClusteredChart".
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get an existing chart named "ColumnClusteredChart".
  let chart = selectedSheet.getChart("ColumnClusteredChart");

  // Set the overlap of every column of each series within a category.
  let seriesList = chart.getSeries();
  seriesList.forEach((series) => {
    // An overlap of 25 means the columns have 25% of their length overlapping with the adjacent columns in the same category.
    series.setOverlap(25);
  });
}

Specifies the series parent label strategy area for a treemap chart.

setParentLabelStrategy(
            parentLabelStrategy: ChartParentLabelStrategy
        ): void;

Parameters

Returns

Specifies the plot order of a chart series within the chart group.

setPlotOrder(plotOrder: number): void;

Parameters

Returns

Specifies the size of the secondary section of either a pie-of-pie chart or a bar-of-pie chart, as a percentage of the size of the primary pie. Can be a value from 5 to 200.

setSecondPlotSize(secondPlotSize: number): void;

Parameters

Returns

Specifies whether connector lines are shown in waterfall charts.

setShowConnectorLines(showConnectorLines: boolean): void;

Parameters

Returns

Specifies whether leader lines are displayed for each data label in the series.

setShowLeaderLines(showLeaderLines: boolean): void;

Parameters

Returns

Specifies if the series has a shadow.

setShowShadow(showShadow: boolean): void;

Parameters

Returns

Specifies if the series is smooth. Only applicable to line and scatter charts.

setSmooth(smooth: boolean): void;

Parameters

Returns

Specifies the way the two sections of either a pie-of-pie chart or a bar-of-pie chart are split.

setSplitType(splitType: ChartSplitType): void;

Parameters

Returns

Specifies the threshold value that separates two sections of either a pie-of-pie chart or a bar-of-pie chart.

setSplitValue(splitValue: number): void;

Parameters

Returns

Sets the values for a chart series. For scatter charts, it refers to y-axis values.

setValues(sourceData: Range): void;

Parameters

Returns

True if Excel assigns a different color or pattern to each data marker. The chart must contain only one series.

setVaryByCategories(varyByCategories: boolean): void;

Parameters

Returns

Sets the values of the x-axis for a chart series.

setXAxisValues(sourceData: Range): void;

Parameters

Returns