Aplicación de pestaña Panel de compilación: Tutorial - Teams

Esta guía paso a paso le ayuda a crear una pestaña de panel, agregar un nuevo widget al panel e implementar Graph API. Verá la siguiente salida:

Captura de pantalla que muestra la salida final del panel.

Requisitos previos

23 minutos restantes

Instalar	Para usar
Visual Studio Code	Entornos de compilación de JavaScript, TypeScript o SharePoint Framework (SPFx). Use la versión 1.55 o posterior.
Kit de herramientas de Teams o CLI de TeamsFx	Extensión de Microsoft Visual Studio Code que crea un scaffolding de proyecto para la aplicación. Use Teams Toolkit v5.
Programa de desarrolladores de Microsoft 365	Cuenta de Teams con los permisos adecuados para instalar una aplicación.
Node.js	Entorno de tiempo de ejecución de JavaScript de back-end. Para obtener más información, vea Node.js tabla de compatibilidad de versiones para el tipo de proyecto.
Microsoft Teams	Microsoft Teams para colaborar con todos los usuarios con los que trabaja a través de aplicaciones para chat, reuniones y llamadas a todos en un solo lugar.
Microsoft Edge (recomendado) o Google Chrome	Un explorador con herramientas de desarrollo.

Creación de un nuevo panel

22 minutos restantes

Teams Toolkit admite la creación de un panel y scaffolding.

Para crear un nuevo panel:

Seleccione el icono Kit de herramientas de Teams en la barra de actividad de Visual Studio Code.
Seleccione Crear una nueva aplicación.
Seleccione Pestaña para crear un nuevo proyecto de pestaña.
Seleccione Panel.
Seleccione TypeScript como lenguaje de programación.
Seleccione Carpeta predeterminada para almacenar la carpeta raíz del proyecto en la ubicación predeterminada.
Escriba un nombre adecuado para la aplicación y seleccione Entrar.

La aplicación de pestaña Teams se crea en pocos segundos.

Una vez creada la aplicación, Teams Toolkit muestra el mensaje siguiente:
Seleccione el icono kit de herramientas de Teams en la barra lateral.
Seleccione Iniciar sesión en Microsoft 365.
Seleccione Iniciar sesión.
Seleccione F5 para ejecutar la aplicación en modo de depuración.
Seleccione Agregar.

El panel de la aplicación de tabulación se crea correctamente en Teams.

Teams también admite diferentes temas, incluidos los temas oscuros y de contraste alto.
- Tema oscuro
- Tema de contraste alto
En la imagen siguiente se muestra el uso del tema Oscuro en el cliente de escritorio de Teams:

En la imagen siguiente se muestra el uso del tema contraste alto en el cliente de escritorio de Teams:

En la CLI de TeamsFx,

Si prefiere un modo interactivo, ejecute teamsfx new el comando y, a continuación, use el teclado para pasar por el mismo flujo que en Visual Studio Code.
Si prefiere el modo no interactivo, escriba todos los parámetros necesarios en un comando:

teamsfx new--interactive false--capabilities "dashboard-tab"--programming-language "TypeScript"--folder "./"--app-name dashboard-cli-001

Realice un recorrido por el código fuente de la aplicación.

22 minutos restantes

Después de crear el proyecto, puede ver las carpetas y los archivos del proyecto en el Explorador en Visual Studio Code. La implementación principal del panel se encuentra en la carpeta tabs.

Folder	Contenido
`.vscode`	Archivos de Visual Studio Code para la depuración.
`appPackage`	Plantillas para el manifiesto de aplicación de Teams.
`env`	Archivos de entorno.
`infra`	Plantillas para aprovisionar recursos de Azure.
`src`	Código fuente de la aplicación teams del panel.

Los siguientes archivos proporcionan la lógica de negocios para la pestaña del panel. Puede actualizar los archivos para que se ajusten a los requisitos de la lógica de negocios. La implementación predeterminada proporciona un punto de partida para ayudarle a empezar.

