API varsayılanları

Material, Compose UI ve Foundation API'leri, varsayılan olarak birçok erişilebilir uygulamayı uygular ve sunar. Bu öğeler, belirli rol ve işlevlerine uygun yerleşik semantikler içerir. Bu sayede, erişilebilirlik desteğinin büyük bir kısmı çok az ek çalışmayla veya ek çalışma olmadan sağlanır.

Uygun API'leri uygun amaçla kullanmak, bileşenlerin genellikle standart kullanım alanlarını kapsayan önceden tanımlanmış erişilebilirlik davranışlarıyla birlikte geldiği anlamına gelir. Ancak bu varsayılan ayarların erişilebilirlik ihtiyaçlarınıza uygun olup olmadığını her zaman kontrol edin. Aksi takdirde Compose, daha spesifik gereksinimleri karşılamanın yollarını sunar.

Compose API'lerindeki varsayılan erişilebilirlik semantiğini ve kalıplarını anlamak, bunları erişilebilirliği göz önünde bulundurarak kullanmanıza yardımcı olur. Ayrıca daha fazla özel bileşende erişilebilirliği desteklemenize yardımcı olur.

Minimum dokunma hedefi boyutları

Kullanıcıların tıklayabileceği, dokunabileceği veya etkileşimde bulunabileceği tüm ekran öğeleri, güvenilir etkileşim için yeterince büyük olmalıdır. Bu öğeleri boyutlandırırken Materyal Tasarım erişilebilirlik yönergelerine doğru şekilde uymak için minimum boyutu 48 dp olarak ayarlayın.

Checkbox, RadioButton, Switch, Slider ve Surface gibi materyal bileşenleri, bu minimum boyutu dahili olarak ayarlar ancak bu yalnızca bileşen kullanıcı işlemlerini alabildiğinde geçerlidir. Örneğin, bir Checkbox öğesinin onCheckedChange parametresi boş olmayan bir değere ayarlandığında onay kutusu, en az 48 dp genişlik ve yüksekliğe sahip olacak şekilde dolgu içerir.

@Composable
private fun CheckableCheckbox() {
    Checkbox(checked = true, onCheckedChange = {})
}
AccessibilitySnippets.kt

Şekil 1. Varsayılan dolgulu bir onay kutusu.

onCheckedChange parametresi null olarak ayarlandığında, bileşenle doğrudan etkileşim kurulamayacağı için dolgu dahil edilmez.

@Composable
private fun NonClickableCheckbox() {
    Checkbox(checked = true, onCheckedChange = null)
}
AccessibilitySnippets.kt

Şekil 2. Dolgusuz bir onay kutusu.

Switch, RadioButton veya Checkbox gibi seçim kontrollerini uygularken genellikle composable'daki tıklama geri çağırmasını null olarak ayarlayıp üst composable'a toggleable veya selectable değiştiricisi ekleyerek tıklanabilir davranışı üst kapsayıcıya taşırsınız.

@Composable
private fun CheckableRow() {
    MaterialTheme {
        var checked by remember { mutableStateOf(false) }
        Row(
            Modifier
                .toggleable(
                    value = checked,
                    role = Role.Checkbox,
                    onValueChange = { checked = !checked }
                )
                .padding(16.dp)
                .fillMaxWidth()
        ) {
            Text("Option", Modifier.weight(1f))
            Checkbox(checked = checked, onCheckedChange = null)
        }
    }
}
AccessibilitySnippets.kt

Şekil 3. Tıklanabilir davranışa sahip bir onay kutusu.

Tıklanabilir bir composable'ın boyutu minimum dokunma hedefi boyutundan küçük olduğunda Compose, dokunma hedefi boyutunu yine de artırır. Bunu, dokunma hedefi boyutunu composable'ın sınırlarının dışına genişleterek yapar.

Aşağıdaki örnekte çok küçük bir tıklanabilir Box bulunmaktadır. Dokunma hedefi alanı, Box sınırlarının ötesine otomatik olarak genişletilir. Bu nedenle, Box öğesinin yanına dokunulduğunda tıklama etkinliği tetiklenir.

@Composable
private fun SmallBox() {
    var clicked by remember { mutableStateOf(false) }
    Box(
        Modifier
            .size(100.dp)
            .background(if (clicked) Color.DarkGray else Color.LightGray)
    ) {
        Box(
            Modifier
                .align(Alignment.Center)
                .clickable { clicked = !clicked }
                .background(Color.Black)
                .size(1.dp)
        )
    }
}
AccessibilitySnippets.kt

Şekil 4. Daha büyük bir dokunma hedefine genişletilen çok küçük tıklanabilir bir kutu.

Farklı composable'ların dokunma alanları arasında olası çakışmaları önlemek için her zaman composable için yeterince büyük bir minimum boyut kullanın. Örnekte, iç kutunun minimum boyutunu ayarlamak için sizeIn değiştiricisini kullanmanız gerekir:

