Word.InlinePicture class

Represents an inline picture.

[ API set: WordApi 1.1 ]

Extends
OfficeExtension.ClientObject

Properties

altTextDescription

Gets or sets a string that represents the alternative text associated with the inline image.

[ API set: WordApi 1.1 ]

altTextTitle

Gets or sets a string that contains the title for the inline image.

[ API set: WordApi 1.1 ]

height

Gets or sets a number that describes the height of the inline image.

[ API set: WordApi 1.1 ]

hyperlink

Gets or sets a hyperlink on the image. Use a '#' to separate the address part from the optional location part.

[ API set: WordApi 1.1 ]

lockAspectRatio

Gets or sets a value that indicates whether the inline image retains its original proportions when you resize it.

[ API set: WordApi 1.1 ]

paragraph

Gets the parent paragraph that contains the inline image. Read-only.

[ API set: WordApi 1.2 ]

parentContentControl

Gets the content control that contains the inline image. Throws if there isn't a parent content control. Read-only.

[ API set: WordApi 1.1 ]

parentContentControlOrNullObject

Gets the content control that contains the inline image. Returns a null object if there isn't a parent content control. Read-only.

[ API set: WordApi 1.3 ]

parentTable

Gets the table that contains the inline image. Throws if it is not contained in a table. Read-only.

[ API set: WordApi 1.3 ]

parentTableCell

Gets the table cell that contains the inline image. Throws if it is not contained in a table cell. Read-only.

[ API set: WordApi 1.3 ]

parentTableCellOrNullObject

Gets the table cell that contains the inline image. Returns a null object if it is not contained in a table cell. Read-only.

[ API set: WordApi 1.3 ]

parentTableOrNullObject

Gets the table that contains the inline image. Returns a null object if it is not contained in a table. Read-only.

[ API set: WordApi 1.3 ]

width

Gets or sets a number that describes the width of the inline image.

[ API set: WordApi 1.1 ]

Methods

delete()

Deletes the inline picture from the document.

[ API set: WordApi 1.2 ]

getBase64ImageSrc()

Gets the base64 encoded string representation of the inline image.

[ API set: WordApi 1.1 ]

getNext()

Gets the next inline image. Throws if this inline image is the last one.

[ API set: WordApi 1.3 ]

getNextOrNullObject()

Gets the next inline image. Returns a null object if this inline image is the last one.

[ API set: WordApi 1.3 ]

getRange(rangeLocation)

Gets the picture, or the starting or ending point of the picture, as a range.

[ API set: WordApi 1.3 ]

insertBreak(breakType, insertLocation)

Inserts a break at the specified location in the main document. The insertLocation value can be 'Before' or 'After'.

[ API set: WordApi 1.2 ]

insertContentControl()

Wraps the inline picture with a rich text content control.

[ API set: WordApi 1.1 ]

insertFileFromBase64(base64File, insertLocation)

Inserts a document at the specified location. The insertLocation value can be 'Before' or 'After'.

[ API set: WordApi 1.2 ]

insertHtml(html, insertLocation)

Inserts HTML at the specified location. The insertLocation value can be 'Before' or 'After'.

[ API set: WordApi 1.2 ]

insertInlinePictureFromBase64(base64EncodedImage, insertLocation)

Inserts an inline picture at the specified location. The insertLocation value can be 'Replace', 'Before', or 'After'.

[ API set: WordApi 1.2 ]

insertOoxml(ooxml, insertLocation)

Inserts OOXML at the specified location. The insertLocation value can be 'Before' or 'After'.

[ API set: WordApi 1.2 ]

insertParagraph(paragraphText, insertLocation)

Inserts a paragraph at the specified location. The insertLocation value can be 'Before' or 'After'.

[ API set: WordApi 1.2 ]

insertText(text, insertLocation)

Inserts text at the specified location. The insertLocation value can be 'Before' or 'After'.

[ API set: WordApi 1.2 ]

load(option)

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

select(selectionMode)

Selects the inline picture. This causes Word to scroll to the selection.

[ API set: WordApi 1.2 ]

toJSON()
track()

Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you are using this object across ".sync" calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you needed to have added the object to the tracked object collection when the object was first created.

untrack()

Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You will need to call "context.sync()" before the memory release takes effect.

Property Details

altTextDescription

Gets or sets a string that represents the alternative text associated with the inline image.

[ API set: WordApi 1.1 ]

altTextDescription: string;
Property Value
string

altTextTitle

Gets or sets a string that contains the title for the inline image.

[ API set: WordApi 1.1 ]

altTextTitle: string;
Property Value
string

height

Gets or sets a number that describes the height of the inline image.

[ API set: WordApi 1.1 ]

height: number;
Property Value
number

Gets or sets a hyperlink on the image. Use a '#' to separate the address part from the optional location part.

[ API set: WordApi 1.1 ]

hyperlink: string;
Property Value
string

lockAspectRatio

