표준 위젯 레이아웃

먼저 핵심 콘텐츠를 파악하여 효과적인 위젯 레이아웃을 만드세요. 레이아웃은 위젯 내에서 정보와 상호작용 요소가 구성되는 방식을 결정합니다. Android는 이 프로세스를 간소화하기 위해 툴바, 텍스트, 목록, 그리드 유형 위젯용으로 사전 빌드된 레이아웃을 여러 개 제공합니다.

텍스트

텍스트 레이아웃은 간결한 정보를 표시하는 데 적합합니다. 텍스트와 함께 이미지를 선택적으로 포함하여 위젯의 시각적 매력을 높입니다.

텍스트만 표시

제목, 상태 업데이트, 간단한 설명 또는 한 줄의 텍스트로 메시지를 효과적으로 전달하는 모든 시나리오에 적합합니다.

텍스트 및 이미지

시각적 효과를 높이기 위해 이미지를 포함하세요. 다양한 화면 크기에 맞게 이 레이아웃을 조정하는 방법을 알아보려면 중단점을 참고하세요.

툴바

툴바 레이아웃을 사용하여 위젯 크기에 따라 조정되는 유연한 레이아웃에서 사용자가 앱에서 자주 사용하는 작업에 빠르게 액세스할 수 있도록 합니다.

검색 툴바

검색 툴바 레이아웃은 툴바의 기본 작업으로 검색에 초점을 맞추도록 의도적으로 설계되었습니다. 유용한 추가 버튼을 사용하면 자주 사용하는 기능에 빠르게 액세스할 수 있습니다.

툴바

툴바에는 앱 브랜딩이 표시되고 그 뒤에 전환 가능한 설정이나 작업 링크에 적합한 가장 많이 사용되는 작업 버튼이 표시됩니다. 크기를 조절할 때 흔히 사용되지 않는 옵션은 더 일반적인 작업에 맞게 숨길 수 있습니다. 여유 공간이 있는 경우 중단점을 사용하여 탭할 수 있는 최소 48dp 버튼을 새로 추가합니다.

목록

목록 레이아웃을 사용하여 여러 항목을 명확하고 스캔 가능한 형식으로 정리합니다. 뉴스 헤드라인, 할 일 목록 또는 메시지에 적합합니다. 콘텐츠를 구조화된 스캔 가능한 목록으로 정리해 줘. 콘텐츠 요구사항에 따라 컨테이너화된 프레젠테이션과 컨테이너화되지 않은 프레젠테이션 중에서 선택합니다.

텍스트 및 이미지 목록

스캔 가능한 텍스트 및 이미지 목록은 뉴스 헤드라인, 앨범 아트로 구성된 재생목록, 메시지 등 다양한 콘텐츠 유형을 표시하는 데 적합합니다.

체크리스트

체크리스트 레이아웃은 작업을 표시하고 사용자가 항목을 완료로 빠르게 표시할 수 있는 명확한 탭 타겟을 제공하는 데 적합합니다.

작업 목록

시각적인 켜짐/꺼짐 상태가 항목 상태에 관한 즉각적인 피드백을 제공하는 작업 목록을 통해 직관적인 제어 그룹화를 제공합니다.

풀 블리드 이미지

Android 17 이상에서 몰입형 전체 화면 이미지를 표시하는 데 이상적인 이 레이아웃은 스냅 스크롤을 사용하여 각 하위 요소가 위젯 컨테이너의 높이에 완벽하게 정렬되도록 합니다.

그리드

선택적 라벨이 있는 시각적으로 풍부한 유연한 그리드에 이미지를 표시합니다. 다양한 화면 크기에 맞게 조정되는 열과 행을 사용합니다.

이미지만

이미지 전용 그리드를 사용하여 시각적으로 인상적인 스크롤 가능한 이미지 갤러리를 만듭니다. 행과 열은 최적의 프레젠테이션을 위해 다양한 화면 크기에 맞게 자동으로 조정됩니다.

