基本的な初回実行エクスペリエンスを使用して Office アドインを構築する

初回実行エクスペリエンスを実装すると、ユーザーのオンボードに役立ち、アドインの価値が強調されます。このチュートリアルでは、ローカルストレージを使用して Office アドインに簡単な初回実行エクスペリエンスを追加して、ユーザーが以前にアドインを起動したかどうかを追跡する方法について説明します。

注:

最初の実行エクスペリエンスは、Office アドインに推奨されるパターンです。これは、ユーザーがアドインの機能を理解し、エンゲージメントを高めるのに役立ちます。

学習内容

アドインに初回実行 UI を追加する方法。
ブラウザーローカルストレージを使用してユーザーの状態を保持する方法。
アドインの HTML、JavaScript、CSS ファイルを更新して、初回実行時のエクスペリエンスをサポートする方法。

概要

ユーザーが初めてアドインを開くと、ウェルカムメッセージと主要な機能の一覧が表示されます。以降の起動時に、アドインはようこそをスキップし、メイン UI を表示します。これは、ローカルストレージ内のフラグを確認し、それに応じて UI を更新することで実現されます。

このチュートリアルでは、Excel の手順とスクリーンショットを提供しますが、同様のパターンを使用して、Office Web アドインがサポートされている他の Office アプリケーションで初回実行エクスペリエンスを実装できます。

手順

最初の実行エクスペリエンスを実装するには、次の手順に従います。

HTML を更新する: 初回実行エクスペリエンス用のコンテナーを追加します。
JavaScript を更新する: ローカルストレージを確認し、必要に応じて最初に実行される UI を表示します。
CSS を更新する: 新しい UI のスタイルが一貫していることを確認します。
アドインをテストする: 最初の実行エクスペリエンスが期待どおりに動作することを確認します。

では、始めましょう。

ヒント

このチュートリアルの完成したバージョンが必要な場合は、 GitHub の Office アドインサンプルリポジトリにアクセスしてください。

前提条件

使用する Office アプリケーションの [Yo Office] クイックスタートを選択します。
- Excel
- OneNote
- Outlook
- PowerPoint
- Project
- Word
選択したクイックスタートの指示に従います。 "試してみる" セクションを完了したら、ここに戻って続行します。

最初の実行エクスペリエンスを実装する

HTML ファイルを更新する

最初の実行エクスペリエンスの一部となる UI の領域を明確にしてください。このチュートリアルでは、ユーザーがアドインを初めて実行したときにのみ表示される内容を表す "first-run-experience" という名前のidを使用して、<div>要素を作成します。

taskpane.htmlを開きます。 <main>要素を次のマークアップに置き換え、ファイルを保存します。このマークアップに関するいくつかの注意事項:

"first-run-experience" <div> が <main> 要素に挿入されます。 Office アドイン機能の一覧を囲みます。既定では、この <div> は表示されません。
最初の <p> 要素は、アドインを使用するための手順をユーザーに提供します。

<main id="app-body" class="ms-welcome__main" style="display: none;">
    <div id="first-run-experience" style="display: none;">
        <h2 class="ms-font-xl"> Discover what Office Add-ins can do for you today! </h2>
        <ul class="ms-List ms-welcome__features">
            <li class="ms-ListItem">
                <i class="ms-Icon ms-Icon--Ribbon ms-font-xl"></i>
                <span class="ms-font-m">Achieve more with Office integration</span>
            </li>
            <li class="ms-ListItem">
                <i class="ms-Icon ms-Icon--Unlock ms-font-xl"></i>
                <span class="ms-font-m">Unlock features and functionality</span>
            </li>
            <li class="ms-ListItem">
                <i class="ms-Icon ms-Icon--Design ms-font-xl"></i>
                <span class="ms-font-m">Create and visualize like a pro</span>
            </li>
        </ul>
    </div>
    <p class="ms-font-l">Select any range of cells in the worksheet, then click <b>Run</b>.</p>
    <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
        <span class="ms-Button-label">Run</span>
    </div>
    <p><label id="item-subject"></label></p>    
</main>

Excel 以外の Office アプリケーションを選択した場合は、最初の <p> 要素をより適切な手順で更新します。

JavaScript ファイルを更新する

ユーザーがアドインを初めて実行する場合は、JavaScript ファイルを更新して初回実行エクスペリエンスを表示します。

taskpane.js ファイルを開きます。 Office.onReady ステートメントを次のコードに置き換え、ファイルを保存します。このコードに関するいくつかの注意事項:
- "showedFRE" というキーがローカルストレージでチェックされます。キーが存在しない場合は、最初の実行エクスペリエンスを表示します。
- showFirstRunExperienceという新しい関数が追加され、HTML に追加された "first-run-experience" <div>表示されます。この関数は、"showedFRE" 項目もローカルストレージに追加します。
```
Office.onReady((info) => {
  if (info.host === Office.HostType.Excel) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";

    // showedFRE is created and set to "true" when you call showFirstRunExperience().
    if (!localStorage.getItem("showedFRE")) {
      showFirstRunExperience();
    }

    document.getElementById("run").onclick = run;
  }
});

async function showFirstRunExperience() {
  document.getElementById("first-run-experience").style.display = "flex";
  localStorage.setItem("showedFRE", true);
}  
```
Excel 以外の Office アプリケーションを選択した場合は、最初の if ステートメントの条件を、選択した Office.HostType のチェックに更新します。

CSS ファイルを更新する

CSS ファイルを更新して、アドイン UI のスタイルが適切に設定されていることを確認し、"first-run-experience" <div>を追加します。

taskpane.css ファイルを開きます。行 .ms-welcome__main { を次のコードに置き換え、ファイルを保存します。
```
.ms-welcome__main, .ms-welcome__main > div {
```

試してみる

Web サーバーが実行されていて、アドインがサイドロードされていることを確認し、作業ウィンドウを開きます。詳細については、使用したクイックスタートの手順を参照してください。
作業ウィンドウに機能の一覧が含まれていることを確認します。
作業ウィンドウを閉じてから、もう一度開きます。作業ウィンドウに機能の一覧が表示されなくなったことを確認します。

次の手順

これで、初めての実行エクスペリエンスで Office 作業ウィンドウアドインが正常に作成されました。

運用環境の準備を整える

このチュートリアルを使用して、基本的な初回実行エクスペリエンスを実装しました。ユーザーが初めて実行するエクスペリエンスを準備するには、次の点を考慮する必要があります。

値 placemat に一覧表示されている機能を、アドインが実際に行う機能と一致するように更新します。
アドインの利点をより適切に示す別のパターン (ビデオプレースマットやカルーセルなど) を実装します。
最初の実行状態を追跡するには、より安全で堅牢なオプションを使用します。たとえば、使用可能な場合はストレージパーティション分割を使用するか、シングルサインオン (SSO) 認証ソリューションを実装します。
- 使用可能な設定オプションの詳細については、「アドインの状態と設定を保持する」を参照してください。
- 使用可能な認証オプションの詳細については、「認証と承認の概要」を参照してください。

Microsoft Marketplace でアドインを使用できるようにする予定の場合は、堅牢で便利な初回実行エクスペリエンスが必要です。詳細については、「Best practices for developing Office Add-ins」を参照してください。

コードサンプル

完了した初回実行エクスペリエンスチュートリアル: Excel でこのチュートリアルを完了した結果。

フィードバック

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

Last updated on 2025-10-11