Show.Chart

Show.Chart is an object type of the Presentation module (Office.show(iframe)). 50 methods.

Remarks

• Module: Presentation · Office.show(iframe) · namespace Show
• Obtained from: Document.findCharts(slides, filter), Slide.findCharts(filter)
• Every method returns a Promise; signatures use TypeScript notation.

Methods

Method	Description
align(alignType)	Aligns the shape relative to the slide.
flip(direction)	Flips the shape vertically or horizontally.
getAxisTitle(axis)	Returns the title of the given axis.
getChartInfo()	Returns the chart's formatting state in one call.
getDataLabelPosition()	Returns the data label position.
getGridLine(axis)	Returns the gridline type of the given axis.
getHeight()	Returns the shape's height.
getHyperlink()	Returns the hyperlink set on the shape.
getLegendPosition()	Returns the legend position.
getPlaceholderType()	Returns the placeholder type of the shape.
getPresetId()	Returns the shape's OOXML preset id (prst).
getRotation()	Returns the rotation angle of the shape.
getTitle()	Returns the chart title.
getTransform()	Returns the position, size, and rotation of the shape.
getType()	Returns the chart type.
getWidth()	Returns the shape's width.
getX()	Returns the shape's X coordinate.
getY()	Returns the shape's Y coordinate.
getZOrderIndex()	Returns the z-order index of the shape within its parent (the slide, or the group for a group child).
hasText()	Returns whether the shape contains text.
isChart()	Checks whether this handle is a Chart (a type guard for union narrowing).
isControl()	Checks whether this handle is a Control (a type guard for union narrowing).
isDiagram()	Checks whether this handle is a Diagram (a type guard for union narrowing).
isEditable()	Returns whether this chart can be edited.
isFlippedH()	Returns whether the shape is flipped horizontally.
isFlippedV()	Returns whether the shape is flipped vertically.
isGroup()	Checks whether this handle is a Group (a type guard for union narrowing).
isImage()	Checks whether this handle is an Image (a type guard for union narrowing).
isLine()	Checks whether this handle is a Line (a type guard for union narrowing).
isOleObject()	Checks whether this handle is an OleObject (a type guard for union narrowing).
isPlaceholder()	Returns whether the shape is a placeholder (title, body frame, etc.).
isShape()	Checks whether this handle is a Shape (a type guard for union narrowing).
isTable()	Checks whether this handle is a Table (a type guard for union narrowing).
moveBy(distance)	Moves the shape by x, y relative to its current position.
removeHyperlink()	Removes the shape's hyperlink.
reorder(order)	Changes the shape's z-order (forward/backward).
setAxisTitle(axis, title)	Sets the title of the given axis.
setDataLabelPosition(position)	Sets the data label position.
setGridLine(axis, gridType)	Sets the gridlines of the given axis.
setHeight(height)	Sets the height of the shape.
setHyperlink(hyperlink)	Sets a hyperlink on the shape (counterpart of getHyperlink; the returned object can be passed back to copy a hyperlink).
setLegendPosition(position)	Sets the legend position.
setRotation(rotation)	Sets the rotation angle of the shape as an absolute value.
setStyle(style)	Changes the chart's preset style.
setTitle(title)	Sets the chart title.
setTransform(transform)	Sets the position, size, and rotation of the shape in one call.
setType(chartType)	Changes the chart type.
setWidth(width)	Sets the width of the shape.
setX(x)	Sets the X coordinate of the shape as an absolute value.
setY(y)	Sets the Y coordinate of the shape as an absolute value.

Method details

align(alignType)

Aligns the shape relative to the slide. Ignored for shapes that cannot be moved. Group children also move relative to the slide, not within the group (same as the editor). If a child moves outside its group, the group grows to contain it.

align(alignType: AlignType): Promise<void>;

Parameters

Name	Type	Description
alignType	AlignType	Alignment type

Returns

none

flip(direction)

Flips the shape vertically or horizontally. This toggles the current flip state; read whether it is currently flipped with isFlippedH()/isFlippedV(). Ignored for shapes that cannot be rotated. For a rotated shape the angle is mirrored as well (getRotation() becomes 360 - previous angle).

flip(direction: FlipDirection): Promise<void>;

Parameters

Name	Type	Description
direction	FlipDirection	Flip direction

