Cómo obtener una vista previa de tu IU con vistas previas componibles

Una función define un elemento componible y se anota con @Composable:

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

Un elemento de texto simple que contiene las palabras "Hello
Internacional"

Para habilitar una vista previa de este elemento componible, crea otro elemento componible con @Composable y @Preview. Este nuevo elemento componible con anotaciones ahora contiene el elemento componible que creaste inicialmente, SimpleComposable:

@Preview
@Composable
fun SimpleComposablePreview() {
    SimpleComposable()
}

La anotación @Preview le indica a Android Studio que este componible debería mostrarse en la vista de diseño de este archivo. Puedes ver actualizaciones de la vista previa del elemento componible a medida que realizas ediciones.

GIF que muestra actualizaciones en tiempo real con Compose
Vista previa

Puedes agregar parámetros de forma manual en tu código para personalizar la forma en que Android Studio renderiza @Preview. Incluso puedes agregar la anotación @Preview al mismo varias veces para obtener una vista previa de un elemento componible con diferentes propiedades.

Uno de los beneficios principales de usar elementos @Preview componibles es evitar la dependencia. en el emulador en Android Studio. Puedes guardar el inicio que consume mucha memoria de la para obtener cambios de apariencia y estilo más definitivos, y la capacidad de @Preview para realizar y probar pequeños cambios de código con facilidad.

Para aprovechar la anotación @Preview de la manera más eficaz, asegúrate de definir tu pantallas en términos del estado que recibe como entrada y los eventos que de salida.

Define tu @Preview

Android Studio ofrece algunas funciones para extender vistas previas componibles. Puedes cambiar el diseño de los contenedores, interactuar con ellos o implementarlos directamente en un emulador o dispositivo.

Dimensiones

De forma predeterminada, las dimensiones de @Preview se eligen automáticamente para unir su contenido. Para configurar las dimensiones manualmente, agrega los parámetros heightDp y widthDp. Los que los valores ya se interpretan como dp, por lo que no es necesario agregar .dp para ellos:

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

Un cuadrado amarillo con las palabras "Hola
Internacional"

Vista previa del color dinámico

Si habilitaste las funciones dinámicas color en tu app Usa el atributo wallpaper para cambiar de fondo de pantalla y ver cómo reacciona la IU a diferentes usuarios fondo de pantalla elegido. Selecciona entre los diferentes temas de fondos de pantalla que ofrece la Wallpaper clase. Esta función requiere Compose 1.4.0 o una versión posterior.

Uso con diferentes dispositivos

En Android Studio Flamingo, puedes editar el parámetro device de la vista previa. de elementos componibles para definir configuraciones de tus elementos componibles en diferentes dispositivos.

Componible de muestra
función

Cuando el parámetro del dispositivo tiene una cadena vacía (@Preview(device = "")), puedes Para invocar la función, presiona Ctrl + Space. Luego, puedes establecer los valores de cada parámetro.

Edición de la muestra
función

En Autocompletar, puedes seleccionar cualquier opción de dispositivo de la lista, por ejemplo, @Preview(device = "id:pixel_4") También puedes ingresar un dispositivo personalizado eligiendo spec:width=px,height=px,dpi=int… para establecer los valores individuales de cada parámetro.

Especificaciones
incluir en una ficha

Para aplicar esta opción, presiona Enter o cancela la acción con Esc.

