Uygulamanızda içeriği uçtan uca görüntüleyin ve Compose'da pencere eklerini tutun

Android platformu, durum çubuğu ve gezinme çubuğu gibi sistem kullanıcı arayüzünü çizmekten sorumludur. Bu sistem kullanıcı arayüzü, kullanıcının hangi uygulamayı kullandığına bakılmaksızın gösterilir.

WindowInsets, uygulamanızın doğru alanda çizilmesini ve kullanıcı arayüzünüzün sistem kullanıcı arayüzü tarafından gizlenmemesini sağlamak için sistem kullanıcı arayüzü hakkında bilgi sağlar.

Android 14 (API düzeyi 34) ve önceki sürümlerde, uygulamanızın kullanıcı arayüzü varsayılan olarak sistem çubuklarının ve ekran kesiklerinin altına çizilmez.

Android 15 (API düzeyi 35) ve sonraki sürümlerde, uygulamanız SDK 35'i hedefledikten sonra sistem çubuklarının altında çizim yapar ve ekranda kesitler gösterir. Bu, daha sorunsuz bir kullanıcı deneyimi sağlar ve uygulamanızın kendisine sunulan pencere alanından tam olarak yararlanmasına olanak tanır.

Sistemin kullanıcı arayüzünün arkasında içerik göstermeye kenardan kenara geçme denir. Bu sayfada, farklı içe yerleştirilmiş içerik türleri, ekranı kenarlara kadar kullanma ve kullanıcı arayüzünüzü animasyonlu hale getirmek ve uygulamanızın içeriğinin sistem kullanıcı arayüzü öğeleriyle gizlenmemesini sağlamak için içe yerleştirilmiş içerik API'lerini kullanma hakkında bilgi edineceksiniz.

Eklemeyle ilgili temel bilgiler

Uygulamanız uçtan uca ilerlediğinde, önemli içerik ve etkileşimlerin sistem kullanıcı arayüzü tarafından gizlenmediğinden emin olmanız gerekir. Örneğin, gezinme çubuğunun arkasına bir düğme yerleştirilirse kullanıcı bu düğmeyi tıklayamayabilir.

Sistem kullanıcı arayüzünün boyutu ve yerleştirildiği yerle ilgili bilgiler eklemeler aracılığıyla belirtilir.

Sistem kullanıcı arayüzünün her bölümü, boyutunu ve yerleştirildiği yeri açıklayan karşılık gelen bir içe yerleştirilme türüne sahiptir. Örneğin, durum çubuğu iç içe yerleştirilmeleri durum çubuğunun boyutunu ve konumunu sağlarken gezinme çubuğu iç içe yerleştirilmeleri gezinme çubuğunun boyutunu ve konumunu sağlar. Her ek türü, dört piksel boyutundan oluşur: üst, sol, sağ ve alt. Bu boyutlar, sistem kullanıcı arayüzünün uygulama penceresinin ilgili kenarlarından ne kadar uzağa uzandığını belirtir. Bu nedenle, bu tür sistem kullanıcı arayüzüyle çakışma olmaması için uygulama kullanıcı arayüzü bu miktarda içe yerleştirilmelidir.

Aşağıdaki yerleşik Android içe yerleştirilmiş türleri WindowInsets üzerinden kullanılabilir:

Bu türler, içeriğin gizlenmesini sağlayan üç "güvenli" ek türüyle özetlenir:

• WindowInsets.safeDrawing
• WindowInsets.safeGestures
• WindowInsets.safeContent

Bu "güvenli" ek türleri, içeriği temel platform eklerine bağlı olarak farklı şekillerde korur:

• Hiçbir sistem kullanıcı arayüzünün altına çizilmemesi gereken içeriği korumak için WindowInsets.safeDrawing kullanın. Eklerin en yaygın şekilde kullanıldığı durum, sistem kullanıcı arayüzü tarafından (kısmen veya tamamen) gizlenen çizim içeriğinin önlenmesidir.
• İçerikleri hareketlerle korumak için WindowInsets.safeGestures simgesini kullanın. Bu sayede sistem hareketleri, uygulama hareketleriyle (alt sayfalar, bantlar veya oyunlardaki hareketler gibi) çakışmaz.
• İçeriğin görsel ve hareketsel olarak örtüşmediğinden emin olmak için WindowInsets.safeDrawing ve WindowInsets.safeGestures ile birlikte WindowInsets.safeContent öğesini kullanın.

Insets kurulumu

