Bileşenleri mevcut kodla eşleme

Geliştiriciler, oluşturulan kod yerine bir 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, mevcut uygulamada animasyon veya karmaşık davranış (ör. açılır menü) gibi, oluşturulan kodla elde edilemeyecek özellikler olduğunda faydalıdır.

Geliştiriciler, bir eşleme dosyası kullanarak bileşenlerin nasıl eşleneceğini belirtir. Harita oluşturma dosyası, kod oluşturucuya en azından doğru istemci kodunun oluşturulabilmesi için hedef birleştirilebilir işleve nasıl ulaşılacağını söyler.

Eşlenen bileşenlere genel bakış şeması

Örnek:

Figma'da bir tasarımcı, Oynatma Çubuğu bileşeninin bir örneğini içeren Kart bileşeni oluşturur, her iki bileşeni de paketleyip bir geliştiriciye gönderir.

Geliştirici, kullanıcı arayüzü paketlerini Figma'dan içe aktardığında ui-packages içinde iki dizin oluşturulur: card ve play_bar. Proje derlendiğinde iki birleştirilebilir 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 işlevini çağırır.

Ancak tasarımcı ve geliştirici, Card yerine Figma'da açıklanması zor işlevlere sahip mevcut bir bileşeni (MyExistingPlaybar) kullanmak istiyor. Bu nedenle geliştirici, play_bar kullanıcı arayüzü paketini MyExistingPlaybar ile eşleyen play_bar.json adlı bir eşleme dosyası ekler:

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

Geliştirici projeyi derlediğinde Card, PlayBar yerine MyExistingPlaybar'u çağırır. MyExistingPlaybar'ün PlayBar ile aynı parametrelere sahip olması gerektiğini unutmayın (ancak aşağıda Ek Yönergeler bölümünde açıklandığı gibi birkaç fark olabilir).

Eşleme dosyası

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

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

Eşleme dosyası oluşturma

Relay, içe aktarılan herhangi bir kullanıcı arayüzü paketi için eşleme dosyası oluşturabilir. Aşağıdaki adımları uygulayın:

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

    Eşleme dosyası oluşturma

  2. İletişim kutusunda aşağıdaki 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.

    • Hedeflenebilir öğe: Oluşturulan öğe yerine kullanılan özel öğeyi ayarlar. Mevcut bir bileşiği kullanabilir veya iletişim kutusunda yeni bir bileşim oluşturabilirsiniz. Yeni bir birleştirilebilir öğe oluşturduğunuzda, kullanıcı arayüzü paketinde tanımlanan parametrelerle aynı parametrelere sahip bir birleştirilebilir öğe oluşturulur.

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

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

Eşleme dosyası oluştur iletişim kutusunu, aşağıdaki adımları uygulayarak Relay paket modülü kullanıcı arayüzünden de açabilirsiniz:

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

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

  3. Paket Seçenekleri bölümünde Eşleme dosyası oluştur düğmesini tıklayın.

    Eşleme dosyası oluşturma

Eşleme dosyası adı

Belirli bir eşleme dosyasının adı, yerine geçtiği bileşenin 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.

Dosya içeriklerini eşleme

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

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

    "target" : "CustomComposableName"

  • package: (Zorunlu) Özel derlenebilir öğenizin 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ğru ise oluşturulan kod dosyasında bu kullanıcı arayüzü paketinin bir uygulaması yine oluşturulur. Yanlış ise uygulama oluşturulmaz. Varsayılan olarak bu değer doğrudur.

    "generateImplementation" : true

  • generatePreviews: (İsteğe bağlı) true veya false. Doğru ise oluşturulan kod dosyasında eşlenen özel bileşenin bir önizlemesi oluşturulur. Yanlış ise önizleme oluşturulmaz. Varsayılan olarak bu değer doğrudur.

    "generatePreviews" : true

Eşlenen varyantlar

Bir Figma bileşeninin varyantları varsa oluşturulan derlenebilir öğe, varyantı kodlayan enum parametreleri içerir (Tasarım Varyantlarını Yönetme eğitimde açıklandığı gibi). Varyantları olan bir Figma bileşenini mevcut kodla eşlemek istiyorsanız bu bileşen, oluşturulan bileşenle aynı parametreleri alan bir bileşenle eşlenmelidir. Örneğin, ChipType özelliğine sahip bir varyantı olan Chip adlı bir Figma bileşeni için oluşturulan birleştirilebilir imza şu şekilde görünür:

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

Chip Figma bileşeninin mevcut bir MyChip bileşeniyle eşlenmesini istiyorsanız MyChip bileşeninin imzası, oluşturulan bileşenle aynı imzaya sahip olmalıdır (ek yönergeler belirtilmediği varsayılır). Kavramsal olarak bu, mevcut kod bileşeninin Figma bileşeniyle aynı tasarım varyantlarını kullanabildiği anlamına gelir.

Ek yönergeler

Örneğin, hedeflemek istediğiniz birleştirilebilir işlevin imzası aşağıdaki gibiyse:

@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'daki chipText parametresinden MyChip'daki description parametresine bir eşleme içerir.

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

fieldMappings bloğu türleri şunlardır:

  • parameter: Bir kullanıcı arayüzü paketi alanını bir kod parametresiyle eşler.
    • source: Kullanıcı arayüzü paketinde belirtildiği şekilde parametrenin adı.
    • target: Hedef kod bileşeninde belirtildiği şekilde parametrenin adı.
  • lambda: Bir kullanıcı arayüzü paketi alanını bir içerik lambda işleviyle eşler.
    • source: Kullanıcı arayüzü paketinde belirtildiği şekilde parametrenin adı.
    • target: Hedef kod bileşeninde belirtildiği şekilde parametrenin adı.

  • modifier: Bir kullanıcı arayüzü paketi alanını bir değişken yöntemiyle eşler.

    • source: Kullanıcı arayüzü paketinde belirtildiği şekilde parametrenin adı.
    • method: Oluşturulan kodda çağrılması gereken, Değiştirici nesnesinde bulunan 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 nitelikli paket adı.
    • scope: Değiştiricinin kapsamını belirten iki değerden biri:
    • any: Düzenleyici, herhangi bir alıcı kapsamında kullanılabilir.
    • relay: Değiştirici, Relay'in RelayContainer nesnesinin alıcı kapsamında kullanılmalıdır.