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ıyor.

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.

Sistem çubuklarının arkasına çizmek için kenardan kenara gitme
Şekil 1. Sistem çubuklarının arkasından çizim yapmak için baştan sona gitme.

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

Uygulamanız, Android 15 (API düzeyi 35) ve sonraki sürümlerde sistemin altında yer alır uygulamanız SDK 35'i hedefledikten sonra çubuklar ve ekran kesimleri. 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.

İçeriğin sistem kullanıcı arayüzünün arkasında gösterilmesine uçtan uca geçiş denir. Bu konuda farklı iç içe aktarma türlerini, bir uçtan uca ve kullanıcı arayüzünüze animasyon eklemek ve uygulamanızın içeriğinin tarafından engellenmez.

Ek temel bilgiler

Bir uygulama uçtan uca giderken önemli içerik ve etkileşimleri sistem arayüzü tarafından gizlenmez. Örneğin, bir düğme arkasına yerleştirildiğinde kullanıcı bu düğmeyi tıklayamayabilir.

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

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 ekleri ve konum çubuğunun konumunu gösterirken, gezinme çubuğu ekleri gezinme çubuğunun boyutuna ve konumuna göre değişiyor. Her bir ek türü dört öğeden oluşur. piksel boyutları vardır: üst, sol, sağ ve alt. Bu boyutlar, öğenin ne kadar sistem kullanıcı arayüzü, uygulama penceresinin ilgili taraflarından itibaren uzanır. Kaçınılması gerekenler Bu nedenle, uygulamanın kullanıcı arayüzü tutar.

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

WindowInsets.statusBars

Durum çubuklarını açıklayan ek açıklamalar. Bunlar, bildirim simgelerini ve diğer göstergeleri içeren en üst sistem kullanıcı arayüzü çubuklarıdır.

WindowInsets.statusBarsIgnoringVisibility

Görünür oldukları zamanları durum çubuğu ekler. Durum çubukları şu anda gizliyse (kapsamlı tam ekran moduna geçilmesi nedeniyle) ana durum çubuğu ekleri boş olur ancak bu ekler boş olmaz.

WindowInsets.navigationBars

Gezinme çubuklarını açıklayan ekler. Bunlar, cihazın sol, sağ veya alt tarafında bulunan ve görev çubuğunu ya da gezinme simgelerini açıklayan sistem kullanıcı arayüzü çubuklarıdır. Bunlar, kullanıcının tercih ettiği gezinme yöntemine ve görev çubuğuyla etkileşime göre çalışma zamanında değişebilir.

WindowInsets.navigationBarsIgnoringVisibility

Görünür olduklarında gezinme çubuğu içe yerleştirilir. Gezinme çubukları şu anda gizliyse (tam ekran moduna girildiği için) ana gezinme çubuğu iç içe yerleştirilmeleri boş olur ancak bu iç içe yerleştirilmeler boş olmaz.

WindowInsets.captionBar

Üst başlık çubuğu gibi serbest biçimli bir pencerede sistem kullanıcı arayüzü pencere süslemesini açıklayan ek.

WindowInsets.captionBarIgnoringVisibility

Altyazı çubuğu, ne zaman görünür olacağına eklenir. Altyazı çubukları şu anda gizliyse ana altyazı çubuğu ek kısımları boş olur ancak bu ek kümeler boş olmaz.

WindowInsets.systemBars

Durum çubukları, gezinme çubukları ve başlık çubuğunu içeren sistem çubuğu eklerinin birleşimi.

WindowInsets.systemBarsIgnoringVisibility

Sistem çubuğu, görünür olduğunda içe yerleştirilir. Sistem çubukları şu anda gizliyse (tam ekran moduna girildiği için) ana sistem çubuğu iç içe yerleştirilmeleri boş olur ancak bu iç içe yerleştirilmeler boş olmaz.

WindowInsets.ime

Yazılım klavyesinin alt kısmında kapladığı alan miktarını açıklayan ek bilgiler.

WindowInsets.imeAnimationSource

Yazılım klavyesinin, geçerli klavye animasyonundan önce kapladığı alan miktarını açıklayan ekler.

WindowInsets.imeAnimationTarget

Yazılım klavyenin mevcut klavye animasyonundan sonra kaplayacak alan miktarını açıklayan iç içe yerleştirilmiş resimler.

WindowInsets.tappableElement

Gezinme kullanıcı arayüzü hakkında daha ayrıntılı bilgi veren ve "dokunduğunda" dokunma işlemlerinin uygulama tarafından değil sistem tarafından işleneceği alan miktarını gösteren bir tür içe yerleştirilmiş öğe. Hareketle gezinme içeren şeffaf gezinme çubuklarında, bazı uygulama öğeleri sistem gezinme kullanıcı arayüzü üzerinden dokunulabilir.

