Mise en service des composants SharePoint avec votre package de solutions

Dans certains cas, vous devrez configurer une bibliothèque de documents ou une liste SharePoint, ainsi que votre package de solution côté client, afin que la liste ou la bibliothèque soit disponible pour les composants côté client, comme les composants WebPart. La chaîne d’outils de SharePoint Framework vous permet de créer un package et de déployer des éléments SharePoint avec votre package de solution côté client. Ces éléments sont ensuite mis en service lorsque la solution côté client est installée sur un site.

Vous pouvez également trouver des détails sur les options d’approvisionnement dans cette présentation en ligne SharePoint PnP disponible sur la chaîne YouTube Microsoft 365 Platform Community (PnP) :

Mettre en service des éléments avec du code JavaScript

Même si vous pouvez créer des éléments SharePoint avec du code JavaScript dans votre composant, comme des composants WebPart, cette possibilité est limitée selon le contexte de l’utilisateur actuel du composant. Si l’utilisateur ne dispose pas des autorisations nécessaires pour créer ou modifier des éléments SharePoint, le code JavaScript ne met pas en service ces éléments. Dans ce cas, pour mettre en service des éléments SharePoint dans un contexte élevé, vous devez créer un package et déployer des éléments avec votre package de solution.

Mettre en service des éléments SharePoint dans votre solution

Les composants SharePoint suivants peuvent être mis en service avec votre package de solution côté client :

• Champs
• Types de contenu
• Répertorier les instances
• Instances de liste avec schéma personnalisé

Champs

Un champ, ou colonne de site, représente un attribut ou un élément de métadonnées que l’utilisateur souhaite gérer pour les éléments de la liste ou pour le type de contenu auquel il a ajouté la colonne. Il s’agit d’une définition de colonne ou modèle réutilisable que vous pouvez affecter à plusieurs listes dans différents sites SharePoint. Les colonnes de site évitent les remaniements et vous garantissent une cohérence des métadonnées dans les sites et les listes.

Par exemple, supposons que vous définissez une colonne de site nommée Client. Les utilisateurs peuvent ajouter cette colonne à leurs listes et la référencer dans leurs types de contenu. Cela garantit que la colonne a les mêmes attributs partout où elle apparaît, au moins au début.

Vous pouvez consulter le schéma et les attributs dans la documentation Field, élément (Field) pour définir un nouveau champ dans votre solution.

Voici l’exemple d’un nouveau champ DateHeure :

<Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
            Name="DateOpened"
            DisplayName="Date Opened"
            Type="DateTime"
            Format="DateOnly"
            Required="FALSE"
            Group="Financial Columns">
        <Default>[today]</Default>
    </Field>

Types de contenu

Un type de contenu est un ensemble de métadonnées (colonnes), un comportement ou un autre paramètre réutilisable pour une catégorie d’éléments ou de documents dans une bibliothèque de documents ou liste SharePoint. Les types de contenu permettent de gérer les paramètres pour une catégorie d’informations de manière centralisée et de sorte à pouvoir les réutiliser.

Par exemple, prenons une situation commerciale dans laquelle vous disposez de trois types différents de documents : des notes de frais, des bons de commande et des factures. Ces trois types de documents ont certaines caractéristiques communes ; tout d’abord, il s’agit de documents financiers, qui contiennent tous des données avec des valeurs exprimées en devise. Chaque type de document a néanmoins ses propres exigences en matière de données, son propre modèle de document et son propre flux de travail.

Une solution à ce problème d’entreprise consiste à créer quatre types de contenu. Le premier type de contenu, Document financier, peut encapsuler les exigences en matière de données qui sont communes à tous les documents financiers de l’organisation. Les trois restants, Note de frais, Bon de commande et Facture, peuvent hériter d’éléments communs de Document financier. Par ailleurs, ils peuvent définir des caractéristiques propres à chacun d’entre eux, par exemple, un jeu de métadonnées particulier, un modèle de document à utiliser pour la création d’un élément et un flux de travail spécifique pour le traitement d’un élément.

Vous pouvez consulter le schéma et les attributs dans la documentation ContentType, élément (ContentType) pour définir un nouveau type de contenu dans votre solution.

