Cell.Chart
Cell.Chart is an object type of the Spreadsheet module (Office.cell(iframe)). 21 methods.
Remarks
- Module: Spreadsheet ·
Office.cell(iframe)· namespaceCell - Obtained from:
Workbook.getObjectById(oid),Worksheet.addChart(chartType, dataRange, seriesBy),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. |
getChartInfo() | Returns the chart type, title, legend, data label, axis title, and gridline state, along with the identifier and data range, in a single call. |
getDataLabelPosition() | Returns the data label position. |
getDataRange() | Returns the cell range that the chart uses as data, as an A1 notation string prefixed with the sheet name ("Sheet1!A1:C5"). |
getGridLine(axis) | Returns the gridline type of the given axis. |
getId() | Returns the unique ID that identifies this chart. |
getLegendPosition() | Returns the legend position. |
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 data source range of the chart. |
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 specified 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>
getChartInfo()
Returns the chart type, title, legend, data label, axis title, and gridline state, along with the identifier and data range, in a single call. Each format value matches the getter of the same name.
getChartInfo(): Promise<ChartInfo>;
Returns
Promise<ChartInfo>
getDataLabelPosition()
Returns the data label position. "none" for a chart with no data labels set, and null for chart types that have no data labels (surface charts).
getDataLabelPosition(): Promise<ChartDataLabelPosition | null>;
Returns
Promise<ChartDataLabelPosition | null>
getDataRange()
Returns the cell range that the chart uses as data, as an A1 notation string prefixed with the sheet name ("Sheet1!A1:C5"). Returns null if the references span multiple sheets or cannot be merged into a single rectangular range.
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>
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>
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. For 100% stacked bar/column and bubble charts loaded from a file, the name of that type (not in ChartType) is returned; any other type not in ChartType is returned as "unknown".
getType(): Promise<ChartType | "percent_stacked_column" | "percent_stacked_bar" | "bubble" | "3d_bubble" | "unknown">;
Returns
Promise<ChartType | "percent_stacked_column" | "percent_stacked_bar" | "bubble" | "3d_bubble" | "unknown">
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 for all chart types except pie-family, doughnut, and radar charts. Passing an empty string clears the axis title.
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. Up to 255 characters |
Returns
none
setDataLabelPosition(position)
Sets the data label position. Passing "none" removes the data labels. Data labels can only be set on 2-D charts (excluding pie-of-pie, stock, and surface charts); 3-D charts are not supported yet. The available positions depend on the chart type.
setDataLabelPosition(position: ChartDataLabelPosition): Promise<void>;
Parameters
| Name | Type | Description |
|---|---|---|
position | ChartDataLabelPosition | where to put the data labels |
Returns
none
setDataRange(dataRange, seriesBy)
Changes the data source range of the chart. Up to 100 rows and 100 columns are supported. If no sheet is specified, the range is treated as a range on the sheet that the chart is on. If seriesBy is omitted, the current series direction is kept.
setDataRange(
dataRange: string | SheetRangeCoords | RangeCoords,
seriesBy?: ChartSeriesBy
): Promise<void>;
Parameters
| Name | Type | Description |
|---|---|---|
dataRange | string | SheetRangeCoords | RangeCoords | new data range. An A1 notation string is also accepted ("A1:B2", "E10" for a single cell, or "Sheet2!A1:C5" for another sheet). A string accepts only one range (multiple ranges such as "A1:B2,D1:E2" are not accepted) |
seriesBy (optional) | ChartSeriesBy | series direction. With AUTO, the direction is determined by the shape of the new range |
Returns
none
setGridLine(axis, gridType)
Sets the gridlines of the given axis. Passing "none" hides that axis's gridlines. Gridlines are supported for chart types that have gridlines on that axis (pie-family and doughnut charts have neither axis; radar charts have no vertical axis).
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
none
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
none
setPosition(startCell)
Moves the top-left corner of the chart to the specified cell. The size is kept as is. If a range of multiple cells is passed as startCell, only the top-left cell of that range is used and the rest is ignored.
setPosition(startCell: string | RangeCoords): Promise<void>;
Parameters
| Name | Type | Description |
|---|---|---|
startCell | string | RangeCoords | cell to move the chart to. An A1 notation string is also accepted ("A1:B2", or "E10" for a single cell) |
Returns
none
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
none
setTitle(title)
Sets the chart title. Passing an empty string clears the title.
setTitle(title: string): Promise<void>;
Parameters
| Name | Type | Description |
|---|---|---|
title | string | Title to show on the chart. Up to 255 characters |
Returns
none
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
none
switchRowColumn()
Switches the series direction by swapping the rows and columns of the data. The direction alternates each time this is called. Scatter and bubble charts and charts without a data range cannot be switched. Up to 100 rows and 100 columns are supported.
switchRowColumn(): Promise<void>;
Returns
none