Membuat dan menyesuaikan katalog komponen

Dalam arsitektur A2UI, setiap platform didorong oleh katalog komponen. Katalog adalah kontrak formal yang menentukan komponen UI, skema properti, dan fungsi klien lokal yang tersedia untuk agen AI. Daripada membuat kode arbitrer atau menciptakan elemen yang tidak diketahui, agen harus membuat antarmuka pengguna hanya menggunakan komponen yang dideklarasikan dalam katalog.

Dengan kata lain: katalog mendeklarasikan komponen, dan agen menggunakannya untuk membangun UI aplikasi Anda.

Saat membangun aplikasi Android dengan perender A2UI Jetpack Compose, Anda memiliki opsi fleksibel untuk cara menyediakan katalog:

  • Katalog Dasar: Project A2UI menentukan spesifikasi standar tujuan umum yang disebut Katalog Dasar, yang mencakup elemen umum seperti tombol, teks, kolom teks, kartu, dan daftar. Library AndroidX androidx.compose.material3:material3-a2ui menyediakan implementasi langsung spesifikasi Katalog Dasar ini menggunakan komponen Desain Material 3 bawaan. Library androidx.a2ui.compose:compose-ui juga menyediakan definisi skema generik untuk Katalog Dasar, yang membantu Anda menerapkan Katalog Dasar untuk sistem desain Anda sendiri.
  • Katalog kustom: Untuk aplikasi produksi dengan sistem desainnya sendiri yang berbeda, Anda dapat membuat katalog kustom dari awal. Hal ini membatasi agen ke komponen, token gaya, dan bahasa visual yang persis sama dengan aplikasi Anda.
  • Subkumpulan atau hybrid: Anda dapat menggabungkan penerapan komponen tertentu dari Katalog Dasar yang disediakan dengan komponen kustom Anda sendiri, atau mengganti penerapan komponen individual dalam rangkaian Katalog Dasar.

Gunakan Katalog Dasar yang disediakan

Untuk memulai dengan cepat tanpa membuat skema komponen dari awal, Anda dapat menggunakan implementasi spesifikasi Katalog Dasar A2UI yang disediakan. Library androidx.compose.material3:material3-a2ui menerapkan Katalog Dasar menggunakan komponen Desain Material 3.

Saat membuat instance materialA2uiBasicCatalogV1, berikan perender dan pengendali untuk hal berikut:

  • Komponen media, seperti gambar, video, dan pemutar audio
  • Pembuka URL
  • Pemformatan pesan yang dilokalkan

Library A2UI sengaja tidak menggabungkan dependensi media dan jaringan eksternal, seperti Coil, Glide, atau Media3. Sebagai gantinya, Anda menyediakan perender Anda sendiri. Tindakan ini mencegah konflik dependensi dengan menyediakan library unik. Misalnya, jika aplikasi Anda sudah menggunakan Coil untuk pemuatan gambar atau Media3 untuk pemutaran, Anda dapat langsung memasang library yang ada tersebut ke katalog.

Contoh berikut menunjukkan cara membuat instance Katalog Dasar dan menghubungkan library media, pembuka URL, dan pemformat pesan pilihan Anda:

// 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,
)

Merakit katalog komponen kustom dari awal

Jika aplikasi Anda menggunakan sistem desain kustom, Anda dapat menentukan katalog sendiri yang berisi penerapan A2uiComponent kustom Anda sendiri. Pendekatan ini memberi Anda kontrol penuh atas skema komponen yang diekspos ke agen dan UI Compose native yang ditampilkan:

// 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()),
)

Untuk mengetahui petunjuk tentang cara menentukan skema komponen individual dan logika rendering UI Compose-nya, lihat Menerapkan komponen A2UI kustom.

Menggunakan subset komponen Katalog Dasar dengan komponen kustom

Anda tidak harus memilih antara membangun semuanya dari awal atau mengadopsi seluruh Katalog Dasar. Anda dapat menyusun katalog yang menggabungkan komponen tertentu dari implementasi Katalog Dasar yang disediakan dengan komponen kustom Anda sendiri:

// 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(...),
)

Atau, Anda dapat menyesuaikan rangkaian Basic Catalog yang disediakan dengan mengganti slot komponen tertentu:

// 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,
    
)

Mengelola pembuatan versi katalog dan evolusi skema

Katalog A2UI diberi versi secara eksplisit berdasarkan kontrak skema JSON-nya. Peningkatan versi diperlukan saat memperkenalkan perubahan skema yang dapat menyebabkan gangguan:

// 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),
)

Untuk mengaktifkan migrasi yang lancar tanpa periode nonaktif, klien Anda dapat mendaftarkan beberapa versi katalog yang didukung dengan pemroses pesan secara bersamaan:

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

Selama negosiasi katalog, agen menemukan semua ID katalog yang didukung dan menargetkan versi yang sesuai untuk setiap platform.

Detail implementasi

Bagian berikut menjelaskan validasi katalog internal dan negosiasi skema.

Perjalanan pengguna pengelolaan katalog memperkenalkan API utama berikut:

  • A2uiCatalog: Antarmuka dan fungsi factory tingkat teratas untuk menentukan katalog komponen.
  • materialA2uiBasicCatalogVX: Fungsi factory versi (seperti materialA2uiBasicCatalogV1) yang menyediakan penerapan Material 3 dari spesifikasi Katalog Dasar A2UI standar.
  • A2uiReadinessEvaluator dan asReadinessEvaluator(): A2uiReadinessEvaluator adalah antarmuka untuk mengevaluasi kesiapan komponen. Fungsi ekstensi asReadinessEvaluator() menyelesaikan status kesiapan menggunakan komponen yang terdaftar dalam katalog.

Katalog versi A2UI dan skema komponen

Definisi skema katalog dikaitkan dengan versi protokol tertentu. Saat protokol berkembang, definisi katalog akan meningkatkan versinya. Implementasi komponen untuk versi berikutnya ini dapat menggunakan API perender yang diupdate sementara versi yang lebih rendah tetap beroperasi secara berdampingan.

Sebelumnya
Ringkasan
Berikutnya
Platform render