Aplicação de Separador Criar Dashboard - Tutorial - Teams

Este guia passo a passo ajuda-o a criar um separador de dashboard, adicionar um novo widget ao dashboard e implementar a Graph API. Verá o seguinte resultado:

Captura de ecrã a mostrar a saída final do dashboard.

Pré-requisitos

23 minutos restantes

Instalar	Para utilizar
Visual Studio Code	Ambientes de compilação JavaScript, TypeScript ou Estrutura do SharePoint (SPFx). Utilize a versão 1.55 ou posterior.
Teams Toolkit ou TeamsFx CLI	Extensão do Microsoft Visual Studio Code que cria um projeto estruturado para a sua aplicação. Utilize o Teams Toolkit v5.
Programa para desenvolvedores do Microsoft 365	Conta do Teams com as permissões adequadas para instalar uma aplicação.
Node.js	Ambiente de runtime do JavaScript de back-end. Para obter mais informações, veja Node.js tabela de compatibilidade de versões para o tipo de projeto.
Microsoft Teams	O Microsoft Teams para colaborar com todas as pessoas com quem trabalha através de aplicações para conversas, reuniões e chamadas num único local.
Microsoft Edge (recomendado) ou Google Chrome	Um navegador com ferramentas de desenvolvedor.

Criar um novo dashboard

22 minutos restantes

O Teams Toolkit suporta a criação de um dashboard e estrutura.

Para criar um novo dashboard:

Selecione o ícone Do Teams Toolkit na Barra de Atividade do Visual Studio Code.
Selecione Criar uma Nova Aplicação.
Selecione Tabulação para criar um novo projeto de separador.
Selecione Dashboard.
Selecione TypeScript como a linguagem de programação.
Selecione Pasta predefinida para armazenar a pasta raiz do projeto na localização predefinida.
Introduza um nome adequado para a sua aplicação e selecione Enter.

A aplicação de separador Teams é criada em poucos segundos.

Depois de criar a sua aplicação, o Toolkit do Teams apresenta a seguinte mensagem:
Selecione o ícone Do Teams Toolkit na barra lateral.
Selecione Iniciar sessão no Microsoft 365.
Selecione Entrar.
Selecione o F5 para executar a aplicação no modo de depuração.
Selecione Adicionar.

O dashboard da aplicação de tabulação foi criado com êxito no Teams.

O Teams também suporta temas diferentes, incluindo temas escuros e de alto contraste.
- Tema escuro
- Tema de alto contraste
A imagem seguinte mostra a utilização do tema Escuro no cliente de ambiente de trabalho do Teams:

A imagem seguinte mostra a utilização do tema Alto contraste no cliente de ambiente de trabalho do Teams:

Na CLI do TeamsFx,

Se preferir um modo interativo, execute teamsfx new o comando e, em seguida, utilize o teclado para percorrer o mesmo fluxo que no Visual Studio Code.
Se preferir um modo não interativo, introduza todos os parâmetros necessários num único comando:

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

Ver uma apresentação do código fonte da aplicação

22 minutos restantes

Depois de criar o projeto, pode ver as pastas e os ficheiros do projeto no Explorador no Visual Studio Code. A implementação principal do dashboard encontra-se na pasta de separadores.

Pasta	Conteúdos
`.vscode`	Ficheiros do Visual Studio Code para depuração.
`appPackage`	Modelos para o manifesto de aplicação do Teams.
`env`	Ficheiros de ambiente.
`infra`	Modelos para aprovisionar recursos do Azure.
`src`	O código fonte da aplicação teams do dashboard.

Os seguintes ficheiros fornecem a lógica de negócio para o separador dashboard. Pode atualizar os ficheiros de acordo com os seus requisitos de lógica de negócio. A implementação predefinida fornece um ponto de partida para ajudá-lo a começar.

Arquivo	Conteúdos
`src/models/chartModel.ts`	Modelo de dados para o widget de gráfico.
`src/models/listModel.ts`	Modelo de dados para o widget de lista.
`src/services/chartService.ts`	Uma implementação de obtenção de dados para o widget de gráfico.
`src/services/listService.ts`	Uma implementação de obtenção de dados para o widget de lista.
`src/dashboards/SampleDashboard.tsx`	Uma implementação de esquema de dashboard de exemplo.
`src/styles/ChartWidget.css`	O ficheiro de estilo de widget de gráfico.
`src/styles/ListWidget.css`	O ficheiro de estilo de widget de lista.
`src/widgets/ChartWidget.tsx`	Uma implementação de widget que pode apresentar um gráfico.
`src/widgets/ListWidget.tsx`	Uma implementação de widget que pode apresentar uma lista.
`src/App.css`	O estilo da rota da aplicação.
`src/App.tsx`	Rota da aplicação.

Os seguintes ficheiros são ficheiros relacionados com o projeto. Geralmente, não precisa de personalizar estes ficheiros.

