使用自定义选项卡扩展团队应用程序Extend your Teams app with a custom tab

自定义选项卡使您能够为您承载于频道、组聊天和个人用户的 web 内容提供服务。Custom tabs allow you to serve web content that you host to your channel, group chat, and personal users. 在较高级别,需要完成以下步骤以创建选项卡:At a high level, you'll need to complete the following steps to create a tab:

  1. 准备开发环境。Prepare your development environment.
  2. (s) 创建页面。Create your page(s).
  3. 承载你的应用服务。Host your app service.
  4. 创建您的应用程序包并上传到 Microsoft 团队。Create your app package and upload to Microsoft Teams.

准备开发环境Prepare your development environment

您需要做的第一件事是准备开发环境。The first thing you'll need to do is prepare your development environment. 您需要确保为您要在其中构建您的应用程序的 Office 365 组织启用自定义应用程序上载。You'll need to make sure custom app uploading is enabled for the Office 365 organization you want to build your app in. 如果需要专用开发租户,可以注册Office 365 开发人员计划If you need a dedicated development tenant, you can sign up for the Office 365 developer program. 有关其他信息,请参阅设置您的开发环境For additional information see Setup your development environment.

(s) 创建页面Create your page(s)

无论您是在个人还是频道/组作用域中提供选项卡,它都将包含一个或多个您承载的 HTML 页面。Whether you present your tab within the personal or channel/group scope, it will consist of one or more HTML pages that you host. 包含个人作用域的选项卡由单个内容页面组成,而具有频道或组作用域的选项卡将需要配置页面,该页面将根据安装时的用户输入设置内容页面的 URL。Tabs with a personal scope consist of a single content page, while tabs with a channel or group scope will require a configuration page that sets the URL of the content page based on user input at the time of installation.

有三种类型的选项卡页。There are three types of tab pages. 有关创建它们的完整详细信息,请参阅相应的文档页面。See the corresponding documentation page for full details on creating them.

  1. 内容页,在选项卡中显示的页面。Content page, the page displayed in a tab.
  2. 配置页面,用于设置或更新内容页面 URL 的页面,并将其添加到频道/组选项卡。Configuration page, the page used to set or update the content page URL, and add it to a channel/group tab.
  3. 删除页面,删除频道/组选项卡时显示的可选页面。Removal page, an optional page that is displayed when a channel/group tab is removed.

选项卡要求Tab requirements

无论页面的类型如何,您都需要遵循以下要求:Regardless of the type of page, you're tab will need to adhere to the following requirements:

  • 您必须允许通过 X 框架选项和/或内容安全策略 HTTP 响应标头在 IFrame 中提供页面。You must allow your pages to be served in an IFrame, via X-Frame-Options and/or Content-Security-Policy HTTP response headers.
    • 设置标头: Content-Security-Policy: frame-ancestors teams.microsoft.com *.teams.microsoft.com *.skype.comSet header: Content-Security-Policy: frame-ancestors teams.microsoft.com *.teams.microsoft.com *.skype.com
    • 对于 Internet Explorer 11 兼容性, X-Content-Security-Policy 也设置。For Internet Explorer 11 compatibility, set X-Content-Security-Policy as well.
    • 或者,设置标头 X-Frame-Options: ALLOW-FROM https://teams.microsoft.com/Alternatively, set header X-Frame-Options: ALLOW-FROM https://teams.microsoft.com/. 此标头已弃用,但仍受大多数浏览器的考虑。This header is deprecated but still respected by most browsers.
  • 通常,作为针对 jacking 的安全措施,登录页面不会呈现在 Iframe 中。Typically, as a safeguard against click-jacking, login pages don't render in IFrames. 因此,身份验证逻辑需要使用重定向 (以外的方法,例如,使用基于令牌的身份验证或基于 cookie 的身份验证) 。Therefore, your authentication logic needs to use a method other than redirect (e.g., use token-based or cookie-based authentication).

备注

Chrome 80,安排在早期2020中发布,默认引入新的 cookie 值并强加 cookie 策略。Chrome 80, scheduled for release in early 2020, introduces new cookie values and imposes cookie policies by default. 建议您为 cookie 设置预期用途,而不是依赖于默认浏览器行为。It's recommended that you set the intended use for your cookies rather than rely on default browser behavior. 请参阅 SameSite cookie 属性 (2020 update) See SameSite cookie attribute (2020 update).

  • 浏览器遵循同一个源策略限制,以防止网页发出请求,而不是为 web 页提供服务的其他域。Browsers adhere to a same-origin policy restriction that prevents a webpage from making requests to a different domain than the one that served a web page. 但是,您可能需要将配置或内容页面重定向到另一个域或子域。However, you may need to redirect the configuration or content page to a another domain or subdomain. 您的跨域导航逻辑应允许团队客户端在加载或与选项卡通信时,针对应用程序清单中的静态 validDomains 列表验证源。Your cross-domain navigation logic should allow the Teams client to validate the origin against a static validDomains list in the app manifest when loading or communicating with the tab.

  • 若要创建无缝体验,应根据团队客户端的主题、设计和意图来设计选项卡的样式。To create a seamless experience, you should style your tabs based on the Teams client's theme, design, and intent. 通常,在构建以满足特定需求并将重点放在一小部分任务或与选项卡的频道位置相关的数据子集时,选项卡的工作效果最佳。Typically, tabs work best when they're built to address a specific need and focus on a small set of tasks or a subset of data that is relevant to the tab's channel location.

  • 在内容页面中,添加对 Microsoft 团队 JavaScript 客户端 SDK (使用脚本标记)的引用。Within your content page, add a reference to Microsoft Teams JavaScript client SDK using script tags. 在页面加载后,对进行调用 microsoftTeams.initialize()Following your page load, make a call to microsoftTeams.initialize(). 如果不显示页面,则不会显示。Your page will not be displayed if you do not.

