الواجهة AsyncStorage في React Native

مهملة: استخدم إحدى الحزم التي يوفرها المجتمع بدلًا عنها.

AsyncStorage هو نظام تخزين مستمر غير مشفّر وغير متزامن، يُخزن البيانات في صورة أزواج (key: value)، وهو نظام موحّد لكلّ أجزاء التطبيق، ويجب استعماله بدلًا عن LocalStorage.

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

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

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

مثال

مثال لاستيراد مكتبة AsyncStorage:

import { AsyncStorage} from 'react-native';

حفظ البيانات:

_storeData = async () => {
  try {
    await AsyncStorage.setItem(
      '@MySuperStore:key',
      'I like to save it.'
    );
  } catch (error) {
    // Error saving data
  }
};

قراءة البيانات:

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

التوابع

`‎getItem()‎`

static getItem(key: string, [callback]: ?(error: ?Error, result: ?string) => void)

تجلب البيانات الخاصة بمفتاح (key) معيّن وتستدعي ردّ نداء (callback). بعد إكتمال العملية أو حدوث خطأ أثناء التنفيذ تُرجع كائن من النوع promise.

المعاملات

الاسم	النوع	مطلوب	الوصف
`key`	سلسلة نصية (string)	نعم	المفتاح الخاص بالبيانات المُراد جلبها.
`callback`	‪?(error: ?Error, result: ?string) => void	لا	دالة تُستدعى عند إكتمال عملية جلب البيانات أو حدوث خطأ أثناء العملية.

`‎setItem()‎`

static setItem(key: string, value: string, [callback]: ?(error: ?Error) => void)

تُخزِّن البيانات في صورة زوج (key: value)، وتستدعي دالة بعد إكتمال العملية أو حدوث خطأ أثناء التنفيذ. تُرجع كائن من النوع Promise.

المعاملات:

الاسم	النوع	مطلوب	الوصف
`key`	سلسلة نصية (string)	نعم	المفتاح الخاص بالعنصر المُراد تخزينه.
`value`	سلسلة نصية (string)	نعم	العنصر المراد تخزينه.
`callback`	‪?(error: ?Error) => void	لا	دالة تُستدعى عند حدوث خطأ اثناء العملية.

`‎removeItem()‎`

static removeItem(key: string, [callback]: ?(error: ?Error) => void)

تحذف العنصر المرتبط بالمفتاح المعين، وتستدعي دالة بعد إكتمال العملية أو حدوث خطأ أثناء التنفيذ. تُرجع كائن من النوع Promise.

المعاملات:

الاسم	النوع	مطلوب	الوصف
`key`	سلسلة نصية (string)	نعم	المفتاح الخاص بالعنصر المُراد حذفه.
`callback`	‪?(error: ?Error) => void	لا	دالة تُستدعى عند حدوث خطأ اثناء العملية.

`mergeItem()‎`

static mergeItem(key: string, value: string, [callback]: ?(error: ?Error) => void)

تُحدِّث القيمة المرتبطة معيّن. ويجب أن يكون المفتاح والقيمة الجديدة في شكل سلسلة JSON. تُرجع كائن من النوع Promise.

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

المعاملات:

الاسم	النوع	مطلوب	الوصف
`key`	سلسلة نصية (string)	نعم	المفتاح المُراد تحديث قيمته.
`value`	سلسلة نصية (string)	نعم	القيمة الجديدة للمفتاح.
`callback`	‪?(error: ?Error) => void	لا	دالة تُستدعى عند حدوث خطأ اثناء العملية.

مثال:

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

`‎clear()‎`

static clear([callback]: ?(error: ?Error) => void)

تحذف جميع البيانات المُخزنة في AsyncStorage، حتى تلك المرتبطة بتطبيقات أخرى. لذلك لا يُنصح باستخدامها ويجب استخدام removeItem أو multiRemove لمسح المفاتيح المرتبطة بتطبيقك فقط. تُرجع كائن من النوع Promise.

