Word.ParagraphCollection class

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

Gets the loaded child items in this collection.

readonly items: Word.Paragraph[];

Property Value

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/20-lists/insert-list.yaml

// This example starts a new list with the second paragraph.
await Word.run(async (context) => {
  const paragraphs: Word.ParagraphCollection = context.document.body.paragraphs;
  paragraphs.load("$none");

  await context.sync();

  // Start new list using the second paragraph.
  const list: Word.List = paragraphs.items[1].startNewList();
  list.load("$none");

  await context.sync();

  // To add new items to the list, use Start or End on the insertLocation parameter.
  list.insertParagraph("New list item at the start of the list", "Start");
  const paragraph: Word.Paragraph = list.insertParagraph("New list item at the end of the list (set to list level 5)", "End");

  // Set up list level for the list item.
  paragraph.listItem.level = 4;

  // To add paragraphs outside the list, use Before or After.
  list.insertParagraph("New paragraph goes after (not part of the list)", "After");

  await context.sync();
});

Returns a Paragraph object that represents a new, blank paragraph added to the document.

add(range: Word.Range): Word.Paragraph;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Removes any spacing before the specified paragraphs.

closeUp(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Decreases the spacing before and after paragraphs in six-point increments.

decreaseSpacing(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Gets the first paragraph in this collection. Throws an ItemNotFound error if the collection is empty.

getFirst(): Word.Paragraph;

Returns

Remarks

[ API set: WordApi 1.3 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/50-document/manage-annotations.yaml

// Gets annotations found in the selected paragraph.
await Word.run(async (context) => {
  const paragraph: Word.Paragraph = context.document.getSelection().paragraphs.getFirst();
  const annotations: Word.AnnotationCollection = paragraph.getAnnotations();
  annotations.load("id,state,critiqueAnnotation");

  await context.sync();

  console.log("Annotations found:");

  for (let i = 0; i < annotations.items.length; i++) {
    const annotation: Word.Annotation = annotations.items[i];

    console.log(`ID ${annotation.id} - state '${annotation.state}':`, annotation.critiqueAnnotation.critique);
  }
});

Gets the first paragraph in this collection. If the collection is empty, then this method will return an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.

getFirstOrNullObject(): Word.Paragraph;

Returns

Remarks

[ API set: WordApi 1.3 ]

Gets the last paragraph in this collection. Throws an ItemNotFound error if the collection is empty.

getLast(): Word.Paragraph;

Returns

Remarks

[ API set: WordApi 1.3 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/word/15-images/insert-and-get-pictures.yaml

// Inserts an image anchored to the last paragraph.
await Word.run(async (context) => {
  context.document.body.paragraphs
    .getLast()
    .insertParagraph("", "After")
    .insertInlinePictureFromBase64(base64Image, "End");

  await context.sync();
});

Gets the last paragraph in this collection. If the collection is empty, then this method will return an object with its isNullObject property set to true. For further information, see *OrNullObject methods and properties.

getLastOrNullObject(): Word.Paragraph;

Returns

Remarks

[ API set: WordApi 1.3 ]

Increases the spacing before and after paragraphs in six-point increments.

increaseSpacing(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Indents the paragraphs by one level.

indent(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Indents the paragraphs in the collection by the specified number of characters.

indentCharacterWidth(count: number): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Indents the first line of the paragraphs in the collection by the specified number of characters.

indentFirstLineCharacterWidth(count: number): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

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

load(options?: Word.Interfaces.ParagraphCollectionLoadOptions & Word.Interfaces.CollectionLoadOptions): Word.ParagraphCollection;

Parameters

Returns

Examples

// This example shows how to get the paragraphs in the Word document
// along with their text and font size properties.
// 
// Run a batch operation against the Word object model.
await Word.run(async (context) => {

    // Create a proxy object for the paragraphs collection.
    const paragraphs = context.document.body.paragraphs;

    // Queue a command to load the text and font properties.
    // It is best practice to always specify the property set. Otherwise, all properties are
    // returned in on the object.
    paragraphs.load('text, font/size');

    // Synchronize the document state by executing the queued commands,
    // and return a promise to indicate task completion.
    await context.sync();

    // Insert code that works with the paragraphs loaded by paragraphs.load().
});

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.ParagraphCollection;

Parameters

Returns

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

load(propertyNamesAndPaths?: OfficeExtension.LoadOption): Word.ParagraphCollection;

Parameters

Returns

Toggles spacing before paragraphs.

openOrCloseUp(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Sets spacing before the specified paragraphs to 12 points.

openUp(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Removes one level of indent for the paragraphs.

outdent(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Applies the next heading level style (Heading 1 through Heading 8) to the specified paragraphs.

outlineDemote(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Demotes the specified paragraphs to body text by applying the Normal style.

outlineDemoteToBody(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Applies the previous heading level style (Heading 1 through Heading 8) to the paragraphs in the collection.

outlinePromote(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Sets the specified paragraphs to single spacing.

space1(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Sets the specified paragraphs to 1.5-line spacing.

space1Pt5(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Sets the specified paragraphs to double spacing.

space2(): void;

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Sets a hanging indent to the specified number of tab stops.

tabHangingIndent(count: number): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

Sets the left indent for the specified paragraphs to the specified number of tab stops.

tabIndent(count: number): void;

Parameters

Returns

Remarks

[ API set: WordApi BETA (PREVIEW ONLY) ]

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's passed to it.) Whereas the original Word.ParagraphCollection object is an API object, the toJSON method returns a plain JavaScript object (typed as Word.Interfaces.ParagraphCollectionData) that contains an "items" array with shallow copies of any loaded properties from the collection's items.

toJSON(): Word.Interfaces.ParagraphCollectionData;

Returns

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're 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 need to add the object to the tracked object collection when the object was first created. If this object is part of a collection, you should also track the parent collection.

track(): Word.ParagraphCollection;

Returns

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'll need to call context.sync() before the memory release takes effect.

untrack(): Word.ParagraphCollection;

Returns