Partager via

Fonctionnalités avancées d’affichage de carte

  • Article

Ce tutoriel s’appuie sur le tutoriel suivant : Créez votre première extension de carte adaptative SharePoint

Importante

Cette fonctionnalité suivante se trouve toujours dans l’état de préversion dans le cadre de la version 1.14 et ne doivent pas être utilisées en production. Nous cherchons à les publier officiellement dans le cadre de la prochaine version 1.15.

Dans ce tutoriel, vous allez implémenter la fonctionnalité avancée d’affichage de carte. Vous vous baserez sur le didacticiel précédent et créerez une vue de carte alimentée par les données d'une liste Microsoft Office SharePoint Online.

Créer une liste de tests

Préparez ce tutoriel en créant une nouvelle liste dans un site SharePoint avec quelques exemples de données :

  1. Accédez à votre site et créez une nouvelle liste nommée Liste d'instructions.

  2. Ajoutez une colonne Ligne de texte unique nommée Description.

    Liste SharePoint vide

  3. Ajoutez quelques éléments à la liste :

    • Titre : Étape 1, Description : Utiliser ACE
    • Titre : Étape 2, Description : ???
    • Titre : Étape 3, Description : SPFx 🚀 🌝

  4. Obtenir l’ID de la liste :

    1. Lors de l’affichage de la liste, sélectionnez l’icône Engrenage dans la barre de la suite pour ouvrir le menu Paramètres. Sélectionnez ensuite l’élément de menu Paramètres de la liste :

      Écran Paramètres de la liste

    2. Sur la page Paramètres de la liste, localisez l’ID de la liste dans l’URL :

      ID de la liste dans l’URL

    3. Enregistrez l’ID de la liste pour pouvoir l’utiliser lors de l’étape suivante.

Ajouter la fonctionnalité ACE

Commencez avec l’ACE HelloWorld du tutoriel précédent, Créez votre première extension de carte adaptative SharePoint. Effectuez les mises à jour suivantes en vue de l’étape 2.

Modifier les propriétés

Modifions les propriétés de notre ACE et définissons l'ID de liste qui contient les données que notre ACE affichera :

  1. Recherchez et ouvrez le fichier suivant dans le projet : ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.ts.

  2. Mettez à jour l’interface utilisée pour définir le type de propriété de l’ACE properties :

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

  3. Recherchez et ouvrez le fichier suivant dans le projet : ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.manifest.json.

  4. Initialisez l’ACE avec l’ID de la liste créée lors de l’étape précédente en définissant les preConfiguredEntries suivantes :

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

    Importante

    Assurez-vous d'entrer l'ID de la liste que vous avez précédemment obtenue dans la listId propriété dans le preconfiguredEntries code ci-dessus.

  5. Recherchez et ouvrez le fichier suivant dans le projet : ./src/adaptiveCardExtensions/helloWorld/HelloWorldPropertyPane.ts.

  6. Mettez à jour le volet des propriétés en ajoutant le champ suivant :

    PropertyPaneTextField('listId', {
  label: 'List ID'
})

Modifier l’état de l’ACE

Ensuite, mettons à jour l'état de l'ACE. Lorsque l'état change, cela déclenchera un nouveau rendu de l'ACE. Ces modifications ajouteront une collection d'éléments de liste à l'état ainsi que l'élément actuel affiché, comme indiqué par la currentIndex propriété que vous ajouterez.

  1. Recherchez et ouvrez le fichier suivant dans le projet : ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.ts.

  2. Ajoutez une nouvelle interface pour les données de la liste en ajoutant le code suivant au fichier :

    export interface IListItem {
  title: string;
  description: string;
}

  3. Mettez à jour l’interface utilisée pour définir l’état de l’ACE pour utiliser la nouvelle interface IListItem :

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

  4. Mettez à jour l’state de l’initialisation en mettant à jour la méthode onInit() dans l’ACE :

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

  5. Supprimez temporairement l’emplacement dans lequel l’state est référencé dans l’ACE et les vues en mettant à jour la méthode onPropertyPaneFieldChanged() :

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

  6. Recherchez et ouvrez le fichier suivant dans le projet : ./src/adaptiveCardExtensions/helloWorld/quickView/QuickView.ts.

  7. Mettez à jour les méthodes data()et onAction() comme suit :

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

