عرض مصدر ReactNative/asyncstorage

<noinclude>{{DISPLAYTITLE:الواجهة AsyncStorage  في React Native}}</noinclude><blockquote>'''مهملة:''' استخدم إحدى [https://reactnative.directory/?search=storage الحزم التي يوفرها المجتمع] بدلًا عنها.</blockquote><code>AsyncStorage</code> هو نظام تخزين مستمر غير مشفّر وغير متزامن، يُخزن البيانات في صورة أزواج <code>(key: value)</code>، وهو نظام موحّد لكلّ أجزاء التطبيق، ويجب استعماله بدلًا عن <code>LocalStorage</code>.

يُفضّل استخدام التجريد (abstraction) على مستوى أعلى من <code>AsyncStorage</code> بدلًا من استخدامه على <code>AsyncStorage</code> مباشرةً في حالة التخزين الثقيل للبيانات.

يدعم نظام iOS نظام التخزين <code>AsyncStorage</code> بواسطة شيفرة أصلية تُخزِّن القيم الصغيرة في قاموس متسلسل، والقيم الكبيرة في ملفّات منفصلة؛ أمّا نظام أندويد فسيتخدم إمّا <code>RocksDB</code> أو <code>SQLite</code> بناءً على ما هو متاح.

شيفرة [[JavaScript|جافاسكربت]] الخاصة بنظام التخزين <code>AsyncStorage</code> توفِّر واجهة برمجة تطبيقات (API) واضحة، وكائنات خطأ (Error Objects)، ودوال غير متعددة. كلّ دالة في واجهة برمجة التطبيقات (API) تُرجع وعدًا (Promise).

== مثال ==
مثال لاستيراد مكتبة <code>AsyncStorage</code>:

<syntaxhighlight class="react" lang="javascript">import { AsyncStorage} from 'react-native';</syntaxhighlight>
حفظ البيانات:

<syntaxhighlight class="react" lang="javascript">_storeData = async () => {
  try {
    await AsyncStorage.setItem(
      '@MySuperStore:key',
      'I like to save it.'
    );
  } catch (error) {
    // Error saving data
  }
};</syntaxhighlight>
قراءة البيانات:

<syntaxhighlight class="react" lang="javascript">_retrieveData = async () => {
  try {
    const value = await AsyncStorage.getItem('TASKS');
    if (value !== null) {
      // We have data!!
      console.log(value);
    }
  } catch (error) {
    // Error retrieving data
  }
};</syntaxhighlight>

__toc__
== التوابع ==

=== <code>‎getItem()‎</code> ===

<syntaxhighlight class="react" lang="javascript">static getItem(key: string, [callback]: ?(error: ?Error, result: ?string) => void)</syntaxhighlight>
تجلب البيانات الخاصة بمفتاح (<code>key</code>) معيّن وتستدعي ردّ نداء (callback). بعد إكتمال العملية أو حدوث خطأ أثناء التنفيذ  تُرجع كائن من النوع [https://www.google.com/url?q=https://wiki.hsoub.com/JavaScript/Promise&sa=D&ust=1611306791480000&usg=AOvVaw2elF2z1fPTgS6EQa20AEJ2 <code>promise</code>].

'''المعاملات'''

{| class="wikitable"
! الاسم
! النوع
! مطلوب
! الوصف
|-
| <code>key</code>
| سلسلة نصية (string)
| نعم
| المفتاح الخاص بالبيانات المُراد جلبها.
|-
| <code>callback</code>
| ‪?(error: ?Error, result: ?string) => void
| لا
| دالة تُستدعى عند إكتمال عملية جلب البيانات أو حدوث خطأ أثناء العملية.
|}
=== <code>‎setItem()‎</code> ===

<syntaxhighlight class="react" lang="javascript">static setItem(key: string, value: string, [callback]: ?(error: ?Error) => void)</syntaxhighlight>
تُخزِّن البيانات في صورة زوج (<code>key: value</code>)، وتستدعي دالة بعد إكتمال العملية أو حدوث خطأ أثناء التنفيذ. تُرجع كائن من النوع <code>[[JavaScript/Promise|Promise]]</code>.

'''المعاملات:'''

{| class="wikitable"
! الاسم
! النوع
! مطلوب
! الوصف
|-
| <code>key</code>
| سلسلة نصية (string)
| نعم
| المفتاح الخاص بالعنصر المُراد تخزينه.
|-
| <code>value</code>
| سلسلة نصية (string)
| نعم
| العنصر المراد تخزينه.
|-
| <code>callback</code>
| <code>?(error: ?Error) => void</code>
| لا
| دالة تُستدعى عند حدوث خطأ اثناء العملية.
|}

=== <code>‎removeItem()‎</code> ===

<syntaxhighlight class="react" lang="javascript">static removeItem(key: string, [callback]: ?(error: ?Error) => void)</syntaxhighlight>
تحذف العنصر المرتبط بالمفتاح المعين، وتستدعي دالة بعد إكتمال العملية أو حدوث خطأ أثناء التنفيذ. تُرجع كائن من النوع <code>[[JavaScript/Promise|Promise]]</code>.

'''المعاملات:'''

{| class="wikitable"
! الاسم
! النوع
! مطلوب
! الوصف
|-
|<code>key</code>
| سلسلة نصية (string)
| نعم
| المفتاح الخاص بالعنصر المُراد حذفه.
|-
|<code>callback</code>
| ‪?(error: ?Error) => void
| لا
| دالة تُستدعى عند حدوث خطأ اثناء العملية.
|}

===<code>mergeItem()‎</code>===

<syntaxhighlight class="react" lang="javascript">static mergeItem(key: string, value: string, [callback]: ?(error: ?Error) => void)</syntaxhighlight>
تُحدِّث القيمة المرتبطة معيّن. ويجب أن يكون المفتاح والقيمة الجديدة في شكل سلسلة JSON. تُرجع كائن من النوع <code>[[JavaScript/Promise|Promise]]</code>.

'''ملاحظة''': بعض عمليات التنفيذ للمنصات الأصيلة (Native implementations) لا تدعم هذه الدالة.

'''المعاملات:'''

{| class="wikitable"
! الاسم
! النوع
! مطلوب
! الوصف
|-
|<code>key</code>
| سلسلة نصية (string)
| نعم
| المفتاح المُراد تحديث قيمته.
|-
|<code>value</code>
| سلسلة نصية (string)
| نعم
| القيمة الجديدة للمفتاح.
|-
|<code>callback</code>
| ‪?(error: ?Error) => void
| لا
| دالة تُستدعى عند حدوث خطأ اثناء العملية.
|}

'''مثال:'''

<syntaxhighlight class="react" lang="javascript">let UID123_object = {
  name: 'Chris',
  age: 30,
  traits: { hair: 'brown', eyes: 'brown' }
};
// You only need to define what will be added or updated
let UID123_delta = {
  age: 31,
  traits: { eyes: 'blue', shoe_size: 10 }
};

AsyncStorage.setItem(
  'UID123',
  JSON.stringify(UID123_object),
  () => {
    AsyncStorage.mergeItem(
      'UID123',
      JSON.stringify(UID123_delta),
      () => {
        AsyncStorage.getItem('UID123', (err, result) => {
          console.log(result);
        });
      }
    );
  }
);

// Console log result:
// => {'name':'Chris','age':31,'traits':
//    {'shoe_size':10,'hair':'brown','eyes':'blue'}}</syntaxhighlight>
=== <code>‎clear()‎</code> ===

<syntaxhighlight class="react" lang="javascript">static clear([callback]: ?(error: ?Error) => void)</syntaxhighlight>
تحذف جميع البيانات المُخزنة في <code>AsyncStorage</code>، حتى تلك المرتبطة بتطبيقات أخرى. لذلك لا يُنصح باستخدامها ويجب استخدام <code>removeItem</code> أو <code>multiRemove</code> لمسح المفاتيح المرتبطة بتطبيقك فقط. تُرجع كائن من النوع <code>[[JavaScript/Promise|Promise]]</code>.

'''المعاملات:'''

{| class="wikitable"
! الاسم
! النوع
! مطلوب
! الوصف
|-
| <code>callback</code>
| <code>‪?(error: ?Error) => void</code>
| لا
| دالة تُستدعى عند حدوث خطأ اثناء العملية.
|}
=== <code>‎getAllKeys()‎</code> ===

<syntaxhighlight class="react" lang="javascript">static getAllKeys([callback]: ?(error: ?Error, keys: ?Array<string>) => void)</syntaxhighlight>
تتحصل على جميع المفاتيح المرتبطة بالتطبيق. تُرجع كائن من النوع <code>[[JavaScript/Promise|Promise]]</code>.

'''المعاملات'''

{| class="wikitable"
! الاسم
! النوع
! مطلوب
! الوصف
|-
| <code>callback</code>
| <code>‪?(error: ?Error) => void</code>
| لا
| دالة تُستدعى عند إكتمال العملية والحصول على المفاتيح أو عند حدوث خطأ.
|}

=== <code>‎flushGetRequests()‎</code> ===

<syntaxhighlight class="react" lang="javascript">static flushGetRequests(): [object Object]</syntaxhighlight>
تحذف جميع الطلبات المُعلّقة عن طريق الحصول على البيانات كدفعة واحدة.

=== <code>‎multiGet()‎</code> ===

<syntaxhighlight class="react" lang="javascript">static multiGet(keys: Array<string>, [callback]: ?(errors: ?Array<Error>, result: ?Array<Array <string>>) => void)</syntaxhighlight>
تسمح بالحصول على العناصر دفعة واحدة عن طريق إرسال مجموعة من المفاتيح للدالة والحصول على البيانات المرتبطة بهذه المفاتيح في شكل أزواج (key: value). تُرجع كائن من النوع <code>[[JavaScript/Promise|Promise]]</code>.

<syntaxhighlight class="react" lang="javascript">multiGet(['k1', 'k2'], cb) -> cb([['k1', 'val1'], ['k2', 'val2']])</syntaxhighlight>
'''المعاملات'''

{| class="wikitable"
! الاسم
! النوع
! مطلوب
! الوصف
|-
| <code>keys</code>
| ‪Array<string>
| نعم
| مصفوفة من المفاتيح المراد جلب العناصر المرتبطة بها.
|-
| <code>callback</code>
| ‪?(errors: ?Array<Error>
result: ?Array<Array <string>>) => void
| لا
| دالة تُستدعى عند إكتمال العملية والحصول على البيانات أو عند حدوث خطأ.
|}

'''مثال'''

<syntaxhighlight class="react" lang="javascript">AsyncStorage.getAllKeys((err, keys) => {
  AsyncStorage.multiGet(keys, (err, stores) => {
    stores.map((result, i, store) => {
      // get at each store's key/value so you can work with it
      let key = store[i][0];
      let value = store[i][1];
    });
  });
});</syntaxhighlight>
=== <code>‎multiSet()‎</code> ===

<syntaxhighlight class="react" lang="javascript">static multiSet(keyValuePairs: Array<Array <string>>, [callback]: ?(errors: ?Array<Error>) => void)</syntaxhighlight>
تُحزِّن عددًا من الازواج (<code>key: value</code>) دفعةً واحدة. عند اكتمال العملية تحصل على ردّ نداء واحد يحتوي على جميع الأخطاء في حال حدوثها. تُرجع كائن من النوع <code>[[JavaScript/Promise|Promise]]</code>.

<syntaxhighlight class="react" lang="javascript">multiSet([['k1', 'val1'], ['k2', 'val2']], cb);</syntaxhighlight>'''المعاملات:'''
{| class="wikitable"
! الاسم
! النوع
! مطلوب
! الوصف
|-
|<code>keyValuePairs</code>
| ‪Array<Array <string>>
| نعم
| مصفومة من الازواج (<code>key: value</code>).
|-
|<code>callback</code>
| ‪?(errors: ?Array<Error>,
result: ?Array<Array <string>>) => void
| لا
| دالة تُستدعى عند اكتمال العملة أو عند حدوث خطأ.
|}

=== <code>‎multiRemove()‎</code> ===

<syntaxhighlight class="react" lang="javascript">static multiRemove(keys: Array<string>, [callback]: ?(errors: ?Array<Error>) => void)</syntaxhighlight>
تحذف جميع البيانات المرتبطة بالمفاتيح المُعطاة للدالة. تُرجع كائن من النوع <code>[[JavaScript/Promise|Promise]]</code>.

'''المعاملات'''

{| class="wikitable"
! الاسم
! النوع
! مطلوب
! الوصف
|-
| <code>keys</code>
| ‪Array<string>
| نعم
| مصفوفة من المفاتيح المراد حذفها.
|-
| <code>callback</code>
| ‪?(errors: ?Array<Error>) => void
| لا
| دالة تُستدعى عند إكتمال العملية أو عند حدوث خطأ.
|}

'''مثال'''

<syntaxhighlight class="react" lang="javascript">let keys = ['k1', 'k2'];
AsyncStorage.multiRemove(keys, (err) => {
  // keys k1 &amp; k2 removed, if they existed
  // do most stuff after removal (if you want)
});</syntaxhighlight>
=== <code>multiMerge</code> ===

<syntaxhighlight class="react" lang="javascript">static multiMerge(keyValuePairs: Array<Array <string>>, [callback]: ?(errors: ?Array<Error>) => void)</syntaxhighlight>
تُحدِّث قيم أكثر من مفتاح واحد دفعة واحدة. ويجب أن تكون جميع القيم والمفاتيح في شكل سلسلة JSON. تُرجع كائن من النوع <code>[[JavaScript/Promise|Promise]]</code>.

'''ملاحظة''': بعض عمليات التنفيذ للمنصات الأصيلة (Native implementations) لا تدعم هذه الدالة.

'''المعاملات'''

{| class="wikitable"
! الاسم
! النوع
! مطلوب
! الوصف
|-
| <code>keyValuePairs</code>
| ‪Array<Array <string>>
| نعم
| مصفومة من الأزواج (key: value).
|-
| <code>callback</code>
| ‪?(errors: ?Array<Error>,
result: ?Array<Array <string>>) => void
| لا
| دالة تُستدعى عند إكتمال العملة أو عند حدوث خطأ.
|}

'''مثال'''

<syntaxhighlight class="react" lang="javascript">// first user, initial values
let UID234_object = {
  name: 'Chris',
  age: 30,
  traits: { hair: 'brown', eyes: 'brown' }
};

// first user, delta values
let UID234_delta = {
  age: 31,
  traits: { eyes: 'blue', shoe_size: 10 }
};

// second user, initial values
let UID345_object = {
  name: 'Marge',
  age: 25,
  traits: { hair: 'blonde', eyes: 'blue' }
};

// second user, delta values
let UID345_delta = {
  age: 26,
  traits: { eyes: 'green', shoe_size: 6 }
};

let multi_set_pairs = [
  ['UID234', JSON.stringify(UID234_object)],
  ['UID345', JSON.stringify(UID345_object)]
];
let multi_merge_pairs = [
  ['UID234', JSON.stringify(UID234_delta)],
  ['UID345', JSON.stringify(UID345_delta)]
];

AsyncStorage.multiSet(multi_set_pairs, (err) => {
  AsyncStorage.multiMerge(multi_merge_pairs, (err) => {
    AsyncStorage.multiGet(['UID234', 'UID345'], (err, stores) => {
      stores.map((result, i, store) => {
        let key = store[i][0];
        let val = store[i][1];
        console.log(key, val);
      });
    });
  });
});

// Console log results:
// => UID234 {"name":"Chris","age":31,"traits":{"shoe_size":10,"hair":"brown","eyes":"blue"}}
// => UID345 {"name":"Marge","age":26,"traits":{"shoe_size":6,"hair":"blonde","eyes":"green"}}</syntaxhighlight>
== المصادر ==

* [https://reactnative.dev/docs/asyncstorage صفحة AsyncStorage في توثيق React Native الرسمي].
[[تصنيف: ReactNative]]