Gets or sets a value that indicates whether the inline image retains its original proportions when you resize it.

[ API set: WordApi 1.1 ]

lockAspectRatio: boolean;
Property Value
boolean

paragraph

Gets the parent paragraph that contains the inline image. Read-only.

[ API set: WordApi 1.2 ]

readonly paragraph: Word.Paragraph;
Property Value
Word.Paragraph

parentContentControl

Gets the content control that contains the inline image. Throws if there isn't a parent content control. Read-only.

[ API set: WordApi 1.1 ]

readonly parentContentControl: Word.ContentControl;
Property Value

parentContentControlOrNullObject

Gets the content control that contains the inline image. Returns a null object if there isn't a parent content control. Read-only.

[ API set: WordApi 1.3 ]

readonly parentContentControlOrNullObject: Word.ContentControl;
Property Value

parentTable

Gets the table that contains the inline image. Throws if it is not contained in a table. Read-only.

[ API set: WordApi 1.3 ]

readonly parentTable: Word.Table;
Property Value
Word.Table

parentTableCell

Gets the table cell that contains the inline image. Throws if it is not contained in a table cell. Read-only.

[ API set: WordApi 1.3 ]

readonly parentTableCell: Word.TableCell;
Property Value
Word.TableCell

parentTableCellOrNullObject

Gets the table cell that contains the inline image. Returns a null object if it is not contained in a table cell. Read-only.

[ API set: WordApi 1.3 ]

readonly parentTableCellOrNullObject: Word.TableCell;
Property Value
Word.TableCell

parentTableOrNullObject

Gets the table that contains the inline image. Returns a null object if it is not contained in a table. Read-only.

[ API set: WordApi 1.3 ]

readonly parentTableOrNullObject: Word.Table;
Property Value
Word.Table

width

Gets or sets a number that describes the width of the inline image.

[ API set: WordApi 1.1 ]

width: number;
Property Value
number

Method Details

delete()

Deletes the inline picture from the document.

[ API set: WordApi 1.2 ]

delete(): void;
Returns
void

getBase64ImageSrc()

Gets the base64 encoded string representation of the inline image.

[ API set: WordApi 1.1 ]

getBase64ImageSrc(): OfficeExtension.ClientResult<string>;
Returns
OfficeExtension.ClientResult<string>

Examples

await Word.run(async (context) => {
    const firstPicture = context.document.body.inlinePictures.getFirst();
    firstPicture.load("width, height");

    await context.sync();
    console.log(`Image dimensions: ${firstPicture.width} x ${firstPicture.height}`);
    //To get the image encoded as base64:
    const base64 = firstPicture.getBase64ImageSrc();

    await context.sync();
    console.log(base64.value);
});

getNext()

Gets the next inline image. Throws if this inline image is the last one.

[ API set: WordApi 1.3 ]

getNext(): Word.InlinePicture;
Returns

Examples

// To use this snippet, add an inline picture to the document and assign it an alt text title.
// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the first inline picture.
    var firstPicture = context.document.body.inlinePictures.getFirstOrNullObject();

    // Queue a command to load the alternative text title of the picture.
    context.load(firstPicture, 'altTextTitle');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {
        if (firstPicture.isNullObject) {
            console.log('There are inline pictures in this document.')
        } else {
            console.log(firstPicture.altTextTitle);
        }
    });   
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

getNextOrNullObject()

Gets the next inline image. Returns a null object if this inline image is the last one.

[ API set: WordApi 1.3 ]

getNextOrNullObject(): Word.InlinePicture;
Returns

Examples

// To use this snippet, add an inline picture to the document and assign it an alt text title.
// Run a batch operation against the Word object model.
Word.run(function (context) {

    // Create a proxy object for the first inline picture.
    var firstPicture = context.document.body.inlinePictures.getFirstOrNullObject();

    // Queue a command to load the alternative text title of the picture.
    context.load(firstPicture, 'altTextTitle');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    return context.sync().then(function () {
        if (firstPicture.isNullObject) {
            console.log('There are inline pictures in this document.')
        } else {
            console.log(firstPicture.altTextTitle);
        }
    });   
})
.catch(function (error) {
    console.log('Error: ' + JSON.stringify(error));
    if (error instanceof OfficeExtension.Error) {
        console.log('Debug info: ' + JSON.stringify(error.debugInfo));
    }
});

getRange(rangeLocation)

Gets the picture, or the starting or ending point of the picture, as a range.

[ API set: WordApi 1.3 ]

getRange(rangeLocation?: Word.RangeLocation): Word.Range;
Parameters
rangeLocation
Word.RangeLocation

Optional. The range location can be 'Whole', 'Start', or 'End'.

Returns
Word.Range

insertBreak(breakType, insertLocation)

Inserts a break at the specified location in the main document. The insertLocation value can be 'Before' or 'After'.

[ API set: WordApi 1.2 ]

insertBreak(breakType: Word.BreakType, insertLocation: Word.InsertLocation): void;
Parameters
breakType
Word.BreakType

