使用 Microsoft 365 (预览版统一清单生成 Outlook 加载项)

有两种工具可用于创建使用 Microsoft 365 统一清单的 Outlook 外接程序项目。 本文介绍如何使用 Office (也称为“Yo Office”) 的 Yeoman 生成器执行此操作。 或者,可以使用 Teams 工具包创建 Outlook 外接程序项目,如使用 Teams 工具包 创建 Office 外接程序项目 (预览版) 中所述。

在本文中,你将演练生成 Outlook 任务窗格加载项的过程,此加载项显示所选邮件的属性,在阅读窗格中触发通知,并将文本插入撰写窗格上的邮件中。 此外接程序将使用 Teams 扩展(如自定义选项卡和消息扩展)使用的统一 JSON 格式清单的预览版本。 有关此清单的详细信息,请参阅 Microsoft 365 (预览版的统一清单)

注意

新清单可用于预览版,仅在 Outlook for Windows 上受支持。 它可能会根据反馈进行更改。 我们鼓励经验丰富的加载项开发人员进行试验。 预览清单不应用于生产加载项。

预览版仅在从 Microsoft 365 订阅下载并安装在 Windows 上的 Office 中受支持。

提示

如果要使用 XML 清单生成 Outlook 加载项,请参阅生成第一个 Outlook 加载项

创建加载项

可以使用 Office 外接程序的 Yeoman 生成器创建具有统一清单的 Office 外接程序。Yeoman 生成器创建一个 Node.js 项目,该项目可以使用Visual Studio Code或任何其他编辑器进行管理。

先决条件

  • 适用于 Windows 的 .NET 运行时。 预览版中使用的工具之一在 .NET 上运行。
  • 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 计划

创建加载项项目

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

    yo office
    

    注意

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

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

    • 选择项目类型 - Outlook Add-in with unified Microsoft 365 Manifest (preview)

    • 要如何命名加载项? - Add-in with Unified Manifest

    命令行界面中 Yeoman 生成器的提示和答案,其中选择了统一清单选项。

    注意

    对于此预览版,加载项名称不能超过 30 个字符。

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

    注意

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

    提示

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

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

    cd "Add-in with Unified Manifest"
    

浏览项目

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

  • 项目根目录中的 ./manifest/manifest.json 文件定义加载项的设置和功能。
  • ./src/taskpane/taskpane.html 文件包含组成任务窗格的 HTML。
  • ./src/taskpane/taskpane.css 文件包含应用于任务窗格中的内容的 CSS。
  • ./src/taskpane/taskpane.ts 文件包含调用 Office JavaScript 库以加快任务窗格与 Outlook 之间交互的代码。
  • ./src/command/command.html 文件将在生成时由 WebPack 编辑,以插入加载从 command.ts 文件所转译 JavaScript 文件的 HTML <script> 标记。
  • ./src/command/command.ts 文件起初几乎没有代码。 本文稍后将向其添加调用 Office JavaScript 库并在选择自定义功能区按钮时执行的代码。

更新代码

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

    提示

    在 Windows 上,可通过命令行导航到项目的根目录,然后输入 code .在 VS Code 中打开该文件夹。

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

    <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>
    

试用

注意

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

  1. 以管理员身份打开命令提示符,并在项目的根目录中运行以下命令。 运行此命令时,本地 Web 服务器将启动,并且将旁加载加载项。

    npm start
    

    注意

    如果这是你第一次在计算机上创建加载项,或者一个多月后第一次,系统会提示你安装安全证书。

  2. 使用 Outlook 中的经典功能区。 这些说明的其余部分假定存在此情况。

  3. 阅读窗格中查看邮件,或在其自己的窗口中打开邮件。 名为 Contoso 加载项的新控件组将显示在 Outlook 开始选项卡(如果在新窗口中打开邮件,则显示在邮件选项卡上)。 该组有一个名为“显示任务窗格”的按钮和一个名为“执行操作”的按钮。

  4. 选择“执行操作”按钮。 它执行一个命令 ,在消息标头底部的邮件正文正上方生成一个较小的信息通知。

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

    注意

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

  6. 若要打开加载项任务窗格,请选择“显示任务窗格”。

    注意

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

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

    注意

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

  8. 滚动至任务窗格的底部并选择 Run 链接,将邮件主题复制至任务窗格中。

  9. 使用以下命令结束调试会话:

    npm stop
    

    重要

    关闭 Web 服务器窗口并不能可靠地关闭 Web 服务器。 如果未正确关闭,则在更改并重新运行项目时会遇到问题。

  10. 关闭 Outlook 的所有实例。

