Partager via

Migrer de JSLink vers les Extensions SharePoint Framework

  • Article

Depuis Microsoft SharePoint 2013, la plupart des solutions d’entreprise conçues en complément de Microsoft 365 et de SharePoint Online ont utilisé la propriété JSLink des affichages de champ et de liste pour personnaliser le rendu des champs.

Dans l’interface utilisateur « moderne » de SharePoint Online et SharePoint Server 2019, la plupart de ces personnalisations ne sont plus disponibles. Heureusement, les extensions SharePoint Framework vous permettent de fournir des fonctionnalités similaires dans l’interface utilisateur « moderne ».

Dans ce didacticiel, vous allez découvrir comment passer des anciennes personnalisations « classiques » au nouveau modèle basé sur les extensions SharePoint Framework.

Remarque

Pour obtenir plus d’informations sur la procédure de création d’extensions SharePoint Framework, reportez-vous à l’article Vue d’ensemble des extensions de SharePoint Framework.

Tout d’abord, voici les options disponibles lors du développement des extensions de SharePoint Framework :

  • Personnalisateur d’application : étend l’IU native « moderne » de SharePoint en ajoutant des éléments HTML personnalisés et du code côté client à des espaces réservés prédéfinis dans les pages « modernes ». Pour plus d’informations sur les personnalisateurs d’application, consultez Créer votre première extension SharePoint Framework (Hello World 1re partie).
  • Jeu de commandes : ajoutez des éléments de menu BCE personnalisés ou des boutons personnalisés à la barre de commandes d’un affichage de liste pour une liste ou une bibliothèque. Vous pouvez associer n’importe quelle action côté client à ces commandes. Pour plus d’informations sur les jeux de commandes, consultez Créer votre première extension de jeu de commandes ListView.
  • Personnalisateur de champ : personnalisez le rendu d’un champ dans un affichage de liste à l’aide d’éléments HTML personnalisés et de code côté client. Pour plus d’informations sur les personnalisateurs de champ, consultez Créer votre première extension de personnalisateur de champ.

L’option la plus utile dans notre cas est l’extension du personnalisateur de champ.

Imaginez que vous êtes dans SharePoint Online et que vous avez une liste personnalisée avec un champ personnalisé intitulé « Couleur », qui est de type Choice et qui propose les valeurs suivantes : Rouge, Vert, Bleu, Jaune. Supposons que vous ayez une valeur personnalisée pour la propriété JSLink du composant WebPart chargé du rendu en mode liste de la liste personnalisée.

Dans l’extrait de code suivant, vous pouvez voir le code JavaScript référencé par la propriété JSLink (customColorRendering.js).

// Define a namespace for the custom rendering code
var customJSLinkRendering = customJSLinkRendering || {};

// Define a function that declare the custom rendering rules for the target list view
customJSLinkRendering.CustomizeFieldRendering = function () {

  // Define a custom object to configure the rendering template overrides
  var customRenderingOverride = {};
  customRenderingOverride.Templates = {};
  customRenderingOverride.Templates.Fields =
  {
    // Declare the custom rendering function for the 'View' of field 'Color'
    'Color':
    {
      'View': customJSLinkRendering.RenderColorField
    }
  };

  // Register the custom rendering template
  SPClientTemplates.TemplateManager.RegisterTemplateOverrides(customRenderingOverride);
};

// Declare the custom rendering function for the 'View' of field 'Color'
customJSLinkRendering.RenderColorField = function (context)
{
  var colorField = context.CurrentItem.Color;

  // Declare a local variable to hold the output color
  var color = '';

  // Evaluate the values of the 'Color' field and render it accordingly
  switch (colorField)
  {
    case 'Red':
      color = 'red';
      break;
    case 'Green':
      color = 'green';
      break;
    case 'Blue':
      color = 'blue';
      break;
    case 'Yellow':
      color = 'yellow';
      break;
    default:
      color = 'white';
      break;
  }

  // Render the output for the 'Color' field
  return "<div style='float: left; width: 20px; height: 20px; margin: 5px; border: 1px solid rgba(0,0,0,.2);background:" + color + "' />";
};

// Invoke the custom rendering function
customJSLinkRendering.CustomizeFieldRendering();

Vous pouvez voir comment la propriété JSLink est configurée dans le composant WebPart d’affichage de liste.

Configuration de la propriété JSLink dans le composant WebPart d’affichage de liste

Si vous avez chargé le fichier JavaScript dans la bibliothèque Éléments du site, la valeur de la propriété JSLink peut être "~site/SiteAssets/customColorRendering.js".

Vous pouvez voir comment fonctionne le rendu personnalisé de la liste.

Rendu personnalisé pour le champ « Couleur » de la liste personnalisée

