Karo sürümleri

Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Wear OS cihazlarda kartlar, bağımsız sürümlere sahip iki temel bileşen tarafından oluşturulur. Uygulama karolarınızın tüm cihazlarda düzgün çalışmasını sağlamak için bu temel mimariyi anlamanız önemlidir.

• Jetpack kartlarıyla ilgili kitaplıklar: Bu kitaplıklar (Wear Kartları ve Wear ProtoLayout dahil) uygulamanıza yerleştirilir ve geliştirici olarak sürümlerini siz kontrol edersiniz. Uygulamanız, sistemdeki onTileRequest() çağrısına yanıt olarak bir TileBuilder.Tile nesnesi (Kartınızı temsil eden veri yapısı) oluşturmak için bu kitaplıkları kullanır.
• ProtoLayout Oluşturucu: Bu sistem bileşeni, Tile nesnesini ekranda oluşturmaktan ve kullanıcı etkileşimlerini yönetmekten sorumludur. Oluşturucunun sürümü, uygulama geliştirici tarafından kontrol edilmez ve aynı donanıma sahip cihazlar arasında bile değişiklik gösterebilir.

Kartın görünümü veya davranışı hem uygulamanızın Jetpack Kartlar kitaplığı sürümlerine hem de kullanıcının cihazındaki ProtoLayout Oluşturucu sürümüne göre değişiklik gösterebilir. Örneğin, bir cihaz döndürme veya nabız verilerinin görüntülenmesini desteklerken başka bir cihaz bu özellikleri desteklemeyebilir.

Bu dokümanda, uygulamanızın Tiles kitaplığının ve ProtoLayout Oluşturucu'nun farklı sürümleriyle uyumlu olmasını sağlamanın yanı sıra daha yeni Jetpack kitaplığı sürümlerine nasıl geçeceğiniz açıklanmaktadır.

Uyumluluğu göz önünde bulundurun

Çeşitli cihazlarda düzgün çalışan bir Kart oluşturmak için aşağıdakileri göz önünde bulundurmanız gerekir.

Oluşturucu sürümünü algılama

• onTileRequest() yönteminize iletilen DeviceParameters nesnesinin getRendererSchemaVersion() yöntemini kullanın. Bu yöntem, cihazdaki ProtoLayoutRenderer'ın ana ve alt sürüm numaralarını döndürür.
• Ardından, Kartınızın tasarımını veya davranışını algılanan oluşturma aracı sürümüne göre uyarlamak için onTileRequest() uygulamanızda koşullu mantık kullanabilirsiniz.
  • Örneğin, belirli bir animasyon desteklenmiyorsa bunun yerine statik bir resim gösterebilirsiniz.

@RequiresSchemaVersion ek açıklaması

• ProtoLayout yöntemlerindeki @RequiresSchemaVersion ek açıklaması, söz konusu yöntemin açıklandığı şekilde davranması için gereken minimum oluşturma şeması sürümünü belirtir (örnek).
  • Cihazda mevcut olandan daha yüksek bir oluşturma aracı sürümü gerektiren bir yöntemi çağırmak uygulamanızın kilitlenmesine neden olmaz ancak içeriğin görüntülenmemesine veya özelliğin yoksayılmasına neden olabilir.

Örnek

override fun onTileRequest(
    requestParams: TileService.TileRequest
): ListenableFuture<Tile> {
    val rendererVersion =
        requestParams.deviceConfiguration.rendererSchemaVersion
    val tile = Tile.Builder()

    if (
        rendererVersion.major > 1 ||
            (rendererVersion.major == 1 && rendererVersion.minor >= 300)
    ) {
        // Use a feature supported in renderer version 1.300 or later
        tile.setTileTimeline(/* ... */ )
    } else {
        // Provide fallback content for older renderers
        tile.setTileTimeline(/* ... */ )
    }

    return Futures.immediateFuture(tile.build())
}

