演習 - 文字列範囲を挿入して書式設定する - Training

17 分

この演習では、テキスト範囲と段落を挿入し、このテキストを書式設定する Word アドインを作成します。

前提条件

Microsoft Word 用 Office アドインを開発するには、Word 2016、バージョン 1711 (ビルド 8730.1000 クイック実行) 以降が必要です。このバージョンを入手するには、Office Insider への参加が必要になることがあります。詳細については、「Office Insider になる」を参照してください。

このモジュールでは、Node.js を使用して、カスタム Word アドインを作成します。このモジュールの演習では、開発者のワークステーションに、次のツールがインストールされていることを前提としています。

重要

ほとんどの場合、次のツールの最新バージョンをインストールすることをお勧めします。ここに記載されているバージョンのリストは、このモジュールが発行され、最後にテストしたときに使用されたものです。

Node.js (アクティブ LTS バージョン)
npm (Node.js と共にインストール)
Yeoman - v4.x (以上)
Microsoft Office 用 Yeoman ジェネレーター - v1.9.5
Visual Studio Code

アドインプロジェクトの作成

次のコマンドを実行し、Yeoman ジェネレーターを使用してアドインプロジェクトを作成します。

yo office

注:

yo office コマンドを実行すると、Yeoman のデータ収集ポリシーと Office アドイン CLI ツールに関するプロンプトが表示される場合があります。提供された情報を使用して、必要に応じてプロンプトに応答します。

プロンプトが表示されたら、以下の情報を入力してアドインプロジェクトを作成します。

プロジェクトの種類を選択する: Office アドイン作業ウィンドウプロジェクト
スクリプトの種類を選択する: JavaScript
What would you want to name your add-in? (アドインの名前を何にしますか) 個人用 Office アドイン
Which Office client application would you like to support?: (どの Office クライアントアプリケーションをサポートしますか) Word

Yeoman ジェネレーターのプロンプトと応答のスクリーンショット。

ウィザードが完了したら、ジェネレーター (My Office アドイン) によって作成されたプロジェクトフォルダーに変更し、npm インストールを実行して npm モジュールをインストールします。

ヒント

依存関係のインストール時には、Yeoman ジェネレーターによって表示される警告やエラーを無視してもかまいません。このユニットの残りの部分では、実施する必要のあるすべての手順を示します。

テキスト範囲の挿入

このセクションでは、プログラムによって、ユーザーが現在使用している Word のバージョンをアドインがサポートしているかどうかをテストしてから、ドキュメントに段落を挿入します。

アドインのコードを作成する

コードエディターでプロジェクトを開きます。
ファイル ./src/taskpane/taskpane.html を開きます。このファイルには、作業ウィンドウの HTML マークアップが含まれます。
<main> 要素を見つけて、開始 <main> タグの後、終了 </main> タグの前に表示されるすべての行を削除します。

開始 <main> タグの後に次のマークアップを追加します。

<button class="ms-Button" id="insert-paragraph">Insert Paragraph</button><br/><br/>

