# 📱 UI-элементы SDK

Эта страница — справочник по UI-элементам мобильных SDK Gravity Field для Android и Flutter. Ниже описаны структура JSON, способы отображения кампаний, оформление контейнера frameUI, каталог элементов и общие типы Style/OnClick.

# Архитектура и модель данных

Кампания описывается объектом CampaignContent, который содержит способ показа (deliveryMethod) и данные для отрисовки (variables). Внутри variables задается внешний контейнер (frameUI), список элементов (elements) и события жизненного цикла.

graph TD
    C[CampaignContent JSON] --> D[deliveryMethod]
    C --> V[variables]

    V --> F[frameUI]
    V --> E[elements array]
    V --> L[onLoad / onImpression / onVisibleImpression / onClose]

    F --> FC[container.style]
    F --> CL["close (icon + onClick)"]

    E --> T[Text]
    E --> I[Image]
    E --> B[Button]
    E --> S[Spacer]
    E --> W[WebView]
    E --> P[ProductsContainer]

Базовый скелет JSON:

{
  "deliveryMethod": "modal",
  "variables": {
    "frameUI": { ... },
    "elements": [ ... ],
    "onLoad": { "action": "load" },
    "onImpression": { "action": "impression" },
    "onVisibleImpression": { "action": "visible_impression" },
    "onClose": { "action": "close" }
  }
}

Общие объекты Style и OnClick, используемые в разных секциях, собраны в конце документа в разделе Общие объекты.

# Способы отображения кампании (`deliveryMethod`)

Поле deliveryMethod определяет, как кампания будет показана пользователю. Передается в корневом объекте контента рядом с variables.

Значение	Описание
`modal`	Модальное окно по центру экрана.
`bottom_sheet`	Шторка, выезжающая снизу экрана.
`full_screen`	Полноэкранное окно, перекрывающее весь контент.
`snackbar`	Всплывающее уведомление (сверху или снизу).
`inline`	Встроенный блок в верстке приложения. Требует размещения `GravityInlineView` (Android) или `GravityInlineWidget` (Flutter) в коде.

# Пример JSON

{
  "deliveryMethod": "modal",
  "variables": {
    "frameUI": { ... },
    "elements": [ ... ]
  }
}

# `FrameUI`: оформление корневого контейнера

frameUI управляет внешним видом рамки кампании (фон, скругления, отступы) и отображением кнопки закрытия. Размещается в variables на одном уровне с elements.

# `frameUI.container`

Главный контейнер, в который помещаются все элементы кампании.

Параметр	Описание	Тип данных	Android	Flutter	Пример значения
`style.backgroundColor`	Цвет фона контейнера.	`String` (HEX)	✅	✅	`"#FFFFFF"`
`style.cornerRadius`	Скругление углов контейнера.	`Number`	✅	✅	`16`
`style.padding`	Внутренние отступы контейнера.	`Object` (`top`, `bottom`, `left`, `right`)	✅	✅	`{"top": 20, "bottom": 20, "left": 16, "right": 16}`
`style.backgroundImage`	Опциональное фоновое изображение.	`String` (URL)	✅	✅	`"https://.../bg.png"`
`style.backgroundFit`	Правило масштабирования фонового изображения.	`String` (`cover`, `contain`, `fill`)	✅	✅	`"cover"`
`onClick`	Действие при нажатии на фон (чаще всего пусто или `close`).	`Object`	✅	✅	`{"action": "close"}`

# `frameUI.close`

Настройки кнопки закрытия. Если объект отсутствует, кнопка не рисуется.

Параметр	Описание	Тип данных	Android	Flutter	Пример значения
`image`	Кастомная иконка закрытия.	`String` (URL)	✅	✅	`"https://.../close.png"`
`style.positioned`	Абсолютное позиционирование иконки.	`Object` (`top`, `right`, `left`, `bottom`)	✅	✅	`{"top": 10, "right": 10}`
`style.size`	Размеры иконки/зоны нажатия.	`Object` (`width`, `height`)	✅	✅	`{"width": 24, "height": 24}`
`onClick`	Действие при нажатии (для закрытия — `{"action": "close"}`).	`Object`	✅	✅	`{"action": "close"}`

# Пример JSON

{
  "deliveryMethod": "modal",
  "variables": {
    "frameUI": {
      "container": {
        "style": {
          "backgroundColor": "#FFFFFF",
          "cornerRadius": 16,
          "padding": { "top": 20, "bottom": 20, "left": 16, "right": 16 }
        }
      },
      "close": {
        "image": "https://example.com/icons/close.png",
        "style": {
          "size": { "width": 24, "height": 24 },
          "positioned": { "top": 10, "right": 10 }
        },
        "onClick": { "action": "close" }
      }
    },
    "elements": [
      {
        "type": "text",
        "text": "Привет, мир!"
      }
    ]
  }
}

# UI Elements (`variables.elements`)

Все UI-элементы описываются в массиве variables.elements. Каждый элемент — это JSON-объект с обязательным полем type и опциональным полем style для кастомизации. В таблицах ниже для каждого параметра указана его поддержка на платформах Android и Flutter.

