Komponenten vorhandenem Code zuordnen

Entwickler können den Codegenerierungsvorgang anpassen, indem sie anstelle des generierten Codes eine Zuordnung zwischen einem UI-Paket und einer vorhandenen Codekomponente angeben. Dies ist von Vorteil, wenn die vorhandene Implementierung Funktionen enthält, die mit dem generierten Code nicht erreicht werden können, z. B. Animationen oder komplexes Verhalten (z. B. ein Drop-down-Menü).

Entwickler geben mithilfe einer Zuordnungsdatei an, wie Komponenten zugeordnet werden sollen. Eine Zuordnungsdatei gibt dem Codegenerator mindestens an, wie die Zielfunktion erreicht werden kann, damit der richtige Clientcode erstellt werden kann.

Hier ein Beispiel:

In Figma erstellt ein Designer eine Kartenkomponente, die eine Instanz einer Wiedergabeleiste enthält, verpackt beide Komponenten und sendet sie an einen Entwickler.

Wenn der Entwickler die UI-Pakete aus Figma importiert, werden in ui-packages zwei Verzeichnisse erstellt: card und play_bar. Beim Erstellen des Projekts werden zwei kombinierbare Funktionen erstellt: Card und PlayBar. Da Card in Figma eine Instanz von Play Bar enthält, enthält die Card-Funktion im Code in der Regel einen Aufruf an die PlayBar-Funktion.

Die Designer und Entwickler möchten jedoch, dass Card stattdessen eine vorhandene Komponente, MyExistingPlaybar, verwendet, die Funktionen hat, die in Figma schwer zu beschreiben sind. Daher fügt der Entwickler eine Zuordnungsdatei namens play_bar.json hinzu, die das play_bar-UI-Paket MyExistingPlaybar zuordnet:

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

Wenn der Entwickler das Projekt jetzt erstellt, ruft Card MyExistingPlaybar anstelle von PlayBar auf. MyExistingPlaybar muss dieselben Parameter wie PlayBar haben. Es kann jedoch einige Unterschiede geben, wie unten unter Zusätzliche Anweisungen beschrieben.

Zuordnungsdatei

In Ihren Android Studio-Projekten werden Zuordnungsdateien unter ui-package-resources/mappings neben dem Ordner ui-packages hinzugefügt. Relay sucht während des Builds nach Zuordnungsdateien.

Zuordnungsdatei generieren

Relay kann eine Zuordnungsdatei für jedes importierte UI-Paket generieren. Gehen Sie dazu so vor:

1. Klicken Sie mit der rechten Maustaste auf den Paketordner oder eine Datei im Zielordner ui-package. Wählen Sie Zuordnungsdatei generieren aus.

   

2. Konfigurieren Sie im Dialogfeld die folgenden Optionen:

   

   • Dateispeicherort:Hier legen Sie den Speicherort der generierten Zuordnungsdatei fest.

   • Ziel-Kompositelement:Hier legen Sie das benutzerdefinierte Kompositionelement fest, das anstelle des generierten Kompositionelements verwendet wird. Sie können einen vorhandenen Composeable-Codeblock verwenden oder über das Dialogfeld einen neuen erstellen. Wenn Sie ein neues Composeable erstellen, wird ein Composeable mit denselben Parametern erstellt, die im UI-Paket definiert sind.

   • Generierte Datei:Hiermit werden die Optionen generateImplementation und generatePreview in der Zuordnungsdatei festgelegt. Weitere Informationen finden Sie unten im Abschnitt Dateiinhalte zuordnen.

3. Klicken Sie auf Zuordnungsdatei generieren. Im Ordner ui-package-resources/mapping wird eine neue Zuordnungsdatei mit den angegebenen Konfigurationen erstellt.

Sie können das Dialogfeld Zuordnungsdatei generieren auch über die Benutzeroberfläche des Relay-Paketmoduls öffnen. Gehen Sie dazu so vor:

1. Klicken Sie im Zielordner ui-package auf eine beliebige Datei für ein UI-Paket.

2. Wenn das Fenster des Relay-Tools nicht automatisch geöffnet wird, klicken Sie auf das Relay-Symbol, um es zu öffnen.

3. Klicken Sie unter Paketoptionen auf die Schaltfläche Zuordnungsdatei generieren.

   

