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

项目
10/16/2024

在本文中，你将逐步完成更新任务窗格加载项以包含使用值定位符模式的首次运行体验的过程。当用户运行外接程序时，加载项通过检查本地存储中的标志来确定是否显示首次运行体验。

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

提示

如果需要本教程的完整版本，请转到 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) 身份验证解决方案。有关可用设置选项的详细信息，请参阅持久保存加载项状态和设置。有关可用身份验证选项的详细信息，请参阅身份验证和授权概述。

如果计划使加载项在 AppSource 市场中可用，则需要获得可靠且有用的首次运行体验。有关详细信息，请参阅Best practices for developing Office Add-ins。

代码示例

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

通过