API varsayılanları

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

Material, Compose kullanıcı arayüzü ve Foundation API'leri, varsayılan olarak birçok erişilebilir uygulamayı uygular ve sunar. Bu öğeler, belirli rollerine ve işlevlerine uygun yerleşik anlamlar içerir. Bu sayede, erişilebilirlik desteğinin çoğu ek çalışma gerektirmeden veya çok az çalışmayla sağlanır.

Uygun API'leri uygun amaç için kullanmak genellikle bileşenlerin standart kullanım alanlarını kapsayan önceden tanımlanmış erişilebilirlik davranışlarına sahip olduğu anlamına gelir. Ancak bu varsayılan ayarların erişilebilirlik ihtiyaçlarınıza uygun olup olmadığını tekrar kontrol etmeyi unutmayın. Aksi takdirde, Oluştur'da daha spesifik gereksinimleri karşılama yöntemleri de bulunur.

Compose API'lerindeki varsayılan erişilebilirlik anlamlarını ve kalıplarını bilmek, bunları erişilebilirlik göz önünde bulundurularak nasıl kullanacağınızı anlamanıza ve daha fazla özel bileşende erişilebilirliği desteklemenize yardımcı olur.

Minimum dokunma hedefi boyutları

Ekranda gösterilen ve kullanıcıların tıklayabileceği, dokunabileceği veya herhangi bir şekilde etkileşimde bulunabileceği öğeler, güvenilir etkileşim için yeterli büyüklükte olmalıdır. Bu öğeleri boyutlandırırken Materyal Tasarım erişilebilirlik kurallarına 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 belirler ancak yalnızca bileşen kullanıcı işlemlerini alabiliyorsa. Örneğin, bir Checkbox'nin 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

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

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

Switch, RadioButton veya Checkbox gibi seçim denetimlerini uygularken genellikle composable'daki tıklama geri çağırma işlevini null olarak ayarlayarak ve üst composable'a bir toggleable veya selectable değiştirici ekleyerek tıklanabilir davranışı üst kapsayıcıya kaldırı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

Tıklanabilir bir composable'ın boyutu minimum dokunma hedefi boyutundan küçük olsa bile Oluştur, dokunma hedefi boyutunu artırır. Bunu, dokunma hedefi boyutunu kompozisyonun sınırlarının dışına çıkararak yapar.

Aşağıdaki örnekte çok küçük bir tıklanabilir Box yer almaktadır. Dokunma hedef alanı, Box'ün sınırları dışında otomatik olarak genişletilir. Bu nedenle, Box'ün yanındaki alana dokunmak tıklama etkinliğini tetikler.

@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

Farklı bileşenlerin dokunma alanları arasında olası çakışmaların oluşmasını önlemek için bileşen için her zaman yeterince büyük bir minimum boyut kullanın. Bu örnekte, iç kutunun minimum boyutunu ayarlamak için sizeIn değiştiricisini kullanmak 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

Grafik öğeleri

Bir Image veya Icon bileşeni tanımladığınızda Android çerçevesinin, uygulamanın neyi gösterdiğini anlaması için otomatik bir yolu yoktur. Grafik öğesinin 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:

Android çerçevesi, yalnızca simgeye dayanarak görsel engelli bir kullanıcıya simgeyi açıklayamaz. Android çerçevesinin, simgenin ek bir metin açıklamasına ihtiyacı vardır.

contentDescription parametresi bir grafik öğeyi 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 öğeleri tamamen dekoratiftir ve bunları kullanıcıya göstermek istemeyebilirsiniz. contentDescription parametresini null olarak ayarladığınızda Android çerçevesine bu öğenin ilişkili işlem veya duruma sahip olmadığını belirtirsiniz.

@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, temel olarak resimler gibi grafik öğeler için kullanılmalıdır. Button veya Text gibi materyal bileşenler ve clickable veya toggleable gibi işlem yapılabilir davranışlar, kendi içsel davranışlarını açıklayan diğer önceden tanımlanmış anlamlarla 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şimde bulunabileceği kullanıcı arayüzü öğeleri oluşturur. Etkileşimli bileşenler birden fazla öğeden oluşabileceğinden clickable ve toggleable, alt öğelerinin anlamlarını varsayılan olarak birleştirir. Böylece bileşen tek bir mantıksal varlık olarak değerlendirilir.

Örneğin, bir Button malzemesi bir alt öğe simgesinden ve bazı metinlerden oluşabilir. Materyal düğmeler, alt öğeleri ayrı ayrı ele almak yerine varsayılan olarak alt öğelerinin anlamlarını birleştirir. Böylece erişilebilirlik hizmetleri, alt öğeleri uygun şekilde gruplandırabilir:

Benzer şekilde, clickable değiştiricinin kullanılması da bir derlenebilir öğenin alt öğelerinin anlamlarını tek bir öğede birleştirmesine neden olur. Bu öğe, ilgili işlem temsiliyle 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 şık bir temsilini sunmak için üst öğede tıklanabilir bir onClickLabel de 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 alırsak bu clickable değiştirici ve tıklama etiketi, TalkBack'in "Etkinleştirmek için iki kez dokunun" şeklindeki daha genel varsayılan geri bildirim 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şlemin türüne bağlı olarak değişir. Uzun tıklama yaptığınızda TalkBack, "İki kez dokunup basılı tutun" şeklinde bir ipucu ve ardından bir etiket gösterir:

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 değiştirmek isteyebilirsiniz. Bunu yapmak için clickable ayarını, semantics değiştiriciyi kullanarak duyuruyu değiştirmekten ayırın ve işlem temsilini değiştirmek için tıklama etiketini burada ayarlayın:

@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

Bu durumda, clickable veya Button gibi mevcut Compose API'leri bu işlemi sizin için hallettiğinden tıklama işlemini iki kez iletmeniz gerekmez. Bunun nedeni, birleştirme mantığının mevcut bilgiler için en dış değiştirici etiketin ve işlemin kullanılmasını sağlamasıdır.

Önceki örnekte, openArticle() tıklama işlemi NestedArticleListItem tarafından otomatik olarak clickable anlamlarına derinlemesine iletilir ve ikinci anlam değiştirici işleminde null olarak bırakılabilir. Ancak tıklama etiketi, ilkinde bulunmadığı için ikinci anlam değiştiriciden onClick(label = "Open this article") alınır.

Alt öğelerin semantiklerinin bir üst öğeyle 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 bileşenler için genel kural olarak, Material kitaplığındaki veya diğer Compose kitaplarındaki benzer bir bileşenin uygulanmasına bakın ve uygun olduğunda erişilebilirlik davranışını taklit edin veya değiştirin.

Örneğin, Materyal Checkbox öğesini kendi uygulamanızla değiştiriyorsanız mevcut onay kutusunun uygulanmasına bakarak bu bileşenin erişilebilirlik özelliklerini yöneten triStateToggleable değiştiriciyi eklemeniz gerektiğini hatırlatabilirsiniz.

Ayrıca, bu bölümde ele alınan mevcut Oluşturma uygulamaları ve hazır erişilebilirlik hususları da dahil olmak üzere Foundation değiştiricileri yoğun bir şekilde kullanın.

Semantikleri temizleme ve ayarlama bölümünde özel bir açma/kapatma düğmesi bileşeni örneğini bulabilir, ayrıca API yönergelerinde özel bileşenlerde erişilebilirliği destekleme hakkında daha ayrıntılı bilgi edinebilirsiniz.