Name der Zuordnungsdatei

Der Name einer bestimmten Zuordnungsdatei muss mit dem Namen des UI-Paketordners für die Komponente übereinstimmen, die sie ersetzt. play_bar.json ordnet also das UI-Paket im Ordner ui-packages/mappings einer vorhandenen Codekomponente zu.

Dateiinhalte zuordnen

Die Zuordnungsdatei enthält die folgenden Eigenschaften:

• target: (Erforderlich) Der Name Ihrer benutzerdefinierten zusammensetzbaren Funktion. Standardmäßig ist dies der Name der Funktion, die durch generierten Code erstellt wurde.

  "target" : "CustomComposableName"
  

• package (erforderlich): Name des Pakets, in dem sich das benutzerdefinierte Composeable befindet. Standardmäßig ist dies das Paket der Funktion, das durch generierten Code erstellt wurde.

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

• generateImplementation: (Optional) „true“ oder „false“. Wenn diese Option aktiviert ist, wird in der generierten Codedatei trotzdem eine Implementierung dieses UI-Pakets erstellt. Wenn „false“ festgelegt ist, wird die Implementierung nicht erstellt. Standardmäßig ist dies der Fall.

  "generateImplementation" : true
  

• generatePreviews: (Optional) „true“ oder „false“. Wenn diese Option aktiviert ist, wird in der generierten Codedatei eine Vorschau der zugeordneten benutzerdefinierten Komponente erstellt. Wenn „false“ festgelegt ist, wird keine Vorschau erstellt. Standardmäßig ist dies der Fall.

  "generatePreviews" : true
  

Zugeordnete Varianten

Wenn eine Figma-Komponente Varianten hat, enthält das generierte Composable Enum-Parameter, die die Variante codieren (wie im Tutorial Designvarianten bearbeiten beschrieben). Wenn Sie eine Figma-Komponente mit Varianten einem vorhandenen Code zuordnen möchten, muss sie einem Composable zugeordnet werden, das dieselben Parameter wie das generierte Composable verwendet. Für eine Figma-Komponente namens Chip mit einer Variante, deren Property ChipType ist, sieht die generierte Signatur für die Zusammensetzbarkeit so aus:

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

Wenn die Chip-Figma-Komponente einem vorhandenen MyChip-Komposit zugeordnet werden soll, muss die Signatur für MyChip mit der Signatur des generierten Komposits übereinstimmen, sofern keine zusätzlichen Anweisungen angegeben werden. Konzeptionell bedeutet das, dass die vorhandene Codekomponente dieselben Designvarianten wie die Figma-Komponente bietet.

Zusätzliche Anweisungen

Angenommen, die zusammensetzbare Funktion, auf die Sie Ihre Anzeigen ausrichten möchten, hat die folgende Signatur:

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

Sie können der Zuordnungsdatei einen fieldMappings-Block hinzufügen, der sich auf die Zuordnung von Parametern auswirkt. In diesem Fall enthält es eine Zuordnung vom Parameter chipText in Chip zum Parameter description in MyChip.

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

Zu den Typen für den fieldMappings-Block gehören:

• parameter: Ordnet ein UI-Paketfeld einem Codeparameter zu.
  • source: Name des Parameters, wie im UI-Paket angegeben.
  • target: Name des Parameters, wie in der Zielcodekomponente angegeben.
• lambda: Hiermit wird ein Feld des UI-Pakets einem Inhalts-Lambda zugeordnet.
  • source: Name des Parameters, wie im UI-Paket angegeben.
  • target: Name des Parameters, wie in der Zielcodekomponente angegeben.

• modifier: Ordnet ein Feld des UI-Pakets einer Modifikatormethode zu.

  • source: Name des Parameters, wie im UI-Paket angegeben.
  • method: Methode des Modifier-Objekts, die im generierten Code aufgerufen werden soll.
  • parameter: Name des Parameters in der angegebenen Modifizierermethode.
  • library: Der qualifizierte Paketname, der importiert werden soll, um auf die Modifier-Methode zuzugreifen.
  • scope: Einer von zwei Werten, der den Geltungsbereich des Modifiers angibt:
  • any: Der Modus kann in jedem Empfängerbereich verwendet werden.
  • relay: Der Modus muss im Empfängerbereich des RelayContainer-Objekts von Relay verwendet werden.