Bileşen katalogları oluşturma ve özelleştirme

A2UI mimarisinde her yüzey bir bileşen kataloğu tarafından desteklenir. Katalog, bir yapay zeka aracının kullanabileceği kullanıcı arayüzü bileşenlerini, özellik şemalarını ve yerel istemci işlevlerini tanımlayan resmi bir sözleşmedir. Aracı, rastgele kod oluşturmak veya bilinmeyen öğeler icat etmek yerine yalnızca katalogda belirtilen bileşenleri kullanarak kullanıcı arayüzleri oluşturmalıdır.

Diğer bir deyişle, katalog bileşenleri bildirir ve ajan, uygulamanızın kullanıcı arayüzünü oluşturmak için bu bileşenleri kullanır.

Jetpack Compose A2UI oluşturucu ile Android uygulaması oluştururken katalogları nasıl sağlayacağınız konusunda esnek seçenekleriniz vardır:

• Temel Katalog: A2UI projesi, düğmeler, metin, metin alanları, kartlar ve listeler gibi ortak öğeleri içeren Temel Katalog adlı standartlaştırılmış, genel amaçlı bir spesifikasyon tanımlar. AndroidX kitaplığı androidx.compose.material3:material3-a2ui, yerel Materyal Tasarım 3 bileşenlerini kullanarak bu Temel Katalog spesifikasyonunun hazır bir uygulamasını sağlar. androidx.a2ui.compose:compose-ui Kitaplık, Temel Katalog için genel bir şema tanımı da sağlar. Bu tanım, kendi tasarım sisteminizde Temel Katalog'u uygulamanıza yardımcı olur.
• Özel kataloglar: Kendine özgü tasarım sistemleri olan üretim uygulamaları için sıfırdan özel bir katalog oluşturabilirsiniz. Bu, ajanı uygulamanızın tam bileşenleri, stil belirteçleri ve görsel diliyle kısıtlar.
• Alt küme veya karma: Sağlanan Temel Katalog'daki belirli bileşen uygulamalarını kendi özel bileşenlerinizle birleştirebilir veya Temel Katalog paketindeki tek tek bileşen uygulamalarını geçersiz kılabilirsiniz.

Sağlanan temel kataloğu kullanın

Bir bileşen şemasını sıfırdan oluşturmadan hızlıca başlamak için A2UI Basic Catalog spesifikasyonunun sağlanan uygulamasını kullanabilirsiniz. androidx.compose.material3:material3-a2ui kitaplığı, Materyal Tasarım 3 bileşenlerini kullanarak Temel Katalog'u uygular.

materialA2uiBasicCatalogV1 öğesini oluşturduğunuzda aşağıdakiler için oluşturucular ve işleyiciler sağlayın:

• Resim, video ve ses oynatıcılar gibi medya bileşenleri
• URL açıcı
• Yerelleştirilmiş ileti biçimlendirmesi

A2UI kitaplıkları, Coil, Glide veya Media3 gibi harici medya ve ağ oluşturma bağımlılıklarını kasıtlı olarak paketlemez. Bunun yerine, kendi oluşturucularınızı sağlarsınız. Bu, benzersiz kitaplıklar sağlayarak bağımlılık çakışmalarını önler. Örneğin, uygulamanızda resim yükleme için Coil veya oynatma için Media3 kullanılıyorsa bu mevcut kitaplıkları doğrudan kataloga bağlayabilirsiniz.

Aşağıdaki örnekte, Basic Catalog'un nasıl oluşturulacağı ve tercih ettiğiniz medya kitaplıklarının, URL açıcının ve mesaj biçimlendiricinin nasıl bağlanacağı gösterilmektedir:

// Instantiate the provided Basic Catalog (implemented with Material 3)
val basicCatalog = materialA2uiBasicCatalogV1(
    // Example: Wire up Coil for image loading (via AsyncImage)
    image = MaterialA2uiBasicCatalogV1Defaults.image {
            url, description, scale, modifier, onError ->
        AsyncImage(
            model = url,
            contentDescription = description,
            contentScale = scale,
            modifier = modifier,
            onError = { state -> onError(state.result.throwable) },
        )
    },

    // Example: Use ExoPlayer/Media3 for video
    video = MaterialA2uiBasicCatalogV1Defaults.video { url, modifier, onError ->
        // Custom ExoPlayer video integration here
    },

    // Example: Use an audio player
    audioPlayer = MaterialA2uiBasicCatalogV1Defaults.audioPlayer {
            url, description, modifier, onError ->
        // Custom audio integration here
    },

    // Handle outbound URLs, such as using an app navigator or context intents.
    urlOpener = { url ->
        appNavigator.openUrl(url)
    },

    // Handle localized message formatting
    messageFormatter = { pattern, locale, args ->
        MessageFormat.format(context, locale, pattern, args)
    },
    localeProvider = A2uiLocaleProvider.Default,
)

Sıfırdan özel bileşen kataloğu oluşturma

Uygulamanızda özel bir tasarım sistemi kullanılıyorsa kendi özel A2uiComponent uygulamalarınızı içeren kendi kataloğunuzu tanımlayabilirsiniz. Bu yaklaşım, aracıya sunulan bileşen şemaları ve yerel Compose kullanıcı arayüzü üzerinde tam kontrol sahibi olmanızı sağlar:

