react hooks

خطاف رد فعل المكثف

مجموعة من الخطافات لمساعدة مطوري Capacitor على استخدام واجهات برمجة تطبيقات Capacitor الأصلية.

المشرفون

معيل	جيثب	اجتماعي
ايلي لوكاس	elylucas	@elylucas

هذه المستندات مخصصة لمكونات Capacitor 3 الإضافية. بالنسبة للمستندات التي تستهدف مكونات v2 الإضافية، راجع فرع 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 يسمح لك بالكتابة إلى واجهة برمجة تطبيقات واحدة عبر العديد من الأنظمة الأساسية، إلا أنه لا يتم دعم جميع الميزات على جميع الأنظمة الأساسية. يُنصح بالتحقق مما إذا كانت الميزة التي تنوي استخدامها متاحة قبل استخدامها لتجنب أي أخطاء في وقت التشغيل.

يقوم كل مسار من مسارات المكون الإضافي للربط بتصدير كائن 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' ) ;
}

الترقية من مكثف 2 خطاف رد الفعل

في Capacitor 3، تم فصل جميع المكونات الإضافية في حزم خاصة بها. وبالمثل، تم أيضًا وضع المكونات الإضافية لخطافات React الإضافية في حزمتها الخاصة، لذلك ستحتاج إلى تثبيت الخطاف لكل مكون إضافي تستخدمه.

تمت أيضًا إزالة وتحديث أي واجهة برمجة تطبيقات مهملة من Capacitor 2 إلى 3، لذلك قد تحتاج إلى إجراء بعض التعديلات لمراعاة تغييرات واجهة برمجة التطبيقات. راجع واجهة برمجة تطبيقات Capacitor Plugin لمعرفة المزيد.

استخدام هوك

@ مكثف/خطاف التطبيق

تثبيت:

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 ( ) ;

راجع مستندات App Capacitor Plugin للحصول على مزيد من المعلومات حول واجهة برمجة تطبيقات البرنامج المساعد.

@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 ( ) ;

راجع مستندات Browser Capacitor Plugin للحصول على مزيد من المعلومات حول واجهة برمجة تطبيقات البرنامج المساعد.

@ خطاف مكثف/كاميرا

تثبيت:

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 >

راجع مستندات Camera Capacitor Plugin للحصول على مزيد من المعلومات حول واجهة برمجة تطبيقات البرنامج الإضافي.

خطاف الحافظة

تثبيت:

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])

راجع مستندات Clipboard Capacitor Plugin للحصول على مزيد من المعلومات حول واجهة برمجة تطبيقات البرنامج المساعد.

خطاف الجهاز

تثبيت:

npm install @capacitor-community/device-react

الاستخدام:

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

useGetInfo ، يتيح useGetLanguageCode الوصول إلى معلومات الجهاز وإعدادات لغة الجهاز:

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

راجع مستندات Device Capacitor Plugin للحصول على مزيد من المعلومات حول واجهة برمجة تطبيقات البرنامج الإضافي.

خطاف نظام الملفات

تثبيت:

npm install @capacitor-community/filesystem-react

الاستخدام:

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

يقوم useFilesystem بإرجاع الطرق الشائعة للوصول إلى واجهة برمجة تطبيقات نظام الملفات.

 const { readFile } = useFilesystem ( ) ;

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

base64FromPath هي طريقة مساعدة ستأخذ مسارًا إلى ملف وتعيد تمثيل base64 المشفر لذلك الملف.

راجع مستندات Filesystem Capacitor Plugin للحصول على مزيد من المعلومات حول واجهة برمجة تطبيقات البرنامج المساعد.

 const base64String = await base64FromPath ( path ) ; 

خطاف تحديد الموقع الجغرافي

تثبيت:

npm install @capacitor-community/geolocation-react

الاستخدام:

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

يُرجع useCurrentPosition موقعًا جغرافيًا واحدًا باستخدام واجهة برمجة تطبيقات تحديد الموقع الجغرافي في Capacitor. يمكن تحديث الموضع يدويًا عن طريق استدعاء getPosition :

 const { currentPosition , getPosition } = useCurrentPosition ( ) ;

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

يتتبع useWatchPosition موقع تحديد الموقع الجغرافي باستخدام watchPosition في واجهة برمجة تطبيقات تحديد الموقع الجغرافي في Capacitor. سيبدأ الموقع في التحديث تلقائيًا، ويمكنك استخدام طريقتي clearWatch و startWatch لإيقاف الساعة وإعادة تشغيلها يدويًا.

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

راجع مستندات Geolocation Capacitor Plugin للحصول على مزيد من المعلومات حول واجهة برمجة تطبيقات البرنامج المساعد.

خطاف لوحة المفاتيح

تثبيت:

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

راجع مستندات Keyboard Capacitor Plugin للحصول على مزيد من المعلومات حول واجهة برمجة تطبيقات البرنامج المساعد.

خطاف الشبكة

تثبيت:

npm install @capacitor-community/network-react

الاستخدام:

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

يراقب useStatus حالة الشبكة ومعلوماتها:

 const { networkStatus } = useStatus ( ) ;

راجع مستندات Network Capacitor Plugin للحصول على مزيد من المعلومات حول واجهة برمجة تطبيقات البرنامج الإضافي.

خطافات قارئ الشاشة

تثبيت:

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

راجع مستندات ScreenReader Capacitor Plugin لمزيد من المعلومات حول واجهة برمجة تطبيقات البرنامج المساعد.

خطافات التخزين

تثبيت:

npm install @capacitor-community/storage-react

الاستخدام:

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

يوفر useStorage إمكانية الوصول إلى محرك تخزين Capacitor. يوجد أيضًا مساعد يسمى useStorageItem مما يجعل إدارة عنصر واحد أمرًا سهلاً إذا لم تكن بحاجة إلى الوصول إلى واجهة برمجة تطبيقات التخزين الكاملة (انظر أدناه)

 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 القيمة الأولية الموجودة بالفعل في المخزن، أو القيمة المقدمة إذا لم تكن هناك قيمة موجودة.

راجع مستندات Storage Capacitor Plugin للحصول على مزيد من المعلومات حول واجهة برمجة تطبيقات البرنامج المساعد.

خطافات أخرى

هذا مشروع متطور ولم يتم دعم جميع المكونات الإضافية للمكثف حتى الآن. إذا كان هناك ما تحتاج إليه، فلا تتردد في فتح مشكلة له، أو الأفضل من ذلك، إرسال PR!