生成首个 Outlook 加载项Build your first Outlook add-in

本文将逐步介绍如何生成显示选定邮件的至少一个属性的 Outlook 任务窗格加载项。In this article, you'll walk through the process of building an Outlook task pane add-in that displays at least one property of a selected message.

创建加载项Create the add-in

可以使用适用于 Office 加载项的 Yeoman 生成器或 Visual Studio 创建 Office 加载项。You can create an Office Add-in by using the Yeoman generator for Office Add-ins or Visual Studio. Yeoman 生成器将创建一个可通过 Visual Studio Code 或任何其他编辑器管理的 Node.js 项目,而 Visual Studio 将创建一个 Visual Studio 解决方案。The Yeoman generator creates a Node.js project that can be managed with Visual Studio Code or any other editor, whereas Visual Studio creates a Visual Studio solution. 选择适合于想要使用的方法的选项卡,然后按照说明创建加载项并在本地测试。Select the tab for the one you'd like to use and then follow the instructions to create your add-in and test it locally.

先决条件Prerequisites

  • Node.js(版本 8.0.0 或更高版本)Node.js (version 8.0.0 or later)

  • 最新版本的 Yeoman适用于 Office 外接程序的 Yeoman 生成器。若要全局安装这些工具,请从命令提示符处运行以下命令:The latest version of Yeoman and the Yeoman generator for Office Add-ins. To install these tools globally, run the following command via the command prompt:

    npm install -g yo generator-office
    

    备注

    即便先前已安装了 Yeoman 生成器,我们还是建议你通过 npm 将包更新为最新版本。Even if you've previously installed the Yeoman generator, we recommend you update your package to the latest version from npm.

创建加载项项目Create the add-in project

  1. 使用 Yeoman 生成器创建 Outlook 加载项项目。Use the Yeoman generator to create an Outlook add-in project. 运行下面的命令,再回答如下所示的提示问题:Run the following command and then answer the prompts as follows:

    yo office
    
    • 选择项目类型 - Office Add-in Task Pane projectChoose a project type - Office Add-in Task Pane project

    • 选择脚本类型 - JavascriptChoose a script type - Javascript

    • 要如何命名加载项?What do you want to name your add-in? - My Office Add-in

    • 要支持哪一个 Office 客户端应用程序?Which Office client application would you like to support? - Outlook

    有关 Yeoman 生成器提示和回答的屏幕截图

    完成此向导后,生成器会创建项目,并安装支持的 Node 组件。After you complete the wizard, the generator will create the project and install supporting Node components.

  2. 导航到 Web 应用程序项目的根文件夹。Navigate to the root folder of the web application project.

    cd "My Office Add-in"
    

浏览项目Explore the project

使用 Yeoman 生成器创建的加载项项目包含适合于基础任务窗格加载项的示例代码。The add-in project that you've created with the Yeoman generator contains sample code for a very basic task pane add-in.

  • 项目根目录中的 ./manifest.xml 文件定义加载项的设置和功能。The ./manifest.xml file in the root directory of the project defines the settings and capabilities of the add-in.
  • ./src/taskpane/taskpane.html 文件包含组成任务窗格的 HTML。The ./src/taskpane/taskpane.html file contains the HTML markup for the task pane.
  • ./src/taskpane/taskpane.css 文件包含应用于任务窗格中的内容的 CSS。The ./src/taskpane/taskpane.css file contains the CSS that's applied to content in the task pane.
  • ./src/taskpane/taskpane.js 文件包含用于加快任务窗格与 Outlook 之间的交互的 Office JavaScript API 代码。The ./src/taskpane/taskpane.js file contains the Office JavaScript API code that facilitates interaction between the task pane and Outlook.

更新代码Update the code

  1. 在代码编辑器中,打开文件 ./src/taskpane/taskpane.html 并将整个 <main> 元素(位于 <body> 元素中)替换为以下标记。In your code editor, open the file ./src/taskpane/taskpane.html and replace the entire <main> element (within the <body> element) with the following markup. 此新标记将添加标签,其中 ./src/taskpane/taskpane.js 中的脚本将写入数据。This new markup adds a label where the script in ./src/taskpane/taskpane.js will write data.

    <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>
    
  2. 在代码编辑器中,打开文件 ./src/taskpane/taskpane.js 并在 run 函数中添加以下代码。In your code editor, open the file ./src/taskpane/taskpane.js and add the following code within the run function. 此代码使用 Office JavaScript API 获取当前邮件的引用并将其 subject 属性值写入任务窗格。This code uses the Office JavaScript API to get a reference to the current message and write its subject property value to the task pane.

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

试用Try it out

备注

Office 加载项应使用 HTTPS,而不是 HTTP(即便是在开发时也是如此)。Office Add-ins should use HTTPS, not HTTP, even when you are developing. 如果系统在运行以下命令之一后提示你安装证书,请接受提示以安装 Yeoman 生成器提供的证书。If you are prompted to install a certificate after you run one of the following commands, accept the prompt to install the certificate that the Yeoman generator provides.

提示

如果在 Mac 上测试加载项,请先运行以下命令,然后再继续。If you're testing your add-in on Mac, run the following command before proceeding. 运行此命令时,本地 Web 服务器将启动。When you run this command, the local web server will start.

npm run dev-server
  1. 在项目的根目录中运行以下命令。Run the following command in the root directory of your project. 运行此命令时,本地 Web 服务器将启动(如果尚未运行)。When you run this command, the local web server will start.

    npm start
    
  2. 按照旁加载 Outlook 加载项以供测试中的说明操作,旁加载加载项。Follow the instructions in Sideload Outlook add-ins for testing to sideload the add-in in Outlook.

  3. 在 Outlook 中,选择或打开邮件。In Outlook, select or open a message.

  4. 选择“主页”选项卡(或“邮件”选项卡,如果在新窗口中打开了邮件),然后选择功能区的“显示任务窗格”按钮以打开加载项任务窗格。Choose the Home tab (or the Message tab if you opened the message in a new window), and then choose the Show Taskpane button in the ribbon to open the add-in task pane.

    Outlook 中邮件窗口的屏幕截图,突出显示了加载项按钮

  5. 滚动至任务窗格的底部并选择“运行”链接,将邮件主题写入任务窗格。Scroll to the bottom of the task pane and choose the Run link to write the message subject to the task pane.

    加载项任务窗格的屏幕截图,其中显示邮件属性

后续步骤Next steps

祝贺!已成功创建首个 Outlook 任务窗格加载项!Congratulations, you've successfully created your first Outlook task pane add-in! 接下来,将继续学习 Outlook 加载项教程,详细了解 Outlook 加载项的功能,以及如何生成更复杂的加载项。Next, learn more about the capabilities of an Outlook add-in and build a more complex add-in by following along with the Advanced Outlook add-in tutorial.