Créer votre première extension de personnalisateur de champ
Les extensions sont des composants côté client qui s’exécutent dans le contexte d’une page SharePoint. Les extensions peuvent être déployées sur SharePoint Online, et vous pouvez utiliser les bibliothèques et les outils JavaScript modernes pour les créer.
Vous pouvez suivre cette procédure en regardant la vidéo sur la chaîne YouTube SharePoint PnP :
Cr?er un projet d?extension
Créez un nouveau répertoire de projet à l’emplacement de votre choix.
md field-extensionAccédez au répertoire du projet.
cd field-extensionCréez une extension HelloWorld en exécutant le générateur SharePoint Yeoman.
yo @microsoft/sharepointLorsque 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 ? : extension de champ
- Les composants de la solution nécessiteront-ils des autorisations pour accéder aux API web qui sont uniques et qui ne sont pas partagées avec d’autres composants du client ? (y/n) n
- 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 personnaliste de champ ? HelloWorld
- Quelle est la description de votre personnaliste de champ ? Description HelloWorld
- Quelle infrastructure voulez-vous utiliser ? : Aucune infrastructure JavaScript
À ce stade, Yeoman installe les dépendances requises et établit la structure des fichiers de la solution avec l’extension HelloWorld. Cette opération peut prendre quelques minutes.
Entrez les informations suivantes dans la console pour démarrer Visual Studio Code.
code .Notes
Étant donné que la solution côté client SharePoint utilise du code HTML/TypeScript, vous pouvez utiliser n’importe quel éditeur de code qui prend en charge le développement côté client pour créer votre extension.
Ouvrez le fichier ./src/extensions/helloWorld/HelloWorldFieldCustomizer.manifest.jssur.
Ce fichier définit votre type d’extension et un identificateur unique
idpour votre extension. Vous aurez besoin ultérieurement de cet identificateur unique lors du débogage et du déploiement de votre extension sur SharePoint.
Codage de votre personnalisateur de champ
Ouvrez le fichier ./src/extensions/helloWorld/HelloWorldFieldCustomizer.ts.
Notez que la classe de base pour le personnalisateur de champ est importée à partir du package sp-listview-extensibility, qui contient le code SharePoint Framework requis par le personnalisateur de champ.
import { Log } from '@microsoft/sp-core-library';
import { override } from '@microsoft/decorators';
import {
BaseFieldCustomizer,
IFieldCustomizerCellEventParameters
} from '@microsoft/sp-listview-extensibility';
La logique de votre personnaliste de champ est contenue dans les méthodes et les onInit() onRenderCell() onDisposeCell() méthodes.
onInit()est l’endroit où vous allez exécuter le programme d’installation nécessaire pour votre extension. Cet événement se produit après quethis.contextetthis.propertiesont été attribués, mais avant que la page DOM ne soit prête. Comme avec les composants Web Parts, renvoie une promesse que vous pouvez utiliser pour faire des opérations asynchrones ; n’est pas appelée tant que votre promesseonInit()onRenderCell()n’est pas résolue. Si vous n’en avez pas besoin, renvoyez simplementPromise.resolve<void>();.onRenderCell()se produit lorsque chaque cellule est rendue. Il fournit un élément HTMLevent.domElementoù votre code peut écrire son contenu.onDisposeCell()se produit immédiatement avantevent.cellDivla suppression. Il peut être utilisé pour libérer des ressources qui ont été allouées pendant le rendu du champ. Par exemple, sionRenderCell()a monté un élément React,onDisposeCell()doit être utilisé pour le libérer ; sinon, une perte de ressource se produit.
Voici le contenu de la solution par défaut et onRenderCell() onDisposeCell() dans celui-ci :
@override
public onRenderCell(event: IFieldCustomizerCellEventParameters): void {
// Use this method to perform your custom cell rendering.
const text: string = `${this.properties.sampleText}: ${event.fieldValue}`;
event.domElement.innerText = text;
event.domElement.classList.add(styles.cell);
}
@override
public onDisposeCell(event: IFieldCustomizerCellEventParameters): void {
super.onDisposeCell(event);
}
Débogage de votre personnalisateur de champ
Vous ne pouvez pas utiliser la console locale pour tester les extensions SharePoint Framework. Vous devez les tester et les développer directement auprès d’un site SharePoint Online activé. Pour ce faire, vous n’êtes pas obligé de déployer votre personnalisation dans le catalogue d’applications. Ainsi, l’expérience de débogage est simple et efficace.
Pour tester votre extension, vous devez d’abord créer le champ pour tester le personnaliste. Accédez au site dans votre client SharePoint Online où tester le personnalisateur de champ.
Accédez à la page Contenu du site.
Dans la barre d’outils, sélectionnez Nouveau, puis Liste.

