Cell.Chart

Cell.Chart is an object type of the Spreadsheet module (Office.cell(iframe)). 22 methods.

Generated from the SDK type definitions

Spreadsheet · 6 object types · 156 methods · namespace Cell. This reference is generated from the API document artifact (sdk-api-doc.html) produced with the SDK build. Descriptions are the editor's API comments as published. Pin the SDK and Office versions together and regenerate when either changes.

Remarks

• Module: Spreadsheet · Office.cell(iframe) · namespace Cell
• Obtained from: Workbook.getObjectById(oid), Worksheet.addChart(chartType, dataRange, opts), Worksheet.getChart(oid)
• Every method returns a Promise; signatures use TypeScript notation.

Methods

Method	Description
delete()	Deletes the chart.
getAxisTitle(axis)	Returns the title of the given axis.
getDataLabelPosition()	Returns the data label position.
getDataRange()	Returns the cell range the chart uses as data, as an A1-notation string.
getGridLine(axis)	Returns the gridline type of the given axis.
getId()	Returns the unique ID that identifies this chart.
getInfo()	Returns the chart summary.
getLegendPosition()	Returns the legend position.
getState()	Returns the formatting state of the chart at once.
getTitle()	Returns the chart title.
getType()	Returns the chart type.
isEditable()	Returns whether this chart can be edited.
setAxisTitle(axis, title)	Sets the title of the given axis.
setDataLabelPosition(position)	Sets the data label position.
setDataRange(dataRange, seriesBy)	Changes the chart's data source range.
setGridLine(axis, gridType)	Sets the gridlines of the given axis.
setLegendPosition(position)	Sets the legend position.
setPosition(startCell)	Moves the top-left corner of the chart to the given cell.
setStyle(style)	Changes the chart's preset style.
setTitle(title)	Sets the chart title.
setType(chartType)	Changes the chart type.
switchRowColumn()	Switches the series direction by swapping the rows and columns of the data.

Method details

delete()

Deletes the chart.

delete(): Promise<CommandResult>;

Returns

Promise<CommandResult>

getAxisTitle(axis)

Returns the title of the given axis. It is an empty string when no title is set, and null for chart types that have no axis title (pie family, doughnut, radar).

getAxisTitle(axis: ChartAxis): Promise<string | null>;

Parameters

Name	Type	Description
axis	ChartAxis	axis to read the title from (horizontal or vertical)

Returns

Promise<string | null>

getDataLabelPosition()

Returns the data label position. A chart that does not show data labels returns "none".

getDataLabelPosition(): Promise<ChartDataLabelPosition>;

Returns

Promise<ChartDataLabelPosition>

getDataRange()

Returns the cell range the chart uses as data, as an A1-notation string. It returns null when the reference spans several sheets or does not combine into one rectangular area.

getDataRange(): Promise<string | null>;

Returns

Promise<string | null>

getGridLine(axis)

Returns the gridline type of the given axis. An axis with gridlines turned off is "none", and chart types that have no gridlines for that axis (both axes for the pie family and doughnut, the vertical axis for radar) return null.

getGridLine(axis: ChartAxis): Promise<ChartGridLineType | null>;

Parameters

Name	Type	Description
axis	ChartAxis	axis to read the gridlines from (horizontal or vertical)

Returns

Promise<ChartGridLineType | null>

getId()

Returns the unique ID that identifies this chart.

getId(): Promise<string>;

Returns

Promise<string>

getInfo()

Returns the chart summary. range follows the same contract as getDataRange.

getInfo(): Promise<ChartInfo>;

Returns

Promise<ChartInfo>

getLegendPosition()

Returns the legend position. A chart with the legend hidden is "none", and a chart whose position cannot be determined is reported as "right".

getLegendPosition(): Promise<ChartLegendPosition>;

Returns

Promise<ChartLegendPosition>

getState()

Returns the formatting state of the chart at once. Each value follows the same contract as the getter of the same name. null for axisTitle and gridLine means that chart type has no axis title or gridlines at all, while "none" means it can have them but they are turned off.

getState(): Promise<{ type: string; title: string; legendPosition: ChartLegendPosition; dataLabelPosition: ChartDataLabelPosition; axisTitle: { horizontal: string | null; vertical: string | null }; gridLine: { horizontal: ChartGridLineType | null; vertical: ChartGridLineType | null } }>;

Returns

