Excel.ChartSeries class

Represents a series in a chart.

[ API set: ExcelApi 1.1 ]

Extends
OfficeExtension.ClientObject

Properties

axisGroup

Returns or sets the group for the specified series. Read/Write

[ API set: ExcelApi 1.8 ]

binOptions

Encapsulates the bin options for histogram charts and pareto charts. Read-only.

[ API set: ExcelApi 1.9 ]

boxwhiskerOptions

Encapsulates the options for the box and whisker charts. Read-only.

[ API set: ExcelApi 1.9 ]

bubbleScale

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. Read/Write.

[ API set: ExcelApi 1.9 ]

chartType

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

[ API set: ExcelApi 1.7 ]

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

dataLabels

Represents a collection of all dataLabels in the series.

[ API set: ExcelApi 1.8 ]

doughnutHoleSize

Represents the doughnut hole size of a chart series. Only valid on doughnut and doughnutExploded charts. Throws an invalid argument exception on invalid charts.

[ API set: ExcelApi 1.7 ]

explosion

Returns or sets 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). Read/Write.

[ API set: ExcelApi 1.8 ]

filtered

Boolean value representing if the series is filtered or not. Not applicable for surface charts.

[ API set: ExcelApi 1.7 ]

firstSliceAngle

Returns or sets 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. Read/Write

[ API set: ExcelApi 1.8 ]

format

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

[ API set: ExcelApi 1.1 ]

gapWidth

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.

[ API set: ExcelApi 1.7 ]

gradientMaximumColor

Returns or sets the color for maximum value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMaximumType

Returns or sets the type for maximum value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMaximumValue

Returns or sets the maximum value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMidpointColor

Returns or sets the color for midpoint value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMidpointType

Returns or sets the type for midpoint value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMidpointValue

Returns or sets the midpoint value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMinimumColor

Returns or sets the color for minimum value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMinimumType

Returns or sets the type for minimum value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMinimumValue

Returns or sets the minimum value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientStyle

Returns or sets series gradient style of a region map chart. Read/Write.

[ API set: ExcelApi 1.9 ]

hasDataLabels

Boolean value representing if the series has data labels or not.

[ API set: ExcelApi 1.7 ]

invertColor

Returns or sets the fill color for negative data points in a series. Read/Write.

[ API set: ExcelApi 1.9 ]

invertIfNegative

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

[ API set: ExcelApi 1.8 ]

mapOptions

Encapsulates the options for a region map chart. Read-only.

[ API set: ExcelApi 1.9 ]

markerBackgroundColor

Represents markers background color of a chart series.

[ API set: ExcelApi 1.7 ]

markerForegroundColor

Represents markers foreground color of a chart series.

[ API set: ExcelApi 1.7 ]

markerSize

Represents marker size of a chart series.

[ API set: ExcelApi 1.7 ]

markerStyle

Represents marker style of a chart series. See Excel.ChartMarkerStyle for details.

[ API set: ExcelApi 1.7 ]

name

Represents the name of a series in a chart.

[ API set: ExcelApi 1.1 ]

overlap

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. Read/Write.

[ API set: ExcelApi 1.8 ]

parentLabelStrategy

Returns or sets the series parent label strategy area for a treemap chart. Read/Write.

[ API set: ExcelApi 1.9 ]

plotOrder

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

[ API set: ExcelApi 1.7 ]

points

Represents a collection of all points in the series. Read-only.

[ API set: ExcelApi 1.1 ]

secondPlotSize

Returns or sets 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. Read/Write.

[ API set: ExcelApi 1.8 ]

showConnectorLines

Specifies whether or not connector lines are shown in waterfall charts. Read/Write.

[ API set: ExcelApi 1.9 ]

showLeaderLines

Specifies whether or not leader lines are displayed for each data label in the series. Read/Write.

[ API set: ExcelApi 1.9 ]

showShadow

Boolean value representing if the series has a shadow or not.

[ API set: ExcelApi 1.7 ]

smooth

Boolean value representing if the series is smooth or not. Only applicable to line and scatter charts.

[ API set: ExcelApi 1.7 ]

splitType

Returns or sets the way the two sections of either a pie of pie chart or a bar of pie chart are split. Read/Write.

[ API set: ExcelApi 1.8 ]

splitValue

Returns or sets the threshold value that separates two sections of either a pie-of-pie chart or a bar-of-pie chart. Read/Write.

