واجهات برمجة التطبيقات للتخزين

يتضمن كل جانب من جوانب تطوير التطبيق تقريبًا عنصرًا لإرسال البيانات أو استلامها. وقت البدء بالأساسيات، ينبغي لك استخدام إطار عمل MVC لمساعدتك في تصميم تطبيقك وتنفيذه بحيث تكون البيانات منفصلة تمامًا عن عرض التطبيق على هذه البيانات (راجِع بنية "MVC").

يجب أيضًا التفكير في كيفية معالجة البيانات عندما يكون تطبيقك غير متصل بالإنترنت (راجع وضع عدم الاتصال بالإنترنت أولاً). يقدم هذا المستند بإيجاز خيارات التخزين لإرسال البيانات واستلامها وحفظها محليًا؛ الـ يوضح لك باقي المستند كيفية استخدام نظام الملفات في Chrome وواجهات برمجة تطبيقات نظام مزامنة الملفات (راجع أيضًا fileSystem API وsyncFileSystem API).

خيارات التخزين

تستخدم التطبيقات المجمّعة العديد من الآليات المختلفة لإرسال البيانات واستلامها. بالنسبة للبيانات الخارجية (الموارد، على الويب)، يجب أن تكون على دراية بسياسة أمان المحتوى (CSP). تطبيقات مشابهة لمتصفِّح Chrome الإضافات، يمكنك استخدام طلبات XMLHttpRequests متعددة المصادر للاتصال بالخوادم البعيدة. إِنْتَ كذلك عزل الصفحات الخارجية، لكي يكون باقي التطبيق آمنًا (راجع تضمين محتوى الويب الخارجي الصفحات).

عند حفظ البيانات محليًا، يمكنك استخدام Chrome Storage API لحفظ كميات صغيرة من السلاسل. وIndexedDB لحفظ البيانات المهيكلة. باستخدام IndexedDB، يمكنك الاحتفاظ بكائنات JavaScript تخزين العناصر واستخدام فهارس المتجر للاستعلام عن البيانات (لمزيد من المعلومات، راجع Simple Todo في HTML5 Rock إدراج برنامج تعليمي). وبالنسبة إلى جميع الأنواع الأخرى من البيانات، مثل البيانات الثنائية، استخدِم نظام الملفات والمزامنة واجهات برمجة التطبيقات لنظام الملفات

تعمل واجهات برمجة التطبيقات لنظام الملفات والمزامنة في نظام الملفات في Chrome على توسيع واجهة برمجة تطبيقات HTML5 FileSystem. باستخدام متصفّح Chrome واجهة برمجة التطبيقات لنظام الملفات، ويمكن للتطبيقات إنشاء قسم في وضع الحماية من منظور المستخدم وقراءته والتنقّل فيه والكتابة إليه نظام الملفات المحلي. على سبيل المثال، يمكن لتطبيق مشاركة الصور استخدام Filesystem API لقراءة أي محتوى الصور التي يختارها المستخدم.

باستخدام واجهة برمجة التطبيقات Sync Filesystem API في Chrome، يمكن للتطبيقات حفظ البيانات ومزامنتها في Google Drive للمستخدم كي يمكن أن تتوفر نفس البيانات عبر عملاء مختلفين. على سبيل المثال، قد يتضمن النص المدعوم من السحابة الإلكترونية المحرر تلقائيًا مزامنة الملفات النصية الجديدة مع حساب المستخدم على Google Drive. عندما يفتح المستخدم محرِّر النصوص في برنامج جديد، وترسل خدمة Google Drive ملفات نصية جديدة إلى هذا المثيل محرر النصوص.

استخدام واجهة برمجة تطبيقات نظام ملفات Chrome

إضافة إذن نظام الملفات

لاستخدام واجهة برمجة تطبيقات نظام الملفات في Chrome، عليك إضافة القسم "fileSystem" إذن إلى البيان، لذلك التي تتيح لك الحصول على إذن من المستخدم لتخزين البيانات الدائمة.

"permissions": [
  "...",
  "fileSystem"
]

خيارات المستخدم لاختيار الملفات

يتوقع المستخدمون اختيار الملفات بالطريقة نفسها التي يختارونها دائمًا. على الأقل، يتوقعون اختيار "اختيار ملف' والزر ومحدد الملفات القياسي. إذا كان تطبيقك يستخدم تسليم الملفات بشكل مكثّف، عليك أيضًا نفِّذ السحب والإفلات (انظر أدناه واطّلع أيضًا على السحب والإفلات الأصلي في HTML5).

الحصول على مسار fileEntry

للحصول على المسار الكامل للملف الذي اختاره المستخدم، fileEntry، يمكنك طلب getDisplayPath():

function displayPath(fileEntry) {
  chrome.fileSystem.getDisplayPath(fileEntry, function(path) {
    console.log(path)
  });
}

تنفيذ السحب والإفلات