Uygulamanızın, içerikleri nereden alacağı konusunda tam kontrol sahibi olmasını sağlamak için aşağıdaki kurulum adımlarını uygulayın. Bu adımlar uygulanmazsa uygulamanız, sistem kullanıcı arayüzünün arkasında siyah veya düz renkler çizebilir ya da yazılım klavyesiyle senkronize olarak animasyon oluşturmayabilir.

1. Android 15 ve sonraki sürümlerde uçtan uca zorunlu kılmak için SDK 35 veya sonraki sürümleri hedefleyin. Uygulamanız, sistem kullanıcı arayüzünün arkasında gösterilir. Eklentileri kullanarak uygulamanızın kullanıcı arayüzünü ayarlayabilirsiniz.
2. İsteğe bağlı olarak, Activity.onCreate() içinde enableEdgeToEdge()'i çağırabilirsiniz. Bu, uygulamanızın önceki Android sürümlerinde uçtan uca ekran kullanmasına olanak tanır.

3. Etkinliğinizin AndroidManifest.xml girişinde android:windowSoftInputMode="adjustResize" değerini ayarlayın. Bu ayar, uygulamanızın yazılım IME'sinin boyutunu içe yerleştirilmiş olarak almasına olanak tanır. Bu boyutu, IME uygulamanızda göründüğünde ve kaybolduğunda içeriği uygun şekilde doldurmak ve düzenlemek için kullanabilirsiniz.

   <!-- in your AndroidManifest.xml file: -->
   <activity
     android:name=".ui.MainActivity"
     android:label="@string/app_name"
     android:windowSoftInputMode="adjustResize"
     android:theme="@style/Theme.MyApplication"
     android:exported="true">
   

API oluşturma

Etkinliğiniz tüm içe yerleştirilen öğelerin işlenmesini kontrol altına aldıktan sonra, içeriğin gizlenmediğinden ve etkileşimli öğelerin sistem kullanıcı arayüzüyle örtüşmediğinden emin olmak için Compose API'lerini kullanabilirsiniz. Bu API'ler, uygulamanızın düzenini de içe yerleştirilen değişikliklerle senkronize eder.

Örneğin, uygulamanızın tamamının içeriğine içe yerleştirilmiş öğeleri uygulamanın en temel yöntemi şudur:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    enableEdgeToEdge()

    setContent {
        Box(Modifier.safeDrawingPadding()) {
            // the rest of the app
        }
    }
}
InsetsSnippets.kt

Bu snippet, safeDrawing pencere içe eklemelerini uygulamanın tüm içeriğinin etrafına dolgu olarak uygular. Bu, etkileşime açık öğelerin sistem kullanıcı arayüzüyle örtüşmemesini sağlarken uygulamanın hiçbirinin kenardan kenara efekt elde etmek için sistem kullanıcı arayüzünün arkasında çizilmeyeceği anlamına da gelir. Pencerenin tamamını kullanmak için ekranlara veya bileşenlere göre içe yerleştirilen öğelerin uygulandığı yerlerde ince ayar yapmanız gerekir.

Bu iç içe aktarma türlerinin hepsi, API 21'e geri aktarılan IME animasyonlarıyla otomatik olarak canlandırılır. Ayrıca, bu iç içe yerleştirilen öğeleri kullanan tüm düzenleriniz, iç içe yerleştirilen öğe değerleri değiştikçe otomatik olarak animasyonlu hale gelir.

Composable düzenlerinizi ayarlamak için bu içe yerleştirilme türlerini kullanmanın iki temel yolu vardır: dolgu değiştiriciler ve içe yerleştirilme boyutu değiştiriciler.

Dolgu değiştiriciler

Modifier.windowInsetsPadding(windowInsets: WindowInsets), belirtilen pencere içe eklemelerini tıpkı Modifier.padding gibi dolgu olarak uygular. Örneğin, Modifier.windowInsetsPadding(WindowInsets.safeDrawing) güvenli çizim iç içe eklemelerini 4 tarafın tamamına dolgu olarak uygular.

En yaygın ek türleri için çeşitli yerleşik yardımcı program yöntemleri de vardır. Modifier.safeDrawingPadding(), Modifier.windowInsetsPadding(WindowInsets.safeDrawing) ile eşdeğer olan bu yöntemlerden biridir. Diğer içe yerleştirilmiş türlerde de benzer değiştiriciler vardır.

İçerik ekleme boyutu değiştiricileri

Aşağıdaki değiştiriciler, bileşenin boyutunu eklerin boyutu olacak şekilde ayarlayarak pencere içe aktarma miktarını uygular:

