Kartları kullanmaya başlayın

Uygulamanızdan karo sağlamaya başlamak için uygulamanızın build.gradle dosyasına aşağıdaki bağımlılıkları ekleyin.

Groovy

dependencies {
    // Use to implement support for wear tiles
    implementation "androidx.wear.tiles:tiles:1.5.0-alpha04"

    // Use to utilize standard components and layouts in your tiles
    implementation "androidx.wear.protolayout:protolayout:1.3.0-alpha04"

    // Use to utilize components and layouts with Material Design in your tiles
    implementation "androidx.wear.protolayout:protolayout-material:1.3.0-alpha04"

    // Use to include dynamic expressions in your tiles
    implementation "androidx.wear.protolayout:protolayout-expression:1.3.0-alpha04"

    // Use to preview wear tiles in your own app
    debugImplementation "androidx.wear.tiles:tiles-renderer:1.5.0-alpha04"

    // Use to fetch tiles from a tile provider in your tests
    testImplementation "androidx.wear.tiles:tiles-testing:1.5.0-alpha04"
}

Kotlin

dependencies {
    // Use to implement support for wear tiles
    implementation("androidx.wear.tiles:tiles:1.5.0-alpha04")

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

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

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

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

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

Not: Bu API, asenkrondur ve ListenableFuture kullanımını yoğun şekilde kullanır. Kotlin iş parçacıklarını kullanmayı tercih ediyorsanız Horologist kitaplığındaki SuspendingTileService.kt işlevini kullanabilirsiniz.

Temel kavramlar

Kartlar, Android uygulamalarıyla aynı şekilde oluşturulmaz ve farklı kavramlardan yararlanır:

• Düzen şablonları: Ekrandaki görsel öğelerin genel düzenini tanımlayın. Kart, ekranın kenarında bir ilerleme göstergesi içeren EdgeContentLayout düzen şablonu veya bu göstergeyi göstermeyen bir PrimaryLayout kullanır.
• Düzen öğeleri: Button veya Chip gibi tek bir grafik öğeyi ya da Column, MultiButtonLayout, MultiSlotLayout veya benzeri bir öğe kullanılarak gruplandırılmış birkaç öğeyi temsil eder. Bunlar bir düzen şablonuna yerleştirilir.
• Kaynaklar: ResourceBuilders.Resources nesneleri, bir düzeni oluşturmak için gereken Android kaynaklarının (resimler) anahtar/değer çiftlerinden oluşan bir haritadan ve bir sürümden oluşur.
• Zaman çizelgesi: TimelineBuilders.Timeline nesnesi, bir veya daha fazla düzenleme nesnesi örneğinin listesidir. Oluşturucunun ne zaman bir düzen nesnesinden diğerine geçmesi gerektiğini belirtmek için çeşitli mekanizmalar ve ifadeler sağlayabilirsiniz (ör. belirli bir zamanda bir düzeni göstermeyi durdurmak için).
• Durum: İki bileşenin birbiriyle iletişim kurmasını sağlamak için kart ile uygulama arasında aktarılan StateBuilders.State türündeki bir veri yapısı. Örneğin, kartta bir düğmeye dokunulursa durum, düğmenin kimliğini içerir. Veri türlerini harita kullanarak da değiştirebilirsiniz.
• Kart: Bir kartı temsil eden TileBuilders.Tile nesnesi. Bu nesne; zaman çizelgesi, kaynak sürümü kimliği, güncellenme aralığı ve durum içerir.
• Protolayout: Bu terim, çeşitli kartlarla ilgili sınıfların adında görünür ve çeşitli Wear OS yüzeylerinde kullanılan bir grafik kitaplığı olan Wear OS Protolayout kitaplığını ifade eder.

Kart oluşturma

Uygulamanızdan bir kart sağlamak için TileService türündeki bir hizmet uygulayın ve bu hizmeti manifest'inize kaydedin. Sistem, onTileRequest() adresine yapılan çağrılar sırasında gerekli kartonları ve onTileResourcesRequest() adresine yapılan çağrılar sırasında gerekli kaynakları ister.

class MyTileService : TileService() {

    override fun onTileRequest(requestParams: RequestBuilders.TileRequest) =
        Futures.immediateFuture(
            Tile.Builder()
                .setResourcesVersion(RESOURCES_VERSION)
                .setTileTimeline(
                    Timeline.fromLayoutElement(
                        Text.Builder(this, "Hello World!")
                            .setTypography(Typography.TYPOGRAPHY_BODY1)
                            .setColor(argb(0xFFFFFFFF.toInt()))
                            .build()
                    )
                )
                .build()
        )

    override fun onTileResourcesRequest(requestParams: ResourcesRequest) =
        Futures.immediateFuture(
            Resources.Builder()
                .setVersion(RESOURCES_VERSION)
                .build()
        )
}
Tile.kt

Ardından, AndroidManifest.xml dosyanızın <application> etiketine bir hizmet ekleyin.

<service
    android:name=".snippets.tile.MyTileService"
    android:label="@string/tile_label"
    android:description="@string/tile_description"
    android:icon="@mipmap/ic_launcher"
    android:exported="true"
    android:permission="com.google.android.wearable.permission.BIND_TILE_PROVIDER">
    <intent-filter>
        <action android:name="androidx.wear.tiles.action.BIND_TILE_PROVIDER" />
    </intent-filter>

    <meta-data android:name="androidx.wear.tiles.PREVIEW"
        android:resource="@drawable/tile_preview" />
</service>
AndroidManifest.xml

İzin ve intent filtresi, bu hizmeti kart sağlayıcı olarak kaydeder.

Simge, etiket, açıklama ve önizleme kaynağı, kullanıcı telefonunda veya kol saatinde kartları yapılandırdığında gösterilir.

Tam bir örnek için GitHub'daki kod örneğine veya codelab'e bakın.

Parça hizmeti yaşam döngüsüne genel bakış

TileService öğenizi oluşturup uygulama manifest dosyanızda beyan ettikten sonra kart hizmetinin durum değişikliklerine yanıt verebilirsiniz.

TileService bir bağlama hizmetidir. TileService, uygulama isteğiniz sonucunda veya sistemin onunla iletişim kurması gerektiğinde bağlanır. Tipik bir bağlı hizmet yaşam döngüsü aşağıdaki dört geri çağırma yöntemini içerir: onCreate(), onBind(), onUnbind() ve onDestroy(). Sistem, hizmet yeni bir yaşam döngüsü aşamasına her girdiğinde bu yöntemleri çağırır.

Önemli: TileService, tipik Service yaşam döngüsünden geçmeye devam eder. Ancak TileService, uygulamanızın tepki verebileceği TileService'ye özgü yaşam döngüsü yöntemleri içerdiğinden diğer bağlı hizmetlerin çoğundan farklıdır. Service yaşam döngüsü yöntemleri ve TileService yaşam döngüsü yöntemleri iki ayrı asynkron iş parçacığında çağrılır.

Bağlı hizmet yaşam döngüsünü kontrol eden geri çağırmalara ek olarak, TileService yaşam döngüsüne özgü diğer yöntemleri de uygulayabilirsiniz. Tüm kart hizmetlerinin, sistemden gelen güncelleme isteklerine yanıt vermek için onTileRequest() ve onTileResourcesRequest()'i uygulaması gerekir.

• onTileAddEvent(): Sistem bu yöntemi yalnızca kullanıcı kartınızı ilk kez eklediğinde ve kaldırıp tekrar eklediğinde çağırır. Tek seferlik başlatma işlemlerini bu sırada yapmanız önerilir.

  onTileAddEvent() yalnızca sistem tarafından bir kart oluşturulduğunda değil, kart grubu yeniden yapılandırıldığında çağrılır. Örneğin, cihaz yeniden başlatılırken veya açıldığında, daha önce eklenmiş kartlar için onTileAddEvent() çağrılmaz. Size ait hangi karoların etkin olduğunun anlık görüntüsünü almak için bunun yerine getActiveTilesAsync() kullanabilirsiniz.

• onTileRemoveEvent(): Sistem bu yöntemi yalnızca kullanıcı kartınızı kaldırırsa çağırır.

• onTileEnterEvent(): Sistem, bu sağlayıcı tarafından sağlanan bir kart ekranda göründüğünde bu yöntemi çağırır.

• onTileLeaveEvent(): Sistem, bu sağlayıcı tarafından sağlanan bir kart ekranda görünmez hale geldiğinde bu yöntemi çağırır.

• onTileRequest(): Sistem bu sağlayıcıdan yeni bir zaman çizelgesi istediğinde bu yöntem çağrılır.

• onTileResourcesRequest(): Sistem bu sağlayıcıdan kaynak paketi istediğinde bu yöntem çağrılır. Bu durum, bir Kart ilk kez yüklenirken veya kaynak sürümü değiştiğinde ortaya çıkabilir.

Not: Aşamaları belirli bir sırayla gerçekleştirmeniz gerekmez (veya bu sıraya güvenmeniz gerekmez). onTileAddEvent() yalnızca kartınız bir kullanıcı tarafından eklendiğinde çağrılabilir. onTileEnterEvent() ve onTileLeaveEvent(), TileService yaşam döngüsü boyunca birden çok kez çağrılabilir. Kullanıcı kartvizitleri kaldırmazsa onTileRemoveEvent() hiçbir zaman çağrılmaz.

Hangi karoların etkin olduğunu sorgulayın

Etkin kartlar, kol saatinde gösterilmek üzere eklenen kartlardır. Uygulamanıza ait hangi karoların etkin olduğunu sorgulamak için TileService'ın statik yöntemi getActiveTilesAsync()'i kullanın.

Dikkat: Sonuç, çağrının yapıldığı andaki etkin kartların listesini yansıtır. Bu liste, sonuç alınırken değişmiş olabilir. Kartınız etkin veya devre dışı olduğunda yapılması gereken işlemleri planlamak için onTileAddEvent() ve onTileRemoveEvent() geri çağırma işlevlerini kullanın.

Kartlar için kullanıcı arayüzü oluşturma

Kartın düzeni, bir oluşturucu kalıbı kullanılarak yazılır. Kartların düzeni, düzen kapsayıcıları ve temel düzen öğelerinden oluşan bir ağaç gibi oluşturulur. Her düzen öğesinin, çeşitli ayarlayıcı yöntemleriyle ayarlayabileceğiniz özellikleri vardır.

Not: Bir düzende görünebilecek iç içe yerleştirilmiş öğelerin sayısı sınırlıdır. Bu sınırı aşarsanız sistem, düzen güncellemesini yoksayıp karoyu önceki durumunda gösterir.

Temel düzen öğeleri

Materyal bileşenleri ile birlikte protolayout kitaplığındaki aşağıdaki görsel öğeler desteklenir:

• Text: İsteğe bağlı olarak kaydırarak bir metin dizesi oluşturur.
• Image: Bir resmi oluşturur.
• Spacer: Öğeler arasında dolgu sağlar veya arka plan rengini ayarladığınızda bölücü görevi görebilir.

Material bileşenleri

protolayout-material kitaplığı, temel öğelere ek olarak Materyal Tasarım kullanıcı arayüzü önerilerine uygun bir kart tasarımı sağlayan bileşenler sağlar.

• Button: Simge içerecek şekilde tasarlanmış tıklanabilir dairesel bileşen.

• Chip: En fazla iki satır metin ve isteğe bağlı bir simge içerecek şekilde tasarlanmış, stadyum şeklindeki tıklanabilir bileşen.

  Not: Column öğesinin içinde Chip öğesi kullanıyorsanız her iki öğenin genişliğini expand() olarak ayarlayın.

• CompactChip: Bir satır metin içerecek şekilde tasarlanmış, stadyum şeklindeki tıklanabilir bileşen.

• TitleChip: Chip'a benzer, ancak başlık metnini barındırmak için daha yüksek bir yüksekliğe sahip, tıklanabilir stadyum şeklindeki bileşen.

• CircularProgressIndicator: Ekranın kenarlarında ilerleme durumunu göstermek için EdgeContentLayout içine yerleştirilebilen dairesel ilerleme durumu göstergesi.

Düzen kapsayıcıları

Materyal düzenleri ile birlikte aşağıdaki kapsayıcılar desteklenir:

• Row: Alt öğeleri yatay olarak arka arkaya yerleştirir.
• Column: Alt öğeleri dikey olarak arka arkaya yerleştirir.
• Box: Alt öğeleri birbirinin üzerine yerleştirir.
• Arc: Alt öğeleri bir daireye yerleştirir.
• Spannable: Metin ve resimleri birbirine karıştırmanın yanı sıra metin bölümlerine belirli FontStyles uygular. Daha fazla bilgi için Spannables konusuna bakın.

Her kapsayıcı, bir veya daha fazla alt öğe içerebilir. Bu alt öğeler de kapsayıcı olabilir. Örneğin, bir Column öğesi alt öğe olarak birden fazla Row öğesi içerebilir. Bu da ızgara benzeri bir düzen oluşturur.

Örneğin, kapsayıcı düzeni ve iki alt düzen öğesi içeren bir kart şu şekilde görünebilir:

Kotlin

private fun myLayout(): LayoutElement =
    Row.Builder()
        .setWidth(wrap())
        .setHeight(expand())
        .setVerticalAlignment(VERTICAL_ALIGN_BOTTOM)
        .addContent(Text.Builder()
            .setText("Hello world")
            .build()
        )
        .addContent(Image.Builder()
            .setResourceId("image_id")
            .setWidth(dp(24f))
            .setHeight(dp(24f))
            .build()
        ).build()

Java

private LayoutElement myLayout() {
    return new Row.Builder()
        .setWidth(wrap())
        .setHeight(expand())
        .setVerticalAlignment(VALIGN_BOTTOM)
        .addContent(new Text.Builder()
            .setText("Hello world")
            .build()
        )
        .addContent(new Image.Builder()
            .setResourceId("image_id")
            .setWidth(dp(24f))
            .setHeight(dp(24f))
            .build()
        ).build();
}

Materyal düzenleri

protolayout-material kitaplığı, temel düzenlere ek olarak öğeleri belirli "yuvalar"da tutmak için tasarlanmış birkaç özel düzen de sunar.

• PrimaryLayout: Altta tek bir birincil işlem CompactChip ve onun üzerinde içerik merkezli olarak konumlandırılır.

  Not: Bu düzeni kullandığınızda içeriğin yüksekliğini ayarlamak için expand() işlevini çağıramazsınız. Aksi takdirde boş bir kart görebilirsiniz.
  
  Bununla birlikte, üst öğenin kenar boşlukları arasındaki tüm alanı kullanmak için içeriğin genişliğinde expand() işlevini çağırabilirsiniz.

• MultiSlotLayout: Birincil ve ikincil etiketleri, aralarında isteğe bağlı içerik ve alt kısımda isteğe bağlı bir CompactChip ile konumlandırır.

• MultiButtonLayout: Materyal yönergelerine göre düzenlenmiş bir dizi düğmeyi yerleştirir.

• EdgeContentLayout: İçeriği ekranın kenarına (ör. CircularProgressIndicator) yerleştirir. Bu düzen kullanılırken içindeki içeriğe otomatik olarak uygun kenar boşlukları ve dolgu uygulanır.

Yaylar

Aşağıdaki Arc kapsayıcı çocukları desteklenir:

• ArcLine: Yay etrafında eğri bir çizgi oluşturur.
• ArcText: Eğri metni Arc'te oluşturur.
• ArcAdapter: Yayda, yaya teğet bir açıda çizilen temel bir düzen öğesi oluşturur.

Not: ArcText, yay etrafında eğri metin çizerken ArcAdapter içinde Text kullanıldığında yay ile teğet olacak şekilde doğrusal metin çizilir.

Daha fazla bilgi için her bir öğe türünün referans dokümanlarına bakın.

Değiştiriciler

Mevcut her düzen öğesine isteğe bağlı olarak değiştiriciler uygulanabilir. Bu değiştiricileri aşağıdaki amaçlarla kullanın:

• Düzenin görsel görünümünü değiştirebilirsiniz. Örneğin, düzen öğenize arka plan, kenar veya dolgu ekleyin.
• Sayfa düzeniyle ilgili meta veriler ekleyin. Örneğin, ekran okuyucularla kullanmak için sayfa düzeni öğenize bir anlam değiştirici ekleyin.
• İşlev ekleyin. Örneğin, karonuzu etkileşimli hale getirmek için düzen öğenize tıklanabilir bir değiştirici ekleyin. Daha fazla bilgi için Kartlarla etkileşim kurma başlıklı makaleyi inceleyin.

Örneğin, aşağıdaki kod örneğinde gösterildiği gibi bir Image öğesinin varsayılan görünümünü ve meta verilerini özelleştirebiliriz:

Kotlin

private fun myImage(): LayoutElement =
    Image.Builder()
        .setWidth(dp(24f))
        .setHeight(dp(24f))
        .setResourceId("image_id")
        .setModifiers(Modifiers.Builder()
            .setBackground(Background.Builder().setColor(argb(0xFFFF0000)).build())
            .setPadding(Padding.Builder().setStart(dp(12f)).build())
            .setSemantics(Semantics.builder()
                .setContentDescription("Image description")
                .build()
            ).build()
        ).build()

Java

private LayoutElement myImage() {
   return new Image.Builder()
           .setWidth(dp(24f))
           .setHeight(dp(24f))
           .setResourceId("image_id")
           .setModifiers(new Modifiers.Builder()
                   .setBackground(new Background.Builder().setColor(argb(0xFFFF0000)).build())
                   .setPadding(new Padding.Builder().setStart(dp(12f)).build())
                   .setSemantics(new Semantics.Builder()
                           .setContentDescription("Image description")
                           .build()
                   ).build()
           ).build();
}

Genişleyen

Spannable, öğeleri metne benzer şekilde düzenleyen özel bir kapsayıcı türüdür. Bu, daha büyük bir metin bloğundaki yalnızca bir alt dizeye farklı bir stil uygulamak istediğinizde faydalıdır. Text öğesiyle bu mümkün değildir.

Spannable kapsayıcısı Span çocukla doldurulur. Diğer alt öğelere veya iç içe yerleştirilmiş Spannable örneklerine izin verilmez.

İki tür Span alt öğesi vardır:

• SpanText: Metni belirli bir stille oluşturur.
• SpanImage: Resmi metinle birlikte satır içi olarak oluşturur.

Örneğin, "Merhaba dünya" karosundaki "dünya" kelimesini italik hale getirebilir ve kelimelerin arasına bir resim ekleyebilirsiniz. Aşağıdaki kod örneğinde gösterildiği gibi:

Kotlin

private fun mySpannable(): LayoutElement =
    Spannable.Builder()
        .addSpan(SpanText.Builder()
            .setText("Hello ")
            .build()
        )
        .addSpan(SpanImage.Builder()
            .setWidth(dp(24f))
            .setHeight(dp(24f))
            .setResourceId("image_id")
            .build()
        )
        .addSpan(SpanText.Builder()
            .setText("world")
            .setFontStyle(FontStyle.Builder()
                .setItalic(true)
                .build())
            .build()
        ).build()

Java

private LayoutElement mySpannable() {
   return new Spannable.Builder()
        .addSpan(new SpanText.Builder()
            .setText("Hello ")
            .build()
        )
        .addSpan(new SpanImage.Builder()
            .setWidth(dp(24f))
            .setHeight(dp(24f))
            .setResourceId("image_id")
            .build()
        )
        .addSpan(new SpanText.Builder()
            .setText("world")
            .setFontStyle(newFontStyle.Builder()
                .setItalic(true)
                .build())
            .build()
        ).build();
}

Kaynaklarla çalışma

Kartların uygulamanızın kaynaklarına erişimi yoktur. Yani bir Image düzen öğesine Android resim kimliği gönderip çözülmesini bekleyemezsiniz. Bunun yerine onTileResourcesRequest() yöntemini geçersiz kılın ve tüm kaynakları manuel olarak sağlayın.

onTileResourcesRequest() yönteminde resim sağlamanın iki yolu vardır:

• setAndroidResourceByResId() kullanarak çizilebilir bir kaynak sağlayın.
• setInlineResource() kullanarak ByteArray olarak dinamik bir resim sağlayın.

Kotlin

override fun onTileResourcesRequest(
    requestParams: ResourcesRequest
) = Futures.immediateFuture(
Resources.Builder()
    .setVersion("1")
    .addIdToImageMapping("image_from_resource", ImageResource.Builder()
        .setAndroidResourceByResId(AndroidImageResourceByResId.Builder()
            .setResourceId(R.drawable.image_id)
            .build()
        ).build()
    )
    .addIdToImageMapping("image_inline", ImageResource.Builder()
        .setInlineResource(InlineImageResource.Builder()
            .setData(imageAsByteArray)
            .setWidthPx(48)
            .setHeightPx(48)
            .setFormat(ResourceBuilders.IMAGE_FORMAT_RGB_565)
            .build()
        ).build()
    ).build()
)

Java

@Override
protected ListenableFuture<Resources> onTileResourcesRequest(
       @NonNull ResourcesRequest requestParams
) {
return Futures.immediateFuture(
    new Resources.Builder()
        .setVersion("1")
        .addIdToImageMapping("image_from_resource", new ImageResource.Builder()
            .setAndroidResourceByResId(new AndroidImageResourceByResId.Builder()
                .setResourceId(R.drawable.image_id)
                .build()
            ).build()
        )
        .addIdToImageMapping("image_inline", new ImageResource.Builder()
            .setInlineResource(new InlineImageResource.Builder()
                .setData(imageAsByteArray)
                .setWidthPx(48)
                .setHeightPx(48)
                .setFormat(ResourceBuilders.IMAGE_FORMAT_RGB_565)
                .build()
            ).build()
        ).build()
);
}