[ API set: ExcelApi 1.9 ]

trendlines

Represents a collection of trendlines in the series. Read-only.

[ API set: ExcelApi 1.7 ]

varyByCategories

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

[ API set: ExcelApi 1.8 ]

xErrorBars

Represents the error bar object of a chart series.

[ API set: ExcelApi 1.9 ]

yErrorBars

Represents the error bar object of a chart series.

[ API set: ExcelApi 1.9 ]

Methods

delete()

Deletes the chart series.

[ API set: ExcelApi 1.7 ]

getDimensionValues(dimension)

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.

[ API set: ExcelApi BETA (PREVIEW ONLY) ]

getDimensionValues(dimensionString)

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.

[ API set: ExcelApi BETA (PREVIEW ONLY) ]

load(options)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

setBubbleSizes(sourceData)

Set bubble sizes for a chart series. Only works for bubble charts.

[ API set: ExcelApi 1.7 ]

setValues(sourceData)

Set values for a chart series. For scatter chart, it means Y axis values.

[ API set: ExcelApi 1.7 ]

setXAxisValues(sourceData)

Set values of X axis for a chart series. Only works for scatter charts.

[ API set: ExcelApi 1.7 ]

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.ChartSeries object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.ChartSeriesData) that contains shallow copies of any loaded child properties from the original object.

Property Details

axisGroup

Returns or sets the group for the specified series. Read/Write

[ API set: ExcelApi 1.8 ]

axisGroup: Excel.ChartAxisGroup | "Primary" | "Secondary";

Property Value

Excel.ChartAxisGroup | "Primary" | "Secondary"

binOptions

Encapsulates the bin options for histogram charts and pareto charts. Read-only.

[ API set: ExcelApi 1.9 ]

readonly binOptions: Excel.ChartBinOptions;

Property Value

boxwhiskerOptions

Encapsulates the options for the box and whisker charts. Read-only.

[ API set: ExcelApi 1.9 ]

readonly boxwhiskerOptions: Excel.ChartBoxwhiskerOptions;

Property Value

bubbleScale

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. Read/Write.

[ API set: ExcelApi 1.9 ]

bubbleScale: number;

Property Value

number

chartType

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

[ API set: ExcelApi 1.7 ]

chartType: Excel.ChartType | "Invalid" | "ColumnClustered" | "ColumnStacked" | "ColumnStacked100" | "3DColumnClustered" | "3DColumnStacked" | "3DColumnStacked100" | "BarClustered" | "BarStacked" | "BarStacked100" | "3DBarClustered" | "3DBarStacked" | "3DBarStacked100" | "LineStacked" | "LineStacked100" | "LineMarkers" | "LineMarkersStacked" | "LineMarkersStacked100" | "PieOfPie" | "PieExploded" | "3DPieExploded" | "BarOfPie" | "XYScatterSmooth" | "XYScatterSmoothNoMarkers" | "XYScatterLines" | "XYScatterLinesNoMarkers" | "AreaStacked" | "AreaStacked100" | "3DAreaStacked" | "3DAreaStacked100" | "DoughnutExploded" | "RadarMarkers" | "RadarFilled" | "Surface" | "SurfaceWireframe" | "SurfaceTopView" | "SurfaceTopViewWireframe" | "Bubble" | "Bubble3DEffect" | "StockHLC" | "StockOHLC" | "StockVHLC" | "StockVOHLC" | "CylinderColClustered" | "CylinderColStacked" | "CylinderColStacked100" | "CylinderBarClustered" | "CylinderBarStacked" | "CylinderBarStacked100" | "CylinderCol" | "ConeColClustered" | "ConeColStacked" | "ConeColStacked100" | "ConeBarClustered" | "ConeBarStacked" | "ConeBarStacked100" | "ConeCol" | "PyramidColClustered" | "PyramidColStacked" | "PyramidColStacked100" | "PyramidBarClustered" | "PyramidBarStacked" | "PyramidBarStacked100" | "PyramidCol" | "3DColumn" | "Line" | "3DLine" | "3DPie" | "Pie" | "XYScatter" | "3DArea" | "Area" | "Doughnut" | "Radar" | "Histogram" | "Boxwhisker" | "Pareto" | "RegionMap" | "Treemap" | "Waterfall" | "Sunburst" | "Funnel";

Property Value

