Proofing annotations
Mark spelling and grammar issues in paragraphs, list them, and apply or dismiss suggestions.
A proofing tool reads paragraph text, checks it, and marks each issue as an annotation. The browser runtime paints annotations in the page. A server runtime keeps them as data that your code reads and decides.
Annotations are view state. They are not saved in the file, not shared with collaborators, and gone when the runtime is disposed.
Mark issues in a paragraph
Paragraph.insertAnnotations() takes an AnnotationSet and returns annotation ids after the next sync. Create a runtime with Runtime and setup. Read plain data before you call your proofing service. Check the paragraph text again before you apply returned offsets:
const snapshot = await runtime.run(async (context) => {
const paragraphs = context.document.body.paragraphs;
paragraphs.load('items/uniqueLocalId,items/text');
await context.sync();
return paragraphs.items.map((paragraph) => ({
id: paragraph.uniqueLocalId,
text: paragraph.text,
}));
});
// Your service returns issues with start, length, and suggestions.
// Send a few requests at a time so a long document does not flood it.
const BATCH_SIZE = 8;
const checked = [];
for (let index = 0; index < snapshot.length; index += BATCH_SIZE) {
const batch = snapshot.slice(index, index + BATCH_SIZE);
checked.push(
...(await Promise.all(
batch.map(async (paragraph) => ({
...paragraph,
issues: await check(paragraph.text),
}))
))
);
}
const byId = new Map(checked.map((paragraph) => [paragraph.id, paragraph]));
const ids = await runtime.run(async (context) => {
const paragraphs = context.document.body.paragraphs;
paragraphs.load('items/uniqueLocalId,items/text');
await context.sync();
const inserted = [];
for (const paragraph of paragraphs.items) {
const result = byId.get(paragraph.uniqueLocalId);
if (!result || result.text !== paragraph.text) continue;
if (result.issues.length === 0) continue;
inserted.push(
paragraph.insertAnnotations({
critiques: result.issues.map((issue) => ({
colorScheme: 'Red',
start: issue.start,
length: issue.length,
popupOptions: {
brandingTextResourceId: '',
subtitleResourceId: '',
titleResourceId: '',
suggestions: issue.suggestions,
},
})),
})
);
}
await context.sync();
return inserted.flatMap((result) => result.value);
});This example sends at most eight checks at a time. Set the limit that your service allows. It skips changed paragraphs. Check them again instead of applying offsets from earlier text. Cancel pending checks when you load or replace the document. Remove earlier annotations before you insert results for the same text again.
startandlengthcount UTF-16 code units ofParagraph.text, as the runtime reads it in its revision view. With the defaultallMarkupview, tracked deletions and insertions both count, and a field counts as its displayed result.lengthmust be at least 1, and the range must lie inside the text. Otherwise the sync fails withInvalidArgument.- The three resource ids name strings in an add-in manifest, which this runtime cannot resolve. Pass empty strings. Any other value fails with
NotSupportedandedit.operation-unsupported. - One call takes at most 1,000 critiques, and one runtime keeps at most 10,000 live annotations.
- Each critique accepts at most 32 suggestions. Each suggestion has at most 4,096 UTF-16 code units.
Read annotations
Paragraph.getAnnotations() lists the paragraph's live annotations in text order. Load id, state, and critiqueAnnotation on the items. The following example lists the issues of the first paragraph:
const issues = await runtime.run(async (context) => {
const annotations = context.document.body.paragraphs.getFirst().getAnnotations();
annotations.load('items/id,items/state,items/critiqueAnnotation');
await context.sync();
return annotations.items.map((annotation) => ({
id: annotation.id,
state: annotation.state,
critique: annotation.critiqueAnnotation.critique,
}));
});| Member | Behavior |
|---|---|
Document.getAnnotationById(id) | Finds a live or decided annotation of this runtime. An unknown, deleted, or removed id fails with ItemNotFound. |
AnnotationCollection.getFirst() | Fails with ItemNotFound on a paragraph without annotations. getFirstOrNullObject() returns a null object instead. |
Annotation.state | Created, Accepted, or Rejected. |
CritiqueAnnotation.critique | The critique data with its current start. Resource ids read as empty strings. |
CritiqueAnnotation.range | The critiqued text as a Range. Load its properties and sync before you read them. |
An annotation follows edits to its paragraph. An edit before the critique moves start, and an edit that changes the critiqued text removes the annotation. A held Annotation whose annotation is gone fails with InvalidObjectPath and edit.stale-target.
Apply or dismiss an issue
accept() replaces the critiqued text with the first suggestion. reject() and delete() remove the mark and leave the document unchanged. The following example applies one issue and dismisses another:
await runtime.run(async (context) => {
context.document.changeTrackingMode = 'TrackMineOnly';
context.document.getAnnotationById(fixId).critiqueAnnotation.accept();
context.document.getAnnotationById(skipId).critiqueAnnotation.reject();
await context.sync();
});accept()edits only the characters that differ. WithTrackMineOnly, the fix is a tracked change. The state becomesAccepted, and other annotations in the paragraph move with the fix.- With
TrackMineOnly, use onecontext.sync()for eachaccept()in the same paragraph. A second tracked fix in that paragraph and sync fails withConflictingChanges, and nothing changes. reject()sets the state toRejected.delete()forgets the annotation.- The following table lists the refusals of
accept(). Nothing changes after a refusal.
| Condition | Code | debugInfo.innerError.code |
|---|---|---|
| The critique has no suggestion | NotSupported | edit.operation-unsupported |
| The critiqued text holds an object, such as a field result, or hidden text | NotSupported | edit.indivisible-content |
| The suggestion holds a paragraph mark or U+FFFC | InvalidArgument | edit.invalid-argument |
| An edit removed the annotation, or it was decided or deleted | InvalidObjectPath | edit.stale-target |
Show annotations in the editor
The browser runtime paints live annotations as text highlights. Each color scheme paints in its own reserved highlight set, docx-critique-red through docx-critique-berry. Red marks spelling issues and Blue and Green mark grammar issues for assistive technology. Lavender and Berry have no proofing meaning.
Restyle the marks with the --doc-critique-<scheme>-color tokens of the editor stylesheet. To show a popup for a mark under the pointer, call editor.getHighlightsAt() from your own pointer handler.
Marks repaint after each sync of the runtime. Between syncs, the editor moves a mark with its text and hides a mark whose text changed.
Limits
- The runtime raises no annotation or paragraph events, such as
onAnnotationClickedoronParagraphChanged. Read annotations again after a sync. - The runtime shows no popup. Use
editor.getHighlightsAt()in the browser to build one. - A preview refuses annotation members with
NotSupportedandedit.preview-unsupported. - Text is read as a batch starts. Annotations inserted in a sync that also edits the same paragraph count in the text before the edit, then follow the edit.