Cordova/storage

تتوفر العديد من واجهات برمجة التطبيقات (APIs) المتخصصة في التخزين لأجل استخدامها مع تطبيقات كوردوفا.

لكل واجهة برمجية مزايا وعيوب، والتي سنلخصها في هذه الصفحة. وعليك اختيار ما يناسب احتياجاتك. يمكنك أيضًا استخدام عدة مقاربات في نفس التطبيق لخدمة أغراض مختلفة.

الواجهة LocalStorage

يوفر التخزين المحلي (Local storage) تخزينًا بسيطًا ومتزامنًا للبيانات على شكل أزواج مفتاح/قيمة (key/value)، وهو مدعوم من قِبَل العارض WebView في جميع منصات كوردوفا.

ملخص الاستخدام

يمكن الوصول إلى ميزة التخزين المحلي عبر window.localStorage. تعرض الشيفرة التالية أهم توابع الكائن Storage المعاد:

var storage = window.localStorage;
var value = storage.getItem(key); // تمرير مفتاح لاستعادة قيمته
storage.setItem(key, value) // تمرير مفتاح وقيمته لإضافة أو تحديث المفتاح
storage.removeItem(key) // تمرير مفتاح لإزالة ذلك المفتاح من المخزن

لمزيد من المعلومات، اطلع على الصفحات الخارجية التالية:

• مواصفات W3C.
• الواجهة البرمجية للتخزين.
• دليل التخزين.

المزايا

• مدعومة من جميع منصات كوردوفا.
• بساطة وتزامنية الواجهة البرمجية تعني أنَّها سهلة الاستخدام.

المساوئ

• تخزن السلاسل النصية فقط؛ لذلك، فالبيانات المعقدة يجب أن تُسَلسَل (serialized)، هذا يعني أنه لا يمكنها تخزين إلا البيانات القابلة للسَّلسَّلة.
• أداؤها سيء مع البيانات ذات الأحجام الكبيرة. تحديدًا:
  • عدم وجود فهرسة يعني أن عمليات البحث تتطلب تكرارًا يدويًّا (manually iterating) على جميع البيانات.
  • تخزين البيانات الكبيرة أو المعقدة بطيء بسبب الحاجة إلى سَلسَلة/فك (serialize/de-serialize) البيانات.
  • الواجهة البرمجية المتزامنة تقتضي أن الاستدعاءات ستعيق (lock) واجهة المستخدم.
• محدودية المساحة الإجمالية للتخزين (5MB في العادة).
• تُخزّن منصة iOS البيانات localStorage المحلية في موضع قد يتم تنظيفه من قبل نظام التشغيل عند الحاجة لتحرير المساحة.

الواجهة WebSQL

توفر الواجهة WebSQL واجهةً برمجيةً لتخزين البيانات في قاعدة بيانات مُهيكلة، والتي يمكن الاستعلام منها باستخدام صيغ SQL العادية (SQLite تحديدًا). وهكذا فهي تضع بين يديك إمكانية الاستفادة من قوة (وتعقيد) لغة SQL.

هذه الميزة مدعومة من WebView على منصات كوردوفا التالية:

• أندرويد
• iOS

ملخص الاستخدام

لإنشاء أو فتح قاعدة بيانات، استخدم التابع window.openDatabase()‎:

var db = window.openDatabase(name, version, displayName, estimatedSize);‎

المعاملات المُمرَّر إلى التابع هي:

• name: سلسلة نصية تمثِّل الاسم المميز لقاعدة البيانات، والذي ستُخزّن به على القرص.
• version: سلسلة نصية تمثِّل إصدار قاعدة البيانات.
• displayName: سلسلة نصية تمثِّل اسم مبسط ومفهوم لقاعدة البيانات والذي سيستخدمه النظام إن كان بحاجة إلى وصف قاعدة بياناتك للمستخدم (عند طلب الإذن لزيادة حجم قاعدة البيانات مثلًا).
• estimatedSize: عدد يمثِّل الحجم الأقصى المتوقع لقاعدة البيانات بالبايت (byte). فمع تزايد حجم قاعدة البيانات، قد يُطالَب المستخدم بالحصول على إذن. إذا اخترت قيمةً مناسبةً، فمن المحتمل أن تقلل من وتيرة مطالبة المستخدم بالإذن.

يوفر كائن Database المُعاد التابع transaction()‎ (أو readTransaction()‎ لتحسين أداء معامَلات القراءة فقط [read-only]) الذي يمكِّنك من إنشاء عمليات نقل آمنة:

var db = window.openDatabase(name, version, displayName, estimatedSize);
db.transaction(function (tx) {
    tx.executeSql(sqlStatement, valueArray, function (tx, result) {
        console.log(result);
    }, function (error) {
        console.log(error);
    });
});

لمزيد من المعلومات، اطلع على مواصفات W3C. إن أردت مرجعًا جيدًا لتعلم لغة SQL، فاطلع على توثيق SQL.

