Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Tạo và tuỳ chỉnh danh mục thành phần

Trong cấu trúc A2UI, mọi thành phần đều được điều khiển bằng một danh mục thành phần. Danh mục là một hợp đồng chính thức xác định các thành phần giao diện người dùng, giản đồ thuộc tính và các hàm cục bộ của ứng dụng có sẵn cho một tác nhân AI. Thay vì tạo mã tuỳ ý hoặc phát minh ra các phần tử không xác định, tác nhân phải tạo giao diện người dùng chỉ bằng các thành phần được khai báo trong danh mục.

Nói cách khác: danh mục khai báo các thành phần và tác nhân sử dụng các thành phần đó để tạo giao diện người dùng cho ứng dụng của bạn.

Khi tạo một ứng dụng Android bằng trình kết xuất A2UI Jetpack Compose, bạn có các lựa chọn linh hoạt về cách cung cấp danh mục:

Danh mục cơ bản: Dự án A2UI xác định một quy cách tiêu chuẩn, đa năng có tên là Danh mục cơ bản, bao gồm các phần tử phổ biến như nút, văn bản, trường văn bản, thẻ và danh sách. Thư viện AndroidX androidx.compose.material3:material3-a2ui cung cấp một quy cách triển khai sẵn có của Quy cách Danh mục cơ bản này bằng cách sử dụng các thành phần Material Design 3 gốc. Thư viện androidx.a2ui.compose:compose-ui cũng cung cấp một định nghĩa lược đồ chung cho Danh mục cơ bản, giúp bạn triển khai Danh mục cơ bản cho hệ thống thiết kế của riêng mình.
Danh mục tuỳ chỉnh: Đối với các ứng dụng sản xuất có hệ thống thiết kế riêng biệt, bạn có thể tạo danh mục tuỳ chỉnh từ đầu. Điều này hạn chế tác nhân chỉ sử dụng các thành phần, mã thông báo tạo kiểu và ngôn ngữ trực quan chính xác của ứng dụng.
Một tập hợp con hoặc kết hợp: Bạn có thể kết hợp các quy trình triển khai thành phần cụ thể từ Danh mục cơ bản được cung cấp với các thành phần tuỳ chỉnh của riêng mình hoặc ghi đè các quy trình triển khai thành phần riêng lẻ trong bộ Danh mục cơ bản.

Sử dụng Danh mục cơ bản được cung cấp

Để bắt đầu nhanh mà không cần tạo lược đồ thành phần từ đầu, bạn có thể sử dụng chế độ triển khai được cung cấp của quy cách Danh mục cơ bản A2UI. Thư viện androidx.compose.material3:material3-a2ui triển khai Danh mục cơ bản bằng các thành phần Material Design 3.

Khi bạn tạo thực thể materialA2uiBasicCatalogV1, hãy cung cấp trình kết xuất và trình xử lý cho những thành phần sau:

Các thành phần nội dung nghe nhìn, chẳng hạn như hình ảnh, video và trình phát âm thanh
Trình mở URL
Định dạng thông báo được bản địa hoá

Các thư viện A2UI cố tình không đi kèm các phần phụ thuộc bên ngoài về nội dung nghe nhìn và mạng, chẳng hạn như Coil, Glide hoặc Media3. Thay vào đó, bạn cung cấp trình kết xuất của riêng mình. Điều này giúp ngăn chặn xung đột về phần phụ thuộc bằng cách cung cấp các thư viện riêng biệt. Ví dụ: nếu ứng dụng của bạn đã dùng Coil để tải hình ảnh hoặc Media3 để phát, thì bạn có thể cắm trực tiếp các thư viện hiện có đó vào danh mục.

Ví dụ sau đây minh hoạ cách khởi tạo Danh mục cơ bản và thiết lập các thư viện nội dung nghe nhìn, trình mở URL và trình định dạng thông báo mà bạn muốn:

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

Tạo một danh mục thành phần tuỳ chỉnh từ đầu

Nếu ứng dụng của bạn sử dụng một hệ thống thiết kế tuỳ chỉnh, thì bạn có thể xác định danh mục của riêng mình chứa các phương thức triển khai A2uiComponent tuỳ chỉnh của riêng bạn. Phương pháp này giúp bạn toàn quyền kiểm soát các giản đồ thành phần được hiển thị cho tác nhân và giao diện người dùng Compose gốc được phát ra:

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

Để biết hướng dẫn về cách xác định từng giản đồ thành phần và logic kết xuất giao diện người dùng Compose, hãy xem phần Triển khai các thành phần A2UI tuỳ chỉnh.

Sử dụng một nhóm nhỏ các thành phần trong Danh mục cơ bản với các thành phần tuỳ chỉnh

Bạn không nhất thiết phải chọn giữa việc xây dựng mọi thứ từ đầu hoặc áp dụng toàn bộ Danh mục cơ bản. Bạn có thể tập hợp một danh mục kết hợp các thành phần đã chọn từ quá trình triển khai Danh mục cơ bản được cung cấp với các thành phần tuỳ chỉnh của riêng bạn:

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

Ngoài ra, bạn có thể tuỳ chỉnh bộ Danh mục cơ bản được cung cấp bằng cách ghi đè các vị trí thành phần cụ thể:

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

Quản lý việc quản lý phiên bản danh mục và sự phát triển của lược đồ

Danh mục A2UI được phân phiên bản rõ ràng dựa trên hợp đồng giản đồ JSON. Bạn phải tăng phiên bản khi giới thiệu các thay đổi về giản đồ gây lỗi:

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

Để cho phép di chuyển liền mạch mà không bị gián đoạn, ứng dụng khách của bạn có thể đăng ký đồng thời nhiều phiên bản danh mục được hỗ trợ bằng trình xử lý thông báo:

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

Trong quá trình đàm phán danh mục, tác nhân sẽ khám phá tất cả mã danh mục được hỗ trợ và nhắm đến phiên bản thích hợp cho từng nền tảng.

Thông tin chi tiết về việc triển khai

Các phần sau đây giải thích quy trình xác thực danh mục nội bộ và thương lượng giản đồ.

Hành trình của người dùng trong việc quản lý danh mục giới thiệu các API chính sau đây:

A2uiCatalog: Giao diện và hàm cấp cao nhất của nhà máy để xác định danh mục thành phần.
materialA2uiBasicCatalogVX: Các hàm ở trạng thái ban đầu theo phiên bản (chẳng hạn như materialA2uiBasicCatalogV1) cung cấp việc triển khai Material 3 theo quy cách Danh mục cơ bản A2UI tiêu chuẩn.
A2uiReadinessEvaluator và asReadinessEvaluator(): A2uiReadinessEvaluator là giao diện để đánh giá mức độ sẵn sàng của thành phần. Hàm tiện ích asReadinessEvaluator() giải quyết các trạng thái sẵn sàng bằng cách sử dụng các thành phần đã đăng ký trong danh mục.

Danh mục phiên bản và lược đồ thành phần A2UI

Định nghĩa giản đồ danh mục được liên kết với một phiên bản giao thức cụ thể. Khi giao thức phát triển, định nghĩa danh mục sẽ nâng cấp phiên bản. Các hoạt động triển khai thành phần cho phiên bản tiếp theo này có thể sử dụng các API trình kết xuất đã cập nhật trong khi các phiên bản thấp hơn vẫn hoạt động song song.

Tổng quan

Tiếp

Nền tảng kết xuất

Tạo và tuỳ chỉnh danh mục thành phần Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.