react native safe area context
Release 5.0.0
Une façon flexible de gérer une zone sûre, fonctionne également sur Android et Web!
npm install react-native-safe-area-contextyarn add react-native-safe-area-contextVous devez ensuite relier les parties natives de la bibliothèque pour les plates-formes que vous utilisez.
Plateforme iOS:
$ npx pod-install
| version | version réactive-native |
|---|---|
| 5 | 0,74 |
| 4 | 0,64 |
Cette bibliothèque a actuellement un support expérimental pour la nouvelle architecture réactive-native. Notez qu'il y aura des changements de rupture et que seule la dernière version de React-Native sera prise en charge.
Cette bibliothèque a 2 concepts importants, si vous connaissez le contexte React, c'est très similaire.
Le composant SafeAreAprovider est une View d'où les encarts fournis par les consommateurs sont relatifs. Cela signifie que si cette vue chevauche des éléments système (barre d'état, encoches, etc.), ces valeurs seront fournies aux consommateurs descendants. Habituellement, vous aurez un fournisseur au sommet de votre application.
Les consommateurs sont des composants et des crochets qui permettent d'utiliser les valeurs d'encart fournies par le fournisseur parent le plus proche. Les valeurs sont toujours relatives à un fournisseur et non à ces composants.
SafeAreAreView est le moyen préféré de consommer des encarts. Il s'agit d'une View régulière avec des encarts appliqués comme un rembourrage ou une marge supplémentaire. Il offre de meilleures performances en appliquant des encarts nativement et évite les scintilleurs qui peuvent se produire avec les autres consommateurs basés sur JS.
USEAFEAREAINSETS offre plus de flexibilité, mais peut provoquer un scintillement de mise en page dans certains cas. Utilisez-le si vous avez besoin de plus de contrôle sur la façon dont les encarts sont appliqués.
Vous devez ajouter SafeAreaProvider dans le composant racine de votre application. Vous devrez peut-être l'ajouter dans d'autres endroits comme la racine des modaux et des routes lorsque vous utilisez react-native-screens .
Notez que les fournisseurs ne devraient pas être à l'intérieur d'une View animée avec Animated ou à l'intérieur d'un ScrollView car il peut provoquer des mises à jour très fréquentes.
import { SafeAreaProvider } from 'react-native-safe-area-context' ;
function App ( ) {
return < SafeAreaProvider > ... </ SafeAreaProvider > ;
} Accepte tous les accessoires de vue. A un style par défaut de {flex: 1} .
initialMetrics Facultatif, par défaut est null .
Peut être utilisé pour fournir la valeur initiale du cadre et des encarts, cela permet de rendu immédiatement. Voir l'optimisation pour plus d'informations sur la façon d'utiliser cet accessoire.
SafeAreaView est un composant View régulière avec les encarts de zone sûre appliqués en tant que rembourrage ou marge.
Des styles de rembourrage ou de marge sont ajoutés aux encarts, par exemple style={{paddingTop: 10}} sur une SafeAreaView qui a des encarts de 20 se traduira par un rembourrage supérieur de 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 >
) ;
} Accepte tous les accessoires de vue.
edges Facultatif, tableau de top , right , bottom et left . Par défaut à tous.
Définit les bords sur lesquels appliquer les encarts de zone sûre.
Par exemple, si vous ne voulez pas que les encarts s'appliquent sur le bord supérieur car la vue ne touche pas le haut de l'écran que vous pouvez utiliser:
< SafeAreaView edges = { [ 'right' , 'bottom' , 'left' ] } /> En éventuellement, il peut être défini sur un objet { top?: EdgeMode, right?: EdgeMode, bottom?: EdgeMode, left?: EdgeMode } Where EdgeMode = 'off' | 'additive' | 'maximum' . L'additif est un mode par défaut et est le même que le passage et le bord dans le tableau: finalPadding = safeArea + padding . Le mode maximum utilisera une zone sûre en encadré ou un rembourrage / marge (dépend du mode ) si une zone sûre est moindre: finalPadding = max(safeArea, padding) . Par exemple, si vous voulez un élément d'interface utilisateur flottant qui devrait être au bord du bord de la zone de sécurité inférieure sur les appareils avec une zone sûre ou 24px du bas de l'écran sur les périphériques sans zone sûre ou si une zone sûre est inférieure à 24px:
< SafeAreaView style = { { paddingBottom : 24 } } edges = { { bottom : 'maximum' } } /> mode Facultatif, padding (par défaut) ou margin .
Appliquez la zone sûre sur le rembourrage ou la marge.
Cela peut être utile par exemple pour créer un composant de séparateur conscient de la zone sûre:
< SafeAreaView mode = "margin" style = { { height : 1 , backgroundColor : '#eee' } } />Renvoie les encarts de zone sûre du fournisseur le plus proche. Cela permet de manipuler les valeurs d'encart de JavaScript. Notez que les encarts ne sont pas mis à jour de manière synchrone, il peut donc provoquer un léger retard par exemple lors de la rotation de l'écran.
Objet avec { 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 ) } } /> ;
} Renvoie le cadre du fournisseur le plus proche. Cela peut être utilisé comme alternative au module Dimensions .
Objet avec { x: number, y: number, width: number, height: number }
SafeAreaInsetsContextRéagir le contexte avec la valeur des encarts de zone sûre.
Peut être utilisé avec les composants de la classe:
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 Composant d'ordre supérieur qui fournit des encarts de zone sûrs comme accessoire 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 } / > ;SafeAreaFrameContextRéagir le contexte avec la valeur du cadre de zone sûre.
initialWindowMetrics Encarts et cadre de la fenêtre sur le rendu initial. Ceci peut être utilisé avec les initialMetrics de SafeAreaProvider . Voir l'optimisation pour plus d'informations.
Objet avec:
{
frame : { x : number , y : number , width : number , height : number } ,
insets : { top : number , left : number , right : number , bottom : number } ,
}Remarque: cette valeur peut être nulle ou obsolète car elle est calculée lorsque le module natif est créé.
Utilisez à la place useSafeAreaInsets .
Utilisez à la place SafeAreaInsetsContext.Consumer .
Utilisez à la place SafeAreaInsetsContext .
Utilisez plutôt initialWindowMetrics .
Si vous effectuez un rendu côté serveur sur le Web, vous pouvez utiliser initialMetrics pour injecter des encarts et une valeur de trame en fonction de l'appareil de l'utilisateur, ou simplement passer des valeurs zéro. Étant donné que la mesure des encarts est asynchrone, elle cassera le contenu de votre page autrement.
Si vous le pouvez, utilisez SafeAreaView . Il est implémenté nativement, donc lors de la rotation de l'appareil, il n'y a pas de retard du pont asynchrone.
Pour accélérer le rendu initial, vous pouvez importer initialWindowMetrics à partir de ce package et défini en tant qu'accessoire initialMetrics sur le fournisseur décrit dans Web SSR. Vous ne pouvez pas le faire si votre fournisseur remonte ou si vous utilisez react-native-navigation .
import {
SafeAreaProvider ,
initialWindowMetrics ,
} from 'react-native-safe-area-context' ;
function App ( ) {
return (
< SafeAreaProvider initialMetrics = { initialWindowMetrics } >
...
</ SafeAreaProvider >
) ;
} Cette bibliothèque comprend une maquette intégrée pour la plaisanterie. Il utilisera les mesures suivantes par défaut:
{
frame : {
width : 320 ,
height : 640 ,
x : 0 ,
y : 0 ,
} ,
insets : {
left : 0 ,
right : 0 ,
bottom : 0 ,
top : 0 ,
} ,
}Pour l'utiliser, ajoutez le code suivant au fichier de configuration de la plaisanterie:
import mockSafeAreaContext from 'react-native-safe-area-context/jest/mock' ;
jest . mock ( 'react-native-safe-area-context' , ( ) => mockSafeAreaContext ) ; Pour avoir plus de contrôle sur les valeurs de test, il est également possible de passer initialMetrics à SafeAreaProvider pour fournir des données simulées pour le cadre et les encarts.
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 >
) ;
} Tout en essayant d'utiliser cette simulation, une erreur fréquemment rencontrée est:
SyntaxError : Cannot use import statement outside a module .Ce problème se pose en raison de l'utilisation de l'instruction IMPORT. Pour le résoudre, vous devez permettre à Babel d'analyser le fichier.
Par défaut, Jest n'analyse pas les fichiers situés dans le dossier Node_Modules.
Cependant, vous pouvez modifier ce comportement comme indiqué dans la documentation Jest sur la personnalisation transformIgnorePatterns . Si vous utilisez un préréglage, comme celui de React-Native, vous devez mettre à jour votre configuration de plaisanterie pour inclure react-native-safe-area-context comme indiqué ci-dessous:
transformIgnorePatterns: [
'node_modules/(?!((jest-)?react-native|@react-native(-community)?|react-native-safe-area-context)/)' ,
] ;Ce réglage garantit correctement Babel analysant les modules, en évitant l'erreur de syntaxe susmentionnée.
Voir le guide contributif
