कॉम्पोनेंट कैटलॉग बनाना और उन्हें पसंद के मुताबिक बनाना

A2UI आर्किटेक्चर में, हर सरफेस को कॉम्पोनेंट कैटलॉग से कंट्रोल किया जाता है. कैटलॉग एक औपचारिक कानूनी समझौता होता है. इसमें यूज़र इंटरफ़ेस (यूआई) कॉम्पोनेंट, प्रॉपर्टी स्कीमा, और एआई एजेंट के लिए उपलब्ध लोकल क्लाइंट फ़ंक्शन के बारे में बताया जाता है. एजेंट को मनमाने तरीके से कोड जनरेट नहीं करना चाहिए या अज्ञात एलिमेंट नहीं बनाने चाहिए. इसके बजाय, उसे कैटलॉग में बताए गए कॉम्पोनेंट का इस्तेमाल करके ही यूज़र इंटरफ़ेस बनाने चाहिए.

दूसरे शब्दों में: कैटलॉग में कॉम्पोनेंट के बारे में बताया जाता है. एजेंट, आपके ऐप्लिकेशन का यूज़र इंटरफ़ेस (यूआई) बनाने के लिए इनका इस्तेमाल करता है.

Jetpack Compose A2UI रेंडरर की मदद से Android ऐप्लिकेशन बनाते समय, आपके पास कैटलॉग उपलब्ध कराने के कई विकल्प होते हैं:

• बेसिक कैटलॉग: A2UI प्रोजेक्ट में, स्टैंडर्ड के मुताबिक तैयार की गई एक खास जानकारी दी गई है. इसे बेसिक कैटलॉग कहा जाता है. इसमें बटन, टेक्स्ट, टेक्स्ट फ़ील्ड, कार्ड, और सूचियों जैसे सामान्य एलिमेंट शामिल होते हैं. AndroidX लाइब्रेरी androidx.compose.material3:material3-a2ui, इस बुनियादी कैटलॉग स्पेसिफ़िकेशन को तुरंत लागू करने की सुविधा देती है. इसके लिए, यह नेटिव मटीरियल डिज़ाइन 3 कॉम्पोनेंट का इस्तेमाल करती है. androidx.a2ui.compose:compose-ui लाइब्रेरी, बुनियादी कैटलॉग के लिए सामान्य स्कीमा की परिभाषा भी उपलब्ध कराती है. इससे आपको अपने डिज़ाइन सिस्टम के लिए बुनियादी कैटलॉग लागू करने में मदद मिलती है.
• कस्टम कैटलॉग: प्रोडक्शन ऐप्लिकेशन के लिए, स्क्रैच से कस्टम कैटलॉग बनाया जा सकता है. इन ऐप्लिकेशन के अपने अलग-अलग डिज़ाइन सिस्टम होते हैं. इससे एजेंट को आपके ऐप्लिकेशन के कॉम्पोनेंट, स्टाइलिंग टोकन, और विज़ुअल लैंग्वेज के बारे में सटीक जानकारी मिलती है.
• सबसेट या हाइब्रिड: आपके पास बुनियादी कैटलॉग में दिए गए कॉम्पोनेंट के कुछ खास वर्शन को अपने कस्टम कॉम्पोनेंट के साथ जोड़ने का विकल्प होता है. इसके अलावा, बुनियादी कैटलॉग के किसी कॉम्पोनेंट के वर्शन को बदला जा सकता है.

दिए गए बेसिक कैटलॉग का इस्तेमाल करना

अगर आपको कॉम्पोनेंट स्कीमा को शुरू से नहीं बनाना है, तो A2UI Basic Catalog स्पेसिफ़िकेशन के दिए गए वर्शन का इस्तेमाल करें. androidx.compose.material3:material3-a2ui लाइब्रेरी, मटीरियल डिज़ाइन 3 कॉम्पोनेंट का इस्तेमाल करके, बेसिक कैटलॉग लागू करती है.

materialA2uiBasicCatalogV1 को इंस्टैंशिएट करते समय, इनके लिए रेंडरर और हैंडलर उपलब्ध कराएं:

• मीडिया कॉम्पोनेंट, जैसे कि इमेज, वीडियो, और ऑडियो प्लेयर
• यूआरएल खोलने की सुविधा
• स्थानीय भाषा के हिसाब से मैसेज फ़ॉर्मैट करना

A2UI लाइब्रेरी, जान-बूझकर बाहरी मीडिया और नेटवर्किंग की डिपेंडेंसी को बंडल नहीं करती हैं. जैसे, Coil, Glide या Media3. इसके बजाय, आपको अपने रेंडरर उपलब्ध कराने होते हैं. यह यूनीक लाइब्रेरी उपलब्ध कराकर, डिपेंडेंसी से जुड़े टकरावों को रोकता है. उदाहरण के लिए, अगर आपका ऐप्लिकेशन इमेज लोड करने के लिए पहले से ही Coil का इस्तेमाल करता है या मीडिया चलाने के लिए Media3 का इस्तेमाल करता है, तो उन मौजूदा लाइब्रेरी को सीधे कैटलॉग में प्लग किया जा सकता है.

