สร้างและปรับแต่งแคตตาล็อกคอมโพเนนต์

ในสถาปัตยกรรม A2UI ทุกแพลตฟอร์มจะขับเคลื่อนโดยแคตตาล็อกคอมโพเนนต์ แคตตาล็อกคือสัญญาที่เป็นทางการซึ่งกำหนดคอมโพเนนต์ UI, สคีมาพร็อพเพอร์ตี้ และฟังก์ชันไคลเอ็นต์ในเครื่องที่พร้อมใช้งานสำหรับ AI Agent เอเจนต์ต้องสร้างอินเทอร์เฟซผู้ใช้โดยใช้เฉพาะคอมโพเนนต์ที่ประกาศไว้ในแคตตาล็อก แทนที่จะสร้างโค้ดโดยพลการหรือสร้างองค์ประกอบที่ไม่รู้จัก

กล่าวคือ แคตตาล็อกจะประกาศคอมโพเนนต์ และ Agent จะใช้คอมโพเนนต์เหล่านั้นเพื่อสร้าง UI ของแอป

เมื่อสร้างแอป 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 ไม่ได้รวมทรัพยากร Dependency ของสื่อภายนอกและการเชื่อมต่อเครือข่าย เช่น Coil, Glide หรือ Media3 โดยเจตนา แต่คุณต้องระบุตัวแสดงผลของคุณเองแทน ซึ่งจะช่วยป้องกันความขัดแย้งของทรัพยากร Dependency โดยการจัดหาไลบรารีที่ไม่ซ้ำกัน ตัวอย่างเช่น หากแอปใช้ 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ที่กำหนดเอง แนวทางนี้ ช่วยให้คุณควบคุมสคีมาของคอมโพเนนต์ที่แสดงต่อเอเจนต์และ UI ของ 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()),
)

ดูวิธีการกำหนดสคีมาของคอมโพเนนต์แต่ละรายการและตรรกะการแสดงผล UI ของ 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: อินเทอร์เฟซและฟังก์ชันระดับบนสุดของ Factory สำหรับการกำหนด แคตตาล็อกคอมโพเนนต์
• materialA2uiBasicCatalogVX: ฟังก์ชันโรงงานที่กำหนดเวอร์ชัน (เช่น materialA2uiBasicCatalogV1) ซึ่งให้การใช้งาน Material 3 ของ ข้อกำหนดแคตตาล็อกพื้นฐาน A2UI มาตรฐาน
• A2uiReadinessEvaluator และ asReadinessEvaluator() A2uiReadinessEvaluator คืออินเทอร์เฟซสำหรับประเมินความพร้อมของคอมโพเนนต์ ฟังก์ชันส่วนขยาย asReadinessEvaluator() จะแก้ปัญหา สถานะความพร้อมโดยใช้คอมโพเนนต์ที่ลงทะเบียนไว้ในแคตตาล็อก

แคตตาล็อกเวอร์ชันและสคีมาคอมโพเนนต์ของ A2UI

คำจำกัดความของสคีมาแคตตาล็อกจะเชื่อมโยงกับโปรโตคอลเวอร์ชันที่เฉพาะเจาะจง เมื่อโปรโตคอลมีการพัฒนา คำจำกัดความของแคตตาล็อกจะอัปเดตเวอร์ชัน การติดตั้งใช้งานคอมโพเนนต์สำหรับเวอร์ชันถัดไปนี้สามารถใช้ API ของโปรแกรมแสดงผลที่อัปเดตแล้ว ในขณะที่เวอร์ชันที่ต่ำกว่าจะยังคงทำงานควบคู่กันไป