react hooks

Ganchos de reação do capacitor

Um conjunto de ganchos para ajudar os desenvolvedores do Capacitor a usar APIs nativas do Capacitor.

Mantenedores

Mantenedor	GitHub	Social
Eli Lucas	elylucas	@elilucas

Estes documentos são para plug-ins do Capacitor 3. Para documentos direcionados a plug-ins v2, consulte o branch capv2.

Começando

Para começar a usar Capacitor Hooks em seu aplicativo, instale o pacote React Hook junto com o plugin Capacitor que deseja usar. Aqui está um exemplo de uso do plugin Storage junto com seu gancho React:

 # Install the Capacitor Plugin
npm install @capacitor/storage 
# And then the React hook package:
npm install @capacitor-community/storage-react

Importe os ganchos:

 import { useStorage } from '@capacitor-community/storage-react'

Em seguida, use os ganchos no seu aplicativo:

 const [ value , setValue ] = useStorage ( 'mykey' ) ; 

Detecção de recursos

Embora o Capacitor permita gravar em uma API em várias plataformas, nem todos os recursos são suportados em todas as plataformas. É recomendável verificar se o recurso que você pretende usar está disponível antes de usá-lo para evitar erros de tempo de execução.

Cada um dos caminhos do plug-in de gancho exporta um objeto availableFeatures , que contém uma lista de recursos para esse plug-in. Se o recurso for compatível com a plataforma atual em que o aplicativo está sendo executado, esse recurso será verdadeiro:

 const { useStorageItem , availableFeatures } = `@capacitor-community/storage-react` ;
const [ value , setValue ] = useStorage ( 'mykey' ) ;
...
if ( availableFeatures . useStorage ) {
  // Storage is available, feel free to use it!
  setValue ( 'cake' ) ;
}

Atualizando dos Ganchos React do Capacitor 2

No Capacitor 3, todos os plugins foram separados em seus próprios pacotes. Da mesma forma, os novos plug-ins de ganchos do React também foram colocados em seu próprio pacote, então você precisará instalar o gancho para cada plug-in que usar.

Quaisquer APIs obsoletas do Capacitor 2 a 3 também foram removidas e atualizadas, portanto, pode ser necessário fazer algumas modificações para levar em conta as alterações da API. Consulte a API do plug-in do Capacitor para saber mais.

Uso de gancho

@capacitor/app Ganchos

Instalação:

npm install @capacitor-community/app-react

Uso:

 import { useAppState , useAppUrlOpen , useLaunchUrl , availableFeatures } from '@capacitor-community/app-react' ;

useAppState fornece acesso às informações de status do aplicativo, como se o aplicativo está ativo ou inativo. Este valor será atualizado dinamicamente.

 const { state } = useAppState ( ) ; 

useLaunchUrl

useLaunchUrl fornece o URL com o qual o aplicativo foi iniciado inicialmente. Se desejar rastrear futuros eventos de URL de entrada, use useAppUrlOpen abaixo.

 const { launchUrl } = useLaunchUrl ( ) ; 

useAppUrlOpen

useAppUrlOpen fornece o URL mais recente usado para ativar o aplicativo. Por exemplo, se o usuário seguiu um link em outro aplicativo que abriu seu aplicativo.

 const { appUrlOpen } = useAppUrlOpen ( ) ;

Consulte a documentação do plug-in do App Capacitor para obter mais informações sobre a API do plug-in.

@capcitor/navegador Ganchos

Instalação:

npm install @capacitor-community/browser-react

Uso:

 import { useClose , useOpen , availableFeatures } from '@capacitor-community/browser-react' ;

useOpen , useClose fornece uma maneira de iniciar e fechar um navegador no aplicativo para conteúdo externo:

 // Open url in browser
const { open } = useOpen ( ) ;

open ( { url : 'http://ionicframework.com' } ) ;

// Close url in browser
const { close } = useClose ( ) ;
useClose ( ) ;

Consulte a documentação do plug-in do capacitor do navegador para obter mais informações sobre a API do plug-in.

@capacitor/câmera Ganchos

Instalação:

npm install @capacitor-community/camera-react

Uso:

 import { useCamera , availableFeatures } from '@capacitor-community/camera-react' ;

useCamera fornece uma maneira de tirar uma foto:

 const { photo , getPhoto } = useCamera ( ) ;
const triggerCamera = useCallback ( async ( ) => {
  getPhoto ( {
      quality : 100 ,
      allowEditing : false ,
      resultType : CameraResultType . DataUrl
    } )
} , [ getPhoto ] ) ;

< div > { photo && < img alt = "" src = { photo . dataUrl } / > } < / div >

Consulte a documentação do plug-in Camera Capacitor para obter mais informações sobre a API do plug-in.

Ganchos para prancheta

Instalação:

npm install @capacitor-community/clipboard-react

Uso:

 import { useClipboard , availableFeatures } from '@capacitor-community/clipboard-react' ;

useClipboard lê e grava dados da área de transferência:

 const { value , getValue , setValue } = useClipboard ( ) ;