المعاملات:

الاسم	النوع	مطلوب	الوصف
`callback`	`‪?(error: ?Error) => void`	لا	دالة تُستدعى عند حدوث خطأ اثناء العملية.

`‎getAllKeys()‎`

static getAllKeys([callback]: ?(error: ?Error, keys: ?Array<string>) => void)

تتحصل على جميع المفاتيح المرتبطة بالتطبيق. تُرجع كائن من النوع Promise.

المعاملات

الاسم	النوع	مطلوب	الوصف
`callback`	`‪?(error: ?Error) => void`	لا	دالة تُستدعى عند إكتمال العملية والحصول على المفاتيح أو عند حدوث خطأ.

`‎flushGetRequests()‎`

static flushGetRequests(): [object Object]

تحذف جميع الطلبات المُعلّقة عن طريق الحصول على البيانات كدفعة واحدة.

`‎multiGet()‎`

static multiGet(keys: Array<string>, [callback]: ?(errors: ?Array<Error>, result: ?Array<Array <string>>) => void)

تسمح بالحصول على العناصر دفعة واحدة عن طريق إرسال مجموعة من المفاتيح للدالة والحصول على البيانات المرتبطة بهذه المفاتيح في شكل أزواج (key: value). تُرجع كائن من النوع Promise.

multiGet(['k1', 'k2'], cb) -> cb([['k1', 'val1'], ['k2', 'val2']])

المعاملات

الاسم	النوع	مطلوب	الوصف
`keys`	‪Array<string>	نعم	مصفوفة من المفاتيح المراد جلب العناصر المرتبطة بها.
`callback`	‪?(errors: ?Array<Error> result: ?Array<Array <string>>) => void	لا	دالة تُستدعى عند إكتمال العملية والحصول على البيانات أو عند حدوث خطأ.

مثال

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

`‎multiSet()‎`

static multiSet(keyValuePairs: Array<Array <string>>, [callback]: ?(errors: ?Array<Error>) => void)

تُحزِّن عددًا من الازواج (key: value) دفعةً واحدة. عند اكتمال العملية تحصل على ردّ نداء واحد يحتوي على جميع الأخطاء في حال حدوثها. تُرجع كائن من النوع Promise.

multiSet([['k1', 'val1'], ['k2', 'val2']], cb);

المعاملات:

الاسم	النوع	مطلوب	الوصف
`keyValuePairs`	‪Array<Array <string>>	نعم	مصفومة من الازواج (`key: value`).
`callback`	‪?(errors: ?Array<Error>, result: ?Array<Array <string>>) => void	لا	دالة تُستدعى عند اكتمال العملة أو عند حدوث خطأ.

`‎multiRemove()‎`

static multiRemove(keys: Array<string>, [callback]: ?(errors: ?Array<Error>) => void)

تحذف جميع البيانات المرتبطة بالمفاتيح المُعطاة للدالة. تُرجع كائن من النوع Promise.

المعاملات

الاسم	النوع	مطلوب	الوصف
`keys`	‪Array<string>	نعم	مصفوفة من المفاتيح المراد حذفها.
`callback`	‪?(errors: ?Array<Error>) => void	لا	دالة تُستدعى عند إكتمال العملية أو عند حدوث خطأ.

مثال

let keys = ['k1', 'k2'];
AsyncStorage.multiRemove(keys, (err) => {
  // keys k1 &amp; k2 removed, if they existed
  // do most stuff after removal (if you want)
});

`multiMerge`

static multiMerge(keyValuePairs: Array<Array <string>>, [callback]: ?(errors: ?Array<Error>) => void)

تُحدِّث قيم أكثر من مفتاح واحد دفعة واحدة. ويجب أن تكون جميع القيم والمفاتيح في شكل سلسلة JSON. تُرجع كائن من النوع Promise.

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

المعاملات

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

مثال

// 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"}}

المصادر

صفحة AsyncStorage في توثيق React Native الرسمي.