Excel.ChartType | "Invalid" | "ColumnClustered" | "ColumnStacked" | "ColumnStacked100" | "3DColumnClustered" | "3DColumnStacked" | "3DColumnStacked100" | "BarClustered" | "BarStacked" | "BarStacked100" | "3DBarClustered" | "3DBarStacked" | "3DBarStacked100" | "LineStacked" | "LineStacked100" | "LineMarkers" | "LineMarkersStacked" | "LineMarkersStacked100" | "PieOfPie" | "PieExploded" | "3DPieExploded" | "BarOfPie" | "XYScatterSmooth" | "XYScatterSmoothNoMarkers" | "XYScatterLines" | "XYScatterLinesNoMarkers" | "AreaStacked" | "AreaStacked100" | "3DAreaStacked" | "3DAreaStacked100" | "DoughnutExploded" | "RadarMarkers" | "RadarFilled" | "Surface" | "SurfaceWireframe" | "SurfaceTopView" | "SurfaceTopViewWireframe" | "Bubble" | "Bubble3DEffect" | "StockHLC" | "StockOHLC" | "StockVHLC" | "StockVOHLC" | "CylinderColClustered" | "CylinderColStacked" | "CylinderColStacked100" | "CylinderBarClustered" | "CylinderBarStacked" | "CylinderBarStacked100" | "CylinderCol" | "ConeColClustered" | "ConeColStacked" | "ConeColStacked100" | "ConeBarClustered" | "ConeBarStacked" | "ConeBarStacked100" | "ConeCol" | "PyramidColClustered" | "PyramidColStacked" | "PyramidColStacked100" | "PyramidBarClustered" | "PyramidBarStacked" | "PyramidBarStacked100" | "PyramidCol" | "3DColumn" | "Line" | "3DLine" | "3DPie" | "Pie" | "XYScatter" | "3DArea" | "Area" | "Doughnut" | "Radar" | "Histogram" | "Boxwhisker" | "Pareto" | "RegionMap" | "Treemap" | "Waterfall" | "Sunburst" | "Funnel"

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

dataLabels

Represents a collection of all dataLabels in the series.

[ API set: ExcelApi 1.8 ]

readonly dataLabels: Excel.ChartDataLabels;

Property Value

doughnutHoleSize

Represents the doughnut hole size of a chart series. Only valid on doughnut and doughnutExploded charts. Throws an invalid argument exception on invalid charts.

[ API set: ExcelApi 1.7 ]

doughnutHoleSize: number;

Property Value

number

explosion

Returns or sets 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). Read/Write.

[ API set: ExcelApi 1.8 ]

explosion: number;

Property Value

number

filtered

Boolean value representing if the series is filtered or not. Not applicable for surface charts.

[ API set: ExcelApi 1.7 ]

filtered: boolean;

Property Value

boolean

firstSliceAngle

Returns or sets 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. Read/Write

[ API set: ExcelApi 1.8 ]

firstSliceAngle: number;

Property Value

number

format

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

[ API set: ExcelApi 1.1 ]

readonly format: Excel.ChartSeriesFormat;

Property Value

gapWidth

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.

[ API set: ExcelApi 1.7 ]

gapWidth: number;

Property Value

number

gradientMaximumColor

Returns or sets the color for maximum value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMaximumColor: string;

Property Value

string

gradientMaximumType

Returns or sets the type for maximum value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMaximumType: Excel.ChartGradientStyleType | "ExtremeValue" | "Number" | "Percent";

Property Value

Excel.ChartGradientStyleType | "ExtremeValue" | "Number" | "Percent"

gradientMaximumValue

Returns or sets the maximum value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMaximumValue: number;

Property Value

number

gradientMidpointColor

Returns or sets the color for midpoint value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMidpointColor: string;

Property Value

string

gradientMidpointType

Returns or sets the type for midpoint value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMidpointType: Excel.ChartGradientStyleType | "ExtremeValue" | "Number" | "Percent";

Property Value

Excel.ChartGradientStyleType | "ExtremeValue" | "Number" | "Percent"

gradientMidpointValue

Returns or sets the midpoint value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMidpointValue: number;

Property Value

number

gradientMinimumColor

Returns or sets the color for minimum value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMinimumColor: string;

Property Value

string

gradientMinimumType

Returns or sets the type for minimum value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMinimumType: Excel.ChartGradientStyleType | "ExtremeValue" | "Number" | "Percent";