إذا كنت بحاجة إلى تنفيذ اختيار السحب والإفلات، فإن وحدة التحكم في الملفات بالسحب والإفلات (dnd.js) في نموذج filesystem-access نقطة انطلاق جيدة. تنشئ وحدة التحكم إدخال ملف من DataTransferItem عن طريق السحب والإفلات. في هذا المثال، يتم ضبط fileEntry على أوّل تم إسقاطه.

var dnd = new DnDFileController('body', function(data) {
  var fileEntry = data.items[0].webkitGetAsEntry();
  displayPath(fileEntry);
});

قراءة ملف

يفتح الرمز التالي الملف (للقراءة فقط) ويقرأه كنص باستخدام كائن FileReader. في حال حذف لم يكن الملف موجودًا، حدث خطأ.

var chosenFileEntry = null;

chooseFileButton.addEventListener('click', function(e) {
  chrome.fileSystem.chooseEntry({type: 'openFile'}, function(readOnlyEntry) {

    readOnlyEntry.file(function(file) {
      var reader = new FileReader();

      reader.onerror = errorHandler;
      reader.onloadend = function(e) {
        console.log(e.target.result);
      };

      reader.readAsText(file);
    });
    });
});

كتابة ملف

حالتا الاستخدام الشائعان لكتابة ملف هما "حفظ" و"حفظ باسم". تُنشئ التعليمة البرمجية التالية writableEntry من chosenFileEntry للقراءة فقط ويكتب فيها الملف المحدّد.

 chrome.fileSystem.getWritableEntry(chosenFileEntry, function(writableFileEntry) {
    writableFileEntry.createWriter(function(writer) {
      writer.onerror = errorHandler;
      writer.onwriteend = callback;

    chosenFileEntry.file(function(file) {
      writer.write(file);
    });
  }, errorHandler);
});

تُنشئ التعليمة البرمجية التالية ملفًا جديدًا باستخدام "حفظ باسم" وتكتب الكائن الثنائي الكبير (blob) الجديد في باستخدام طريقة writer.write().

chrome.fileSystem.chooseEntry({type: 'saveFile'}, function(writableFileEntry) {
    writableFileEntry.createWriter(function(writer) {
      writer.onerror = errorHandler;
      writer.onwriteend = function(e) {
        console.log('write complete');
      };
      writer.write(new Blob(['1234567890'], {type: 'text/plain'}));
    }, errorHandler);
});

استخدام واجهة برمجة تطبيقات نظام ملفات مزامنة Chrome

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

إضافة إذن مزامنة نظام الملفات

لاستخدام واجهة برمجة تطبيقات نظام ملفات المزامنة في Chrome، عليك إضافة "syncFileSystem" إذن بحيث يمكنك الحصول على إذن من المستخدم لتخزين البيانات الدائمة ومزامنتها.

"permissions": [
  "...",
  "syncFileSystem"
]

بدء تخزين الملفات القابلة للمزامنة

لبدء تخزين الملفات القابلة للمزامنة في تطبيقك، ما عليك سوى طلب syncFileSystem.requestFileSystem. تعرض هذه الطريقة نظام ملفات قابل للمزامنة يدعمه Google Drive، على سبيل المثال:

chrome.syncFileSystem.requestFileSystem(function (fs) {
   // FileSystem API should just work on the returned 'fs'.
   fs.root.getFile('test.txt', {create:true}, getEntryCallback, errorCallback);
});

لمحة عن حالة مزامنة الملفات

استخدِم syncFileSystem.getFileStatus للحصول على حالة المزامنة لملف حالي:

chrome.syncFileSystem.getFileStatus(entry, function(status) {...});

يمكن أن تكون قيم حالة مزامنة الملفات واحدة مما يلي: 'synced' أو 'pending' أو 'conflicting'. "تمت المزامنة" تعني أن الملف متزامن بالكامل؛ ليست هناك أي تغييرات محلية معلّقة لم يتم إجراؤها تمت مزامنته مع Google Drive. ومع ذلك، قد تكون هناك تغييرات معلّقة من جانب Google Drive التي لم يتم استرجاعها بعد.

"في انتظار المراجعة" يعني أنّ الملف يحتوي على تغييرات معلّقة لم تتم مزامنتها مع Google Drive بعد. إذا كان التطبيق عبر الإنترنت، تتم مزامنة التغييرات المحلية (تقريبًا) على الفور مع Google Drive، يتم تنشيط حدث syncFileSystem.onFileStatusChanged بالحالة 'synced' (انظر أدناه المزيد من التفاصيل).

يتم تنشيط syncFileSystem.onFileStatusChanged عندما تتغير حالة الملف إلى 'conflicting' "متعارضة" تعني أن هناك تغييرات متعارضة على كل من سعة التخزين المحلية Google Drive لا يمكن أن يكون الملف بهذه الحالة إلا إذا تم ضبط سياسة حل التعارض على 'manual' السياسة التلقائية هي 'last_write_win' ويتم حلّ التعارضات تلقائيًا من خلال سياسة بسيطة للطرفين من حيث الكتابة. يمكن تغيير سياسة حل التعارض في النظام من خلال syncFileSystem.setConflictResolutionPolicy.