Bu değiştiriciler, özellikle inset alanını kaplayan bir Spacer boyutunu boyutlandırmak için yararlıdır:

LazyColumn(
    Modifier.imePadding()
) {
    // Other content
    item {
        Spacer(
            Modifier.windowInsetsBottomHeight(
                WindowInsets.systemBars
            )
        )
    }
}
InsetsSnippets.kt

Inset tüketimi

İçe yerleştirilen dolgu değiştiricileri (windowInsetsPadding ve safeDrawingPadding gibi yardımcılar), içe yerleştirilenlerin dolgu olarak uygulanan kısmını otomatik olarak tüketir. İç içe yerleştirilmiş iç dolgu değiştiricileri ve iç dolgu boyutu değiştiricileri, kompozisyon ağacında daha derine inerken iç dolguların bir kısmının dış iç dolgu değiştiriciler tarafından zaten kullanıldığını bilir ve iç dolguların aynı kısmını birden fazla kez kullanmaktan kaçınır. Bu da çok fazla ek alan kullanılmasına neden olur.

İçeriği ekleme boyutu değiştiriciler, eklentiler zaten kullanılmışsa aynı eklenti bölümünün birden fazla kez kullanılmasını da önler. Ancak boyutlarını doğrudan değiştirdikleri için kendileri yerleşik reklam tüketmez.

Sonuç olarak, iç içe yerleştirilmiş dolgu değiştiriciler her bir kompozit öğeye uygulanan dolgu miktarını otomatik olarak değiştirir.

Önceki LazyColumn örneğine baktığımızda, LazyColumn, imePadding değiştiricisi tarafından yeniden boyutlandırılıyor. LazyColumn içinde, son öğe sistem çubuklarının alt kısmının yüksekliğine göre boyutlandırılır:

LazyColumn(
    Modifier.imePadding()
) {
    // Other content
    item {
        Spacer(
            Modifier.windowInsetsBottomHeight(
                WindowInsets.systemBars
            )
        )
    }
}
InsetsSnippets.kt

IME kapatıldığında imePadding() değiştiricisi, IME'nin yüksekliği olmadığından dolgu uygulamaz. imePadding() değiştiricisi hiçbir dolgu uygulamadığından, iç içe yerleştirilmiş öğe kullanılmaz ve Spacer öğesinin yüksekliği, sistem çubuklarının alt tarafının boyutu olur.

IME açıldığında IME içe yerleştirilenleri, IME'nin boyutuna uyacak şekilde animasyonlu olarak ayarlanır ve imePadding() değiştirici, IME açıldığında LazyColumn öğesini yeniden boyutlandırmak için alt dolgu uygulamaya başlar. imePadding() değiştirici alt dolgu uygulamaya başladığında, bu miktarda içe yerleştirilmiş öğe de tüketilmeye başlar. Bu nedenle, sistem çubuklarının aralığı imePadding() değiştiricisi tarafından zaten uygulandığından Spacer öğesinin yüksekliği azalmaya başlar. imePadding() değiştirici, sistem çubuklarından daha büyük bir alt dolgu miktarı uyguladığında Spacer öğesinin yüksekliği sıfır olur.

IME kapandığında değişiklikler ters yönde gerçekleşir: imePadding(), sistem çubuklarının alt tarafından daha az uygulandığında Spacer sıfır yükseklikten genişlemeye başlar. IME tamamen animasyonla kapatıldığında Spacer, sistem çubuklarının alt tarafının yüksekliğiyle eşleşir.

Bu davranış, tüm windowInsetsPadding değiştiriciler arasında iletişim kurularak gerçekleştirilir ve birkaç başka şekilde de etkilenebilir.

Modifier.consumeWindowInsets(insets: WindowInsets), Modifier.windowInsetsPadding ile aynı şekilde içe yerleştirilen öğeleri tüketir ancak tüketilen içe yerleştirilen öğeleri dolgu olarak uygulamaz. Bu, belirli miktarda iç içe yerleştirilmiş öğenin zaten kullanıldığını kardeş öğelere belirtmek için iç içe yerleştirilmiş öğe boyutu değiştiricileriyle birlikte kullanışlıdır:

Column(Modifier.verticalScroll(rememberScrollState())) {
    Spacer(Modifier.windowInsetsTopHeight(WindowInsets.systemBars))

    Column(
        Modifier.consumeWindowInsets(
            WindowInsets.systemBars.only(WindowInsetsSides.Vertical)
        )
    ) {
        // content
        Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.ime))
    }

    Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.systemBars))
}
InsetsSnippets.kt