إصدارات قواعد البيانات

عند فتح قاعدة بيانات قائمة، فإن كان الإصدار المحدد لا يتطابق مع إصدار قاعدة البيانات، فسيُطلق استثناء ولن تُفتح قاعدة البيانات. لكن إن حدَّدت سلسلةً فارغةً مكان الإصدار، فستُفتح قاعدة البيانات بغض النظر عن إصدارها الحالي (يمكنك الاستعلام عن الإصدار الحالي عبر db.version). لكن كن حذرًا، لأنه في حال إنشاء قاعدة البيانات، فستعيّن سلسلة فارغة لإصدارها.

محاسن

• أداء جيد، إذ يمكن فهرسة البيانات لتسريع عمليات البحث، كما أنّ الواجهة البرمجية غير المتزامنة تعني أنها لا تعوق (lock) واجهة المستخدم.
• متانة (Robustness) واستقرار ناتجين عن استخدام نموذج قاعدة بيانات معامَلاتي (transactional database model).
• دعم الإصدارات (Support for versioning).

مساوئ

• لا تدعمها كل منصات كوردوفا.
• أكثر تعقيدًا من الواجهة LocalStorage أو الواجهة IndexedDB.

• الواجهة البرمجية مهملة. من المستبعد أن تُدعم على المنصات التي لا تدعمها حاليًا، وقد تُزال من المنصات التي تدعمها إلى الآن.
• تفرِض بنية جامدة، والتي يتوجب تعريفها مقدمًا.
• محدودية مساحة التخزين (5MB في العادة).

الواجهة IndexedDB

الهدف من الواجهة IndexedDB البرمجية هو دمج نقاط قوة الواجهتين البرمجيتين LocalStorage و WebSQL، مع تجنب نقاط ضعفهما.

تتيح لك الواجهة IndexedDB تخزين كائنات JavaScript (بشرط أن تكون مدعومة من قبل خوارزمية النسخ المهيكل (structured clone algorithm)) مُفهرَسَة بمفتاح. كما توفر بعضًا من فوائد جداول SQL، دون تقييد البنية، أو الحاجة إلى تعريفها مقدمًا.

توفر IndexedDB نموذج بيانات بسيط وسهل الفهم، تمامًا مثل LocalStorage. ولكن على خلاف LocalStorage، يمكنك إنشاء عدة قواعد بيانات، مع عدة مخازن (stores) في كل قاعدة بيانات؛ أضف إلى ذلك أنَّ أداءها أفضل بفضل واجهتها البرمجية غير المتزامنة والبحث المفهرس.

الواجهة IndexedDB مدعومة من قِبَل WebView الأساسية على منصات كوردوفا التالية:

• ويندوز (مع بعض القيود)
• أندرويد (4.4 فما فوق)

قيود ويندوز

دعم منصة ويندوز للواجهة IndexedDB غير كامل. على سبيل المثال فهي:

• غير متوفرة في عاملات الشبكة (web workers).
• لا تدعم المفاتيح المسارية في المصفوفات (array keyPaths).
• لا تدعم مفاتيح المصفوفات (array keys).
• لا تدعم البحث عن الكائنات عبر الفهارس المركبة.

ملخص الاستخدام

• تعمل الواجهة IndexedDB بشكل غير متزامن، إذ تطلب عملية معينة على قاعدة بيانات، ثم يتم إعلامك بالنتيجة عبر الحدث DOM.
• عندما تقدِّم طلبًا، ستحصل على كائن طلب (request object)، والذي يوفر الحدثين onerror و onsuccess، بالإضافة إلى خصائص مثل result و error و readyState.

يوضح المثال التالي بعض الاستخدامات البسيطة للواجهة IndexedDB:

