Создание и настройка каталогов компонентов.

В архитектуре A2UI каждая поверхность управляется каталогом компонентов . Каталог представляет собой формальный контракт, определяющий компоненты пользовательского интерфейса, схемы свойств и локальные клиентские функции, доступные агенту ИИ. Вместо того чтобы генерировать произвольный код или изобретать неизвестные элементы, агент должен создавать пользовательские интерфейсы, используя исключительно компоненты, объявленные в каталоге.

Иными словами: каталог объявляет компоненты, а агент использует их для построения пользовательского интерфейса вашего приложения.

При создании Android-приложения с использованием рендерера Jetpack Compose A2UI у вас есть гибкие возможности для предоставления каталогов:

  • Базовый каталог : Проект 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 для воспроизведения, вы можете напрямую подключить эти существующие библиотеки к каталогу.

В следующем примере показано, как создать экземпляр базового каталога и подключить предпочитаемые медиатеки, средство открытия 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 UI см. в разделе «Реализация пользовательских компонентов 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 ), которые обеспечивают реализацию стандартной спецификации A2UI Basic Catalog в Material 3.
  • A2uiReadinessEvaluator и asReadinessEvaluator() : A2uiReadinessEvaluator — это интерфейс для оценки готовности компонентов. Функция расширения asReadinessEvaluator() определяет состояния готовности, используя компоненты, зарегистрированные в каталоге.

Каталог версий A2UI и схемы компонентов

Определение схемы каталога связано с конкретной версией протокола. При развитии протокола определение каталога обновляет свою версию. Реализации компонентов для этой следующей версии могут использовать обновленные API рендеринга, в то время как более старые версии остаются работоспособными параллельно.

Назад
Обзор
Далее
Рендеринг поверхностей