Предварительный просмотр вашего пользовательского интерфейса с помощью составных предпросмотров

Компонуемый объект определяется функцией и аннотируется @Composable : 

@Composable
fun SimpleComposable() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

Простой текстовый элемент, содержащий слова «Hello World»

Чтобы включить предварительный просмотр этого компонуемого объекта, создайте другой компонуемый объект, аннотированный @Composable и @Preview . Этот новый аннотированный компонуемый объект теперь содержит компонуемый объект, который вы создали изначально, SimpleComposable : 

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}
AndroidStudioComposeSnippets.kt

Аннотация @Preview сообщает Android Studio, что этот компонуемый объект должен отображаться в представлении дизайна этого файла. Вы можете видеть обновления в реальном времени для вашего компонуемого предварительного просмотра по мере внесения изменений.

GIF-анимация, показывающая обновления в реальном времени с помощью Compose Предварительный просмотр

Вы можете вручную добавлять параметры в свой код, чтобы настроить способ, которым Android Studio отображает @Preview . Вы даже можете добавить аннотацию @Preview к одной и той же функции несколько раз, чтобы просмотреть составной объект с разными свойствами.

Одним из основных преимуществ использования @Preview composables является отказ от зависимости от эмулятора в Android Studio. Вы можете сохранить ресурсоемкий запуск эмулятора для более окончательных изменений внешнего вида и функций, а также способность @Preview с легкостью вносить и тестировать небольшие изменения кода.

Чтобы использовать аннотацию @Preview наиболее эффективно, обязательно определите свои экраны с точки зрения состояния, которое они получают в качестве входных данных, и событий, которые они выводят.

Определите свой @Preview

Android Studio предлагает некоторые функции для расширения компонуемых предпросмотров. Вы можете изменить дизайн их контейнера, взаимодействовать с ними или развернуть их напрямую на эмуляторе или устройстве.

Размеры

По умолчанию размеры @Preview выбираются автоматически для переноса его содержимого. Чтобы задать размеры вручную, добавьте параметры heightDp и widthDp . Эти значения уже интерпретируются как dp , поэтому вам не нужно добавлять к ним .dp : 

@Preview(widthDp = 50, heightDp = 50)
@Composable
fun SquareComposablePreview() {
    Box(Modifier.background(Color.Yellow)) {
        Text("Hello World")
    }
}
AndroidStudioComposeSnippets.kt

Желтый квадрат со словами «Hello World»

Динамический предварительный просмотр цвета

Если вы включили динамический цвет в своем приложении, используйте атрибут wallpaper для переключения обоев и посмотрите, как ваш пользовательский интерфейс реагирует на выбранные обои разных пользователей. Выберите из различных тем обоев, предлагаемых классом Wallpaper . Для этой функции требуется Compose 1.4.0 или выше.

Использование с разными устройствами

В Android Studio Flamingo вы можете редактировать параметр device аннотации Preview, чтобы определить конфигурации для ваших компонуемых объектов на разных устройствах.

Образец компонуемой функции

Если параметр устройства имеет пустую строку ( @Preview(device = "") ), вы можете вызвать автозаполнение, нажав Ctrl + Space . Затем вы можете задать значения каждого параметра.

Редактирование образца функции

Из автозаполнения вы можете выбрать любой вариант устройства из списка, например, @Preview(device = "id:pixel_4") . В качестве альтернативы вы можете ввести пользовательское устройство, выбрав spec:width=px,height=px,dpi=int… чтобы задать индивидуальные значения каждого параметра.

Список спец.

Чтобы применить, нажмите Enter или отмените, нажав Esc .

Если вы установили недопустимое значение, объявление будет подчеркнуто красным, и может быть доступно исправление ( Alt + Enter (⌥ + ⏎ для macOS) > Заменить на … ). Проверка попытается предоставить исправление, которое наиболее близко соответствует введенным вами данным.

