生成首个 Outlook 加载项

本文将逐步介绍如何生成显示选定邮件的至少一个属性的 Outlook 任务窗格加载项。

创建加载项

你可通过适用于 Office 加载项的 Yeoman 生成器或 Visual Studio 来创建 Office 加载项。 Yeoman 生成器将创建一个可通过 Visual Studio Code 或任何其他编辑器管理的 Node.js 项目，而 Visual Studio 将创建一个 Visual Studio 解决方案。 选择适合于想要使用的方法的选项卡，然后按照说明创建加载项并在本地测试。

Yeoman 生成器

先决条件

• Node.js（最新LTS 版本）。 访问 Node.js 站点 ，下载并安装适合你的操作系统的版本。

• 最新版本的 Yeoman 和适用于 Office 加载项的 Yeoman 生成器。若要全局安装这些工具，请从命令提示符处运行以下命令。

  npm install -g yo generator-office
  

  注意

  即便先前已安装了 Yeoman 生成器，我们还是建议你通过 npm 将包更新为最新版本。

• 已连接到 Microsoft 365 订阅的 Office (包括 Office 网页版)。

  注意

  如果你还没有 Office，你可能有资格通过 Microsoft 365 开发人员计划获得Microsoft 365 E5开发人员订阅;有关详细信息，请参阅常见问题解答。 或者，可以 注册 1 个月的免费试用版 或 购买 Microsoft 365 计划。

• Outlook 2016 或更高版本的 Windows (连接到 Microsoft 365 帐户) 、Outlook on Mac、Outlook 网页版 或新的 Windows 版 Outlook (预览版) 。

创建加载项项目

1. 运行以下命令，使用 Yeoman 生成器创建加载项项目。 包含项目的文件夹将添加到当前目录。

   yo office
   

   注意

   运行该yo office命令时，可能会收到有关 Yeoman 和 Office 加载项 CLI 工具的数据收集策略的提示。 根据你的需要，使用提供的信息来响应提示。

   出现提示时，请提供以下信息以创建加载项项目。

   • 选择项目类型 - Office Add-in Task Pane project

   • 选择脚本类型 - JavaScript

   • 要如何命名加载项？ - My Office Add-in

   • 要支持哪一个 Office 客户端应用程序? - Outlook

   

   完成此向导后，生成器会创建项目，并安装支持的 Node 组件。

   注意

   如果使用 Node.js 20.0.0 或更高版本，则当生成器运行安装时，可能会看到一条警告，指出你的引擎不受支持。 我们正在努力解决此问题。 同时，警告不会影响生成的生成器或项目，因此可以忽略它。

   提示

   创建加载项项目后，可忽略 Yeoman 生成器提供的后续步骤指南。 本文中的分步说明提供了完成本教程所需的全部指南。

2. 导航到 Web 应用程序项目的根文件夹。

   cd "My Office Add-in"
   

浏览项目

使用 Yeoman 生成器创建的加载项项目包含适合于基础任务窗格加载项的示例代码。

• 项目根目录中的 ./manifest.xml 文件定义加载项的设置和功能。
• ./src/taskpane/taskpane.html 文件包含组成任务窗格的 HTML。
• ./src/taskpane/taskpane.css 文件包含应用于任务窗格中的内容的 CSS。
• ./src/taskpane/taskpane.js 文件包含用于加快任务窗格与 Outlook 之间的交互的 Office JavaScript API 代码。

更新代码

1. 在 VS Code 或首选代码编辑器中打开项目。

   提示

   在 Windows 上，可通过命令行导航到项目的根目录，然后输入 code .在 VS Code 中打开该文件夹。 在 Mac 上，需要先将 code 命令添加到路径中，然后才可使用该命令在 VS Code 中打开项目文件夹。

