Un ensemble de hooks pour aider les développeurs de Capacitor à utiliser les API Capacitor natives.
Mainteneur | GitHub | Sociale |
---|---|---|
Ely Lucas | élylucas | @elylucas |
Ces documents sont destinés aux plugins Capacitor 3. Pour les documents qui ciblent les plugins v2, consultez la branche capv2.
Pour commencer à utiliser Capacitor Hooks dans votre application, vous installez le package React Hook avec le plugin Capacitor que vous souhaitez utiliser. Voici un exemple d'utilisation du plugin Storage avec son hook React :
# Install the Capacitor Plugin
npm install @capacitor/storage
# And then the React hook package:
npm install @capacitor-community/storage-react
Importez les hooks :
import { useStorage } from '@capacitor-community/storage-react'
Utilisez ensuite les hooks de votre application :
const [ value , setValue ] = useStorage ( 'mykey' ) ;
Bien que Capacitor vous permette d'écrire sur une API sur plusieurs plates-formes, toutes les fonctionnalités ne sont pas prises en charge sur toutes les plates-formes. Il est conseillé de vérifier si la fonctionnalité que vous avez l'intention d'utiliser est disponible avant de l'utiliser pour éviter toute erreur d'exécution.
Chacun des chemins du plugin hook exporte un objet availableFeatures
, qui contient une liste de fonctionnalités pour ce plugin. Si la fonctionnalité est prise en charge pour la plate-forme actuelle sur laquelle l'application est exécutée, cette fonctionnalité sera vraie :
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' ) ;
}
Dans Capacitor 3, tous les plugins étaient séparés dans leurs propres packages. De même, les nouveaux plugins React hooks ont également été placés dans leur propre package, vous devrez donc installer le hook pour chaque plugin que vous utilisez.
Toutes les API obsolètes des condensateurs 2 à 3 ont également été supprimées et mises à jour, vous devrez donc peut-être apporter quelques modifications pour tenir compte des modifications de l'API. Consultez l’API Capacitor Plugin pour en savoir plus.
Installation:
npm install @capacitor-community/app-react
Usage:
import { useAppState , useAppUrlOpen , useLaunchUrl , availableFeatures } from '@capacitor-community/app-react' ;
useAppState
permet d'accéder aux informations sur l'état de l'application, par exemple si l'application est active ou inactive. Cette valeur sera mise à jour dynamiquement.
const { state } = useAppState ( ) ;
useLaunchUrl
useLaunchUrl
fournit l'URL avec laquelle l'application a été initialement lancée. Si vous souhaitez suivre les futurs événements d’URL entrants, utilisez plutôt useAppUrlOpen
ci-dessous.
const { launchUrl } = useLaunchUrl ( ) ;
useAppUrlOpen
useAppUrlOpen
fournit l'URL la plus récente utilisée pour activer l'application. Par exemple, si l'utilisateur a suivi un lien dans une autre application qui a ouvert votre application.
const { appUrlOpen } = useAppUrlOpen ( ) ;
Consultez la documentation du plugin App Capacitor pour plus d’informations sur l’API du plugin.
Installation:
npm install @capacitor-community/browser-react
Usage:
import { useClose , useOpen , availableFeatures } from '@capacitor-community/browser-react' ;
useOpen
, useClose
fournit un moyen de lancer et de fermer un navigateur intégré à l'application pour le contenu externe :
// Open url in browser
const { open } = useOpen ( ) ;
open ( { url : 'http://ionicframework.com' } ) ;
// Close url in browser
const { close } = useClose ( ) ;
useClose ( ) ;
Consultez la documentation du plugin Browser Capacitor pour plus d’informations sur l’API du plugin.
Installation:
npm install @capacitor-community/camera-react
Usage:
import { useCamera , availableFeatures } from '@capacitor-community/camera-react' ;
useCamera
fournit un moyen de prendre une photo :
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 >
Consultez la documentation du plugin Camera Capacitor pour plus d’informations sur l’API du plugin.
Installation:
npm install @capacitor-community/clipboard-react
Usage:
import { useClipboard , availableFeatures } from '@capacitor-community/clipboard-react' ;
useClipboard
lit et écrit les données du presse-papier :
const { value , getValue , setValue } = useClipboard ( ) ;
const paste = useCallback ( async ( ) => {
await setValue ( 'http://ionicframework.com/);
}, [setValue]);
const copy = useCallback(async () => {
getValue();
}, [getValue])
Consultez la documentation du plugin Clipboard Capacitor pour plus d’informations sur l’API du plugin.
Installation:
npm install @capacitor-community/device-react
Usage:
import { useGetInfo , useGetLanguageCode , availableFeatures } from '@capacitor-community/device-react' ;
useGetInfo
, useGetLanguageCode
donne accès aux informations sur l'appareil et aux paramètres de langue de l'appareil :
const { info } = useGetInfo ( ) ;
const { languageCode } = useGetLanguageCode ( ) ;
Consultez la documentation du plug-in Device Capacitor pour plus d’informations sur l’API du plug-in.
Installation:
npm install @capacitor-community/filesystem-react
Usage:
import { useFilesystem , base64FromPath , availableFeatures } from '@capacitor-community/filesystem-react' ;
useFilesystem
renvoie les méthodes courantes pour accéder aux API du système de fichiers.
const { readFile } = useFilesystem ( ) ;
const file = await readFile ( {
path : filepath ,
directory : FilesystemDirectory . Data
} ) ;
base64FromPath
est une méthode d'assistance qui prendra un chemin d'accès à un fichier et renverra la représentation codée en base64 de ce fichier.
Consultez la documentation du plug-in Filesystem Capacitor pour plus d’informations sur l’API du plug-in.
const base64String = await base64FromPath ( path ) ;
Installation:
npm install @capacitor-community/geolocation-react
Usage:
import { useCurrentPosition , useWatchPosition , availableFeatures } from '@capacitor-community/geolocation-react' ;
useCurrentPosition
renvoie une position de géolocalisation unique à l'aide de l'API de géolocalisation dans Capacitor. La position peut être mise à jour manuellement en appelant getPosition
:
const { currentPosition , getPosition } = useCurrentPosition ( ) ;
const handleRefreshPosition = ( ) => {
getPosition ( ) ;
}
useWatchPosition
suit une position de géolocalisation à l'aide de watchPosition
dans l'API de géolocalisation de Capacitor. L'emplacement commencera automatiquement à se mettre à jour et vous pourrez utiliser les méthodes clearWatch
et startWatch
pour arrêter et redémarrer manuellement la montre.
const { currentPosition , startWatch , clearWatch } = useWatchPosition ( ) ;
Consultez la documentation du plug-in Geolocation Capacitor pour plus d’informations sur l’API du plug-in.
Installation:
npm install @capacitor-community/keyboard-react
Usage:
import { useKeyboardState } from '@capacitor-community/keyboard' ;
useKeyboard
renvoie si le clavier à l'écran est affiché ou non ainsi qu'une approximation de la hauteur du clavier en pixels.
const { isOpen , keyboardHeight } = useKeyboard ( ) ;
// Use keyboardHeight to translate an input that would otherwise be hidden by the keyboard
Consultez la documentation du plugin Keyboard Capacitor pour plus d’informations sur l’API du plugin.
Installation:
npm install @capacitor-community/network-react
Usage:
import { useStatus , availableFeatures } from '@capacitor-community/network-react' ;
useStatus
surveille l'état et les informations du réseau :
const { networkStatus } = useStatus ( ) ;
Consultez la documentation du plugin Network Capacitor pour plus d’informations sur l’API du plugin.
Installation:
npm install @capacitor-community/screen-reader-react
Usage:
import { useIsScreenReaderEnabled , useSpeak , availableFeatures } from '@capacitor-community/screen-reader-react' ;
useIsScreenReaderEnabled
permet de détecter et de répondre à l'activation d'un périphérique de lecture d'écran ou d'un paramètre du système d'exploitation :
const { isScreenReaderEnabled } = useIsScreenReaderEnabled ( ) ;
useSpeak
active un moteur de synthèse vocale (si disponible) pour lire le texte parlé.
const { speak } = useSpeak ( ) ;
speak ( { value : textToSpeak } )
Consultez la documentation du plug-in ScreenReader Capacitor pour plus d’informations sur l’API du plug-in.
Installation:
npm install @capacitor-community/storage-react
Usage:
import { useStorage , useStorageItem , availableFeatures } from '@capacitor-community/storage-react' ;
useStorage
donne accès au moteur de stockage de Capacitor. Il existe également un assistant appelé useStorageItem
qui facilite la gestion d'un seul élément si vous n'avez pas besoin d'accéder à l'API de stockage complète (voir ci-dessous).
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
suit un seul élément et fournit un moyen agréable de lire et d'écrire cet élément :
const [ name , setName ] = useStorageItem ( 'name' , 'Max' ) ;
// Example:
const updateName = useCallback ( ( n ) => {
setName ( n ) ;
} , [ setName ] ) ;
useStorageItem
utilisera la valeur initiale déjà stockée, ou celle fournie s'il n'y a pas de valeur existante.
Consultez la documentation du plugin Storage Capacitor pour plus d’informations sur l’API du plugin.
Il s'agit d'un projet en évolution et tous les plugins Capacitor ne sont pas encore pris en charge. S'il y en a un dont vous avez besoin, n'hésitez pas à ouvrir un numéro, ou mieux encore, soumettez un PR !