react native safe area context
Release 5.0.0
¡Una forma flexible de manejar un área segura, también funciona en Android y Web!
npm install react-native-safe-area-contextyarn add react-native-safe-area-contextLuego debe vincular las partes nativas de la biblioteca para las plataformas que está utilizando.
Plataforma iOS:
$ npx pod-install
| versión | versión react-nativa |
|---|---|
| 5 | 0.74 |
| 4 | 0.64 |
Esta biblioteca actualmente tiene soporte experimental para la nueva arquitectura react-nativa. Tenga en cuenta que habrá cambios de ruptura y solo se admitirá la última versión de React-Native.
Esta biblioteca tiene 2 conceptos importantes, si está familiarizado con el contexto React, esto es muy similar.
El componente SafeAleProvider es una View desde donde se encuentran las inserciones proporcionadas por los consumidores. Esto significa que si esta vista se superpone con algún elemento del sistema (barra de estado, muescas, etc.) se proporcionarán estos valores a los consumidores descendientes. Por lo general, tendrá un proveedor en la parte superior de su aplicación.
Los consumidores son componentes y ganchos que permiten el uso de valores de inserción proporcionados por el proveedor principal más cercano. Los valores siempre son relativos a un proveedor y no con estos componentes.
SafeareAview es la forma preferida de consumir inserciones. Esta es una View regular con inserciones aplicadas como acolchado o margen adicionales. Ofrece un mejor rendimiento aplicando inserciones de forma nativa y evita los parpadeos que pueden ocurrir con los otros consumidores basados en JS.
UssAfeareaInsets ofrece más flexibilidad, pero puede causar algún parpadeo de diseño en ciertos casos. Use esto si necesita más control sobre cómo se aplican las inserciones.
Debe agregar SafeAreaProvider en el componente de la raíz de su aplicación. Es posible que deba agregarlo en otros lugares como la raíz de los modales y las rutas cuando se usa react-native-screens .
Tenga en cuenta que los proveedores no deben estar dentro de una View animada con Animated o dentro de una ScrollView , ya que puede causar actualizaciones muy frecuentes.
import { SafeAreaProvider } from 'react-native-safe-area-context' ;
function App ( ) {
return < SafeAreaProvider > ... </ SafeAreaProvider > ;
} Acepta todos los accesorios de vista. Tiene un estilo predeterminado de {flex: 1} .
initialMetrics Opcional, predeterminado es null .
Se puede usar para proporcionar el valor inicial para el marco y las inserciones, esto permite hacer que la representación inmediatamente. Consulte la optimización para obtener más información sobre cómo usar este accesorio.
SafeAreaView es un componente View regular con los inserciones de área segura aplicadas como relleno o margen.
Los estilos de acolchado o margen se agregan a los inserciones, por ejemplo, style={{paddingTop: 10}} en una SafeAreaView que tiene las inserciones de 20 darán como resultado un relleno superior 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 >
) ;
} Acepta todos los accesorios de vista.
edges Opcional, matriz de top , right , bottom e left . Predeterminado a todos.
Establece los bordes para aplicar las inserciones de área segura.
Por ejemplo, si no desea que los inserciones se apliquen al borde superior porque la vista no toca la parte superior de la pantalla que puede usar:
< SafeAreaView edges = { [ 'right' , 'bottom' , 'left' ] } /> Opcionalmente se puede configurar en un objeto { top?: EdgeMode, right?: EdgeMode, bottom?: EdgeMode, left?: EdgeMode } donde EdgeMode = 'off' | 'additive' | 'maximum' . El aditivo es un modo predeterminado y es el mismo que pasar y borde en la matriz: finalPadding = safeArea + padding . El modo máximo utilizará un área segura de área o relleno/margen (depende del mode ) si el área segura es menor: finalPadding = max(safeArea, padding) . Por ejemplo, si desea un elemento de interfaz de usuario flotante que debe estar en el borde de área segura inferior en dispositivos con área segura o 24 px desde la parte inferior de la pantalla en dispositivos sin área segura o si un área segura es inferior a 24 px:
< SafeAreaView style = { { paddingBottom : 24 } } edges = { { bottom : 'maximum' } } /> mode Opcional, padding (predeterminado) o margin .
Aplique el área segura al relleno o al margen.
Esto puede ser útil, por ejemplo, para crear un componente de separador de área seguro consciente:
< SafeAreaView mode = "margin" style = { { height : 1 , backgroundColor : '#eee' } } />Devuelve las inserciones de área segura del proveedor más cercano. Esto permite manipular los valores de inserción de JavaScript. Tenga en cuenta que las inserciones no se actualizan sincrónicamente, por lo que puede causar un ligero retraso, por ejemplo, al girar la pantalla.
Objeto con { 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 ) } } /> ;
} Devuelve el marco del proveedor más cercano. Esto se puede usar como una alternativa al módulo Dimensions .
Objeto con { x: number, y: number, width: number, height: number }
SafeAreaInsetsContextReaccione el contexto con el valor de las inserciones de área segura.
Se puede usar con componentes de clase:
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 Componente de orden superior que proporciona inserciones de área seguras a medida que las insets apropiadas.
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 } / > ;SafeAreaFrameContextReaccione el contexto con el valor del marco de área segura.
initialWindowMetrics ISSET y marco de la ventana en el render inicial. Esto se puede usar con la initialMetrics de SafeAreaProvider . Consulte la optimización para obtener más información.
Objeto con:
{
frame : { x : number , y : number , width : number , height : number } ,
insets : { top : number , left : number , right : number , bottom : number } ,
}Nota: Este valor puede ser nulo o desactualizado a medida que se calcula cuando se crea el módulo nativo.
Usar useSafeAreaInsets en su lugar.
Use SafeAreaInsetsContext.Consumer en su lugar.
Use SafeAreaInsetsContext en su lugar.
Use initialWindowMetrics en su lugar.
Si está haciendo una representación en el lado del servidor en la web, puede usar initialMetrics para inyectar inserciones y valor de cuadro en función del dispositivo que tiene el usuario, o simplemente aprobar valores cero. Dado que la medición de inserciones es async, romperá de lo contrario el contenido de su página.
Si puede, use SafeAreaView . Se implementa de forma nativa, por lo que al girar el dispositivo, no hay retraso desde el puente asíncrono.
Para acelerar el render inicial, puede importar initialWindowMetrics de este paquete y establecer como el accesorio initialMetrics en el proveedor como se describe en la SSR web. No puede hacer esto si su proveedor vuelve a montar, o está utilizando react-native-navigation .
import {
SafeAreaProvider ,
initialWindowMetrics ,
} from 'react-native-safe-area-context' ;
function App ( ) {
return (
< SafeAreaProvider initialMetrics = { initialWindowMetrics } >
...
</ SafeAreaProvider >
) ;
} Esta biblioteca incluye un simulacro incorporado para la broma. Utilizará las siguientes métricas de forma predeterminada:
{
frame : {
width : 320 ,
height : 640 ,
x : 0 ,
y : 0 ,
} ,
insets : {
left : 0 ,
right : 0 ,
bottom : 0 ,
top : 0 ,
} ,
}Para usarlo, agregue el siguiente código al archivo de configuración de Jest:
import mockSafeAreaContext from 'react-native-safe-area-context/jest/mock' ;
jest . mock ( 'react-native-safe-area-context' , ( ) => mockSafeAreaContext ) ; Para tener más control sobre los valores de prueba, también es posible pasar initialMetrics a SafeAreaProvider para proporcionar datos simulados para el marco y las inserciones.
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 >
) ;
} Al intentar usar este simulacro, un error encontrado con frecuencia es:
SyntaxError : Cannot use import statement outside a module .Este problema surge debido al uso de la declaración de importación. Para resolverlo, debe permitir que Babel analice el archivo.
Por defecto, Jest no analiza los archivos ubicados dentro de la carpeta Node_Modules.
Sin embargo, puede modificar este comportamiento como se describe en la documentación de Jest en la personalización transformIgnorePatterns . Si está utilizando un preajuste, como el de React-Native, debe actualizar su configuración de Jest para incluir react-native-safe-area-context como se muestra a continuación:
transformIgnorePatterns: [
'node_modules/(?!((jest-)?react-native|@react-native(-community)?|react-native-safe-area-context)/)' ,
] ;Este ajuste asegura que Babel analice correctamente los módulos, evitando el error de sintaxis mencionado anteriormente.
Ver la guía contribuyente