Modifier.consumeWindowInsets(paddingValues: PaddingValues), WindowInsets bağımsız değişkenine sahip sürüme çok benzer davranır ancak tüketmek için isteğe bağlı bir PaddingValues gerekir. Bu, dolgu veya aralığın, iç dolgu değiştiricilerden başka bir mekanizma (ör. normal Modifier.padding veya sabit yükseklikli aralıklar) tarafından sağlandığında çocukları bilgilendirmek için kullanışlıdır:

Column(Modifier.padding(16.dp).consumeWindowInsets(PaddingValues(16.dp))) {
    // content
    Spacer(Modifier.windowInsetsBottomHeight(WindowInsets.ime))
}
InsetsSnippets.kt

Ham pencere içe eklemelerinin tüketim olmadan gerekli olduğu durumlarda doğrudan WindowInsets değerlerini kullanın veya tüketimden etkilenmeyen içe eklemelerin PaddingValues değerini döndürmek için WindowInsets.asPaddingValues() değerini kullanın. Ancak aşağıdaki uyarılar nedeniyle, mümkün olduğunda pencere içe ekleme dolgu değiştiricilerini ve pencere içe ekleme boyutu değiştiricilerini kullanmayı tercih edin.

Insets ve Jetpack Compose aşamaları

Compose, ekleri güncellemek ve canlandırmak için temel AndroidX temel API'lerini kullanır. Bu API'ler, ekleri yöneten temel platform API'lerini kullanır. Bu platform davranışı nedeniyle, içe yerleştirilenler Jetpack Compose aşamalarıyla özel bir ilişkiye sahiptir.

İçe yerleştirilenlerin değeri, kompozisyon aşamasından sonra ancak düzen aşamasından önce güncellenir. Bu, kompozisyondaki içe yerleştirilen öğelerin değerinin okunması için genellikle bir kare gecikmeli bir içe yerleştirilen öğe değeri kullanılacağı anlamına gelir. Bu sayfada açıklanan yerleşik değiştiriciler, iç içe yerleştirilen öğelerin değerlerinin, yerleşim aşamasına kadar kullanılmasının geciktirilmesi için tasarlanmıştır. Bu sayede, iç içe yerleştirilen öğelerin değerleri güncellendikleri karede kullanılır.

WindowInsets içeren klavye IME animasyonları

Kaydırma içeren bir kapsayıcıya Modifier.imeNestedScroll() uygulayarak kapsayıcının alt kısmına kaydırdığınızda IME'yi otomatik olarak açıp kapatabilirsiniz.

class WindowInsetsExampleActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        WindowCompat.setDecorFitsSystemWindows(window, false)

        setContent {
            MaterialTheme {
                MyScreen()
            }
        }
    }
}

@OptIn(ExperimentalLayoutApi::class)
@Composable
fun MyScreen() {
    Box {
        LazyColumn(
            modifier = Modifier
                .fillMaxSize() // fill the entire window
                .imePadding() // padding for the bottom for the IME
                .imeNestedScroll(), // scroll IME at the bottom
            content = { }
        )
        FloatingActionButton(
            modifier = Modifier
                .align(Alignment.BottomEnd)
                .padding(16.dp) // normal 16dp of padding for FABs
                .navigationBarsPadding() // padding for navigation bar
                .imePadding(), // padding for when IME appears
            onClick = { }
        ) {
            Icon(imageVector = Icons.Filled.Add, contentDescription = "Add")
        }
    }
}
MigrationOtherConsiderationsSnippets.kt

Material 3 bileşenleri için içe yerleştirilme desteği

Kullanım kolaylığı açısından, yerleşik Material 3 composable'ların (androidx.compose.material3) birçoğu, composable'ların uygulamanıza Material özelliklerine göre nasıl yerleştirildiklerine bağlı olarak eklenerek yerleştiriliyor.

İçe yerleştirilmiş öğeleri işleme

Aşağıda, inset'leri otomatik olarak işleyen Malzeme Bileşenlerinin listesi yer almaktadır.

Uygulama çubukları

• TopAppBar / SmallTopAppBar / CenterAlignedTopAppBar / MediumTopAppBar / LargeTopAppBar: Pencerenin üst kısmında kullanıldığı için sistem çubuklarının üst ve yatay taraflarını dolgu olarak uygular.
• BottomAppBar: Sistem çubuklarının alt ve yatay taraflarını dolgu olarak uygular.

İçerik kapsayıcıları

