In Word Add-In using the JS API, how can i update a text by adding/removing certain parts of paragraph?

Question

In Word Add-In using the JS API, how can i update a text by adding/removing certain parts of paragraph?

Rajat Bharadwaj 5

I am developing a Microsoft Word add-in using the Office JavaScript API.

I need to replace the text inside an existing content control. For example:

Current text:

Payment needs to be completed in 70 days.

New text:

Payment needs to be completed in 30 days.

Currently, I use:

contentControl.insertText(
  newText,
  Word.InsertLocation.replace
);

When Track Changes is enabled, Word marks the entire original clause as deleted and the entire new clause as inserted. This is not a good user experience. I want Word to show only 70 as deleted and 30 as inserted after text replacement.

The actual clauses can contain multiple paragraphs and several insertions, deletions and replacements, so this is not limited to replacing a single word.

I have considered calculating a character-level diff and then replacing individual ranges using writable Range.start and Range.end, guarded by:

Office.context.requirements.isSetSupported(
  "WordApiDesktop",
  "1.4"
);

However, I would like to confirm:

Is there a production Word JavaScript API that compares two strings or ranges and applies granular tracked changes automatically?
Can compare() or compareFromBase64() be scoped to a particular range or content control rather than the complete document?
Is using character-level diff results with writable Range.start and Range.end the recommended production approach?
Is there a supported alternative for Word on the web and older desktop versions?
How should paragraph marks, table-cell markers, fields, nested content controls and rich formatting be handled safely?
Can granular text changes be applied while preserving the existing content control, its tag and its formatting?

The solution must use production APIs only. Can someone please help me on this?

0 comments

1 answer

Your answer

Answer 1

Hello @Rajat Bharadwaj

With the current production Word JavaScript APIs, there isn’t a built-in range/content-control diff API that compares two strings and automatically generates granular tracked changes for only the modified characters. contentControl.insertText(..., "Replace") replaces the complete content of that control, so with Track Changes enabled, Word can mark the whole old value as deleted and the whole replacement as inserted.

Document.compare() and compareFromBase64() are document-level, desktop-only APIs. They compare the active document against another document and can't be scoped to a particular Range or content control. compareFromBase64() also doesn't support compareTargetSelected.

So for production code, if you need changes such as only 70 → 30 to appear as tracked revisions, the practical approach is to calculate the diff yourself and apply the smallest possible edits to corresponding ranges. The newer Range.start/end properties are available in WordApiDesktop 1.4, but that makes this approach dependent on the desktop version.

For Word on the web or older clients, you would need to fall back to APIs supported by those requirement sets, typically locating text/ranges with the existing range/search APIs and performing targeted insertText operations rather than relying on writable character offsets.

For complex content containing paragraph marks, tables, fields, nested controls, or mixed formatting, do not treat the document as one flat string. Diff and modify within stable structural boundaries, and avoid deleting/recreating the outer content control. Targeted edits inside it preserve the control itself, including its tag; replacing the whole control content risks losing more formatting/revision fidelity than necessary.

References:

Word ContentControl API

Document comparison APIs

So in short: no production API currently performs granular tracked-change diffing for a range automatically; targeted edits based on your own diff are the supported pattern.

Help make this community better for everyone: if this answer resolved your issue, please accept it or upvote it. If not, share more details in a comment so we can continue the discussion and find the right solution.