Farklı oluşturma aracı sürümleriyle test etme

Kartlarınızı farklı oluşturma aracı sürümleriyle test etmek için Wear OS emülatörünün farklı sürümlerine dağıtın. (Fiziksel cihazlarda ProtoLayout Oluşturucu güncellemeleri Play Store veya sistem güncellemeleri tarafından yayınlanır. Belirli bir oluşturma aracı sürümünün yüklenmesini zorunlu kılmak mümkün değildir.)

Android Studio'nun Kart Önizleme özelliği, kodunuzun bağlı olduğu Jetpack ProtoLayout kitaplığına yerleştirilmiş bir oluşturma aracı kullanır. Bu nedenle, kartları test ederken farklı Jetpack kitaplığı sürümlerine bağlı olmak da bir yaklaşımdır.

Kartlar 1.5 / ProtoLayout 1.3'e (Material 3 Expressive) taşıma

Kartlarınızın sisteme sorunsuz bir şekilde entegre olmasını sağlayacak kullanıcı arayüzü değişiklikleri de dahil olmak üzere en son geliştirmelerden yararlanmak için Jetpack Kart kitaplıklarınızı güncelleyin.

Jetpack Tiles 1.5 ve Jetpack ProtoLayout 1.3, dikkate değer birkaç iyileştirme ve değişiklik içeriyor. Bunlardan bazıları:

• Kullanıcı arayüzünü açıklamak için Compose benzeri bir API.
• Alt kenar düğmesi ve gelişmiş görseller için destek dahil olmak üzere Material 3 Expressive bileşenleri: Lottie animasyonları, daha fazla degrade türü ve yeni yay çizgisi stilleri. - Not: Bu özelliklerin bazıları yeni API'ye taşınmadan da kullanılabilir.

Öneriler

• Tüm kartlarınızı aynı anda taşıyabilirsiniz. Uygulamanızda farklı karo sürümlerini karıştırmaktan kaçının. Material 3 bileşenleri ayrı bir yapıda (androidx.wear.protolayout:protolayout-material3) bulunduğundan, aynı uygulamada hem M2.5 hem de M3 karolarını teknik olarak kullanmak mümkün olsa da, kesinlikle gerekli olmadığı sürece (örneğin, uygulamanızda bir kerede taşınamayan çok sayıda karo varsa) bu yaklaşımı kesinlikle önermeyiz.
• Kartlar kullanıcı deneyimi kılavuzunu uygulayın. Kartların son derece yapılandırılmış ve şablonlu yapısı göz önüne alındığında, kendi tasarımlarınız için başlangıç noktası olarak mevcut örneklerdeki tasarımları kullanın.
• Çeşitli ekran ve yazı tipi boyutlarında test edin. Kartlar genellikle bilgi bakımından yoğundur. Bu nedenle metin (özellikle düğmelere yerleştirildiğinde) taşmaya ve kırpılmaya eğilimlidir. Bu sorunu en aza indirmek için önceden oluşturulmuş bileşenleri kullanın ve kapsamlı özelleştirmelerden kaçının. Android Studio'nun karo önizleme özelliğini ve birden fazla gerçek cihazı kullanarak test edin.

Taşıma süreci

Bağımlılıkları güncelleme

Öncelikle build.gradle.kts dosyanızı güncelleyin. Sürümleri güncelleyin ve protolayout-material bağımlılığını aşağıdaki gibi protolayout-material3 olarak değiştirin:

// In build.gradle.kts

//val tilesVersion = "1.4.1"
//val protoLayoutVersion = "1.2.1"

