יצירה והתאמה אישית של קטלוגים של רכיבים

בארכיטקטורת A2UI, כל משטח מונע על ידי קטלוג רכיבים. קטלוג הוא חוזה רשמי שמגדיר את רכיבי ממשק המשתמש, סכימות המאפיינים והפונקציות של הלקוח המקומי שזמינים לסוכן AI. במקום ליצור קוד שרירותי או להמציא רכיבים לא מוכרים, הסוכן צריך לבנות ממשקי משתמש באמצעות הרכיבים שמוצהרים בקטלוג בלבד.

במילים אחרות: הקטלוג מכריז על הרכיבים, והסוכן משתמש בהם כדי לבנות את ממשק המשתמש של האפליקציה.

כשמפתחים אפליקציית Android באמצעות כלי הרינדור A2UI של Jetpack Compose, יש לכם אפשרויות גמישות לגבי אופן אספקת הקטלוגים:

• הקטלוג הבסיסי: פרויקט A2UI מגדיר מפרט סטנדרטי לשימוש כללי שנקרא הקטלוג הבסיסי, שכולל רכיבים נפוצים כמו לחצנים, טקסט, שדות טקסט, כרטיסים ורשימות. ספריית AndroidX‏ androidx.compose.material3:material3-a2ui מספקת הטמעה מוכנה לשימוש של מפרט הקטלוג הבסיסי הזה באמצעות רכיבים מקוריים של Material Design 3. androidx.a2ui.compose:compose-uiהספרייה מספקת גם הגדרת סכימה כללית לקטלוג הבסיסי, שעוזרת לכם להטמיע את הקטלוג הבסיסי במערכת העיצוב שלכם.
• קטלוגים בהתאמה אישית: לאפליקציות ייצור עם מערכות עיצוב נפרדות משלהן, אפשר ליצור קטלוג בהתאמה אישית מאפס. ההגבלה הזו מאפשרת לסוכן להשתמש רק ברכיבים המדויקים, בטוקנים של הסגנון ובשפה החזותית של האפליקציה.
• קבוצת משנה או שילוב: אתם יכולים לשלב הטמעות ספציפיות של רכיבים מהקטלוג הבסיסי שסופק עם רכיבים מותאמים אישית משלכם, או לבטל הטמעות ספציפיות של רכיבים בחבילת הקטלוג הבסיסי.

שימוש בקטלוג הבסיסי שסופק

כדי להתחיל במהירות בלי ליצור סכימת רכיבים מאפס, אפשר להשתמש בהטמעה שסופקה של מפרט קטלוג בסיסי של A2UI. הספרייה androidx.compose.material3:material3-a2ui מטמיעה את הקטלוג הבסיסי באמצעות רכיבי Material Design 3.

כשמפעילים את materialA2uiBasicCatalogV1, צריך לספק רכיבי עיבוד ומטפלים עבור:

• רכיבי מדיה, כמו תמונות, סרטונים ונגני אודיו
• כלי לפתיחת כתובות URL
• עיצוב הודעות שמותאם לשוק המקומי

ספריות 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(...),
)

לחלופין, אפשר להתאים אישית את חבילת Basic Catalog שסופקה על ידי החלפת משבצות ספציפיות של רכיבים:

// 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: ממשק ופונקציית factory ברמה העליונה להגדרת קטלוגים של רכיבים.
• ‫materialA2uiBasicCatalogVX: פונקציות factory עם גרסאות (כמו materialA2uiBasicCatalogV1) שמספקות את ההטמעה של Material 3 של המפרט הרגיל של קטלוג בסיסי של A2UI.
• ‫A2uiReadinessEvaluator ו-asReadinessEvaluator(): ‫A2uiReadinessEvaluator הוא הממשק להערכת מוכנות הרכיב. פונקציית התוסף asReadinessEvaluator() פותרת מצבי מוכנות באמצעות הרכיבים שרשומים בקטלוג.

קטלוג גרסאות וסכימות רכיבים של A2UI

הגדרת סכימת קטלוג משויכת לגרסה ספציפית של פרוטוקול. כשהפרוטוקול מתפתח, הגרסה של הגדרת הקטלוג מתעדכנת. הטמעות של רכיבים בגרסה הבאה הזו יכולות להשתמש בממשקי API מעודכנים של רכיבי עיבוד, בעוד שגרסאות ישנות יותר ממשיכות לפעול זו לצד זו.