إنشاء كتالوجات المكوّنات وتخصيصها

في بنية A2UI، يتم تشغيل كل مساحة عرض من خلال كتالوج مكونات. الكتالوج هو عقد رسمي يحدّد مكوّنات واجهة المستخدم ومخططات الخصائص ووظائف العميل المحلية المتاحة لوكيل الذكاء الاصطناعي. بدلاً من إنشاء رمز عشوائي أو اختراع عناصر غير معروفة، يجب أن ينشئ الوكيل واجهات المستخدم باستخدام المكوّنات المحدّدة في الكتالوج فقط.

بعبارة أخرى، يحدّد الكتالوج المكوّنات، ويستخدم الوكيل هذه المكوّنات لإنشاء واجهة المستخدم لتطبيقك.

عند إنشاء تطبيق Android باستخدام أداة العرض A2UI في Jetpack Compose، تتوفّر لك خيارات مرنة بشأن كيفية توفير الكتالوجات:

• الكتالوج الأساسي: يحدّد مشروع A2UI مواصفات موحّدة وعامة الأغراض تُعرف باسم الكتالوج الأساسي، وتشمل عناصر شائعة مثل الأزرار والنصوص وحقول النصوص والبطاقات والقوائم. توفّر مكتبة AndroidX androidx.compose.material3:material3-a2ui عملية تنفيذ جاهزة لمواصفات "الكتالوج الأساسي" باستخدام مكوّنات Material Design 3 الأصلية. توفّر مكتبة androidx.a2ui.compose:compose-ui أيضًا تعريفًا عامًا للمخطط الخاص بـ "الكتالوج الأساسي"، ما يساعدك في تنفيذ "الكتالوج الأساسي" لنظام التصميم الخاص بك.
• قوائم مخصّصة: بالنسبة إلى تطبيقات الإنتاج التي تتضمّن أنظمة تصميم مميّزة، يمكنك إنشاء قائمة مخصّصة من البداية. يؤدي ذلك إلى حصر الوكيل في المكوّنات ورموز الأنماط واللغة المرئية المحدّدة لتطبيقك.
• مجموعة فرعية أو مختلطة: يمكنك الجمع بين عمليات تنفيذ مكوّنات معيّنة من "الفهرس الأساسي" المقدَّم ومكوّناتك المخصّصة، أو يمكنك إلغاء عمليات تنفيذ مكوّنات فردية ضمن مجموعة "الفهرس الأساسي".

استخدام "قائمة المنتجات الأساسية" المتوفّرة

للبدء بسرعة بدون إنشاء مخطط مكون من البداية، يمكنك استخدام التنفيذ المقدَّم لمواصفات A2UI Basic Catalog. تنفّذ مكتبة androidx.compose.material3:material3-a2ui Basic Catalog باستخدام مكوّنات Material Design 3.

عند إنشاء مثيل materialA2uiBasicCatalogV1، يجب توفير أدوات العرض والمعالجات لما يلي:

• مكوّنات الوسائط، مثل الصور والفيديوهات ومشغّلات الصوت
• أداة فتح عناوين URL
• تنسيق الرسائل المترجَمة

لا تتضمّن مكتبات A2UI عمدًا تبعيات الوسائط والشبكات الخارجية، مثل Coil أو Glide أو Media3. بدلاً من ذلك، يمكنك توفير أدوات العرض الخاصة بك. يمنع ذلك حدوث تعارضات في التبعيات من خلال توفير مكتبات فريدة. على سبيل المثال، إذا كان تطبيقك يستخدم Coil لتحميل الصور أو Media3 لتشغيل الوسائط، يمكنك ربط هذه المكتبات الحالية مباشرةً بالكتالوج.

يوضّح المثال التالي كيفية إنشاء مثيل من Basic Catalog وربط مكتبات الوسائط المفضّلة وأداة فتح عناوين URL وأداة تنسيق الرسائل:

// 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 المخصّصة. يمنحك هذا الأسلوب تحكّمًا كاملاً في مخططات المكوّنات المعروضة للوكيل وواجهة مستخدم Compose الأصلية التي تم إنشاؤها:

// 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، راجِع تنفيذ مكوّنات مخصّصة في "التطبيق أثناء الاستخدام".

استخدام مجموعة فرعية من مكوّنات "الفهرس الأساسي" مع مكوّنات مخصّصة

ليس عليك الاختيار بين إنشاء كل شيء من البداية أو اعتماد "الفهرس الأساسي" بأكمله. يمكنك تجميع كتالوج يجمع بين مكونات محدّدة من عملية تنفيذ "الكتالوج الأساسي" المقدَّمة ومكوناتك المخصّصة:

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

يمكنك بدلاً من ذلك تخصيص حزمة "كتالوج الأساس" المتوفّرة من خلال إلغاء خانات مكوّنات معيّنة:

// 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) التي توفّر تنفيذ Material 3 لمواصفات "الكتالوج الأساسي" العادية لواجهة A2UI.
• ‫A2uiReadinessEvaluator وasReadinessEvaluator(): A2uiReadinessEvaluator هي الواجهة لتقييم مدى جاهزية المكوّن. تعمل دالة الإضافة asReadinessEvaluator() على تحديد حالات الجاهزية باستخدام المكوّنات المسجّلة في قائمة.

كتالوج إصدارات A2UI ومخططات المكوّنات

يرتبط تعريف مخطط الفهرس بإصدار بروتوكول معيّن. عندما يتطوّر البروتوكول، يتم تحديث إصدار تعريف الكتالوج. يمكن أن تستخدم عمليات تنفيذ المكوّنات في هذا الإصدار التالي واجهات برمجة تطبيقات معدَّلة خاصة بأداة العرض، بينما تظل الإصدارات الأقدم تعمل جنبًا إلى جنب.