WindowInsets.tappableElementIgnoringVisibility

Dokunulabilir öğe, görünür olduğunda içe yerleştirilir. Dokunulabilir öğeler şu anda gizliyse (etkileyici tam ekran moduna girmesi nedeniyle) dokunulabilir ana öğe ek ayarları boş olur ancak bu ek öğeler boş olmaz.

WindowInsets.systemGestures

Sistemin gezinme için hareketleri durduracağı iç içe yerleştirilmiş öğelerin miktarını temsil eden iç içe yerleştirilmiş öğeler. Uygulamalar, Modifier.systemGestureExclusion aracılığıyla bu hareketlerin sınırlı bir kısmının işlenmesini manuel olarak belirtebilir.

WindowInsets.mandatorySystemGestures

Sistem tarafından her zaman işlenecek ve Modifier.systemGestureExclusion üzerinden devre dışı bırakılamayan sistem hareketlerinin bir alt kümesi.

WindowInsets.displayCutout

Ekran kesimiyle (çentik veya delik) çakışmamayı önlemek için gereken boşluk miktarını gösteren iç içe yerleştirilmiş resimler.

WindowInsets.waterfall

Şelale ekranının kavisli alanlarını temsil eden iç içe yerleştirilmiş resimler. Şelale ekranlarda, ekranın cihazın yanlarına doğru kıvrıldığı, ekranın kenarlarında kavisli alanlar bulunur.

Bu türler, üç "güvenli" ifadesiyle özetlenir içeriğin belirli bir içeriğe belirsiz:

Bu "güvenli" içe yerleştirilmiş türleri, temel platform içe yerleştirilmişlerine göre içeriği farklı şekillerde korur:

  • Çizmemesi gereken içerikleri korumak için WindowInsets.safeDrawing özelliğini kullanın herhangi bir sistem arayüzünün altında. Eklerin en yaygın şekilde kullanıldığı durumlar şunlardır: sistem kullanıcı arayüzü tarafından (kısmen veya .
  • Hareketlerle içerikleri korumak için WindowInsets.safeGestures özelliğini kullanın. Bu Sistem hareketlerinin, uygulama hareketleriyle (alttakiler için olanlar gibi) çakışmasını önler bantlarda veya oyunlarda).
  • WindowInsets.safeContent öğesini aşağıdakilerin kombinasyonu olarak kullanın: WindowInsets.safeDrawing ve WindowInsets.safeGestures. içerikte görsel çakışma ve hareket çakışması olmamalıdır.

İç içe yerleştirilmiş öğe ayarları

Uygulamanızın içerik çektiği yerler üzerinde tam kontrol sahibi olmak için şu ayarları uygulayın: adımları. Bu adımlar olmadan, uygulamanız yazılım klavyesiyle eş zamanlı olarak animasyon uygulamamalıdır.

  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 görüntülenir. Uygulamanızın kullanıcı arayüzünü, ek'ler.
  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 tümü, IME animasyonlarıyla otomatik olarak canlandırılır API 21'e geri bağlanmış oldu. Dolayısıyla, bu ekleri kullanan tüm düzenleriniz aynı zamanda inset değerleri değiştikçe otomatik olarak canlandırılır.

Composable düzenlerinizi ayarlamak için bu içe yerleştirilmiş türleri kullanmanın iki temel yolu vardır: dolgu değiştiriciler ve içe yerleştirilmiş boyut 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.

Ayrıca, en yaygın içe yerleştirilmiş metin türleri için çeşitli yerleşik yardımcı program yöntemleri de vardır. Modifier.safeDrawingPadding(), eşdeğeri olan yöntemlerden biridir. Modifier.windowInsetsPadding(WindowInsets.safeDrawing). RACI matrisinde değiştiricileri belirleyin.

Inset boyut değiştiricileri

Aşağıdaki değiştiriciler, bileşenin boyutunu iç içe yerleştirilen öğelerin boyutuna ayarlayarak bir miktar pencere iç içe yerleştirilen öğesi uygular:

Modifier.windowInsetsStartWidth(windowInsets: WindowInsets)

Genişlik olarak windowInsets öğesinin başlangıç tarafını uygular (ör. Modifier.width)

Modifier.windowInsetsEndWidth(windowInsets: WindowInsets)

Genişlik olarak windowInsets öğesinin son tarafını uygular (ör. Modifier.width)

Modifier.windowInsetsTopHeight(windowInsets: WindowInsets)

windowInsets öğesinin üst tarafını yükseklik olarak uygular (Modifier.height gibi)

Modifier.windowInsetsBottomHeight(windowInsets: WindowInsets)

Yükseklik olarak windowInsets öğesinin alt tarafını uygular (Modifier.height gibi)