@Composable
private fun LargeBox() {
    var clicked by remember { mutableStateOf(false) }
    Box(
        Modifier
            .size(100.dp)
            .background(if (clicked) Color.DarkGray else Color.LightGray)
    ) {
        Box(
            Modifier
                .align(Alignment.Center)
                .clickable { clicked = !clicked }
                .background(Color.Black)
                .sizeIn(minWidth = 48.dp, minHeight = 48.dp)
        )
    }
}
AccessibilitySnippets.kt

Şekil 5. Daha büyük bir kutu dokunma hedefi.

Öğenin daha küçük bir görünür boyutta kalması gerekiyorsa bunun yerine Material 3'teki minimumInteractiveComponentSize değiştiricisini kullanın. Her boyutta en az 48 dp düzen alanı ayırır ve öğeyi bu alanda ortalar. Böylece öğe, çizilen boyutunu korur ve etrafındaki öğeler yer açmak için hareket eder. Değiştirici, dokunma hedefini genişletmez. Daha önce açıklanan genişletme için düzende yer bırakır. Checkbox gibi Material bileşenleri bu değiştiriciyi dahili olarak kullanır. Boyut değiştiriciden önce yerleştirin. Çünkü boyut değiştirici, ayırabileceği alanı sınırlandırır.

@Composable
private fun MinimumInteractiveBox() {
    var clicked by remember { mutableStateOf(false) }
    Row(verticalAlignment = Alignment.CenterVertically) {
        Box(
            Modifier
                .clickable { clicked = !clicked }
                .minimumInteractiveComponentSize()
                .size(24.dp)
                .background(if (clicked) Color.DarkGray else Color.Black)
        )
        Text("Option")
    }
}
AccessibilitySnippets.kt

Grafik öğeler

Bir Image veya Icon composable tanımladığınızda Android çerçevesinin, uygulamanın ne gösterdiğini anlamasının otomatik bir yolu yoktur. Grafik öğenin metin açıklamasını iletmeniz gerekir.

Kullanıcının mevcut sayfayı arkadaşlarıyla paylaşabileceği bir ekran düşünün. Bu ekranda tıklanabilir bir paylaş simgesi bulunur:

Şekil 6. "Paylaş" simgesinin seçili olduğu tıklanabilir simgelerden oluşan bir satır.

Android çerçevesi, yalnızca simgeye bakarak görme engelli bir kullanıcıya simgeyi açıklayamaz. Android çerçevesi, simgenin ek bir metin açıklamasına ihtiyaç duyar.

contentDescription parametresi bir grafik öğesini tanımlar. Kullanıcı tarafından görülebildiği için yerelleştirilmiş bir dize kullanın.

@Composable
private fun ShareButton(onClick: () -> Unit) {
    IconButton(onClick = onClick) {
        Icon(
            imageVector = Icons.Filled.Share,
            contentDescription = stringResource(R.string.label_share)
        )
    }
}
AccessibilitySnippets.kt

Bazı grafik öğeler tamamen dekoratiftir ve bunları kullanıcıya iletmek istemeyebilirsiniz. contentDescription parametresini null olarak ayarladığınızda Android çerçevesine bu öğenin ilişkili işlemleri veya durumu olmadığını belirtmiş olursunuz.

@Composable
private fun PostImage(post: Post, modifier: Modifier = Modifier) {
    val image = post.imageThumb ?: painterResource(R.drawable.placeholder_1_1)

    Image(
        painter = image,
        // Specify that this image has no semantic meaning
        contentDescription = null,
        modifier = modifier
            .size(40.dp, 40.dp)
            .clip(MaterialTheme.shapes.small)
    )
}
AccessibilitySnippets.kt

contentDescription, esas olarak resim gibi grafik öğeler için kullanılmak üzere tasarlanmıştır. Button veya Text gibi Material bileşenleri ve clickable veya toggleable gibi işlem yapılabilir davranışlar, kendi davranışlarını açıklayan önceden tanımlanmış başka semantiklerle birlikte gelir ve diğer Compose API'leri aracılığıyla değiştirilebilir.

Etkileşimli öğeler

Material ve Foundation Compose API'leri, kullanıcıların clickable ve toggleable değiştirici API'leri aracılığıyla etkileşim kurabileceği kullanıcı arayüzü öğeleri oluşturur. Etkileşimli bileşenler birden fazla öğeden oluşabileceğinden clickable ve toggleable, alt öğelerinin semantiğini varsayılan olarak birleştirir. Böylece bileşen, tek bir mantıksal varlık olarak değerlendirilir.

Örneğin, bir Material Button, bir alt simge ve metinden oluşabilir. Material Button, alt öğeleri ayrı ayrı ele almak yerine varsayılan olarak alt öğe semantiğini birleştirir. Böylece erişilebilirlik hizmetleri, alt öğeleri buna göre gruplandırabilir:

Şekil 7. Birleştirilmemiş ve birleştirilmiş alt öğe semantiğine sahip düğmeler.

