Manifiesto de componente

  • 10 minutos

Configurar el manifiesto del componente es un paso esencial en la creación de un componente de código. El archivo ControlManifest.Input.xml se inicializa con algunas de sus opciones, como el nombre y el tipo de componente, cuando utiliza el comando pac pcf init. Aún debe personalizar el archivo para especificar las propiedades y recursos que esté utilizando y para habilitar cualquiera de las características del marco que utilice en el componente.

Propiedades de componente

Las propiedades definen un contrato entre el componente de código y la aplicación de hospedaje. Deben abstraer al fabricante de cómo implementa el componente, pero aun así proporcionar capacidades configurables para el fabricante que utiliza el componente. Los siguientes son algunos de los tipos comunes de propiedades que puede necesitar para agregar propiedades a un componente:

  • Permitir que los datos comerciales pasen hacia y desde el componente de código. Por ejemplo, al pasar una geolocalización al componente, el componente podría mostrar un mapa que resalte una ubicación específica.
  • Permitir controlar las características y comportamientos de los componentes. Por ejemplo, con nuestro ejemplo de mapa, se podría agregar una propiedad que indique si el usuario puede acercar o alejar el mapa.
  • Permitir que se personalicen algunos aspectos del estilo del componente. Por ejemplo, en el mapa, el componente podría permitirle personalizar el color del marcador al proporcionar una propiedad que el creador puede configurar.

La siguiente captura de pantalla es un manifiesto de ejemplo que muestra las propiedades definidas para un componente indicador de progreso.

Captura de pantalla que muestra las propiedades codificadas en un componente indicador de progreso

Cuando un creador configura un componente de código, las propiedades definidas en el manifiesto están disponibles para su configuración. Esta imagen muestra cómo se muestra el manifiesto anterior para un componente indicador de progreso a un creador en el diseñador de aplicaciones. Les permite ver las propiedades disponibles y personalizarlas.

Captura de pantalla que muestra las propiedades en una cuadrícula de propiedades para un componente indicador de progreso

Atributos de propiedades

Hay una cantidad de atributos en una propiedad que puede configurar según sus necesidades. Los siguientes son los más comunes que debe tener en cuenta:

  • of-type: este atributo define el tipo de datos de la propiedad. Hay muchos tipos para elegir, como SingleLine.Text o Enum. Algunos tipos, como Enum ofrecen una experiencia de configuración más rica para el creador al proporcionar una lista fija para seleccionar. Otros limitan el contenido de datos según el tipo que puede pasar desde la aplicación de hospedaje. Algunos son más apropiados para el enlace de datos, como Lookup.Simple. Intente siempre evitar cambiar los tipos de datos una vez que haya publicado su componente.

  • usage : este atributo identifica si la propiedad es de entrada, salida o vinculada. Es para aplicaciones basadas en modelo. La opción vinculada espera tener una columna de datos de tabla asociada para proporcionar el valor de los datos.

  • required : indica si se requiere un valor para la propiedad. Si agrega nuevas propiedades después de publicar un componente, piense en el impacto de hacer que la propiedad sea obligatoria en las aplicaciones existentes que usan el componente.

  • default-value : este atributo tiene el valor predeterminado proporcionado al componente. En aplicaciones basadas en modelo, esta propiedad solo se permite en propiedades con un tipo de entrada de uso. Proporcionar un valor predeterminado puede ser útil para que los creadores tengan una idea de cómo pretenden establecer la propiedad. Cuando agrega una nueva propiedad a un componente existente, el valor predeterminado a menudo se establece en el valor que utilizó el componente antes de que se volviera configurable a través de la propiedad.

Al evaluar las propiedades que planea agregar, hay algunos elementos que debe tener en cuenta:

  • Evite tener demasiadas propiedades en su componente, ya que el fabricante tendría que navegar por una larga lista de opciones.
  • Utilice nombres para propiedades que sean claras. Cuando sea posible, proporcione suficientes detalles en la descripción para informar al fabricante sobre su propósito.
  • Piense en agregar algunas propiedades para permitir a los fabricantes diseñar su componente. Estas propiedades pueden ser importantes cuando se utiliza el componente en una amplia variedad de aplicaciones.
  • Evite cambiar el nombre o eliminar propiedades después de publicar su componente, ya que supondrán un cambio importante para las aplicaciones de consumo existentes.

Recursos de componentes

El nodo de recursos en el manifiesto identifica los archivos de recursos que requiere el componente. En un componente nuevo, inicialmente solo contiene el elemento necesario code. Puede agregar otros recursos de los que dependa su componente. Los más comunes son css y resx.

El elemento css le permite identificar un archivo CSS (hoja de estilo CSS) que debe cargarse. Opcionalmente, puede especificar un orden para cargarlos si tiene varios. El siguiente código es un ejemplo de cargar dos archivos CSS.

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

El nodo resx en el manifiesto identifica el archivo utilizado para administrar las cadenas localizadas que define. Si va a localizar, es más fácil agregarlo en un nuevo componente y actualizarlo a medida que agrega propiedades. Las propiedades en el valor de manifiesto de los atributos display-name-key y description-key se utilizan para buscar el valor localizado si se puede ubicar en un archivo de recursos resx.

Por ejemplo, revise la siguiente definición de propiedad y cómo se definen esos atributos.

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

En un archivo resx, que es un archivo XML que utiliza el Microsoft ResX Schema, definiría los siguientes elementos de datos para las claves de propiedad.

<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>

Después, crearía un archivo resx aparte para cada idioma que admita.

A continuación, en su nodo de recursos de manifiesto agregaría los siguientes nodos resx para cargar los archivos cuando se utiliza el componente.

<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" />

Uso de características de componentes

Las características de dispositivo, utilidad y WebAPI del marco están disponibles para que las utilicen los componentes que utiliza en una aplicación basada en modelo. Para usar una de estas características, debe declararla en el manifiesto en el nodo de uso de características mediante la adición de un nodo uses-feature. El siguiente código es un ejemplo de cómo habilitar el uso de la característica WebAPI.

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