const paste = useCallback ( async ( ) => {
  await setValue ( 'http://ionicframework.com/);
}, [setValue]);

const copy = useCallback(async () => {
  getValue(); 
}, [getValue])

Consulte a documentação do Clipboard Capacitor Plugin para obter mais informações sobre a API do plugin.

Ganchos de dispositivos

Instalação:

npm install @capacitor-community/device-react

Uso:

 import { useGetInfo , useGetLanguageCode , availableFeatures } from '@capacitor-community/device-react' ;

useGetInfo , useGetLanguageCode dá acesso às informações do dispositivo e às configurações de idioma do dispositivo:

 const { info } = useGetInfo ( ) ;
const { languageCode } = useGetLanguageCode ( ) ;

Consulte a documentação do plug-in do Device Capacitor para obter mais informações sobre a API do plug-in.

Ganchos do sistema de arquivos

Instalação:

npm install @capacitor-community/filesystem-react

Uso:

 import { useFilesystem , base64FromPath , availableFeatures } from '@capacitor-community/filesystem-react' ;

useFilesystem retorna métodos comuns para obter acesso às APIs do sistema de arquivos.

 const { readFile } = useFilesystem ( ) ;

const file = await readFile ( {
  path : filepath ,
  directory : FilesystemDirectory . Data
} ) ;

base64FromPath é um método auxiliar que pegará um caminho para um arquivo e retornará a representação codificada em base64 desse arquivo.

Consulte a documentação do plug-in do Filesystem Capacitor para obter mais informações sobre a API do plug-in.

 const base64String = await base64FromPath ( path ) ; 

Ganchos de geolocalização

Instalação:

npm install @capacitor-community/geolocation-react

Uso:

 import { useCurrentPosition , useWatchPosition , availableFeatures } from '@capacitor-community/geolocation-react' ;

useCurrentPosition retorna uma única posição de geolocalização usando a API de geolocalização no Capacitor. A posição pode ser atualizada manualmente chamando getPosition :

 const { currentPosition , getPosition } = useCurrentPosition ( ) ;

const handleRefreshPosition = ( ) => {
  getPosition ( ) ;
}

useWatchPosition rastreia uma posição de geolocalização usando watchPosition na API de geolocalização no Capacitor. A localização começará a ser atualizada automaticamente e você poderá usar os métodos clearWatch e startWatch para parar e reiniciar manualmente o relógio.

 const { currentPosition , startWatch , clearWatch } = useWatchPosition ( ) ;

Consulte a documentação do plug-in do capacitor de geolocalização para obter mais informações sobre a API do plug-in.

Ganchos de teclado

Instalação:

npm install @capacitor-community/keyboard-react

Uso:

 import { useKeyboardState } from '@capacitor-community/keyboard' ;

useKeyboard retorna se o teclado na tela é mostrado ou não, bem como uma aproximação da altura do teclado em pixels.

 const { isOpen , keyboardHeight } = useKeyboard ( ) ;
// Use keyboardHeight to translate an input that would otherwise be hidden by the keyboard

Consulte a documentação do plug-in do capacitor de teclado para obter mais informações sobre a API do plug-in.

Ganchos de rede

Instalação:

npm install @capacitor-community/network-react

Uso:

 import { useStatus , availableFeatures } from '@capacitor-community/network-react' ;

useStatus monitora o status e as informações da rede:

 const { networkStatus } = useStatus ( ) ;

Consulte a documentação do Network Capacitor Plugin para obter mais informações sobre a API do plugin.

Ganchos do leitor de tela

Instalação:

npm install @capacitor-community/screen-reader-react

Uso:

 import { useIsScreenReaderEnabled , useSpeak , availableFeatures } from '@capacitor-community/screen-reader-react' ;

useIsScreenReaderEnabled fornece acesso para detectar e responder a um dispositivo de leitura de tela ou configuração de sistema operacional sendo habilitado:

 const { isScreenReaderEnabled } = useIsScreenReaderEnabled ( ) ;

useSpeak ativa um mecanismo de conversão de texto em fala (se disponível) para ler texto falado.

 const { speak } = useSpeak ( ) ;
speak ( { value : textToSpeak } )

Consulte a documentação do plug-in ScreenReader Capacitor para obter mais informações sobre a API do plug-in.

Ganchos de armazenamento

Instalação:

npm install @capacitor-community/storage-react

Uso:

 import { useStorage , useStorageItem , availableFeatures } from '@capacitor-community/storage-react' ;

useStorage fornece acesso ao mecanismo de armazenamento do Capacitor. Há também um auxiliar chamado useStorageItem que facilita o gerenciamento de um único item se você não precisar acessar a API de armazenamento completa (veja abaixo)

 const { get , set , remove , getKeys , clear } = useStorage ( ) ;
useEffect ( ( ) => {
  async function example ( ) {
    const value = await get ( 'name' ) ;
    await set ( 'name' , 'Max' ) ;
    await remove ( 'name' ) ;
    const allKeys = await getKeys ( ) ;
    await clear ( ) ;
  }
} , [ get , set , remove , keys , clear ] ) ; 

useStorageItem

useStorageItem rastreia um único item e fornece uma ótima maneira de ler e escrever esse item:

 const [ name , setName ] = useStorageItem ( 'name' , 'Max' ) ;

// Example:
const updateName = useCallback ( ( n ) => {
  setName ( n ) ;
} , [ setName ] ) ;

useStorageItem usará o valor inicial já armazenado ou aquele fornecido se não houver valor existente.

Consulte a documentação do plug-in do Storage Capacitor para obter mais informações sobre a API do plug-in.

Outros ganchos

Este é um projeto em evolução e nem todos os plug-ins do Capacitor são suportados ainda. Se você precisar de algum, fique à vontade para abrir um problema ou, melhor ainda, enviar um PR!