Comme vous le voyez, les champs Couleur restituent une case remplie de la couleur sélectionnée au niveau de l’élément.

Remarque

Pour configurer ce type de solution dans un site « classique », vous pouvez, finalement, utiliser un modèle de configuration de PnP, capable de configurer la liste avec à la fois le champ personnalisé et la propriété JSLink.

Pour migrer la solution précédente vers SharePoint Framework, suivez les étapes ci-dessous.

Créer une nouvelle solution SharePoint Framework

  1. À partir de la console, créez un dossier pour votre projet comme suit :

    md spfx-custom-field-extension

  2. Accédez au dossier du projet :

    cd spfx-custom-field-extension

  3. Dans le dossier du projet, exécutez le générateur Yeoman pour SharePoint Framework afin de structurer un projet SharePoint Framework :

    yo @microsoft/sharepoint

  4. Lorsque vous y êtes invité, entrez les valeurs suivantes (sélectionnez l’option par défaut pour toutes les invites qui ne sont pas mentionnées ci-dessous) :

    • Quel est le nom de votre solution ? : spfx-custom-field-extension
    • Quel type de composant côté client voulez-vous créer ? : Extension
    • Quel type d’extension côté client créer ? Personnalisateur de champ
    • Quel est le nom de votre personnalisateur de champ ? CustomColorField
    • Quel modèle voulez-vous utiliser ? : Pas de framework JavaScript

  5. Démarrez Visual Studio Code (ou l’éditeur de code de votre choix) et commencez à développer la solution. Pour démarrer Visual Studio Code, vous pouvez exécuter l’instruction suivante.

    code .

Définir le nouveau personnalisateur de champ avec JavaScript

Pour reproduire le comportement du rendu de champ personnalisé JSLink, vous devez implémenter la même logique à l’aide du code côté client au sein de la nouvelle solution SharePoint Framework. Pour accomplir cette tâche, procédez comme suit.

  1. Ouvrez le fichier dossier./src/extensions/customColorField/CustomColorFieldFieldCustomizer.manifest.json. Copiez la valeur de la propriété id et stockez-la dans un endroit sûr, car vous en aurez besoin plus tard.

  2. Ouvrez le fichier ./src/extensions/customColorField/CustomColorFieldFieldCustomizer.ts, puis modifiez le contenu en fonction de l’extrait de code suivant :

    import { Log } from '@microsoft/sp-core-library';
import { override } from '@microsoft/decorators';
import {
  BaseFieldCustomizer,
  IFieldCustomizerCellEventParameters
} from '@microsoft/sp-listview-extensibility';

import * as strings from 'CustomColorFieldFieldCustomizerStrings';
import styles from './CustomColorFieldFieldCustomizer.module.scss';

/**
* If your field customizer uses the ClientSideComponentProperties JSON input,
* it will be deserialized into the BaseExtension.properties object.
* You can define an interface to describe it.
*/
export interface ICustomColorFieldFieldCustomizerProperties {
  // This is an example; replace with your own property
  sampleText?: string;
}

const LOG_SOURCE: string = 'CustomColorFieldFieldCustomizer';

export default class CustomColorFieldFieldCustomizer
extends BaseFieldCustomizer<ICustomColorFieldFieldCustomizerProperties> {

  @override
  public onInit(): Promise<void> {
    // Add your custom initialization to this method.  The framework will wait
    // for the returned promise to resolve before firing any BaseFieldCustomizer events.
    Log.info(LOG_SOURCE, 'Activated CustomColorFieldFieldCustomizer with properties:');
    Log.info(LOG_SOURCE, JSON.stringify(this.properties, undefined, 2));
    Log.info(LOG_SOURCE, `The following string should be equal: "CustomColorFieldFieldCustomizer" and "${strings.Title}"`);
    return Promise.resolve();
  }

  @override
  public onRenderCell(event: IFieldCustomizerCellEventParameters): void {

    var colorField = event.fieldValue;

    // Declare a local variable to hold the output color
    var color = '';

    // Evaluate the values of the 'Color' field and render it accordingly
    switch (colorField)
    {
      case 'Red':
        color = 'red';
        break;
      case 'Green':
        color = 'green';
        break;
      case 'Blue':
        color = 'blue';
        break;
      case 'Yellow':
        color = 'yellow';
        break;
      default:
        color = 'white';
        break;
    }

    // Render the output for the 'Color' field
    event.domElement.innerHTML = "<div style='float: left; width: 20px; height: 20px; margin: 5px; border: 1px solid rgba(0,0,0,.2);background:" + color + "' />";
  }

  @override
  public onDisposeCell(event: IFieldCustomizerCellEventParameters): void {
    // This method should be used to free any resources that were allocated during rendering.
    // For example, if your onRenderCell() called ReactDOM.render(), then you should
    // call ReactDOM.unmountComponentAtNode() here.
    super.onDisposeCell(event);
  }
}

    Comme vous le voyez, le contenu de la méthode onRenderCell() est presque identique à la méthode RenderColorField() dans l’implémentation des JSLink. Les seules différences sont les suivantes :

    • Pour récupérer la valeur de champ active, vous devez impérativement lire la propriété event.fieldValue de l’argument d’entrée de la méthode onRenderCell().
    • Afin de renvoyer le code HTML personnalisé pour afficher le champ, vous devez attribuer une valeur à la propriété innerHTML de l’objet event.domElement, qui représente le conteneur HTML de sortie du rendu du champ.

    Hormis ces modifications mineures, vous pouvez réutiliser le même code JavaScript qu’auparavant.

    Dans l’illustration suivante, vous pouvez voir le résultat obtenu.

    Le personnalisateur de champ dans une liste « moderne »

