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

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

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

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

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

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

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

Одним из основных преимуществ использования составных элементов @Preview является отсутствие зависимости от эмулятора в 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

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

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

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

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

Если параметр устройства имеет пустую строку ( @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

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

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

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

Системный интерфейс

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

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

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

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

LocalInspectionMode

Вы можете прочитать из LocalInspectionMode CompositionLocal чтобы узнать, отображается ли составной объект в предварительном просмотре (внутри проверяемого компонента ). Если композиция отображается в предварительном просмотре, 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 предоставляет функции, которые позволяют вам взаимодействовать с заданными вами предпросмотрами. Это взаимодействие помогает вам понять поведение ваших предварительных просмотров во время выполнения и позволяет лучше ориентироваться в пользовательском интерфейсе с помощью предварительных просмотров.

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

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

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

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

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

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

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

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

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

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

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

Шаблоны мультипредпросмотра

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

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

@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

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

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

Очень часто возникает необходимость передать большой набор данных в компонуемый предварительный просмотр. Для этого просто передайте пример данных в функцию Composable 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 для их отображения. Однако это имеет следующие ограничения:

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

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

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

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

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

@Composable
fun AuthorColumn(viewModel: AuthorViewModel = viewModel()) {
  AuthorColumn(
    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]
) {
  AuthorColumn(...) {
    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 .