var db;
var databaseName = 'myDB';
var databaseVersion = 1;
var openRequest = window.indexedDB.open(databaseName, databaseVersion);
openRequest.onerror = function (event) {
    console.log(openRequest.errorCode);
};
openRequest.onsuccess = function (event) {
    // قاعدة البيانات مفتوحة ومهيئة، كل شيء جاهز للبدء
    db = openRequest.result;
    displayData();
};
openRequest.onupgradeneeded = function (event) {
    // هذه إما قاعدة بيانات منشأة حديثا، أو رقم إصدار جديد
    // open() تم تسليمه إلى استدعاء
    var db = event.target.result;
    db.onerror = function () {
        console.log(db.errorCode);
    };
    //تنشئ كائن تخزين وفهارس، المفاتيح هي قيم بيانات تُستخدم لتنظيم واستعادة القيم من 
    // keyPath  كائن التخزين. الخيار  
    //يحدد موضع تخزين المفتاح. في حال تحديد مفتاح المسار، فلن
    //يحتوي المخزن إلا على كائنات جافاسكريبت، وينبغي أن تكون لكل الكائنات المخزنة 
    // autoIncrement  خاصية بنفس اسم مفتاح المسار، إلا إن كان الخيار
    // true  يساوي  
    var store = db.createObjectStore('customers', { keyPath: 'customerId' });

    //تعرف الفهارس التي نريد استخدامها. الكائنات التي نضيف إلى المخزن لا ينبغي 
    //بالضرورة أن تحتوي هذه الخاصيات. ولكنها ستظهر فقط في الفهرس المحدد
    //
    // syntax: store.createIndex(indexName, keyPath[, parameters]);
    //
    // unique  كل هذه القيم يمكن أن تكون مكررة، لذا عين قيمة    
    // false إلى القيمة
    store.createIndex('firstName', 'firstName', { unique: false });
    store.createIndex('lastName', 'lastName', { unique: false });
    store.createIndex('street', 'street', { unique: false });
    store.createIndex('city', 'city', { unique: false });
    store.createIndex('zipCode', 'zipCode', { unique: false });
    store.createIndex('country', 'country', { unique: false });
    // بمجرد إنشاء المخزن، قم بملئه
    store.transaction.oncomplete = function (event) {

       // transaction  يأخذ التابع 
       // مصفوفة مؤلفة من أسماء كائنات التخزين والفهارس التي ستكون في 
       //نطاق المعاملة، أو سلسلة نصية واحدة للدخول إلى كائن تخزين واحد. ستكون 
       // readwrite المعاملة للقراءة فقط إلا في حال تحديد الوسيط الاختياري 
       // objectStore  يعيد كائن معاملات، والذي يوفر التابع 
       //للدخول إلى إحدى كائنات التخزين الموجودة في نطاق هذه المعاملة

        var customerStore = db.transaction('customers', 'readwrite').objectStore('customers');
        customers.forEach(function (customer) {
            customerStore.add(customer);
        });
    };
};
function displayData() {
}‎

لمزيد من المعلومات، اطلع على الصفحات الخارجية التالية:

• مواصفات W3C
• توثيق الواجهة IndexedDB
• مفاهيم أساسية حول IndexedDB
• دليل استخدام IndexedDB

محاسن

• الأداء الجيد، إذ لن تعيق الواجهة البرمجية غير المتزامنة واجهة المستخدم، كما ستوفر الفهرسة أداءً جيدًا في عمليات البحث.
• نموذج بيانات بسيط أسهل في التعلم من SQL.
• بنية أكثر مرونة من الواجهة WebSQL.
• يوفر تعدد قواعد البيانات ومخازن الكائنات (object stores) بنية أكثر تفصيلًا من الواجهة LocalStorage.
• متانة واستقرار نتيجة استخدام نموذج بيانات معاملاتي (transactional database model).
• دعم الإصدارات.

مساوئ

• غير مدعومة على منصة iOS.
• واجهة برمجية معقدة مع استدعاءات متشعبة (nested callbacks).
• محدودية مساحة التخزين (5MB في العادة).

خيارات تستند على الإضافات

الواجهة البرمجية FileSystem

كانت الواجهة FileSystem البرمجية جزءًا من مواصفات W3C، وقد نُفِّذت من قبل Chrome دون بقية المتصفحات.

توفر هذه الواجهة واجهات برمجية لتخزين واسترجاع البيانات على نظام الملفات المحلي (يمكنك معرفة المزيد عبر هذا المقال). على الرغم من أن هذه الواجهة البرمجية غير مدعومة ابتدائيًا من قبل أي منصة من منصات كوردوفا، إلا أن الإضافة File توفر تنفيذًا شاملاً ومتوفرًا على جميع منصات كوردوفا.

الإضافة SQLite

توفر الإضافة SQLite واجهةً برمجيةً مشابهة للواجهة WebSQL الموضحة أعلاه مع بعض الاختلافات، أهمها أنها:

• مدعومةٌ من منصة ويندوز.
• ليس لها فعليًا قيود على الحجم.

كما أنَّها متاحةً في الإصدارات التالية:

• cordova-sqlite-storage: الإصدار الأساسي الذي يتضمن التنفيذ sqlite3 الخاص بها. وهو مدعوم من منصات iOS وأندرويد وويندوز.
• cordova-sqlite-ext: إصدار موسع مع ميزات إضافية بما في ذلك دعم التعابير النظامية (REGEXP) على أندرويد و iOS.
• cordova-sqlite-evfree: مماثل للإصدار Cordova-sqlite-ext، ولكنه أكثر كفاءة في التعامل مع الذاكرة. متاح تحت رخصة جنو العمومية الإصدار الثالث (GPL v3) أو تحت رخصة تجارية.

إضافات أخرى

إن أردت خيارات تخزين بديلة فابحث في مستودع إضافات كوردوفا.

انظر أيضًا

• تطوير الإضافات.
• إضافة الوصول إلى الملفات.

مصادر

• صفحة Storage في توثيق كوردوفا الرسمي.