public onAction(action: IActionArguments): void {
}

Maintenant que l'état a été mis à jour, nous pouvons maintenant mettre à jour notre ACE pour récupérer les données de la liste Microsoft Office SharePoint Online.

Ajouter une dépendance

L'étape suivante consiste à ajouter une prise en charge au projet et à ACE pour récupérer les éléments d'une liste Microsoft Office SharePoint Online. Pour ce faire, vous utiliserez l'API SharePoint Framework (SPFx) pour appeler le point de terminaison REST SharePoint.

Tout d'abord, ajoutez une dépendance au package SPFx utilisé pour soumettre des requêtes HTTP aux points de terminaison REST :

  1. Recherchez et ouvrez le fichier suivant dans le projet : ./package.json. Prenez note de la version bêta des packages bêta liés à SPFx utilisés par les autres packages répertoriés comme dépendances dans la section dependencies du fichier package.json.

  2. Installez le package NPM suivant dans votre projet : @microsoft/sp-http:

    npm install @microsoft/sp-http -SE

Récupérer les données de la liste

Ensuite, ajoutez la prise en charge de l'appel de l'API REST Microsoft Office SharePoint Online et de l'ajout des éléments récupérés à l'état de l'ACE. Lorsque l'état est mis à jour, il déclenchera le nouveau rendu de l'ACE.

  1. Recherchez et ouvrez le fichier suivant dans le projet : ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.ts.

  2. Demandez les données de la liste à l’aide de l’API SPFx SPHttpClient. Ajoutez ce qui suit à la classe qui implémente l’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();
}

  3. Mettez à jour l'ACE pour demander les données de la liste lors de son initialisation en mettant à jour la onInit() méthode.

    Remplacez la dernière ligne return Promise.resolve(); comme return this._fetchData(); suit :

    public onInit(): Promise<void> {
  // ...
  return this._fetchData();
}

  4. Mettez à jour l’ACE pour demander les données de la liste lorsque le volet des propriétés est mis à jour. Ajoutez la méthode suivante à la classe qui implémente l’ACE. Ce code ne demande les données que lorsque l’ID de la liste est modifié dans le volet des propriétés :

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

Mises à jour de la carte

Avec l'ACE mis à jour pour récupérer les éléments d'une liste Microsoft Office SharePoint Online, mettons à jour la carte pour afficher ces données.

  1. Localisez et ouvrez le fichier suivant dans le projet : ./src/adaptiveCardExtensions/helloWorld/cardView/CardView.ts.

  2. Mettez à jour le getter data()pour afficher les données de la liste :

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

Vous pouvez à présent tester le ACE. Créez et lancez l'ACE dans l'atelier hébergé :

gulp serve

Une fois le serveur web local chargé, accédez au workbench hébergé : https://{tenant}.sharepoint.com/_layouts/15/workbench.aspx

Remarque

Supprimez les anciennes instances de l’ACE de votre workbench. Les instances ACE du tutoriel précédent afficheront un message d’erreur puisque les propriétés ACE ont été mises à jour.

Ouvrez la boîte à outils du composant WebPart et sélectionnez votre ACE :

Sélectionner ACE dans la Boîte à outils

Vues de cartes conditionnelles

Par défaut, les affichages sont automatiquement réactifs à la taille de la carte. Cependant, les ACE peuvent éventuellement fournir des affichages différents pour une taille de carte donnée.

Modifiez l’ACE HelloWorld pour afficher le nombre total d’éléments de liste dans la taille de carte Moyenne et affichez les éléments de liste dans la taille de carte Large pour maximiser l’utilisation de l’espace disponible.

Affichage de la taille de carte moyenne

