표준 위젯 레이아웃

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

텍스트

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

텍스트만

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

텍스트 및 이미지

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

툴바

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

검색 툴바

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

툴바

툴바는 앱 브랜딩과 함께 전환 가능한 설정 또는 작업 링크에 적합한 가장 많이 사용되는 작업의 버튼을 표시합니다. 크기를 조절할 때 흔히 사용되는 옵션은 더 일반적인 작업을 위해 숨길 수 있습니다. 중단점 을 사용하여 공간이 있을 때 최소 48dp 탭 가능한 버튼을 새로 추가합니다.

목록

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

텍스트 및 이미지 목록

검색 가능한 텍스트 및 이미지 목록은 뉴스 헤드라인, 앨범 아트가 포함된 재생목록 또는 메시지와 같은 여러 콘텐츠 유형을 표시하는 데 적합합니다.

체크리스트

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

작업 목록

작업 목록으로 직관적인 컨트롤 그룹화를 제공합니다. 여기서 시각적 온/오프 상태는 항목 상태에 관한 즉각적인 의견을 제공합니다.

전체 화면 이미지

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

그리드

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

이미지만

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

이미지 및 텍스트

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

코드 샘플

다음 표에서는 각 표준 레이아웃을 상응하는 Jetpack Glance 구현에 매핑합니다. 이 구현은 Android 플랫폼 샘플 GitHub 저장소에 있습니다.

표준 레이아웃 참조 파일 가이드
작업 목록 레이아웃
  • 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)`를 직접 사용하세요.
이미지가 포함된 텍스트 레이아웃
  • 사용 가능한 위젯 측정기준에 따라 텍스트와 이미지를 나란히 또는 쌓아서 배치할 수 있도록 반응형 레이아웃 크기 조정 규칙을 따릅니다.