Archivo	Contenido
`src/models/chartModel.ts`	Modelo de datos para el widget de gráfico.
`src/models/listModel.ts`	Modelo de datos para el widget de lista.
`src/services/chartService.ts`	Una implementación de recuperación de datos para el widget de gráfico.
`src/services/listService.ts`	Una implementación de recuperación de datos para el widget de lista.
`src/dashboards/SampleDashboard.tsx`	Una implementación de diseño de panel de ejemplo.
`src/styles/ChartWidget.css`	Archivo de estilo de widget de gráfico.
`src/styles/ListWidget.css`	Archivo de estilo de widget de lista.
`src/widgets/ChartWidget.tsx`	Implementación de widget que puede mostrar un gráfico.
`src/widgets/ListWidget.tsx`	Implementación de widget que puede mostrar una lista.
`src/App.css`	El estilo de la ruta de la aplicación.
`src/App.tsx`	Ruta de aplicación.

Los siguientes archivos son archivos relacionados con el proyecto. Por lo general, no es necesario personalizar estos archivos.

Archivo	Contenido
`src/index.css`	Estilo del punto de entrada de la aplicación.
`src/index.tsx`	Punto de entrada de la aplicación.
`src/internal/addNewScopes.ts`	Se agrega la implementación de nuevos ámbitos.
`src/internal/context.ts`	Contexto de TeamsFx.
`src/internal/login.ts`	Implementación del inicio de sesión.
`src/internal/singletonContext.ts`	Implementación de la instancia de TeamsUserCredential singleton.

Adición de un widget al panel

20 minutos restantes

Para agregar un nuevo widget al panel, siga estos pasos:

Definición de un modelo de datos
Creación de un servicio de recuperación de datos
Creación de un archivo de widget
Agregar el widget al panel

Definición de un modelo de datos

En Visual Studio Code, vaya a EXPLORER srcmodels (Modelosde src> de EXPLORER>).
Cree un archivo sampleModel.ts .

Agregue el código siguiente en el archivo sampleModel.ts :

  export interface SampleModel {
  content: string;
  }

Captura de pantalla que muestra la creación del archivo sampleModel en la carpeta models de Visual Studio Code.

Creación de un servicio de recuperación de datos

Nota:

Puede implementar un servicio para recuperar datos del servicio back-end o de Microsoft Graph API.

En Visual Studio Code, vaya a Servicios>explorer src>.
Cree un archivo sampleService.ts .

Agregue el código siguiente en el archivo sampleService.ts :

import { SampleModel } from "../models/sampleModel";

export const getSampleData = (): SampleModel => {
  return { content: "Hello world!" };
  };

Captura de pantalla que muestra la creación de sampleService.ts archivo en la carpeta de servicio de Visual Studio Code.

En Visual Studio Code, vaya a EXPLORER>src>widgets (Explorador de widgets).
Cree un archivo SampleWidget.tsx .

Agregue el código siguiente en el archivo SampleWidget.tsx :

import { Button, Text } from "@fluentui/react-components";
import { BaseWidget } from "@microsoft/teamsfx-react";
import { SampleModel } from "../models/sampleModel";
import { getSampleData } from "../services/sampleService";
interface SampleWidgetState 
{
  data?: SampleModel;
}
export class SampleWidget extends BaseWidget<any, SampleWidgetState>
{
  override async getData(): Promise<SampleWidgetState>
  {
    return { data: getSampleData() };
  }
  override header(): JSX.Element | undefined
  {
    return <Text>Sample Widget</Text>;
  }
  override body(): JSX.Element | undefined
  {
    return <div>{this.state.data?.content}</div>;
  }
  override footer(): JSX.Element | undefined
  {
    return <Button>View Details</Button>;
  }
}

Para agregar un widget al panel, siga estos pasos:

En Visual Studio Code, vaya a Panelessrc>> del Explorador >SampleDashboard.tsx.

Agregue el widget al panel actualizando el override layout() método :

override layout(): JSX.Element | undefined {
  return (<>
      <ListWidget />
      <ChartWidget />
      <SampleWidget />
    </>
  );
}

Captura de pantalla que muestra el archivo sampleDashboard existente en Visual Studio Code.

Opcional: consulte el código siguiente para agregar el widget en una columna:

.one-column {
  display: grid;
  gap: 20 px;
  grid-template-rows: 1fr 1fr;
}

override layout(): JSX.Element | undefined {
  return (<>
      <ListWidget />
      <div className="one-column">
        <ChartWidget />
        <SampleWidget />
      </div>
   </>
  );
}

Después de agregar todos los detalles pertinentes para crear un widget, guarde los archivos correspondientes.

Puede ver el diseño cambiado y el widget de calendario en el panel.