Пример недопустимого значения

Локаль

Чтобы протестировать различные локали пользователя, добавьте параметр locale : 

@Preview(locale = "fr-rFR")
@Composable
fun DifferentLocaleComposablePreview() {
    Text(text = stringResource(R.string.greeting))
}
AndroidStudioComposeSnippets.kt

Простой текстовый элемент, содержащий слово «Bonjour» с французским флагом

Установить цвет фона

По умолчанию ваш компонуемый элемент отображается с прозрачным фоном. Чтобы добавить фон, добавьте параметры showBackground и backgroundColor . Помните, что backgroundColor — это значение ARGB Long , а не Color : 

@Preview(showBackground = true, backgroundColor = 0xFF00FF00)
@Composable
fun WithGreenBackground() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

Зеленый прямоугольник со словами «Hello World»

Системный пользовательский интерфейс

Если вам необходимо отобразить панели состояния и действий внутри предварительного просмотра, добавьте параметр showSystemUi : 

@Preview(showSystemUi = true)
@Composable
fun DecoratedComposablePreview() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

Окно предварительного просмотра, отображающее действие с панелями состояния и действий.

Режим пользовательского интерфейса

Параметр uiMode может принимать любые константы Configuration.UI_* и позволяет вам изменять поведение предварительного просмотра соответствующим образом. Например, вы можете установить предварительный просмотр в Ночной режим, чтобы увидеть, как реагирует тема.

Интерфейс предварительного просмотра создания

LocalInspectionMode

Вы можете прочитать из LocalInspectionMode CompositionLocal , чтобы увидеть, отображается ли компонуемый объект в предварительном просмотре (внутри компонента inspectable ). Если композиция отображается в предварительном просмотре, LocalInspectionMode.current оценивается как true . Эта информация позволяет вам настраивать предварительный просмотр; например, вы можете отображать изображение-заполнитель в окне предварительного просмотра вместо отображения реальных данных.

Таким образом, вы также можете обойти ограничения . Например, показывая образцы данных вместо вызова сетевого запроса. 

@Composable
fun GreetingScreen(name: String) {
    if (LocalInspectionMode.current) {
        // Show this text in a preview window:
        Text("Hello preview user!")
    } else {
        // Show this text in the app:
        Text("Hello $name!")
    }
}
AndroidStudioComposeSnippets.kt

Взаимодействуйте с вашим @Preview

Android Studio предоставляет функции, которые позволяют вам взаимодействовать с вашими определенными предпросмотрами. Это взаимодействие помогает вам понять поведение времени выполнения ваших предпросмотров и позволяет вам лучше ориентироваться в вашем пользовательском интерфейсе с предпросмотрами.

Интерактивный режим

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

Пользователь, нажимающий кнопку «интерактивного» предварительного просмотра

Видео пользователя, взаимодействующего с превью

Навигация по коду и компонуемые контуры

Вы можете навести курсор на предварительный просмотр, чтобы увидеть контуры компонуемых элементов, содержащихся в нем. Нажатие на компонуемый контур активирует представление редактора для перехода к его определению.

Пользователь наводит курсор на предварительный просмотр, заставляя Studio отображать контуры его компонуемых объектов

Запустить предварительный просмотр

Вы можете запустить определенный @Preview на эмуляторе или физическом устройстве. Предварительный просмотр развертывается в том же приложении проекта, что и новое Activity , поэтому он использует тот же контекст и разрешения. Вам не нужно писать шаблонный код, запрашивающий разрешение, если оно уже было предоставлено.

Нажмите на значок «Запустить предварительный просмотр». Запустить предварительный просмотр значок рядом с аннотацией @Preview или в верхней части предварительного просмотра, и Android Studio развернет этот @Preview на подключенном устройстве или эмуляторе.

Пользователь, нажимающий кнопку «запустить предварительный просмотр»

Видео пользователя, развертывающего предварительный просмотр на устройстве

