Word アドインで注釈を使用する

コミュニティコントリビューションを含む:アブドゥルハディ・ジャラド

注釈を使用して、文法ガイダンスや推奨される改善点など、Wordドキュメントにフィードバックを直接書き込むことを示します。 Wordは、影響を受けるテキストを強調表示し、ユーザーが注釈をポイントしたときに、推奨されるアクションを含むポップアップを表示できます。

この記事では、次の方法について説明します。

アドインがユーザーのアクションに応答できるように、注釈イベントを登録します。
現在の段落に批判を追加します。
注釈の状態と批判の詳細を調べます。
提案を適用または却下し、注釈を拒否します。
不要になった注釈を削除します。

重要

これらの注釈はドキュメントに保持されません。つまり、ドキュメントを再度開くと、注釈を再生成する必要があります。ただし、ユーザーが推奨される変更を受け入れた場合、ユーザーがドキュメントを閉じる前に変更を保存する限り、変更は保持されます。

前提条件

注釈 API は、Microsoft 365 サブスクリプションを必要とするサービスに依存しています。そのため、1 回限りの購入ライセンスでWordでこの機能を使用することはできません。アドインが注釈 API を正常に実行できるように、ユーザーは Microsoft 365 サブスクリプションに接続されたWordを実行している必要があります。

キー注釈 API

キー注釈 API を次に示します。

Paragraph.insertAnnotations
Paragraph.getAnnotations
オブジェクト：
- 注釈: 注釈を表します。
- AnnotationCollection: 注釈のコレクションを表します。
- AnnotationSet: このセッションでアドインによって生成される注釈のセットを表します。
- CritiqueAnnotation: 注釈の批判の種類を表します。
- 批判: 段落の影響を受ける領域に関するフィードバックを表します。色付きの下線で示されます。
ドキュメントの注釈イベント:

注釈 API を使用する

次のセクションでは、注釈 API を操作する方法について説明します。この例は、注釈の管理コードサンプルに基づいています。

サービスからのフィードバックまたは批判の結果を使用して、ユーザーのドキュメントコンテンツに基づいて注釈を動的に管理します。

注釈イベントを登録する

次のコードは、イベントハンドラーを登録する方法を示しています。 Wordでのイベントの操作の詳細については、「Word JavaScript API を使用してイベントを操作する」を参照してください。注釈イベントハンドラーの例については、次のセクションを参照してください。

let eventContexts = [];

async function registerEventHandlers() {
  // Registers event handlers.
  await Word.run(async (context) => {
    eventContexts[0] = context.document.onParagraphAdded.add(paragraphChanged);
    eventContexts[1] = context.document.onParagraphChanged.add(paragraphChanged);

    eventContexts[2] = context.document.onAnnotationClicked.add(onClickedHandler);
    eventContexts[3] = context.document.onAnnotationHovered.add(onHoveredHandler);
    eventContexts[4] = context.document.onAnnotationInserted.add(onInsertedHandler);
    eventContexts[5] = context.document.onAnnotationRemoved.add(onRemovedHandler);
    eventContexts[6] = context.document.onAnnotationPopupAction.add(onPopupActionHandler);

    await context.sync();

    console.log("Event handlers registered.");
  });
}

onClickedHandler イベントハンドラー

登録された onAnnotationClicked イベントが発生すると、次のコードが実行されます。

async function onClickedHandler(args: Word.AnnotationClickedEventArgs) {
  // Runs when the registered Document.onAnnotationClicked event occurs.
  await Word.run(async (context) => {
    const annotation: Word.Annotation = context.document.getAnnotationById(args.id);
    annotation.load("critiqueAnnotation");

    await context.sync();

    console.log(`AnnotationClicked: ID ${args.id}:`, annotation.critiqueAnnotation.critique);
  });
}

onHoveredHandler イベントハンドラー

登録された onAnnotationHovered イベントが発生すると、次のコードが実行されます。

async function onHoveredHandler(args: Word.AnnotationHoveredEventArgs) {
  // Runs when the registered Document.onAnnotationHovered event occurs.
  await Word.run(async (context) => {
    const annotation: Word.Annotation = context.document.getAnnotationById(args.id);
    annotation.load("critiqueAnnotation");

    await context.sync();

    console.log(`AnnotationHovered: ID ${args.id}:`, annotation.critiqueAnnotation.critique);
  });
}

onInsertedHandler イベントハンドラー

登録された onAnnotationInserted イベントが発生すると、次のコードが実行されます。

async function onInsertedHandler(args: Word.AnnotationInsertedEventArgs) {
  // Runs when the registered Document.onAnnotationInserted event occurs.
  await Word.run(async (context) => {
    const annotations = [];
    for (let i = 0; i < args.ids.length; i++) {
      let annotation: Word.Annotation = context.document.getAnnotationById(args.ids[i]);
      annotation.load("id,critiqueAnnotation");
      annotations.push(annotation);
    }

    await context.sync();

    for (let annotation of annotations) {
      console.log(`AnnotationInserted: ID ${annotation.id}:`, annotation.critiqueAnnotation.critique);
    }
  });
}

