Bileşenleri mevcut kodla eşleme

Geliştiriciler, oluşturulan kod yerine Kullanıcı Arayüzü Paketi ile mevcut bir kod bileşeni arasında eşleme sağlayarak kod oluşturma sürecini özelleştirebilir. Bu yöntem, mevcut uygulamada, oluşturulan kodla animasyon veya karmaşık davranış gibi (açılır menü gibi) özellikler bulunduğunda yararlıdır.

Geliştiriciler, bileşenlerin eşleme dosyası kullanarak nasıl eşleneceğini belirtir. Eşleme dosyası, kod oluşturucuya en azından doğru istemci kodunun oluşturulabilmesi için hedef composable işlevine nasıl ulaşılacağını bildirir.

Eşlenen bileşene genel bakış diyagramı

Örnek:

Figma'da tasarımcı, Play Bar bileşeninin bir örneğini içeren bir Kart bileşeni oluşturur, her iki bileşeni de paketler ve geliştiriciye gönderir.

Geliştirici, Kullanıcı Arayüzü Paketlerini Figma'dan içe aktardığında ui-packages ürününde iki dizin oluşturulur: card ve play_bar. Proje derlendiğinde iki composable işlev oluşturulur: Card ve PlayBar. Genellikle Card Figma'da bir Play Bar örneği içerdiğinden, kodda Card composable işlevi PlayBar composable'a bir çağrı içerir.

Ancak tasarımcı ve geliştirici Card ürününün, Figma'da tarif edilmesi zor bir işleve sahip mevcut bircomposable (MyExistingPlaybar) kullanmasını istiyor. Bu nedenle geliştirici, play_bar Kullanıcı Arayüzü Paketi'ni MyExistingPlaybar ile eşleyen play_bar.json adlı bir eşleme dosyası ekler:

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