Benzer şekilde, clickable değiştiricisini kullanmak da bir composable'ın alt öğelerinin semantiğini tek bir varlıkta birleştirmesine neden olur. Bu varlık, ilgili işlem temsiliyle birlikte erişilebilirlik hizmetlerine gönderilir:

Row(
    // Uses `mergeDescendants = true` under the hood
    modifier = Modifier.clickable { openArticle() }
) {
    Icon(
        painter = painterResource(R.drawable.ic_logo),
        contentDescription = "Open",
    )
    Text("Accessibility in Compose")
}
AccessibilitySnippets.kt

Erişilebilirlik hizmetlerine ek bilgi sağlamak ve işlemin daha düzgün bir temsilini sunmak için üst tıklanabilir öğede belirli bir onClickLabel da ayarlayabilirsiniz:

Row(
    modifier = Modifier
        .clickable(onClickLabel = "Open this article") {
            openArticle()
        }
) {
    Icon(
        painter = painterResource(R.drawable.ic_logo),
        contentDescription = "Open"
    )
    Text("Accessibility in Compose")
}
AccessibilitySnippets.kt

TalkBack'i örnek olarak kullanırsak bu clickable değiştirici ve tıklama etiketi, TalkBack'in daha genel bir varsayılan geri bildirim olan "Etkinleştirmek için iki kez dokunun" yerine "Bu makaleyi açmak için iki kez dokunun" şeklinde bir işlem ipucu sağlamasına olanak tanır.

Bu geri bildirim, işlem türüne göre değişir. Uzun tıklama, "İki kez dokunup basılı tutarak" şeklinde bir TalkBack ipucu ve ardından bir etiket sağlar:

Row(
    modifier = Modifier
        .combinedClickable(
            onLongClickLabel = "Bookmark this article",
            onLongClick = { addToBookmarks() },
            onClickLabel = "Open this article",
            onClick = { openArticle() },
        )
) {}
AccessibilitySnippets.kt

Bazı durumlarda clickable değiştiriciye doğrudan erişiminiz olmayabilir (örneğin, daha alt bir iç içe yerleştirilmiş katmanda ayarlandığında) ancak yine de duyuru etiketini varsayılandan farklı bir değerle değiştirmek isteyebilirsiniz. Bunu yapmak için clickable ayarını, semantics değiştiricisini kullanarak duyuruyu değiştirmekten ayırın ve tıklama etiketini burada ayarlayarak işlem temsilini değiştirin:

@Composable
private fun ArticleList(openArticle: () -> Unit) {
    NestedArticleListItem(
        // Clickable is set separately, in a nested layer:
        onClickAction = openArticle,
        // Semantics are set here:
        modifier = Modifier.semantics {
            onClick(
                label = "Open this article",
                action = {
                    // Not needed here: openArticle()
                    true
                }
            )
        }
    )
}
AccessibilitySnippets.kt

Tıklama işlemini iki kez iletmeniz gerekmez. clickable veya Button gibi mevcut Compose API'leri bu işlemi sizin için gerçekleştirir. Birleştirme mantığı, mevcut bilgiler için en dıştaki değiştirici etiketinin ve işleminin yapıldığını doğrular. Önceki örnekte NestedArticleListItem, openArticle() tıklama işlemini otomatik olarak clickable semantiğine aktarır. İkinci semantik değiştirici işleminde tıklama işlemini boş bırakabilirsiniz. Ancak tıklama etiketi, ilk anlamsal değiştiricide bulunmadığı için ikinci anlamsal değiştiriciden onClick(label = "Open this document") alınır.

Alt semantiklerin üst semantiklerle birleştirilmesini beklediğiniz ancak bunun gerçekleşmediği senaryolarla karşılaşabilirsiniz. Daha ayrıntılı bilgi için Birleştirme ve temizleme bölümüne bakın.

Özel bileşenler

Özel bir bileşen oluştururken Material kitaplığında veya diğer Compose kitaplıklarında benzer bir bileşenin uygulamasını inceleyin. Ardından, erişilebilirlik davranışını uygun şekilde taklit edin veya değiştirin. Örneğin, Material Checkbox bileşenini kendi uygulamanızla değiştirirseniz mevcut Checkbox uygulamasına bakarak bileşenin erişilebilirlik özelliklerini işleyen triStateToggleable değiştiricisini eklemeniz gerektiğini hatırlayabilirsiniz. Ayrıca, yerleşik erişilebilirlik hususlarını ve bu bölümde ele alınan mevcut Compose uygulamalarını içerdiğinden Foundation değiştiricilerini yoğun bir şekilde kullanın.

Özel açma/kapatma bileşeni örneğini Semantiği temizleme ve ayarlama bölümünde bulabilirsiniz. Özel bileşenlerde erişilebilirliği destekleme hakkında daha ayrıntılı bilgiyi API yönergelerinde bulabilirsiniz.