react native safe area context
Release 5.0.0
Cara fleksibel untuk menangani area yang aman, juga berfungsi di Android dan Web!
npm install react-native-safe-area-contextyarn add react-native-safe-area-contextAnda kemudian perlu menautkan bagian asli perpustakaan untuk platform yang Anda gunakan.
Platform iOS:
$ npx pod-install
| versi | Versi reaksi-asli |
|---|---|
| 5 | 0.74 |
| 4 | 0.64 |
Perpustakaan ini saat ini memiliki dukungan eksperimental untuk arsitektur reaksi-asli yang baru. Perhatikan bahwa akan ada perubahan yang melanggar dan hanya versi terbaru dari React-asli yang akan didukung.
Perpustakaan ini memiliki 2 konsep penting, jika Anda terbiasa dengan konteks React, ini sangat mirip.
Komponen SafeareAprovider adalah View dari mana inset yang disediakan oleh konsumen relatif. Ini berarti bahwa jika tampilan ini tumpang tindih dengan elemen sistem apa pun (bilah status, takik, dll.) Nilai -nilai ini akan diberikan kepada konsumen keturunan. Biasanya Anda akan memiliki satu penyedia di bagian atas aplikasi Anda.
Konsumen adalah komponen dan kait yang memungkinkan menggunakan nilai inset yang disediakan oleh penyedia induk terdekat. Nilai selalu relatif terhadap penyedia dan bukan terhadap komponen -komponen ini.
Safeareaview adalah cara yang disukai untuk mengonsumsi inset. Ini adalah View reguler dengan inset yang diterapkan sebagai bantalan atau margin tambahan. Ini menawarkan kinerja yang lebih baik dengan menerapkan inset secara asli dan menghindari flicker yang dapat terjadi dengan konsumen berbasis JS lainnya.
UseAfeareAinsets menawarkan lebih banyak fleksibilitas, tetapi dapat menyebabkan beberapa tata letak berkedip dalam kasus tertentu. Gunakan ini jika Anda membutuhkan lebih banyak kontrol atas bagaimana inset diterapkan.
Anda harus menambahkan SafeAreaProvider di komponen root aplikasi Anda. Anda mungkin perlu menambahkannya di tempat lain seperti akar modal dan rute saat menggunakan react-native-screens .
Perhatikan bahwa penyedia tidak boleh berada di dalam View yang dianimasikan dengan Animated atau di dalam ScrollView karena dapat menyebabkan pembaruan yang sangat sering.
import { SafeAreaProvider } from 'react-native-safe-area-context' ;
function App ( ) {
return < SafeAreaProvider > ... </ SafeAreaProvider > ;
} Menerima semua alat peraga tampilan. Memiliki gaya default {flex: 1} .
initialMetrics Opsional, default ke null .
Dapat digunakan untuk memberikan nilai awal untuk bingkai dan inset, ini memungkinkan rendering segera. Lihat optimasi untuk informasi lebih lanjut tentang cara menggunakan prop ini.
SafeAreaView adalah komponen View reguler dengan inset Area Aman yang diterapkan sebagai padding atau margin.
Gaya padding atau margin ditambahkan ke insets, misalnya style={{paddingTop: 10}} pada SafeAreaView yang memiliki inset 20 akan menghasilkan bantalan top 30.
import { SafeAreaView } from 'react-native-safe-area-context' ;
function SomeComponent ( ) {
return (
< SafeAreaView style = { { flex : 1 , backgroundColor : 'red' } } >
< View style = { { flex : 1 , backgroundColor : 'blue' } } />
</ SafeAreaView >
) ;
} Menerima semua alat peraga tampilan.
edges Opsional, array top , right , bottom , dan left . Default untuk semua.
Menetapkan tepi untuk menerapkan inset Area yang aman ke.
Misalnya jika Anda tidak ingin inset diterapkan ke tepi atas karena tampilan tidak menyentuh bagian atas layar yang dapat Anda gunakan:
< SafeAreaView edges = { [ 'right' , 'bottom' , 'left' ] } /> Secara opsional itu dapat diatur ke objek { top?: EdgeMode, right?: EdgeMode, bottom?: EdgeMode, left?: EdgeMode } di mana EdgeMode = 'off' | 'additive' | 'maximum' . Additive adalah mode default dan sama dengan passing dan tepi dalam array: finalPadding = safeArea + padding . Mode Maksimum Akan Menggunakan Area Safe Inset atau Padding/Margin (Tergantung pada mode ) Jika Area Aman Kurang: finalPadding = max(safeArea, padding) . Misalnya jika Anda menginginkan elemen UI mengambang yang seharusnya berada di tepi area aman di perangkat dengan area aman atau 24px dari bagian bawah layar pada perangkat tanpa area aman atau jika area aman kurang dari 24px:
< SafeAreaView style = { { paddingBottom : 24 } } edges = { { bottom : 'maximum' } } /> mode Opsional, padding (default) atau margin .
Oleskan area aman untuk bantalan atau margin.
Ini bisa berguna misalnya untuk membuat komponen pemisah Area yang aman:
< SafeAreaView mode = "margin" style = { { height : 1 , backgroundColor : '#eee' } } />Mengembalikan Area Area yang aman dari penyedia terdekat. Ini memungkinkan memanipulasi nilai inset dari JavaScript. Perhatikan bahwa inset tidak diperbarui secara sinkron sehingga dapat menyebabkan sedikit penundaan misalnya saat memutar layar.
Objek dengan { top: number, right: number, bottom: number, left: number } .
import { useSafeAreaInsets } from 'react-native-safe-area-context' ;
function HookComponent ( ) {
const insets = useSafeAreaInsets ( ) ;
return < View style = { { paddingBottom : Math . max ( insets . bottom , 16 ) } } /> ;
} Mengembalikan kerangka penyedia terdekat. Ini dapat digunakan sebagai alternatif untuk modul Dimensions .
Objek dengan { x: number, y: number, width: number, height: number }
SafeAreaInsetsContextBereaksi konteks dengan nilai inset Area Aman.
Dapat digunakan dengan komponen kelas:
import { SafeAreaInsetsContext } from 'react-native-safe-area-context' ;
class ClassComponent extends React . Component {
render ( ) {
return (
< SafeAreaInsetsContext . Consumer >
{ ( insets ) => < View style = { { paddingTop : insets . top } } /> }
</ SafeAreaInsetsContext . Consumer >
) ;
}
}withSafeAreaInsets Komponen orde lebih tinggi yang menyediakan inset area yang aman sebagai prop insets .
type Props = WithSafeAreaInsetsProps & {
someProp : number ;
} ;
class ClassComponent extends React . Component < Props > {
render ( ) {
return < View style = { { paddingTop : this . props . insets . top } } / >;
}
}
const ClassComponentWithInsets = withSafeAreaInsets ( ClassComponent ) ;
< ClassComponentWithInsets someProp = { 1 } / > ;SafeAreaFrameContextBereaksi konteks dengan nilai bingkai Area Aman.
initialWindowMetrics Inset dan bingkai jendela pada render awal. Ini dapat digunakan dengan Metrik initialMetrics dari SafeAreaProvider . Lihat optimasi untuk informasi lebih lanjut.
Objek dengan:
{
frame : { x : number , y : number , width : number , height : number } ,
insets : { top : number , left : number , right : number , bottom : number } ,
}Catatan: Nilai ini bisa nol atau ketinggalan zaman saat dihitung ketika modul asli dibuat.
Gunakan useSafeAreaInsets sebagai gantinya.
Gunakan SafeAreaInsetsContext.Consumer sebagai gantinya.
Gunakan SafeAreaInsetsContext sebagai gantinya.
Gunakan initialWindowMetrics sebagai gantinya.
Jika Anda melakukan rendering sisi server di Web, Anda dapat menggunakan initialMetrics untuk menyuntikkan inset dan membingkai nilai berdasarkan perangkat yang dimiliki pengguna, atau cukup lulus nol nilai. Karena pengukuran inset adalah async, itu akan merusak rendering konten halaman Anda sebaliknya.
Jika Anda bisa, gunakan SafeAreaView . Ini diimplementasikan secara asli sehingga saat memutar perangkat, tidak ada penundaan dari jembatan asinkron.
Untuk mempercepat render awal, Anda dapat mengimpor initialWindowMetrics dari paket ini dan ditetapkan sebagai prop initialMetrics pada penyedia seperti yang dijelaskan dalam SSR Web. Anda tidak dapat melakukan ini jika penyedia Anda kembali, atau Anda menggunakan react-native-navigation .
import {
SafeAreaProvider ,
initialWindowMetrics ,
} from 'react-native-safe-area-context' ;
function App ( ) {
return (
< SafeAreaProvider initialMetrics = { initialWindowMetrics } >
...
</ SafeAreaProvider >
) ;
} Perpustakaan ini termasuk tiruan bawaan untuk bercanda. Ini akan menggunakan metrik berikut secara default:
{
frame : {
width : 320 ,
height : 640 ,
x : 0 ,
y : 0 ,
} ,
insets : {
left : 0 ,
right : 0 ,
bottom : 0 ,
top : 0 ,
} ,
}Untuk menggunakannya, tambahkan kode berikut ke file pengaturan JEST:
import mockSafeAreaContext from 'react-native-safe-area-context/jest/mock' ;
jest . mock ( 'react-native-safe-area-context' , ( ) => mockSafeAreaContext ) ; Untuk memiliki lebih banyak kontrol atas nilai -nilai uji, juga dimungkinkan untuk meneruskan initialMetrics ke SafeAreaProvider untuk menyediakan data tiruan untuk bingkai dan inset.
export function TestSafeAreaProvider ( { children } ) {
return (
< SafeAreaProvider
initialMetrics = { {
frame : { x : 0 , y : 0 , width : 0 , height : 0 } ,
insets : { top : 0 , left : 0 , right : 0 , bottom : 0 } ,
} }
>
{ children }
</ SafeAreaProvider >
) ;
} Saat mencoba menggunakan tiruan ini, kesalahan yang sering ditemui adalah:
SyntaxError : Cannot use import statement outside a module .Masalah ini muncul karena penggunaan pernyataan impor. Untuk mengatasinya, Anda perlu mengizinkan Babel untuk menguraikan file.
Secara default, Jest tidak mengurai file yang terletak di dalam folder Node_Modules.
Namun, Anda dapat memodifikasi perilaku ini sebagaimana diuraikan dalam dokumentasi JEST pada kustomisasi transformIgnorePatterns . Jika Anda menggunakan preset, seperti yang dari React-asli, Anda harus memperbarui konfigurasi JEST Anda untuk memasukkan react-native-safe-area-context seperti yang ditunjukkan di bawah ini:
transformIgnorePatterns: [
'node_modules/(?!((jest-)?react-native|@react-native(-community)?|react-native-safe-area-context)/)' ,
] ;Penyesuaian ini memastikan Babel dengan benar mem -parses modul, menghindari kesalahan sintaks yang disebutkan di atas.
Lihat Panduan yang Berkontribusi