Returns

none

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's formatting state in one call. Each value matches the getter of the same name.

getChartInfo(): Promise<ChartFormatInfo>;

Returns

Promise<ChartFormatInfo>

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>

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>

getHeight()

Returns the shape's height. (Symmetric with setHeight.)

getHeight(): Promise<number | null>;

Returns

Promise<number | null> - Height (px). null if the target shape is gone

getHyperlink()

Returns the hyperlink set on the shape. The returned object can be passed to setHyperlink as is. Returns null if an unsupported kind (run program, macro, etc.) is attached. Only the click hyperlink (hlinkClick) is read; it is the same target as setHyperlink/removeHyperlink, so a get → set round trip holds (hover-only links are outside this API layer). Text links attached per run are read with Shape.getTextHyperlink.

getHyperlink(): Promise<Hyperlink | null>;

Returns

Promise<Hyperlink | null> - Hyperlink information. null if there is no hyperlink (action)

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>

getPlaceholderType()

Returns the placeholder type of the shape.

getPlaceholderType(): Promise<PlaceholderType | null>;

Returns

Promise<PlaceholderType | null> - Placeholder type. null if the shape is not a placeholder or the target shape is gone

getPresetId()

Returns the shape's OOXML preset id (prst).

getPresetId(): Promise<string | null>;

Returns

Promise<string | null> - Preset id (prst); null if none

getRotation()

Returns the rotation angle of the shape. (counterpart of setRotation)

getRotation(): Promise<number | null>;

Returns

Promise<number | null> - Rotation angle (degrees). null if the target shape is gone

getTitle()

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

getTitle(): Promise<string>;

Returns

Promise<string>

getTransform()

Returns the position, size, and rotation of the shape. x/y are the top-left corner of the shape regardless of flip, so passing the returned value to another shape's setTransform places both shapes at the same spot. Values are rounded to the editor's input units - size to one decimal place, position to integers. The setters use the same units, so shapes placed more finely (e.g. imported documents) move by that amount when the value is passed back.

getTransform(): Promise<ShapeTransform | null>;

Returns

Promise<ShapeTransform | null> - Position, size, and rotation of the shape. null if the target shape is gone (e.g. deleted during collaboration)

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">

getWidth()

Returns the shape's width. (Symmetric with setWidth.)

getWidth(): Promise<number | null>;

Returns

Promise<number | null> - Width (px). null if the target shape is gone

getX()

Returns the shape's X coordinate. (Symmetric with setX.)

getX(): Promise<number | null>;

Returns

Promise<number | null> - X coordinate (px). null if the target shape is gone

getY()

Returns the shape's Y coordinate. (Symmetric with setY.)

getY(): Promise<number | null>;

Returns

Promise<number | null> - Y coordinate (px). null if the target shape is gone

getZOrderIndex()

Returns the z-order index of the shape within its parent (the slide, or the group for a group child). 0 is the back; larger values are further to the front.

getZOrderIndex(): Promise<number | null>;

Returns

Promise<number | null> - z-order index. null if the target shape is gone

hasText()

Returns whether the shape contains text. Uses the same criterion the editor uses for empty text - true when there is only whitespace or two or more empty paragraphs (only line breaks), false when there is a single empty paragraph. Kinds without shape-level text (table, group, chart) are always false. (query tables per cell)

hasText(): Promise<boolean | null>;

Returns

Promise<boolean | null> - Whether text exists. null if the target shape is gone

isChart()

