react native safe area context
Release 5.0.0
Eine flexible Möglichkeit, sich sicher zu machen, arbeitet auch auf Android und Web!
npm install react-native-safe-area-contextyarn add react-native-safe-area-contextAnschließend müssen Sie die nativen Teile der Bibliothek für die von Ihnen verwendeten Plattformen verknüpfen.
iOS -Plattform:
$ npx pod-install
| Version | React-native Version |
|---|---|
| 5 | 0,74 |
| 4 | 0,64 |
Diese Bibliothek unterstützt derzeit experimentelle Unterstützung für die neue React-native Architektur. Beachten Sie, dass es sich um Veränderungen handelt und nur die neueste Version von React-Native unterstützt wird.
Diese Bibliothek hat 2 wichtige Konzepte. Wenn Sie mit dem React -Kontext vertraut sind, ist dies sehr ähnlich.
Die SafeareAwrovider -Komponente ist eine View , aus der die von den Verbrauchern bereitgestellten Einsätze im Verhältnis zu den Bereichen sind. Dies bedeutet, dass diese Werte den Descetent -Verbrauchern mit diesen Werten überschneidet, wenn sich diese Werte überschneiden. Normalerweise haben Sie einen Anbieter oben in Ihrer App.
Verbraucher sind Komponenten und Haken, die die Verwendung des vom nächstgelegenen übergeordneten Anbieter bereitgestellten Einschubwerte ermöglichen. Die Werte sind immer relativ zu einem Anbieter und nicht zu diesen Komponenten.
Safearaview ist die bevorzugte Möglichkeit, Einsätze zu konsumieren. Dies ist eine regelmäßige View mit Einschüssen, die als zusätzliche Polsterung oder Marge angewendet werden. Es bietet eine bessere Leistung, indem es nativ Einfügungen anwendet, und vermeidet Flackern, die mit den anderen JS -basierten Verbrauchern auftreten können.
UseSeareAinsets bietet mehr Flexibilität, kann in bestimmten Fällen jedoch dazu führen, dass Layout flackern. Verwenden Sie dies, wenn Sie mehr Kontrolle darüber benötigen, wie Insets angewendet werden.
Sie sollten SafeAreaProvider in Ihre App -Root -Komponente hinzufügen. Möglicherweise müssen Sie es an anderen Stellen wie der Wurzel von Modalen und Routen hinzufügen, wenn Sie react-native-screens verwenden.
Beachten Sie, dass Anbieter nicht in einer View sein sollten, die mit Animated oder in einer ScrollView animiert ist, da dies sehr häufige Updates verursachen kann.
import { SafeAreaProvider } from 'react-native-safe-area-context' ;
function App ( ) {
return < SafeAreaProvider > ... </ SafeAreaProvider > ;
} Akzeptiert alle Ansichtsquellen. Hat einen Standardstil von {flex: 1} .
initialMetrics Optional, Standardeinstellungen zu null .
Kann verwendet werden, um den Anfangswert für Rahmen und Einschüsse bereitzustellen. Dies ermöglicht das sofort das Rendern. Weitere Informationen zur Verwendung dieser Requisiten finden Sie unter Optimierung.
SafeAreaView ist eine reguläre View mit den als Polster oder Marge angewendeten sicheren Flächeneinsätzen.
Polster- oder Randstile werden zu den Insets hinzugefügt, z. B. style={{paddingTop: 10}} auf einer SafeAreaView mit 20 -Punkten -Einsätzen führen zu einer Top -Polsterung von 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 >
) ;
} Akzeptiert alle Ansichtsquellen.
edges Optional, Spitze von top , right , bottom und left . Standardmäßig an alle.
Legt die Kanten so ein, dass die sicheren Flächeneinschüsse auf die Anwendung von Flächen angewendet werden.
Wenn Sie beispielsweise nicht möchten, dass Insets auf die obere Kante gelten, da die Ansicht nicht die Oberseite des Bildschirms berührt, können Sie verwenden:
< SafeAreaView edges = { [ 'right' , 'bottom' , 'left' ] } /> Optional kann es auf ein Objekt eingestellt werden { top?: EdgeMode, right?: EdgeMode, bottom?: EdgeMode, left?: EdgeMode } EdgeMode = 'off' | 'additive' | 'maximum' . Additive ist ein Standardmodus und ist das gleiche wie das Übergeben und die Kante im Array: finalPadding = safeArea + padding . Der maximale Modus verwendet einen sicheren Bereich für den sicheren Bereich oder die Polsterung/Marge (abhängig vom mode ), wenn der sichere Bereich geringer ist: finalPadding = max(safeArea, padding) . Wenn Sie beispielsweise ein schwimmendes UI -Element wünschen, das sich am unteren Bereich sicherer Bereich auf Geräten mit sicherem Bereich oder 24px vom unteren Bildschirm unter den Geräten ohne sicheren Bereich befinden sollte, oder wenn sich der sichere Bereich weniger als 24px beträgt:
< SafeAreaView style = { { paddingBottom : 24 } } edges = { { bottom : 'maximum' } } /> mode Optional, padding (Standard) oder margin .
Wenden Sie den sicheren Bereich entweder auf die Polsterung oder den Rand auf.
Dies kann beispielsweise nützlich sein, um einen sicheren Bereich für die Kenntnis von Separator zu erstellen:
< SafeAreaView mode = "margin" style = { { height : 1 , backgroundColor : '#eee' } } />Gibt die sicheren Bereiche des nächsten Anbieters zurück. Dies ermöglicht es, die Einschubwerte von JavaScript zu manipulieren. Beachten Sie, dass Insets nicht synchron aktualisiert werden, sodass dies beispielsweise beim Drehen des Bildschirms zu einer leichten Verzögerung führen kann.
Objekt mit { 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 ) } } /> ;
} Gibt den Rahmen des nächsten Anbieters zurück. Dies kann als Alternative zum Dimensions verwendet werden.
Objekt mit { x: number, y: number, width: number, height: number }
SafeAreaInsetsContextReagieren Sie den Kontext mit dem Wert der sicheren Flächeneinsätze.
Kann mit Klassenkomponenten verwendet werden:
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 Komponente höherer Ordnung, die sichere Flächen als insets -Requisite einfügen.
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 } / > ;SafeAreaFrameContextReagieren Sie den Kontext mit dem Wert des sicheren Bereichsrahmens.
initialWindowMetrics Einsichten und Rahmen des Fensters zum ersten Render. Dies kann mit den initialMetrics von SafeAreaProvider verwendet werden. Weitere Informationen finden Sie unter Optimierung.
Objekt mit:
{
frame : { x : number , y : number , width : number , height : number } ,
insets : { top : number , left : number , right : number , bottom : number } ,
}HINWEIS: Dieser Wert kann null oder veraltet sein, wenn er beim Erstellen des nativen Moduls berechnet wird.
Us useSafeAreaInsets stattdessen.
Verwenden Sie stattdessen SafeAreaInsetsContext.Consumer .
Verwenden Sie stattdessen SafeAreaInsetsContext .
Verwenden Sie stattdessen initialWindowMetrics .
Wenn Sie im Web das Server -Side -Rendering durchführen, können Sie initialMetrics verwenden, um Insets und Rahmenwert basierend auf dem Gerät, das der Benutzer hat, zu injizieren oder einfach Nullwerte zu übergeben. Da die Messung der Insets asynchronisiert ist, wird es ansonsten von Ihrem Seiteninhalt zurückgegriffen.
Wenn Sie können, verwenden Sie SafeAreaView . Es ist nativ implementiert, so dass beim Drehen des Geräts keine Verzögerung von der asynchronen Brücke vorliegt.
Um das anfängliche Render zu beschleunigen, können Sie initialWindowMetrics aus diesem Paket importieren und als initialMetrics -Requisiten für den Anbieter festlegen, wie in Web SSR beschrieben. Sie können dies nicht tun, wenn Ihr Anbieter wieder resultiert, oder Sie verwenden react-native-navigation .
import {
SafeAreaProvider ,
initialWindowMetrics ,
} from 'react-native-safe-area-context' ;
function App ( ) {
return (
< SafeAreaProvider initialMetrics = { initialWindowMetrics } >
...
</ SafeAreaProvider >
) ;
} Diese Bibliothek umfasst einen eingebauten Schein für Scherz. Es wird standardmäßig die folgenden Metriken verwenden:
{
frame : {
width : 320 ,
height : 640 ,
x : 0 ,
y : 0 ,
} ,
insets : {
left : 0 ,
right : 0 ,
bottom : 0 ,
top : 0 ,
} ,
}Um es zu verwenden, fügen Sie den folgenden Code der Scherz -Setup -Datei hinzu:
import mockSafeAreaContext from 'react-native-safe-area-context/jest/mock' ;
jest . mock ( 'react-native-safe-area-context' , ( ) => mockSafeAreaContext ) ; Um mehr Kontrolle über die Testwerte zu haben, ist es auch möglich, initialMetrics an SafeAreaProvider zu übergeben, um Scheindaten für Rahmen und Einsätze bereitzustellen.
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 >
) ;
} Beim Versuch, dieses Schein zu verwenden, ist ein häufig auftretender Fehler:
SyntaxError : Cannot use import statement outside a module .Dieses Problem ergibt sich aus der Verwendung der Import -Erklärung. Um es zu beheben, müssen Sie Babel erlauben, die Datei zu analysieren.
Standardmäßig analysiert Jest keine Dateien im Ordner node_modules.
Sie können dieses Verhalten jedoch wie in der Scherzdokumentation zur transformIgnorePatterns -Anpassung ändern. Wenn Sie eine Voreinstellung verwenden, wie die von React-native, sollten Sie Ihre Scherzkonfiguration aktualisieren, um react-native-safe-area-context zu enthalten, wie unten gezeigt:
transformIgnorePatterns: [
'node_modules/(?!((jest-)?react-native|@react-native(-community)?|react-native-safe-area-context)/)' ,
] ;Diese Anpassung sorgt dafür, dass Babel Module korrekt analysiert und den oben genannten Syntaxfehler vermeidet.
Siehe den beitragenden Leitfaden