Arquivo	Conteúdos
`src/index.css`	O estilo do ponto de entrada da aplicação.
`src/index.tsx`	Ponto de entrada da aplicação.
`src/internal/addNewScopes.ts`	A implementação de novos âmbitos adiciona.
`src/internal/context.ts`	Contexto do TeamsFx.
`src/internal/login.ts`	Implementação do início de sessão.
`src/internal/singletonContext.ts`	Implementação do singleton da instância teamsUserCredential.

Adicionar um widget ao dashboard

20 minutos restantes

Para adicionar um novo widget ao dashboard, siga estes passos:

Definir um modelo de dados
Criar um serviço de obtenção de dados
Criar um ficheiro widget
Adicionar o widget ao dashboard

Definir um modelo de dados

No Visual Studio Code, aceda a EXPLORER src models (Explorador> demodelossrc>).
Crie um ficheiro sampleModel.ts .

Adicione o seguinte código no ficheiro sampleModel.ts :

  export interface SampleModel {
  content: string;
  }

Captura de ecrã a mostrar a criação do ficheiro sampleModel na pasta models no Visual Studio Code.

Criar um serviço de obtenção de dados

Observação

Pode implementar um serviço para obter dados do serviço de back-end ou da Microsoft Graph API.

No Visual Studio Code, aceda a EXPLORER>src>services.
Crie um ficheiro sampleService.ts .

Adicione o seguinte código no ficheiro sampleService.ts :

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

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

Captura de ecrã a mostrar a criação de sampleService.ts ficheiro na pasta do serviço no Visual Studio Code.

No Visual Studio Code, aceda a EXPLORER>src>widgets.
Crie um ficheiro SampleWidget.tsx .

Adicione o seguinte código no ficheiro 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 adicionar um widget ao dashboard, siga estes passos:

No Visual Studio Code, aceda a Explorer>src>dashboards>SampleDashboard.tsx.

Adicione o widget ao dashboard ao atualizar o override layout() método :

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

Captura de ecrã a mostrar o ficheiro sampleDashboard existente no Visual Studio Code.

Opcional: veja o seguinte código para adicionar o widget numa coluna:

.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>
   </>
  );
}

Depois de adicionar todos os detalhes relevantes para criar um widget, guarde os respetivos ficheiros.

Pode ver o esquema alterado e o widget do calendário no dashboard.

Adicionar chamada SSO e Graph API

15 minutos restantes

Aprendeu a criar um separador do dashboard e a adicionar um novo widget ao dashboard. Vamos adicionar o Início de Sessão Único (SSO) e a chamada à Graph API ao separador do dashboard.

Adicionar SSO

Para adicionar o SSO, siga estes passos:

1. Crie o manifesto da aplicação Microsoft Entra.

Para criar um manifesto da aplicação Microsoft Entra, siga estes passos:

No Visual Studio Code, aceda a EXPLORADOR.
Crie um ficheiro de aad.manifest.json .

Adicione o seguinte código no ficheiro aad.manifest.json :

{
  "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 ecrã a mostrar a adição do código de manifesto da aplicação Microsoft Entra.

2. Atualize o manifesto da aplicação Teams.

Para atualizar o manifesto da aplicação Teams, siga estes passos:

No Visual Studio Code, aceda a EXPLORER>appPackage>manifest.json.

Adicione o seguinte código após a propriedade domínios válidos no ficheiro de manifest.json :

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

Captura de ecrã a mostrar a adição de informações da aplicação Web no manifesto.

3. Atualize os ficheiros de configuração do Teams Toolkit.

Para atualizar o código de configuração do Teams Toolkit em ficheiros teamsapp.yml e teamsapp.local.yml , siga os passos:

teamsapp.yml
teamsapp.local.yml

Adicione o código em 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 ecrã a mostrar a adição de aadApp/create e aadApp/update code.

Adicione o seguinte código, sob a ação cli/runNpmCommand e o build app nome:

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

Captura de ecrã a mostrar as informações para reagir ao código da CLI.

Adicione o código em 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 ecrã a mostrar a adição de aadApp/create e aadApp/update code.

Na ação file/createOrUpdateEnvironmentFile**, adicione o seguinte código:

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

Captura de ecrã a mostrar as informações para reagir aos códigos.

4. Atualize o código fonte.

Crie auth-start.html e auth-end.html ficheiros na pasta pública .

Adicione o código nos ficheiros auth-start.html e auth-end.html .

auth-start
auth-end

Adicione o seguinte código no 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>

Adicione o seguinte código no 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>

Adicionou os ficheiros SSO ao seu projeto e tem de chamar as APIs do Graph em seguida.

Adicionar chamada à Graph API

Para adicionar a Graph API, siga estes passos:

O SDK do TeamsFx implementa a chamada à graph API.

No Visual Studio Code, aceda a EXPLORER>src>services>listService.ts.

Atualize o seguinte código no 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",
  // },
}

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

Atualize o para adicionar widget export default class ListWidget() de perfil de utilizador.

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

O SSO e a Graph API mostram o perfil de utilizador com sessão iniciada no widget de lista.

Desafio completo

10 minutos restantes

Encontrou algo assim?

Captura de ecrã a mostrar a saída final do dashboard.

Parabéns!

100% concluído!

Concluiu o tutorial!

Compartilhar via

Criar um dashboard no Teams