Créez une liste nommée Commandes, puis sélectionnez Créer.

Sélectionnez + le signe, puis sélectionnez Numéro pour créer un champ Numéro pour la liste.

Définissez le nom du champ sur pourcentage, puis sélectionnez Enregistrer.

Ajoutez quelques éléments avec différents nombres dans le champ Pourcentage. Nous modifierons le rendu ultérieurement dans ce didacticiel, donc les différents nombres seront affichés différemment en fonction de votre implémentation personnalisée.

Dans Visual Studio Code, ouvrez le fichier ./config/serve.jssur.
Définissez
InternalFieldNamel’attributPercentpour le nom du champ que nous avons créé. Mettez à jour les attributs pour qu’ils correspondent à une URL de la liste que nous avons créée lors despageUrlétapes d’aperçu. Après les modifications, votre serve.jsdoit ressembler au code suivant :{ "$schema": "https://developer.microsoft.com/json-schemas/core-build/serve.schema.json", "port": 4321, "https": true, "serveConfigurations": { "default": { "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx", "fieldCustomizers": { "Percent": { "id": "b909e395-f714-421f-94e0-d638dafeb210", "properties": { "sampleText": "Value" } } } }, "helloWorld": { "pageUrl": "https://sppnp.sharepoint.com/sites/Group/Lists/Orders/AllItems.aspx", "fieldCustomizers": { "Percent": { "id": "b909e395-f714-421f-94e0-d638dafeb210", "properties": { "sampleText": "Value" } } } } } }Notes
Le GUID dans l’extrait JSON ci-dessus est l’ID unique du composant d’extension SPFx. Ceci est défini dans le manifeste du composant. Le GUID de votre solution sera différent, car chaque ID de composant est unique.
Compilez votre code et hébergez les fichiers compilés à partir de l’ordinateur local en exécutant la commande suivante :
gulp serveLorsque le code se compile sans erreur, il sert le manifeste résultant à partir https://localhost:4321 de .

Cela démarre votre navigateur par défaut et charge la page définie dans serve.jsfichier.
Acceptez le chargement des manifestes de débogage en sélectionnant Charger les scripts de débogage lorsque vous y êtes invité.

Notez que les valeurs de colonne Pourcentage sont désormais présentées avec une chaîne de préfixe supplémentaire en tant que Valeur :, qui est fournie en tant que propriété pour le personnaliste de champ.

