Inscrire un contrôle personnalisé

Objectif

Installer un contrôle personnalisé dans un environnement en téléversant son paquet, afin qu’il puisse être monté sur un champ de formulaire piloté par modèle.

Vous cherchez comment construire le contrôle plutôt que l’installer ? Cette page suppose que le contrôle existe déjà et qu’il a été empaqueté. Son écriture — le contrat de props fixe, les types de champ qu’il peut remplacer, les états de valeur qu’il doit gérer, les tests et l’empaquetage — est décrite dans Construire un contrôle personnalisé.

Prérequis

• Vous êtes connecté au Centre de contrôle d’administration en tant qu’administrateur de la plateforme.
• Un éditeur et une solution appartenant à cet éditeur existent déjà.
• L’environnement dans lequel vous installez le contrôle est actif.
• Vous disposez du paquet du contrôle — le .zip produit par npm run pack dans le projet du contrôle. Il est généralement écrit dans le dossier package/ de ce projet et porte le nom du contrôle, par exemple par_signature_pad-1.2.3.zip.

Étapes

1. Choisissez l’environnement dans lequel installer le contrôle, à l’aide du sélecteur de la barre supérieure.
2. Ouvrez Solutions, puis la solution à laquelle appartient le contrôle.
3. Sélectionnez Contrôles personnalisés dans la navigation de gauche de la solution (ou la carte Contrôles personnalisés de la vue d’ensemble de la solution). La page liste les contrôles que cette solution a déjà installés dans l’environnement sélectionné.
4. Sélectionnez Nouveau. Un panneau s’ouvre sur le côté de l’écran.
5. Choisissez le fichier de paquet du contrôle.
6. Sélectionnez Inscrire le contrôle personnalisé. Le contrôle apparaît dans la liste de cette solution et de cet environnement, dans la vue d’ensemble de la solution sous Contrôles personnalisés, et dans la palette de champs du concepteur de formulaires.

C’est tout le formulaire. Il n’y a rien d’autre à remplir, car le paquet dit déjà tout : le nom logique et le nom d’affichage du contrôle, la portée Module Federation et le module exposé réellement utilisés par sa construction, le fichier d’entrée à servir et les types de champ qu’il peut remplacer. Ces deux dernières informations étaient autrefois recopiées à la main depuis une configuration de bundler, et une erreur sur l’une ou l’autre produisait un seul symptôme — le contrôle ne se chargeait tout simplement pas — sans rien pour dire laquelle des deux était fausse.

Téléverser à nouveau remplace la version installée. C’est la boucle normale pendant le travail sur un contrôle : le modifier, exécuter npm run pack, le téléverser à nouveau. Inutile de supprimer d’abord l’ancienne inscription. La colonne Version indique quelle construction est installée, ce qui vous permet de vérifier que ce qui tourne est bien ce que vous avez empaqueté en dernier.

Pour retirer un contrôle, cochez sa ligne et sélectionnez Retirer. Il est alors désinstallé de l’environnement et son paquet stocké est supprimé ; la solution conserve sa référence au composant, car d’autres environnements peuvent encore avoir le contrôle installé.

Où vit le code du contrôle

Les octets du paquet sont stockés par la plateforme et servis depuis sa propre adresse. Rien n’est récupéré sur un hôte externe, donc :

• la solution est autonome — l’exporter emporte le code du contrôle, et l’importer en Test ou en Production installe un contrôle fonctionnel plutôt qu’un pointeur vers l’endroit où il a été construit ;
• il n’y a aucune URL à autoriser, et aucune URL qui puisse devenir obsolète.

Le code d’un contrôle n’a pas besoin d’être téléversé sous forme de ressources web. Les ressources web servent aux fichiers autonomes que vous créez et référencez par leur nom — une feuille de style, une image, un script — et non au résultat de la construction d’un contrôle.

Ce qui se passe en coulisses

L’archive est vérifiée avant tout stockage : sa taille, le nombre de fichiers qu’elle contient et la taille qu’elle atteint une fois décompressée, qu’aucun fichier ne désigne un chemin hors de son propre dossier, que chaque fichier est d’un type servi par la plateforme, et que son manifeste correspond au schéma de paquet publié. Le nom logique du contrôle est ensuite comparé au préfixe de l’éditeur propriétaire.

Le paquet est stocké en entier et décompressé la première fois que le contrôle est réellement demandé. C’est pourquoi un contrôle continue de fonctionner après un redémarrage de la plateforme, et fonctionne de la même façon sur chaque serveur : le paquet stocké est la copie de référence, et les fichiers décompressés ne sont qu’un cache qui se reconstruit tout seul.

Installer le contrôle dans un environnement ne l’installe dans aucun autre ; il voyage lorsque sa solution est exportée puis importée.

Dépannage

• « The package has no 'parsware.json' at its root. » — le fichier téléversé est un simple résultat de construction et non un paquet. Construisez-le avec npm run pack dans le projet du contrôle.
• « Custom control … must start with the publisher prefix …_. » — le logicalName du package.json du contrôle ne commence pas par le préfixe de l’éditeur propriétaire. Modifiez-le à cet endroit et réempaquetez.
• « The package holds … files; the maximum is … » — presque toujours un dossier node_modules qui s’est retrouvé dans l’archive. Empaquetez le résultat de la construction, pas le projet.
• « Custom control … is already installed in this environment by another solution. » — le nom logique est déjà pris. Renommez le contrôle, ou supprimez l’autre inscription.
• « Environment … is not active. » — attendez que l’environnement ait fini d’être provisionné, ou choisissez un autre environnement.

Pendant l’écriture du contrôle

Charger un package à chaque modification est une boucle lente. Dans un environnement de développement, Nouveau propose un second choix, Utiliser un serveur de développement en cours d’exécution : saisissez l’adresse qu’affiche npm run dev et sélectionnez Inscrire un contrôle personnalisé. Le nom du contrôle et ses réglages de federation sont lus sur le serveur de développement, et les formulaires y chargent le contrôle : une modification enregistrée est visible à la prochaine ouverture d’un formulaire. La colonne Version indique Hébergé (développement) tant qu’il est enregistré ainsi.

• Si le contrôle est déjà installé, retirez-le d’abord. Un serveur de développement s’enregistre sous le nom logique du contrôle, le formulaire auquel vous l’avez lié continue donc de l’utiliser.
• Quand vous avez fini, chargez le package. Il remplace l’enregistrement du serveur de développement, et la colonne Version affiche de nouveau le build.

Ce choix n’apparaît pas hors d’un environnement de développement : un contrôle enregistré ainsi n’a pas de package, son code ne voyagerait donc pas avec la solution. La préparation du projet du contrôle est décrite dans Créer un contrôle personnalisé.

Scénarios associés

• Construire un contrôle personnalisé.
• Lier un contrôle personnalisé à un champ.
• Inscrire une application React personnalisée.
• Créer une solution.