Funcionalidade avançada de exibição de cartão

Artigo
04/08/2023

Este tutorial se baseia no seguinte tutorial: Criar sua primeira Extensão de Cartão Adaptável do SharePoint

Importante

Esse recurso ainda é um status de visualização como parte da versão 1.14 e não deve ser usado em produção. Queremos lançá-los oficialmente como parte da próxima versão 1.15.

Neste tutorial, você implementará a funcionalidade avançada de exibição de cartão. Você se baseia no tutorial anterior e criará uma exibição de cartão alimentada por dados em uma lista do SharePoint.

Criação de uma lista de testes

Prepare este tutorial criando uma nova lista em um site do SharePoint com alguns dados de exemplo:

Navegue até seu site e crie uma nova lista chamada Lista de Instrução.
Adicione uma coluna de Linha única de texto chamada Descrição.
Adicione alguns itens à lista:
- Título: Etapa 1, Descrição: Usar ACEs
- Título: Etapa 2, Descrição: ???
- Título: Etapa 3, Descrição: SPFx 🚀 🌝
Obter a ID da lista:
1. Ao exibir a lista, selecione o ícone de engrenagem na barra de pacotes para abrir o menu Configurações. Em seguida, selecione o item de menu Configurações da lista:
2. Na página Configurações da lista, localize a ID da lista na URL:
3. Salve a ID da lista para que você possa usá-la na próxima etapa.

Adicionar a funcionalidade ACE

Comece com a ACE HelloWorld do tutorial anterior, Criar sua primeira Extensão de Cartão Adaptável do SharePoint. Faça as seguintes atualizações em preparação para a Etapa 2.

Alterar propriedades

Vamos modificar as propriedades da nossa ACE e definir a ID da lista que contém os dados que nossa ACE exibirá:

Localize e abra o seguinte arquivo em seu projeto: ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.ts.

Atualize a interface usada para definir o tipo da propriedade propertiesda ACE:

export interface IHelloWorldAdaptiveCardExtensionProps {
  title: string;
  description: string;
  iconProperty: string;
  listId: string;
}

Localize e abra o seguinte arquivo em seu projeto: ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.manifest.json.

Inicialize a ACE com a ID da Lista criada na etapa anterior definindo o seguinte preConfiguredEntries:

  "preconfiguredEntries": [{
    // ...
    "properties": {
      "title": "HelloWorld",
      "description": "HelloWorld description",
      "iconProperty": "", // Default to sharepointlogo
      "listId": "" // TODO: enter list id
    }
  }]

Importante

Insira a ID da lista obtida anteriormente na propriedade listId no código preconfiguredEntries acima.

Localize e abra o seguinte arquivo no projeto: ./src/adaptiveCardExtensions/helloWorld/HelloWorldPropertyPane.ts.
Atualize o Painel de Propriedades adicionando o seguinte campo:
```
PropertyPaneTextField('listId', {
  label: 'List ID'
})
```

Alterar o estado do ACE

Em seguida, vamos atualizar o estado da ACE. Quando o estado for alterado, ele disparará a ACE para renderizar novamente. Essas alterações adicionarão uma coleção de itens de lista ao estado, bem como o item atual exibido, conforme indicado pela propriedade currentIndex que você adicionará.

Localize e abra o seguinte arquivo em seu projeto: ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.ts.
Adicione uma nova interface para os dados da Lista adicionando o seguinte código ao arquivo:
```
export interface IListItem {
  title: string;
  description: string;
}
```

Atualize a interface usada para definir o estado da ACE para usar a nova interface IListItem:

export interface IHelloWorldAdaptiveCardExtensionState {
  currentIndex: number;
  items: IListItem[];
}

Atualize a inicialização state atualizando o métodoonInit() na ACE:

public onInit(): Promise<void> {
  this.state = {
    currentIndex: 0,
    items: []
  };
  // ...
}

Remova temporariamente onde o state é referenciado no ACE e no Views atualizando o método onPropertyPaneFieldChanged():

// tslint:disable-next-line: no-any
protected onPropertyPaneFieldChanged(propertyPath: string, oldValue: any, newValue: any): void {
}

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

Atualize os métodos data() e onAction() para o seguinte:

public get data(): IQuickViewData {
  return {
    subTitle: '',
    title: strings.Title
  };
}

public onAction(action: IActionArguments): void {
}

Agora que o estado foi atualizado, agora podemos atualizar nossa ACE para buscar dados da lista do SharePoint.

Adicionar dependência

A próxima etapa é adicionar suporte ao projeto e à ACE para recuperar itens de uma lista do SharePoint. Para fazer isso, você usará a API da Estrutura do SharePoint (SPFx) para chamar o ponto de extremidade REST do SharePoint.

Primeiro, adicione uma dependência ao pacote SPFx usado para enviar solicitações HTTP para os pontos de extremidade REST:

Localize e abra o seguinte arquivo no projeto: ./package.json. Anote a versão beta dos pacotes beta relacionados ao SPFx usados pelos outros pacotes listados como dependências na seção dependencies do arquivo package.json.
Instale o seguinte pacote NPM em seu projeto: @microsoft/sp-http:
```
npm install @microsoft/sp-http -SE
```