Bu değiştiriciler, özellikle de iç içe yerleştirilmiş öğelerin alanını kaplayan bir Spacer öğesinin boyutunu belirlemek için yararlıdır:

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

Inset tüketimi

Inset dolgu değiştiricileri (windowInsetsPadding ve yardımcılar gibi) safeDrawingPadding), eklerin dolgu olarak uygulanır. Kompozisyon ağacının derinlerine inerken, iç içe yerleştirilmiş dolgu değiştiricileri ve inset boyut değiştiricileri, tablodaki inset'ler, dış içe doğru dolgu değiştiricileri tarafından zaten kullanıldı ve eklerin aynı kısmını birden fazla kez kullanmak da alan sağlar.

Inset boyut değiştiricileri, eklerin aynı bölümünü birden fazla kez kullanmaktan da kaçınır . Ancak, kurumsal sorumluluklarını değiştirdikleri için, boyutunu doğrudan kullanmazlar.

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 kapalıyken imePadding() değiştirici, IME'nin yüksekliği olmadığı için 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 kapatıldığında değişiklikler tersten gerçekleşir: Spacer imePadding(), Spacer işareti, yüksekliğin yüksekliğine eşitlenene kadar, sistem çubuklarının alt tarafındaki devre dışı bırakıldıktan sonra sistem çubuklarının alt tarafındaki

Şekil 2. TextField içeren uçtan uca geç sütun.

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

Modifier.consumeWindowInsets(insets: WindowInsets) ek öğeleri de tüketir Modifier.windowInsetsPadding ile aynıdır ancak bu tür dolgu olarak tüketilir. Bu, ek kardeşlere belirli sayıda ekin mevcut olduğunu belirtmek için zaten tüketildi:

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şkeni olan sürüme çok benzer şekilde çalışır ancak rastgele bir PaddingValues alır. 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 eklerinin tüketilmeden gerekli olduğu durumlarda WindowInsets değerlerini doğrudan girin veya şu işlemler için WindowInsets.asPaddingValues() kullanın: ve tüketimden etkilenmeyen eklerin PaddingValues kadarını döndürür. 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.

İçerikler ve Jetpack Compose aşamaları

Compose, iç içe yerleştirilen öğeleri güncellemek ve animasyonlu hale getirmek için temel AndroidX çekirdek API'lerini kullanır. Bu API'ler, iç içe yerleştirilen öğeleri yöneten temel platform API'lerini kullanır. Bu platform sayesinde eklerin Jetpack'in evreleriyle özel bir ilişkisi vardır Oluştur'u tıklayın.

İçe yerleştirilenlerin değeri, kompozisyon aşamasından sonra ancak düzen aşamasından önce güncellenir. Bu, iç içe yerleştirilmiş öğelerin değerinin okunması, genellikle bir kare gecikmeli ek değerleri kullanır. 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 ile klavye IME animasyonlarını kullanma

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

Klavye yer açmak için yukarı ve aşağı kaydırılan kullanıcı arayüzü öğesini gösteren animasyon
Şekil 3. IME animasyonları.

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

Kullanım kolaylığı için, yerleşik Material 3 bileşenlerinin çoğu (androidx.compose.material3), bileşenlerin Material spesifikasyonlarına göre uygulamanıza nasıl yerleştirildiğine bağlı olarak iç içe eklemeleri kendileri yönetir.

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

Aşağıda Malzeme listesi verilmiştir bileşenlerden insetleri otomatik olarak işler.

Uygulama çubukları

İçerik kapsayıcıları

İskele

Varsayılan olarak Scaffold kullanmanız ve kullanmanız için paddingValues parametresi olarak ek değerler sağlar. Scaffold, ekleri içeriğe uygulamaz; bu sorumluluk size aittir. Örneğin, bu ek öğ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 ek değerlerini geçersiz kıl

composable'a iletilen windowInsets parametresini şu şekilde değiştirebilirsiniz: composable'ın davranışını yapılandırın. Bu parametre farklı bir window inset parametresi bunun yerine uygulanacak veya boş bir örnek iletilerek devre dışı bırakılmalıdır: WindowInsets(0, 0, 0, 0)

Örneğin, LargeTopAppBar, 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ştirilmiş içerikleriyle 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, konu hakkında ek öğeleri hangisinin tüketmesi gerektiği ve hangisinin yoksayılması gerektiği.

Örneğin, en dıştaki düzeniniz bir Android View düzeniyse insetleri Görüntüle sisteminde tüketme ve Oluşturma için bunları yoksayma. Alternatif olarak, en dıştaki düzeniniz bir composable ise inset'leri ekleyin ve AndroidView composable'ı buna uygun şekilde yerleştirin.

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.

Kaynaklar