Voici un exemple de type de contenu :

<ContentType ID="0x010042D0C1C200A14B6887742B6344675C8B"
    Name="Cost Center"
    Group="Financial Content Types"
    Description="Financial Content Type">
    <FieldRefs>
        <FieldRef ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}" />
        <FieldRef ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}" />
    </FieldRefs>
</ContentType>

Répertorier les instances

Les listes sont une fonctionnalité sous-jacente clé d’un site SharePoint. Elles permettent aux équipes de collecter, suivre et partager des informations. De nombreuses applications se basent sur les listes créées au niveau du site pour le stockage des données afin d’implémenter leur comportement. Une instance de liste est une liste SharePoint prédéfinie qui a un identificateur connu. Vous pouvez personnaliser et ajouter des éléments à ces listes, créer des listes supplémentaires à partir de modèles de liste qui sont déjà disponibles et créer des listes personnalisées composées uniquement des paramètres et des colonnes que vous choisissez.

SharePoint propose plusieurs modèles de liste, comme la liste des contacts, le calendrier, la liste des tâches et bien plus encore. Vous pouvez utiliser ces modèles afin de créer de nouvelles instances de liste pour vos composants WebPart ou d’autres composants. Par exemple, vous pouvez définir une instance de liste Documents financiers basée sur le modèle de bibliothèque de documents pour stocker des documents associés à votre composant WebPart.

Vous pouvez consulter le schéma et les attributs dans la documentation ListInstance, élément (List Instance) pour définir une instance de liste dans votre solution.

Voici un exemple de définition d’instance de liste :

<ListInstance
    FeatureId="00bfea71-e717-4e80-aa17-d0c71b360101"
    Title="Finance Records"
    Description="Finance documents"
    TemplateType="101"
    Url="Lists/FinanceRecords">
</ListInstance>

Instances de liste avec schéma personnalisé

Vous pouvez utiliser une définition de schéma de liste personnalisée afin de définir les champs, les types de contenu et les affichages utilisés dans votre instance de liste. Pour référencer un schéma personnalisé pour l’instance de liste, utilisez l’attribut CustomSchema dans l’élément ListInstance.

Par exemple, vous pouvez définir une instance de liste Documents financiers avec un type de contenu Document financier pouvant encapsuler les exigences en matière de données qui sont communes à tous les documents financiers de l’organisation.

Voici un exemple de définition d’une instance de liste qui utilise un schéma personnalisé :

<ListInstance
    CustomSchema="schema.xml"
    FeatureId="00bfea71-de22-43b2-a848-c05709900100"
    Title="Cost Centers"
    Description="Cost Centers"
    TemplateType="100"
    Url="Lists/CostCenters">
</ListInstance>

Voici la définition de schéma personnalisé qui définit un type de contenu pour l’instance de liste définie précédemment :

<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE" Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
  <MetaData>
    <ContentTypes>
      <ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
    </ContentTypes>
    <Fields></Fields>
    <Views>
      <View BaseViewID="1" Type="HTML" WebPartZoneID="Main" DisplayName="$Resources:core,objectiv_schema_mwsidcamlidC24;" DefaultView="TRUE" MobileView="TRUE" MobileDefaultView="TRUE" SetupPath="pages\viewpage.aspx" ImageUrl="/_layouts/images/generic.png" Url="AllItems.aspx">
        <XslLink Default="TRUE">main.xsl</XslLink>
        <JSLink>clienttemplates.js</JSLink>
        <RowLimit Paged="TRUE">30</RowLimit>
        <Toolbar Type="Standard" />
        <ViewFields>
          <FieldRef Name="LinkTitle"></FieldRef>
          <FieldRef Name="SPFxAmount"></FieldRef>
          <FieldRef Name="SPFxCostCenter"></FieldRef>
        </ViewFields>
        <Query>
          <OrderBy>
            <FieldRef Name="ID" />
          </OrderBy>
        </Query>
      </View>
    </Views>
    <Forms>
      <Form Type="DisplayForm" Url="DispForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
      <Form Type="EditForm" Url="EditForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
      <Form Type="NewForm" Url="NewForm.aspx" SetupPath="pages\form.aspx" WebPartZoneID="Main" />
    </Forms>
  </MetaData>