Копировать @Preview рендер

Каждый визуализированный превью можно скопировать как изображение, щелкнув по нему правой кнопкой мыши.

Пользователь нажимает на предварительный просмотр, чтобы скопировать его как изображение.

Несколько предварительных просмотров одной и той же аннотации @Preview

Вы можете продемонстрировать несколько версий одного и того же @Preview composable с разными спецификациями или разными параметрами, переданными composable. Таким образом, вы можете сократить шаблонный код, который вам пришлось бы написать в противном случае.

Шаблоны многопросмотра

androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ представляет шаблоны API Multipreview: @PreviewScreenSizes , @PreviewFontScales , @PreviewLightDark и @PreviewDynamicColors , так что с помощью одной единственной аннотации вы можете предварительно просмотреть свой пользовательский интерфейс Compose в распространенных сценариях.

Предварительный просмотр различных шрифтов и размеров экрана с использованием шаблонов

Создавайте пользовательские аннотации с множественным предпросмотром

С помощью multipreview вы можете определить класс аннотации, который сам по себе имеет несколько аннотаций @Preview с различными конфигурациями. Добавление этой аннотации к компонуемой функции автоматически отображает все различные предпросмотры одновременно. Например, вы можете использовать эту аннотацию для предварительного просмотра нескольких устройств, размеров шрифтов или тем одновременно, не повторяя эти определения для каждого компонуемого объекта.

Начните с создания собственного класса аннотаций: 

@Preview(
    name = "small font",
    group = "font scales",
    fontScale = 0.5f
)
@Preview(
    name = "large font",
    group = "font scales",
    fontScale = 1.5f
)
annotation class FontScalePreviews
AndroidStudioComposeSnippets.kt

Вы можете использовать эту пользовательскую аннотацию для предпросмотра ваших компонуемых объектов: 

@FontScalePreviews
@Composable
fun HelloWorldPreview() {
    Text("Hello World")
}
AndroidStudioComposeSnippets.kt

Вкладка дизайна Android Studio, на которой показана композиция с мелким и крупным шрифтом

Вы можете объединить несколько аннотаций multipreview и обычных аннотаций preview, чтобы создать более полный набор предпросмотров. Объединение аннотаций multipreview не означает, что будут показаны все различные комбинации. Вместо этого каждая аннотация multipreview действует независимо и отображает только свои собственные варианты. 

@Preview(
    name = "Spanish",
    group = "locale",
    locale = "es"
)
@FontScalePreviews
annotation class CombinedPreviews

@CombinedPreviews
@Composable
fun HelloWorldPreview2() {
    MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } }
}
AndroidStudioComposeSnippets.kt

Вкладка дизайна Android Studio, показывающая компонуемый во всех конфигурациях

Комбинированный характер множественного предварительного просмотра (и обычного предварительного просмотра!) позволяет более полно тестировать многие свойства крупномасштабных проектов.

@Preview и большие наборы данных

Очень часто возникает необходимость передать большой набор данных в ваш компонуемый предварительный просмотр. Чтобы сделать это, просто передайте выборочные данные в функцию компонуемого предварительного просмотра, добавив параметр с аннотацией @PreviewParameter . 

@Preview
@Composable
fun UserProfilePreview(
    @PreviewParameter(UserPreviewParameterProvider::class) user: User
) {
    UserProfile(user)
}

AndroidStudioComposeSnippets.kt

Чтобы предоставить образец данных, создайте класс, который реализует PreviewParameterProvider и возвращает образец данных в виде последовательности. 

class UserPreviewParameterProvider : PreviewParameterProvider<User> {
    override val values = sequenceOf(
        User("Elise"),
        User("Frank"),
        User("Julia")
    )
}
AndroidStudioComposeSnippets.kt

Это позволяет отобразить один предварительный просмотр для каждого элемента данных в последовательности:

