Compose'da pencere ekleri

Android platformu, ve gezinme çubuğunda görünür. Bu sistem kullanıcı arayüzü, kullanıyor.

WindowInsets, sistem hakkında bilgi sağlar Uygulamanızın doğru alanı çizmesini ve kullanıcı arayüzünüzün gizlenmemesini sağlayan kullanıcı arayüzü olduğunu görebilirsiniz.

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

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 çok sorunsuz bir kullanıcı deneyimi sunar ve uygulamanızın, bir alan sağlar.

İç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. içerme işlemleri aracılığıyla.

Sistem kullanıcı arayüzünün her bir bölümü, ve nereye yerleştirildiğini gösterir. Ö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 ek türleri WindowInsets aracılığıyla kullanılabilir:

WindowInsets.statusBars

Durum çubuklarını açıklayan ekler. 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 veya gezinme simgelerini açıklayan sistem kullanıcı arayüzü çubuklarıdır. Bu ayarlar, kullanıcının tercih ettiği gezinme yöntemine ve görev çubuğuyla etkileşimde bulunmasına bağlı olarak çalışma zamanında değişebilir.

WindowInsets.navigationBarsIgnoringVisibility

Görünür oldukları zamanlara ilişkin gezinme çubuğu ekler. Gezinme çubukları şu anda gizliyse (kapsamlı tam ekran moduna geçilmesi nedeniyle) ana gezinme çubuğu ekleri boş olur, ancak bu ekler 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

Görünür oldukları zamanlara ilişkin sistem çubuğu ekler. Sistem çubukları şu anda gizliyse (kapsamlı tam ekran moduna geçilmesi nedeniyle) ana sistem çubuğu ekleri boş olur, ancak bu ekler 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 klavyesinin, geçerli klavye animasyonundan sonra kaplayacağı alan miktarını açıklayan ek bilgiler.

WindowInsets.tappableElement

Gezinme kullanıcı arayüzü hakkında daha ayrıntılı bilgileri açıklayan ve "dokunmaların" bulunduğu alanı veren bir ek türü işlem uygulama tarafından değil, sistem tarafından işlenir. Hareketle gezinme içeren şeffaf gezinme çubukları için bazı uygulama öğelerine sistem gezinme kullanıcı arayüzü üzerinden dokunulabilir.

WindowInsets.tappableElementIgnoringVisibility

Dokunulabilir öğe, görünür oldukları zamanlara eklenir. 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 hareketlerine müdahale edeceği eklerin miktarını temsil eden ekler. 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 kesimi (çentik veya iğne deliği) ile çakışmayı önlemek için gereken boşluk miktarını temsil eden ek değerler.

WindowInsets.waterfall

Şelale görüntüsünün kavisli alanlarını temsil eden ek kısımlar. Şelale görüntüsünde, ekranın kenarlarında cihazın kenarları boyunca kaymaya başladığı kavisli alanlar bulunuyor.

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

Bunlar "güvenli" inset türleri, içerik türüne bağlı olarak içeriği farklı şekillerde korur. temel platform eklerini içerir:

  • Ç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.

Insets kurulumu

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, enableEdgeToEdge() numaralı telefonu şurada çağırın: Activity.onCreate(), önceki deneyimde uygulamanızın baştan sona Android sürümleri.

  3. Etkinliğinizde android:windowSoftInputMode="adjustResize" AndroidManifest.xml giriş. Bu ayar, uygulamanızın içeriği yerleştirmek ve düzenlemek için kullanabileceğiniz ek olarak yazılım IME'si IME, uygulamanızda görünüp kaybolduğunda uygun şekilde

    <!-- 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 eklerin işlenmesini kontrol ettiğinde İçeriğin bulanıklaştırılmamasını ve etkileşimli öğelerin görünmediğinden emin olmak için birbiriyle çakıştığından emin olun. Bu API'ler ayrıca uygulamanızın düzenini inset değişiklikleri.

Örneğin bu, ekleri içeriğe uygulamanın en temel yöntemidir. kullanın:

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

    enableEdgeToEdge()

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

Bu snippet, safeDrawing pencere eklerini uygulamanın tüm içeriğini kontrol edebilirsiniz. Bu, etkileşimde bulunulabilir öğelerin sistem kullanıcı arayüzüyle çakışıyorsa, hiçbir uygulamanın uçtan uca efekt elde etmek için sistem kullanıcı arayüzünü devreye sokmaktır. Google Etiket Yöneticisi'nin sonra, eklerin uygulandığı yerlerde tek tek ekranda ince ayar yapmanız gerekir veya bileşen bazında sunmanızı sağlar.

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.

