Asigna componentes al código existente

Los desarrolladores pueden personalizar el proceso de generación de código si brindan una asignación entre un paquete de IU y un componente de código existente, en lugar del código generado. Esto es beneficioso cuando la implementación existente tiene funciones que no se pueden lograr con el código generado, como animación o comportamiento complejo (como un menú desplegable).

Los desarrolladores especifican cómo asignar componentes mediante un archivo de asignación. Un archivo de asignación le indica al generador de códigos, como mínimo, cómo alcanzar la función de componibilidad objetivo para que se pueda crear el código de cliente correcto.

A continuación, se muestra un ejemplo:

En Figma, un diseñador crea un componente Card que contiene una instancia de un componente Play Bar, empaqueta ambos componentes y los envía a un desarrollador.

Cuando el desarrollador importa los paquetes de IU desde Figma, se crean dos directorios en ui-packages: card y play_bar. Cuando compilan el proyecto, se crean dos funciones de componibilidad: Card y PlayBar. Por lo general, debido a que Card contiene una instancia de Play Bar en Figma, en el código, la función de componibilidad Card contiene una llamada al elemento componible PlayBar.

Sin embargo, el diseñador y el desarrollador quieren que Card use un elemento componible MyExistingPlaybar existente, que tiene una funcionalidad difícil de describir en Figma. Por lo tanto, el desarrollador agrega un archivo de asignación llamado play_bar.json que asigna el paquete de IU play_bar a MyExistingPlaybar:

{
    "target": "MyExistingPlaybar",
    "package": "com.example.myApp"
}

Ahora, cuando el desarrollador compila el proyecto, Card llama a MyExistingPlaybar en lugar de PlayBar. Ten en cuenta que MyExistingPlaybar debe tener los mismos parámetros que PlayBar (aunque puede haber algunas diferencias, como se describe en Directivas adicionales a continuación).

Archivo de asignación

En tus proyectos de Android Studio, los archivos de asignación se agregan en ui-package-resources/mappings junto a la carpeta ui-packages. Relay busca archivos de asignación durante la compilación.

Genera un archivo de asignación

Relay puede generar un archivo de asignación para cualquier paquete de IU importado. Para ello, sigue estos pasos:

1. Haz clic con el botón derecho en la carpeta del paquete o en cualquier archivo dentro de la carpeta ui-package objetivo. Selecciona Generate mapping file.

   

2. Configura las siguientes opciones en el diálogo:

   

   • Ubicación del archivo: Establece la ubicación del archivo de asignación generado.

   • Elemento componible de destino: Establece el elemento componible personalizado que se usa en lugar del elemento componible generado. Tienes la opción de usar un elemento componible existente o crear uno nuevo desde el diálogo. Cuando creas un elemento componible nuevo, se crea uno con los mismos parámetros que se definen en el paquete de la IU.

   • Archivo generado: Establece las opciones generateImplementation y generatePreview en el archivo de asignación. Consulta Cómo asignar el contenido de un archivo a continuación para obtener más detalles.

3. Haz clic en Generate mapping file. Se crea un nuevo archivo de asignación dentro de la carpeta ui-package-resources/mapping con las configuraciones especificadas.

También puedes abrir el diálogo Generate mapping file desde la IU del módulo del paquete de Relay siguiendo estos pasos:

1. Haz clic en cualquier archivo de un paquete de IU dentro de la carpeta ui-package de destino.

2. Si la ventana de la herramienta de retransmisión no se abre automáticamente, haz clic en el ícono de retransmisión para abrirla.

3. Haz clic en el botón Generate mapping file en Package Options.

   

Nombre del archivo de asignación

El nombre de un archivo de asignación determinado debe coincidir con el nombre de la carpeta del paquete de IU para el componente que reemplaza. Por lo tanto, play_bar.json asigna el paquete de IU de la carpeta ui-packages/mappings a un componente de código existente.

