通过

旁加载使用 Microsoft 365 统一清单的 Office 加载项

旁加载使用 Microsoft 365 统一清单 的加载项的过程因要使用的工具以及加载项项目的创建方式而异。

注意

使用统一清单的加载项可以在 Windows 版本 2304 (内部版本 16320.20000) 或更高版本的 Office 上旁加载。 目前，无法在 Web、Mac 或 iPad 上旁加载它。

使用 Yeoman 生成器为 Office 加载项 (Yo Office) 旁加载加载项

通过 系统提示、bash shell 或终端使用旁加载中所述的过程。

使用 Microsoft 365 代理工具包旁加载

  1. 首先， 确保关闭要旁加载到的 Office 桌面应用程序。

  2. 在 Visual Studio Code中，打开“代理工具包”。

  3. 仅适用于 Outlook：在 “帐户 ”部分中，验证是否已登录到 Microsoft 365。

  4. 选择“查看 | Visual Studio Code中的运行”。 在 “运行和调试 ”下拉菜单中，根据加载项选择其中一个选项。

    • Excel Desktop (Edge Chromium)
    • Outlook Desktop (Edge Chromium)
    • PowerPoint Desktop (Edge Chromium)
    • Word桌面 (Edge Chromium)

  5. 按 F5。 项目生成并打开节点开发服务器窗口。 此过程可能需要几分钟时间，然后打开所选 Office 应用程序的桌面版本。 现在可以使用加载项。 对于 Outlook 加载项，请确保在 Microsoft 365 帐户标识的收件箱中工作。

  6. 若要停止调试并卸载加载项，请选择“在Visual Studio Code中运行 | 停止调试”。 关闭服务器窗口不会可靠地停止服务器，关闭 Office 应用程序不会可靠地导致 Office 取消获取加载项。

    注意

    如果前面的步骤似乎不起作用，请在 Visual Studio Code 中打开终端来卸载加载项，然后使用系统提示、bash shell 或终端完成旁加载部分的卸载步骤（最后一个步骤）。

使用系统提示、bash shell 或终端的旁加载

  1. 首先， 确保要旁加载到的 Office 桌面应用程序已关闭。
  2. 打开系统提示符、bash shell 或 Visual Studio Code 终端，并导航到项目的根目录。
  3. 旁加载加载项的命令取决于项目的创建时间。 "scripts"如果项目的 package.json 文件的节具有“start：desktop”脚本，则运行 npm run start:desktop;否则运行 npm run start。 项目生成并打开节点开发服务器窗口。 此过程可能需要几分钟时间，然后 Office 主机应用程序 (Excel、Outlook、PowerPoint 或桌面Word) 打开。
  4. 对于 Excel、PowerPoint 或 Word 加载项，还有一个附加步骤：选择“主页”功能区上的“加载项”按钮。 在打开的浮出控件上，选择加载项。 这将完成安装。
  5. 现在可以使用加载项。
  6. 使用完加载项后，请确保运行 命令 npm run stop。 关闭服务器窗口不会可靠地停止服务器，关闭 Office 应用程序不会可靠地导致 Office 取消获取加载项。

旁加载其他 NodeJS 和 npm 项目

有两种工具可用于旁加载。

使用 Office-Addin-Debugging 工具旁加载

  1. 若要旁加载加载项，请运行以下命令。 此命令将清单的 属性中引用的 "icons" 统一清单和两个图标图像文件放入 zip 文件，并将其旁加载到 Office 应用程序。 它还会在单独的 NodeJS 窗口中启动服务器，以在 localhost 上托管加载项文件。 有关此命令的更多详细信息，请参阅 Office-Addin-Debugging。

    npx office-addin-debugging start <relative-path-to-unified-manifest> desktop

  2. 使用 office-addin-debugging 启动外接程序时， 始终使用以下命令停止会话。 关闭服务器窗口不会可靠地停止服务器，关闭 Office 应用程序不会可靠地导致 Office 取消获取加载项。

    npx office-addin-debugging stop <relative-path-to-unified-manifest>

使用 Microsoft 365 代理工具包 CLI (命令行接口) 旁加载

  1. 使用以下步骤手动创建 zip 包。

    1. 打开统一清单并滚动到 "icons" 属性。 请注意两个图像文件的相对路径。
    2. 使用任何 zip 实用工具创建包含统一清单和两个映像文件的 zip 文件。 图像文件在 zip 文件中的相对路径必须与项目中的相对路径相同。 例如，如果相对路径为“assets/icon-64.png”和“assets/icon-128.png”，则必须在 "assets" zip 包中包含包含两个文件的文件夹。
    3. 如果文件夹包含其他文件（例如 Office 功能区中使用的图像文件），请从 zip 包中删除这些文件。 除了 zip 包) 根目录中 "icons" 的清单之外，它应仅具有属性 (中指定的两个映像文件。

  2. 在项目的根目录中，打开命令提示符或 bash shell 并运行以下命令以安装 Agents Toolkit CLI。

    npm install -g @microsoft/m365agentstoolkit-cli

  3. 运行以下命令以旁加载加载项。

    atk install --file-path <relative-path-to-zip-file>

    重要

    此命令返回有关加载项的一些信息，包括自动生成的游戏 ID，如以下示例所示。

    命令“atk install --file-path manifests/contoso/contoso.zip”和系统响应，包括用户的帐户名称、游戏 ID GUID 和应用 ID GUID。

    你将需要此游戏 ID 来结束旁加载和调试会话。 它记录在 Windows 计算机上的以下注册表项中：

    HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Wef\Developer\OutlookSideloadManifestPath\TitleId

    由于历史原因，字符串“Outlook”位于密钥名称中，但它适用于随 Agents Toolkit CLI 一起安装的任何加载项。

    仅记录随 CLI 一起安装的最新加载项。 如果在卸载与 CLI 一起安装的早期加载项之前，使用 CLI 旁加载加载项，则注册表中不会记录早期加载项的游戏 ID。 因此，建议同时将其保存在项目根目录中的文本文件中，并在 Mac 和 Windows 计算机上 TitleID.txt 命名该文件。

  4. 使用代理工具包 CLI 启动加载项时， 始终使用以下命令停止会话。 关闭服务器窗口不会可靠地停止服务器，关闭 Office 应用程序不会可靠地导致 Office 取消获取加载项。 将“{title ID}”替换为加载项的游戏 ID，包括“U_”前缀;例如 。 U_90d141c6-cf4f-40ee-b714-9df9ea593f39

    atk uninstall --mode title-id --title-id {title ID} --interactive false

    重要

    命令的文档uninstall介绍了使用加载项清单 ID 而不是标题 ID 的方法。 由于 CLI 调用的 API 中的 bug，此选项当前不起作用。 必须使用 uninstall 上面提供的 命令，并且必须包含 --interactive false 选项。