• ModalDrawerSheet / DismissibleDrawerSheet / PermanentDrawerSheet (modal gezinme çekmecesinin içindeki içerik): İçeriğe dikey ve başlangıç iç içe yerleştirilmeleri uygular.
• ModalBottomSheet: Alt ekleri uygular.
• NavigationBar : Alt ve yatay iç içe eklemeleri uygular.
• NavigationRail: Dikey ve başlangıç iç içe yerleştirilmelerini uygular.

İskele

Varsayılan olarak Scaffold, tüketmeniz ve kullanmanız için paddingValues parametresi olarak inset'ler sağlar. Scaffold, içeriklere içe yerleştirilen öğeleri uygulamaz. Bu sorumluluk size aittir. Örneğin, bu iç içe yerleştirilen öğeleri Scaffold içinde bir LazyColumn ile kullanmak için:

Scaffold { innerPadding ->
    // innerPadding contains inset information for you to use and apply
    LazyColumn(
        // consume insets as scaffold doesn't do it by default
        modifier = Modifier.consumeWindowInsets(innerPadding),
        contentPadding = innerPadding
    ) {
        items(count = 100) {
            Box(
                Modifier
                    .fillMaxWidth()
                    .height(50.dp)
                    .background(colors[it % colors.size])
            )
        }
    }
}
InsetsSnippets.kt

Varsayılan iç içe eklemeleri geçersiz kılma

Kompozitin davranışını yapılandırmak için kompozite iletilen windowInsets parametresini değiştirebilirsiniz. Bu parametre, bunun yerine uygulanacak farklı bir pencere içe yerleştirilmesi türü olabilir veya boş bir örnek ile iletilerek devre dışı bırakılabilir: WindowInsets(0, 0, 0, 0).

Örneğin, LargeTopAppBar öğesinde içe yerleştirilme işlevini devre dışı bırakmak için windowInsets parametresini boş bir örneğe ayarlayın:

LargeTopAppBar(
    windowInsets = WindowInsets(0, 0, 0, 0),
    title = {
        Text("Hi")
    }
)
InsetsSnippets.kt

Görüntüleme sistemi iç içe yerleştirilenleriyle birlikte çalışabilirlik

Ekranınızda aynı hiyerarşide hem Görünümler hem de Oluştur kodu varsa varsayılan iç içe eklemeleri geçersiz kılmanız gerekebilir. Bu durumda, hangi öğenin içe yerleştirilenleri kullanması ve hangi öğenin bunları yoksaması gerektiğini açıkça belirtmeniz gerekir.

Örneğin, en dıştaki düzeniniz Android View düzeniyse Görünüm sistemindeki ek öğeleri kullanmalı ve Oluşturma için bunları yoksaymalısınız. Alternatif olarak, en dıştaki düzeniniz bir bileşense Oluştur'da iç içe eklemeleri kullanmanız ve AndroidView bileşenlerini uygun şekilde doldurmanız gerekir.

Varsayılan olarak her ComposeView, tüm iç metinleri WindowInsetsCompat tüketim düzeyinde tüketir. Bu varsayılan davranışı değiştirmek için ComposeView.consumeWindowInsets değerini false olarak ayarlayın.

Sistem çubuğu koruması

Uygulamanız SDK 35 veya sonraki sürümleri hedeflediğinde uçtan uca görüntüleme zorunlu kılınacaktır. Sistem durum çubuğu ve hareketle gezinme çubukları şeffaftır ancak üç düğmeli gezinme çubuğu yarı saydamdır.

Varsayılan yarı saydam üç düğmeli gezinme arka plan korumasını kaldırmak için Window.setNavigationBarContrastEnforced değerini false olarak ayarlayın.

Kaynaklar

• Android'de kullanıma sunuldu: Tamamen Kotlin ve Jetpack Compose ile geliştirilmiş, tam işlevli bir Android uygulaması.
• Android 15'te kenardan kenara yaptırımları işleme: Android 15 kenardan kenara yaptırımıyla ilgili bilgiler içeren bir codelab
• Android 15'in uçtan uca yaptırımı için ek sistemlerin kullanımıyla ilgili ipuçları
• Uygulamanızın uçtan uca kullanıcı arayüzünü önizleme ve test etme
• Android 15'teki tam ekran uygulama zorunluluğu hakkında bilgi veren Android uygulama deneyiminizi iyileştirmenizi sağlayacak 3 özellik: Tam ekran, Tahmini Geri ve Bir Bakışta başlıklı YouTube videosu
• Uçtan uca ve iç kısımlar | Oluşturma İpuçları: Kenardan kenara çizmek için eklerin nasıl ele alınacağını gösteren YouTube videosu