向 Teams 应用添加选项卡功能

项目
12/17/2024

选项卡是嵌入Microsoft Teams 中的网页。选项卡充当简单的 HTML iframe 标记，指向应用清单中声明的域 (以前称为 Teams 应用清单) 。可以为单个用户添加选项卡作为功能添加到团队、群组聊天或个人应用中的频道中的 Teams 应用。可在应用中包含自定义选项卡，以便在 Teams 中嵌入自己的 Web 内容，或将 Teams 特定的功能添加到 Web 内容。有关详细信息，请参阅 Teams 的生成选项卡。

在开始之前，建议创建并浏览选项卡应用。有关详细信息，请参阅使用 Teams 工具包创建选项卡应用。

先决条件

确保在 Teams 应用中配置选项卡功能时满足以下先决条件：

Teams 应用及其应用清单文件
Microsoft 365 帐户来测试应用
Microsoft Azure 帐户

Teams 应用中的“配置”选项卡

以下步骤可帮助你在 Teams 应用中配置选项卡功能：

更新应用清单
设置本地调试环境
将应用预配到 Azure

提示

如果开发服务器端选项卡应用，则无需更新文件夹结构、调试配置文件或 bicep 基础结构。将新路由添加到机器人服务中的选项卡，并在 Teams 工具包中更新应用清单。有关详细信息，请参阅示例应用。

更新应用清单

若要在个人聊天、群组聊天或频道中配置选项卡，请使用 manifest.json 以下代码更新文件：

  "staticTabs": [
      {
          "entityId": "index",
          "name": "Personal Tab",
          "contentUrl": "${{TAB_ENDPOINT}}/index.html#/tab",
          "websiteUrl": "${{TAB_ENDPOINT}}/index.html#/tab",
          "scopes": [
              "personal",
              "groupChat",
              "team"
          ]
      }
  ],

使用选项卡的域更新的值 validDomains 。
```
"validDomains": [
    "${{TAB_DOMAIN}}"
],
```
注意

TAB_ENDPOINT 和 TAB_DOMAIN 是 Teams 工具包的内置变量。在运行时，会根据当前环境将它们替换为真正的终结点。

设置本地调试环境

在 Visual Studio Code 中将选项卡应用代码引入项目中。如果没有，可以使用 Teams 工具包创建新的选项卡应用，并将源代码复制到当前项目中。默认情况下，选项卡应用的文件夹结构如下所示：

    |-- appPackage/
    |-- env/
    |-- infra/
    |-- tab/            <!--tab app source code-->
    |   |-- src/
    |   |   |-- app.ts
    |   |-- package.json
    |-- index.ts        <!--your current source code-->
    |-- package.json
    |-- teamsapp.yml

按如下所示重新组织文件夹结构：

    |-- appPackage/
    |-- infra/
    |-- tab/           <!--tab app source code-->
    |   |-- src/
    |   |   |-- app.ts
    |   |-- package.json
    |-- bot/            <!--move your current source code to a new sub folder-->
    |   |-- index.ts
    |   |-- package.json
    |-- teamsapp.yml

更新和 teamsapp.local.yml 文件中teamsapp.yml的以下代码，使其与文件夹结构保持一致：

    deploy:
      # Run npm command
      - uses: cli/runNpmCommand
        with:
          args: install --no-audit
          workingDirectory: ./bot

若要配置选项卡项目的调试配置文件，请将以下代码添加到 tasks.json 文件中：

{
    "label": "Start application",
    "dependsOn": [
        "Start bot",
        "Start frontend"
    ]
},
{
    "label": "Start bot",
    "type": "shell",
    "command": "npm run dev:teamsfx",
    "isBackground": true,
    "options": {
        "cwd": "${workspaceFolder}/bot"
    },
    "problemMatcher": {
        "pattern": [
            {
                "regexp": "^.*$",
                "file": 0,
                "location": 1,
                "message": 2
            }
        ],
        "background": {
            "activeOnStart": true,
            "beginsPattern": "[nodemon] starting",
            "endsPattern": "restify listening to|Bot/ME service listening at|[nodemon] app crashed"
        }
    }
},
{
    "label": "Start frontend",
    "type": "shell",
    "command": "npm run dev:teamsfx",
    "isBackground": true,
    "options": {
        "cwd": "${workspaceFolder}/tab"
    },
    "problemMatcher": {
        "pattern": {
            "regexp": "^.*$",
            "file": 0,
            "location": 1,
            "message": 2
        },
        "background": {
            "activeOnStart": true,
            "beginsPattern": ".*",
            "endsPattern": "Compiled|Failed|compiled|failed"
        }
    }
}