</List>

Créer des éléments SharePoint dans votre solution

Le package de solution utilise des fonctionnalités SharePoint pour créer un package et mettre en service les éléments SharePoint. Une fonctionnalité est un conteneur qui inclut des éléments SharePoint à mettre en service. Une fonctionnalité contient un fichier Feature.xml, ainsi que des fichiers manifeste d’élément. Ces fichiers XML sont également appelés définitions de fonctionnalité.

En général, un package de solution côté client contient une fonctionnalité. Cette fonctionnalité est activée lorsque la solution est installée sur un site. N’oubliez pas que les administrateurs de site installent votre package de solution et non la fonctionnalité.

Une fonctionnalité est principalement construite à l’aide des fichiers XML ci-après.

Fichier manifeste d’élément

Le fichier manifeste d’élément contient les définitions des éléments SharePoint et est exécuté lors de l’activation de la fonctionnalité. Par exemple, les définitions XML permettant de créer un champ, un type de contenu ou une instance de liste sont contenues dans le manifeste d’élément.

Voici un exemple de fichier manifeste d’élément qui définit un nouveau champ Date/Heure.

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Field ID="{1511BF28-A787-4061-B2E1-71F64CC93FD5}"
            Name="DateOpened"
            DisplayName="Date Opened"
            Type="DateTime"
            Format="DateOnly"
            Required="FALSE"
            Group="Financial Columns">
        <Default>[today]</Default>
    </Field>
  </Elements>

Fichier d’élément

Tous les fichiers pris en charge qui accompagnent le manifeste d’élément sont des fichiers d’élément. Par exemple, le schéma d’instance de liste est un fichier d’élément associé à une instance de liste définie dans un manifeste d’élément.

Voici un exemple de schéma d’instance de liste personnalisé :

<List xmlns:ows="Microsoft SharePoint" Title="Basic List" EnableContentTypes="TRUE" FolderCreation="FALSE"
      Direction="$Resources:Direction;" Url="Lists/Basic List" BaseType="0" xmlns="http://schemas.microsoft.com/sharepoint/">
  <MetaData>
    <ContentTypes>
      <ContentTypeRef ID="0x010042D0C1C200A14B6887742B6344675C8B" />
    </ContentTypes>
  </MetaData>
</List>

Fichier d’actions de mise à niveau

Comme son nom l’indique, il s’agit du fichier qui inclut les actions de mise à niveau lorsque la solution est mise à jour sur le site. Dans le cadre des actions de mise à niveau, l’action peut également indiquer d’inclure des fichiers manifeste d’élément. Par exemple, si la mise à niveau nécessite l’ajout d’un nouveau champ, la définition du champ est disponible en tant que manifeste d’élément et est associée au fichier d’actions de mise à niveau.

Voici un exemple de fichier d’actions de mise à niveau qui applique un fichier manifeste d’élément pendant la mise à niveau :

<ApplyElementManifests>
      <ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>

Configurer la fonctionnalité SharePoint

Pour inclure les fichiers XML, vous devez d’abord définir la configuration de la fonctionnalité dans le fichier de configuration package-solution.json sous le dossier config dans votre projet. Le fichier package-solution.json contient les informations de métadonnées clés sur votre package de solution côté client. Il est référencé lorsque vous exécutez la tâche gulp package-solution qui rassemble votre solution dans un fichier .sppkg.

{
  "solution": {
    "name": "hello-world-client-side-solution",
    "id": "26364618-3056-4b45-98c1-39450adc5723",
    "version": "1.1.0.0",
    "features": [{
      "title": "hello-world-client-side-solution",
      "description": "hello-world-client-side-solution",
      "id": "d46cd9d6-87fc-473b-a4c0-db9ad9162b64",
      "version": "1.1.0.0",
      "assets": {
        "elementManifests": [
          "elements.xml"
        ],
        "elementFiles":[
          "schema.xml"
        ],
        "upgradeActions":[
        	"upgrade-actions-v1.xml"
        ]
      }
    }]
  },
  "paths": {
    "zippedPackage": "solution/hello-world.sppkg"
  }
}