Si estableces un valor no válido, la declaración aparecerá subrayada en rojo y es posible que se aplique una corrección. estar disponible (Alt + Enter (⌥ + ⏎ para macOS) > Replace with .... La inspección intenta proporcionar una solución que se parezca más a tu entrada.

Ejemplo de no válido
valor

Configuración regional

Para probar diferentes configuraciones regionales de usuario, agrega el parámetro locale:

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

Un elemento de texto simple que contiene la palabra "Bonjour" con un francés
marca

Cómo establecer un color de fondo

De forma predeterminada, el elemento componible se muestra con un fondo transparente. Para agregar un segundo plano, agrega los parámetros showBackground y backgroundColor. Conservar en Ten en cuenta que backgroundColor es un Long ARGB, no un Color. valor:

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

Un rectángulo verde con las palabras “Hello
Internacional"

IU del sistema

Si necesitas mostrar barras de estado y de acción dentro de una vista previa, agrega el parámetro showSystemUi:

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

Una ventana de vista previa que muestra una actividad con el estado y las barras de acciones.

Modo de IU

El parámetro uiMode puede tomar cualquiera de los Configuration.UI_* constantes y te permite cambiar el comportamiento de la vista previa según corresponda. Por ejemplo, puedes configurar la vista previa en Modo nocturno para la reacción del tema.

IU de la vista previa de Compose

LocalInspectionMode

Puedes leer desde el LocalInspectionMode CompositionLocal para ver si el elemento componible se renderiza en una vista previa (dentro de una componente inspeccionable). Si la composición se renderiza En una vista previa, LocalInspectionMode.current se evalúa como true. Esta la información te permite personalizar la vista previa; por ejemplo, puedes mostrar una imagen del marcador de posición en la ventana de vista previa en lugar de mostrar datos reales.

De esta manera, también puedes evitar las limitaciones. Para como datos de muestra en lugar de llamar a la solicitud de red.

@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!")
    }
}

Interactúa con tu @Preview

Android Studio ofrece funciones que te permiten interactuar con tu vistas previas. Esta interacción te permite comprender las vistas previas comportamiento del tiempo de ejecución y te permite navegar mejor por la IU con vistas previas.

Modo interactivo

El modo interactivo te permite interactuar con una vista previa de manera similar a como lo harías en un dispositivo en el que se ejecuta el programa, como un teléfono o una tablet. El modo interactivo está aislada en un entorno de zona de pruebas (es decir, aislada de otras vistas previas), donde puedes hacer clic en los elementos y, luego, ingresar la entrada del usuario en la vista previa. Es un breve manera de probar diferentes estados, gestos y hasta animaciones de tu elemento componible.

El usuario hace clic en la vista "interactiva" de la vista previa.
botón

Un video del usuario interactuando con una
vista previa

Navegación por código y esquemas componibles

Puedes desplazarte por sobre una vista previa para ver los contornos del elemento componible que contiene. Cuando haces clic en un esquema componible, se activa la vista de edición para navegar a su definición.

El usuario coloca el cursor sobre una vista previa, lo que hace que Studio muestre los esquemas de
es
elementos componibles

Ejecutar vista previa

Puedes ejecutar un @Preview específico en un emulador o dispositivo físico. El se implementa dentro de la misma app del proyecto que un Activity nuevo, por lo que comparte el mismo contexto y permisos. No requiere que escribas código estándar que solicita un permiso si ya se otorgó.

Haz clic en el ícono Run Preview Ejecutar vista previa
ícono. junto a la anotación @Preview o en la parte superior de la vista previa, y Android Studio implementa ese @Preview en tu dispositivo o emulador conectado.

El usuario hace clic en la opción "Ejecutar vista previa" de la vista previa.
botón

Video en el que se muestra cómo un usuario implementa una vista previa en la
dispositivo

Cómo copiar la renderización de @Preview

Se puede copiar cada vista previa renderizada como imagen haciendo clic con el botón derecho en ella.

El usuario hace clic en una vista previa para copiarla como una
imagen.

Varias vistas previas de la misma anotación @Preview

Puedes mostrar varias versiones del mismo elemento @Preview componible con diferentes especificaciones o diferentes parámetros que se pasan al elemento componible. Esta puedes reducir el código estándar que, de otro modo, tendrías que escribir.

Plantillas de vista previa múltiple

androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ presenta la vista previa múltiple. Plantillas de API: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark, y @PreviewDynamicColors, para que con una sola anotación puedas obtener una vista previa de la IU de Compose en situaciones comunes.

Cómo obtener una vista previa de diferentes fuentes y tamaños de pantalla con plantillas

Cómo crear anotaciones de vista previa múltiple personalizadas