// Use these versions for M3.
val tilesVersion = "1.5.0-rc01"
val protoLayoutVersion = "1.3.0-rc01"

 dependencies {
     // Use to implement support for wear tiles
     implementation("androidx.wear.tiles:tiles:$tilesVersion")

     // Use to utilize standard components and layouts in your tiles
     implementation("androidx.wear.protolayout:protolayout:$protoLayoutVersion")

     // Use to utilize components and layouts with Material Design in your tiles
     // implementation("androidx.wear.protolayout:protolayout-material:$protoLayoutVersion")
     implementation("androidx.wear.protolayout:protolayout-material3:$protoLayoutVersion")

     // Use to include dynamic expressions in your tiles
     implementation("androidx.wear.protolayout:protolayout-expression:$protoLayoutVersion")

     // Use to preview wear tiles in your own app
     debugImplementation("androidx.wear.tiles:tiles-renderer:$tilesVersion")

     // Use to fetch tiles from a tile provider in your tests
     testImplementation("androidx.wear.tiles:tiles-testing:$tilesVersion")
 }

TileService büyük ölçüde değişmeden kalır

Bu taşıma işleminde yapılan başlıca değişiklikler kullanıcı arayüzü bileşenlerini etkiler. Sonuç olarak, tüm kaynak yükleme mekanizmaları dahil olmak üzere TileService uygulamanız için çok az veya hiç değişiklik gerekmemelidir.

Ana istisna, kart etkinliği izlemeyle ilgilidir: Uygulamanız onTileEnterEvent() veya onTileLeaveEvent() kullanıyorsa onRecentInteractionEventsAsync()'e geçmeniz gerekir. API 36'dan itibaren bu etkinlikler toplu olarak gönderilecek.

Düzen oluşturma kodunuzu uyarlama

ProtoLayout 1.2'de (M2.5) onTileRequest() yöntemi bir TileBuilders.Tile döndürür. Bu nesne, bir TimelineBuilders.Timeline de dahil olmak üzere çeşitli öğeler içeriyordu. TimelineBuilders.Timeline, kartın kullanıcı arayüzünü açıklayan LayoutElement öğesini içeriyordu.

ProtoLayout 1.3 (M3) ile genel veri yapısı ve akışı değişmese de LayoutElement artık Compose'dan esinlenen bir yaklaşımla oluşturuluyor. Bu yaklaşımda, tanımlanmış slotlara dayalı bir düzen kullanılıyor. Bu slotlar (üstten alta) titleSlot (genellikle birincil başlık veya üstbilgi için), mainSlot (temel içerik için) ve bottomSlot (genellikle kenar düğmesi gibi işlemler veya kısa metin gibi ek bilgiler için) şeklindedir. Bu düzen, primaryLayout() işlevi tarafından oluşturulur.

M2.5 ve M3 düzen işlevlerinin karşılaştırması

fun myLayout(
    context: Context,
    deviceConfiguration: DeviceParametersBuilders.DeviceParameters
) =
    PrimaryLayout.Builder(deviceConfiguration)
        .setResponsiveContentInsetEnabled(true)
        .setContent(
            Text.Builder(context, "Hello World!")
                .setTypography(Typography.TYPOGRAPHY_BODY1)
                .setColor(argb(0xFFFFFFFF.toInt()))
                .build()
        )
        .build()

fun myLayout(
    context: Context,
    deviceConfiguration: DeviceParametersBuilders.DeviceParameters,
) =
    materialScope(context, deviceConfiguration) {
        primaryLayout(mainSlot = { text("Hello, World!".layoutString) })
    }

Temel farklılıkları vurgulamak için:

1. İnşaat ustalarının çıkarılması. Material3 kullanıcı arayüzü bileşenleri için geleneksel oluşturucu deseni, daha açıklayıcı ve Compose'dan ilham alan bir söz dizimi ile değiştirildi. (String/Color/Değişkenler gibi kullanıcı arayüzü dışındaki bileşenler de yeni Kotlin sarmalayıcıları alır.)
2. Standartlaştırılmış İlk Kullanıma Hazırlama ve Düzen İşlevleri. M3 düzenleri, standartlaştırılmış başlatma ve yapı işlevlerini kullanır: materialScope() ve primaryLayout(). Bu zorunlu işlevler, M3 ortamını (materialScope aracılığıyla tema, bileşen kapsamı) başlatır ve birincil yuvaya dayalı düzeni (primaryLayout aracılığıyla) tanımlar. Her ikisi de düzen başına tam olarak bir kez çağrılmalıdır.