Предварительные просмотры Элис, Фрэнка и Джулии композиты

Вы можете использовать один и тот же класс поставщика для нескольких предпросмотров. При необходимости ограничьте количество предпросмотров, установив параметр limit. 

@Preview
@Composable
fun UserProfilePreview2(
    @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User
) {
    UserProfile(user)
}
AndroidStudioComposeSnippets.kt

Ограничения и передовой опыт

Android Studio выполняет код предпросмотра непосредственно в области предпросмотра. Для этого не требуется запуск эмулятора или физического устройства, поскольку он использует перенесенную часть фреймворка Android под названием Layoutlib . Layoutlib — это пользовательская версия фреймворка Android, разработанная для работы вне устройств Android. Цель библиотеки — предоставить предварительный просмотр макета в Android Studio, который очень близок к его отображению на устройствах.

Ограничения превью

Из-за способа, которым предварительные просмотры визуализируются в Android Studio, они являются легкими и не требуют всего фреймворка Android для их визуализации. Однако это имеет следующие ограничения:

  • Нет доступа к сети
  • Нет доступа к файлу
  • Некоторые API-интерфейсы Context могут быть недоступны в полной мере.

Превью и ViewModels

Предварительные просмотры ограничены при использовании ViewModel в компонуемом объекте. Система предварительных просмотров не способна построить все параметры, переданные ViewModel , такие как репозитории, варианты использования, менеджеры и т. п. Кроме того, если ваша ViewModel участвует во внедрении зависимостей (например, с Hilt ), система предварительных просмотров не может построить весь граф зависимостей для построения ViewModel .

При попытке предварительного просмотра составного объекта с помощью ViewModel Android Studio выдает ошибку при рендеринге конкретного составного объекта:

Панель проблем Android Studio с сообщением Failed to instanceiate a `ViewModel`

Если вы хотите просмотреть компонуемый объект, который использует ViewModel , вам следует создать другой компонуемый объект с параметрами из ViewModel , переданными в качестве аргументов компонуемого объекта. Таким образом, вам не нужно просматривать компонуемый объект, который использует ViewModel . 

@Composable
fun AuthorScreen(viewModel: AuthorViewModel = viewModel()) {
  AuthorScreen(
    name = viewModel.authorName,
    // ViewModel sends the network requests and makes posts available as a state
    posts = viewModel.posts
  )
}

@Preview
@Composable
fun AuthorScreenPreview(
  // You can use some sample data to preview your composable without the need to construct the ViewModel
  name: String = sampleAuthor.name,
  posts: List<Post> = samplePosts[sampleAuthor]
) {
  AuthorScreen(...) {
    name = NameLabel(name),
    posts = PostsList(posts)
  }
}

Класс аннотации @Preview

Вы всегда можете нажать Ctrl или ⌘ + щелкнуть мышью по аннотации @Preview в Android Studio, чтобы получить полный список параметров, которые можно настроить при настройке предварительного просмотра. 

annotation class Preview(
    val name: String = "",
    val group: String = "",
    @IntRange(from = 1) val apiLevel: Int = -1,
    val widthDp: Int = -1,
    val heightDp: Int = -1,
    val locale: String = "",
    @FloatRange(from = 0.01) val fontScale: Float = 1f,
    val showSystemUi: Boolean = false,
    val showBackground: Boolean = false,
    val backgroundColor: Long = 0,
    @UiMode val uiMode: Int = 0,
    @Device val device: String = Devices.DEFAULT,
    @Wallpaper val wallpaper: Int = Wallpapers.NONE,
)
AndroidStudioComposeSnippets.kt

Дополнительные ресурсы

Чтобы узнать больше о том, как Android Studio способствует простоте использования @Preview , а также узнать больше советов по инструментам, посетите блог Compose Tooling .

{% дословно %} {% endverbatim %} {% дословно %} {% endverbatim %}
Далее
Предварительный просмотр и отладка анимации