위젯 시작하기

기본 요건 및 설정

시작하기 전에 환경이 다음 요구사항을 충족하는지 확인하세요.

런타임 요구사항

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-alpha20"
    implementation "androidx.compose.remote:remote-core:1.0.0-alpha20"
    implementation "androidx.glance.wear:wear:1.0.0-alpha19"
    implementation "androidx.glance.wear:wear-core:1.0.0-alpha19"
    implementation "androidx.wear.compose.remote:remote-material3:1.0.0-alpha12"

    // Tooling for previews (optional, but recommended)
    implementation "androidx.compose.remote:remote-tooling-preview:1.0.0-alpha20"
    implementation "androidx.wear.compose:compose-ui-tooling:1.7.0"
    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-alpha20")
    implementation("androidx.compose.remote:remote-core:1.0.0-alpha20")
    implementation("androidx.glance.wear:wear:1.0.0-alpha19")
    implementation("androidx.glance.wear:wear-core:1.0.0-alpha19")
    implementation("androidx.wear.compose.remote:remote-material3:1.0.0-alpha12")

    // Tooling for previews (optional, but recommended)
    implementation("androidx.compose.remote:remote-tooling-preview:1.0.0-alpha20")
    implementation("androidx.wear.compose:compose-ui-tooling:1.7.0")
    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,
    )
}

렌더링된 미리보기 이미지를 추출하려면 다음 단계를 완료하세요.

  1. Android 스튜디오에서 미리보기 컴포저블의 디자인 화면을 엽니다.
  2. 미리보기 창에서 렌더링된 미리보기를 마우스 오른쪽 버튼으로 클릭하거나 미리보기 도구 모음을 사용하여 이미지 복사를 선택하거나 이미지를 저장합니다. 또는 CLI 도구 또는 자동화된 스크립트를 사용하여 Compose 미리보기를 추출합니다.
  3. 작은 이미지 파일과 큰 이미지 파일을 앱의 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를 호출하세요.