// Define a custom catalog that mirrors your app's design system
val CustomDesignSystemCatalog = A2uiCatalog(
    catalogId = "https://example.com/catalogs/my-design-system/v1/catalog.json",
    components = listOf(
        CustomButtonComponent,
        CustomCardComponent,
        CustomTextFieldComponent,
    ),
    functions = listOf(MyCustomLocalFunction()),
)

Bileşen şemalarını ve bunların Compose kullanıcı arayüzü oluşturma mantığını tanımlama talimatları için Özel A2UI bileşenlerini uygulama başlıklı makaleye bakın.

Temel Katalog bileşenlerinin bir alt kümesini özel bileşenlerle kullanma

Her şeyi sıfırdan oluşturmak veya Temel Katalog'un tamamını kullanmak arasında kesin bir seçim yapmanız gerekmez. Sağlanan Temel Katalog uygulamasındaki belirli bileşenleri kendi özel bileşenlerinizle birleştirerek bir katalog oluşturabilirsiniz:

// Assemble a catalog using select Basic Catalog components alongside custom components
val hybridCatalog = A2uiCatalog(
    catalogId = "https://example.com/catalogs/my-app/v1/catalog.json",
    components = listOf(
        // Use provided Basic Catalog components (built with Material 3)
        MaterialA2uiBasicCatalogV1Defaults.text,
        MaterialA2uiBasicCatalogV1Defaults.card,

        // Add proprietary components from your app's design system
        CustomChartComponent,
        CustomProductCardComponent,
    ),
    functions = createBasicCatalogFunctions(...),
)

Alternatif olarak, belirli bileşen yuvalarını geçersiz kılarak sağlanan Temel Katalog paketini özelleştirebilirsiniz:

// Override specific components within the Basic Catalog suite
val customizedBasicCatalog = materialA2uiBasicCatalogV1(
    // Supply required renderers (such as Coil or ExoPlayer) as shown earlier
    image = MaterialA2uiBasicCatalogV1Defaults.image(myImageRenderer),
    video = MaterialA2uiBasicCatalogV1Defaults.video(myVideoRenderer),
    audioPlayer = MaterialA2uiBasicCatalogV1Defaults
        .audioPlayer(myAudioRenderer),
    urlOpener = { url -> /* Open URL */ },
    messageFormatter = { pattern, _, _ -> pattern },
    localeProvider = A2uiLocaleProvider.Default,
    // Replaces the default button. If you use this, implement the
    // A2uiBasicCatalogV1.Button interface.
    button = MyCustomBrandButtonComponent,
    
)

Katalog sürüm oluşturma ve şema geliştirmeyi yönetme

A2UI katalogları, JSON şeması sözleşmelerine göre açıkça sürüm oluşturulur. Şemada uyumluluğu bozan değişiklikler yapıldığında sürüm yükseltme işlemi gereklidir:

// Original component (v1 catalog)
object CustomButtonComponent : A2uiComponent { ... }

// Unchanged component across versions
object CustomTextComponent : A2uiComponent { ... }

// Future breaking schema change (v2 catalog)
object CustomButtonComponentV2 : A2uiComponent { ... }

// Assembles the v1 catalog
fun customCatalogV1(
    button: A2uiComponent = CustomButtonComponent,
    text: A2uiComponent = CustomTextComponent,
): A2uiCatalog = A2uiCatalog(
    catalogId = "https://example.com/catalogs/my-app/v1/catalog.json",
    components = listOf(button, text),
)

// Assembles the v2 catalog
fun customCatalogV2(
    button: A2uiComponent = CustomButtonComponentV2,
    text: A2uiComponent = CustomTextComponent,
): A2uiCatalog = A2uiCatalog(
    catalogId = "https://example.com/catalogs/my-app/v2/catalog.json",
    components = listOf(button, text),
)

Müşteriniz, kesinti olmadan sorunsuz taşıma işlemleri gerçekleştirmek için ileti işlemcisine aynı anda birden fazla desteklenen katalog sürümü kaydedebilir:

private val processor = A2uiMessageProcessor(
    catalogs = listOf(
        customCatalogV1(),
        customCatalogV2(),
    ),
)

Katalog pazarlığı sırasında aracı, desteklenen tüm katalog kimliklerini keşfeder ve her yüzey için uygun sürümü hedefler.

Uygulama ayrıntıları

Aşağıdaki bölümlerde, dahili katalog doğrulama ve şema anlaşması açıklanmaktadır.

Katalog yönetimi kullanıcı yolculuklarında aşağıdaki temel API'ler tanıtılmaktadır:

• A2uiCatalog: Bileşen kataloglarını tanımlamak için arayüz ve üst düzey fabrika işlevi.
• materialA2uiBasicCatalogVX: Standart A2UI Basic Catalog spesifikasyonunun Material 3 uygulamasını sağlayan, sürümlendirilmiş fabrika işlevleri (ör. materialA2uiBasicCatalogV1).
• A2uiReadinessEvaluator ve asReadinessEvaluator(): A2uiReadinessEvaluator, bileşen hazırlığını değerlendirmek için kullanılan arayüzdür. asReadinessEvaluator() uzantı işlevi, bir kataloğa kaydedilen bileşenleri kullanarak hazırlık durumlarını çözer.

A2UI sürüm kataloğu ve bileşen şemaları

Katalog şeması tanımı belirli bir protokol sürümüyle ilişkilendirilir. Protokol geliştiğinde katalog tanımı sürümünü ilerletir. Bu sonraki sürüm için bileşen uygulamaları, güncellenmiş oluşturucu API'lerini kullanabilir. Daha düşük sürümler ise yan yana çalışmaya devam eder.