Property Value

Excel.ChartGradientStyleType | "ExtremeValue" | "Number" | "Percent"

gradientMinimumValue

Returns or sets the minimum value of a region map chart series. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientMinimumValue: number;

Property Value

number

gradientStyle

Returns or sets series gradient style of a region map chart. Read/Write.

[ API set: ExcelApi 1.9 ]

gradientStyle: Excel.ChartGradientStyle | "TwoPhaseColor" | "ThreePhaseColor";

Property Value

Excel.ChartGradientStyle | "TwoPhaseColor" | "ThreePhaseColor"

hasDataLabels

Boolean value representing if the series has data labels or not.

[ API set: ExcelApi 1.7 ]

hasDataLabels: boolean;

Property Value

boolean

invertColor

Returns or sets the fill color for negative data points in a series. Read/Write.

[ API set: ExcelApi 1.9 ]

invertColor: string;

Property Value

string

invertIfNegative

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

[ API set: ExcelApi 1.8 ]

invertIfNegative: boolean;

Property Value

boolean

mapOptions

Encapsulates the options for a region map chart. Read-only.

[ API set: ExcelApi 1.9 ]

readonly mapOptions: Excel.ChartMapOptions;

Property Value

markerBackgroundColor

Represents markers background color of a chart series.

[ API set: ExcelApi 1.7 ]

markerBackgroundColor: string;

Property Value

string

Examples

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");
    let salesTable = sheet.tables.getItem("SalesTable");
    let dataRange = sheet.getRange("A1:E7");

    // Create an XY scatter chart.
    let chart = sheet.charts.add("XYScatterSmooth", dataRange, "Auto");
    chart.title.text = "Bicycle Parts Quarterly Sales"; 
  
    let series = chart.series;
    let series0 = series.getItemAt(0);
    let series1 = series.getItemAt(1);
    let series2 = series.getItemAt(2);
    let series3 = series.getItemAt(3);

    // Set markers.
    series0.markerStyle = "Dash";
    series0.markerForegroundColor = "black";
    series1.markerStyle = "Star";
    series1.markerForegroundColor = "black";
    series2.markerStyle = "X";
    series2.markerSize = 12;
    series3.markerStyle = "Triangle";
    series3.markerBackgroundColor = "purple";

    await context.sync();
});

markerForegroundColor

Represents markers foreground color of a chart series.

[ API set: ExcelApi 1.7 ]

markerForegroundColor: string;

Property Value

string

Examples

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");
    let salesTable = sheet.tables.getItem("SalesTable");
    let dataRange = sheet.getRange("A1:E7");

    // Create an XY scatter chart.
    let chart = sheet.charts.add("XYScatterSmooth", dataRange, "Auto");
    chart.title.text = "Bicycle Parts Quarterly Sales"; 
  
    let series = chart.series;
    let series0 = series.getItemAt(0);
    let series1 = series.getItemAt(1);
    let series2 = series.getItemAt(2);
    let series3 = series.getItemAt(3);

    // Set markers.
    series0.markerStyle = "Dash";
    series0.markerForegroundColor = "black";
    series1.markerStyle = "Star";
    series1.markerForegroundColor = "black";
    series2.markerStyle = "X";
    series2.markerSize = 12;
    series3.markerStyle = "Triangle";
    series3.markerBackgroundColor = "purple";

    await context.sync();
});

markerSize

Represents marker size of a chart series.

[ API set: ExcelApi 1.7 ]

markerSize: number;

Property Value

number

Examples

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");
    let salesTable = sheet.tables.getItem("SalesTable");
    let dataRange = sheet.getRange("A1:E7");

    // Create an XY scatter chart.
    let chart = sheet.charts.add("XYScatterSmooth", dataRange, "Auto");
    chart.title.text = "Bicycle Parts Quarterly Sales"; 
  
    let series = chart.series;
    let series0 = series.getItemAt(0);
    let series1 = series.getItemAt(1);
    let series2 = series.getItemAt(2);
    let series3 = series.getItemAt(3);

    // Set markers.
    series0.markerStyle = "Dash";
    series0.markerForegroundColor = "black";
    series1.markerStyle = "Star";
    series1.markerForegroundColor = "black";
    series2.markerStyle = "X";
    series2.markerSize = 12;
    series3.markerStyle = "Triangle";
    series3.markerBackgroundColor = "purple";

    await context.sync();
});

