Manifeste de composant

  • 10 minutes

La configuration du manifeste du composant est une étape essentielle dans la création d’un composant de code. Le fichier ControlManifest.Input.xml est initialisé avec certains de vos choix, comme le nom et le type de composant, lorsque vous utilisez la commande pac pcf init. Vous devez toujours personnaliser le fichier pour spécifier les propriétés et ressources que vous utilisez et activer les fonctionnalités de l’infrastructure que vous utilisez dans le composant.

Propriétés du composant

Les propriétés définissent un contrat entre le composant de code et l’application d’hébergement. Elles doivent soustraire le créateur de la manière dont vous implémentez le composant, tout en fournissant des fonctionnalités configurables au créateur utilisant le composant. Voici certains des types courants de propriétés dont vous pourriez avoir besoin pour ajouter des propriétés à un composant :

  • Autoriser la transmission de données métier vers et depuis le composant de code : par exemple, en transmettant une géolocalisation au composant, celui-ci pourrait afficher une carte mettant en évidence un emplacement spécifique.
  • Autoriser le contrôle des fonctionnalités et comportements du composant : par exemple, à l’aide de notre exemple de carte, une propriété pourrait être ajoutée pour indiquer si l’utilisateur peut effectuer un zoom avant ou arrière sur la carte.
  • Autoriser la personnalisation de certains aspects du style du composant : par exemple, sur la carte, le composant pourrait vous permettre de personnaliser la couleur des épingles en fournissant une propriété que le créateur peut configurer.

La capture d’écran suivante est un exemple de manifeste illustrant les propriétés définies pour un composant d’indicateur de progression :

Capture d’écran illustrant les propriétés codées dans un composant d’indicateur de progression.

Lorsqu’un créateur configure un composant de code, les propriétés définies dans le manifeste sont configurables. Cette image montre comment le manifeste ci-dessus pour un composant d’indicateur de progression est présenté à un créateur dans le concepteur d’applications. Ainsi, il peut voir les propriétés disponibles et les personnaliser.

Capture d’écran illustrant les propriétés d’une grille de propriétés pour un composant d’indicateur de progression.

Attributs de propriété

Vous pouvez configurer plusieurs attributs d’une propriété en fonction de vos besoins. Voici les plus courants que vous devriez prendre en compte :

  • of-type : cet attribut définit le type de données de la propriété. Vous pouvez faire votre choix parmi de nombreux types, par exemple SingleLine.Text et Enum. Certains types tels qu’Enum offrent une expérience de configuration plus riche au créateur en fournissant une liste fixe dans laquelle effectuer une sélection. D’autres limitent le contenu des données en fonction du type pouvant être transmis depuis l’application d’hébergement. Certains sont plus appropriés pour la liaison de données, comme Lookup.Simple. Essayez toujours d’éviter de modifier les types de données après avoir publié votre composant.

  • usage : cet attribut identifie si la propriété est d’entrée, de sortie ou liée. Ceci concerne les applications pilotées par modèle. L’option liée s’attend à ce qu’une colonne de données de table soit associée pour fournir la valeur des données.

  • required : indique si une valeur pour la propriété est requise. Si vous ajoutez de nouvelles propriétés après la publication d’un composant, tenez compte de l’impact de rendre la propriété obligatoire sur les applications existantes qui utilisent le composant.

  • default-value : cet attribut comporte la valeur par défaut fournie au composant. Dans les applications pilotées par modèle, cette propriété n’est autorisée que sur les propriétés avec un type d’utilisation entrée. Fournir une valeur par défaut peut être utile aux créateurs pour donner une idée de la façon dont vous souhaitez définir la propriété. Lorsque vous ajoutez une nouvelle propriété à un composant existant, la valeur par défaut est souvent définie sur la valeur utilisée par le composant avant qu’il ne devienne configurable au moyen de la propriété.

Lorsque vous évaluez les propriétés que vous envisagez d’ajouter, voici quelques éléments à prendre en compte :

  • Évitez d’avoir trop de propriétés sur votre composant, ce qui obligerait le créateur à parcourir une longue liste d’options.
  • Utilisez des noms clairs pour les propriétés. Dans la mesure du possible, fournissez suffisamment de détails dans la description pour informer le créateur de son objectif.
  • Envisagez d’ajouter quelques propriétés pour permettre aux créateurs d’appliquer un style à votre composant. Ces propriétés peuvent être importantes lorsque vous pouvez utiliser le composant dans un large éventail d’applications.
  • Évitez de renommer ou supprimer des propriétés après avoir publié votre composant, car cela constituerait un changement cassant pour les applications consommatrices existantes.

Ressources de composant

Le nœud de ressource dans le manifeste identifie les fichiers de ressource requis par le composant. Dans un nouveau composant, celui-ci ne comporte initialement que l’élément de code requis. Vous pouvez ajouter d’autres ressources dont dépend votre composant. Les plus courants sont css et resx.

L’élément css vous permet d’identifier un fichier CSS (feuille de style en cascade) à charger. Vous pouvez éventuellement spécifier un ordre dans lequel les charger si vous en avez plusieurs. Le code suivant est un exemple de chargement de deux fichiers CSS :

<css path="css/ComponentCommon.css" order="1" />
<css path="css/ProgressIndicator.css" order="2" />

Le nœud resx dans le manifeste identifie le fichier permettant de gérer les chaînes localisées que vous définissez. Si vous envisagez de localiser, il est plus facile d’ajouter ceci à un nouveau composant et d’effectuer une mise à jour à mesure que vous ajoutez des propriétés. Les propriétés de la valeur de manifeste des attributs display-name-key et description-key permettent de rechercher la valeur localisée si elle peut être localisée dans un fichier de ressource resx chargé.

Par exemple, examinez la définition de propriété suivante et la façon dont ces attributs sont définis :

 <property name="PercentComplete" description-key="PercentComplete_Desc" display-name-key="PercentComplete" required="true" usage="input" of-type="Whole.None" default-value="40" />

Dans un fichier resx, à savoir un fichier XML qui utilise Microsoft ResX Schema, vous devez définir les éléments de données suivants pour les clés de propriété :

<data name="PercentComplete" xml:space="preserve">
        <value>Percent Complete</value>
</data>
<data name="PercentComplete_Desc" xml:space="preserve">
        <value>Percent Complete is the current value for how much has been completed.</value>
</data>

Vous créeriez alors un fichier resx distinct pour chaque langue prise en charge.

Ensuite, dans votre nœud de ressource de manifeste, vous ajouteriez les nœuds resx suivants pour charger les fichiers lorsque le composant est utilisé :

<resx path="strings/ProgressIndicator.1033.resx" version="1.0.0" />
<resx path="strings/ProgressIndicator.1035.resx" version="1.0.0" />
<resx path="strings/ProgressIndicator.3082.resx" version="1.0.0" />

Utilisation des fonctionnalités de composant

Les fonctionnalités device, utility et WebAPI de l’infrastructure peuvent être utilisées par les composants que vous utilisez dans une application pilotée par modèle. Pour utiliser l’une de ces fonctionnalités, vous devez la déclarer dans le manifeste dans le nœud feature-usage en ajoutant un nœud uses-feature. Le code suivant est un exemple d’activation de l’utilisation de la fonctionnalité WebAPI :

<feature-usage>
    <uses-feature name="WebAPI" required="true" />
 </feature-usage>