生成具有基本首次运行体验的 Office 加载项

2025-10-11

实现首次运行体验有助于载入用户并突出显示加载项的价值。本教程指导你使用本地存储将简单的首次运行体验添加到 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 区域。在本教程中，你将创建一个名为 <div> “first-run-experience”的元素，该元素 id 表示用户仅在首次运行外接程序时看到的内容。

打开 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 文件，以确保在添加了“first-run-experience <div>”的情况下，加载项 UI 的样式正确。

打开 taskpane.css 文件。将行 .ms-welcome__main { 替换为以下代码，然后保存文件。
```
.ms-welcome__main, .ms-welcome__main > div {
```

试用

确保 Web 服务器正在运行且加载项已旁加载，然后打开任务窗格。有关详细信息，请参阅使用的快速入门中的说明。
验证任务窗格是否包含功能列表。
关闭任务窗格，然后重新打开它。验证任务窗格是否不再显示功能列表。

后续步骤

恭喜，你已成功创建具有首次运行体验的 Office 任务窗格加载项！

使其准备好生产

使用本教程，你实现了基本的首次运行体验。若要为用户准备好首次运行体验，应考虑以下事项：

更新 value placemat 中列出的功能，使其与加载项的实际功能相匹配。
实现不同的模式 (例如视频放置或旋转) ，以更好地展示外接程序的优势。
使用更安全、更可靠的选项来跟踪首次运行状态。例如，使用存储分区（如果可用），或实现单一登录 (SSO) 身份验证解决方案。
- 有关可用设置选项的详细信息，请参阅持久保存加载项状态和设置。
- 有关可用身份验证选项的详细信息，请参阅身份验证和授权概述。

如果你计划使加载项在 Microsoft 市场中可用，则必须具有强大而有用的首次运行体验。有关详细信息，请参阅Best practices for developing Office Add-ins。