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 ]

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

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 ]

imageFormat

Gets the format of the inline image. Read-only.

[ API set: WordApi BETA (PREVIEW ONLY) ]

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 an error 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 an error 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 an error 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 an error 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 ]

getRange(rangeLocationString)

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.

[ API set: WordApi 1.2 ]

insertBreak(breakTypeString, insertLocation)

Inserts a break at the specified location in the main document.

[ 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.

[ API set: WordApi 1.2 ]

insertFileFromBase64(base64File, insertLocationString)

Inserts a document at the specified location.

[ API set: WordApi 1.2 ]

insertHtml(html, insertLocation)

Inserts HTML at the specified location.

[ API set: WordApi 1.2 ]

insertHtml(html, insertLocationString)

Inserts HTML at the specified location.

[ API set: WordApi 1.2 ]

insertInlinePictureFromBase64(base64EncodedImage, insertLocation)

Inserts an inline picture at the specified location.

[ API set: WordApi 1.2 ]

insertInlinePictureFromBase64(base64EncodedImage, insertLocationString)

Inserts an inline picture at the specified location.

[ API set: WordApi 1.2 ]

insertOoxml(ooxml, insertLocation)

Inserts OOXML at the specified location.

[ API set: WordApi 1.2 ]

insertOoxml(ooxml, insertLocationString)

Inserts OOXML at the specified location.

[ API set: WordApi 1.2 ]

insertParagraph(paragraphText, insertLocation)

Inserts a paragraph at the specified location.

[ API set: WordApi 1.2 ]

insertParagraph(paragraphText, insertLocationString)

Inserts a paragraph at the specified location.

[ API set: WordApi 1.2 ]

insertText(text, insertLocation)

Inserts text at the specified location.

[ API set: WordApi 1.2 ]

insertText(text, insertLocationString)

Inserts text at the specified location.

[ 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.

load(propertyNames)

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

load(propertyNamesAndPaths)

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 ]

select(selectionModeString)

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

[ API set: WordApi 1.2 ]

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Word.InlinePicture object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.InlinePictureData) that contains shallow copies of any loaded child properties from the original object.

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

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

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

imageFormat

Note

This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Gets the format of the inline image. Read-only.

[ API set: WordApi BETA (PREVIEW ONLY) ]

readonly imageFormat: Word.ImageFormat | "Unsupported" | "Undefined" | "Bmp" | "Jpeg" | "Gif" | "Tiff" | "Png" | "Icon" | "Exif" | "Wmf" | "Emf" | "Pict" | "Pdf" | "Svg";

Property Value

Word.ImageFormat | "Unsupported" | "Undefined" | "Bmp" | "Jpeg" | "Gif" | "Tiff" | "Png" | "Icon" | "Exif" | "Wmf" | "Emf" | "Pict" | "Pdf" | "Svg"

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

parentContentControl

Gets the content control that contains the inline image. Throws an error 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 an error if it is not contained in a table. Read-only.

[ API set: WordApi 1.3 ]

readonly parentTable: Word.Table;

Property Value

parentTableCell

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

[ API set: WordApi 1.3 ]

readonly parentTableCell: Word.TableCell;

