Cordova/storage

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

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

التخزين المحلي (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
• MDN: الواجهة البرمجية للتخزين
• MDN: دليل التخزين

المزايا

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

العيوب

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

WebSQL

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

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

• أندرويد
• 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

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

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

المزايا

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

العيوب

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

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

IndexedDB

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

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

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

IndexedDB مدعومة من WebView على منصات Cordova التالية:

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

قيود ويندوز

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

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

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

• تعمل IndexedDB بشكل غير متزامن - إذ تقوم بطلب عملية معينة على قاعدة بيانات، ثم يتم إعلامك بالنتيجة عبر حدث دوم (DOM event).
• عندما تقوم بتقديم طلب، ستحصل على كائن طلب (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 API

كانت FileSystem API جزءًا من مواصفات W3C، وقد نُزِّلت (implemented) من قبل Chrome دون بقية المتصفحات.

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

إضافة SQLite

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

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

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

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

إضافات أخرى

إن أردت خيارات تخزين بديلة فابحث عن Cordova plugins.

انظر أيضا

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

مصادر

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