Buscar os dados da lista

Em seguida, adicione suporte para chamar a API REST do SharePoint e adicionar os itens recuperados ao estado da ACE. Quando o estado for atualizado, ele disparará a ACE para renderizar novamente.

Localize e abra o seguinte arquivo em seu projeto: ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.ts.

Solicite os dados da lista usando a APISPHttpClient do SPFx. Adicione o seguinte à classe que implementa o ACE:

import { SPHttpClient } from '@microsoft/sp-http';

..

private _fetchData(): Promise<void> {
  if (this.properties.listId) {
    return this.context.spHttpClient.get(
      `${this.context.pageContext.web.absoluteUrl}` +
        `/_api/web/lists/GetById(id='${this.properties.listId}')/items`,
      SPHttpClient.configurations.v1
    )
      .then((response) => response.json())
      .then((jsonResponse) => jsonResponse.value.map(
        (item) => { return { title: item.Title, description: item.Description }; })
        )
      .then((items) => this.setState({ items }));
  }

  return Promise.resolve();
}

Atualize a ACE para solicitar os dados da lista durante a inicialização atualizando o método onInit().

Substitua a última linha return Promise.resolve(); para ser return this._fetchData(); da seguinte maneira:
```
public onInit(): Promise<void> {
  // ...
  return this._fetchData();
}
```

Atualize a ACE para solicitar os dados da lista quando o Painel de Propriedades for atualizado. Adicione o método a seguir à classe que implementa a ACE. Esse código só solicitará os dados quando a ID da lista for alterada no Painel de Propriedades:

protected onPropertyPaneFieldChanged(propertyPath: string, oldValue: any, newValue: any): void {
  if (propertyPath === 'listId' && newValue !== oldValue) {
    if (newValue) {
      this._fetchData();
    } else {
      this.setState({ items: [] });
    }
  }
}

Atualizações de cartão

Com a ACE atualizada para buscar itens de uma lista do SharePoint, vamos atualizar o cartão para exibir esses dados.

Localize e abra o seguinte arquivo no projeto: ./src/adaptiveCardExtensions/helloWorld/cardView/CardView.ts.

Atualize o getter data() para exibir dados da lista:

public get data(): IPrimaryTextCardParameters {
  const { title, description } = this.state.items[this.state.currentIndex];
  return {
    description,
    primaryText: title
  };
}

Agora você pode testar o ACE. Compile e inicie o ACE no workbench hospedado:

gulp serve

Depois que o servidor Web local estiver em execução, navegue até o workbench hospedado: https://{tenant}.sharepoint.com/_layouts/15/workbench.aspx

Observação

Remova qualquer instância antiga do ACE do seu workbench. Instâncias ACE do tutorial anterior mostrarão uma mensagem de erro já que as propriedades ACE foram atualizadas.

Abra a Caixa de ferramentas e selecione o ACE:

Selecione a ACE na Caixa de ferramentas

Exibições de cartão condicional

Por padrão, as exibições são automaticamente responsivas ao tamanho do cartão. No entanto, as ACEs podem, opcionalmente, fornecer exibições diferentes para qualquer tamanho de cartão fornecido.

Altere a ACE HelloWorld para exibir a contagem total de itens de Lista no tamanho de cartão Médioe exiba os itens de lista no tamanho do cartãoGrande para maximizar o uso do espaço disponível.

Exibição de cartão médio

Vamos criar uma exibição de cartão médio para nosso ACE:

Crie um novo arquivo na pasta ./src/adaptiveCardExtensions/helloWorld/cardView/MediumCardView.ts.

Adicione o seguinte código para criar uma nova exibição de cartão de tamanho Médio:

import {
  BaseBasicCardView,
  IActionArguments,
  IBasicCardParameters,
  ICardButton
} from '@microsoft/sp-adaptive-card-extension-base';
import {
  IListItem, QUICK_VIEW_REGISTRY_ID,
  IHelloWorldAdaptiveCardExtensionProps,
  IHelloWorldAdaptiveCardExtensionState
} from '../HelloWorldAdaptiveCardExtension';

// Extend from BaseBasicCardView
export class MediumCardView extends BaseBasicCardView<IHelloWorldAdaptiveCardExtensionProps, IHelloWorldAdaptiveCardExtensionState> {
  // Use the Card button to open the Quick View
  public get cardButtons(): [ICardButton] {
    return [
      {
        title: 'View All',
        action: {
          type: 'QuickView',
          parameters: {
            view: QUICK_VIEW_REGISTRY_ID
          }
        }
      }
    ];
  }

  // Display the total number of steps
  public get data(): IBasicCardParameters {
    return {
      primaryText: `${this.state.items.length} Steps`
    };
  }
}

Localize e abra o seguinte arquivo em seu projeto: ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.ts.

Agora, registre o novo Modo de Exibição fazendo as seguintes alterações em seu ACE:

import { MediumCardView } from './cardView/MediumCardView';

..

const MEDIUM_VIEW_REGISTRY_ID: string = 'HelloWorld_MEDIUM_VIEW';

..