✅ — Поддерживается
❌ — Не поддерживается

# `Text`

Элемент для отображения текстового контента.

Параметр	Описание	Тип данных	Android	Flutter	Пример значения
`text`	Текст для отображения.	`String`	✅	✅	`"Скидка 20%"`
`style.textColor`	Цвет текста.	`String` (HEX)	✅	✅	`"#333333"`
`style.fontSize`	Размер шрифта.	`Number`	✅	✅	`16`
`style.fontWeight`	Насыщенность шрифта.	`String` ("100"-"900")	✅	✅	`"700"`
`style.contentAlignment`	Горизонтальное выравнивание текста.	`String` (`start`, `center`, `end`)	✅	✅	`"center"`
`style.margin`	Внешние отступы.	`Object`	✅	✅	`{"top": 8, "bottom": 8}`

# Пример JSON

{
  "type": "text",
  "text": "Специальное предложение!",
  "style": {
    "fontSize": 20,
    "fontWeight": "700",
    "textColor": "#1A1A1A",
    "contentAlignment": "center",
    "margin": { "bottom": 16 }
  }
}

# `Image`

Элемент для отображения изображений по URL.

Параметр	Описание	Тип данных	Android	Flutter	Пример значения
`src`	URL-адрес изображения.	`String`	✅	✅	`"https://.../image.png"`
`style.size`	Размеры изображения.	`Object` (`width`, `height`)	✅	✅	`{"height": 150}`
`style.fit`	Режим масштабирования.	`String` (`cover`, `contain`, `fill`)	✅	✅	`"cover"`
`style.cornerRadius`	Радиус скругления углов.	`Number`	✅	✅	`12`
`style.layoutWidth`	Поведение ширины.	`String` (`match_parent`, `wrap_content`)	✅	✅	`"match_parent"`
`style.margin`	Внешние отступы.	`Object`	✅	✅	`{"top": 16}`
`onClick`	Действие при клике.	`Object`	✅	✅	`{"action": "follow_url", "url": "..."}`

# Пример JSON

{
  "type": "image",
  "src": "https://example.com/promo_banner.jpg",
  "style": {
    "size": { "height": 180 },
    "layoutWidth": "match_parent",
    "fit": "cover",
    "cornerRadius": 16
  },
  "onClick": {
    "action": "follow_deeplink",
    "deeplink": "app://sale/summer-2024"
  }
}

# `Button`

Интерактивный элемент-кнопка.

Параметр	Описание	Тип данных	Android	Flutter	Пример значения
`text`	Текст на кнопке.	`String`	✅	✅	`"Купить"`
`style.backgroundColor`	Цвет фона кнопки.	`String` (HEX)	✅	✅	`"#007AFF"`
`style.pressColor`	Цвет при нажатии (эффект ripple).	`String` (HEX)	✅	✅	`"#0056B3"`
`style.cornerRadius`	Радиус скругления углов.	`Number`	✅	✅	`8`
`style.size`	Размеры кнопки. Обычно используется только `height`.	`Object` (`height`)	✅	✅	`{"height": 48}`
`style.layoutWidth`	Поведение ширины.	`String` (`match_parent`, `wrap_content`)	✅	✅	`"match_parent"`
`style.textStyle`	Стили для текста внутри кнопки.	`Object`	✅	✅	`{"color": "#FFFFFF", "fontWeight": "600"}`
`onClick`	Действие при клике.	`Object`	✅	✅	`{"action": "close"}`

# Пример JSON

{
  "type": "button",
  "text": "Перейти в каталог",
  "style": {
    "backgroundColor": "#007AFF",
    "cornerRadius": 8,
    "size": { "height": 48 },
    "layoutWidth": "match_parent",
    "textStyle": {
      "color": "#FFFFFF",
      "fontWeight": "600"
    }
  },
  "onClick": {
    "action": "follow_deeplink",
    "deeplink": "app://catalog"
  }
}

# `Spacer`

Невидимый элемент, который занимает доступное пространство. Используется для гибкого позиционирования других элементов.

Параметр	Описание	Тип данных	Android	Flutter	Пример значения
`style.weight`	Коэффициент растяжения. Чем больше значение, тем больше места займет элемент.	`Number`	✅	❌	`1`

# Пример JSON

Используйте Spacer, чтобы "прижать" кнопку к низу экрана:

"elements": [
  {
    "type": "text",
    "text": "Заголовок вверху"
  },
  {
    "type": "spacer"
  },
  {
    "type": "button",
    "text": "Кнопка внизу"
  }
]

# `WebView`

Элемент для встраивания веб-страниц непосредственно в UI кампании.

Параметр	Описание	Тип данных	Android	Flutter	Пример значения
`src`	URL-адрес страницы для загрузки.	`String`	✅	✅	`"https://example.com"`
`style.size`	Размеры веб-вью.	`Object` (`width`, `height`)	✅	✅	`{"height": 300}`
`style.margin`	Внешние отступы.	`Object`	✅	✅	`{"top": 10}`

# Пример JSON

{
  "type": "webview",
  "src": "https://example.com/survey-form",
  "style": {
    "size": { "height": 400 },
    "layoutWidth": "match_parent"
  }
}