이미지 및 텍스트

텍스트 라벨과 설명을 통합하여 추가 컨텍스트와 정보로 이미지 그리드 콘텐츠를 풍부하게 만들 수도 있습니다.

코드 샘플

다음 표에서는 각 표준 레이아웃을 Android 플랫폼 샘플 GitHub 저장소의 해당 Jetpack Glance 구현에 매핑합니다.

표준 레이아웃 참조 파일 가이드
작업 목록 레이아웃
  • Glance 작업 콜백으로 목록 항목 작업을 처리하고 적절한 상태 업데이트를 보장합니다.
체크리스트 레이아웃
  • 작업 매개변수 또는 콜백을 사용하여 체크박스 상태 전환을 구현하여 수집 항목을 업데이트합니다.
  • 위젯 `onClick` 매개변수에 `actionRunCallback`, `ActionCallback(actionParametersOf(…))`, `actionStartActivity(…)`와 같은 Glance 작업 콜백을 사용하여 체크박스 탭과 같은 클릭 이벤트를 처리합니다.
표현력 있는 툴바 레이아웃
  • `ColorProvider` 가져오기 오류 방지: `androidx.glance.unit.ColorProvider` 를 가져오고 `androidx.glance.color.ColorProvider(dayColor, nightColor)`를 사용합니다.
  • `ColorProvider` 대신 단색 배경 색상에 `GlanceModifier.background(Color)`를 직접 사용합니다.
이미지 그리드 레이아웃
  • 이미지 로드 라이브러리가 구성되거나 요청되지 않는 한 이미지 항목에 단색 (`GlanceModifier.background`) 또는 로컬 드로어블을 사용합니다.
이미지 텍스트 목록 레이아웃
  • 일반적인 사용 사례: 뉴스 피드, 기사 목록, 운동 기록, 메시지 피드, 세로 썸네일 목록
  • 썸네일 이미지를 기본/보조 텍스트와 결합할 때 목록 행 높이와 텍스트 잘림의 균형을 맞춥니다.
긴 텍스트 레이아웃
  • `2 * padding` 과 같은 `Dp` 값을 곱하는 경우 `androidx.compose.ui.unit.times`를 가져옵니다.
  • 크기 조정 규칙 준수: `dimens.xml` 의 크기가 패딩 및 서체 크기 조정에 사용되는지 확인합니다.
검색 툴바 레이아웃
  • `ColorProvider` 가져오기 오류 방지: `androidx.glance.unit.ColorProvider` 를 가져오고 `androidx.glance.color.ColorProvider(dayColor, nightColor)`를 사용합니다.
  • ColorProvider 대신 단색 배경 색상에 `GlanceModifier.background(Color)` 를 직접 사용하세요.
풀블리드 이미지 레이아웃 / 스냅 스크롤
  • 스냅 스크롤을 위해 LazyColumn에서 `verticalScrollMode = VerticalScrollMode.SnapScrollMatchHeight(size.height)` 를 설정합니다.
  • 스냅 스크롤을 구현하는 경우 Glance 1.3.0-alpha02 이상, SDK 37 (Baklava) 이상 컴파일, Android Gradle 플러그인 (AGP) 9.1.0 이상이 필요합니다.
  • 위젯 제공자 클래스에서 `override val sizeMode: SizeMode = SizeMode.Exact` 를 설정합니다.
표준 툴바 레이아웃
  • 문제 해결을 참고하여 `ColorProvider` 가져오기 오류를 방지하세요. `androidx.glance.color.ColorProvider(dayColor, nightColor)`를 사용하세요.
  • `ColorProvider` 대신 단색 배경 색상에 `GlanceModifier.background(Color)`를 직접 사용합니다.
이미지가 포함된 텍스트 레이아웃
  • 반응형 레이아웃 크기 조정 규칙에 따라 사용 가능한 위젯 크기에 따라 텍스트와 이미지를 나란히 또는 쌓아서 배치합니다.