Checks whether this handle is a Chart (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isChart(): Promise<this is Chart>;

Returns

Promise<this is Chart>

isControl()

Checks whether this handle is a Control (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isControl(): Promise<this is Control>;

Returns

Promise<this is Control>

isDiagram()

Checks whether this handle is a Diagram (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isDiagram(): Promise<this is Diagram>;

Returns

Promise<this is Diagram>

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>

isFlippedH()

Returns whether the shape is flipped horizontally. (calling flip(FlipDirection.HORIZONTAL) toggles this value)

isFlippedH(): Promise<boolean | null>;

Returns

Promise<boolean | null> - Horizontal flip state. null if the target shape is gone

isFlippedV()

Returns whether the shape is flipped vertically. (calling flip(FlipDirection.VERTICAL) toggles this value)

isFlippedV(): Promise<boolean | null>;

Returns

Promise<boolean | null> - Vertical flip state. null if the target shape is gone

isGroup()

Checks whether this handle is a Group (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isGroup(): Promise<this is Group>;

Returns

Promise<this is Group>

isImage()

Checks whether this handle is an Image (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isImage(): Promise<this is Image>;

Returns

Promise<this is Image>

isLine()

Checks whether this handle is a Line (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isLine(): Promise<this is Line>;

Returns

Promise<this is Line>

isOleObject()

Checks whether this handle is an OleObject (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isOleObject(): Promise<this is OleObject>;

Returns

Promise<this is OleObject>

isPlaceholder()

Returns whether the shape is a placeholder (title, body frame, etc.).

isPlaceholder(): Promise<boolean | null>;

Returns

Promise<boolean | null> - Placeholder state. null if the target shape is gone

isShape()

Checks whether this handle is a Shape (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isShape(): Promise<this is Shape>;

Returns

Promise<this is Shape>

isTable()

Checks whether this handle is a Table (a type guard for union narrowing). Synchronously inspects the SDK handle's internal discriminator - no postMessage round trip, no await needed.

isTable(): Promise<this is Table>;

Returns

Promise<this is Table>

moveBy(distance)

Moves the shape by x, y relative to its current position. (Absolute placement is setX / setY.)

moveBy(distance: ShapeMoveDistance): Promise<void>;

Parameters

Name	Type	Description
distance	ShapeMoveDistance	Distance to move (px)

Returns

none

removeHyperlink()

Removes the shape's hyperlink. Text links attached per run are removed with Shape.removeTextHyperlink.

removeHyperlink(): Promise<void>;

Returns

none

reorder(order)

Changes the shape's z-order (forward/backward). Ignored if it is already at the target position.

reorder(order: ShapeZOrder): Promise<void>;

Parameters

Name	Type	Description
order	ShapeZOrder	Reorder type

Returns

none

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

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

setHeight(height)

Sets the height of the shape. Ignored for shapes that cannot be resized.

setHeight(height: number): Promise<void>;

Parameters

Name	Type	Description
height	number	Height (px, rounded to one decimal place)

Returns

none

setHyperlink(hyperlink)

Sets a hyperlink on the shape (counterpart of getHyperlink; the returned object can be passed back to copy a hyperlink). Unsupported kinds and invalid targets (such as a deleted slide) are ignored. Text links attached per run are set with Shape.setTextHyperlink.

setHyperlink(hyperlink: Hyperlink): Promise<void>;

Parameters

Name	Type	Description
hyperlink	Hyperlink	The same Hyperlink object as returned by getHyperlink(). Ignored if type is missing

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

setRotation(rotation)

Sets the rotation angle of the shape as an absolute value. Ignored for shapes that cannot be rotated. (counterpart of getRotation)

setRotation(rotation: number): Promise<void>;

Parameters

Name	Type	Description
rotation	number	Rotation angle (degrees)

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

setTransform(transform)

Sets the position, size, and rotation of the shape in one call. The value returned by getTransform() can be passed as is. (counterpart of getTransform) Only the fields given a value are applied, in the order size → position → rotation; omitted fields keep their current value. As with the individual setters, each field is ignored on shapes that do not support that operation (resize/move/rotate).

setTransform(transform?: Partial<ShapeTransform>): Promise<void>;

Parameters

Name	Type	Description
transform (optional)	Partial<ShapeTransform>	Position/size (px) · rotation (degrees)

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

setWidth(width)

Sets the width of the shape. Ignored for shapes that cannot be resized.

setWidth(width: number): Promise<void>;

Parameters

Name	Type	Description
width	number	Width (px, rounded to one decimal place)

Returns

none

setX(x)

Sets the X coordinate of the shape as an absolute value. Ignored for shapes that cannot be moved. (use moveBy for a relative move)

setX(x: number): Promise<void>;

Parameters

Name	Type	Description
x	number	X coordinate (px, rounded to an integer)

Returns

none

setY(y)

Sets the Y coordinate of the shape as an absolute value. Ignored for shapes that cannot be moved.

setY(y: number): Promise<void>;

Parameters

Name	Type	Description
y	number	Y coordinate (px, rounded to an integer)

Returns

none