Word.Chart

Word.Chart is an object type of the Word module (Office.word(iframe)). 34 methods.

Remarks

• Module: Word · Office.word(iframe) · namespace Word
• Obtained from: Document.getChart(shapeId), Document.getCharts(options)
• Every method returns a Promise; signatures use TypeScript notation.

Methods

Method	Description
delete()	Deletes the shape.
getAxisTitle(axis)	Returns the title of the given axis.
getBody()	Returns the text area inside the shape.
getChartInfo()	Returns the chart's formatting state in one call.
getDataLabelPosition()	Returns the data label position.
getFill()	Returns the current fill settings of the shape.
getGridLine(axis)	Returns the gridline type of the given axis.
getHyperlink()	Returns the hyperlink information attached to the shape.
getId()	Returns the chart shape ID.
getLegendPosition()	Returns the legend position.
getLine()	Returns the current line settings of the shape.
getRange()	Returns the range of the position the shape occupies.
getTitle()	Returns the chart title.
getType()	Returns the chart type.
insertHyperlink(url, options)	Sets a hyperlink on the shape.
isEditable()	Returns whether this chart can be edited.
move(options)	Changes the position of a shape placed in front of or behind text.
removeHyperlink()	Removes the hyperlink from the shape.
resize(options)	Changes the size of the shape.
setAxisTitle(axis, title)	Sets the title of the given axis.
setDataLabelPosition(position)	Sets the data label position.
setFill(fill)	Sets the shape fill.
setGridLine(axis, gridType)	Sets the gridlines of the given axis.
setLegendPosition(position)	Sets the legend position.
setLine(options)	Sets the shape line.
setStyle(style)	Changes the chart's preset style.
setText(text)	Replaces the text content of the shape.
setTextMargin(options)	Sets the inner margins of the shape text area.
setTextVerticalAlign(align)	Sets the vertical alignment of the shape text.
setTitle(title)	Sets the chart title.
setType(chartType)	Changes the chart type.
setWrap(wrap)	Changes the wrap mode of the shape.
setZOrder(order)	Changes the z-order of a shape placed in front of or behind text.
updateHyperlink(options)	Updates the address or tooltip of the hyperlink attached to the shape.

Method details

delete()

Deletes the shape. - Both inline shapes and shapes placed in front of or behind text can be deleted.

delete(): Promise<void>;

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>

getBody()

Returns the text area inside the shape.

getBody(): Promise<Body>;

Returns

Promise<Body> - text area container, null if the shape is not a text box

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>

getFill()

Returns the current fill settings of the shape.
The return value can be passed to setFill() as-is.
A theme color fill or a radial gradient fill returns only type, so passing such a value back to setFill() fails.

getFill(): Promise<ShapeFill | null>;

Returns

Promise<ShapeFill | null> - fill information (same shape as the setFill input), null if there is no fill information

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>

getHyperlink()

Returns the hyperlink information attached to the shape. - A shape can have one hyperlink.

getHyperlink(): Promise<{ url: string; tooltip: string | null; linkType: HyperlinkType; anchor?: string } | null>;

Returns

Promise<{ url: string; tooltip: string | null; linkType: HyperlinkType; anchor?: string } | null> - link information, null if none. For a bookmark, url="#name" and anchor="name"

getId()

Returns the chart shape ID.

getId(): Promise<string>;

Returns

Promise<string> - chart shape ID (permanent GUID)

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>

getLine()

Returns the current line settings of the shape. - The return value can be passed to setLine() as-is.

getLine(): Promise<ShapeLine | null>;

Returns

Promise<ShapeLine | null> - line information (same shape as the setLine input), null if there is no line information

getRange()

Returns the range of the position the shape occupies. - The shape occupies a single character position, so start = end.

getRange(): Promise<Range>;

Returns

Promise<Range> - range of the shape position (errors at use time if the shape does not exist)

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

insertHyperlink(url, options)

Sets a hyperlink on the shape. - Replaces an existing link if present. Web address, email and bookmark are distinguished by URL format; a web address without a protocol gets https:// prepended.

insertHyperlink(url: string, options?: { tooltip?: string }): Promise<void>;

Parameters

Name	Type	Description
url	string	link destination
options (optional)	{ tooltip?: string }	additional options
options.tooltip (optional)	string	mouse-over tooltip (default: url)