Oluşturulabilir reklam öğenizi ayarlamak için bu ek türlerini kullanmanın iki temel yolu vardır düzenler: dolgu değiştiricileri ve iç içe yerleştirilmiş boyut değiştiricileri

Dolgu değiştiriciler

Modifier.windowInsetsPadding(windowInsets: WindowInsets), dolgu olarak verilen pencere eklerini Modifier.padding gibi davranır. Örneğin, Modifier.windowInsetsPadding(WindowInsets.safeDrawing) geçerlidir güvenli çizim, 4 tarafın da dolgusu olarak eklenir.

En yaygın ek 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 inset boyutu olması gerekir:

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 (ör. Modifier.height)

Modifier.windowInsetsBottomHeight(windowInsets: WindowInsets)

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

Bu değiştiriciler özellikleSpacer inset alanı:

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ştirme dolgu değiştiricileri kullanmak istediğiniz dolgu.

Önceki LazyColumn örneğine baktığımızda LazyColumn, imePadding değiştiricisiyle yeniden boyutlandırıldı. LazyColumn içindeki son öğe yüksekliği kadar olacak şekilde e-tablonuz görüntülenir:

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

IME kapatıldığında imePadding() değiştiricisi dolgu uygulamaz çünkü IME'nin yüksekliği yoktur. imePadding() değiştiricisi dolgu uygulamadığından hiçbir ek tüketilmez ve Spacer öğesinin yüksekliği, yer alır.

IME açıldığında, IME'nin içe aktarması IME'nin boyutuna uyacak şekilde canlandırılır ve imePadding() değiştiricisi, IME açılırken LazyColumn. imePadding() değiştirici uygulanmaya başladığında alt dolgusu o kadar miktarda içe aktarılmaya başlar. Dolayısıyla, Spacer yüksekliği, sistemdeki boşluğun bir parçası olarak azalmaya başlar çubuklar imePadding() değiştiricisi tarafından zaten uygulandı. Bir imePadding() değiştiricisi daha büyük bir alt dolgu uyguluyor Spacer yüksekliği sıfırdır.

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.
ziyaret edin.

Bu davranış tüm paydaşların arasındaki iletişimle gerçekleştirilir windowInsetsPadding değiştiricileridir ve birkaç başka düzenleyiciden etkilenebilir yolları.

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) çok davranıyor WindowInsets bağımsız değişkeni olan sürüme benzer, ancak isteğe bağlı PaddingValues. Bu, proje başlatma belgenizi normal Modifier.padding veya sabit yükseklik gibi iç dolgu değiştiricileri ayırıcılar:

@OptIn(ExperimentalLayoutApi::class)
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. Bununla birlikte, aşağıdaki uyarılardan dolayı, pencere iç içe geçmiş dolgusunu kullanmayı tercih edin değiştiricileri ve pencere iç içe geçmişleri boyut değiştiricileri kullanın.

Insets ve Jetpack Compose aşamaları

Compose, ek öğeleri güncellemek ve canlandırmak için temel AndroidX temel API'lerini kullanır. kullanılan 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.

Eklerin değeri beste aşamasından sonra ancak önce önce güncellenir pek çok farklı işlevi vardır. Bu, iç içe yerleştirilmiş öğelerin değerinin okunması, genellikle bir kare gecikmeli ek değerleri kullanır. Yerleşik değiştiricileri oluşturmak için, bu sayfada açıklanan işlevlerin Bu düzen aşamasına kadar inset değerleri kullanılır. Bu da içe aktarılan değerlerin aynı kareyi seçmeniz gerekir.

WindowInsets içeren klavye IME animasyonları

Kaydırma kapsayıcısını açmak ve kapatmak için Modifier.imeNestedScroll() öğesini IME'yi, kapsayıcının en altına kaydırırken otomatik olarak kapatır.

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 inset desteği

Kullanım kolaylığı açısından, yerleşik Material 3 composable'larının çoğu (androidx.compose.material3) composable'ların uygulamanıza nasıl yerleştirildiklerine bağlı olarak eklerin kendilerini işlemesi Malzeme spesifikasyonlarına uygun olmalıdır.

Inset işleme composable'ları

Aşağıda Malzeme listesi verilmiştir bileşenlerden inset'leri 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 ekleriyle birlikte çalışma

Ekranınızda hem Görünümler hem de görünümler olduğunda varsayılan değerleri geçersiz kılmanız gerekebilir. Kodu aynı hiyerarşide oluşturun. 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, WindowInsetsCompat tüketim seviyesi. Bu varsayılan davranışı değiştirmek için ComposeView.consumeWindowInsets Hedef: false.

Kaynaklar

ziyaret edin. ziyaret edin.