Crie uma Extensão de Cartão Adaptável com ação de geolocalização

Observação

Este tutorial pressupõe que você instalou a SPFx v1.14.

Para obter mais informações sobre como instalar a SPFx v1.14, consulte notas de versão da Estrutura do SharePoint v1.14.

Estruturar um projeto de Extensão de Cartão Adaptável

Crie um novo diretório de projeto para o seu projeto e altere a pasta atual para esse diretório.

Crie um novo projeto executando o Gerador Yeoman do SharePoint a partir do novo diretório que você criou:

yo @microsoft/sharepoint

Quando solicitado, insira os seguintes valores (selecione a opção padrão para todos os avisos omitidos abaixo):

• Qual o nome da sua solução? geolocalização-tutorial
• Que tipo de componente do cliente será criado? Extensão de Cartão Adaptável
• Qual modelo você deseja usar? Modelo de Texto Principal
• Qual é o nome da Extensão de Cartão Adaptável? GeoLocation

Neste ponto, o Yeoman instalará as dependências necessárias e manterá a estrutura dos arquivos da solução. Esse processo pode levar alguns minutos.

Atualizar a URL do workbench hospedada do seu projeto.

Quando você usa a tarefa gulp serve, por padrão, ela iniciará um navegador com a URL de workbench hospedada especificada em seu projeto. A URL padrão para o workbench hospedado em um novo projeto aponta para uma URL inválida.

• Localize e abra o arquivo ./config/serve.json no seu projeto.

• Localize a propriedade initialPage:

  {
    "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json",
    "port": 4321,
    "https": true,
    "initialPage": "https://enter-your-SharePoint-site/ _layouts/workbench.aspx"
  }
  

• Altere o domínio enter-your-SharePoint-site para a URL do seu site e locatário do SharePoint que você deseja usar para testar. Por exemplo: https://contoso.sharepoint.com/sites/devsite/_layouts/workbench.aspx.

Neste ponto, se você fizer gulp serve, verá o cartão GeoLocation:

Adicionar ações de geolocalização à extensão de cartão adaptável

Neste ponto, temos de obter o código gerado por scaffolding pronto para uso. Agora, vamos tentar adicionar ações de geolocalização às experiências de Exibição de Cartão e Exibição Rápida.

Criaremos um cartão que terá um Modo de Exibição de Cartão e um Modo de Exibição Rápido. No Modo de Exibição de Cartão, forneceremos um botão, que mostrará ao usuário sua localização atual e clicar no Modo de Exibição de Cartão em si abrirá um Modo de Exibição Rápido.

No Modo de Exibição Rápido, forneceremos três botões que executarão as seguintes ações:

• Obter a localização atual do usuário
• Permitir que o usuário escolha uma localização no mapa
• Mostrar uma localização específica no mapa

Atualizar os rótulos que aparecerão no cartão

Antes de começar a adicionar as ações, primeiro vamos atualizar as cadeias de caracteres que você verá no cartão.

Para isso, localize e abra o seguinte arquivo em seu projeto: ./src/adaptiveCardExtensions/geoLocation/loc/en-us.js

Substitua o conteúdo deste arquivo por:

define([], function() {
  return {
    "PropertyPaneDescription": "Tutorial on geolocation action in ACE.",
    "TitleFieldLabel": "Geolocation",
    "Title": "GeoLocation",
    "SubTitle": "GeoLocation Actions",
    "PrimaryText": "Location Demo",
    "Description": "Demonstrating GeoLocation Capabilities",
    "ShowCurrentLocation": "My Location"
  }
});

Em seguida, localize e abra o seguinte arquivo em seu projeto: ./src/adaptiveCardExtensions/geoLocation/loc/mystring.d.ts

Adicione o seguinte:

ShowCurrentLocation: string;

À interface IGeoLocationAdaptiveCardExtensionStrings.

Adicionar ações no Modo de Exibição de Cartão

Conforme mencionado anteriormente, no Modo de Exibição de Cartão, adicionaremos um botão, que mostrará ao usuário sua localização atual e, ao clicar no Modo de Exibição de Cartão, mostraremos a experiência de Exibição Rápida.

Primeiro, adicionaremos a funcionalidade para o botão no Modo de Exibição de Cartão. Para isso, localize e abra o seguinte arquivo em seu projeto: ./src/adaptiveCardExtensions/geoLocation/cardView/CardView.ts

Aqui, substitua a definição da função cardButtons pelo seguinte:

public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] | undefined {
  return [
    {
      title: strings.ShowCurrentLocation,
      action: {
        type: 'VivaAction.ShowLocation'
      }
    }
  ];
}

Com essa alteração, configuramos um botão com o rótulo My Location e, ao clicar, a ação é VivaAction.ShowLocation, que mostrará ao usuário sua localização atual.

Em seguida, substitua o conteúdo da função onCardSelection pelo seguinte:

public get onCardSelection(): IQuickViewCardAction | IExternalLinkCardAction | undefined {
  return {
      type: 'QuickView',
      parameters: {
        view: QUICK_VIEW_REGISTRY_ID
      }
  };
}

Essa alteração implica que, quando um usuário clica no Modo de Exibição de Cartão, ele deve abrir um Modo de Exibição Rápido para ele.

