如何运行已完成的项目How to run the completed project

先决条件Prerequisites

若要在此文件夹中运行已完成的项目,需要执行以下操作:To run the completed project in this folder, you need the following:

  • Node.js 计算机上安装的Node.js和 线。Node.js and Yarn installed on your development machine. (:本教程是使用 Node 版本 14.15.0 和一线 1.22.0 编写的。(Note: This tutorial was written with Node version 14.15.0 and Yarn version 1.22.0. 本指南中的步骤可能与其他版本一起运行,但尚未测试。) The steps in this guide may work with other versions, but that has not been tested.)
  • 具有邮箱的个人 Microsoft 帐户Outlook.com Microsoft 工作或学校帐户。Either a personal Microsoft account with a mailbox on Outlook.com, or a Microsoft work or school account.

如果你没有 Microsoft 帐户,则有两种获取免费帐户的选项:If you don't have a Microsoft account, there are a couple of options to get a free account:

向 Azure Active Directory 管理中心注册 Web 应用程序Register a web application with the Azure Active Directory admin center

  1. 打开浏览器,并转到 Azure Active Directory 管理中心Open a browser and navigate to the Azure Active Directory admin center. 使用 个人帐户(亦称为“Microsoft 帐户”)或 工作或学校帐户 登录。Login using a personal account (aka: Microsoft Account) or Work or School Account.

  2. 选择左侧导航栏中的“Azure Active Directory”,再选择“管理”下的“应用注册”。Select Azure Active Directory in the left-hand navigation, then select App registrations under Manage.

    应用注册的屏幕截图A screenshot of the App registrations

  3. 选择“新注册”。Select New registration. 在“注册应用”页上,按如下方式设置值。On the Register an application page, set the values as follows.

    • 将“名称”设置为“Office Add-in Graph Tutorial”。Set Name to Office Add-in Graph Tutorial.
    • 将“受支持的帐户类型”设置为“任何组织目录中的帐户和个人 Microsoft 帐户”。Set Supported account types to Accounts in any organizational directory and personal Microsoft accounts.
    • 在“重定向 URI”下,将第一个下拉列表设置为“Single-page application (SPA)”,并将值设置为“https://localhost:3000/consent.html”。Under Redirect URI, set the first drop-down to Single-page application (SPA) and set the value to https://localhost:3000/consent.html.

    "注册应用程序"页的屏幕截图

  4. 选择“注册”。Select Register. "Office 外接程序图形 教程"页上,复制应用程序应用程序 (客户端) ID 并保存它,下一步将需要它。On the Office Add-in Graph Tutorial page, copy the value of the Application (client) ID and save it, you will need it in the next step.

    新应用注册的应用程序 ID 屏幕截图

  5. 选择“管理”下的“证书和密码”。Select Certificates & secrets under Manage. 选择“新客户端密码”按钮。Select the New client secret button. 在 Description 中 输入 值,然后选择"过期"选项之 一,然后选择"添加"。Enter a value in Description and select one of the options for Expires and select Add.

  6. 离开此页前,先复制客户端密码值。Copy the client secret value before you leave this page. 将在下一步中用到它。You will need it in the next step.

    重要

    此客户端密码不会再次显示,所以请务必现在就复制它。This client secret is never shown again, so make sure you copy it now.

  7. "管理"下****选择 API 权限,然后选择 "添加权限"。Select API permissions under Manage, then select Add a permission.

  8. 选择 Microsoft Graph, 然后选择 委派权限Select Microsoft Graph, then Delegated permissions.

  9. 选择以下权限,然后选择 "添加权限"。Select the following permissions, then select Add permissions.

    • Calendars.ReadWrite - 这将允许应用读取和写入用户的日历。Calendars.ReadWrite - this will allow the app to read and write to the user's calendar.
    • MailboxSettings.Read - 这将允许应用从用户的邮箱设置获取用户的时区。MailboxSettings.Read - this will allow the app to get the user's time zone from their mailbox settings.

    已配置权限的屏幕截图

配置 Office 外接程序单一登录Configure Office Add-in single sign-on

