ایجاد و سفارشی‌سازی کاتالوگ‌های کامپوننت

در معماری A2UI، هر سطح توسط یک کاتالوگ اجزا هدایت می‌شود. کاتالوگ یک قرارداد رسمی است که اجزای رابط کاربری، طرحواره‌های ویژگی و توابع کلاینت محلی موجود برای یک عامل هوش مصنوعی را تعریف می‌کند. به جای تولید کد دلخواه یا اختراع عناصر ناشناخته، عامل باید رابط‌های کاربری را منحصراً با استفاده از اجزای اعلام شده در کاتالوگ بسازد.

به عبارت دیگر: کاتالوگ کامپوننت‌ها را تعریف می‌کند و عامل از آنها برای ساخت رابط کاربری برنامه شما استفاده می‌کند.

هنگام ساخت یک برنامه اندروید با رندرکننده Jetpack Compose A2UI، گزینه‌های انعطاف‌پذیری برای نحوه ارائه کاتالوگ‌ها دارید:

• کاتالوگ پایه : پروژه A2UI یک مشخصات استاندارد و عمومی به نام کاتالوگ پایه تعریف می‌کند که شامل عناصر رایجی مانند دکمه‌ها، متن، فیلدهای متنی، کارت‌ها و لیست‌ها می‌شود. کتابخانه AndroidX androidx.compose.material3:material3-a2ui پیاده‌سازی آماده‌ای از این مشخصات کاتالوگ پایه را با استفاده از کامپوننت‌های بومی Material Design 3 ارائه می‌دهد. کتابخانه androidx.a2ui.compose:compose-ui همچنین یک تعریف طرحواره عمومی برای کاتالوگ پایه ارائه می‌دهد که به شما کمک می‌کند کاتالوگ پایه را برای سیستم طراحی خود پیاده‌سازی کنید.
• کاتالوگ‌های سفارشی : برای برنامه‌های کاربردی با سیستم‌های طراحی متمایز خود، می‌توانید یک کاتالوگ سفارشی را از ابتدا بسازید. این کار عامل را به اجزای دقیق، توکن‌های استایل‌بندی و زبان بصری برنامه شما محدود می‌کند.
• زیرمجموعه یا ترکیبی : شما می‌توانید پیاده‌سازی‌های اجزای خاص از کاتالوگ پایه ارائه شده را با اجزای سفارشی خود ترکیب کنید، یا پیاده‌سازی‌های اجزای منفرد را در مجموعه کاتالوگ پایه نادیده بگیرید.

از کاتالوگ پایه ارائه شده استفاده کنید

برای شروع سریع بدون نیاز به نوشتن طرحواره کامپوننت از ابتدا، می‌توانید از پیاده‌سازی ارائه شده از مشخصات کاتالوگ پایه A2UI استفاده کنید. کتابخانه androidx.compose.material3:material3-a2ui کاتالوگ پایه را با استفاده از کامپوننت‌های طراحی متریال ۳ پیاده‌سازی می‌کند.

وقتی materialA2uiBasicCatalogV1 را نمونه‌سازی می‌کنید، رندرکننده‌ها و هندلرهای زیر را ارائه دهید:

• اجزای رسانه‌ای، مانند تصاویر، ویدیو و پخش‌کننده‌های صوتی
• بازکننده آدرس اینترنتی
• قالب‌بندی پیام محلی‌شده

کتابخانه‌های A2UI عمداً وابستگی‌های رسانه‌ای و شبکه‌ای خارجی مانند Coil، Glide یا Media3 را در خود جای نمی‌دهند. در عوض، شما رندرکننده‌های خودتان را ارائه می‌دهید. این کار با ارائه کتابخانه‌های منحصر به فرد، از تداخل وابستگی‌ها جلوگیری می‌کند. به عنوان مثال، اگر برنامه شما از قبل از Coil برای بارگذاری تصویر یا از Media3 برای پخش استفاده می‌کند، می‌توانید آن کتابخانه‌های موجود را مستقیماً به کاتالوگ اضافه کنید.

مثال زیر نحوه نمونه‌سازی کاتالوگ پایه و اتصال کتابخانه‌های رسانه‌ای دلخواه، بازکننده 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 آنها، به بخش پیاده‌سازی کامپوننت‌های سفارشی 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(...),
)

از طرف دیگر، می‌توانید مجموعه کاتالوگ پایه ارائه شده را با لغو اسلات‌های خاص کامپوننت، سفارشی کنید:

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

در طول مذاکره کاتالوگ ، عامل تمام شناسه‌های کاتالوگ پشتیبانی‌شده را کشف می‌کند و نسخه مناسب برای هر سطح را هدف قرار می‌دهد.

جزئیات پیاده‌سازی

بخش‌های بعدی اعتبارسنجی کاتالوگ داخلی و مذاکره طرحواره را توضیح می‌دهند.

مسیرهای کاربری مدیریت کاتالوگ، APIهای کلیدی زیر را معرفی می‌کنند:

• A2uiCatalog : رابط و تابع کارخانه سطح بالا برای تعریف کاتالوگ‌های اجزا.
• materialA2uiBasicCatalogVX : توابع کارخانه‌ای نسخه‌بندی‌شده (مانند materialA2uiBasicCatalogV1 ) که پیاده‌سازی Material 3 از مشخصات استاندارد کاتالوگ پایه A2UI را فراهم می‌کنند.
• A2uiReadinessEvaluator و asReadinessEvaluator() : A2uiReadinessEvaluator رابطی برای ارزیابی آمادگی کامپوننت است. تابع الحاقی asReadinessEvaluator() وضعیت‌های آمادگی را با استفاده از کامپوننت‌های ثبت‌شده در یک کاتالوگ بررسی می‌کند.

کاتالوگ نسخه A2UI و طرحواره‌های کامپوننت

تعریف طرحواره کاتالوگ با یک نسخه پروتکل خاص مرتبط است. هنگامی که پروتکل تکامل می‌یابد، تعریف کاتالوگ نسخه خود را ارتقا می‌دهد. پیاده‌سازی‌های کامپوننت برای این نسخه بعدی می‌توانند از APIهای رندر به‌روزرسانی‌شده استفاده کنند، در حالی که نسخه‌های پایین‌تر در کنار هم عملیاتی باقی می‌مانند.