L’objet JSON features contient les métadonnées relatives à la fonctionnalité, comme illustré dans le tableau suivant.

Créer les fichiers XML de fonctionnalité

La chaîne d’outils recherche les fichiers XML tels que définis dans la configuration sous un dossier spécial (sharepoint\assets) dans votre projet de solution côté client.

Les configurations définies dans le fichier package-solution.json permettent de mapper les fichiers XML avec leur fichier XML de fonctionnalité approprié lors de l’exécution de la tâche Gulp package-solution.

Créer un package d’éléments SharePoint

Une fois que vous avez défini votre fonctionnalité dans package-solution.json et que vous avez créé les fichiers XML de fonctionnalité respectifs, vous pouvez utiliser la tâche gulp suivante pour rassembler les éléments SharePoint avec votre package .sppkg.

gulp package-solution

Cette commande permet de créer un package regroupant les manifestes de composant côté client, comme les composants WebPart, ainsi que les fichiers XML de fonctionnalité référencés dans le fichier de configuration package-solution.json.

Mettre à niveau des éléments SharePoint

Vous pouvez inclure les nouveaux éléments SharePoint ou mettre à jour les éléments SharePoint existants lors de la mise à niveau de votre solution côté client. Comme la mise en service d’éléments SharePoint utilise des fonctionnalités, vous utilisez le fichier XML UpgradeActions des fonctionnalités pour définir la liste des actions de mise à niveau.

Le tableau d’objets JSON upgradeActions dans le fichier package-solution.json fait référence aux fichiers XML de fonctionnalité associés aux actions de mise à niveau de votre fonctionnalité. Au moins un fichier d’action de mise à niveau définit le fichier XML manifeste d’élément qui est exécuté lors de la mise à niveau de la fonctionnalité.

Lors de la mise à niveau d’une solution SharePoint Framework, vous devez également mettre à jour les attributs de version pour la solution et la fonctionnalité, dans lesquelles les actions de mise à niveau ont été incluses. Une incrémentation de version de la solution indique aux utilisateurs finals SharePoint qu’une nouvelle version du package est disponible. Une incrémentation de version de l’élément de fonctionnalité garantit que les tâches définies dans les actions de mise à niveau sont traitées dans le cadre de la mise à niveau de la solution.

Voici un exemple de fichier d’action de mise à niveau qui applique un fichier manifeste d’élément pendant la mise à niveau :

<ApplyElementManifests>
      <ElementManifest Location="9c0be970-a4d7-41bb-be21-4a683586db18\elements-v2.xml" />
</ApplyElementManifests>

Voici le fichier element-v2.xml correspondant qui définit un nouveau champ Devise à mettre en service pendant la mise à niveau :

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
    <Field ID="{060E50AC-E9C1-4D3C-B1F9-DE0BCAC300F6}"
            Name="Amount"
            DisplayName="Amount"
            Type="Currency"
            Decimals="2"
            Min="0"
            Required="FALSE"
            Group="Financial Columns" />
</Elements>

Sous-éléments

Les actions de mise à niveau dans les solutions côté client prennent en charge les sous-éléments ci-après.

AddContentTypeField

Permet d’ajouter un nouveau champ à un type de contenu mis en service existant. Permet de propager la modification du type de contenu de site à toutes les listes et les types de contenu enfant dans le site. Par exemple :

<AddContentTypeField
     ContentTypeId="0x010100A6F9CE1AFE2A48f0A3E6CB5BB770B0F7"
     FieldId="{B250DCFD-9310-4e2d-85F2-BE2DA37A57D2}"
     PushDown="TRUE" />

ApplyElementManifests

Permet d’ajouter un nouvel élément à une fonctionnalité existante. Lorsqu’une fonctionnalité est mise à niveau, permet de mettre en service tous les éléments non déclaratifs qui sont référencés dans les manifestes d’élément spécifiés.

VersionRange

Permet de spécifier une plage de versions auxquelles les actions de mise à niveau spécifiées sont appliquées.

Voir aussi

• Didacticiel - Mise en service des composants SharePoint à partir de votre composant WebPart côté client SharePoint
• Présentation de SharePoint Framework