更新应用注册以支持 Office 外接程序单一登录 (SSO) 。 Update the app registration to support Office Add-in single sign-on (SSO).

  1. 选择 "公开 API"。Select Expose an API. 在此 API 定义的 范围部分中,选择 "添加范围"。In the Scopes defined by this API section, select Add a scope. 当系统提示设置应用程序 ID URI 时,将值设置为 api://localhost:3000/YOUR_APP_ID_HEREYOUR_APP_ID_HERE 以应用程序 ID 替换。When prompted to set an Application ID URI, set the value to api://localhost:3000/YOUR_APP_ID_HERE, replacing YOUR_APP_ID_HERE with the application ID. 选择 "保存"并继续Choose Save and continue.

  2. 按如下所示填写字段,然后选择"添加范围"。Fill in the fields as follows and select Add scope.

    • 范围名称:access_as_userScope name: access_as_user
    • 谁可以同意?:管理员和用户Who can consent?: Admins and users
    • 管理员同意显示名称:Access the app as the userAdmin consent display name: Access the app as the user
    • 管理员同意说明:Allows Office Add-ins to call the app's web APIs as the current user.Admin consent description: Allows Office Add-ins to call the app's web APIs as the current user.
    • 用户同意显示名称:Access the app as youUser consent display name: Access the app as you
    • 用户同意说明:Allows Office Add-ins to call the app's web APIs as you.User consent description: Allows Office Add-ins to call the app's web APIs as you.
    • 状态:已启用State: Enabled

    "添加范围"表单的屏幕截图

  3. 在"授权客户端应用程序"部分,选择 "添加客户端应用程序"。In the Authorized client applications section, select Add a client application. 从以下列表中输入客户端 ID,在"授权范围"下启用范围,然后选择"添加应用程序"。Enter a client ID from the following list, enable the scope under Authorized scopes, and select Add application. 对列表中的每个客户端 ID 重复此过程。Repeat this process for each of the client IDs in the list.

    • d3590ed6-52b3-4102-aeff-aad2292ab01c (Microsoft Office)d3590ed6-52b3-4102-aeff-aad2292ab01c (Microsoft Office)
    • ea5a67f6-b6f3-4338-b240-c655ddc3cc8e (Microsoft Office)ea5a67f6-b6f3-4338-b240-c655ddc3cc8e (Microsoft Office)
    • 57fb890c-0dab-4253-a5e0-7188c88b2bb4(Office 网页版)57fb890c-0dab-4253-a5e0-7188c88b2bb4 (Office on the web)
    • 08e18876-6177-487e-b8b5-cf950c1e598c(Office 网页版)08e18876-6177-487e-b8b5-cf950c1e598c (Office on the web)

安装开发证书Install development certificates

  1. 运行以下命令,为加载项生成和安装开发证书。Run the following command to generate and install development certificates for your add-in.

    npx office-addin-dev-certs install
    

    如果系统提示确认,请确认操作。If prompted for confirmation, confirm the actions. 命令完成后,你将看到如下所示的输出。Once the command completes, you will see output similar to the following.

    You now have trusted access to https://localhost.
    Certificate: <path>\localhost.crt
    Key: <path>\localhost.key
    
  2. 将路径复制到 localhost.crt 和 localhost.key,下一步将需要它们。Copy the paths to localhost.crt and localhost.key, you'll need them in the next step.

更新清单Update the manifest

  1. 打开 manifest.xml 文件,然后进行以下更改。Open the manifest.xml file and make the following changes.
    1. 替换为 NEW_GUID_HERE 新的 GUID,如 b4fa03b8-1eb6-4e8b-a380-e0476be9e019Replace NEW_GUID_HERE with a new GUID, like b4fa03b8-1eb6-4e8b-a380-e0476be9e019.
    2. 将应用注册的所有实例 YOUR_APP_ID_HERE 替换为应用程序 ID。Replace all instances of YOUR_APP_ID_HERE with the application ID from your app registration.

配置示例Configure the sample

  1. 将文件 example.env 重命名为 .envRename the example.env file to .env.

  2. 编辑 .env 文件并做出以下更改。Edit the .env file and make the following changes.

    1. 替换为 YOUR_APP_ID_HERE应用 注册门户获得的应用程序 ID。Replace YOUR_APP_ID_HERE with the Application Id you got from the App Registration Portal.
    2. 替换为 YOUR_CLIENT_SECRET_HERE 从应用注册门户获得的客户密码。Replace YOUR_CLIENT_SECRET_HERE with the client secret you got from the App Registration Portal.
    3. 替换为 PATH_TO_LOCALHOST.CRT 命令输出中 localhost.crt 文件 npx office-addin-dev-certs install 的路径。Replace PATH_TO_LOCALHOST.CRT with the path to your localhost.crt file from the output of the npx office-addin-dev-certs install command.
    4. 替换为 PATH_TO_LOCALHOST.KEY 命令输出中 localhost.key 文件 npx office-addin-dev-certs install 的路径。Replace PATH_TO_LOCALHOST.KEY with the path to your localhost.key file from the output of the npx office-addin-dev-certs install command.
  3. 将文件 config.example.js 重命名为 config.jsRename the config.example.js file to config.js.

  4. 编辑 config.js 文件并做出以下更改。Edit the config.js file and make the following changes.

    1. 替换为 YOUR_APP_ID_HERE应用 注册门户获得的应用程序 ID。Replace YOUR_APP_ID_HERE with the Application Id you got from the App Registration Portal.
  5. 在 CLI (命令行界面) ,导航到此目录并运行以下命令来安装要求。In your command-line interface (CLI), navigate to this directory and run the following command to install requirements.

    yarn install
    

运行示例Run the sample

  1. 在 CLI 中运行以下命令以启动应用程序。Run the following command in your CLI to start the application.

    yarn start
    
  2. 在浏览器中 ,转到Office.com 并登录。In your browser, go to Office.com and sign in. 选择 左侧 工具栏中的"创建",然后选择 "电子表格"。Select Create in the left-hand toolbar, then select Spreadsheet.

    "创建"菜单的屏幕截图Office.com

  3. 选择 "插入"选项卡,然后选择 "Office 加载项"。Select the Insert tab, then select Office Add-ins.

  4. 选择 "上载我的外接程序", 然后选择"浏览"。Select Upload My Add-in, then select Browse. 上传manifest.xml 文件Upload your manifest.xml file.

  5. 选择 "主页"****选项卡上的" 导入日历"按钮以打开任务窗格。Select the Import Calendar button on the Home tab to open the taskpane.

    "开始"选项卡上"导入日历"按钮的屏幕截图