Amélioration du rendu du personnalisateur de champ
Maintenant que nous avons testé avec succès le point de départ prétentable du personnaliste de champ, nous allons modifier légèrement la logique afin d’avoir un rendu plus fin de la valeur du champ.
Ouvrez le fichier ./src/extensions/helloWorld/HelloWorldFieldCustomizer.module.scss et mettez à jour la définition de style comme suit.
.HelloWorld { .cell { display: inline-block; } .full { background-color: #e5e5e5; width: 100px; } }Ouvrez le fichier ./src/extensions/helloWorld/HelloWorldFieldCustomizer.ts et mettez à jour la
onRenderCell()méthode comme suit.@override public onRenderCell(event: IFieldCustomizerCellEventParameters): void { event.domElement.classList.add(styles.cell); event.domElement.innerHTML = ` <div class='${styles.HelloWorld}'> <div class='${styles.full}'> <div style='width: ${event.fieldValue}px; background:#0094ff; color:#c0c0c0'> ${event.fieldValue} </div> </div> </div>`; }Dans la fenêtre de la console, assurez-vous de ne pas avoir d’erreurs. Si la solution n’est pas en cours d’exécution, exécutez la tâche suivante :
gulp serveDans votre liste créée précédemment, actualisez la fenêtre du navigateur avec les paramètres de requête de débogage ou redémarrez le navigateur avec gulp serve.
Acceptez le chargement des manifestes de débogage en sélectionnant Charger les scripts de débogage lorsque vous y êtes invité.

Notez la façon dont nous avons modifié le style du rendu du champ complètement. La valeur du champ est indiquée à l’aide d’une représentation graphique de la valeur.

Ajouter la définition du champ au package de solution pour le déploiement
Maintenant que nous avons correctement testé notre solution en mode débogage, nous pouvons la déployer automatiquement dans le cadre du package de solution déployé sur les sites.
Installez le package de solution sur le site où il doit être installé, afin que le manifeste d’extension soit inclus pour l’exécution.
Associez le personnalisateur de champ à un champ existant dans le site. Vous pouvez le faire par programme à l’aide de SharePoint REST ou de l’API CSOM, ou à l’aide de Feature Framework dans le package SharePoint Framework solution. Dans ce didacticiel, nous allons utiliser les fichiers xml de Feature Framework. Vous devez associer les propriétés suivantes dans l’objet
SPFieldau niveau du site ou de la liste.ClientSideComponentId: il s’agit de l’identificateur (GUID) du personnalificateur de champ qui a été installé dans le catalogue d’applications.ClientSideComponentProperties: il s’agit d’un paramètre facultatif qui peut être utilisé pour fournir des propriétés pour l’instance du personnaliste de champ.
Vous pouvez contrôler la nécessité d’ajouter une solution contenant votre extension au site avec la propriété
skipFeatureDeploymentdans ./config/package-solution.jsfichier. Même si vous n’avez pas besoin que la solution soit installée sur le site, vous devez l’associer à des objets spécifiques pour queClientSideComponentIdl’extension soit visible.Vous pouvez utiliser, par exemple, l’cmdlet Set-PnPField des cmdlets PowerShell PnP pour associer par programmation une extension à des champs existants dans vos sites.
Notes
PnP PowerShell est une solution open source pour laquelle un support est assuré par la communauté active. Il n’existe pas de contrat SLA Microsoft pour le support technique relatif à cet outil open source.
Vérification du fichier elements.xml
Dans les étapes suivantes, nous allons vérifier la définition de champ par défaut, qui a été automatiquement créée et sera ensuite utilisée pour déployer automatiquement les configurations nécessaires lorsque le package de solution sera installé sur un site.
Revenez à votre solution dans Visual Studio Code (ou dans votre éditeur favori).
Ouvrez le fichier ./sharepoint/assets/elements.xml.

Regardez le XML dans ce fichier. La propriété a été automatiquement mise à jour avec l’ID unique de votre personnaliste de champ disponible dans le fichier ClientSideComponentId ./src/extensions/helloWorld/HelloWorldFieldCustomizer.manifest.jssur. Vous devez ajuster ce fichier en fonction de votre type de champ et des détails.
Notes
Pour plus d’informations sur le schéma XML Feature Framework, voir : SharePoint référence de schéma.
<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<Field ID="{060E50AC-E9C1-3D3C-B1F9-DE0BCAC200F6}"
Name="SPFxPercentage"
DisplayName="Percentage"
Type="Number"
Min="0"
Required="FALSE"
Group="SPFx Columns"
ClientSideComponentId="7e7a4262-d02b-49bf-bfcb-e6ef1716aaef">
</Field>
</Elements>
S’assurer que les définitions sont prises en compte dans le pipeline de build
Ouvrez le fichier ./config/package-solution.json.
Le fichier package-solution.json définit les métadonnées de package, comme illustré dans le code suivant : Pour vous assurer que le fichierelement.xml est pris en compte lors de la création du package de solution, la création de la création de la carte par défaut de ce fichier est mise à jour pour inclure des détails supplémentaires pour une définition de fonctionnalité. Cette définition de fonctionnalité est utilisée pour mettre en service et exécuter elements.xml fichier.
Notez également que includeClientSideAssets l’attribut est définie sur true . Cela signifie que les ressources JavaScript seront incluses dans le fichier * .sppkg :
{
"$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
"solution": {
"name": "field-extension-client-side-solution",
"id": "80c04d1b-dca7-4d0a-86c0-9aedf904704f",
"version": "1.0.0.0",
"includeClientSideAssets": true,
"isDomainIsolated": false,
"features": [
{
"title": "Application Extension - Deployment of custom action.",
"description": "Deploys a custom action with ClientSideComponentId association",
"id": "b27507b9-7c2a-4398-8946-7438571f16f6",
"version": "1.0.0.0",
"assets": {
"elementManifests": [
"elements.xml"
]
}
}
]
},
"paths": {
"zippedPackage": "solution/field-extension.sppkg"
}
}
Déployer le champ sur SharePoint Online et héberger JavaScript à partir d’un hôte local
Vous êtes maintenant prêt à déployer la solution sur un site SharePoint et à inclure automatiquement l’association de champ dans un champ. Nous allons utiliser l’option --ship avec cet empaquetage afin que toutes les ressources soient automatiquement empaquetées dans le package de solution.
Dans la fenêtre de la console, entrez la commande suivante pour intégrer votre solution côté client qui contient l’extension dans un package, afin que la structure de base soit prête pour la création de package :
gulp bundle --shipExécutez la commande suivante afin de créer le package de solutions :
gulp package-solution --shipLa commande crée le package : ./sharepoint/solution/field-extension.sppkg:
Vous devez maintenant déployer le package qui a été généré dans le catalogue d’applications. Pour ce faire, accédez au catalogue d’applications de votre client et ouvrez la bibliothèque Applications pour SharePoint.
Télécharger fichier ./sharepoint/solution/field-extension.sppkg dans le catalogue d’applications.
Notez que SharePoint affiche la boîte de dialogue d’confiance et vous demande d’faire confiance à la solution côté client avec SharePoint Online comme domaine. Vos ressources seront automatiquement hébergées à partir de l’URL du catalogue d’applications ou de Microsoft 365 CDN public, en fonction des paramètres de votre client.
Sélectionnez le bouton Déployer.

Accédez au site sur lequel vous souhaitez tester la mise en service de composants SharePoint. Il peut s’agir d’une collection de sites dans le client où vous avez déployé ce package de solutions.
Sélectionnez l’icône d’engrenage dans la barre de navigation supérieure à droite, puis sélectionnez Ajouter une application.
Dans la zone de recherche, entrez le champ, puis sélectionnez Entrée pour filtrer vos applications.

Sélectionnez l’application field-extension-client-side-solution pour installer la solution sur le site. Une fois l’installation terminée, actualisez la page.
Une fois que la solution est installée, sélectionnez Nouveau dans la barre d’outils sur la page Contenu du site et sélectionnez Liste.

Créez une liste appelée Factures.
Lorsque la nouvelle liste est créée, sur la page Contenu du site, sélectionnez Paramètres dans le menu de la liste nouvellement créée.

Sélectionner des > colonnes à ajouter à partir de colonnes de site existantes.
Sélectionnez le SPFx Pourcentage de colonnes qui a été mise en service à partir du package de > solution, puis sélectionnez OK.

Accédez à la liste Factures nouvellement créée. Ajoutez quelques nouveaux éléments à la liste avec des valeurs différentes dans la colonne Pourcentage pour voir comment le champ est rendu sans les paramètres de requête de débogage.

Le processus de publication de votre application est identique quel que soit le type d’extension.
Notes
Il s’agissait d’un personnalateur de champ relativement simple avec des fonctionnalités qui auraient également pu être obtenues avec la mise en forme de colonne d’utilisation pourpersonnaliser SharePoint . Toutefois, la mise en forme de colonne ne prend pas en charge le code personnalisé réel. Notez que les personnaliseurs de champ ne peuvent pas être modifiés par les utilisateurs finaux à partir de l’interface utilisateur, ce qui permet des cas d’utilisation supplémentaires.