react hooks

Реагирующие крючки для конденсаторов

Набор хуков, которые помогут разработчикам Capacitor использовать собственные API-интерфейсы Capacitor.

Мейнтейнеры

Сопровождающий	GitHub	Социальный
Эли Лукас	элилукас	@elylucas

Эти документы предназначены для плагинов Capacitor 3. Документацию, посвященную плагинам версии 2, см. в ветке capv2.

Начиная

Чтобы начать использовать Capacitor Hooks в своем приложении, вы устанавливаете пакет React Hook вместе с плагином Capacitor, который хотите использовать. Вот пример использования плагина Storage вместе с его хуком React:

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

Импортируйте крючки:

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

Затем используйте хуки в своем приложении:

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

Обнаружение функций

Хотя Capacitor позволяет писать в один API на нескольких платформах, не все функции поддерживаются на всех платформах. Рекомендуется проверить, доступна ли функция, которую вы собираетесь использовать, перед ее использованием, чтобы избежать ошибок во время выполнения.

Каждый из путей плагина-перехватчика экспортирует объект availableFeatures , который содержит список функций для этого плагина. Если эта функция поддерживается для текущей платформы, на которой работает приложение, эта функция будет верной:

 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' ) ;
}

Обновление с Capacitor 2 React Hooks

В Capacitor 3 все плагины были разделены на отдельные пакеты. Аналогично, новые плагины перехватчиков React также были помещены в отдельный пакет, поэтому вам нужно будет установить перехватчик для каждого используемого вами плагина.

Все устаревшие API от Capacitor 2 до 3 также были удалены и обновлены, поэтому вам, возможно, придется внести некоторые изменения, чтобы учесть изменения API. Дополнительную информацию см. в API плагина конденсатора.

Использование крючка

@capacitor/app Хуки

Установка:

npm install @capacitor-community/app-react

Использование:

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

useAppState предоставляет доступ к информации о состоянии приложения, например, активно ли приложение или неактивно. Это значение будет обновляться динамически.

 const { state } = useAppState ( ) ; 

useLaunchUrl

useLaunchUrl предоставляет URL-адрес, с которого приложение было первоначально запущено. Если вы хотите отслеживать будущие события входящего URL-адреса, используйте вместо этого useAppUrlOpen ниже.

 const { launchUrl } = useLaunchUrl ( ) ; 

useAppUrlOpen

useAppUrlOpen предоставляет самый последний URL-адрес, использованный для активации приложения. Например, если пользователь перешел по ссылке в другом приложении, которая открыла ваше приложение.

 const { appUrlOpen } = useAppUrlOpen ( ) ;

Дополнительную информацию об API плагина см. в документации по плагину App Capacitor.

@capcitor/браузерные хуки

Установка:

npm install @capacitor-community/browser-react

Использование:

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

useOpen , useClose предоставляет возможность запускать и закрывать браузер в приложении для внешнего контента:

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

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

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

Дополнительную информацию об API плагина см. в документации по плагину конденсатора браузера.

@capacitor/крючки для камеры

Установка:

npm install @capacitor-community/camera-react

Использование:

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

useCamera предоставляет возможность сделать фотографию:

 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 >

Дополнительную информацию об API плагина см. в документации по плагину Camera Capacitor.

Крючки для буфера обмена

Установка:

npm install @capacitor-community/clipboard-react

Использование:

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

useClipboard считывает и записывает данные буфера обмена:

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

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

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

Дополнительную информацию об API плагина см. в документации по плагину Clipboard Capacitor.

Перехватчики устройств

Установка:

npm install @capacitor-community/device-react

Использование:

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

useGetInfo , useGetLanguageCode предоставляет доступ к информации об устройстве и настройкам языка устройства:

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

Дополнительную информацию об API плагина см. в документации по плагину Device Capacitor.

Хуки файловой системы

Установка:

npm install @capacitor-community/filesystem-react

Использование:

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

useFilesystem возвращает распространенные методы для получения доступа к API файловой системы.

 const { readFile } = useFilesystem ( ) ;

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

base64FromPath — это вспомогательный метод, который принимает путь к файлу и возвращает представление этого файла в кодировке Base64.

Дополнительную информацию об API плагина см. в документации по плагину Filesystem Capacitor.

 const base64String = await base64FromPath ( path ) ; 

Геолокационные крючки

Установка:

npm install @capacitor-community/geolocation-react

Использование:

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

useCurrentPosition возвращает одну позицию геолокации, используя API геолокации в Capacitor. Позицию можно обновить вручную, вызвав getPosition :

 const { currentPosition , getPosition } = useCurrentPosition ( ) ;

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

useWatchPosition отслеживает положение геолокации с помощью watchPosition в API геолокации в Capacitor. Местоположение автоматически начнет обновляться, и вы можете использовать методы clearWatch и startWatch чтобы вручную остановить и перезапустить часы.

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

Дополнительную информацию об API плагина см. в документации по плагину Geolocation Capacitor.

Крючки для клавиатуры

Установка:

npm install @capacitor-community/keyboard-react

Использование:

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

useKeyboard возвращает информацию о том, отображается ли экранная клавиатура, а также приблизительную высоту клавиатуры в пикселях.

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

Дополнительную информацию об API плагина см. в документации по плагину Keyboard Capacitor.

Сетевые крючки

Установка:

npm install @capacitor-community/network-react

Использование:

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

useStatus отслеживает состояние сети и информацию:

 const { networkStatus } = useStatus ( ) ;

Дополнительную информацию об API плагина см. в документации по плагину Network Capacitor.

Хуки для чтения экрана

Установка:

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

Использование:

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

useIsScreenReaderEnabled предоставляет доступ к обнаружению и реагированию на включение устройства чтения экрана или настроек ОС:

 const { isScreenReaderEnabled } = useIsScreenReaderEnabled ( ) ;

useSpeak активирует механизм преобразования текста в речь (если доступен) для чтения устного текста.

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

Дополнительную информацию об API плагина см. в документации по плагину ScreenReader Capacitor.

Крючки для хранения

Установка:

npm install @capacitor-community/storage-react

Использование:

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

useStorage предоставляет доступ к механизму хранения данных Capacitor. Существует также помощник под названием useStorageItem , который упрощает управление одним элементом, если вам не нужен доступ к полному API хранилища (см. ниже).

 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 отслеживает один элемент и предоставляет удобный способ чтения и записи этого элемента:

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

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

useStorageItem будет использовать начальное значение, уже находящееся в хранилище, или предоставленное, если существующего значения нет.

Дополнительную информацию об API плагина см. в документации по плагину Storage Capacitor.

Другие крючки

Это развивающийся проект, и пока не все плагины конденсаторов поддерживаются. Если он вам нужен, смело открывайте для него выпуск или, что еще лучше, отправьте PR!