컴포저블은 함수에 의해 정의되고 @Composable
로 주석 처리됩니다.
@Composable fun SimpleComposable() { Text("Hello World") }
이 컴포저블의 미리보기를 사용 설정하려면 @Composable
및 @Preview
주석이 있는 다른 컴포저블을 만듭니다. 이제 주석이 추가된 이 새 컴포저블에는
처음에 만든 컴포저블 SimpleComposable
는 다음과 같습니다.
@Preview @Composable fun SimpleComposablePreview() { SimpleComposable() }
@Preview
주석은 Android 스튜디오에 다음과 같이 알려줍니다.
컴포저블이 이 파일의 디자인 뷰에 표시되어야 합니다. 라이브 스트림은
컴포저블 미리보기에 업데이트를 적용할 수 있습니다.
코드에 매개변수를 수동으로 추가하여 Android 스튜디오의 @Preview
렌더링 방식을 맞춤설정할 수 있습니다. 동일한 파일에 @Preview
주석을 추가할 수도 있습니다.
함수를 여러 번 사용하여 다양한 속성이 있는 컴포저블을 미리 볼 수 있습니다.
@Preview
컴포저블을 사용하는 주요 이점 중 하나는 Android 스튜디오에서 에뮬레이터를 사용하지 않아도 된다는 것입니다. 시작 지점에서 메모리를 많이 사용하는
에뮬레이터에서 최종 디자인과 분위기를 더 잘 변경할 수 있으며, @Preview
간단한 코드 변경사항을 쉽게 테스트할 수 있습니다.
@Preview
주석을 가장 효과적으로 활용하려면
화면, 입력으로 수신한 상태와
출력됩니다.
@Preview
정의
Android 스튜디오는 컴포저블 미리보기를 확장할 수 있는 기능을 제공합니다. 컨테이너 디자인을 변경하거나 미리보기와 상호작용하거나 에뮬레이터 또는 기기에 미리보기를 직접 배포할 수 있습니다.
크기
기본적으로 콘텐츠를 래핑하기 위해 @Preview
크기가 자동으로 선택됩니다.
크기를 수동으로 설정하려면 heightDp
및 widthDp
매개변수를 추가하세요. 이러한
값이 이미 dp
로 해석되므로 .dp
를 추가할 필요가 없습니다.
다음과 같습니다.
@Preview(widthDp = 50, heightDp = 50) @Composable fun SquareComposablePreview() { Box(Modifier.background(Color.Yellow)) { Text("Hello World") } }
동적 색상 미리보기
앱에서 동적 색상을 사용 설정한 경우 wallpaper
속성을 사용하여 배경화면을 전환하고 사용자가 선택한 여러 배경화면에 따라 UI가 어떻게 달라지는지 확인합니다. 다양한 배경화면 테마 중에서 선택
제공:
Wallpaper
클래스에 대해 자세히 알아보세요. 이 기능을 사용하려면 Compose 1.4.0 및 이후 버전이 필요합니다.
다양한 기기에서 사용
Android 스튜디오 Flamingo에서는 미리보기 주석의 device
매개변수를 수정하여 다양한 기기에서 컴포저블의 구성을 정의할 수 있습니다.
기기 매개변수에 빈 문자열(@Preview(device = "")
)이 있는 경우 Ctrl
+ Space
를 눌러 자동 완성을 호출할 수 있습니다. 그런 다음
지정할 수 있습니다.
자동 완성을 사용하면 목록에서 기기 옵션을 선택할 수 있습니다. 예를 들어
@Preview(device = "id:pixel_4")
또는 맞춤 기기를 입력할 수 있습니다.
spec:width=px,height=px,dpi=int…
를 선택하여
표시됩니다.
적용하려면 Enter
를 누르거나 Esc
로 취소하세요.
잘못된 값을 설정하면 선언에 빨간색으로 밑줄이 표시되고 수정사항을 사용할 수 있습니다(Alt
+ Enter
(macOS의 경우 ⌥ + ⏎) > Replace with …). 검사는 입력과 가장 유사한 수정사항을 제공하려고 시도합니다.
언어
다양한 사용자 언어를 테스트하려면 locale
매개변수를 추가합니다.
@Preview(locale = "fr-rFR") @Composable fun DifferentLocaleComposablePreview() { Text(text = stringResource(R.string.greeting)) }
배경 색상 설정
기본적으로 컴포저블은 투명한 배경으로 표시됩니다. 배경을 추가하려면 showBackground
및 backgroundColor
매개변수를 추가하세요. 유지
backgroundColor
는 Color
가 아닌 ARGB Long
입니다.
값:
@Preview(showBackground = true, backgroundColor = 0xFF00FF00) @Composable fun WithGreenBackground() { Text("Hello World") }
시스템 UI
미리보기 내에 상태 표시줄과 작업 모음을 표시해야 하는 경우 showSystemUi
매개변수를 추가하세요.
@Preview(showSystemUi = true) @Composable fun DecoratedComposablePreview() { Text("Hello World") }
UI 모드
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!") } }
@Preview
와 상호작용
Android 스튜디오에서 제공하는 기능을 사용하면 정의된 API와 상호작용할 수 있으며 미리 볼 수 있습니다 이러한 상호작용은 미리보기의 런타임 동작 미리보기로 UI를 더 잘 탐색할 수 있습니다.
대화형 모드
대화형 모드를 사용하면 스마트폰이나 태블릿과 같이 프로그램을 실행하는 기기에서와 유사한 방식으로 미리보기와 상호작용할 수 있습니다. 대화형 모드 샌드박스 환경에서 격리 (즉, 다른 미리보기로부터 격리됨) 여기서 요소를 클릭하고 미리보기에 사용자 입력을 입력할 수 있습니다. 이 모드를 사용하면 컴포저블의 여러 상태, 동작, 애니메이션을 빠르게 테스트할 수 있습니다.
코드 탐색 및 컴포저블 개요
미리보기 위로 마우스를 가져가면 미리보기 내에 포함된 컴포저블의 개요가 표시됩니다. 컴포저블 개요를 클릭하면 편집기 뷰가 컴포저블 정의로 이동합니다.
미리보기 실행
에뮬레이터 또는 실제 기기에서 특정 @Preview
를 실행할 수 있습니다. 미리보기는 새 Activity
와 동일한 프로젝트 앱 내에 배포되므로 동일한 컨텍스트와 권한을 공유합니다. 권한이 이미 부여된 경우 권한을 요청하는 템플릿 코드를 작성할 필요가 없습니다.
미리보기 실행 아이콘 을 클릭합니다.
@Preview
주석 옆이나 미리보기 상단에
스튜디오는 @Preview
를 연결된 기기나 에뮬레이터에 배포합니다.
@Preview
렌더링 복사
렌더링된 모든 미리보기는 마우스 오른쪽 버튼으로 클릭하여 이미지로 복사할 수 있습니다.
동일한 @Preview
주석의 여러 미리보기
서로 다른 사양이나 컴포저블에 전달된 서로 다른 매개변수를 사용하여 동일한 @Preview
컴포저블의 여러 버전을 표시할 수 있습니다. 이렇게 하면 작성해야 하는 상용구 코드의 양을 줄일 수 있습니다.
다중 미리보기 템플릿
androidx.compose.ui:ui-tooling-preview
1.6.0-alpha01 이상에 다중 미리보기 도입
API 템플릿: @PreviewScreenSizes
, @PreviewFontScales
, @PreviewLightDark
,
및 @PreviewDynamicColors
이므로 단일 주석으로
Compose UI를 미리 봅니다.
맞춤 다중 미리보기 주석 만들기
다중 미리보기를 사용하면 자체적으로 다양한 구성과 함께 여러 @Preview
주석을 포함하는 주석 클래스를 정의할 수 있습니다. 구성 가능한 함수에 이 주석을 추가하면 다양한 미리보기가 모두 한 번에 자동 렌더링됩니다. 예를 들어, 이 주석을 사용하면 하나의 컴포저블에 관한 정의를 모두 반복하지 않고도 여러 기기, 글꼴 크기, 테마를 동시에 미리 볼 수 있습니다.
먼저 나만의 맞춤 주석 클래스를 만듭니다.
@Preview( name = "small font", group = "font scales", fontScale = 0.5f ) @Preview( name = "large font", group = "font scales", fontScale = 1.5f ) annotation class FontScalePreviews
미리보기 컴포저블에 이 맞춤 주석을 사용할 수 있습니다.
@FontScalePreviews @Composable fun HelloWorldPreview() { Text("Hello World") }
여러 다중 미리보기 주석과 일반 미리보기 주석을 결합할 수 있습니다. 전체 미리보기 집합을 만들 수 있습니다. 다중 미리보기 주석 결합 다른 조합이 모두 표시되는 것은 아닙니다. 대신 각 다중 미리보기 주석이 독립적으로 작동하며 다중 미리보기 주석 고유의 변형만 렌더링합니다.
@Preview( name = "Spanish", group = "locale", locale = "es" ) @FontScalePreviews annotation class CombinedPreviews @CombinedPreviews @Composable fun HelloWorldPreview2() { MaterialTheme { Surface { Text(stringResource(R.string.hello_world)) } } }
다중 미리보기와 일반 미리보기의 조합을 통해 대규모 프로젝트의 여러 속성을 더 포괄적으로 테스트할 수 있습니다.
@Preview
및 대규모 데이터 세트
컴포저블 미리보기에 대규모 데이터 세트를 전달해야 하는 경우가 많습니다. 이렇게 하려면 다음과 같이 컴포저블 미리보기 함수에 샘플 데이터를 전달하기만 하면 됩니다.
@PreviewParameter
를 사용하여 매개변수 추가
주석을 추가합니다.
@Preview @Composable fun UserProfilePreview( @PreviewParameter(UserPreviewParameterProvider::class) user: User ) { UserProfile(user) }
샘플 데이터를 제공하려면 다음을 구현하는 클래스를 만듭니다.
PreviewParameterProvider
를 반환하고
시퀀스로 샘플링합니다.
class UserPreviewParameterProvider : PreviewParameterProvider<User> { override val values = sequenceOf( User("Elise"), User("Frank"), User("Julia") ) }
이렇게 하면 시퀀스에서 데이터 요소당 하나의 미리보기가 렌더링됩니다.
여러 미리보기에 같은 제공자 클래스를 사용할 수 있습니다. 필요한 경우 제한 매개변수를 설정하여 미리보기 수를 조정할 수 있습니다.
@Preview @Composable fun UserProfilePreview2( @PreviewParameter(UserPreviewParameterProvider::class, limit = 2) user: User ) { UserProfile(user) }
제한사항 및 권장사항
Android 스튜디오는 미리보기 영역에서 직접 미리보기 코드를 실행합니다. 그렇지 않습니다.
에뮬레이터나 실제 기기를 실행해야 하는 이유는 포팅된
Layoutlib
라는 Android 프레임워크의 일부입니다. Layoutlib
는 Android 기기 외부에서 실행되도록 설계된 Android 프레임워크의 맞춤 버전입니다. 이
라이브러리의 목표는 Android 스튜디오에서 레이아웃의 미리보기를 제공하는 것입니다.
기기에서의 렌더링에 매우 가깝습니다.
미리보기 제한사항
미리보기는 Android 스튜디오 내에서 렌더링되는 방식으로 인해 가볍고 렌더링하는 데 전체 Android 프레임워크가 필요하지 않습니다. 하지만 여기에는 다음과 같은 제한사항이 있습니다.
- 네트워크에 액세스할 수 없음
- 파일에 액세스할 수 없음
- 일부
Context
API를 완전히 사용하지 못할 수도 있음
미리보기 및 ViewModels
다음 내에서 ViewModel
를 사용하면 미리보기가 제한됩니다.
있습니다. 미리보기 시스템은
ViewModel
에 전달되는 매개변수(예: 저장소, 사용 사례, 관리자,
또는 그와 유사한 형태일 수 있습니다. 또한 ViewModel
가 종속 항목 삽입에 참여하는 경우 (예:
Hilt와 마찬가지로) 미리보기 시스템에서 전체 종속 항목을 빌드할 수 없음
그래프를 사용하여 ViewModel
를 구성합니다.
ViewModel
를 사용하여 컴포저블을 미리 보려고 하면 Android 스튜디오에 특정 컴포저블을 렌더링할 때 오류가 표시됩니다.
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 또는 ⌘ + 클릭'을 눌러 Android의 @Preview
주석
전체 매개변수 목록을 보려면 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, )
추가 리소스
Android 스튜디오에서 @Preview
사용 편의성을 높이는 방법을 자세히 알아보고 도구 팁을 더 확인하려면 Compose 도구 블로그를 참고하세요.
추천 서비스
- 참고: JavaScript가 사용 중지되어 있으면 링크 텍스트가 표시됩니다.
- CompositionLocal을 사용한 로컬 범위 지정 데이터
- Compose의 Material Design 2
- Compose에서 뷰 사용