markerStyle

Represents marker style of a chart series. See Excel.ChartMarkerStyle for details.

[ API set: ExcelApi 1.7 ]

markerStyle: Excel.ChartMarkerStyle | "Invalid" | "Automatic" | "None" | "Square" | "Diamond" | "Triangle" | "X" | "Star" | "Dot" | "Dash" | "Circle" | "Plus" | "Picture";

Property Value

Excel.ChartMarkerStyle | "Invalid" | "Automatic" | "None" | "Square" | "Diamond" | "Triangle" | "X" | "Star" | "Dot" | "Dash" | "Circle" | "Plus" | "Picture"

Examples

await Excel.run(async (context) => {
    let sheet = context.workbook.worksheets.getItem("Sample");
    let salesTable = sheet.tables.getItem("SalesTable");
    let dataRange = sheet.getRange("A1:E7");

    // Create an XY scatter chart.
    let chart = sheet.charts.add("XYScatterSmooth", dataRange, "Auto");
    chart.title.text = "Bicycle Parts Quarterly Sales"; 
  
    let series = chart.series;
    let series0 = series.getItemAt(0);
    let series1 = series.getItemAt(1);
    let series2 = series.getItemAt(2);
    let series3 = series.getItemAt(3);

    // Set markers.
    series0.markerStyle = "Dash";
    series0.markerForegroundColor = "black";
    series1.markerStyle = "Star";
    series1.markerForegroundColor = "black";
    series2.markerStyle = "X";
    series2.markerSize = 12;
    series3.markerStyle = "Triangle";
    series3.markerBackgroundColor = "purple";

    await context.sync();
});

name

Represents the name of a series in a chart.

[ API set: ExcelApi 1.1 ]

name: string;

Property Value

string

overlap

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. Read/Write.

[ API set: ExcelApi 1.8 ]

overlap: number;

Property Value

number

parentLabelStrategy

Returns or sets the series parent label strategy area for a treemap chart. Read/Write.

[ API set: ExcelApi 1.9 ]

parentLabelStrategy: Excel.ChartParentLabelStrategy | "None" | "Banner" | "Overlapping";

Property Value

Excel.ChartParentLabelStrategy | "None" | "Banner" | "Overlapping"

plotOrder

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

[ API set: ExcelApi 1.7 ]

plotOrder: number;

Property Value

number

points

Represents a collection of all points in the series. Read-only.

[ API set: ExcelApi 1.1 ]

readonly points: Excel.ChartPointsCollection;

Property Value

secondPlotSize

Returns or sets 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. Read/Write.

[ API set: ExcelApi 1.8 ]

secondPlotSize: number;

Property Value

number

showConnectorLines

Specifies whether or not connector lines are shown in waterfall charts. Read/Write.

[ API set: ExcelApi 1.9 ]

showConnectorLines: boolean;

Property Value

boolean

showLeaderLines

Specifies whether or not leader lines are displayed for each data label in the series. Read/Write.

[ API set: ExcelApi 1.9 ]

showLeaderLines: boolean;

Property Value

boolean

showShadow

Boolean value representing if the series has a shadow or not.

[ API set: ExcelApi 1.7 ]

showShadow: boolean;

Property Value

boolean

smooth

Boolean value representing if the series is smooth or not. Only applicable to line and scatter charts.

[ API set: ExcelApi 1.7 ]

smooth: boolean;

Property Value

boolean

splitType

Returns or sets the way the two sections of either a pie of pie chart or a bar of pie chart are split. Read/Write.

[ API set: ExcelApi 1.8 ]

splitType: Excel.ChartSplitType | "SplitByPosition" | "SplitByValue" | "SplitByPercentValue" | "SplitByCustomSplit";

Property Value

Excel.ChartSplitType | "SplitByPosition" | "SplitByValue" | "SplitByPercentValue" | "SplitByCustomSplit"

splitValue

Returns or sets the threshold value that separates two sections of either a pie-of-pie chart or a bar-of-pie chart. Read/Write.

[ API set: ExcelApi 1.9 ]

splitValue: number;

Property Value

number

trendlines

Represents a collection of trendlines in the series. Read-only.

[ API set: ExcelApi 1.7 ]

readonly trendlines: Excel.ChartTrendlineCollection;

Property Value

varyByCategories

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