Cómo asignar el contenido de un archivo

El archivo de asignación contiene las siguientes propiedades:

• target: (Obligatorio) Es el nombre de tu función de componibilidad personalizada. De forma predeterminada, este es el nombre de la función creada por el código generado.

  "target" : "CustomComposableName"
  

• package: (Obligatorio) Es el nombre del paquete en el que se encuentra tu elemento componible personalizado. De forma predeterminada, este es el paquete de la función que crea el código generado.

  "package" : "com.example.podcastapp.ui.components"
  

• generateImplementation: (Opcional) Es verdadero o falso. Si es verdadero, se crea una implementación de este paquete de IU en el archivo de código generado. Si es falso, no se crea la implementación. De forma predeterminada, este valor es verdadero.

  "generateImplementation" : true
  

• generatePreviews: (opcional) Es verdadero o falso. Si es verdadero, se crea una vista previa del componente personalizado asignado en el archivo de código generado. Si es falso, no se crea ninguna vista previa. De forma predeterminada, este valor es verdadero.

  "generatePreviews" : true
  

Variantes asignadas

Si un componente de Figma tiene variantes, el elemento componible generado contiene parámetros de enum que codifican la variante (como se describe en el instructivo Cómo manejar variantes de diseño). Si deseas asignar un componente de Figma con variantes al código existente, debe asignarse a un elemento componible que tome los mismos parámetros que el elemento componible generado. Por ejemplo, para un componente de Figma llamado Chip con una variante cuya propiedad es ChipType, la firma del elemento componible generado de Chip se ve de la siguiente manera:

@Composable
fun Chip(
    modifier: Modifier = Modifier,
    chipType: ChipType = ChipType.Red,
    chipText: String
) { ... }

Si deseas que el componente Chip de Figma se asigne a un elemento componible MyChip existente, la firma de MyChip debe tener la misma firma que el elemento componible generado (suponiendo que no se especifiquen directivas adicionales). Conceptualmente, esto sugiere que el componente de código existente es capaz de las mismas variantes de diseño que el componente de Figma.

Directivas adicionales

Por ejemplo, si la función de componibilidad a la que deseas orientarte tiene la siguiente firma:

@Composable
fun MyChip(
    modifier: Modifier = Modifier,
    chipType: ChipType = ChipType.Red,
    description: String  // instead of chipText
) { ... }

Puedes agregar un bloque fieldMappings al archivo de asignación que afecte la forma en que se asignan los parámetros. En este caso, contiene una asignación del parámetro chipText en Chip al parámetro description en MyChip.

{
    "target": "MyChip",
    "package": "com.example.myApp",
    "fieldMappings": [
        {
            "type": "parameter",
            "source": "chipText",
            "target": "description"
        }
    ]
}

Los tipos para el bloque fieldMappings incluyen los siguientes:

• parameter: Asigna un campo de paquete de IU a un parámetro de código.
  • source: Es el nombre del parámetro, como se especifica en el paquete de IU.
  • target: Es el nombre del parámetro, como se especifica en el componente del código de destino.
• lambda: Asigna un campo de paquete de IU a una lambda de contenido.
  • source: Es el nombre del parámetro, como se especifica en el paquete de IU.
  • target: Es el nombre del parámetro, como se especifica en el componente del código de destino.

• modifier: Asigna un campo de paquete de IU a un método modifier.

  • source: Es el nombre del parámetro, como se especifica en el paquete de IU.
  • method: Es el método del objeto Modifier que se debe invocar en el código generado.
  • parameter: Es el nombre del parámetro dentro del método Modifier especificado.
  • library: Es el nombre del paquete calificado que se importará para acceder al método Modifier.
  • scope: Es uno de dos valores para indicar el alcance del Modifier:
  • any: El modificador se puede usar en cualquier alcance del receptor.
  • relay: El modificador debe usarse en el alcance del receptor del objeto RelayContainer de Relay.