构建具有基本首次运行体验的 Office 加载项

实现首次运行体验有助于用户加入并突出加载项的价值。本教程将指导你使用本地存储将简单的首次运行体验添加到 Office 加载项，以跟踪用户以前是否启动过加载项。

注意

首次运行体验是 Office 加载项的推荐模式。它可帮助用户了解加载项的功能并提高参与度。

要学习的知识

如何向加载项添加首次运行 UI。
如何使用浏览器本地存储来保存用户状态。
如何更新加载项的 HTML、TypeScript 或 JavaScript 和 CSS 文件以支持首次运行体验。

概述

当用户首次打开加载项时，你将显示欢迎消息和主要功能列表。在后续启动中，加载项将跳过“欢迎”并显示主 UI，而标志仍保留在本地存储中。这是通过检查本地存储中的标志并相应地更新 UI 来实现的。

注意

本地存储绑定到浏览器或 Webview 配置文件，可以将其清除，包括通过 Office 加载项缓存清除操作。如果清除标志或用户切换了配置文件，则首次运行体验可以再次出现。这适用于可恢复的载入状态，但不适用于必须跨会话或设备保留的跟踪。

本教程提供了 Excel 的说明和屏幕截图，但你可以使用类似的模式在支持 Office Web 加载项的其他 Office 应用程序中实现首次运行体验。

步骤

按照以下步骤实现首次运行体验：

更新 HTML：为首次运行体验添加容器。
更新 TypeScript 或 JavaScript：检查本地存储并显示首次运行的 UI（如果需要）。
更新 CSS：确保新 UI 的样式一致。
测试加载项：验证首次运行体验是否按预期工作。

让我们开始吧！

提示

如果需要本教程的完整版本，请访问 GitHub 上的 Office 加载项示例存储库。

先决条件

为要使用的 Office 应用程序选择 Office 快速入门。
- Excel
- OneNote
- Outlook
- PowerPoint
- Project
- Word
按照所选快速入门中的说明进行操作。完成其“试用”部分后，返回此处继续。

实现首次运行体验

更新 HTML 文件

明确将成为首次运行体验一部分的 UI 区域。在本教程中，您将创建一个 <div> 名为“first-run-experience”的元素，该元素 id 表示用户仅在首次运行加载项时看到的内容。

打开 taskpane.html。将元素 <main> 替换为以下标记，然后保存文件。有关此标记的一些注意事项：

在元素中<main>插入了“first-run-experience”<div>。它围绕着 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> 元素。

更新 TypeScript 或 JavaScript 文件

如果这是用户首次运行加载项，请更新 TypeScript 或 JavaScript 文件以显示首次运行体验。

如果选择了带有 Microsoft 365 统一清单的 Excel、PowerPoint 或 Word，则在继续操作之前，请执行以下操作。否则，转到下一步。
1. 打开 ./src/taskpane 文件夹中相应的 application-name.ts 文件。例如，如果使用 Excel，则为 ./src/taskpane/excel.ts。
2. 将特定于应用程序的函数重命名 (例如 runExcel，， runPowerPoint或 runWord) run为 .
3. 复制该文件的所有内容，然后替换该 taskpane.ts的所有内容。
4. 删除 application-name.ts 文件 (例如， excel.ts) 。

打开 taskpane.ts 或 taskpane.js 文件。将该 Office.onReady 语句替换为以下代码。有关此代码的一些说明：

它检查本地存储中是否存在名为“showedFRE”的密钥。如果密钥不存在，则显示首次运行体验。
它添加了一个名为“首次运行体验”的新 showFirstRunExperience 函数，用于显示添加到 HTML 的“首次运行体验” <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;
  }
});

function showFirstRunExperience() {
  document.getElementById("first-run-experience").style.display = "flex";
  localStorage.setItem("showedFRE", "true");
}

如果选择了除 Excel 之外的 Office 应用程序，请更新第一个if语句的条件以检查所选的 Office.HostType。
保存所做的更改。

更新 CSS 文件

更新 CSS 文件，以确保在添加“首次运行体验” <div>的情况下具有适当的加载项 UI 样式。

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

试用

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

后续步骤

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

使其生产准备就绪

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

更新值 placemat 中列出的功能，使其与加载项的实际功能相匹配。
实现不同的模式 (例如视频餐垫或轮播) ，以更好地展示加载项的好处。
如果需要跨会话或设备保留首次运行状态，请将其保存在与用户标识关联的联机数据库中。使用单一登录 (SSO) 获取该标识。存储分区有助于隔离本地数据，但不会使数据持久。单独的身份验证并不能保存状态。
- 有关可用设置选项的详细信息，请参阅保留加载项状态和设置。
- 有关可用身份验证选项的详细信息，请参阅身份验证和授权概述。

如果计划在 Microsoft Marketplace 中提供加载项，则必须具有强大且有用的首次运行体验。有关详细信息，请参阅Best practices for developing Office 加载项。

代码示例

已完成首次运行体验教程：使用 Excel 完成本教程的结果。

另请参阅

反馈

此页面是否有帮助？

上次更新时间为 2026-11-05