[ API set: ExcelApi 1.8 ]

varyByCategories: boolean;

Property Value

boolean

xErrorBars

Represents the error bar object of a chart series.

[ API set: ExcelApi 1.9 ]

readonly xErrorBars: Excel.ChartErrorBars;

Property Value

yErrorBars

Represents the error bar object of a chart series.

[ API set: ExcelApi 1.9 ]

readonly yErrorBars: Excel.ChartErrorBars;

Property Value

Method Details

delete()

Deletes the chart series.

[ API set: ExcelApi 1.7 ]

delete(): void;

Returns

void

Examples

await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getItem("Sample");
  const seriesCollection = sheet.charts.getItemAt(0).series;
  seriesCollection.load("count");
  await context.sync();

  if (seriesCollection.count > 0) {
    const series = seriesCollection.getItemAt(0);

    // Delete the first series.
    series.delete();
  }

  await context.sync();
});

getDimensionValues(dimension)

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

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.

[ API set: ExcelApi BETA (PREVIEW ONLY) ]

getDimensionValues(dimension: Excel.ChartSeriesDimension): OfficeExtension.ClientResult<string[]>;

Parameters

dimension
Excel.ChartSeriesDimension

the dimension of axis where the data from

Returns

OfficeExtension.ClientResult<string>[]

getDimensionValues(dimensionString)

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.

[ API set: ExcelApi BETA (PREVIEW ONLY) ]

getDimensionValues(dimensionString: "Categories" | "Values" | "XValues" | "YValues"): OfficeExtension.ClientResult<string[]>;

Parameters

dimensionString
"Categories" | "Values" | "XValues" | "YValues"

the dimension of axis where the data from

Returns

OfficeExtension.ClientResult<string>[]

load(options)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(options?: Excel.Interfaces.ChartSeriesLoadOptions): Excel.ChartSeries;

Parameters

options
Excel.Interfaces.ChartSeriesLoadOptions

Provides options for which properties of the object to load.

Returns

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNames?: string | string[]): Excel.ChartSeries;

Parameters

propertyNames
string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns

Examples

// Rename the 1st series of Chart1 to "New Series Name"
Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    chart.series.getItemAt(0).name = "New Series Name";
    return ctx.sync().then(function() {
            console.log("Series1 Renamed");
    });
}).catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths?: {
            select?: string;
            expand?: string;
        }): Excel.ChartSeries;

Parameters

propertyNamesAndPaths
{ select?: string; expand?: string; }

propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.

Returns

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties: Interfaces.ChartSeriesUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parameters

properties
Interfaces.ChartSeriesUpdateData

A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.

options
OfficeExtension.UpdateOptions

Provides an option to suppress errors if the properties object tries to set any read-only properties.

Returns

void

Remarks

This method has the following additional signature:

set(properties: Excel.ChartSeries): void

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Excel.ChartSeries): void;

Parameters

properties
Excel.ChartSeries

Returns

void

setBubbleSizes(sourceData)

Set bubble sizes for a chart series. Only works for bubble charts.

[ API set: ExcelApi 1.7 ]

setBubbleSizes(sourceData: Range): void;

Parameters

sourceData
Range

The Range object corresponding to the source data.

Returns

void

setValues(sourceData)

Set values for a chart series. For scatter chart, it means Y axis values.

[ API set: ExcelApi 1.7 ]

setValues(sourceData: Range): void;

Parameters

sourceData
Range

The Range object corresponding to the source data.

Returns

void

Examples

await Excel.run(async (context) => {
  const sheet = context.workbook.worksheets.getItem("Sample");

  let seriesCollection = sheet.charts.getItemAt(0);
  let rangeSelection = sheet.getRange("C2:C7");
  let xRangeSelection = sheet.getRange("A1:A7");

  // Add a series.
  let newSeries = seriesCollection.series.add("Qtr2");
  newSeries.setValues(rangeSelection);
  newSeries.setXAxisValues(xRangeSelection);

  await context.sync();
});

setXAxisValues(sourceData)

Set values of X axis for a chart series. Only works for scatter charts.

[ API set: ExcelApi 1.7 ]

setXAxisValues(sourceData: Range): void;

Parameters

sourceData
Range

The Range object corresponding to the source data.

Returns

void

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.ChartSeries object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.ChartSeriesData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Excel.Interfaces.ChartSeriesData;

Returns