# `ProductsContainer`

Контейнер для отображения списка товарных рекомендаций. Данные о товарах (products) передаются на одном уровне с variables.

Параметр	Описание	Тип данных	Android	Flutter	Пример значения
`style.productContainerType`	Режим отображения: `row` (горизонтальный список) или `grid` (сетка).	`String`	✅	✅	`"grid"`
`style.size`	Размеры контейнера. Обычно используется только `height`.	`Object` (`height`)	✅	✅	`{"height": 280}`
`style.gridColumns`	Количество колонок для режима `grid`.	`Number`	✅	❌	`2`
`style.gridSettings`	Настройки сетки: `columns`, `horizontalSpacing`, `verticalSpacing`.	`Object`	❌	✅	`{"columns": 2, "horizontalSpacing": 8}`

# Пример JSON

{
  "type": "products-container",
  "style": {
    "productContainerType": "grid",
    "gridColumns": 2,
    "gridSettings": {
      "columns": 2,
      "horizontalSpacing": 8,
      "verticalSpacing": 8
    }
  }
}

# Общие объекты (`Style` и `OnClick`)

Эти объекты используются в разных разделах (frameUI, элементы и т.д.), поэтому их спецификация вынесена отдельно.

# `Style`

Параметр	Описание	Тип данных	Android	Flutter	Пример значения
`backgroundColor`	Цвет фона.	`String` (HEX)	✅	✅	`"#FFFFFF"`
`backgroundImage`	Фоновое изображение.	`String` (URL)	✅	✅	`"https://.../bg.png"`
`backgroundFit`	Режим масштабирования фонового изображения (`cover`, `contain`, `fill`).	`String`	✅	✅	`"cover"`
`pressColor`	Цвет нажатия (ripple).	`String` (HEX)	✅	✅	`"#0056B3"`
`outlineColor`	Цвет обводки.	`String` (HEX)	✅	✅	`"#E0E0E0"`
`cornerRadius`	Скругление углов.	`Number`	✅	✅	`12`
`size`	Размеры элемента.	`Object` (`width`, `height`)	✅	✅	`{"height": 48}`
`margin` / `padding`	Внешние/внутренние отступы.	`Object` (`top`, `bottom`, `left`, `right`)	✅	✅	`{"top": 8, "bottom": 8}`
`fontSize`	Размер шрифта.	`Number`	✅	✅	`16`
`fontWeight`	Толщина шрифта (`100`-`900`).	`String`	✅	✅	`"700"`
`textColor`	Цвет текста.	`String` (HEX)	✅	✅	`"#1A1A1A"`
`textStyle`	Стили текста внутри кнопок.	`Object`	✅	✅	`{"color": "#FFFFFF", "fontWeight": "600"}`
`fit`	Режим масштабирования для изображений (`cover`, `contain`, `fill`).	`String`	✅	✅	`"cover"`
`contentAlignment`	Выравнивание контента (`start`, `center`, `end`).	`String`	✅	✅	`"center"`
`layoutWidth`	Поведение ширины (`match_parent`, `wrap_content`).	`String`	✅	✅	`"match_parent"`
`positioned`	Абсолютное позиционирование.	`Object` (`top`, `bottom`, `left`, `right`)	✅	✅	`{"top": 10, "right": 10}`
`weight`	Коэффициент растяжения для `Spacer`.	`Number`	✅	❌	`1`
`productContainerType`	Тип отображения товаров (`row`, `grid`).	`String`	✅	✅	`"grid"`
`gridColumns`	Количество колонок для сетки товаров.	`Number`	✅	❌	`2`

# `OnClick`

Определяет действие при нажатии на элемент.

Поле	Описание	Пример
`action`	Тип действия: `follow_url`, `follow_deeplink`, `copy`, `close`, `request_push`, `request_tracking`.	`"action": "close"`
`url`	URL для `follow_url`.	`"url": "https://example.com"`
`deeplink`	Диплинк для `follow_deeplink`.	`"deeplink": "app://sale"`
`copyData`	Данные для копирования для `copy`.	`"copyData": "SAVE10"`
`closeOnClick`	Закрывать ли кампанию после действия (по умолчанию `true`).	`"closeOnClick": true`

# 📱 UI-элементы SDK

# Архитектура и модель данных

# Способы отображения кампании (deliveryMethod)

# Пример JSON

# FrameUI: оформление корневого контейнера

# frameUI.container

# frameUI.close

# Пример JSON

# UI Elements (variables.elements)

# Text

# Пример JSON

# Image

# Пример JSON

# Button

# Пример JSON

# Spacer

# Пример JSON

# WebView

# Пример JSON

# ProductsContainer

# Пример JSON

# Общие объекты (Style и OnClick)

# Style

# OnClick

# Способы отображения кампании (`deliveryMethod`)

# `FrameUI`: оформление корневого контейнера

# `frameUI.container`

# `frameUI.close`

# UI Elements (`variables.elements`)

# `Text`

# `Image`

# `Button`

# `Spacer`

# `WebView`

# `ProductsContainer`

# Общие объекты (`Style` и `OnClick`)

# `Style`

# `OnClick`