有关如何配置调试配置文件的详细信息，请参阅示例应用。

若要使选项卡项目能够使用 Teams 工具包，请将以下操作添加到 teamsapp.local.yml 文件：

provision:
  - uses: script # Set TAB_DOMAIN for local launch
    name: Set TAB_DOMAIN for local launch
    with:
      run: echo "::set-output TAB_DOMAIN=localhost:53000"
  - uses: script # Set TAB_ENDPOINT for local launch
    name: Set TAB_ENDPOINT for local launch
    with:
      run: echo "::set-output TAB_ENDPOINT=https://localhost:53000"
deploy:
  - uses: devTool/install # Install development tool(s)
    with:
      devCert:
        trust: true
    writeToEnvironmentFile: # Write the information of installed development tool(s) into environment file for the specified environment variable(s).
      sslCertFile: SSL_CRT_FILE
      sslKeyFile: SSL_KEY_FILE
  - uses: cli/runNpmCommand # Run npm command
    with:
      args: install --no-audit
      workingDirectory: ./tab
  - uses: file/createOrUpdateEnvironmentFile # Generate runtime environment variables for tab
    with:
      target: ./tab/.localConfigs
      envs:
        BROWSER: none
        HTTPS: true
        PORT: 53000
        SSL_CRT_FILE: ${{SSL_CRT_FILE}}
        SSL_KEY_FILE: ${{SSL_KEY_FILE}}

选择 F5 键在本地调试应用。

将应用预配到 Azure

若要创建服务器端选项卡应用，无需更新 bicep 文件或 Azure 基础结构。可以在与机器人相同的Azure 应用服务中托管选项卡应用。

若要为选项卡应用预配 Azure Static Web 应用，请将以下代码添加到 azure.bicep 文件：

@maxLength(20)
@minLength(4)
param resourceBaseName string
param storageSku string
param staticWebAppName string = resourceBaseName

// Azure Static Web Apps that hosts your static web site
resource swa 'Microsoft.Web/staticSites@2022-09-01' = {
  name: staticWebAppName
  // SWA do not need location setting
  location: 'centralus'
  sku: {
    name: staticWebAppSku
    tier: staticWebAppSku
  }
  properties: {}
}
var siteDomain = swa.properties.defaultHostname

output AZURE_STATIC_WEB_APPS_RESOURCE_ID string = swa.id
output TAB_DOMAIN string = siteDomain
output TAB_ENDPOINT string = 'https://${siteDomain}'

若要确保正确设置必要的参数，请更新文件， azure.parameters.json 如下所示：

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "resourceBaseName": {
      "value": "helloworld${{RESOURCE_SUFFIX}}"
    },
    "storageSku": {
      "value": "Free"
    },
  }
}

若要在 Azure Static Web Apps 中托管选项卡应用，请在文件中teamsapp.yml定义 azureStaticWebApps/getDeploymentToken 操作。该操作依赖于 AZURE_STATIC_WEB_APPS_RESOURCE_IDbicep 部署的输出。在操作后 arm/deploy 添加以下代码：

 provision:
   ...
   - uses: arm/deploy
     ...
   # Add this action
   - uses: azureStaticWebApps/getDeploymentToken
     with:
       resourceId: ${{AZURE_STATIC_WEB_APPS_RESOURCE_ID}}
       writeToEnvironmentFile:
         deploymentToken: SECRET_TAB_SWA_DEPLOYMENT_TOKEN
   ...

转到 “查看>命令面板...” 或选择 Ctrl+Shift+P。
输入 Teams: Provision 命令以将 bicep 应用到 Azure。

若要自动生成和部署选项卡应用，请将以下 build 和 deploy 操作添加到文件 teamsapp.yml ：

  - uses: cli/runNpmCommand # Run npm command
    with:
      args: install
      workingDirectory: ./tab
  - uses: cli/runNpmCommand # Run npm command
    with:
      args: run build
      workingDirectory: ./tab
  # Deploy bits to Azure Storage Static Website
 - uses: cli/runNpxCommand
     name: deploy to Azure Static Web Apps
     with:
       args: '@azure/static-web-apps-cli deploy ./build -d ${{SECRET_TAB_SWA_DEPLOYMENT_TOKEN}} --env production'

转到 “查看>命令面板...” 或选择 Ctrl+Shift+P。
输入 Teams: Deploy 以将选项卡应用代码部署到 Azure。
在 “运行和调试”下，选择“ 启动远程 (Edge) ”或 “启动远程 (Chrome) ”。
选择 F5 键以调试和预览 Teams 应用。

后续步骤

添加功能的操作指南

通过