WordDocument is an OfficeJS-like API. It follows the names and shapes of the Word JavaScript API, so if you know Word.run, you know most of it.
It is not OfficeJS-compatible. It is not a drop-in replacement for Office.js, and add-in code does not run on it without changes. There is no Word.run, no request context and no load/sync. Some members are missing, some have a different shape, and some are extensions that Office.js does not have. The differences are below.
Try it
Edit the script. The pages on the right show the result when you stop typing. Click a block on a page to go to the line that made it.No run, load or sync
Office.js sends a batch of commands to Word and waits. Here the document is in memory, so every property reads at once and every edit applies at once.
load() and no sync(). Remove them when you port add-in code. Values that Office.js wraps in a ClientResult (for example getReviewedText()) have a .value that is ready at once.
Handles and collections
- A collection (
paragraphs,tables,revisions,comments) has.items,.getFirst(),.getFirstOrNullObject()and.length. - Collections are live. Read them again after an edit that adds or removes items.
- A handle points into the document. When its content is removed (for example, a rejected revision), the handle throws
no longer part of the document. - Re-query ranges after you replace their text or change their container.
Paragraph ids (w14:paraId)
Word gives each paragraph and table row a w14:paraId. Word keeps these ids on save only when every paragraph and row has a valid, unique id. If one id is missing, Word makes new ids for all of them.
A file with missing ids:
- Every paragraph and row gets an id, as Word does when it saves. When a file has no paraIds, or some are missing, the open fills them from the file’s own text and order.
- Each open of the same file fills the same ids, and every copy in a live session fills them alike. Two different files get different ids.
- The filled ids go into the next save once you read a
uniqueLocalIdor make an edit. After that the ids come from the file, so a later text change, by us or by another tool, does not move them. - A document whose ids nobody read and that nobody edited saves byte for byte. If you change only its properties (for example a custom property), the body, headers, footers and notes save as they were, with no filled ids.
- Each paragraph and row that you add gets a new id. This applies to the facade, the editor and accepted suggestion cards.
- An edited paragraph keeps its id.
- A split follows Word: Enter at the end of a paragraph keeps the id on the first part, and Enter at any other position moves it to the second part.
- When two paragraphs join, the paragraph whose mark stays keeps its id.
insertParagraphkeeps the id on the paragraph you call it on. Word gives the id to the new paragraph instead. Both files are valid; only which paragraph holds the id differs.- Word keeps all of these ids when it saves the file, and an edit in Word keeps a paragraph’s id.
uniqueLocalId
Paragraph.uniqueLocalId is a GUID built from the paragraph’s paraId. Its first eight digits are the paraId. It stays the same after a save, a reload, a server restart and a round trip through Word. doc.getParagraphByUniqueLocalId(id) finds the paragraph in the body, a header, a footer or a note, and throws ItemNotFound when no paragraph has that id (for example, after you delete it).
- This goes further than Word. Word makes a new
uniqueLocalIdfor every paragraph each time Word starts, so add-in code written for Word must not expect it to last. - The id is unique in one document only. A copy of a file, or a document made from one template, can have the same ids, so key your store by document and id.
- A split in the middle of a paragraph moves the id to the second part, as described above. The text after the split point keeps the id.
- Save the document after you read ids from a file that had none. If you do not save, the ids you read are not in the file, and an edit by another tool before the next open can change them.
- Reading every id costs time in proportion to the number of paragraphs: about 30 ms for 40,000 paragraphs. A lookup by id in the body takes about 1 ms at that size.
Locations
Insert methods take an Office.js location. The values are case-sensitive.Units
Sizes are in points (72 per inch), as in Office.js. Table, row and column indexes start at 0.Extensions
Some members do not exist in Office.js but exist in Word’s VBA object model (for examplesetLineSpacing, documentDefaults, insertMath). They have the VBA name, and the type docs mark them as extensions. Where Office.js has a member, OfficeJS follows its name and behavior.
Layout-backed members
A few members need laid-out pages:readPage(), getRects()-style geometry, updateFields() (page numbers, TOC) and toPdf(). They need a layout host:
- In Node,
@reductoai/docx/nodeinstalls one when you import it. - In a page, call
browserLayoutHost({ fonts })once. See Office.js in the browser. - With
@reductoai/docx/officejsalone there is no host. Pure edits work; layout-backed members throwNo layout host.
Coverage
OfficeJS covers most ofWord.Document, Body, Paragraph, Range, Table, List, ContentControl, Comment, TrackedChange, sections, headers and footers, styles, fields and pictures. The API reference lists every member, and the members that throw because they are not implemented. A value that OfficeJS cannot write throws an error that tells you why; it does not fail silently.