Geçiş sırasını değiştirme

Geçiş sırası, erişilebilirlik hizmetlerinin kullanıcı arayüzü öğeleri arasında gezinme sırasıdır. Compose uygulamalarında öğeler, beklenen okuma sırasına göre düzenlenir. Bu sıra genellikle soldan sağa, ardından yukarıdan aşağıya şeklindedir. Ancak Compose'un doğru okuma sırasını belirlemek için ek ipuçlarına ihtiyaç duyabileceği bazı senaryolar vardır.

isTraversalGroup ve traversalIndex, Compose'un varsayılan sıralama algoritmasının yeterli olmadığı senaryolarda erişilebilirlik hizmetlerinin gezinme sırasını etkilemenize olanak tanıyan semantik özelliklerdir. isTraversalGroup, özelleştirme gerektiren anlamsal açıdan önemli grupları tanımlarken traversalIndex, bu gruplardaki bağımsız öğelerin sırasını ayarlar. Bir gruptaki tüm öğelerin birlikte seçilmesi gerektiğini belirtmek için isTraversalGroup simgesini tek başına kullanabilir veya daha fazla özelleştirme için traversalIndex simgesiyle birlikte kullanabilirsiniz.

Ekran okuyucunun gezinme sırasını kontrol etmek için uygulamanızda isTraversalGroup ve traversalIndex kullanın.

Öğeleri gezinme için gruplandırma

isTraversalGroup, bir semantics düğümünün geçiş grubu olup olmadığını tanımlayan bir boole özelliğidir. Bu tür düğümler, alt düğümleri düzenlerken sınır görevi görür.

Bir düğümde isTraversalGroup = true ayarının yapılması, diğer öğelere geçmeden önce o düğümün tüm alt öğelerinin ziyaret edildiği anlamına gelir. Sütunlar, satırlar veya kutular gibi ekran okuyucu tarafından odaklanılamayan düğümlerde isTraversalGroup özelliğini ayarlayabilirsiniz.

Aşağıdaki örnekte isTraversalGroup kullanılmaktadır. Dört metin öğesi döndürür. Soldaki iki öğe bir CardBox öğesine, sağdaki iki öğe ise başka bir CardBox öğesine aittir:

// CardBox() function takes in top and bottom sample text.
@Composable
fun CardBox(
    topSampleText: String,
    bottomSampleText: String,
    modifier: Modifier = Modifier
) {
    Box(modifier) {
        Column {
            Text(topSampleText)
            Text(bottomSampleText)
        }
    }
}

@Composable
fun TraversalGroupDemo() {
    val topSampleText1 = "This sentence is in "
    val bottomSampleText1 = "the left column."
    val topSampleText2 = "This sentence is "
    val bottomSampleText2 = "on the right."
    Row {
        CardBox(
            topSampleText1,
            bottomSampleText1
        )
        CardBox(
            topSampleText2,
            bottomSampleText2
        )
    }
}

Kod, aşağıdakine benzer bir çıkış üretir:

İki sütun metin içeren düzen. Sol sütunda "Bu cümle sol sütunda", sağ sütunda ise "Bu cümle sağda" yazıyor.
Şekil 1. İki cümle içeren bir düzen (biri sol sütunda, diğeri sağ sütunda).

Anlamsal öğeler ayarlanmadığından ekran okuyucunun varsayılan davranışı, öğeleri soldan sağa ve yukarıdan aşağıya doğru taramaktır. Bu varsayılan ayar nedeniyle TalkBack, cümle parçalarını yanlış sırada okur:

"This sentence is in" → "This sentence is" → "the left column." → "sağda"

Parçaları doğru şekilde sıralamak için orijinal snippet'i değiştirerek isTraversalGroup değerini true olarak ayarlayın:

@Composable
fun TraversalGroupDemo2() {
    val topSampleText1 = "This sentence is in "
    val bottomSampleText1 = "the left column."
    val topSampleText2 = "This sentence is"
    val bottomSampleText2 = "on the right."
    Row {
        CardBox(
//      1,
            topSampleText1,
            bottomSampleText1,
            Modifier.semantics { isTraversalGroup = true }
        )
        CardBox(
//      2,
            topSampleText2,
            bottomSampleText2,
            Modifier.semantics { isTraversalGroup = true }
        )
    }
}

isTraversalGroup her CardBox için özel olarak ayarlandığından, öğeler sıralanırken CardBox sınırları geçerli olur. Bu durumda önce sol CardBox, ardından sağ CardBox okunur.

TalkBack artık cümle parçalarını doğru sırayla okur:

"Bu cümle" → "sol sütunda." → "This sentence is" → "on the right."

Geçiş sırasını özelleştirme

traversalIndex, TalkBack gezinme sırasını özelleştirmenize olanak tanıyan bir kayan nokta özelliğidir. Öğeleri gruplandırmak TalkBack'in doğru çalışması için yeterli değilse ekran okuyucu sıralamasını daha da özelleştirmek için traversalIndex ile birlikte isTraversalGroup kullanın.

