Word.Shape
Word.Shape is an object type of the Word module (Office.word(iframe)). 18 methods.
Word · 14 object types · 259 methods · namespace Word. 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: Word ·
Office.word(iframe)· namespaceWord - Obtained from:
Document.getShape(shapeId),Document.getShapes(options),Paragraph.insertShape(preset, options),Range.getShapes(),Range.insertShape(preset, options) - Every method returns a
Promise; signatures use TypeScript notation.
Methods
| Method | Description |
|---|---|
delete() | Deletes the shape. |
getBody() | Returns the text area inside the shape. |
getFill() | Returns the current fill settings of the shape. |
getHyperlink() | Returns the hyperlink information attached to the shape. |
getLine() | Returns the current line settings of the shape. |
getRange() | Returns the range of the position the shape occupies. |
insertHyperlink(url, options) | Sets a hyperlink on the shape. |
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. |
setFill(fill) | Sets the shape fill. |
setLine(options) | Sets the shape line. |
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. |
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
Promise<void>
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
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
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"
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)
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
Promise<void>
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
Promise<void>
removeHyperlink()
Removes the hyperlink from the shape. - The shape itself is kept. Use getHyperlink() to check whether a link exists.
removeHyperlink(): Promise<void>;
Returns
Promise<void>
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
Promise<void>
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
Promise<void> - no return value
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
Promise<void>
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
Promise<void>
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
Promise<void>
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
Promise<void>
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
Promise<void>
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
Promise<void>
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
Promise<void>