react native safe area context
Release 5.0.0
Uma maneira flexível de lidar com uma área segura, também funciona no Android e na Web!
npm install react-native-safe-area-contextyarn add react-native-safe-area-contextVocê precisa vincular as partes nativas da biblioteca para as plataformas que está usando.
plataforma iOS:
$ npx pod-install
| versão | Versão reagt-nativa |
|---|---|
| 5 | 0,74 |
| 4 | 0,64 |
Atualmente, esta biblioteca possui suporte experimental para a nova arquitetura de reação nativa. Observe que haverá mudanças de quebra e apenas a versão mais recente do React-native será suportada.
Esta biblioteca possui 2 conceitos importantes, se você estiver familiarizado com o contexto do React, isso é muito semelhante.
O componente SafeareAprovider é uma View de onde as inserções fornecidas pelos consumidores são relativas. Isso significa que, se essa exibição se sobrepor a algum elemento do sistema (barra de status, entalhes etc.), esses valores serão fornecidos aos consumidores descendentes. Geralmente você terá um provedor no topo do seu aplicativo.
Os consumidores são componentes e ganchos que permitem o uso de valores de inserção fornecidos pelo provedor pai mais próximo. Os valores são sempre relativos a um provedor e não a esses componentes.
SafeareAview é a maneira preferida de consumir inserções. Esta é uma View regular com inserções aplicadas como preenchimento ou margem extra. Oferece um melhor desempenho aplicando inserções nativamente e evita os filmes que podem acontecer com os outros consumidores baseados em JS.
usafeareainsets oferece mais flexibilidade, mas pode causar um layout pisca em certos casos. Use isso se precisar de mais controle sobre como as inserções são aplicadas.
Você deve adicionar SafeAreaProvider no componente raiz do seu aplicativo. Pode ser necessário adicioná-lo em outros lugares, como a raiz de modais e rotas ao usar react-native-screens .
Observe que os provedores não devem estar dentro de uma View animada com Animated ou dentro de um ScrollView , pois pode causar atualizações muito frequentes.
import { SafeAreaProvider } from 'react-native-safe-area-context' ;
function App ( ) {
return < SafeAreaProvider > ... </ SafeAreaProvider > ;
} Aceita todos os acessórios de visualização. Tem um estilo padrão de {flex: 1} .
initialMetrics Opcional, padrão para null .
Pode ser usado para fornecer o valor inicial para quadros e inserções, isso permite renderizar imediatamente. Consulte a otimização para obter mais informações sobre como usar este suporte.
SafeAreaView é um componente View regular com as inserções de área segura aplicadas como preenchimento ou margem.
Os estilos de preenchimento ou margem são adicionados às inserções, por exemplo, style={{paddingTop: 10}} em um SafeAreaView que possui inserções de 20 resultará em um preenchimento 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 >
) ;
} Aceita todos os acessórios de visualização.
edges Opcional, matriz de top , right , bottom e left . Padrões para todos.
Define as bordas para aplicar a área segura.
Por exemplo, se você não deseja que as inserções se apliquem à borda superior porque a visualização não toca na parte superior da tela que você pode usar:
< SafeAreaView edges = { [ 'right' , 'bottom' , 'left' ] } /> Opcionalmente, ele pode ser definido como um objeto { top?: EdgeMode, right?: EdgeMode, bottom?: EdgeMode, left?: EdgeMode } onde EdgeMode = 'off' | 'additive' | 'maximum' . O aditivo é um modo padrão e é o mesmo que passa e borda na matriz: finalPadding = safeArea + padding . O modo máximo usará uma área segura inserida ou preenchimento/margem (depende do mode ) se a área segura for menor: finalPadding = max(safeArea, padding) . Por exemplo, se você deseja um elemento de interface do usuário flutuante que deve estar na borda da área segura inferior em dispositivos com área segura ou 24px da parte inferior da tela em dispositivos sem área segura ou se a área segura for menor que 24px:
< SafeAreaView style = { { paddingBottom : 24 } } edges = { { bottom : 'maximum' } } /> mode Opcional, padding (padrão) ou margin .
Aplique a área segura no preenchimento ou na margem.
Isso pode ser útil, por exemplo, para criar um componente separador de área segura:
< SafeAreaView mode = "margin" style = { { height : 1 , backgroundColor : '#eee' } } />Retorna a área segura inserções do fornecedor mais próximo. Isso permite manipular os valores de inserção do JavaScript. Observe que as inserções não são atualizadas de maneira síncrona, para que possa causar um pequeno atraso, por exemplo, ao girar a tela.
Objeto com { 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 ) } } /> ;
} Retorna o quadro do provedor mais próximo. Isso pode ser usado como uma alternativa ao módulo Dimensions .
Objeto com { x: number, y: number, width: number, height: number }
SafeAreaInsetsContextReaja o contexto com o valor da área segura inserções.
Pode ser usado com componentes de 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 Componente de ordem superior que fornece inserções de área segura como suporte 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 } / > ;SafeAreaFrameContextReaja o contexto com o valor da estrutura da área segura.
initialWindowMetrics Inserções e quadros da janela na renderização inicial. Isso pode ser usado com o initialMetrics do SafeAreaProvider . Consulte Otimização para obter mais informações.
Objeto com:
{
frame : { x : number , y : number , width : number , height : number } ,
insets : { top : number , left : number , right : number , bottom : number } ,
}Nota: Este valor pode ser nulo ou desatualizado, pois é calculado quando o módulo nativo é criado.
Use useSafeAreaInsets .
Use SafeAreaInsetsContext.Consumer .
Use o SafeAreaInsetsContext .
Use initialWindowMetrics .
Se você estiver fazendo a renderização do lado do servidor na web, poderá usar initialMetrics para injetar inserções e o valor de quadro com base no dispositivo que o usuário possui ou simplesmente passar valores zero. Como a medição de inserções é assíncrona, ela quebrará o conteúdo da sua página de outra forma.
Se você puder, use SafeAreaView . Ele é implementado nativamente; ao girar o dispositivo, não há atraso na ponte assíncrona.
Para acelerar a renderização inicial, você pode importar initialWindowMetrics deste pacote e definir como o suporte initialMetrics no provedor, conforme descrito no Web SSR. Você não pode fazer isso se o seu provedor remonta ou estiver usando react-native-navigation .
import {
SafeAreaProvider ,
initialWindowMetrics ,
} from 'react-native-safe-area-context' ;
function App ( ) {
return (
< SafeAreaProvider initialMetrics = { initialWindowMetrics } >
...
</ SafeAreaProvider >
) ;
} Esta biblioteca inclui um simulado embutido para a brincadeira. Ele usará as seguintes métricas por padrão:
{
frame : {
width : 320 ,
height : 640 ,
x : 0 ,
y : 0 ,
} ,
insets : {
left : 0 ,
right : 0 ,
bottom : 0 ,
top : 0 ,
} ,
}Para usá -lo, adicione o seguinte código ao arquivo de configuração do JEST:
import mockSafeAreaContext from 'react-native-safe-area-context/jest/mock' ;
jest . mock ( 'react-native-safe-area-context' , ( ) => mockSafeAreaContext ) ; Para ter mais controle sobre os valores do teste, também é possível passar initialMetrics para SafeAreaProvider para fornecer dados simulados para o quadro e as inserções.
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 >
) ;
} Ao tentar usar essa simulação, um erro frequentemente encontrado é:
SyntaxError : Cannot use import statement outside a module .Este problema surge devido ao uso da declaração de importação. Para resolvê -lo, você precisa permitir que Babel analise o arquivo.
Por padrão, o jest não analisa os arquivos localizados na pasta Node_modules.
No entanto, você pode modificar esse comportamento conforme descrito na documentação do JEST sobre a personalização transformIgnorePatterns . Se você estiver usando uma predefinição, como a do React-native, atualize sua configuração de brincadeira para incluir react-native-safe-area-context como mostrado abaixo:
transformIgnorePatterns: [
'node_modules/(?!((jest-)?react-native|@react-native(-community)?|react-native-safe-area-context)/)' ,
] ;Esse ajuste garante que Babel analise os módulos corretamente, evitando o erro de sintaxe mencionado acima.
Veja o guia contribuinte