Com as alterações feitas até o momento, o Modo de Exibição de Cartão teria a seguinte aparência:

Adicionar ações no Modo de Exibição Rápido

No Modo de Exibição Rápido, apresentaremos botões para três ações:

• Obter a localização atual do usuário
• Permitir que o usuário escolha uma localização no mapa
• Mostrar uma localização específica no mapa (por exemplo, mostraremos o Monte Everest)

Além desses, temos dois blocos de texto para mostrar Latitude e Longitude, que mostrará as respectivas coordenadas quando a ação VivaAction.GetLocation for executada (mais sobre isso adiante).

Primeiro, definiremos o modelo da Exibição Rápida. Para isso, localize e abra o seguinte arquivo em seu projeto: ./src/adaptiveCardExtensions/geoLocation/quickView/template/QuickViewTemplate.json

Substitua o conteúdo desse arquivo com o seguinte:

{
  "schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.2",
  "body": [
    {
      "type": "TextBlock",
      "text": "${latitude}"
    },
    {
      "type": "TextBlock",
      "text": "${longitude}"
    }
  ],
  "actions": [
    {
      "title": "Choose location on map",
      "type": "VivaAction.GetLocation",
      "parameters": {
        "chooseLocationOnMap": true
      }
    },
    {
      "title": "Get my location",
      "type": "VivaAction.GetLocation"
    },
    {
      "title": "Show custom location",
      "type": "VivaAction.ShowLocation",
      "parameters": {
        "locationCoordinates": {
          "latitude": 27.98884062493244,
          "longitude": 86.9249751
        }
      }
    }
  ]
}

Com isso, estamos fornecendo dois blocos de texto para mostrar o Latitude e Longitude da localização que obtemos por meio de VivaAction.GetLocation. Além disso, descrevemos três ações de geolocalização.

Depois de adicionar essas ações, o Modo de Exibição Rápido terá a seguinte aparência:

Configurar o estado para nossa Extensão de Cartão Adaptável

Até agora, criamos o Modo de Exibição de Cartão e o Modo de Exibição Rápido. Se você fizer um gulp serve neste ponto, poderá executar as ações descritas acima.

Mas agora, vamos tornar a tarefa mais complicada.

Agora, queremos mostrar as coordenadas da localização atual do usuário ou da localização escolhida pelo usuário na Exibição Rápida quando as respectivas ações forem executadas.

Para isso, aproveitaremos os dois blocos de texto que introduzimos anteriormente no arquivo QuickViewTemplate.json

Para fazer isso, primeiro apresentaremos novos estados. Primeiro localize e abra o seguinte arquivo em seu projeto: ./src/adaptiveCardExtensions/geoLocation/GeoLocationAdaptiveCardExtension.ts

Aqui, adicione o seguinte states à interface IGeoLocationAdaptiveCardExtensionState:

latitude: string;
longitude: string;

Em seguida, na função onInit, altere this.state={} para

this.state = {
  latitude: 'TBD',
  longitude: 'TBD'
};

Agora, também faremos alterações semelhantes no Modo de Exibição Rápido.

Localize e abra o seguinte arquivo no seu projeto: ./src/adaptiveCardExtensions/geoLocation/quickView/QuickView.ts

Adicione as seguintes propriedades à interface IQuickViewData:

latitude: string;
longitude: string;

e adicione as duas linhas a seguir no objeto retornado do getter data:

latitude: "Latitude: " + this.state.latitude,
longitude: "Longitude: " + this.state.longitude

Implementar a função onAction

Até agora, criamos nossas ações de geolocalização e com fio em nossos estados. Agora podemos finalmente implementar a função onAction, que oferece a capacidade do Desenvolvedor de Terceiros decidir o que deseja fazer com as coordenadas de localização que o usuário compartilhou com eles.

Para isso, abra o arquivo QuickView.ts (./src/adaptiveCardExtensions/geoLocation/quickView/QuickView.ts) e importe a interface IGetLocationActionArguments da seguinte maneira:

import {IGetLocationActionArguments} from '@microsoft/sp-adaptive-card-extension-base';

Por fim, introduza a seguinte função onAction na classe QuickView:

public onAction(action: IGetLocationActionArguments): void {
  if (action.type === 'VivaAction.GetLocation') {
    this.setState({
      latitude: action.location.latitude.toString(),
      longitude: action.location.longitude.toString()
    });
  }
}

Agora, sempre que a ação VivaAction.GetLocation for disparada no Modo de Exibição Rápido, dependendo dos parâmetros que foram passados, a estrutura de Extensão de Cartão Adaptável passará as coordenadas atuais do usuário ou as coordenadas escolhidas pelo usuário para o retorno de chamada onAction. Na implementação compartilhada acima, verificamos se o tipo action é do tipo VivaAction.GetLocation, e, se for, renderizamos novamente o Modo de Exibição Rápido fazendo um setState no qual atualizamos os blocos de texto latitude e longitude.

Neste ponto, você pode executar o gulp serve novamente e ver se todas as alterações feitas até agora estão funcionando.

É isso! Parabéns por criar com êxito a Extensão de Cartão Adaptável com ações de geolocalização.