Artık geliştirici projeyi derlerken Card, PlayBar yerine MyExistingPlaybar yöntemini çağırır. MyExistingPlaybar parametresinin, PlayBar ile aynı parametrelere sahip olması gerektiğini unutmayın (ancak aşağıdaki Ek Yönergeler'de açıklanan birkaç farklılıklar olabilir).

Eşleme dosyası

Eşleme dosyaları, Android Studio projelerinizde ui-packages klasörünün yanındaki ui-package-resources/mappings altına eklenir. Relay, derleme sırasında eşleme dosyalarını arar.

Proje görünümündeki eşleme dosyası

Eşleme dosyası oluşturma

Geçiş, içe aktarılan herhangi bir Kullanıcı Arayüzü Paketi için eşleme dosyası oluşturabilir. Şu adımları uygulayın:

  1. Paket klasörünü veya hedef ui-package klasöründeki herhangi bir dosyayı sağ tıklayın. Eşleme dosyası oluştur'u seçin.

    Eşleme dosyası uygunluğu oluşturun

  2. İletişim kutusunda şu seçenekleri yapılandırın:

    Eşleme dosyaları oluşturma iletişim kutusu

    • Dosya konumu: Oluşturulan eşleme dosyasının konumunu ayarlar.

    • Target composable: Oluşturulan composable yerine kullanılan özel composable'ı ayarlar. İletişim kutusundan mevcut bir composable'ı kullanabilir veya yeni bir tane oluşturabilirsiniz. Yeni bir composable oluşturmak, UI paketinde tanımlanan parametrelere sahip bir composable oluşturur.

    • Oluşturulan dosya: Eşleme dosyasında generateImplementation ve generatePreview seçeneklerini ayarlar. Daha fazla ayrıntı için aşağıdaki Dosya içeriğini eşleme bölümüne bakın.

  3. Eşleme dosyası oluştur'u tıklayın. ui-package-resources/mapping klasörünün içinde belirtilen yapılandırmalarla yeni bir eşleme dosyası oluşturulur.

Aşağıdaki adımları uygulayarak Geçiş paketi modülü kullanıcı arayüzünden Eşleme dosyası oluştur iletişim kutusunu açabilirsiniz:

  1. Hedef ui-package klasöründeki herhangi bir kullanıcı arayüzü paketine ait dosyayı tıklayın.

  2. Geçiş aracı penceresi otomatik olarak açılmazsa pencereyi açmak için Geçiş simgesini tıklayın.

  3. Paket Seçenekleri'nin altındaki Eşleme dosyası oluştur düğmesini tıklayın.

    Eşleme dosyası uygunluğu oluşturun

Eşleme dosyası adı

Belirli bir eşleme dosyasının adı, yerini aldığı bileşene ilişkin Kullanıcı Arayüzü Paketi klasörünün adıyla eşleşmelidir. Bu nedenle, play_bar.json, ui-packages/mappings klasöründeki Kullanıcı Arayüzü Paketini mevcut bir kod bileşeniyle eşler.

Eşleme dosyası içerikleri

Eşleme dosyası aşağıdaki özellikleri içerir:

  • target: (Zorunlu) Özel composable işlevinizin adı. Varsayılan olarak bu, oluşturulan kod tarafından oluşturulan işlevin adıdır.

    "target" : "CustomComposableName"

  • package: (Zorunlu) Özel composable'ınızın içinde bulunduğu paketin adı. Varsayılan olarak bu, oluşturulan kod tarafından oluşturulan işlevin paketidir.

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

  • generateImplementation: (İsteğe bağlı) true veya false. Doğruysa, oluşturulan kod dosyasında bu Kullanıcı Arayüzü Paketi'nin bir uygulaması yine de oluşturulur. Yanlış değerine ayarlanırsa uygulama oluşturulmaz. Varsayılan olarak bu ayar doğrudur.

    "generateImplementation" : true

  • generatePreviews: (İsteğe bağlı) true veya false'tur. Değer true ise oluşturulan kod dosyasında, eşlenen özel bileşenin bir önizlemesi oluşturulur. Politika, yanlış değerine ayarlanırsa önizleme oluşturulmaz. Varsayılan olarak bu ayar doğrudur.

    "generatePreviews" : true

Eşlenen varyantlar

Figma bileşeninin varyantları varsa oluşturulan composable, varyantı kodlayan enum parametreleri içerir (Tasarım Varyantlarını Kullanma eğiticisinde açıklandığı gibi). Varyantları olan bir Figma bileşenini mevcut kodla eşlemek istiyorsanız bileşeni, oluşturulan composable ile aynı parametreleri alan bir composable ile eşleştirilmelidir. Örneğin, özelliği ChipType" olan bir varyanta sahip Chip adlı bir Figma bileşeni için Chip'in oluşturulan composable imzası şu şekilde görünür:

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

Chip Figma bileşeninin mevcut bir MyChipcomposable ile eşlenmesini istiyorsanız MyChip imzasının, oluşturulan composable ile aynı imzaya sahip olması gerekir (ek yönergeler belirtilmediği varsayılır). Kavramsal olarak bu, mevcut kod bileşeninin Figma bileşeniyle aynı tasarım varyantlarını kullanabildiğini gösterir.

Ek yönergeler

Örneğin, hedeflemek istediğiniz composable işlev aşağıdaki imzaya sahipse:

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

Eşleme dosyasına, parametrelerin eşlenme şeklini etkileyen bir fieldMappings bloğu ekleyebilirsiniz. Bu durumda, Chip içindeki chipText parametresinden MyChip öğesindeki description parametresine bir eşleme içerir.

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

fieldMappings engelleme türleri şunlardır:

  • parameter: Kullanıcı Arayüzü Paketi alanını bir kod parametresiyle eşler.
    • source: Kullanıcı Arayüzü Paketinde belirtilen parametre adı.
    • target: Hedef kod bileşeninde belirtilen parametre adı.
  • lambda: Kullanıcı Arayüzü Paketi alanını bir içerik lambda'sıyla eşler.
    • source: Kullanıcı Arayüzü Paketinde belirtilen parametre adı.
    • target: Hedef kod bileşeninde belirtilen parametre adı.

  • modifier: Kullanıcı Arayüzü Paketi alanını bir değiştirici yöntemiyle eşler.

    • source: Kullanıcı Arayüzü Paketinde belirtilen parametre adı.
    • method: Oluşturulan kodda çağrılması gereken Değiştirici nesne üzerindeki yöntem.
    • parameter: Belirtilen Değiştirici yöntemindeki parametrenin adı.
    • library: Değiştirici yöntemine erişmek için içe aktarılacak uygun paket adı.
    • scope: Değiştirici'nin kapsamını belirten iki değerden biri:
    • any: Değiştirici, herhangi bir alıcı kapsamında kullanılabilir.
    • relay: Değiştirici, Relay'in RelayContainer nesnesinin alıcı kapsamında kullanılmalıdır.