BookmarkCollectionNEW

BookmarkCollection:

{
  all(options?: BookmarkQueryOptions): Bookmark[];
  get(name: string): Bookmark | undefined;
  add(input: AddBookmarkInput): Bookmark | undefined;
}

The bookmarks of a document.

Methods

all()

all(options?): Bookmark[]

Lists bookmarks in document order: the body first, including table cells, footnotes, endnotes and shape text, then each section’s headers and footers. Bookmarks inside comments are not listed.

Parameters

options?

BookmarkQueryOptions

Filters to apply

Returns

Bookmark[]

The matching bookmarks

Example

List every bookmark, including those of a table of contents’ entries:

const names = draft.bookmarks().all({ includeHidden: true }).map(({ name }) => name);

---

get()

get(name): Bookmark | undefined

Finds a bookmark by its exact name, hidden or not.

Parameters

name

string

The bookmark’s Bookmark.name

Returns

Bookmark | undefined

The bookmark, or undefined when the document has no bookmark with that name

Remarks

A shortcut for finding the bookmark with this name in all({ includeHidden: true }).

The match is exact, while bookmark names must be unique in any case: when the document has Intro, get('intro') returns undefined, and adding intro is refused.

Example

Check whether a page reference’s bookmark exists:

for (const field of draft.fields().all()) {
  if (field.definition.type === 'pageReference' && !draft.bookmarks().get(field.definition.bookmark)) {
    console.log(`Broken reference to ${field.definition.bookmark}`);
  }
}

---

add()

add(input): Bookmark | undefined

Adds a bookmark on a stretch of text or at a position.

Parameters

input

AddBookmarkInput

The bookmark’s name and where it goes

Returns

Bookmark | undefined

The new bookmark, or undefined when the name is invalid or taken, the anchor is invalid, or the participant may not add it; the document is then unchanged

Remarks

A span of text must not be empty, and its ends must be in the same container (the body, one table cell, one header…) with only paragraphs between them. It may overlap fields and other bookmarks.

Bookmark changes are never tracked, so only an owner may add one, and not in a review transaction.

Examples

Bookmark a word, so a text reference can show it:

await doc.transaction(async ({ draft }) => {
  const paragraph = draft.body().content().blocklevels()[0];
  if (paragraph?.type !== 'paragraph') return false;
  const textView = paragraph.asTextView();
  const hit = textView.searchText('Introduction');
  if (!hit) return false;
  draft.bookmarks().add({ name: 'Intro', anchor: { type: 'text', span: { from: { textView, range: hit.range } } } });
  return true;
});

Mark the start of a paragraph, so a page reference can show its page:

await doc.transaction(async ({ draft }) => {
  const paragraph = draft.body().content().blocklevels()[3];
  if (paragraph?.type !== 'paragraph') return false;
  draft.bookmarks().add({ name: 'Results', anchor: { type: 'point', point: { textView: paragraph.asTextView(), placement: 'before' } } });
  return true;
});