API های ذخیره سازی

تقریباً هر جنبه ای از توسعه برنامه شامل برخی از عناصر ارسال یا دریافت داده است. با شروع، باید از یک چارچوب MVC استفاده کنید تا به شما کمک کند برنامه خود را طراحی و پیاده سازی کنید تا داده ها کاملاً از دیدگاه برنامه در مورد آن داده جدا باشد (به معماری MVC مراجعه کنید).

همچنین باید به نحوه مدیریت داده ها در زمانی که برنامه شما آفلاین است فکر کنید ( ابتدا به آفلاین مراجعه کنید). این سند به طور خلاصه گزینه های ذخیره سازی برای ارسال، دریافت و ذخیره داده ها را به صورت محلی معرفی می کند. باقی‌مانده سند به شما نشان می‌دهد که چگونه از APIهای File System و Sync File System Chrome استفاده کنید (همچنین به fileSystem API و syncFileSystem API مراجعه کنید).

گزینه های ذخیره سازی

برنامه های بسته بندی شده از مکانیسم های مختلفی برای ارسال و دریافت داده ها استفاده می کنند. برای داده های خارجی (منابع، صفحات وب)، باید از سیاست امنیتی محتوا (CSP) آگاه باشید. مشابه برنامه‌های افزودنی Chrome، می‌توانید از XMLHttpRequest‌های متقاطع برای برقراری ارتباط با سرورهای راه دور استفاده کنید. همچنین می توانید صفحات خارجی را ایزوله کنید تا بقیه برنامه شما ایمن باشد (به جاسازی صفحات وب خارجی مراجعه کنید).

هنگام ذخیره داده‌ها به صورت محلی، می‌توانید از Chrome Storage API برای ذخیره مقادیر کمی از داده‌های رشته‌ای و از IndexedDB برای ذخیره داده‌های ساخت‌یافته استفاده کنید. با IndexedDB، می‌توانید اشیاء جاوا اسکریپت را در یک شی ذخیره کنید و از فهرست‌های فروشگاه برای جستجوی داده‌ها استفاده کنید (برای کسب اطلاعات بیشتر، به آموزش فهرست کار ساده HTML5 Rock مراجعه کنید). برای سایر انواع داده‌ها، مانند داده‌های باینری، از Filesystem و Sync Filesystem API استفاده کنید.

APIهای سیستم فایل و همگام‌سازی Chrome's Filessystem API HTML5 FileSystem را گسترش می‌دهند. با استفاده از API Filesystem Chrome، برنامه‌ها می‌توانند در قسمتی از سیستم فایل محلی کاربر ایجاد کنند، بخوانند، پیمایش کنند و بنویسند. به عنوان مثال، یک برنامه اشتراک‌گذاری عکس می‌تواند از Filesystem API برای خواندن و نوشتن هر عکسی که کاربر انتخاب می‌کند استفاده کند.

با استفاده از Chrome's Sync Filesystem API، برنامه‌ها می‌توانند داده‌ها را در Google Drive کاربر ذخیره و همگام‌سازی کنند تا داده‌های یکسان در میان کلاینت‌های مختلف در دسترس باشد. به عنوان مثال، یک برنامه ویرایشگر متن با پشتوانه ابری می تواند به طور خودکار فایل های متنی جدید را با حساب Google Drive کاربر همگام کند. هنگامی که کاربر ویرایشگر متن را در یک کلاینت جدید باز می کند، Google Drive فایل های متنی جدید را به آن نمونه از ویرایشگر متن فشار می دهد.

با استفاده از Chrome Filesystem API

اضافه کردن مجوز سیستم فایل

برای استفاده از Chrome's File System API، باید مجوز "fileSystem" را به مانیفست اضافه کنید تا بتوانید از کاربر اجازه ذخیره داده های پایدار را دریافت کنید.

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

گزینه های کاربر برای انتخاب فایل ها

کاربران انتظار دارند فایل ها را به همان روشی که همیشه انتخاب می کنند انتخاب کنند. حداقل، آنها انتظار یک دکمه انتخاب فایل و انتخاب کننده فایل استاندارد دارند. اگر برنامه شما به شدت از انتقال فایل استفاده می کند، باید کشیدن و رها کردن را نیز اجرا کنید (به زیر مراجعه کنید و همچنین Native HTML5 Drag and Drop را بررسی کنید).

به دست آوردن مسیر یک fileEntry

برای دریافت مسیر کامل فایلی که کاربر انتخاب کرده است، fileEntry ، getDisplayPath() را فراخوانی کنید:

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

پیاده سازی کشیدن و رها کردن

اگر نیاز به اجرای انتخاب کشیدن و رها کردن دارید، کنترل‌کننده فایل کشیدن و رها کردن ( dnd.js ) در نمونه دسترسی به فایل سیستم نقطه شروع خوبی است. کنترلر یک ورودی فایل را از 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);
});

کد زیر یک فایل جدید با قابلیت "Save as" ایجاد می کند و با استفاده از متد writer.write() blob جدید را در فایل می نویسد.

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 Sync Filesystem API

با استفاده از ذخیره‌سازی فایل قابل همگام‌سازی، اشیاء داده بازگشتی را می‌توان به همان روشی که سیستم‌های فایل آفلاین محلی در FileSystem API انجام می‌دهند، اما با همگام‌سازی (و خودکار) آن داده‌ها در Google Drive.

اضافه کردن مجوز سیستم فایل همگام سازی

برای استفاده از Chrome's Sync Filesystem API، باید مجوز «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' . "Synced" به این معنی است که فایل به طور کامل همگام شده است. هیچ تغییر محلی معلقی وجود ندارد که با 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);
      }
    }
  }
});

بررسی استفاده از API

برای بررسی میزان داده‌هایی که توسط API استفاده می‌شود، دایرکتوری Sandboxed محلی برنامه یا بایت‌های استفاده برگردانده شده توسط syncFileSystem.getUsageAndQuota را جستجو کنید: 

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

همچنین می توانید به فضای ذخیره سازی سرویس پشتیبان همگام سازی کاربر (در Google Drive) نگاه کنید. فایل‌های همگام‌سازی‌شده در پوشه Google Drive مخفی، Chrome Syncable FileSystem ذخیره می‌شوند. پوشه در لیست «درایو من» شما نشان داده نمی‌شود، اما می‌توانید با جستجوی نام پوشه در کادر جستجو به آن دسترسی پیدا کنید. (توجه داشته باشید که چیدمان پوشه راه دور تضمین نمی شود که بین نسخه ها سازگار با عقب بماند.)