Con la vista previa múltiple, puedes definir una clase de anotación que tenga varias anotaciones @Preview con configuraciones diferentes. Agregar esta anotación a una función de componibilidad renderiza automáticamente todas las vistas previas diferentes en una vez. Por ejemplo, puedes usar esta anotación para obtener una vista previa de varios dispositivos, tamaños de fuente o temas al mismo tiempo sin repetir esas definiciones para cada elemento componible.

Para comenzar, crea tu propia clase de anotación personalizada:

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

Puedes usarla para los elementos que admiten composición de la vista previa:

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

Pestaña Design de Android Studio que muestra el elemento componible con tamaño pequeño y grande
fuente

Puedes combinar varias anotaciones de vista previa múltiple y anotaciones de vista previa normal. para crear un conjunto más completo de vistas previas. Cómo combinar anotaciones de vista previa múltiple no significa que se muestran todas las combinaciones diferentes. En cambio, cada anotación de vista previa múltiple actúa de manera independiente y solo renderiza sus propias variantes.

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

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

La pestaña Design de Android Studio que muestra el elemento componible en todos
parámetros de configuración

La naturaleza de combinación de la vista previa múltiple y la vista previa normal te brinda más y probar de manera exhaustiva muchas propiedades de los proyectos a mayor escala.

@Preview y conjuntos de datos grandes

Con frecuencia, surge una necesidad en la que debes pasar un conjunto de datos grande a tu elemento componible vista previa. Para ello, simplemente pasa datos de muestra a una función de vista previa componible agregar un parámetro con @PreviewParameter .

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

Para proporcionar los datos de muestra, crea una clase que implemente PreviewParameterProvider y muestra el datos de muestra como una secuencia.

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

Esto genera una vista previa por elemento de datos en la secuencia:

Vistas previas en las que se muestran a Elise, Frank y Julia
elementos componibles

Puedes usar la misma clase de proveedor para varias vistas previas. Si es necesario, limita la cantidad de vistas previas estableciendo el parámetro de límite.

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

Limitaciones y prácticas recomendadas

Android Studio ejecuta el código de las vistas previas directamente en el área de la vista previa. No requerir la ejecución de un emulador o dispositivo físico, ya que aprovecha una conexión parte del framework de Android llamada Layoutlib. Layoutlib es una cuenta personalizada versión del framework de Android diseñada para ejecutarse fuera de dispositivos Android. El de la biblioteca es proporcionar una vista previa de un diseño en Android Studio que está muy cerca de su renderización en los dispositivos.

Limitaciones de las vistas previas

Debido a la forma en que se renderizan las vistas previas en Android Studio, se ligeros y no requieren todo el framework de Android para renderizarlos. Sin embargo, esto conlleva las siguientes limitaciones:

  • No tienes acceso a la red.
  • No tienes acceso al archivo.
  • Es posible que algunas APIs de Context no estén completamente disponibles.

Vistas previas y ViewModels

Las vistas previas están limitadas cuando se usa ViewModel en una componible. El sistema de vistas previas no puede construir todos los parámetros pasados a un ViewModel, como repositorios, casos de uso, administradores, o similares. Además, si tu ViewModel participa en la inserción de dependencias (como como con Hilt), el sistema de vistas previas no puede compilar toda la dependencia. gráfico para construir el ViewModel.

Cuando intentas obtener una vista previa de un elemento componible con ViewModel, Android Studio muestra un elemento cuando se renderiza el elemento componible específico:

Panel de problemas de Android Studio con Error al crear una instancia de &quot;ViewModel&quot;
mensaje

Si quieres obtener una vista previa de un elemento componible que usa un ViewModel, debes crear otro elemento componible con los parámetros de ViewModel pasados como argumentos de el elemento componible. De esta manera, no necesitas obtener una vista previa del elemento componible que usa el 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)
  }
}

Clase de anotación @Preview

Puedes presionar “Ctrl o ⌘ + clic” en cualquier momento la anotación @Preview en Android Studio para obtener una lista completa de los parámetros que se pueden ajustar cuando personalices vista previa.

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

Recursos adicionales

Para obtener más información sobre cómo Android Studio promueve la facilidad de uso de @Preview y obtén más información más consejos sobre herramientas, visita el blog Compose Herramientas.