Android 기술
GitHub에서 보기Wear OS 위젯
android skills add wear-widgets기본 요건 및 설정
시작하기 전에 환경이 다음 요구사항을 충족하는지 확인하세요.
런타임 요구사항
Wear 위젯을 사용하려면 대상 기기에 com.google.android.wearable.protolayout.renderer APK 버전 1.6.1 이상이 필요합니다.
다음 방법 중 하나로 호환되는 버전의 렌더러를 가져옵니다.
- Wear OS 7 에뮬레이터: Wear OS 7 에뮬레이터 이미지를 사용합니다. 7 미만의 버전은 적합하지 않습니다. 설정 안내는 Wear OS 7 에뮬레이터 설정을 참고하세요.
- 실제 기기: Google Play 스토어에서 자동 업데이트를 수신하는 실제 Wear OS 기기 또는 Google Play 스토어에 로그인된 개발자 기기를 사용합니다.
기기에 설치된 버전을 확인하려면 다음 명령어를 사용하세요.
adb shell dumpsys package com.google.android.wearable.protolayout.renderer | \
grep -m 1 versionName | \
awk -F= '{print $2}'
Gradle 구성
Wear 위젯 라이브러리는 Google Maven에서 사용할 수 있습니다.
1. SDK 버전 구성
compileSdk 및 targetSdk이 37 이상으로 설정되어 있는지 확인합니다.
android {
compileSdk = 37
// ...
defaultConfig {
targetSdk = 37
// ...
}
}
2. 종속 항목 추가
앱의 build.gradle.kts 파일에 다음 종속 항목을 포함합니다.
Groovy
dependencies { // Core Wear Widget and Remote Compose libraries implementation "androidx.compose.remote:remote-creation-compose:1.0.0-alpha21" implementation "androidx.compose.remote:remote-core:1.0.0-alpha21" implementation "androidx.glance.wear:wear:1.0.0-alpha20" implementation "androidx.glance.wear:wear-core:1.0.0-alpha20" implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha13" // Tooling for previews (optional, but recommended) implementation "androidx.compose.remote:remote-tooling-preview:1.0.0-alpha21" implementation "androidx.wear.compose:compose-ui-tooling:1.7.1" implementation "androidx.wear.tiles:tiles-tooling-preview:1.6.2" debugImplementation "androidx.wear.tiles:tiles-renderer:1.6.2" }
Kotlin
dependencies { // Core Wear Widget and Remote Compose libraries implementation("androidx.compose.remote:remote-creation-compose:1.0.0-alpha21") implementation("androidx.compose.remote:remote-core:1.0.0-alpha21") implementation("androidx.glance.wear:wear:1.0.0-alpha20") implementation("androidx.glance.wear:wear-core:1.0.0-alpha20") implementation("androidx.wear.compose.remote:remote-material3:1.0.0-alpha13") // Tooling for previews (optional, but recommended) implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha21") implementation("androidx.wear.compose:compose-ui-tooling:1.7.1") implementation("androidx.wear.tiles:tiles-tooling-preview:1.6.2") debugImplementation("androidx.wear.tiles:tiles-renderer:1.6.2") }
Hello World 위젯 빌드
Wear 위젯은 GlanceWearWidgetService를 확장하는 서비스와 GlanceWearWidget를 확장하는 위젯 클래스로 구성됩니다. @RemoteComposable 함수를 사용하여 UI를 정의합니다.
서비스 정의
서비스는 시스템이 바인딩하는 진입점입니다.
위젯을 정의하려면 GlanceWearWidgetService를 확장하는 서비스를 만들고 @AssociateWithGlanceWearWidget로 주석을 달아 서비스를 적절한 GlanceWearWidget 클래스와 연결합니다.
@AssociateWithGlanceWearWidget(HelloWidget::class) class HelloWidgetService : GlanceWearWidgetService() { override val widget: GlanceWearWidget = HelloWidget() }
위젯 정의
위젯 클래스는 위젯의 데이터와 레이아웃을 제공합니다.
class HelloWidget : GlanceWearWidget() { override suspend fun provideWidgetData( context: Context, params: WearWidgetParams, ): WearWidgetData { return WearWidgetDocument( background = WearWidgetBrush.color(Color.Blue.rc), ) { HelloWidgetContent() } } }
콘텐츠 정의
콘텐츠는 원격 Compose 구성요소를 사용하여 빌드됩니다.
@RemoteComposable @Composable fun HelloWidgetContent() { RemoteBox( modifier = RemoteModifier.fillMaxSize(), contentAlignment = RemoteAlignment.Center, ) { RemoteText( text = "Hello World".rs, color = Color.White.rc, ) } }
Android 스튜디오에서 위젯 미리보기
androidx.glance.wear:wear-tooling-preview를 사용하여 Android 스튜디오의 Design 패널에서 직접 위젯 레이아웃을 미리 볼 수 있습니다.
사전 정의된 미리보기 도구 모음
wear-tooling-preview 라이브러리는 다양한 컨테이너 모양과 기기 설정에서 레이아웃을 테스트할 수 있는 사전 정의된 PreviewParameterProvider 도구를 제공합니다.
- 모서리가 둥근 정사각형 모음 (
SquircleAllWidgetPreviewParams): 모서리가 둥근 직사각형 컨테이너입니다. - 원형 스위트 (
RoundAllWidgetPreviewParams): 알약 모양 컨테이너입니다. - 직사각형 스위트 (
RectangularAllWidgetPreviewParams): 안전 패딩이 있는 잘리지 않은 직사각형 컨테이너입니다. 이 미리보기 구성으로 생성된 이미지는 위젯 선택 도구에서 사용하는 APK 삽입 미리보기 이미지로 사용하기에 적합합니다 (미리보기 이미지 애셋 생성 참고).
Android 스튜디오에서 위젯을 미리 보려면 @WearWidgetPreview를 사용하세요.
@Preview @Composable fun HelloWidgetPreview( @PreviewParameter(SquircleAllWidgetPreviewParams::class) params: WearWidgetParams, ) { WearWidgetPreview( widget = HelloWidget(), params = params, ) }
위젯 구성 XML 만들기
새 파일 res/xml/hello_widget_info.xml을 만들어 위젯의 속성과 지원되는 크기를 정의합니다. <wearwidget-provider> 태그에서 지원되는 XML 속성의 전체 참조는 WearWidgetProviderInfo 문서를 참고하세요.
<wearwidget-provider description="@string/hello_widget_description" icon="@mipmap/ic_launcher" label="@string/hello_widget_label" preferredType="SMALL"> <container type="SMALL" previewImage="@drawable/widget_preview_small" /> <container type="LARGE" previewImage="@drawable/widget_preview_large" /> </wearwidget-provider>
미리보기 이미지 확장 소재 생성
<container> 요소의 previewImage 속성은 시스템 위젯 선택 도구에 표시되는 드로어블 애셋을 참조합니다. 올바른 경계와 밀도로 미리보기 애셋을 생성하려면 RectangularAllWidgetPreviewParams와 함께 Android 스튜디오 미리보기를 사용하고 (작은 컨테이너와 큰 컨테이너 모두에 대한 미리보기 변형을 생성함) 320DPI 스마트시계 디스플레이 밀도를 지정합니다.
@Preview( name = "Widget Preview Asset", device = "spec:width=1000dp,height=1000dp,dpi=320", ) @Composable fun HelloWidgetCatalogPreview( @PreviewParameter(RectangularAllWidgetPreviewParams::class) params: WearWidgetParams, ) { WearWidgetPreview( widget = HelloWidget(), params = params, ) }
렌더링된 미리보기 이미지를 추출하려면 다음 단계를 완료하세요.
- Android 스튜디오에서 미리보기 컴포저블의 Design 표시 경로를 엽니다.
- 미리보기 창에서 렌더링된 미리보기를 마우스 오른쪽 버튼으로 클릭하거나 미리보기 툴바를 사용하여 Copy Image를 선택하거나 이미지를 저장합니다. 또는 CLI 도구 또는 자동화된 스크립트를 사용하여 Compose 미리보기를 추출합니다.
- 작은 이미지 파일과 큰 이미지 파일을 앱의
res/drawable-nodpi/디렉터리(예:res/drawable-nodpi/widget_preview_small.png및res/drawable-nodpi/widget_preview_large.png)에 저장합니다.
AndroidManifest.xml에 등록
필수 인텐트 필터 및 메타데이터를 사용하여 AndroidManifest.xml에 서비스를 등록합니다.
<service android:name=".snippets.widget.HelloWidgetService" android:exported="true" android:icon="@mipmap/ic_launcher" android:label="@string/hello_widget_label" android:permission="com.google.android.wearable.permission.BIND_TILE_PROVIDER"> <intent-filter> <action android:name="androidx.glance.wear.action.BIND_WIDGET_PROVIDER" /> <!-- If you already have a Tile, omit the following line. --> <action android:name="androidx.wear.tiles.action.BIND_TILE_PROVIDER" /> </intent-filter> <meta-data android:name="androidx.glance.wear.widget.provider" android:resource="@xml/hello_widget_info" /> <meta-data android:name="androidx.wear.tiles.PREVIEW" android:resource="@drawable/tile_preview" /> </service>
빌드 및 배포
서비스와 위젯을 정의한 후 프로젝트를 빌드하고 기기나 에뮬레이터에 배포할 수 있습니다.
빌드 및 설치
프로젝트를 빌드하고 연결된 기기 또는 에뮬레이터에 디버그 APK를 설치합니다.
./gradlew :app:installDebug
위젯 추가 및 미리보기
앱이 설치되면 adb를 사용하여 프로그래매틱 방식으로 위젯을 캐러셀에 추가하고 화면에 표시합니다.
참고: Wear 위젯은 디버깅 목적으로 기본 카드 인프라를 사용합니다. 따라서 adb 명령어에는 add-tile 및 show-tile 작업이 필요합니다.
1. 캐러셀에 위젯을 추가합니다.
adb shell am broadcast \
-a com.google.android.wearable.app.DEBUG_SURFACE \
--es operation add-tile \
--ecn component <your_package_name>/.HelloWidgetService
2. 위젯 표시:
adb shell am broadcast \
-a com.google.android.wearable.app.DEBUG_SYSUI \
--es operation show-tile \
--ei index 0
프로그래매틱 방식으로 위젯 콘텐츠 업데이트
앱의 기본 데이터가 변경되면 (예: 데이터 동기화, 푸시 알림 또는 사용자 작업 수신) 시스템에 위젯 콘텐츠를 새로고침하도록 알립니다.
위젯의 모든 활성 인스턴스에 대한 업데이트를 요청하려면 위젯 클래스에서 triggerUpdateAll를 호출합니다.
// Request a content update for all active HelloWidget instances
HelloWidget().triggerUpdateAll(context)
모든 활성 인스턴스를 새로고침하지 않고 특정 위젯 인스턴스를 업데이트하려면 대상 인스턴스 ID를 사용하여 triggerUpdate를 호출합니다.