Registrar un control personalizado

Objetivo

Instalar un control personalizado en un entorno cargando su paquete, para poder montarlo en un campo de un formulario basado en modelo.

¿Busca cómo construir el control en lugar de instalarlo? Esta página da por hecho que el control ya existe y está empaquetado. Escribirlo (el contrato fijo de propiedades, los tipos de campo a los que puede sustituir, los estados de valor que debe gestionar, las pruebas y el empaquetado) se explica en Crear un control personalizado.

Requisitos previos

• Ha iniciado sesión en el Centro de control de administración como administrador de la plataforma.
• Ya existen un editor y una solución propiedad de ese editor.
• El entorno en el que instala el control está activo.
• Tiene el paquete del control: el .zip que genera npm run pack en el propio proyecto del control. Normalmente se escribe en la carpeta package/ de ese proyecto y lleva el nombre del control, por ejemplo par_signature_pad-1.2.3.zip.

Pasos

1. Elija el entorno en el que se debe instalar el control, con el selector de la barra superior.
2. Abra Soluciones y después la solución a la que pertenece el control.
3. Seleccione Controles personalizados en la navegación de la izquierda de la solución (o la tarjeta Controles personalizados en la vista general de la solución). La página enumera los controles que esta solución ya ha instalado en el entorno seleccionado.
4. Seleccione Nuevo. Se abre un panel a un lado de la pantalla.
5. Elija el archivo del paquete del control.
6. Seleccione Registrar control personalizado. El control aparece en la lista de esa solución y ese entorno, en la vista general de la solución bajo Controles personalizados y en la paleta de campos del diseñador de formularios.

Ese es todo el formulario. No hay nada más que rellenar porque el paquete ya lo dice todo: el nombre lógico y el nombre para mostrar del control, el ámbito de Module Federation y el módulo expuesto que usó realmente su compilación, el archivo de entrada que hay que servir y los tipos de campo a los que puede sustituir. Los dos últimos antes se copiaban a mano de la configuración de un empaquetador, y equivocarse en cualquiera de ellos producía un único síntoma (el control simplemente no se cargaba) sin nada que dijera cuál de los dos estaba mal.

Volver a cargarlo sustituye la compilación instalada. Es el ciclo normal mientras trabaja en un control: cambiarlo, ejecutar npm run pack y volver a cargarlo. No tiene que quitar antes el registro anterior. La columna Versión muestra qué compilación está instalada, así que puede comprobar que lo que se ejecuta es lo último que empaquetó.

Para quitar un control, marque su fila y seleccione Quitar. Esto lo desinstala del entorno y elimina su paquete guardado; la solución conserva la referencia al componente, porque puede que otros entornos todavía tengan el control instalado.

Dónde vive el código del control

La plataforma guarda los bytes del paquete y los sirve desde su propia dirección. No se obtiene nada de un host externo, así que:

• la solución es autónoma: al exportarla se lleva el código del control, y al importarla en Prueba o en Producción se instala un control que funciona, no un puntero al lugar donde se construyó;
• no hay ninguna URL que agregar a la lista de permitidos, ni ninguna URL que quede obsoleta.

El código de un control no tiene que cargarse como recursos web. Los recursos web son para archivos independientes que usted crea y a los que hace referencia por su nombre (una hoja de estilos, una imagen, un script), no para la salida de compilación de un control.

Qué ocurre entre bastidores

El archivo se comprueba antes de guardar nada: su tamaño, cuántos archivos contiene y cuánto ocupa una vez descomprimido, que ningún archivo de su interior nombre una ruta fuera de su propia carpeta, que todos los archivos sean de un tipo que la plataforma sirve y que su manifiesto coincida con el esquema de paquete publicado. Después se comprueba el nombre lógico del control contra el prefijo del editor propietario.

El paquete se guarda completo y se descomprime la primera vez que se solicita realmente el control. Por eso un control sigue funcionando después de reiniciar la plataforma, y por eso funciona igual en todos los servidores: el paquete guardado es la copia real, y los archivos descomprimidos no son más que una caché que se reconstruye sola.

Instalar el control en un entorno no lo instala en ningún otro; viaja cuando su solución se exporta e importa.

Solución de problemas

• «El paquete no tiene un 'parsware.json' en su raíz». El archivo cargado es una salida de compilación sin más, no un paquete. Genérelo con npm run pack en el proyecto del control.
• «El control personalizado … debe empezar por el prefijo del editor …_». El logicalName del package.json del control no empieza por el prefijo del editor propietario. Cámbielo ahí y vuelva a empaquetar.
• «El paquete contiene … archivos; el máximo es …». Casi siempre es una carpeta node_modules que acabó dentro del archivo. Empaquete la salida de compilación, no el proyecto.
• «El control personalizado … ya está instalado en este entorno por otra solución». El nombre lógico está ocupado. Cambie el nombre del control o quite el otro registro.
• «El entorno … no está activo». Espere a que el entorno termine de aprovisionarse o elija otro entorno.

Mientras escribe el control

Cargar un paquete por cada cambio es un ciclo lento. En un entorno de desarrollo, Nuevo ofrece una segunda opción, Usar un servidor de desarrollo en ejecución: escriba la dirección que muestra npm run dev y seleccione Registrar control personalizado. El nombre del control y su configuración de federation se leen del servidor de desarrollo, y los formularios cargan el control desde él, así que un cambio guardado se ve la próxima vez que se abre un formulario. La columna Versión dice Hospedado (desarrollo) mientras esté registrado así.

• Si el control ya está instalado, quítelo primero. Un servidor de desarrollo se registra con el nombre lógico del control, así que el formulario al que lo vinculó lo sigue usando.
• Cuando termine, cargue el paquete. Reemplaza el registro del servidor de desarrollo, y la columna Versión vuelve a mostrar la compilación.

La opción no aparece fuera de un entorno de desarrollo: un control registrado así no tiene paquete, de modo que su código no viajaría con la solución. Cómo preparar el proyecto del control para ello está en Crear un control personalizado.

Escenarios relacionados

• Crear un control personalizado.
• Enlazar un control personalizado a un campo.
• Registrar una aplicación React personalizada.
• Crear una solución.