traversalIndex özelliği aşağıdaki niteliklere sahiptir:

  • Daha düşük traversalIndex değerlerine sahip öğelere öncelik verilir.
  • Pozitif ya da negatif bir değere sahip olabilir.
  • Varsayılan değer: 0f.
  • Geçiş dizininin geçiş davranışını etkilemesi için erişilebilirlik hizmetleri tarafından seçilebilen ve odaklanılabilen bir bileşende (ör. metin veya düğme gibi ekrandaki öğeler) ayarlanması gerekir.
    • Örneğin, bir Column için yalnızca traversalIndex ayarını etkinleştirmenin hiçbir etkisi olmaz. Sütunda isTraversalGroup ayarının da etkinleştirilmesi gerekir.

Aşağıdaki örnekte, traversalIndex ve isTraversalGroup öğelerini birlikte nasıl kullanabileceğiniz gösterilmektedir.

Saat kadranı, standart gezinme sırasının işe yaramadığı yaygın bir senaryodur. Bu bölümdeki örnek, kullanıcının saat kadranındaki sayılar arasında gezinebileceği ve saat ile dakika alanları için rakamları seçebileceği bir saat seçicidir.

Üzerinde saat seçici bulunan bir kadran.
Şekil 2. Kadran resmi.

Aşağıdaki basitleştirilmiş snippet'te, 12'den başlayıp dairenin etrafında saat yönünde ilerleyen 12 sayının çizildiği bir CircularLayout vardır:

@Composable
fun ClockFaceDemo() {
    CircularLayout {
        repeat(12) { hour ->
            ClockText(hour)
        }
    }
}

@Composable
private fun ClockText(value: Int) {
    Box(modifier = Modifier) {
        Text((if (value == 0) 12 else value).toString())
    }
}

Saat kadranı, varsayılan soldan sağa ve yukarıdan aşağıya sıralamayla mantıklı bir şekilde okunmadığından TalkBack, sayıları sırayla okumaz. Bu sorunu düzeltmek için aşağıdaki snippet'te gösterildiği gibi artan sayaç değerini kullanın:

@Composable
fun ClockFaceDemo() {
    CircularLayout(Modifier.semantics { isTraversalGroup = true }) {
        repeat(12) { hour ->
            ClockText(hour)
        }
    }
}

@Composable
private fun ClockText(value: Int) {
    Box(modifier = Modifier.semantics { this.traversalIndex = value.toFloat() }) {
        Text((if (value == 0) 12 else value).toString())
    }
}

Geçiş sırasını doğru şekilde ayarlamak için önce CircularLayout öğesini geçiş grubu yapın ve isTraversalGroup = true değerini ayarlayın. Ardından, her saat metni düzene çizilirken ilgili traversalIndex değerini sayaç değerine ayarlayın.

Sayaç değeri sürekli arttığından, ekrana sayılar eklendikçe her saat değerinin traversalIndex değeri daha büyük olur. Saat değeri 0'ın traversalIndex değeri 0, saat değeri 1'in traversalIndex değeri 1'dir. Bu şekilde, TalkBack'in bunları okuma sırası ayarlanır. Artık CircularLayout içindeki sayılar beklenen sırada okunuyor.

Ayarlanan traversalIndexes yalnızca aynı gruplandırmadaki diğer dizinlere göre olduğundan, ekran sıralamasının geri kalanı korunmuştur. Başka bir deyişle, önceki kod snippet'inde gösterilen semantik değişiklikler yalnızca isTraversalGroup = true ayarının yapıldığı kadran içindeki sıralamayı değiştirir.

CircularLayout's semantiğini isTraversalGroup = true olarak ayarlamasanız bile traversalIndex değişikliklerinin geçerli olacağını unutmayın. Ancak bunları bağlayan CircularLayout olmadan, saat kadranının on iki rakamı, ekrandaki diğer tüm öğeler ziyaret edildikten sonra en son okunur. Bunun nedeni, diğer tüm öğelerin varsayılan traversalIndex değerinin 0f olması ve saat metni öğelerinin diğer tüm 0f öğelerinden sonra okunmasıdır.

API ile ilgili dikkat edilmesi gereken noktalar

Geçiş API'lerini kullanırken aşağıdakileri göz önünde bulundurun:

  • isTraversalGroup = true, gruplandırılmış öğeleri içeren üst öğede ayarlanmalıdır.
  • traversalIndex, semantik içeren ve erişilebilirlik hizmetleri tarafından seçilecek bir alt bileşende ayarlanmalıdır.
  • İncelediğiniz tüm öğelerin aynı zIndex düzeyinde olduğundan emin olun. Bu, semantiği ve gezinme sırasını da etkiler.
  • Anlamsal öğelerin gereksiz yere birleştirilmediğinden emin olun. Bu durum, bileşenlerin geçiş dizinlerinin uygulandığı bileşenleri etkileyebilir.