Incorporación de sso y llamada a Graph API

15 minutos restantes

Ha aprendido a crear una pestaña de panel y a agregar un nuevo widget al panel. Vamos a agregar el inicio de sesión único (SSO) y la llamada a graph API a la pestaña del panel.

Agregar inicio de sesión único

Para agregar sso, siga estos pasos:

1. Crear manifiesto de aplicación De Microsoft Entra.

Para crear un manifiesto de aplicación de Microsoft Entra, siga estos pasos:

En Visual Studio Code, vaya a EXPLORADOR.
Cree un archivo aad.manifest.json .

Agregue el código siguiente en aad.manifest.json archivo:

{
  "id": "${{AAD_APP_OBJECT_ID}}",
  "appId": "${{AAD_APP_CLIENT_ID}}",
  "name": "dashboardDemo",
  "accessTokenAcceptedVersion": 2,
  "signInAudience": "AzureADMyOrg",
  "optionalClaims": {
      "idToken": [],
      "accessToken": [
          {
            "name": "idtyp",
            "source": null,
            "essential": false,
            "additionalProperties": []
          }
      ],
      "saml2Token": []
  },
  "requiredResourceAccess": [
      {
        "resourceAppId": "Microsoft Graph",
        "resourceAccess": [
            {
              "id": "User.Read", 
              "type": "Scope"
            }
        ]
      }
  ],
   "oauth2Permissions": [
      {
        "adminConsentDescription": "Allows Teams to call the app's web APIs as the current user.",
        "adminConsentDisplayName": "Teams can access app's web APIs",
        "id": "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}",
        "isEnabled": true,
        "type": "User",
        "userConsentDescription": "Enable Teams to call this app's web APIs with the same rights that you have",
        "userConsentDisplayName": "Teams can access app's web APIs and make requests on your behalf",
        "value": "access_as_user"
      }
  ],
  "preAuthorizedApplications": [
      {
          "appId": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
          "permissionIds": 
          ["${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"]
      },
      {
          "appId": "5e3ce6c0-2b1f-4285-8d4b-75ee78787346",
          "permissionIds": 
          ["${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"]
      },
      {
          "appId": "d3590ed6-52b3-4102-aeff-aad2292ab01c",
          "permissionIds": 
          ["${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"]
      },
      {
          "appId": "00000002-0000-0ff1-ce00-000000000000",
          "permissionIds": 
          ["${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"]
      },
      {
          "appId": "bc59ab01-8403-45c6-8796-ac3ef710b3e3",
          "permissionIds": 
          ["${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"]
      },
      {
          "appId": "0ec893e0-5785-4de6-99da-4ed124e5296c",
          "permissionIds": 
          ["${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"]
      },
      {
          "appId": "4765445b-32c6-49b0-83e6-1d93765276ca",
          "permissionIds": 
          ["${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"]
      },
      {
          "appId": "4345a7b9-9a63-4910-a426-35363201d503",
          "permissionIds": 
          ["${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"]
      }
  ],
  "identifierUris": 
  ["api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}"],
  "replyUrlsWithType": [
    {
      "url": "${{TAB_ENDPOINT}}/auth-end.html",
      "type": "Web"
    },
    {
      "url": "${{TAB_ENDPOINT}}/auth-end.html?clientId=${{AAD_APP_CLIENT_ID}}",
      "type": "Spa"
    },
    {
      "url": "${{TAB_ENDPOINT}}/blank-auth-end.html",
      "type": "Spa"
    }
  ]
}

Captura de pantalla que muestra la adición de código de manifiesto de la aplicación Microsoft Entra.

2. Actualizar manifiesto de aplicación de Teams.

Para actualizar el manifiesto de aplicación de Teams, siga estos pasos:

En Visual Studio Code, vaya aAPLICACIÓN EXPLORERPaquete>>manifest.json.

Agregue el código siguiente después de la propiedad domains válida en el archivo manifest.json :

  "webApplicationInfo": {
  "id": "${{AAD_APP_CLIENT_ID}}",
  "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}"
  }

Captura de pantalla que muestra la adición de información de la aplicación web en el manifiesto.

3. Actualice los archivos de configuración del kit de herramientas de Teams.

Para actualizar el código de configuración del kit de herramientas de Teams en archivos de teamsapp.yml y teamsapp.local.yml , siga estos pasos:

teamsapp.yml
teamsapp.local.yml