Tema oluşturma

Renk

Material 3 Expressive'in öne çıkan özelliklerinden biri "dinamik temalandırma"dır: Bu özelliği etkinleştiren kartlar (varsayılan olarak açıktır) sistem tarafından sağlanan temada gösterilir (kullanılabilirlik, kullanıcının cihazına ve yapılandırmasına bağlıdır).

M3'teki bir diğer değişiklik de renk jetonu sayısının 4'ten 29'a çıkarılması oldu. Yeni renk jetonlarını ColorScheme sınıfında bulabilirsiniz.

Yazı biçimi

M2.5'e benzer şekilde M3 de büyük ölçüde önceden tanımlanmış yazı tipi boyutu sabitlerine dayanır. Doğrudan yazı tipi boyutu belirtmeniz önerilmez. Bu sabitler Typography sınıfında bulunur ve daha etkileyici seçenekler sunan biraz daha geniş bir yelpaze sunar.

Tüm ayrıntılar için Yazı biçimi dokümanlarına bakın.

Şekil

Çoğu M3 bileşeni, renk boyutunun yanı sıra şekil boyutunda da değişiklik gösterebilir.

full şeklinde bir textButton (mainSlot içinde):

Aynı metin düğmesi, small şeklinde:

Bileşenler

M3 bileşenleri, M2.5 bileşenlerine kıyasla çok daha esnek ve yapılandırılabilirdir. M2.5'te genellikle çeşitli görsel işlemler için farklı bileşenler gerekirken M3'te genellikle iyi varsayılan değerlere sahip genelleştirilmiş ancak yüksek oranda yapılandırılabilir bir "temel" bileşen kullanılır.

Bu ilke, "root" düzeni için geçerlidir. M2.5'te bu PrimaryLayout veya EdgeContentLayout idi. M3'te, tek bir üst düzey MaterialScope oluşturulduktan sonra primaryLayout() işlevi çağrılır. Bu yöntem, kök düzeni doğrudan döndürür (geliştirici gerekmez) ve titleSlot, mainSlot ve bottomSlot gibi çeşitli "slotlar" için LayoutElements değerini kabul eder. Bu yuvalar, text(), button() veya card() tarafından döndürülenler gibi belirli kullanıcı arayüzü bileşenleriyle ya da LayoutElementBuilders'daki Row veya Column gibi düzen yapılarıyla doldurulabilir.

Temalar, M3'teki önemli bir iyileştirmeyi temsil eder. Kullanıcı arayüzü öğeleri varsayılan olarak M3 stil spesifikasyonlarına otomatik olarak uyar ve dinamik tema oluşturmayı destekler.

Değiştiriciler

