Utilizzare Jetpack Compose su Wear OS

Versione di Compose for Wear OS Material 2.5 3

---

Figura 1. Jetpack Compose per Wear OS

Compose per Wear OS è simile a Compose per dispositivi mobili. Tuttavia, ci sono alcune differenze fondamentali. Questa guida illustra le somiglianze e le differenze.

Compose per Wear OS fa parte di Android Jetpack e, come le altre librerie Jetpack per Wear che utilizzi, ti aiuta a scrivere codice migliore più velocemente. Questo è il nostro approccio consigliato per la creazione di interfacce utente per le app per Wear OS.

Se non hai dimestichezza con l'utilizzo del toolkit Jetpack Compose, consulta il percorso di Compose. Molti dei principi di sviluppo per Compose per dispositivi mobili si applicano a Compose per Wear OS. Per ulteriori informazioni sui vantaggi generali di un framework UI dichiarativo, consulta Perché Compose. Per scoprire di più su Compose per Wear OS, consulta il percorso di Compose per Wear OS e il repository di esempi di Wear OS su GitHub.

Competenze Android

Visualizza su GitHub

Wear Compose Material 3

Utilizza una skill Android per creare app utilizzando Jetpack Compose su Wear OS, inclusa la migrazione dalle versioni precedenti di Material a Material3.

Per installare lo skill dalla CLI Android, esegui:

android skills add wear-compose-m3

Material Design in Jetpack Compose su Wear OS

Jetpack Compose su Wear OS offre un'implementazione di Material 3, che ti aiuta a progettare esperienze con l'app più coinvolgenti. I componenti di Material Design su Wear OS si basano sui temi di Material di Wear. Questo tema è un modo sistematico per personalizzare Material Design e riflettere meglio il brand del tuo prodotto.

Compatibilità

Compose per Wear OS funziona sugli smartwatch che supportano Wear OS 3.0 (livello API 30) e su quelli che utilizzano Wear OS 2.0 (livello API 25 e versioni successive). L'utilizzo della versione 1.5 di Compose per Wear OS richiede l'utilizzo della versione 1.8 delle librerie androidx.compose e di Kotlin 1.9.0. Puoi utilizzare la mappatura della distinta base e la mappa di compatibilità di Compose con Kotlin per verificare la compatibilità di Compose.

Piattaforme

Compose per Wear OS semplifica la creazione di app su Wear OS. Per ulteriori informazioni, vedi App. Utilizza i nostri componenti integrati per creare esperienze utente conformi alle linee guida di Wear OS. Per saperne di più sui componenti, consulta le nostre indicazioni per la progettazione.

Configurazione

L'utilizzo di Jetpack Compose con Wear OS è simile all'utilizzo di Jetpack Compose per qualsiasi altro progetto Android. La differenza principale è che Jetpack Compose per Wear aggiunge librerie specifiche per Wear che semplificano la creazione di interfacce utente su misura per gli smartwatch. In alcuni casi, questi componenti condividono lo stesso nome delle loro controparti non Wear, ad esempio androidx.wear.compose.material3.Button e androidx.compose.material3.Button.

Crea una nuova app in Android Studio

Per creare un nuovo progetto che includa Jetpack Compose, procedi nel seguente modo:

1. Se ti trovi nella finestra Welcome to Android Studio (Benvenuto in Android Studio), fai clic su Start a new Android Studio project (Avvia un nuovo progetto Android Studio). Se hai già un progetto Android Studio aperto, seleziona File > Nuovo > Importa esempio dalla barra dei menu.
2. Cerca Compose per Wear e seleziona Compose per Wear OS Starter.
3. Nella finestra Configura il progetto, segui questi passaggi:
   1. Imposta il Nome applicazione.
   2. Scegli la località del progetto per l'esempio.
4. Fai clic su Fine.
5. Verifica che il file build.gradle del progetto sia configurato correttamente, come descritto in File delle proprietà di Gradle.

Ora è tutto pronto per iniziare a sviluppare un'app utilizzando Compose per Wear OS.

Dipendenze del toolkit Jetpack Compose

Per utilizzare Jetpack Compose con Wear OS, devi includere le dipendenze del toolkit di Jetpack Compose nel file build.gradle della tua app. La maggior parte delle modifiche alle dipendenze relative a Wear OS si trova nei livelli architetturali superiori, circondati da un riquadro rosso nell'immagine seguente.

Figura 2. Modifiche alle dipendenze per Wear OS nell'architettura Compose

Ciò significa che molte delle dipendenze che utilizzi già con Jetpack Compose non cambiano quando scegli come target Wear OS. Ad esempio, le dipendenze di UI, runtime, compilatore e animazione rimangono invariate.

Tuttavia, Wear OS ha le proprie versioni delle librerie material e material3, foundation e navigation, quindi verifica di utilizzare le librerie corrette.

Se possibile, utilizza la versione WearComposeMaterial delle API. Sebbene sia tecnicamente possibile utilizzare la versione mobile di Compose Material, questa non è ottimizzata per i requisiti unici di Wear OS. Inoltre, la combinazione di Compose Material con Compose Material per Wear OS può causare un comportamento imprevisto. Ad esempio, poiché ogni libreria ha la propria classe MaterialTheme, esiste la possibilità che i colori, la tipografia o le forme non siano coerenti se vengono utilizzate entrambe le versioni.

La seguente tabella illustra le differenze di dipendenza tra Wear OS e dispositivi mobili:

Dipendenza Wear OS (androidx.wear.*)	Confronto	Dipendenza mobile (androidx.*)
androidx.wear.compose:compose-material3	anziché	androidx.compose.material:material3
androidx.wear.compose:compose-navigation	anziché	androidx.navigation:navigation-compose
androidx.wear.compose:compose-foundation	oltre a	androidx.compose.foundation:foundation

Nota: è possibile utilizzare altre dipendenze di Material non mobile, come Material Ripple e Material Icons Extended.

Il seguente snippet mostra un file build.gradle di esempio che include queste dipendenze:

Kotlin

dependencies {

    val composeBom = platform("androidx.compose:compose-bom:2026.09.00")

    // General compose dependencies
    implementation(composeBom)
    implementation("androidx.activity:activity-compose:1.13.0")
    implementation("androidx.compose.ui:ui-tooling-preview:1.12.1")
    // Other compose dependencies

    // Compose for Wear OS dependencies
    implementation("androidx.wear.compose:compose-material3:1.7.1")

    // Foundation is additive, so you can use the mobile version in your Wear OS app.
    implementation("androidx.wear.compose:compose-foundation:1.7.1")

    // Wear OS preview annotations
    implementation("androidx.wear.compose:compose-ui-tooling:1.7.1")

    // If you are using Compose Navigation, use the Wear OS version (NOT THE MOBILE VERSION).
    // Uncomment the line below and update the version number.
    // implementation("androidx.wear.compose:compose-navigation:1.7.1")

    // Testing
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.1.3")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.4.0")
    androidTestImplementation("androidx.compose.ui:ui-test-junit4:1.0.3")
    debugImplementation("androidx.compose.ui:ui-tooling:1.4.1")

}

Feedback

Prova Compose per Wear OS e utilizza l'Issue Tracker per fornire suggerimenti e feedback.

Unisciti al canale#compose-wear su Kotlin Slack per entrare in contatto con la community di sviluppatori e farci sapere la tua esperienza.