Returns

none

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>

move(options)

Changes the position of a shape placed in front of or behind text.
x and y are pt coordinates relative to relativeFromH and relativeFromV; unspecified fields are kept.
A reference point must be given together with its coordinate, because changing the reference point changes the meaning of the coordinate.
If anchorParagraphId is given, the shape moves to that paragraph; otherwise only the position within the current paragraph changes.

move(options: { x?: number; y?: number; relativeFromH?: PositionRelativeFromH; relativeFromV?: PositionRelativeFromV; anchorParagraphId?: string }): Promise<void>;

Parameters

Name	Type	Description
options	{ x?: number; y?: number; relativeFromH?: PositionRelativeFromH; relativeFromV?: PositionRelativeFromV; anchorParagraphId?: string }	move options (x/y in pt). Omitted fields keep their current value

Returns

none

removeHyperlink()

Removes the hyperlink from the shape. - The shape itself is kept. Use getHyperlink() to check whether a link exists.

removeHyperlink(): Promise<void>;

Returns

none

resize(options)

Changes the size of the shape. - Specify at least one of width or height. The size of the unspecified dimension is kept.

resize(options: Size): Promise<void>;

Parameters

Name	Type	Description
options	Size	new size (pt). Each field is optional, at least one required; omitted axes keep their current value

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

setFill(fill)

Sets the shape fill.
For blipFill, give image as one of { src } (file name already uploaded to the server) / { url } (external image address) / { base64 }. url and base64 are uploaded to the server first and then applied, so the result must be awaited in every case - always call with await.
The input has the same shape as the getFill() return value (ShapeFill), so a read value can be re-applied as-is.

setFill(fill: ShapeFill): Promise<void>;

Parameters

Name	Type	Description
fill	ShapeFill	fill information (type determines which fields are valid)

Returns

none - no return value

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

setLine(options)

Sets the shape line. - Omitted = no change, null (color/dash/compound) = remove. null or a non-number for width is rejected (no "remove" meaning).

setLine(options: ShapeLine): Promise<void>;

Parameters

Name	Type	Description
options	ShapeLine	line options. Omitted = no change, null for color/dash/compound = remove

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

setText(text)

Replaces the text content of the shape.
For a plain shape, a new text area is created. Throws for shapes that cannot hold text, such as images.
An empty string clears the content.

setText(text: string): Promise<void>;

Parameters

Name	Type	Description
text	string	text to fill in ("" clears the content)

Returns

none

setTextMargin(options)

Sets the inner margins of the shape text area. - Specifies all four margins of a shape that has a text area.

setTextMargin(options: { left: number; top: number; right: number; bottom: number }): Promise<void>;

Parameters

Name	Type	Description
options	{ left: number; top: number; right: number; bottom: number }	four margins (pt, each ≥ 0)

Returns

none

setTextVerticalAlign(align)

Sets the vertical alignment of the shape text. - Applies only to shapes with a text area. If there is none, add text first with setText().

setTextVerticalAlign(align: TextVerticalAlign): Promise<void>;

Parameters

Name	Type	Description
align	TextVerticalAlign	"top"|"middle"|"bottom"

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

setWrap(wrap)

Changes the wrap mode of the shape. - Switches between inline with text and in front of / behind text.

setWrap(wrap: ShapeWrap): Promise<void>;

Parameters

Name	Type	Description
wrap	ShapeWrap	"inline"|"infront"|"behind"

Returns

none

setZOrder(order)

Changes the z-order of a shape placed in front of or behind text. - Specifying the same position for a shape already at the very front or back makes no change.

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

Parameters

Name	Type	Description
order	ShapeZOrder	"front"|"back"|"forward"|"backward"

Returns

none

updateHyperlink(options)

Updates the address or tooltip of the hyperlink attached to the shape. - Throws if there is no existing link. Unspecified fields are kept.

updateHyperlink(options: { url?: string; tooltip?: string }): Promise<void>;

Parameters

Name	Type	Description
options	{ url?: string; tooltip?: string }	items to update (at least one of url/tooltip)
options.url (optional)	string	new URL (web http(s):// · email mailto: · bookmark #name) (default: current value)
options.tooltip (optional)	string	new tooltip (default: current value)

Returns

none