ファイル ./src/taskpane/taskpane.js を開きます。このファイルには、作業ウィンドウと Office のホストアプリケーションの間のやり取りを可能にする Office JavaScript API コードが含まれています。
次の手順を実行して、[run] ボタンと run() 関数へのすべての参照を削除します。
- document.getElementById("run").onclick = run; 行を見つけて削除します。
- run() 関数全体を見つけて削除します。
Office.onReady() メソッドの呼び出しで、if (info.host === Office.HostType.Word) { の行を見つけて、その行の直後に次のコードを追加します。
```
// Determine if the user's version of Office supports all the Office.js APIs that are used in the tutorial.
if (!Office.context.requirements.isSetSupported('WordApi', '1.3')) {
  console.log('Sorry. The tutorial add-in uses Word.js APIs that are not available in your version of Office.');
}

// Assign event handlers and other initialization logic.
document.getElementById("insert-paragraph").onclick = insertParagraph;
```
注:
- このコードの最初の部分では、ユーザーの Word のバージョンが、このチュートリアルで使用するすべての API を含んでいる Word.js のバージョンをサポートしているかどうかを調べます。運用アドインでは、未サポートの API を呼び出す UI を非表示または無効化する条件ブロックの本体を使用してください。これにより、ユーザーは、自分が使用している Word のバージョンでサポートされているアドインの部分を使用できるようになります。
- 2 番目の部分では、[insert-paragraph] ボタンのイベントハンドラーを追加します。
次の関数をファイルの最後に追加します。
```
async function insertParagraph() {
  await Word.run(async (context) => {

    // TODO1: Queue commands to insert a paragraph into the document.

    await context.sync();
  })
  .catch(function (error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
      console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
  });
}
```
注:
- Word.js のビジネスロジックは、Word.run に渡される関数に追加されます。このロジックは、すぐには実行されません。代わりに、保留中のコマンドのキューに追加されます。
- context.sync メソッドは、キューに登録されたすべてのコマンドを、実行するために Word に送信します。
- Word.run の後に catch ブロックを続けます。これは、どのような場合にも当てはまるベストプラクティスです。
insertParagraph() 関数で、TODO1 を次のコードに置き換えます。:
```
const docBody = context.document.body;
docBody.insertParagraph("Office has several versions, including Office 2016, Microsoft 365 Click-to-Run, and Office on the web.",
                        "Start");
```
注:
- insertParagraph メソッドの最初のパラメーターは、新しい段落のテキストです。
- 2 番目のパラメーターは、段落を挿入する本文内の場所です。親オブジェクトが本文の場合、段落の挿入に使用できるその他のオプションには、End と Replace があります。
taskpane.html ファイルと taskpane.js ファイルに対するすべての変更内容を保存します。

アドインをテストする

次の手順を実行して、ローカル Web サーバーを起動し、アドインをサイドロードします。

注:

開発の最中でも、OfficeアドインはHTTPではなくHTTPSを使用する必要があります。次のいずれかのコマンドを実行した後に証明書をインストールするように求められた場合は、Yeoman ジェネレーターによって提供される証明書をインストールするプロンプトを受け入れます。
ヒント

macOS でアドインをテストする場合は、先に進む前に、プロジェクトのルートディレクトリで次のコマンドを実行します。このコマンドを実行すると、ローカル Web サーバーが起動します。
```
npm run dev-server
```
- Word でアドインをテストするには、プロジェクトのルートディレクトリから次のコマンドを実行します。ローカル Web サーバーが (まだ実行されていない場合) 起動し、アドインが読み込まれた Word が開きます。
```
npm start
```
- Word on the web でアドインをテストするには、プロジェクトのルートディレクトリから次のコマンドを実行します。このコマンドを実行すると、ローカル Web サーバーが起動します (まだ実行されていない場合)。
```
npm run start:web
```
  アドインを使用するには、Word on the web で新しいドキュメントを開き、「Office on the web で Office アドインをサイドロードする」の手順に従ってアドインをサイドロードします。
Word の [ホーム] タブを選択し、リボンの [作業ウィンドウの表示] ボタンをクリックして、アドインの作業ウィンドウを開きます。
作業ウィンドウで、[段落の挿入] を選択します。
段落に変更を加えます。
[段落の挿入] ボタンをもう一度選択します。 insertParagraph*() メソッドはドキュメントの本文の開始位置に挿入を行うため、新しい段落は前の段落の上に表示されます。

テキストの書式設定

このセクションでは、組み込みのスタイルをテキストに適用したり、カスタムスタイルをテキストに適用したり、テキストのフォントを変更したりします。

組み込みのスタイルをテキストに適用する

ファイル ./src/taskpane/taskpane.html を開きます。
[insert-paragraph] ボタンの <button> 要素を見つけ、その行の後に次のマークアップを追加します。
```
<button class="ms-Button" id="apply-style">Apply Style</button><br/><br/>
```
ファイル ./src/taskpane/taskpane.js を開きます。
Office.onReady() メソッドの呼び出し内で、Office.onReady() メソッドの次の行を検索します。
```
document.getElementById("insert-paragraph").onclick = insertParagraph;
```
その直後に、次のコードを追加します。
```
document.getElementById("apply-style").onclick = applyStyle;
```

次の関数をファイルの最後に追加します。

async function applyStyle() {
  await Word.run(async (context) => {

    // TODO1: Queue commands to style text.

    await context.sync();
  })
  .catch(function (error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
      console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
  });
}

applyStyle() 関数で、TODO1 を次のコードに置き換えます。このコードはスタイルを段落に適用していますが、スタイルをテキストの範囲に適用することもできます。
```
const firstParagraph = context.document.body.paragraphs.getFirst();
firstParagraph.styleBuiltIn = Word.Style.intenseReference;
```

カスタムスタイルをテキストに適用する

ファイル ./src/taskpane/taskpane.html を開きます。
[apply-style] ボタンの <button> 要素を見つけ、その行の後に次のマークアップを追加します。
```
<button class="ms-Button" id="apply-custom-style">Apply Custom Style</button><br/><br/>
```
ファイル ./src/taskpane/taskpane.js を開きます。
Office.onReady() メソッドの呼び出し内で、Office.onReady() メソッドの次の行を検索します。
```
document.getElementById("apply-style").onclick = applyStyle;
```
その直後に、次のコードを追加します。
```
document.getElementById("apply-custom-style").onclick = applyCustomStyle;
```

次の関数をファイルの最後に追加します。

async function applyCustomStyle() {
  await Word.run(async (context) => {

    // TODO1: Queue commands to apply the custom style.

    await context.sync();
  })
  .catch(function (error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
      console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
  });
}

applyCustomStyle() 関数で、TODO1 を次のコードに置き換えます。このコードは、まだ存在していないカスタムスタイルを適用します。下記の手順で、「MyCustomStyle」という名前のスタイルを作成します。
```
const lastParagraph = context.document.body.paragraphs.getLast();
lastParagraph.style = "MyCustomStyle";
```
プロジェクトに行ったすべての変更が保存されていることを確認します。

テキストのフォントを変更する

ファイル ./src/taskpane/taskpane.html を開きます。
[apply-custom-style] ボタンの <button> 要素を見つけ、その行の後に次のマークアップを追加します。
```
<button class="ms-Button" id="change-font">Change Font</button><br/><br/>
```
ファイル ./src/taskpane/taskpane.js を開きます。
Office.onReady() メソッドの呼び出し内で、Office.onReady() メソッドの次の行を検索します。
```
document.getElementById("apply-custom-style").onclick = applyCustomStyle;
```
その直後に、次のコードを追加します。
```
document.getElementById("change-font").onclick = changeFont;
```

次の関数をファイルの最後に追加します。

async function changeFont() {
  await Word.run(async (context) => {

    // TODO1: Queue commands to apply a different font.

    await context.sync();
  })
  .catch(function (error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
      console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
  });
}

changeFont() 関数で、TODO1 を次のコードに置き換えます。このコードは、Paragraph.getNext() メソッドにチェーンされた ParagraphCollection.getFirst() メソッドを使用して 2 番目の段落への参照を取得します。
```
const secondParagraph = context.document.body.paragraphs.getFirst().getNext();
secondParagraph.font.set({
  name: "Courier New",
  bold: true,
  size: 18
});
```
プロジェクトに行ったすべての変更が保存されていることを確認します。

アドインをテストする

ローカル Web サーバーが既に実行されていて、アドインが既に Word に読み込まれている場合は、手順 2 に進みます。そうでない場合は、ローカル Web サーバーを起動し、アドインのサイドロードを行います。
- Word でアドインをテストするには、プロジェクトのルートディレクトリから次のコマンドを実行します。ローカル Web サーバーが (まだ実行されていない場合) 起動し、アドインが読み込まれた Word が開きます。
```
npm start
```
- Word on the web でアドインをテストするには、プロジェクトのルートディレクトリから次のコマンドを実行します。このコマンドを実行すると、ローカル Web サーバーが起動します (まだ実行されていない場合)。
```
npm run start:web
```
  アドインを使用するには、Word on the web で新しいドキュメントを開き、「Office on the web で Office アドインをサイドロードする」の手順に従ってアドインをサイドロードします。
Word でアドインの作業ウィンドウをまだ開いていない場合は、[ホーム] タブから [作業ウィンドウの表示] を選択します。
ドキュメントに 3 つ以上の段落があることを確認してください。 [段落の挿入] ボタンを 3 回選択できます。 ドキュメントの末尾に空白の段落がないことを慎重に確認してください。ある場合は、削除します。
Word で、「MyCustomStyle」という名前のカスタムスタイルを作成します。このスタイルには、必要に応じて任意の書式を設定できます。
[ スタイルの適用 ] ボタンを選択します。最初の段落は、組み込みのスタイルである Intense Reference でスタイル設定されます。
[ カスタムスタイルの適用 ] ボタンを選択します。最後の段落は、選択したカスタムスタイルでスタイル設定されます。 (何も起こっていないと思われる場合は、最後の段落が空白になる可能性があります。その場合は、テキストを追加します)。
[ フォントの変更 ] ボタンを選択します。 2 番目の段落のフォントを、18 ポイントで太字の Courier New に変更します。

概要

この演習では、テキスト範囲と段落を挿入し、このテキストの書式設定を行う Word アドインを作成しました。

自分の知識をテストする

Word JavaScript API から現在の Word コンテキストのインスタンスを取得するには、どうすればよいですか?

現在の Word コンテキストを返す Word.run((context) => {..}) メソッドを呼び出します。

this.context.current API を使用して、Word コンテキストの参照を取得できます。

Word.getContext() API を使用して、現在の Word コンテキストのインスタンスを取得します。

現在のコンポーネントでサポートされている Word JavaScript API のバージョンをアドインで検出するにはどうすればよいですか?

Microsoft Word は常に最新の Word JavaScript API バージョンを使用していますので、確認する必要はありません。

Office.context.requirements.isSetSupported('WordApi','#.#') メソッドを使用します。

Office.context.getCurrentVersion('WordApi') メソッドを使用します。

作業を確認する前にすべての問題に回答する必要があります。

続行

演習 - 文字列範囲を挿入して書式設定する

前提条件

アドイン プロジェクトの作成

テキスト範囲の挿入

アドインのコードを作成する

アドインをテストする

テキストの書式設定

組み込みのスタイルをテキストに適用する

カスタム スタイルをテキストに適用する

テキストのフォントを変更する

アドインをテストする

概要

自分の知識をテストする

フィードバック

アドインプロジェクトの作成

カスタムスタイルをテキストに適用する