M3'te, bir bileşeni süslemek veya genişletmek için kullandığınız Modifiers, Compose'a daha benzer. Bu değişiklik, uygun dahili türleri otomatik olarak oluşturarak standart metinlerin sayısını azaltabilir. (Bu değişiklik, M3 kullanıcı arayüzü bileşenlerinin kullanımına paraleldir. Gerekirse ProtoLayout 1.2'deki oluşturucu stili değiştiricileri M3 kullanıcı arayüzü bileşenleriyle ve bunun tam tersini kullanabilirsiniz.)

// A Builder-style modifier to set the opacity of an element to 0.5
fun myModifier(): ModifiersBuilders.Modifiers =
    ModifiersBuilders.Modifiers.Builder()
        .setOpacity(TypeBuilders.FloatProp.Builder(0.5F).build())
        .build()

// The equivalent Compose-like modifier is much simpler
fun myModifier(): LayoutModifier = LayoutModifier.opacity(0.5F)

Değiştiricileri API stilini kullanarak oluşturabilir ve LayoutModifier öğesini ModifiersBuilders.Modifier öğesine dönüştürmek için toProtoLayoutModifiers() uzantı işlevini de kullanabilirsiniz.

Yardımcı İşlevler

ProtoLayout 1.3, birçok kullanıcı arayüzü bileşeninin Compose'dan ilham alan bir API kullanılarak ifade edilmesine olanak tanısa da LayoutElementBuilders'teki satır ve sütun gibi temel düzen öğeleri, oluşturucu kalıbını kullanmaya devam eder. Bu üslup farkını gidermek ve yeni M3 bileşen API'leriyle tutarlılık sağlamak için yardımcı işlevler kullanabilirsiniz.

primaryLayout(
    mainSlot = {
        LayoutElementBuilders.Column.Builder()
            .setWidth(expand())
            .setHeight(expand())
            .addContent(text("A".layoutString))
            .addContent(text("B".layoutString))
            .addContent(text("C".layoutString))
            .build()
    }
)

// Function literal with receiver helper function
fun column(builder: Column.Builder.() -> Unit) =
    Column.Builder().apply(builder).build()

primaryLayout(
    mainSlot = {
        column {
            setWidth(expand())
            setHeight(expand())
            addContent(text("A".layoutString))
            addContent(text("B".layoutString))
            addContent(text("C".layoutString))
        }
    }
)

Kartlar 1.2 / ProtoLayout 1.0'a taşıma

1.2 sürümü itibarıyla çoğu Kart düzeni API'si androidx.wear.protolayout ad alanındadır. En son API'leri kullanmak için kodunuzda aşağıdaki taşıma adımlarını tamamlayın.

Bağımlılıkları güncelleme

Uygulama modülünüzün derleme dosyasında aşağıdaki değişiklikleri yapın:

  // Remove
  implementation 'androidx.wear.tiles:tiles-material:version'

  // Include additional dependencies
  implementation "androidx.wear.protolayout:protolayout:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-material:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-expression:1.2.1"

  // Update
  implementation "androidx.wear.tiles:tiles:1.4.1"

  // Remove
  implementation("androidx.wear.tiles:tiles-material:version")

  // Include additional dependencies
  implementation("androidx.wear.protolayout:protolayout:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-material:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-expression:1.2.1")

  // Update
  implementation("androidx.wear.tiles:tiles:1.4.1")

Ad alanlarını güncelleme

Uygulamanızın Kotlin ve Java tabanlı kod dosyalarında aşağıdaki güncellemeleri yapın. Alternatif olarak bu ad alanını yeniden adlandırma komut dosyasını da çalıştırabilirsiniz.

1. Tüm androidx.wear.tiles.material.* içe aktarma işlemlerini androidx.wear.protolayout.material.* ile değiştirin. Bu adımı androidx.wear.tiles.material.layouts kitaplığı için de tamamlayın.

2. Diğer androidx.wear.tiles.* içe aktarma işlemlerinin çoğunu androidx.wear.protolayout.* ile değiştirin.

   androidx.wear.tiles.EventBuilders, androidx.wear.tiles.RequestBuilders, androidx.wear.tiles.TileBuilders ve androidx.wear.tiles.TileService için içe aktarma işlemleri aynı kalacak.

3. Desteği sonlandırılan TileService ve TileBuilder sınıflarındaki birkaç yöntemi yeniden adlandırın:

   1. TileBuilders: getTimeline() - getTileTimeline() ve setTimeline() - setTileTimeline() arası
   2. TileService: onResourcesRequest(), onTileResourcesRequest() olarak değiştirildi
   3. RequestBuilders.TileRequest: getDeviceParameters() - getDeviceConfiguration(), setDeviceParameters() - setDeviceConfiguration(), getState() - getCurrentState() ve setState() - setCurrentState()