Agregue el código en provision.

  - uses: aadApp/create
    with:
        name: "YOUR_AAD_APP_NAME"
        generateClientSecret: true
        signInAudience: "AzureADMyOrg"
    writeToEnvironmentFile:
        clientId: AAD_APP_CLIENT_ID
        clientSecret: SECRET_AAD_APP_CLIENT_SECRET
        objectId: AAD_APP_OBJECT_ID
        tenantId: AAD_APP_TENANT_ID
        authority: AAD_APP_OAUTH_AUTHORITY
        authorityHost: AAD_APP_OAUTH_AUTHORITY_HOST

  - uses: aadApp/update
    with:
      manifestPath: "./aad.manifest.json"
      outputFilePath: ./build/aad.manifest.${{TEAMSFX_ENV}}.json

Captura de pantalla que muestra la adición de código aadApp/create y aadApp/update.

Agregue el código siguiente, en la acción cli/runNpmCommand y el build app nombre:

  env:
  REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
  REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html

Captura de pantalla que muestra la información para reaccionar al código de la CLI.

Agregue el código en provision.


  - uses: aadApp/create
    with:
        name: "YOUR_AAD_APP_NAME"
        generateClientSecret: true
        signInAudience: "AzureADMyOrg"
    writeToEnvironmentFile:
        clientId: AAD_APP_CLIENT_ID
        clientSecret: SECRET_AAD_APP_CLIENT_SECRET
        objectId: AAD_APP_OBJECT_ID
        tenantId: AAD_APP_TENANT_ID
        authority: AAD_APP_OAUTH_AUTHORITY
        authorityHost: AAD_APP_OAUTH_AUTHORITY_HOST

  - uses: aadApp/update
    with:
      manifestPath: "./aad.manifest.json"
      outputFilePath: ./build/aad.manifest.${{TEAMSFX_ENV}}.json

Captura de pantalla que muestra la adición de código aadApp/create y aadApp/update.

En la acción file/createOrUpdateEnvironmentFile**, agregue el código siguiente:

  REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}}
  REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html

Captura de pantalla que muestra la información para reaccionar a los códigos.

4. Actualizar código fuente.

Cree archivosauth-start.html y auth-end.html en la carpeta pública .

Agregue el código en los archivosauth-start.html y auth-end.html .

auth-start
auth-end

Agregue el código siguiente en auth-start.html:

  <!--The Teams authentication flow process uses this file to assist with retrieval of the access token.-->
  <!--If you're not familiar with this process, don't alter or remove this file from your project.-->
  <html>
    <head>
      <title>Sign-in Start Page</title>
      <meta charset="utf-8" />
    </head>

    <body>
    <script src="https://res.cdn.office.net/teams-js/2.7.1/js/MicrosoftTeams.min.js" integrity="sha384-4Gy2G+qxzDVdrdemcVqKVQvaSK1Ghg3x6xcsaMLPc/pw7KPtiogHGM97LTWF2PWg" crossorigin="anonymous"></script>
      <script
        type="text/javascript"
        src="https://alcdn.msauth.net/browser/2.21.0/js/msal-browser.min.js"
        integrity="sha384-s/NxjjAgw1QgpDhOlVjTceLl4axrp5nqpUbCPOEQy1PqbFit9On6uw2XmEF1eq0s"
        crossorigin="anonymous">
      </script>
      <script type="text/javascript">
        microsoftTeams.app.initialize().then(() => {
          microsoftTeams.app.getContext().then(async (context) => {
            // Generate random state string and store it, so we can verify it in the callback
            var currentURL = new URL(window.location);
            var clientId = currentURL.searchParams.get("clientId");
            var scope = currentURL.searchParams.get("scope");
            var loginHint = currentURL.searchParams.get("loginHint");

            const msalConfig = {
              auth: {
                clientId: clientId,
                authority: `https://login.microsoftonline.com/${context.user.tenant.id}`,
                navigateToLoginRequestUrl: false
              },
              cache: {
                cacheLocation: "sessionStorage",
              },
            }
            const msalInstance = new msal.PublicClientApplication(msalConfig);
            const scopesArray = scope.split(" ");
            const scopesRequest = {
              scopes: scopesArray,
              redirectUri: window.location.origin + `/auth-end.html?clientId=${clientId}`,
              loginHint: loginHint
            };
            await msalInstance.loginRedirect(scopesRequest);
          });
        });
        </script>
    </body>
  </html>