Tester la solution en mode de débogage

  1. Revenez à la fenêtre de la console et exécutez la commande suivante pour créer la solution et lancer le serveur local Node.js qui l’hébergera.

    gulp serve --nobrowser

  2. Ouvrez votre navigateur préféré et accédez à une liste « moderne » qui comporte un champ personnalisé avec pour nom Couleur et pour type Choice, avec les mêmes options de valeur qu’avant (Rouge, Vert, Bleu, Jaune). Vous pouvez utiliser la liste que vous avez créée dans le site « classique », en l’affichant simplement avec la nouvelle expérience « moderne ». À présent, ajoutez les paramètres de chaîne de requête suivants à l’URL de la page AllItems.aspx.

    ?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&fieldCustomizers={"Color":{"id":"c3070978-d85e-4298-8758-70b5b5933076"}}

    Dans la chaîne de requête, remplacez le GUID par la valeur id enregistrée à partir du fichier CustomColorFieldFieldCustomizer.manifest.json. Le nom de la propriété Color fait référence au nom du champ à personnaliser. Si vous le souhaitez, vous pouvez également fournir un objet de configuration personnalisé, sérialisé au format JSON, comme paramètre supplémentaire pour la construction du personnalisateur de champ.

    Notez que, lors de l’exécution de la demande de page, une boîte de message d’avertissement intitulée « Autoriser scripts de débogage ? » apparaît pour vous demander l’autorisation d’exécuter du code à partir de l’hôte local pour des raisons de sécurité. Si vous souhaitez déboguer localement et tester la solution, vous devez autoriser l’action « Charger les scripts de débogage ».

    Remarque

    Par ailleurs, vous pouvez créer des entrées de configuration du serveur dans le fichier config/serve.json dans votre projet pour automatiser la création des paramètres de chaîne de requête de débogage comme indiqué dans ce document : Débogage de solutions SharePoint Framework sur des pages SharePoint modernes

Définir le nouveau personnalisateur de champ avec TypeScript

Vous êtes prêt à remplacer le code JavaScript par du code TypeScript pour tirer parti de l’approche entièrement saisie de TypeScript.

  1. Ouvrez le fichier /src/extensions/customColorField/CustomColorFieldFieldCustomizer.module.scss. Ce fichier est de type CSS SASS qui représente le style de l’interface utilisateur pour le personnalisateur de champ. Remplacez le contenu du fichier SCSS par le contenu suivant.

    .CustomColorField {
  .cell {
    float: left;
    width: 20px;
    height: 20px;
    margin: 5px;
    border: 1px solid rgba(0,0,0,.2);
  }

  .cellRed {
    background: red;
  }

  .cellGreen {
    background: green;
  }

  .cellBlue {
    background: blue;
  }

  .cellYellow {
    background: yellow;
  }

  .cellWhite {
    background: white;
  }
}

  2. Remplacez l’implémentation de la méthode onRenderCell() par l’extrait de code suivant.

    @override
public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
  // Read the current field value
  let colorField: String = event.fieldValue;

  // Add the main style to the field container element
  event.domElement.classList.add(styles.CustomColorField);

  // Get a reference to the output HTML
  let fieldHtml: HTMLDivElement = event.domElement.firstChild as HTMLDivElement;

  // Add the standard style
  fieldHtml.classList.add(styles.cell);

  // Add the colored style
  switch(colorField)
  {
    case "Red":
      fieldHtml.classList.add(styles.cellRed);
      break;
    case "Green":
      fieldHtml.classList.add(styles.cellGreen);
      break;
    case "Blue":
      fieldHtml.classList.add(styles.cellBlue);
      break;
    case "Yellow":
      fieldHtml.classList.add(styles.cellYellow);
      break;
    default:
      fieldHtml.classList.add(styles.cellWhite);
      break;
  }
}

    Notez que la nouvelle implémentation de la méthode utilise une approche entièrement saisie et affecte la classe CSS cell à l’élément enfant DIV de l’élément de champ actuel, avec une autre classe CSS personnalisée définissant la couleur cible du DIV, basée sur la valeur du champ sélectionnée.

  3. Exécutez une fois de plus le personnalisateur de champ en mode de débogage et observez le résultat.