承载你的应用服务Host your app service

需要将你的内容托管在可使用 HTTPS 的公开可用 URL 上。Your content needs to be hosted on a publicly available URL available using HTTPS. 对于测试,可以使用反向代理(如 ngrok)将本地端口公开给面向 INTERNET 的 URL。For testing, you can use a reverse proxy, such as ngrok, to expose your local port to an internet-facing URL.

使用应用程序 Studio 创建应用程序包Create your app package with App Studio

您可以使用 Microsoft 团队客户端中的应用程序 Studio 应用来帮助创建应用程序清单。You can use the App Studio app from within the Microsoft Teams client to help create your app manifest. 如果未在团队中安装应用程序 studio,请选择 "团队" 应用的左下角的 " 应用  商店应用", 然后搜索应用程序 studio。If you do not have App studio installed in Teams, select Apps Store App at the bottom-left corner of the Teams app, and search for App Studio. 找到该磁贴后,选择它并在弹出窗口对话框中选择 "安装"。Once you find the tile, select it and choose install in the pop-up window dialog box.

  1. 打开 Microsoft 团队客户端—使用 基于 web 的版本 ,您可以使用浏览器的 开发人员工具检查您的前端代码。Open the Microsoft Teams client—using the web based version will enable you to inspect your front-end code using your browser's developer tools.
  2. 打开应用程序 Studio 并选择 " 清单编辑器 " 选项卡。Open App Studio and select the Manifest editor tab.
  3. 选择 " 创建新的应用程序 " 磁贴。Choose the Create a new app tile.
  4. 添加应用程序详细信息 (请参阅 清单架构定义 ,以获取每个字段) 的完整说明。Add your app details (see the manifest schema definition for full description of each field).
  5. 在 "功能" 部分,选择 " 选项卡"。In the capabilities section select Tabs.
    • 对于 "个人" 选项卡,选择 " 添加个人" 选项卡 ,然后选择 " 添加"。For a personal tab, choose Add a personal tab and select Add. 将显示一个弹出对话框窗口,可在其中添加选项卡详细信息。You will be presented with a pop-up dialogue window where you can add your tab details.
    • 对于 "通道/组" 选项卡,在 " 团队" 选项卡下选择 " 添加 " 并完成 "团队" 选项卡弹出窗口中的选项卡详细信息字段。For a channel/group tab, under Team Tab select Add and complete the tab details fields in the Team tab pop-up window. 请确保 可以更新配置? 选中 "工作组" 和 " 组" 聊天 框,然后选择 " 保存"。Make sure the can update configuration? Team and Group chat boxes are checked and select Save.
  6. 在 " 域和权限 " 部分中," 选项卡 " 字段中的域应包含不带 HTTPS 前缀的主机或反向代理 URL。In the Domains and permissions section, the Domains from your tabs field should contain your host or reverse proxy URL without the HTTPS prefix.
  7. 在 "完成 => 测试和分布" 选项卡上,您可以下载应用程序包,将包安装到团队中,或提交到团队应用商店以供审批。From the Finish => Test and distribute tab you can Download your app package, Install the package into a team, or Submit to the Teams app store for approval. 如果使用反向代理,将在右侧的 " 说明 " 字段中收到警告。在测试选项卡时可以忽略此警告If you are using a reverse proxy you will get a warning in the Description field on the right. The warning can be ignored while testing your tab.

手动创建应用程序包Create your app package manually

与 bot 和邮件扩展一样,您可以更新应用程序 清单 以包含选项卡属性。As with bots and messaging extensions, you update the app manifest of your app to include the tab properties. 这些属性控制您的选项卡在中可用的范围、要使用的 Url 以及各种其他属性。These properties govern the scopes your tab is available in, the URLs to be used, and various other properties.

个人选项卡Personal Tabs

"个人" 选项卡的显示内容对于所有用户都是相同的,并在阵列中进行配置 staticTabsThe displayed content for personal tabs is the same for all users and is configured in the staticTabs array. 您可以在应用程序中声明最高 16 (16) 个人选项卡。You may declare up to sixteen (16) personal tabs in an app.