Property Value

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

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

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}`);
  // Get the image encoded as base64.
  const base64 = firstPicture.getBase64ImageSrc();

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

getNext()

Gets the next inline image. Throws an error 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 no 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 no 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

getRange(rangeLocationString)

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

[ API set: WordApi 1.3 ]

getRange(rangeLocationString?: "Whole" | "Start" | "End" | "Before" | "After" | "Content"): Word.Range;

Parameters

rangeLocationString
"Whole" | "Start" | "End" | "Before" | "After" | "Content"

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

Returns

insertBreak(breakType, insertLocation)

Inserts a break at the specified location in the main document.

[ 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

insertBreak(breakTypeString, insertLocation)

Inserts a break at the specified location in the main document.

[ API set: WordApi 1.2 ]

insertBreak(breakTypeString: "Page" | "Next" | "SectionNext" | "SectionContinuous" | "SectionEven" | "SectionOdd" | "Line", insertLocation: "Before" | "After" | "Start" | "End" | "Replace"): void;

Parameters

breakTypeString
"Page" | "Next" | "SectionNext" | "SectionContinuous" | "SectionEven" | "SectionOdd" | "Line"

Required. The break type to add.

insertLocation
"Before" | "After" | "Start" | "End" | "Replace"

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.

[ 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

insertFileFromBase64(base64File, insertLocationString)

Inserts a document at the specified location.

[ API set: WordApi 1.2 ]

insertFileFromBase64(base64File: string, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace"): Word.Range;

Parameters

base64File
string

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

insertLocationString
"Before" | "After" | "Start" | "End" | "Replace"

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

Returns

insertHtml(html, insertLocation)

Inserts HTML at the specified location.

[ 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

insertHtml(html, insertLocationString)

Inserts HTML at the specified location.

[ API set: WordApi 1.2 ]

insertHtml(html: string, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace"): Word.Range;

Parameters

html
string

Required. The HTML to be inserted.

insertLocationString
"Before" | "After" | "Start" | "End" | "Replace"

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

Returns

insertInlinePictureFromBase64(base64EncodedImage, insertLocation)

Inserts an inline picture at the specified location.

[ 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

insertInlinePictureFromBase64(base64EncodedImage, insertLocationString)

Inserts an inline picture at the specified location.

[ API set: WordApi 1.2 ]

insertInlinePictureFromBase64(base64EncodedImage: string, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace"): Word.InlinePicture;

Parameters

base64EncodedImage
string

Required. The base64 encoded image to be inserted.

insertLocationString
"Before" | "After" | "Start" | "End" | "Replace"

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

Returns

insertOoxml(ooxml, insertLocation)

Inserts OOXML at the specified location.

[ 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

insertOoxml(ooxml, insertLocationString)

Inserts OOXML at the specified location.

[ API set: WordApi 1.2 ]

insertOoxml(ooxml: string, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace"): Word.Range;

Parameters

ooxml
string

Required. The OOXML to be inserted.

insertLocationString
"Before" | "After" | "Start" | "End" | "Replace"

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

Returns

insertParagraph(paragraphText, insertLocation)

Inserts a paragraph at the specified location.

[ 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

insertParagraph(paragraphText, insertLocationString)

Inserts a paragraph at the specified location.

[ API set: WordApi 1.2 ]

insertParagraph(paragraphText: string, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace"): Word.Paragraph;

Parameters

paragraphText
string

Required. The paragraph text to be inserted.

insertLocationString
"Before" | "After" | "Start" | "End" | "Replace"

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

Returns

insertText(text, insertLocation)

Inserts text at the specified location.

[ 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

insertText(text, insertLocationString)

Inserts text at the specified location.

[ API set: WordApi 1.2 ]

insertText(text: string, insertLocationString: "Before" | "After" | "Start" | "End" | "Replace"): Word.Range;

Parameters

text
string

Required. Text to be inserted.

insertLocationString
"Before" | "After" | "Start" | "End" | "Replace"

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

Returns

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?: Word.Interfaces.InlinePictureLoadOptions): Word.InlinePicture;

Parameters

Returns

Remarks

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

load(option?: string | string[]): Word.InlinePicture - Where option is a comma-delimited string or an array of strings that specify the properties to load.

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.

load(propertyNames)

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

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

Parameters

propertyNames
string | string[]

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

Returns

load(propertyNamesAndPaths)

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

load(propertyNamesAndPaths?: { select?: string; expand?: string; }): Word.InlinePicture;

Parameters

propertyNamesAndPaths
{ select?: string; expand?: string; }

Where propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.

Returns

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

select(selectionModeString)

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

[ API set: WordApi 1.2 ]

select(selectionModeString?: "Select" | "Start" | "End"): void;

Parameters

selectionModeString
"Select" | "Start" | "End"

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

Returns

void

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties: Interfaces.InlinePictureUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parameters

properties
Interfaces.InlinePictureUpdateData

A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.

options
OfficeExtension.UpdateOptions

Provides an option to suppress errors if the properties object tries to set any read-only properties.

Returns

void

Remarks

This method has the following additional signature:

set(properties: Word.InlinePicture): void

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Word.InlinePicture): void;

Parameters

properties
Word.InlinePicture

Returns

void

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Word.InlinePicture object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.InlinePictureData) that contains shallow copies of any loaded child properties from the original object.

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