Agregue el código siguiente en auth-end.html:

  <!--The Teams authentication flow process uses this file to assist with retrieval of the access token.-->
  <!--If you're not familiar with this process, don't alter or remove this file from your project.-->
  <html>
    <head>
      <title>Sign-in End Page</title>
      <meta charset="utf-8" />
    </head>

    <body>
    <script src="https://res.cdn.office.net/teams-js/2.7.1/js/MicrosoftTeams.min.js" integrity="sha384-4Gy2G+qxzDVdrdemcVqKVQvaSK1Ghg3x6xcsaMLPc/pw7KPtiogHGM97LTWF2PWg" crossorigin="anonymous"></script>
      <script
        type="text/javascript"
        src="https://alcdn.msauth.net/browser/2.21.0/js/msal-browser.min.js"
        integrity="sha384-s/NxjjAgw1QgpDhOlVjTceLl4axrp5nqpUbCPOEQy1PqbFit9On6uw2XmEF1eq0s"
        crossorigin="anonymous">
      </script>
      <script type="text/javascript">
        var currentURL = new URL(window.location);
        var clientId = currentURL.searchParams.get("clientId");

        microsoftTeams.app.initialize().then(() => {
          microsoftTeams.app.getContext().then(async (context) => {
            const msalConfig = {
              auth: {
                clientId: clientId,
                authority: `https://login.microsoftonline.com/${context.user.tenant.id}`,
                navigateToLoginRequestUrl: false
              },
              cache: {
                cacheLocation: "sessionStorage",
              },
            }
            const msalInstance = new window.msal.PublicClientApplication(msalConfig);
            msalInstance.handleRedirectPromise()
              .then((tokenResponse) => 
              {
                if (tokenResponse !== null) 
                {
                  microsoftTeams.authentication.notifySuccess(JSON.stringify({
                    sessionStorage: sessionStorage
                  }));
                } else {
                  microsoftTeams.authentication.notifyFailure("Get empty response.");
                }
              }).catch((error) => 
              {
                microsoftTeams.authentication.notifyFailure(JSON.stringify(error));
              });
          });
        });
      </script>
    </body>
  </html>

Agregó los archivos de SSO al proyecto y debe llamar a graph API a continuación.

Agregar llamada a Graph API

Para agregar Graph API, siga estos pasos:

El SDK de TeamsFx implementa la llamada a graph API.

En Visual Studio Code, vaya a explorer>src>services>listService.ts.

Actualice el código siguiente en el listService.ts:

/**
  * Retrieve sample data
  * @returns data for list widget
  */
import {TeamsUserCredentialContext} from "../internal/singletonContext";
import {
  createMicrosoftGraphClientWithCredential,
  TeamsUserCredential,
  } from "@microsoft/teamsfx";
  import { ListModel } from "../models/listModel";
  import { loginAction } from "../internal/login";
export const getListData = async (): Promise<ListModel[]> => {
  await loginAction(["User.Read"]);
  let credential = TeamsUserCredentialContext.getInstance().getCredential();
  const graphClient = createMicrosoftGraphClientWithCredential(credential, 
  ["User.Read",
  ]);
  const me = await graphClient.api("/me").get();
  return [
    {
      id: me.id,
      title: me.displayName,
      content: me.mail,
    },
  ];
  // {
  //   id: "id1",
  //   title: "Sample title",
  //   content: "Sample description",
  // },
  // {
  //   id: "id2",
  //   title: "Sample title",
  //   content: "Sample description",
  // },
  // {
  //   id: "id3",
  //   title: "Sample title",
  //   content: "Sample description",
  // },
}

Vaya a EXPLORER>src>widgets>ListWidget.tsx.

Actualice para agregar el export default class ListWidget() widget de perfil de usuario.

 export default class ListWidget extends BaseWidget<any, IListWidgetState> {
   async getData(): Promise<IListWidgetState> {
     return { data: await getListData() };

SSO y Graph API muestran el perfil de usuario que ha iniciado sesión en el widget de lista.

Desafío completo

10 minutos restantes

¿Se te ocurrió algo como esto?

Captura de pantalla que muestra la salida final del panel.

Enhorabuena.

100 % completado.

Ha completado el tutorial.

Compartir a través de

Creación de un panel en Teams