Excel.ChartSeries class
Represents a series in a chart.
- Extends
Remarks
Properties
chart |
Represents the chart type of a series. See |
context | The request context associated with the object. This connects the add-in's process to the Office host application's process. |
doughnut |
Represents the doughnut hole size of a chart series. Only valid on doughnut and doughnut exploded charts. Throws an |
filtered | Specifies if the series is filtered. Not applicable for surface charts. |
format | Represents the formatting of a chart series, which includes fill and line formatting. |
gap |
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. |
has |
Specifies if the series has data labels. |
marker |
Specifies the marker background color of a chart series. |
marker |
Specifies the marker foreground color of a chart series. |
marker |
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. |
marker |
Specifies the marker style of a chart series. See |
name | Specifies the name of a series in a chart. The name's length should not be greater than 255 characters. |
plot |
Specifies the plot order of a chart series within the chart group. |
points | Returns a collection of all points in the series. |
show |
Specifies if the series has a shadow. |
smooth | Specifies if the series is smooth. Only applicable to line and scatter charts. |
trendlines | The collection of trendlines in the series. |
Methods
delete() | Deletes the chart series. |
load(options) | Queues up a command to load the specified properties of the object. You must call |
load(property |
Queues up a command to load the specified properties of the object. You must call |
load(property |
Queues up a command to load the specified properties of the object. You must call |
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. |
set |
Sets the bubble sizes for a chart series. Only works for bubble charts. |
set |
Sets the values for a chart series. For scatter charts, it refers to y-axis values. |
set |
Sets the values of the x-axis for a chart series. |
toJSON() | Overrides the JavaScript |
Property Details
chartType
Represents the chart type of a series. See Excel.ChartType
for details.
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"
Remarks
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
doughnutHoleSize
Represents the doughnut hole size of a chart series. Only valid on doughnut and doughnut exploded charts. Throws an InvalidArgument
error on invalid charts.
doughnutHoleSize: number;
Property Value
number
Remarks
filtered
Specifies if the series is filtered. Not applicable for surface charts.
filtered: boolean;
Property Value
boolean
Remarks
format
Represents the formatting of a chart series, which includes fill and line formatting.
readonly format: Excel.ChartSeriesFormat;
Property Value
Remarks
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.
gapWidth: number;
Property Value
number
Remarks
hasDataLabels
Specifies if the series has data labels.
hasDataLabels: boolean;
Property Value
boolean
Remarks
markerBackgroundColor
Specifies the marker background color of a chart series.
markerBackgroundColor: string;
Property Value
string
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-series-markers.yaml
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
Specifies the marker foreground color of a chart series.
markerForegroundColor: string;
Property Value
string
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-series-markers.yaml
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
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.
markerSize: number;
Property Value
number
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-series-markers.yaml
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
Specifies the marker style of a chart series. See Excel.ChartMarkerStyle
for details.
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"
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-series-markers.yaml
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
Specifies the name of a series in a chart. The name's length should not be greater than 255 characters.
name: string;
Property Value
string
Remarks
plotOrder
Specifies the plot order of a chart series within the chart group.
plotOrder: number;
Property Value
number
Remarks
points
Returns a collection of all points in the series.
readonly points: Excel.ChartPointsCollection;
Property Value
Remarks
showShadow
Specifies if the series has a shadow.
showShadow: boolean;
Property Value
boolean
Remarks
smooth
Specifies if the series is smooth. Only applicable to line and scatter charts.
smooth: boolean;
Property Value
boolean
Remarks
trendlines
The collection of trendlines in the series.
readonly trendlines: Excel.ChartTrendlineCollection;
Property Value
Remarks
Method Details
delete()
Deletes the chart series.
delete(): void;
Returns
void
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-series.yaml
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();
});
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
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".
await Excel.run(async (context) => {
const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");
chart.series.getItemAt(0).name = "New Series Name";
await context.sync();
console.log("Series1 Renamed");
});
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
- Excel.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
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)
Sets the bubble sizes for a chart series. Only works for bubble charts.
setBubbleSizes(sourceData: Range): void;
Parameters
- sourceData
- Excel.Range
The Range
object corresponding to the source data.
Returns
void
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-bubble-chart.yaml
await Excel.run(async (context) => {
/*
The table is expected to look like this:
Product, Inventory, Price, Current Market Share
Calamansi, 2000, $2.45, 10%
...
We want each bubble to represent a single row.
*/
// Get the worksheet and table data.
const sheet = context.workbook.worksheets.getItem("Sample");
const table = sheet.tables.getItem("Sales");
const dataRange = table.getDataBodyRange();
// Get the table data without the row names.
const valueRange = dataRange.getOffsetRange(0, 1).getResizedRange(0, -1);
// Create the chart.
const bubbleChart = sheet.charts.add(Excel.ChartType.bubble, valueRange);
bubbleChart.name = "Product Chart";
// Remove the default series, since we want a unique series for each row.
bubbleChart.series.getItemAt(0).delete();
// Load the data necessary to make a chart series.
dataRange.load(["rowCount", "values"]);
await context.sync();
// For each row, create a chart series (a bubble).
for (let i = 0; i < dataRange.rowCount; i++) {
const newSeries = bubbleChart.series.add(dataRange.values[i][0], i);
newSeries.setXAxisValues(dataRange.getCell(i, 1));
newSeries.setValues(dataRange.getCell(i, 2));
newSeries.setBubbleSizes(dataRange.getCell(i, 3));
// Show the product name and market share percentage.
newSeries.dataLabels.showSeriesName = true;
newSeries.dataLabels.showBubbleSize = true;
newSeries.dataLabels.showValue = false;
}
await context.sync();
});
setValues(sourceData)
Sets the values for a chart series. For scatter charts, it refers to y-axis values.
setValues(sourceData: Range): void;
Parameters
- sourceData
- Excel.Range
The Range
object corresponding to the source data.
Returns
void
Remarks
Examples
// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/10-chart/chart-series.yaml
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)
Sets the values of the x-axis for a chart series.
setXAxisValues(sourceData: Range): void;
Parameters
- sourceData
- Excel.Range
The Range
object corresponding to the source data.
Returns
void
Remarks
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
Office Add-ins