Required. The break type to add.

insertLocation
Word.InsertLocation

Required. The value can be 'Before' or 'After'.

Returns
void

insertContentControl()

Wraps the inline picture with a rich text content control.

[ API set: WordApi 1.1 ]

insertContentControl(): Word.ContentControl;
Returns

insertFileFromBase64(base64File, insertLocation)

Inserts a document at the specified location. The insertLocation value can be 'Before' or 'After'.

[ API set: WordApi 1.2 ]

insertFileFromBase64(base64File: string, insertLocation: Word.InsertLocation): Word.Range;
Parameters
base64File
string

Required. The base64 encoded content of a .docx file.

insertLocation
Word.InsertLocation

Required. The value can be 'Before' or 'After'.

Returns
Word.Range

insertHtml(html, insertLocation)

Inserts HTML at the specified location. The insertLocation value can be 'Before' or 'After'.

[ API set: WordApi 1.2 ]

insertHtml(html: string, insertLocation: Word.InsertLocation): Word.Range;
Parameters
html
string

Required. The HTML to be inserted.

insertLocation
Word.InsertLocation

Required. The value can be 'Before' or 'After'.

Returns
Word.Range

insertInlinePictureFromBase64(base64EncodedImage, insertLocation)

Inserts an inline picture at the specified location. The insertLocation value can be 'Replace', 'Before', or 'After'.

[ API set: WordApi 1.2 ]

insertInlinePictureFromBase64(base64EncodedImage: string, insertLocation: Word.InsertLocation): Word.InlinePicture;
Parameters
base64EncodedImage
string

Required. The base64 encoded image to be inserted.

insertLocation
Word.InsertLocation

Required. The value can be 'Replace', 'Before', or 'After'.

Returns

insertOoxml(ooxml, insertLocation)

Inserts OOXML at the specified location. The insertLocation value can be 'Before' or 'After'.

[ API set: WordApi 1.2 ]

insertOoxml(ooxml: string, insertLocation: Word.InsertLocation): Word.Range;
Parameters
ooxml
string

Required. The OOXML to be inserted.

insertLocation
Word.InsertLocation

Required. The value can be 'Before' or 'After'.

Returns
Word.Range

insertParagraph(paragraphText, insertLocation)

Inserts a paragraph at the specified location. The insertLocation value can be 'Before' or 'After'.

[ API set: WordApi 1.2 ]

insertParagraph(paragraphText: string, insertLocation: Word.InsertLocation): Word.Paragraph;
Parameters
paragraphText
string

Required. The paragraph text to be inserted.

insertLocation
Word.InsertLocation

Required. The value can be 'Before' or 'After'.

Returns
Word.Paragraph

insertText(text, insertLocation)

Inserts text at the specified location. The insertLocation value can be 'Before' or 'After'.

[ API set: WordApi 1.2 ]

insertText(text: string, insertLocation: Word.InsertLocation): Word.Range;
Parameters
text
string

Required. Text to be inserted.

insertLocation
Word.InsertLocation

Required. The value can be 'Before' or 'After'.

Returns
Word.Range

load(option)

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

load(option?: string | string[]): Word.InlinePicture;
Parameters
option
string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns
Remarks

In addition to this signature, this method has the following signatures:

load(option?: { select?: string; expand?: string; }): Word.InlinePicture - Where option.select is a comma-delimited string that specifies the properties to load, and options.expand is a comma-delimited string that specifies the navigation properties to load.

load(option?: { select?: string; expand?: string; top?: number; skip?: number }): Word.InlinePicture - Only available on collection types. It is similar to the preceding signature. Option.top specifies the maximum number of collection items that can be included in the result. Option.skip specifies the number of items that are to be skipped and not included in the result. If option.top is specified, the result set will start after skipping the specified number of items.

select(selectionMode)

Selects the inline picture. This causes Word to scroll to the selection.

[ API set: WordApi 1.2 ]

select(selectionMode?: Word.SelectionMode): void;
Parameters
selectionMode
Word.SelectionMode

Optional. The selection mode can be 'Select', 'Start', or 'End'. 'Select' is the default.

Returns
void

toJSON()

toJSON(): Word.Interfaces.InlinePictureData;
Returns

track()

Track the object for automatic adjustment based on surrounding changes in the document. This call is a shorthand for context.trackedObjects.add(thisObject). If you are using this object across ".sync" calls and outside the sequential execution of a ".run" batch, and get an "InvalidObjectPath" error when setting a property or invoking a method on the object, you needed to have added the object to the tracked object collection when the object was first created.

track(): Word.InlinePicture;
Returns

untrack()

Release the memory associated with this object, if it has previously been tracked. This call is shorthand for context.trackedObjects.remove(thisObject). Having many tracked objects slows down the host application, so please remember to free any objects you add, once you're done using them. You will need to call "context.sync()" before the memory release takes effect.

untrack(): Word.InlinePicture;
Returns