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: Storage API
• MDN: Storage Guide

المزايا

• مدعومة من جميع منصات 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.
• واجهة برمجية معقدة تحتوي على استدعاءات متشعبة.
• محدودية مساحة التخزين (حوالي 5MB في العادة).

إضافات

FileSystem API

كانت FileSystem API جزءًا من مواصفات W3C، والتي تم تتزيلها من قبل Chrome دون بقية المتصفحات. توفر هذه الإضافة واجهات برمجية لتخزين واسترجاع البيانات على نظام الملفات المحلي (يمكنك معرفة المزيد من المقال المفصل html5rocks article). على الرغم من أن الواجهة البرمجية غير مدعومة من قبل أي منصة من منصات كوردوفا، يوفر File plugin تقديما شاملاً ومتوفرًا على جميع منصات Cordova.

إضافة SQLite

توفر الإضافة SQLite واجهة برمجية شبه مطابقة لواجهة WebSQL الموضحة أعلاه. الاختلافات الرئيسية هي:

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

كما أنها متاحة في التشكيلات التالية:

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

Cordova-sqlite-ext ولكن مع تحسين التعامل مع الذاكرة. متاحة تحت رخصة GPL v3 أو تحت رخصة تجارية.

إضافات أخرى

ابحث عن [/plugins Cordova plugins] لأجل إضافات أخرى توفر خيارات تخزين بديلة.

مصادر

• قسم التخزين في التوثيق الرسمي لكوردوفا.