public onInit(): Promise<void> {
  // ...
  this.cardNavigator.register(CARD_VIEW_REGISTRY_ID, () => new CardView());
  this.cardNavigator.register(MEDIUM_VIEW_REGISTRY_ID, () => new MediumCardView());
  // ...
}

Atualize o método renderCard() para retornar a Exibição de cartão Médio ou Grande com base no tamanho do cartão:

protected renderCard(): string | undefined {
  return this.cardSize === 'Medium' ? MEDIUM_VIEW_REGISTRY_ID : CARD_VIEW_REGISTRY_ID;
}

Teste suas alterações atualizando o workbench:

A ACE atualizada renderizando diferentes tamanhos da ACE

Altere o tamanho do cartão para Grande e atualize o navegador:

Cartão da ACE renderizando o Cartão grande

Interatividade de Cartão Grande

As exibições do Cartão ACE dão suporte à interação do usuário. Os botões podem invocar APIs REST ou ser usados para interagir com o Cartão de outras maneiras. Nesta seção, você alterará o modo de exibição do Cartão grande para iterar pelos itens na lista do SharePoint.

Localize e abra o seguinte arquivo no projeto: ./src/adaptiveCardExtensions/helloWorld/cardView/CardView.ts.
Na parte superior do arquivo, adicione IActionArguments como uma das referências a serem importadas do pacote @microsoft/sp-adaptive-card-extension-base:
```
import { IActionArguments } from '@microsoft/sp-adaptive-card-extension-base';
```

Os botões no modo de exibição Cartão podem ser dinâmicos com base no estado atual da ACE. Adicione o seguinte código ao arquivo CardView.ts da ACE:

public get cardButtons(): [ICardButton] | [ICardButton, ICardButton] {
  const buttons: ICardButton[] = [];

  // Hide the Previous button if at Step 1
  if (this.state.currentIndex > 0) {
    buttons.push({
      title: 'Previous',
      action: {
        type: 'Submit',
        parameters: {
          id: 'previous',
          op: -1 // Decrement the index
        }
      }
    });
  }

  // Hide the Next button if at the end
  if (this.state.currentIndex < this.state.items.length - 1) {
    buttons.push({
      title: 'Next',
      action: {
        type: 'Submit',
        parameters: {
          id: 'next',
          op: 1 // Increment the index
        }
      }
    });
  }

  return buttons as [ICardButton] | [ICardButton, ICardButton];
}

Em seguida, atualize o state quando um botão é selecionado implementando o seguinte método:

public onAction(action: IActionArguments): void {
  if (action.type === 'Submit') {
    const { id, op } = action.data;
    switch (id) {
      case 'previous':
      case 'next':
      this.setState({ currentIndex: this.state.currentIndex + op });
      break;
    }
  }
}

Teste suas alterações recarregando o workbench no navegador.

A primeira instância do cartão mostrará o primeiro item de lista com um botão Avançar:

Primeira exibição do cartão com o botão Avançar

Selecione o botão Avançar. O cartão exibirá o próximo item na lista e adicionará um botão Anterior :

Card exibindo um item de lista do SharePoint que não é o primeiro ou último item da lista

Selecione o botão Avançar até chegar ao último item na lista. O cartão exibirá o item na lista e exibirá apenas o botão Anterior :

Cartão exibindo o último item na lista com apenas um botão Anterior

Exibição do Cartão de Cache e estado ACE

A partir do SPFx v1.14, as ACEs têm uma camada de cache do lado do cliente que pode ser configurada para armazenar:

O cartão renderizado mais recente.
O estado da ACE.

Renderização do modo de exibição de Cartão armazenado em cache

Se o cartão renderizado mais recente for armazenado, o Painel renderizará esse cartão armazenado em cache antes que o ACE seja inicializado, melhorando o desempenho percebido.

As configurações para esse cache podem ser definidas substituindo o seguinte método:

protected getCacheSettings(): Partial<ICacheSettings> {
  return {
    isEnabled: true, // can be set to false to disable caching
    expiryTimeInSeconds: 86400, // controls how long until the cached card and state are stale
    cachedCardView: () => new CardView() // function that returns the custom Card view that will be used to generate the cached card
  };
}

Reidratação do estado ACE armazenado em cache

O subconjunto do estado ACE armazenado em cache pode ser configurado substituindo o seguinte método:

protected getCachedState(state: TState): Partial<TState>;

O objeto retornado por esse método será serializado e armazenado em cache. Por padrão, nenhum estado é armazenado em cache. Na próxima chamada para onInit, o valor desserializado será passado para onInit como parte do ICachedLoadParameters

public onInit(cachedLoadParameters?: ICachedLoadParameters): Promise<void>;

O valor pode ser usado para reidratar o estado do ACE recém-inicializado.

Conclusão

Após este laboratório, você deve estar familiarizado com:

Alterar o padrão properties de uma ACE
Alterar as interfaces properties/state da ACE
Criar e registrar exibições de cartão
Renderizar condicionalmente elementos de Exibição de cartão
A manipulação avançada da Exibição de cartão
Exibição do Cartão de Cache e estado ACE

Partilhar via