名称Name 类型Type 最大大小Maximum size 必需Required 说明Description
entityId 字符串String 64 个字符64 characters 选项卡显示的实体的唯一标识符。A unique identifier for the entity that the tab displays.
name 字符串String 128个字符128 characters 该选项卡在通道接口中的显示名称。The display name of the tab in the channel interface.
contentUrl 字符串String 2048 个字符2048 characters 指向要在团队画布中显示的实体 UI 的 https://URL。The https:// URL that points to the entity UI to be displayed in the Teams canvas.
websiteUrl 字符串String 2048 个字符2048 characters 要指向的 https://URL,如果用户要在浏览器中查看。The https:// URL to point at if a user opts to view in a browser.
scopes 枚举数组Array of enum 11 静态选项卡仅支持 personal 作用域,这意味着只能将其设置为个人应用程序的一部分。Static tabs support only the personal scope, which means it can be provisioned only as part of a personal app.

简单的个人选项卡清单示例Simple personal tab manifest example

下面的示例仅展示了 staticTabs 应用程序清单中的数组。The example below shows just the staticTabs array from an app manifest.

...
"staticTabs": [
    {
      "entityId": "idForPage",
      "name": "Display name for tab",
      "contentUrl": "https:// yourURL.com/content ",
      "websiteUrl": "https://yourURL.com/website",
      "scopes": [ "personal" ]
    }
...

通道/组选项卡Channel/group tabs

在阵列中添加通道/组选项卡 configurableTabsChannel/group tabs are added in the configurableTabs array. 您只能在数组中声明一个通道/组选项卡 configurableTabsYou may declare only one channel/group tab in the configurableTabs array.

名称Name 类型Type 最大大小Maximum size 必需Required 说明Description
configurationUrl 字符串String 2048 个字符2048 characters 指向 "配置" 页的 https://URL。The https:// URL to configuration page.
canUpdateConfiguration 布尔值Boolean 一个值,指示是否可在用户创建之后更新该选项卡的配置实例。A value indicating whether an instance of the tab's configuration can be updated by the user after creation. 设置 trueDefault: true
scopes 枚举数组Array of enum 11 可配置的选项卡仅支持 teamgroupchat 范围。Configurable tabs support only the team and groupchat scopes.

简单通道/组选项卡清单示例Simple channel/group tab manifest example

下面的示例仅展示了 configurableTabs 应用程序清单中的数组。The example below shows just the configurableTabs array from an app manifest.

...
"configurableTabs": [
    {
      "configurationUrl": "https://yourURL.com/configure",
      "canUpdateConfiguration": true,
      "scopes": [ "team", "groupchat" ]
    }
...

manifest.json 其捆绑到 zip 文件夹中,并将它与两个必需的图标组合在一起。Once you have completed your manifest.json bundle it in a zip folder along with your two required icons.

将应用程序包直接上载到团队Upload app package directly to a team

  1. 打开 Microsoft 团队客户端。Open the Microsoft Teams client. 如果您使用的是 基于 web 的版本 ,则可以使用浏览器的 开发人员工具检查您的前端代码。If you use the web based version you can inspect your front-end code using your browser's developer tools.
  2. 在左侧的 " YourTeams " 面板中,选择要用于 ... 测试选项卡的团队旁边的菜单,然后选择 " 管理团队"。In the YourTeams panel on the left, select the ... menu next to the team that you're using to test your tab and choose Manage team.
  3. 在主面板中,从选项卡栏中选择 " 应用 ",然后选择 "上载" 位于页面右下角的 自定义应用程序In the main panel select Apps from the tab bar and choose Upload a custom app located in the lower right-hand corner of the page.
  4. 打开您的项目目录,浏览到 " /package " 文件夹,选择 "应用程序包" zip 文件夹,然后选择 " 打开"。Open your project directory, browse to the ./package folder, select the app package zip folder and choose Open. 您的选项卡将上传到团队。Your tab will upload into Teams.

在团队中查看您的选项卡View your tab in Teams

  1. 查看您的个人选项卡:View your personal tab:

    • 在位于团队客户端最左侧的导航栏中,选择 ... 菜单并从列表中选择您的应用程序。In the navbar located at the far-left of the Teams client, select the ... menu and choose your app from the list.
  2. 查看频道/组选项卡:View your channel/group tab:

    • 返回到您的团队,选择要在其中显示选项卡的频道,从选项卡栏中选择 "➕",然后从库中选择您的选项卡。Return to your team, choose the channel where you would like to display the tab, select ➕ from the tab bar, and choose your tab from the gallery.
    • 按照有关添加选项卡的说明操作。请注意,"通道/组" 选项卡有一个自定义配置对话框。选择 " 保存 ",您的选项卡将添加到频道的选项卡栏中。Follow the directions for adding a tab. Note that there's a custom configuration dialog for your channel/group tab. Select Save and your tab will be added to the channel's tab bar.

了解详细信息Learn more