Promise<{ type: string; title: string; legendPosition: ChartLegendPosition; dataLabelPosition: ChartDataLabelPosition; axisTitle: { horizontal: string | null; vertical: string | null }; gridLine: { horizontal: ChartGridLineType | null; vertical: ChartGridLineType | null } }>

getTitle()

Returns the chart title. It returns an empty string when no title is set.

getTitle(): Promise<string>;

Returns

Promise<string>

getType()

Returns the chart type. A type that is not in ChartType returns "unknown".

getType(): Promise<string>;

Returns

Promise<string>

isEditable()

Returns whether this chart can be edited. A chart sourced from external data can only be read, not edited.

isEditable(): Promise<boolean>;

Returns

Promise<boolean>

setAxisTitle(axis, title)

Sets the title of the given axis. Axis titles are supported by every chart type except the pie family, doughnut, and radar.

setAxisTitle(axis: ChartAxis, title: string): Promise<void>;

Parameters

Name	Type	Description
axis	ChartAxis	axis to set the title on (horizontal or vertical)
title	string	title to show on the axis

Returns

Promise<void>

setDataLabelPosition(position)

Sets the data label position. Passing "none" hides the data labels. The available positions differ by chart type, and "none" works for every type.

setDataLabelPosition(position: ChartDataLabelPosition): Promise<void>;

Parameters

Name	Type	Description
position	ChartDataLabelPosition	where to put the data labels

Returns

Promise<void>

setDataRange(dataRange, seriesBy)

Changes the chart's data source range. Up to 100 rows and 100 columns are supported. Omitting seriesBy keeps the current series direction.

setDataRange(
  dataRange: string | RangeCoords,
  seriesBy?: "auto" | "rows" | "columns"
): Promise<void>;

Parameters

Name	Type	Description
dataRange	string | RangeCoords	new data range; an A1-notation string also works ("A1:B2", or "E10" for a single cell)
seriesBy (optional)	"auto" | "rows" | "columns"	series direction; rows makes one row a series, columns makes one column a series, and auto decides from the shape of the new range. Scatter and bubble charts do not accept rows or columns

Returns

Promise<void>

setGridLine(axis, gridType)

Sets the gridlines of the given axis. Passing "none" hides the gridlines of that axis. Chart types that have no gridlines for that axis (both axes for the pie family and doughnut, the vertical axis for radar) raise an error for any value, "none" included.

setGridLine(axis: ChartAxis, gridType: ChartGridLineType): Promise<void>;

Parameters

Name	Type	Description
axis	ChartAxis	axis to set the gridlines on (horizontal or vertical)
gridType	ChartGridLineType	gridline type to show

Returns

Promise<void>

setLegendPosition(position)

Sets the legend position. Passing "none" hides the legend.

setLegendPosition(position: ChartLegendPosition): Promise<void>;

Parameters

Name	Type	Description
position	ChartLegendPosition	where to put the legend

Returns

Promise<void>

setPosition(startCell)

Moves the top-left corner of the chart to the given cell. The size stays. When startCell is a range of several cells, only its top-left cell is used and the rest is ignored.

setPosition(startCell: string | RangeCoords): Promise<void>;

Parameters

Name	Type	Description
startCell	string | RangeCoords	cell to move to; an A1-notation string also works ("A1:B2", or "E10" for a single cell)

Returns

Promise<void>

setStyle(style)

Changes the chart's preset style. The actual colors behind a number follow the document theme.

setStyle(style: number): Promise<void>;

Parameters

Name	Type	Description
style	number	style number (integer 1-12); the numbers form color groups of three (1-3, 4-6, 7-9, 10-12), and the three numbers inside a group differ only in background (translucent background, white background, colored background with series borders, in that order)

Returns

Promise<void>

setTitle(title)

Sets the chart title.

setTitle(title: string): Promise<void>;

Parameters

Name	Type	Description
title	string	title to show on the chart

Returns

Promise<void>

setType(chartType)

Changes the chart type. Passing the current type changes nothing.

setType(chartType: ChartType): Promise<void>;

Parameters

Name	Type	Description
chartType	ChartType	chart type to change to (enum string, for example "clustered_column")

Returns

Promise<void>

switchRowColumn()

Switches the series direction by swapping the rows and columns of the data. The direction alternates on each call. Scatter and bubble charts cannot be switched, and neither can a chart with no data range or with more than 100 rows or columns.

switchRowColumn(): Promise<void>;

Returns

Promise<void>