Empaqueter et héberger la solution

Si vous êtes satisfait du résultat, vous êtes maintenant prêt à empaqueter la solution et à l’héberger dans une infrastructure d’hébergement réelle. Avant de générer l’offre groupée et le package, vous devez déclarer un fichier XML d’infrastructure de fonctionnalité afin de configurer l’extension.

Vérification des éléments d’infrastructure de fonctionnalité

  1. Dans l’éditeur de code, ouvrez le fichier /sharepoint/assets/elements.xml. Dans l’extrait de code suivant, vous pouvez voir à quoi le fichier doit ressembler.

    <?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Field ID="{40475661-efaf-447a-a220-c992b20ec1c3}"
           Name="SPFxColor"
           DisplayName="Color"
           Title="Color"
           Type="Choice"
           Required="FALSE"
           Group="SPFx Columns"
           ClientSideComponentId="c3070978-d85e-4298-8758-70b5b5933076">
    </Field>
</Elements>

    Comme vous le voyez, il rappelle un fichier SharePoint Feature Framework, mais il définit un élément Field personnalisé avec un type de champ Choice, qui utilise l’attribut ClientSideComponentId pour faire référence à l’id du personnalisateur de champ, et il peut y avoir un attribut ClientSideComponentProperties pour configurer les propriétés de configuration personnalisées requises par l’extension.

  2. Ouvrez le fichier ./config/package-solution.json. Dans le fichier, vous trouverez une référence au fichier elements.xml dans la section assets.

    {
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-custom-field-extension-client-side-solution",
    "id": "ab0fbbf8-01ba-4633-8498-46cfd5652619",
    "version": "1.0.0.0",
    "features": [{
      "title": "Application Extension - Deployment of custom action.",
      "description": "Deploys a custom action with ClientSideComponentId association",
      "id": "090dc976-878d-44fe-8f8e-ac603d094aa1",
      "version": "1.0.0.0",
      "assets": {
        "elementManifests": [
          "elements.xml"
        ]
      }
    }]
  },
  "paths": {
    "zippedPackage": "solution/spfx-custom-field-extension.sppkg"
  }
}

Regrouper, empaqueter et déployer la solution

Ensuite, vous devez regrouper et empaqueter l’offre groupée de solutions dans le catalogue d’applications. Pour réaliser cette tâche, procédez comme suit.

Préparez et déployez la solution pour le client SharePoint Online :

  1. Exécutez la tâche suivante pour regrouper votre solution. Cette procédure crée une version Release de votre projet :

    gulp bundle --ship

  2. Exécutez la tâche suivante pour créer un package pour votre solution. Cette commande crée un package *.sppkg dans le dossier sharepoint/solution .

    gulp package-solution --ship

  3. Chargez ou glissez-déplacez le nouveau package de solution côté client dans le catalogue d’applications de votre client, puis sélectionnez le bouton Déployer.

Installer et exécuter la solution

  1. Ouvrez le navigateur et accédez à n’importe quel site cible « moderne ».

  2. Accédez à la page Contenu du site, puis ajoutez une nouvelle application.

  3. Installez une nouvelle application De votre organisation pour parcourir les solutions disponibles dans le catalogue des applications.

  4. Sélectionnez la solution nommée spfx-custom-field-extension-client-side-solution et installez-la sur le site cible.

    Ajouter une application d’interface utilisateur pour ajouter la solution à un site

  5. Une fois l’installation de l’application terminée, créez une liste personnalisée, modifiez les paramètres de liste et ajoutez une nouvelle colonne aux colonnes de site existantes. Sélectionnez le groupe de colonnes appelé Colonnes SPFx et ajoutez le champ Couleur.

    Ajouter le champ à la liste

  6. Modifiez le nouveau champ et configurez des valeurs de couleur (telles que Rouge, Vert, Bleu, Jaune), puis enregistrez les paramètres de champ.

  7. Ajoutez des éléments à la liste et observez le résultat dans l’affichage de liste. Il doit ressembler à l’une des captures d’écran suivantes.

    Personnalisateur de champ en action

Profitez de votre personnalisateur de champ créé à l’aide des extensions de SharePoint Framework !

Voir aussi