في حال ضبط سياسة حلّ التعارض على 'manual' ونتج عن ملف حالة 'conflicting'، سيظل بإمكان التطبيق قراءة الملف وكتابته كملف محلي بلا اتصال بالإنترنت، ولكن لا تتم مزامنة التغييرات. وسيظل الملف منفصلاً عن التغييرات التي يتم إجراؤها عن بُعد على العملاء الآخرين إلى أن يحدث التعارض تم حلها. أسهل طريقة لحل التعارض هي حذف أو إعادة تسمية النسخة المحلية من الملف. يؤدي ذلك إلى فرض مزامنة النسخة البعيدة وحل حالة التعارض يتم تنشيط حدث onFileStatusChanged بالحالة 'synced'.

الاستماع إلى التغييرات في الحالة المتزامنة

يتم تنشيط الحدث syncFileSystem.onFileStatusChanged عند تغيُّر حالة مزامنة الملف. على سبيل المثال، لنفترض أنّ ملفًا يتضمّن تغييرات معلّقة وهو في الحالة "في انتظار المراجعة". الولاية. ربما كان التطبيق في حالة عدم الاتصال بالإنترنت حيث يكون التغيير على وشك أن تتم مزامنته. وعندما تكتشف خدمة المزامنة في انتظار التغيير المحلي ويحمّل التغيير إلى Google Drive، تُنشِئ الخدمة حدث واحد (onFileStatusChanged) مع القيم التالية: { fileEntry:a fileEntry for the file, status: 'synced', action: 'updated', direction: 'local_to_remote' }

وبالمثل، وبغض النظر عن الأنشطة المحلية، قد تكتشف خدمة المزامنة التغييرات التي يجريها المستخدم عن بُعد برنامج عميل آخر، وينزِّل التغييرات من Google Drive إلى مساحة التخزين المحلية. إذا كان جهاز التحكم عن بُعد كان التغيير لإضافة ملف جديد، يتم تنشيط حدث بالقيم التالية: { fileEntry: a fileEntry for the file, status: 'synced', action: 'added', direction: 'remote_to_local' }

إذا كان هناك تغييرات متعارضة بين الجانبين المحلي والبعيد للملف نفسه وإذا كان التعارض تم ضبط سياسة الدقة على 'manual'، وتم تغيير حالة الملف إلى حالة conflicting، وأصبح منفصلة عن خدمة المزامنة، ولن تتم مزامنتها حتى يتم حل التعارض. في هذه الدورة، في حال تنشيط حدث بالقيم التالية: { fileEntry: a fileEntry for the file, status: 'conflicting', action: null, direction: null }

يمكنك إضافة أداة معالجة حدث هذا الحدث للاستجابة لأي تغييرات في الحالة. على سبيل المثال، يستمع تطبيق Chrome Music Player إلى أي موسيقى جديدة تمت مزامنتها من Google Drive، ولكنه لا يستمع بعد إلى إلى التخزين المحلي للمستخدم على جهاز عميل معين. أي موسيقى يتم العثور عليها تتم مزامنتها مع ذلك. العميل:

chrome.syncFileSystem.onFileStatusChanged.addListener(function(fileInfo) {
  if (fileInfo.status === 'synced') {
    if (fileInfo.direction === 'remote_to_local') {
      if (fileInfo.action === 'added') {
        db.add(fileInfo.fileEntry);
      } else if (fileInfo.action === 'deleted') {
        db.remove(fileInfo.fileEntry);
      }
    }
  }
});

التحقّق من استخدام واجهة برمجة التطبيقات

للتحقق من كمية البيانات التي تستخدمها واجهة برمجة التطبيقات، يمكنك الاستعلام عن الدليل المحلي في وضع الحماية الخاص بالتطبيق أو وحدات بايت الاستخدام التي يعرضها syncFileSystem.getUsageAndQuota:

chrome.syncFileSystem.getUsageAndQuota(fileSystem, function (storageInfo) {
   updateUsageInfo(storageInfo.usageBytes);
   updateQuotaInfo(storageInfo.quotaBytes);
});

يمكنك أيضًا الاطلاع على تخزين خدمة الخلفية للمزامنة للمستخدم (في Google Drive). الملفات التي تمت مزامنتها هي تم حفظه في مجلد مخفي في Google Drive، Chrome Syncable FileSystem (نظام الملفات القابل للمزامنة في Chrome). لن يتم عرض المجلد في ملفك في "ملفاتي" ولكن يمكن الوصول إليها بالبحث عن اسم المجلد في مربع البحث. (لاحظ أن لا يمكن ضمان بقاء تنسيق المجلد البعيد متوافقًا مع الإصدارات القديمة بين الإصدارات.)