2. 打开文件 ./src/taskpane/taskpane.html，将 body> 元素) 中的<整个 <main> 元素 (替换为以下标记。 此新标记将添加标签，其中 ./src/taskpane/taskpane.js 中的脚本将写入数据。

   <main id="app-body" class="ms-welcome__main" style="display: none;">
       <h2 class="ms-font-xl"> Discover what Office Add-ins can do for you today! </h2>
       <p><label id="item-subject"></label></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>
   </main>
   

3. 在代码编辑器中，打开文件 ./src/taskpane/taskpane.js，然后将以下代码添加到 run 函数。 此代码使用 Office JavaScript API 获取当前邮件的引用并将其 subject 属性值写入任务窗格。

   // Get a reference to the current message
   const item = Office.context.mailbox.item;
   
   // Write message property value to the task pane
   document.getElementById("item-subject").innerHTML = "<b>Subject:</b> <br/>" + item.subject;
   

   taskpane.js 文件现在应包含以下代码。

   /*
    * Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
    * See LICENSE in the project root for license information.
    */
   
   /* global document, Office */
   
   Office.onReady((info) => {
     if (info.host === Office.HostType.Outlook) {
       document.getElementById("sideload-msg").style.display = "none";
       document.getElementById("app-body").style.display = "flex";
       document.getElementById("run").onclick = run;
     }
   });
   
   export async function run() {
     // Get a reference to the current message
     const item = Office.context.mailbox.item;
   
     // Write message property value to the task pane
     document.getElementById("item-subject").innerHTML = "<b>Subject:</b> <br/>" + item.subject;
   }
   

试用

注意

即使在开发过程中，Office 外接程序也应使用 HTTPS，而不是 HTTP。 如果在运行以下命令之一后系统提示安装证书，请接受安装 Yeoman 生成器提供的证书的提示。 你可能还必须以管理员身份运行命令提示符或终端才能进行更改。

1. 在项目的根目录中运行以下命令。 运行此命令时，本地 Web 服务器将启动，加载项将旁加载。

   npm start
   

   注意

   如果加载项未自动旁加载，请按照 旁加载 Outlook 外接程序 中的说明进行测试，在 Outlook 中手动旁加载加载项。

2. 在 Outlook 中，在阅读窗格中查看邮件，或在其自己的窗口中打开邮件。

3. 如果在) 的窗口中打开邮件，请选择“ 开始 ”选项卡 (或“ 邮件 ”选项卡，然后选择功能区上的“ 显示任务窗格 ”按钮以打开加载项任务窗格。

   

4. 当系统提示“Web 视图在加载时停止”对话框时，请选择“确定”。

   注意

   如果选择“取消”，则当加载项的此实例正在运行时，将不会再次显示该对话框。 但如果重新启动加载项，则会再次看到该对话框。

5. 滚动至任务窗格的底部并选择“运行”链接，将邮件主题写入任务窗格。

   

   

后续步骤

祝贺！已成功创建首个 Outlook 任务窗格加载项！ 接下来，将继续学习 Outlook 加载项教程，详细了解 Outlook 加载项的功能，以及如何生成更复杂的加载项。

Visual Studio

先决条件

• 安装了 Office/SharePoint 开发工作负载的 Visual Studio 2019 或更高版本

  注意

  如果以前安装了 Visual Studio 2019 或更高版本，请使用 Visual Studio 安装程序确保已安装 Office/SharePoint 开发工作负载。

• 已连接到 Microsoft 365 订阅的 Office (包括 Office 网页版)。

创建加载项项目

1. 在 Visual Studio 菜单栏中，依次选择“文件”>“新建”>“项目”。

2. 在“Visual C#”或“Visual Basic”下的项目类型列表中，展开“Office/SharePoint”，选择“加载项”，然后选择“Outlook Web 加载项”作为项目类型。

3. 命名此项目，再选择“确定”。

4. 此时，Visual Studio 创建解决方案，且它的两个项目显示在“解决方案资源管理器”中。 MessageRead.html 文件在 Visual Studio 中打开。

浏览 Visual Studio 解决方案

在用户完成向导后，Visual Studio 会创建一个包含两个项目的解决方案。

项目	说明
加载项项目	仅包含 XML 清单文件，内含描述加载项的所有设置。 这些设置有助于 Office 应用程序确定应在何时激活加载项，以及应在哪里显示加载项。 Visual Studio 生成了此文件的内容，以便于用户能够立即运行项目并使用外接程序。 可以通过修改 XML 文件随时更改这些设置。
Web 应用项目	包含加载项的内容页，包括开发 Office 感知 HTML 和 JavaScript 页面所需的全部文件和文件引用。 开发外接程序时，Visual Studio 在本地 Internet Information Services (IIS) 服务器上托管 Web 应用程序。 准备好发布加载项后，需要将此 Web 应用项目部署到 Web 服务器。

更新代码

1. MessageRead.html 指定将在加载项的任务窗格中呈现的 HTML。 在 MessageRead.html中，将 <body> 元素替换为以下标记并保存文件。

   <body class="ms-font-m ms-welcome">
       <div class="ms-Fabric content-main">
           <h1 class="ms-font-xxl">Message properties</h1>
           <table class="ms-Table ms-Table--selectable">
               <thead>
                   <tr>
                       <th>Property</th>
                       <th>Value</th>
                   </tr>
               </thead>
               <tbody>
                   <tr>
                       <td><strong>Id</strong></td>
                       <td class="prop-val"><code><label id="item-id"></label></code></td>
                   </tr>
                   <tr>
                       <td><strong>Subject</strong></td>
                       <td class="prop-val"><code><label id="item-subject"></label></code></td>
                   </tr>
                   <tr>
                       <td><strong>Message Id</strong></td>
                       <td class="prop-val"><code><label id="item-internetMessageId"></label></code></td>
                   </tr>
                   <tr>
                       <td><strong>From</strong></td>
                       <td class="prop-val"><code><label id="item-from"></label></code></td>
                   </tr>
               </tbody>
           </table>
       </div>
   </body>
   

2. 打开 Web 应用项目的根文件夹中的文件“MessageRead.js”。 此文件指定的是加载项脚本。 将整个内容替换为以下代码，并保存文件。

   'use strict';
   
   (function () {
   
       Office.onReady(function () {
           // Office is ready
           $(document).ready(function () {
               // The document is ready
               loadItemProps(Office.context.mailbox.item);
           });
       });
   
       function loadItemProps(item) {
           // Write message property values to the task pane
           $('#item-id').text(item.itemId);
           $('#item-subject').text(item.subject);
           $('#item-internetMessageId').text(item.internetMessageId);
           $('#item-from').html(item.from.displayName + " <" + item.from.emailAddress + ">");
       }
   })();
   

3. 打开 Web 应用项目的根文件夹中的文件“MessageRead.css”。 此文件指定的是加载项自定义样式。 将整个内容替换为以下代码，并保存文件。

   html,
   body {
       width: 100%;
       height: 100%;
       margin: 0;
       padding: 0;
   }
   
   td.prop-val {
       word-break: break-all;
   }
   
   .content-main {
       margin: 10px;
   }
   

更新清单

1. 打开加载项项目中的 XML 清单文件。 此文件定义的是加载项设置和功能。

2. <ProviderName> 元素具有占位符值。 将其替换为你的姓名。

3. DisplayName> 元素的<DefaultValue 属性具有占位符。 将其替换为 My Office Add-in。

4. Description> 元素的<DefaultValue 属性具有占位符。 将其替换为 My First Outlook add-in。

5. 保存文件。

   ...
   <ProviderName>John Doe</ProviderName>
   <DefaultLocale>en-US</DefaultLocale>
   <!-- The display name of your add-in. Used on the store and various places of the Office UI such as the add-ins dialog. -->
   <DisplayName DefaultValue="My Office Add-in" />
   <Description DefaultValue="My First Outlook add-in"/>
   ...
   

试用

1. 使用 Visual Studio，通过按 F5 或选择“ 开始 ”按钮来测试新创建的 Outlook 加载项。 加载项本地托管在 IIS 上。

2. 在 “连接到 Exchange 电子邮件帐户 ”对话框中，输入 Microsoft 帐户的电子邮件地址和密码，然后选择“ 连接”。 如果 Outlook.com 登录页是在浏览器中打开，请使用先前输入的相同凭据登录电子邮件帐户。

   注意

   如果“ 连接到 Exchange 电子邮件帐户 ”对话框反复提示你登录，或者你收到错误，指出你未授权，则 Microsoft 365 租户上的帐户可能会关闭基本身份验证。 若要测试此加载项，请在“Web 外接程序项目属性”对话框的“部署”部分中将 “使用多重身份验证 ”属性设置为 True 后再次尝试登录，或者改用 Microsoft 帐户 登录。

3. 邮箱将在 Outlook 网页版 打开。 选择或打开邮件。

   提示

   还可以在 Outlook on Windows 中测试加载项，前提是 IIS 服务器正在运行。

4. 在消息中，导航到操作栏，然后选择“ 应用”。

   

5. 在加载项列表中，选择“ 我的 Office 加载项”，然后选择“ 显示任务窗格”。

   

6. 从打开的任务窗格中查看所选消息的属性。

   

   注意

   如果任务窗格未加载，请尝试通过在同一台计算机上的浏览器中打开它来进行验证。

后续步骤

祝贺！已成功创建首个 Outlook 任务窗格加载项！ 接下来，了解有关使用 Visual Studio 开发 Office 加载项的详细信息。

疑难解答

• 按照设置开发环境中的说明，确保环境已准备好进行 Office 开发。

• Yo Office 执行的自动 npm install 步骤可能会失败。 如果在尝试运行 npm start时看到错误，请在命令提示符中导航到新创建的项目文件夹并手动运行 npm install。 有关 Yo Office 的详细信息，请参阅 使用 Yeoman 生成器创建 Office 外接程序项目。

• 如果外接程序显示错误 (例如“无法启动此加载项”。关闭此对话框以忽略问题，或单击“重启”重试。) 按 F5 或选择“在Visual Studio 中调试>开始调试”时，请参阅在 Visual Studio 中调试 Office 加载项了解其他调试选项。

• 一些示例代码使用 ES6 JavaScript。 这与 使用 Trident (Internet Explorer 11) 浏览器引擎的旧版 Office 不兼容。 有关如何在外接程序中支持这些平台的信息，请参阅 支持较旧的 Microsoft Webviews 和 Office 版本。 如果你还没有用于开发的 Microsoft 365 订阅，你可能有资格通过 Microsoft 365 开发人员计划获得Microsoft 365 E5开发人员订阅;有关详细信息，请参阅常见问题解答。 或者，可以 注册 1 个月的免费试用版 或 购买 Microsoft 365 计划。

如果在任务窗格中收到错误“我们无法从本地主机打开此加载项”，请按照疑难解答文章中中所述步骤进行操作。

代码示例

• Outlook“Hello world”加载项：了解如何生成仅包含清单、HTML 网页和徽标的简单 Office 加载项。

另请参阅

• Office 加载项 XML 清单
• 使用 Visual Studio Code 发布