向功能区添加自定义按钮

将自定义按钮添加到功能区,用于将文本插入到邮件正文中。

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

    提示

    在 Windows 上,可通过命令行导航到项目的根目录,然后输入 code .在 VS Code 中打开该文件夹。

  2. 在代码编辑器中,打开文件 ./src/command/command.ts,并将以下代码添加到文件末尾。 此函数将 Hello World 插入到邮件正文中的光标点。

    function insertHelloWorld(event: Office.AddinCommands.Event) {
        Office.context.mailbox.item.body.setSelectedDataAsync("Hello World", {coercionType: Office.CoercionType.Text});
    
        // Be sure to indicate when the add-in command function is complete
        event.completed();
    }
    
    // Register the function with Office
    Office.actions.associate("insertHelloWorld", insertHelloWorld);
    
  3. 打开文件 ./manifest/manifest.json

    注意

    引用嵌套 JSON 属性时,本文使用点表示法。 引用数组中的项时,将使用此项括号中的从零开始的编号。

  4. 如果写入邮件,需要提高加载项的权限。 滚动到属性 authorization.permissions.resourceSpecific[0].name 并将值更改为 MailboxItem.ReadWrite.User

  5. 当外接程序命令运行代码而不是打开任务窗格时,它必须在运行时中运行代码,该运行时独立于任务窗格代码运行的嵌入式 Web 视图。 因此,清单必须指定其他运行时。 滚动到属性 extension.runtimes 并将以下对象添加到 runtimes 数组。 请务必在数组中已有的对象之后放置逗号。 关于此标记,请注意以下几点。

    • actions[0].id 属性的值必须与添加到 commands.ts 文件的函数名称完全相同,在此情况中为 insertHelloWorld。 在后面的步骤中,将按此 ID 引用项目。
    {
        "id": "ComposeCommandsRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/commands.html",
            "script": "https://localhost:3000/commands.js"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "insertHelloWorld",
                "type": "executeFunction",
                "displayName": "insertHelloWorld"
            }
        ]
    }
    
  6. 用户正在阅读电子邮件时,将显示“显示任务窗格”按钮,但仅当用户撰写新电子邮件(或答复电子邮件)时,才应显示用于添加文本的按钮。 因此,清单必须指定新的功能区对象。 滚动到属性 extension.ribbons 并将以下对象添加到 ribbons 数组。 请务必在数组中已有的对象之后放置逗号。 请注意有关此 JSON 的以下事项:

    • contexts 数组中的唯一值是“mailCompose”,因此当在撰写(或答复)窗口中时,此按钮将显示,而不是在显示“显示任务窗格”和“执行操作”按钮的邮件阅读窗口中时。 将此值与 contexts 现有功能区对象中的数组进行比较,其值为 ["mailRead"]
    • tabs[0].groups[0].controls[0].actionId 的值必须与在前面的步骤中创建的运行时对象中 actions[0].id 属性的值完全相同。
    {
        "contexts": ["mailCompose"],
        "tabs": [
            {
                "builtInTabId": "TabDefault",
                "groups": [
                    {
                        "id": "msgWriteGroup",
                        "label": "Contoso Add-in",
                        "icons": [
                            { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" },
                            { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" },
                            { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" }
                        ],
                        "controls": [
                            {
                                "id": "HelloWorldButton",
                                "type": "button",
                                "label": "Insert text",
                                "icons": [
                                    { "size": 16, "url": "https://localhost:3000/assets/icon-16.png" },
                                    { "size": 32, "url": "https://localhost:3000/assets/icon-32.png" },
                                    { "size": 80, "url": "https://localhost:3000/assets/icon-80.png" }
                                ],
                                "supertip": {
                                    "title": "Insert text",
                                    "description": "Inserts some text."
                                },
                                "actionId": "insertHelloWorld"
                            }                  
                        ]
                    }
                ]
            }
        ]
    }
    

试用更新后的加载项

  1. 以管理员身份打开命令提示符,并在项目的根目录中运行以下命令。

    npm start
    
  2. 在 Outlook 中,打开一个新邮件窗口(或答复现有邮件)。 名为 Contoso 加载程序的新控件组将显示在 Outlook 邮件选项卡上。该组有一个名为插入文本的按钮。

  3. 将光标放在邮件正文中的任意位置,然后选择插入文本按钮。

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

    注意

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

    短语 "Hello World" 将插入光标处。

  5. 使用以下命令结束调试会话:

    npm stop
    

疑难解答

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

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

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

另请参阅