Créons une vue de carte moyenne pour notre ACE :

  1. Créez un nouveau dossier ./src/adaptiveCardExtensions/helloWorld/cardView/MediumCardView.ts.

  2. Ajoutez le code suivant pour créer un affichage de carte de taille Moyenne :

    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`
    };
  }
}

  3. Recherchez et ouvrez le fichier suivant dans le projet : ./src/adaptiveCardExtensions/helloWorld/HelloWorldAdaptiveCardExtension.ts.

  4. Maintenant, enregistrez le nouvel affichage en apportant les modifications suivantes à votre 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());
  // ...
}

  5. Mettez à jour la méthode renderCard() pour renvoyer l’affichage de carte de taille Moyenne ou Large en fonction de la taille de la carte :

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

Testez vos modifications en actualisant le plan de travail :

Mise à jour de l’ACE rendant différentes tailles de l’ACE

Définissez la taille de la carte sur Large et actualisez le navigateur :

Carte ACE renvoyant la taille de carte Large

Grande interactivité de la carte

Les affichages de carte ACE prennent en charge l’interaction de l’utilisateur. Les boutons peuvent invoquer des API REST ou être utilisés pour interagir avec la carte de façons différentes. Dans cette section, vous allez modifier l’affichage de carte de taille Large pour parcourir les éléments de la liste SharePoint.

  1. Localisez et ouvrez le fichier suivant dans le projet : ./src/adaptiveCardExtensions/helloWorld/cardView/CardView.ts.

  2. En haut du fichier, ajoutez IActionArguments comme l'une des références à importer depuis le package @microsoft/sp-adaptive-card-extension-base :

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

  3. Les boutons de l’affichage Carte peuvent être dynamiques en fonction de l’état actuel de l’ACE. Ajoutez le code suivant au fichier CardView.ts de votre 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];
}

  4. Ensuite, mettez à jour l’state lorsqu’un bouton est sélectionné en implémentant la méthode suivante :

    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;
    }
  }
}

Testez vos modifications en rechargeant le workbench dans votre navigateur.

La première instance de la carte affichera le premier élément de la liste avec un bouton Suivant :

Premier affichage de la carte avec le bouton Suivant

Sélectionnez le bouton Suivant. La carte affiche l’élément suivant dans la liste et ajoute un bouton Précédent :

Carte affichant un élément de la liste SharePoint qui n’est ni le premier ni le dernier élément de la liste

Sélectionnez le bouton Suivant jusqu’au dernier élément de la liste. La carte affiche l’élément dans la liste et affiche uniquement le bouton Précédent :

Carte affichant le dernier élément de la liste avec seulement un bouton Précédent

Affichage de la carte de mise en cache et état de ACE

À compter de SPFx v1.14, les ACE disposent d’une couche de mise en cache côté client qui peut être configurée pour stocker :

  1. La dernière carte rendue.
  2. L’État de l’ACE.

Rendu à partir de l’affichage de la carte de mise en cache

Si la dernière carte rendue est stockée, le tableau de bord affiche cette carte de mise en cache avant l’initialisation de l’ACE, ce qui améliore les performances perçues.

Les paramètres de ce cache peuvent être configurés en remplaçant la méthode suivante :

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
  };
}

Réalimentation à partir de l’état ACE mis en cache

Le sous-ensemble de l’état ACE mis en cache peut être configuré en remplaçant la méthode suivante :

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

L’objet retourné par cette méthode sera sérialisé et mis en cache. Par défaut, aucun statut n’est mis en cache. Au prochain appel à onInit, la valeur désérialisée est passée à onInit dans le cadre de l'ICachedLoadParameters

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

La valeur peut ensuite être utilisée pour réalimenter l’état de l’ACE nouvellement initialisé.

Conclusion

Après ce tutoriel, vous devrez savoir :

  • Modifier les properties par défaut de ACE
  • Modifier les interfaces de properties/state de ACE
  • Créer et enregistrer des affichages de carte
  • Utiliser le rendu conditionnel des éléments des affichages de carte
  • Effectuer une manipulation avancée des affichages de carte
  • Affichage de la carte de mise en cache et état de ACE