यहां दिए गए उदाहरण में, Basic Catalog को इंस्टैंशिएट करने का तरीका बताया गया है. साथ ही, इसमें आपकी पसंदीदा मीडिया लाइब्रेरी, यूआरएल ओपनर, और मैसेज फ़ॉर्मेटर को वायर अप करने का तरीका भी बताया गया है:

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

शुरुआत से कस्टम कॉम्पोनेंट कैटलॉग बनाना

अगर आपका ऐप्लिकेशन कस्टम डिज़ाइन सिस्टम का इस्तेमाल करता है, तो अपने हिसाब से कैटलॉग बनाया जा सकता है. इसमें कस्टम A2uiComponent लागू करने की सुविधा होती है. इस तरीके से, आपको एजेंट को दिखाए गए कॉम्पोनेंट स्कीमा और नेटिव कंपोज़ यूज़र इंटरफ़ेस (यूआई) पर पूरा कंट्रोल मिलता है:

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

अलग-अलग कॉम्पोनेंट के स्कीमा और उनके Compose यूज़र इंटरफ़ेस (यूआई) रेंडरिंग लॉजिक को तय करने के निर्देशों के लिए, कस्टम A2UI कॉम्पोनेंट लागू करना लेख पढ़ें.

कस्टम कॉम्पोनेंट के साथ, बुनियादी कैटलॉग के कॉम्पोनेंट के सबसेट का इस्तेमाल करना

आपको यह तय करने की ज़रूरत नहीं है कि आपको सब कुछ शुरू से बनाना है या पूरा बेसिक कैटलॉग अपनाना है. आपके पास ऐसा कैटलॉग बनाने का विकल्प होता है जिसमें बुनियादी कैटलॉग के कुछ कॉम्पोनेंट और आपके कस्टम कॉम्पोनेंट शामिल हों:

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

इसके अलावा, कॉम्पोनेंट के कुछ स्लॉट को बदलकर, उपलब्ध कराई गई Basic Catalog Suite को अपनी पसंद के मुताबिक बनाया जा सकता है:

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

कैटलॉग वर्शनिंग और स्कीमा एवोल्यूशन को मैनेज करना

A2UI कैटलॉग को उनके JSON स्कीमा कॉन्ट्रैक्ट के आधार पर वर्शन किया जाता है. स्कीमा में बड़े बदलाव करने पर, वर्शन को अपडेट करना ज़रूरी है:

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

बिना किसी रुकावट के माइग्रेशन की सुविधा चालू करने के लिए, आपका क्लाइंट एक साथ कई कैटलॉग वर्शन रजिस्टर कर सकता है. इसके लिए, उसे मैसेज प्रोसेसर का इस्तेमाल करना होगा:

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

कैटलॉग नेगोशिएशन के दौरान, एजेंट उन सभी कैटलॉग आईडी का पता लगाता है जो काम करते हैं. साथ ही, हर प्लैटफ़ॉर्म के लिए सही वर्शन को टारगेट करता है.

लागू करने से जुड़ी जानकारी

यहां दिए गए सेक्शन में, इंटरनल कैटलॉग की पुष्टि करने और स्कीमा नेगोशिएशन के बारे में बताया गया है.

कैटलॉग मैनेजमेंट से जुड़ी उपयोगकर्ता यात्राओं में, यहां दिए गए मुख्य एपीआई के बारे में बताया गया है:

• A2uiCatalog: कॉम्पोनेंट कैटलॉग तय करने के लिए, इंटरफ़ेस और टॉप-लेवल फ़ैक्ट्री फ़ंक्शन.
• materialA2uiBasicCatalogVX: वर्शन वाले फ़ैक्ट्री फ़ंक्शन (जैसे कि materialA2uiBasicCatalogV1), जो स्टैंडर्ड A2UI बेसिक कैटलॉग स्पेसिफ़िकेशन के Material 3 को लागू करते हैं.
• A2uiReadinessEvaluator और asReadinessEvaluator(): A2uiReadinessEvaluator, कॉम्पोनेंट की तैयारी का आकलन करने के लिए इंटरफ़ेस है. asReadinessEvaluator() एक्सटेंशन फ़ंक्शन, कैटलॉग में रजिस्टर किए गए कॉम्पोनेंट का इस्तेमाल करके, उपलब्धता की स्थितियों का पता लगाता है.

A2UI वर्शन कैटलॉग और कॉम्पोनेंट स्कीमा

कैटलॉग स्कीमा की परिभाषा, किसी खास प्रोटोकॉल वर्शन से जुड़ी होती है. प्रोटोकॉल में बदलाव होने पर, कैटलॉग की परिभाषा का वर्शन अपडेट हो जाता है. इस नए वर्शन के लिए कॉम्पोनेंट लागू करने वाले, अपडेट किए गए रेंडरर एपीआई का इस्तेमाल कर सकते हैं. वहीं, पुराने वर्शन भी साथ-साथ काम करते रहेंगे.