onRemovedHandler イベントハンドラー

登録された onAnnotationRemoved イベントが発生すると、次のコードが実行されます。

async function onRemovedHandler(args: Word.AnnotationRemovedEventArgs) {
  // Runs when the registered Document.onAnnotationRemoved event occurs.
  await Word.run(async (context) => {
    for (let id of args.ids) {
      console.log(`AnnotationRemoved: ID ${id}`);
    }
  });
}

onPopupActionHandler イベントハンドラー

登録された onAnnotationPopupAction イベントが発生すると、次のコードが実行されます。

async function onPopupActionHandler(args: Word.AnnotationPopupActionEventArgs) {
  // Runs when the registered Document.onAnnotationPopupAction event occurs.
  await Word.run(async (context) => {
    let message = `AnnotationPopupAction: ID ${args.id} = `;
    if (args.action === "Accept") {
      message += `Accepted: ${args.critiqueSuggestion}`;
    } else {
      message += "Rejected";
    }

    console.log(message);
  });
}

注釈を挿入する

次のコードは、選択した段落に注釈を挿入する方法を示しています。

async function insertAnnotations() {
  // Adds annotations to the selected paragraph.
  await Word.run(async (context) => {
    const paragraph: Word.Paragraph = context.document.getSelection().paragraphs.getFirst();
    const options: Word.CritiquePopupOptions = {
      brandingTextResourceId: "PG.TabLabel",
      subtitleResourceId: "PG.HelpCommand.TipTitle",
      titleResourceId: "PG.HelpCommand.Label",
      suggestions: ["suggestion 1", "suggestion 2", "suggestion 3"]
    };
    const critique1: Word.Critique = {
      colorScheme: Word.CritiqueColorScheme.red,
      start: 1,
      length: 3,
      popupOptions: options
    };
    const critique2: Word.Critique = {
      colorScheme: Word.CritiqueColorScheme.green,
      start: 6,
      length: 1,
      popupOptions: options
    };
    const critique3: Word.Critique = {
      colorScheme: Word.CritiqueColorScheme.blue,
      start: 10,
      length: 3,
      popupOptions: options
    };
    const critique4: Word.Critique = {
      colorScheme: Word.CritiqueColorScheme.lavender,
      start: 14,
      length: 3,
      popupOptions: options
    };
    const critique5: Word.Critique = {
      colorScheme: Word.CritiqueColorScheme.berry,
      start: 18,
      length: 10,
      popupOptions: options
    };
    const annotationSet: Word.AnnotationSet = {
      critiques: [critique1, critique2, critique3, critique4, critique5]
    };

    const annotationIds = paragraph.insertAnnotations(annotationSet);

    await context.sync();

    console.log("Annotations inserted:", annotationIds.value);
  });
}

注釈を取得する

次のコードは、選択した段落から注釈を取得する方法を示しています。

async function getAnnotations() {
  // 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);
    }
  });
}

注釈を受け入れる

次のコードは、選択した段落で見つかった最初の注釈を受け入れる方法を示しています。

async function acceptFirst() {
  // Accepts the first annotation 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();

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

      if (annotation.state === Word.AnnotationState.created) {
        console.log(`Accepting ID ${annotation.id}...`);
        annotation.critiqueAnnotation.accept();

        await context.sync();
        break;
      }
    }
  });
}

注釈を拒否する

次のコードは、選択した段落で見つかった最後の注釈を拒否する方法を示しています。

async function rejectLast() {
  // Rejects the last annotation 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();

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

      if (annotation.state === Word.AnnotationState.created) {
        console.log(`Rejecting ID ${annotation.id}...`);
        annotation.critiqueAnnotation.reject();

        await context.sync();
        break;
      }
    }
  });
}

注釈を削除する

次のコードは、選択した段落にあるすべての注釈を削除する方法を示しています。

async function deleteAnnotations() {
  // Deletes all 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");

    await context.sync();

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

      ids.push(annotation.id);
      annotation.delete();
    }

    await context.sync();

    console.log("Annotations deleted:", ids);
  });
}

注釈イベントの登録解除

次のコードは、 eventContexts 変数で追跡されるイベントコンテキストを使用して、イベントハンドラーを登録解除する方法を示しています。

async function deregisterEventHandlers() {
  // Deregisters event handlers.
  await Word.run(async (context) => {
    for (let i = 0; i < eventContexts.length; i++) {
      await Word.run(eventContexts[i].context, async (context) => {
        eventContexts[i].remove();
      });
    }

    await context.sync();

    eventContexts = [];
    console.log("Removed event handlers.");
  });
}

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-05-22