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ódigo, como mínimo, cómo alcanzar la función de componibilidad de destino para que se pueda crear el código de cliente correcto.

Diagrama de descripción general de los componentes asignados

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

Archivo de asignación en la vista Project

Genera un archivo de asignación

Relay puede generar un archivo de asignación para cualquier paquete de IU importado. 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 de destino. Selecciona Generate mapping file.

    Cómo generar la asignación del archivo de asignación

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

    Diálogo para generar archivos de asignación

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

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

    • Generated file:Configura las opciones generateImplementation y generatePreview en el archivo de asignación. Consulta Contenido del archivo de asignación a continuación para obtener más detalles.

  3. Haz clic en Generar archivo de asignación. Se crea un archivo de asignación nuevo 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 mediante 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 herramientas Relay no se abre automáticamente, haz clic en el ícono Relay para abrirla.

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

    Cómo generar la asignación del archivo de asignación

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.

Contenido del archivo de asignación

El archivo de asignación contiene las siguientes propiedades:

  • target: (obligatorio): Es el nombre de la 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. Según la configuración predeterminada, este es el paquete de la función creado por el código generado.

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

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

    "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 creará una vista previa. Este es el valor predeterminado de forma predeterminada.

    "generatePreviews" : true

Variantes asignadas

Si un componente de Figma tiene variantes, el elemento componible generado contendrá parámetros de enumeración 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, debes asignarlo 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 componible generada por Chip se ve de la siguiente manera:

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

Si quieres que el componente Chip Figma se asigne a un elemento componible MyChip existente, la firma de MyChip debe tener la misma firma que el elemento 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 orientar 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 afecta 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 modificador.

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