الفرق بين المراجعتين ل"Cordova/cordova plugin file"
سطر 632: | سطر 632: | ||
=== الكتابة في ملف === | === الكتابة في ملف === | ||
− | بمجرد | + | بمجرد الحصول على الكائن <code>FileEntry</code>، يمكنك الكتابة في الملف عن طريق استدعاء التابع <code>createWriter</code>، والذي يعيد كائنًا <code>FileWriter</code> في دالة النجاح (success callback). |
+ | |||
+ | استدع التابع <code>write</code> الخاص بالكائن <code>FileWriter</code> للكتابة في الملف. | ||
<syntaxhighlight lang="javascript">function writeFile(fileEntry, dataObj) { | <syntaxhighlight lang="javascript">function writeFile(fileEntry, dataObj) { | ||
− | // | + | // (log.txt) FileEntry لأجل الكائن FileWriter انشاء |
fileEntry.createWriter(function (fileWriter) { | fileEntry.createWriter(function (fileWriter) { | ||
fileWriter.onwriteend = function() { | fileWriter.onwriteend = function() { | ||
سطر 643: | سطر 645: | ||
console.log("Failed file write: " + e.toString()); | console.log("Failed file write: " + e.toString()); | ||
}; | }; | ||
− | // | + | // dataObj في حال عدم تمرير كائن البيانات |
− | // | + | // جديد Blob أنشئ كائن. |
if (!dataObj) { | if (!dataObj) { | ||
dataObj = new Blob(['some file data'], { type: 'text/plain' }); | dataObj = new Blob(['some file data'], { type: 'text/plain' }); | ||
سطر 652: | سطر 654: | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
− | == قراءة | + | === قراءة ملف === |
− | تحتاج إلى كائن FileEntry لقراءة ملف موجود. استخدم الخاصية file في الكائن FileEntry للحصول على مرجع الملف، ثم أنشئ كائنًا جديدًا من النوع FileReader. يمكنك استخدام توابع مثل <code>readAsText</code> لبدء عملية القراءة. عند اكتمال عملية القراءة، | + | تحتاج إلى كائن <code>FileEntry</code> لقراءة ملف موجود. استخدم الخاصية <code>file</code> في الكائن <code>FileEntry</code> للحصول على مرجع الملف، ثم أنشئ كائنًا جديدًا من النوع <code>FileReader</code>. يمكنك استخدام توابع مثل التابع <code>readAsText</code> لبدء عملية القراءة. |
+ | |||
+ | عند اكتمال عملية القراءة، ستخزن الخاصية <code>this.result</code> نتيجة عملية القراءة. | ||
<syntaxhighlight lang="javascript">function readFile(fileEntry) { | <syntaxhighlight lang="javascript">function readFile(fileEntry) { | ||
fileEntry.file(function (file) { | fileEntry.file(function (file) { | ||
سطر 666: | سطر 670: | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
− | == | + | === إضافة محتوى إلى ملف باستخدام توابع بديلة === |
− | + | ستحتاج غالبًا إلى إضافة محتوًى إلى الملفات الموجودة بدلاً من إنشاء ملفات جديدة. إليك مثالًا على ذلك. | |
+ | |||
+ | يوضح هذا المثال طريقة أخرى يمكنك من خلالها الوصول إلى نظام الملفات باستخدام <code>window.resolveLocalFileSystemURL</code>. في هذا المثال، قم بتمرير عنوان الملف المستقل عن المنصات <code>cordova.file.dataDirectory</code> إلى الدالة. تتلقى دالة النجاح (success callback) كائنًا <code>DirectoryEntry</code>، والذي يمكنك استخدامه للقيام بعدة أمورـ مثل إنشاء ملفٍ. | ||
<syntaxhighlight lang="javascript">window.resolveLocalFileSystemURL(cordova.file.dataDirectory, function (dirEntry) { | <syntaxhighlight lang="javascript">window.resolveLocalFileSystemURL(cordova.file.dataDirectory, function (dirEntry) { | ||
console.log('file system open: ' + dirEntry.name); | console.log('file system open: ' + dirEntry.name); | ||
سطر 675: | سطر 681: | ||
}, onErrorLoadFs);</syntaxhighlight> | }, onErrorLoadFs);</syntaxhighlight> | ||
− | بالإضافة إلى | + | بالإضافة إلى هذا، يمكنك استخدام التابع <code>resolveLocalFileSystemURL</code> للوصول إلى بعض مواضع نظام الملفات التي لا تدخل في نظام التخزين المحصّن. راجع فقرة [[Cordova/cordova plugin file#.D9.85.D9.83.D8.A7.D9.86 .D8.AA.D8.AE.D8.B2.D9.8A.D9.86 .D8.A7.D9.84.D9.85.D9.84.D9.81.D8.A7.D8.AA .28Where to Store Files.29|مكان تخزين الملفات]] لمزيد من المعلومات؛ العديد من مواضع التخزين هذه مخصوصة بالمنصات. يمكنك أيضًا تمرير مواضع نظام ملفات مستقلة عن المنصات إلى التابع <code>resolveLocalFileSystemURL</code> باستخدام البروتوكول <code>cdvfile</code>. |
− | بالنسبة إلى عملية الإضافة (append)، لا يوجد شيء جديد في الدالة <code>createFile</code> التي | + | بالنسبة إلى عملية الإضافة (append)، لا يوجد شيء جديد في الدالة <code>createFile</code> التي استدعيناها في الشيفرة البرمجية السابقة (راجع الأمثلة السابقة لمطالعة الشيفرات الفعلية). حيث تستدعي <code>createFile</code> الدالة <code>writeFile</code>. عليك أن تتحقق في <code>writeFile</code> مما إذا كانت عملية الإضافة مطلوبة أم لا. |
− | بمجرد الحصول على كائن | + | بمجرد الحصول على كائن <code>FileWriter</code>، استدع التابع <code>seek</code>، ومرّر إليه فهرس الموضع الذي تريد الكتابة عنده. |
+ | |||
+ | في هذا المثال، سنتحقق أيضًا من وجود الملف. وبعد استدعاء التابع <code>seek</code>، سنستدع التابع <code>write</code> الخاصة بالكائن <code>FileWriter</code>. | ||
<syntaxhighlight lang="javascript">function writeFile(fileEntry, dataObj, isAppend) { | <syntaxhighlight lang="javascript">function writeFile(fileEntry, dataObj, isAppend) { | ||
− | // | + | // (log.txt) FileEntry لأجل الكائن FileWriter انشاء |
fileEntry.createWriter(function (fileWriter) { | fileEntry.createWriter(function (fileWriter) { | ||
fileWriter.onwriteend = function() { | fileWriter.onwriteend = function() { | ||
سطر 690: | سطر 698: | ||
console.log("Failed file read: " + e.toString()); | console.log("Failed file read: " + e.toString()); | ||
}; | }; | ||
− | // | + | // في حال إضافة بيانات إلى الملف، اذهب إلى نهاية الملف |
if (isAppend) { | if (isAppend) { | ||
try { | try { | ||
سطر 703: | سطر 711: | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
− | == تخزين ملف ثنائي موجود == | + | === تخزين ملف ثنائي موجود (Store an existing binary file ) === |
+ | |||
+ | سبق ووضحنا كيفية الكتابة في ملف أنشأته للتو في نظام الملفات المُحصّن. لكن ماذا لو احتجت إلى الوصول إلى ملف موجود، وأردت جعله قابلًا للتخزين على جهازك؟ في هذا المثال، ستحصل على ملف باستخدام طلبية xhr (xhr request)، ثم ستحفظه في ذاكرة التخزين المؤقت في نظام الملفات المُحصّنة. | ||
− | + | قبل الحصول على الملف، عليك الحصول أولًا على مرجع لكائن <code>FileSystem</code> باستخدام التابع <code>requestFileSystem</code>. مع إعطائه القيمة<code>window.TEMPORARY</code> (كما فعلنا من قبل)، يمثل الكائن <code>FileSystem</code> المعاد ذاكرة التخزين المؤقت في نظام االملفات المُحصّنة. | |
− | + | استخدم <code>fs.root</code> للحصول على الكائن <code>DirectoryEntry</code> الذي تحتاجه. | |
<syntaxhighlight lang="javascript">window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) { | <syntaxhighlight lang="javascript">window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) { | ||
console.log('file system open: ' + fs.name); | console.log('file system open: ' + fs.name); | ||
سطر 713: | سطر 723: | ||
}, onErrorLoadFs);</syntaxhighlight> | }, onErrorLoadFs);</syntaxhighlight> | ||
− | في الختام، إليك طلبية xhr للحصول على بقعة الصورة (Blob image). لا يوجد أي شيء خاص بكوردوفا في هذه الشيفرة، باستثناء أنك ستقوم | + | في الختام، إليك طلبية xhr للحصول على بقعة الصورة (Blob image). لا يوجد أي شيء خاص بكوردوفا في هذه الشيفرة، باستثناء أنك ستقوم بإعادة توجيه مرجع <code>DirectoryEntry</code> الذي حصلت عليه بالفعل كوسيط للدالة <code>saveFile</code>. سوف تقوم بحفظ بقعة الصورة (Blob image) وعرضها في وقت لاحق بعد قراءة الملف (للتحقق من صحة العملية). |
<syntaxhighlight lang="javascript">function getSampleFile(dirEntry) { | <syntaxhighlight lang="javascript">function getSampleFile(dirEntry) { | ||
var xhr = new XMLHttpRequest(); | var xhr = new XMLHttpRequest(); | ||
سطر 726: | سطر 736: | ||
xhr.send(); | xhr.send(); | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
− | ملاحظة: كجزء من إجراءات الأمان في كوردوفا 5، تتطلب الشيفرة السابقة إضافة اسم النطاق، http://cordova.apache.org، إلى العنصر Content-Security-Policy | + | '''ملاحظة''': كجزء من إجراءات الأمان في كوردوفا 5، تتطلب الشيفرة السابقة إضافة اسم النطاق، http://cordova.apache.org، إلى العنصر <code>Content-Security-Policy</code> في الملف <code>index.html</code>. |
− | في الملف index.html. | ||
− | بعد الحصول على الملف، انسخ المحتويات في ملف جديد. الكائن DirectoryEntry الحالي مرتبط بالفعل مع | + | بعد الحصول على الملف، انسخ المحتويات في ملف جديد. الكائن <code>DirectoryEntry</code> الحالي مرتبط بالفعل مع المخزن المؤقت (cache) للتطبيق. |
<syntaxhighlight lang="javascript">function saveFile(dirEntry, fileData, fileName) { | <syntaxhighlight lang="javascript">function saveFile(dirEntry, fileData, fileName) { | ||
dirEntry.getFile(fileName, { create: true, exclusive: false }, function (fileEntry) { | dirEntry.getFile(fileName, { create: true, exclusive: false }, function (fileEntry) { | ||
سطر 736: | سطر 745: | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
− | + | ستمرر كائن الملف Blob إلى الدالة <code>writeFile</code> باعتباره كائن البيانات <code>dataObj</code>، وستحفظه في الملف الجديد. | |
<syntaxhighlight lang="javascript">function writeFile(fileEntry, dataObj, isAppend) { | <syntaxhighlight lang="javascript">function writeFile(fileEntry, dataObj, isAppend) { | ||
− | // | + | // (log.txt) FileEntry لأجل الكائن FileWriter انشاء |
fileEntry.createWriter(function (fileWriter) { | fileEntry.createWriter(function (fileWriter) { | ||
fileWriter.onwriteend = function() { | fileWriter.onwriteend = function() { | ||
سطر 756: | سطر 765: | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
− | بعد الكتابة في الملف، اقرأه وقم بعرضه. | + | بعد الكتابة في الملف، اقرأه وقم بعرضه. وبما أنّك حفظت الصورة على هيئة بيانات ثنائية (binary data)، فيمكنك قراءتها باستخدام التابع FileReader.readAsArrayBuffer. |
<syntaxhighlight lang="javascript">function readBinaryFile(fileEntry) { | <syntaxhighlight lang="javascript">function readBinaryFile(fileEntry) { | ||
fileEntry.file(function (file) { | fileEntry.file(function (file) { | ||
سطر 770: | سطر 779: | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
− | بعد قراءة البيانات، يمكنك عرض الصورة باستخدام الشيفرة التالية. استخدم window.URL.createObjectURL للحصول على السلسلة النصية للشِّعب (DOM) الخاصة ببقعة الصورة (Blob image). | + | بعد قراءة البيانات، يمكنك عرض الصورة باستخدام الشيفرة التالية. استخدم <code>window.URL.createObjectURL</code> للحصول على السلسلة النصية للشِّعب (DOM) الخاصة ببقعة الصورة (Blob image). |
<syntaxhighlight lang="javascript">function displayImage(blob) { | <syntaxhighlight lang="javascript">function displayImage(blob) { | ||
− | // | + | // استخدم الصورة إن كانت النتيجة عبارة عن سلسلة نصية تمثل صورة صالحة في الشِّعب |
var elem = document.getElementById('imageFile'); | var elem = document.getElementById('imageFile'); | ||
− | // | + | // عند إنهاء الصورة window.URL.revokeObjectURL ملاحظة:استخدم |
elem.src = window.URL.createObjectURL(blob); | elem.src = window.URL.createObjectURL(blob); | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
− | == عرض ملف صورة == | + | === عرض ملف صورة === |
− | لعرض صورة باستخدام | + | لعرض صورة باستخدام <code>FileEntry</code>، يمكنك استدعاء التابع <code>toURL</code>. |
<syntaxhighlight lang="javascript">function displayImageByFileURL(fileEntry) { | <syntaxhighlight lang="javascript">function displayImageByFileURL(fileEntry) { | ||
var elem = document.getElementById('imageFile'); | var elem = document.getElementById('imageFile'); | ||
سطر 786: | سطر 795: | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
− | إن كنت تستخدم عناوين مخصوصة بمنصات معينة بدلاً من | + | إن كنت تستخدم عناوين مخصوصة بمنصات معينة بدلاً من <code>FileEntry</code>، وأردت عرض صورة، فقد تحتاج إلى تضمين الجزء الرئيسي من العنوان في العنصر <code>Content-Security-Policy</code> في الملف <code>index.html</code>. |
− | في الملف index.html. على سبيل المثال، في ويندوز 10، يمكنك تضمين <code>ms-appdata:</code> في | + | |
− | ذلك العنصر. | + | على سبيل المثال، في ويندوز 10، يمكنك تضمين <code>ms-appdata:</code> في ذلك العنصر. كما يوضح المثال التالي: |
<syntaxhighlight lang="javascript"><meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: ms-appdata: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *"></syntaxhighlight> | <syntaxhighlight lang="javascript"><meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: ms-appdata: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *"></syntaxhighlight> | ||
− | == إنشاء المجلدات == | + | === إنشاء المجلدات === |
− | في | + | في الشيفرة التالية، ستنشئ مجلدات في المجلد الجذري للمخزن (root storage location) الخاص بالتطبيق. يمكنك استخدام هذه الشيفرة مع أي موضع تخزين قابل للكتابة (<code>DirectoryEntry</code>). في هذا المثال، ستكتب في ذاكرة التخزين المؤقت للتطبيق (على افتراض أنك حصلت على الكائن <code>FileSystem</code> عبر <code>window.TEMPORARY</code> ) عن طريق تمرير <code>fs.root</code> إلى هذه الدالة. |
− | + | تنشئ هذه الشيفرة المجلد <code>/NewDirInRoot/images</code> في المخزن المؤقت للتطبيق (بخصوص القيم المخصوصة بمنصات معينة، راجع فقرة [[Cordova/cordova plugin file#.D8.A8.D9.86.D9.8A.D8.A7.D8.AA .D9.86.D8.B8.D8.A7.D9.85 .D8.A7.D9.84.D9.85.D9.84.D9.81.D8.A7.D8.AA .28File System Layouts.29|بنيات نظام الملفات]] أعلاه.) | |
<syntaxhighlight lang="javascript">function createDirectory(rootDirEntry) { | <syntaxhighlight lang="javascript">function createDirectory(rootDirEntry) { | ||
rootDirEntry.getDirectory('NewDirInRoot', { create: true }, function (dirEntry) { | rootDirEntry.getDirectory('NewDirInRoot', { create: true }, function (dirEntry) { | ||
سطر 805: | سطر 814: | ||
عند إنشاء مجلدات فرعية، عليك إنشاء كل مجلد على حدة كما هو موضح في الشيفرة البرمجية السابقة. | عند إنشاء مجلدات فرعية، عليك إنشاء كل مجلد على حدة كما هو موضح في الشيفرة البرمجية السابقة. | ||
+ | |||
+ | انظر أيضا | ||
+ | * [[Cordova/config ref|الملف Config.xml]] | ||
+ | |||
+ | * [[Cordova/plugins|دليل تطوير الإضافات في كوردوفا]] | ||
+ | |||
+ | * صفحة <nowiki/>[[Cordova/events|الأحداث]]. | ||
+ | |||
==مصادر== | ==مصادر== | ||
*[https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-file/index.html صفحة cordova-plugin-file في توثيق كوردوفا الرسمي.] | *[https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-file/index.html صفحة cordova-plugin-file في توثيق كوردوفا الرسمي.] |
مراجعة 17:15، 16 ديسمبر 2018
تقدم إضافة الملفات (cordova-plugin-file
) واجهة برمجية للملفات، والتي يمكن استخدامها للقراءة أو الكتابة في الملفات الموجودة على الجهاز.
هذه الإضافة مبنية على عدة مواصفات، بما فيها:
- الواجهة البرمجية للملفات في HTML5.
- المجلدات ونظام الملفات بُنِيا على هذه المواصفات. لكن تجدر الإشارة إلى أن معظم شيفرة الإضافة كُتِبت وفق مواصفات سابقة.
- تعتمد هذه الإضافة مواصفات الكائن FileWriter:
ملاحظة: رغم أن مواصفات W3C FileSystem صارت مُتجاوزة في متصفحات الويب، إلا أنّ كوردوفا تدعمها في هذه الإضافة في المنصات المدرجة في فقرة المنصات المدعومة، باستثناء المتصفحات (Browser).
لفهم كيفية استخدام هذه الإضافة، تحقق من المثال في أسفل هذه الصفحة. ولمزيد من الأمثلة (المرتكزة على المتصفحات)، يمكنك الاطلاع على هذا المقال الرائع حول FileSystem .
للتعرف على خيارات التخزين الأخرى، يرجى الرجوع إلى دليل التخزين.
تعرّف إضافة الملفات كائنًا عامًّا cordova.file
. وعلى الرغم من أنّ هذا الكائن موجود في النطاق العام (global scope)، إلا أنه لن يكون متوفرًا إلا بعد إطلاق الحدث deviceready
.
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
console.log(cordova.file);
}
التثبيت
يمكنك تثبيت هذه الإضافة عبر الأمر:
cordova plugin add cordova-plugin-file
المنصات المدعومة
- أندرويد
- iOS
- OS X
- ويندوز
- Browser
لا تدعم هذه المنصات التابعين FileReader.readAsArrayBuffer
أو FileWriter.write(blob)
.
مكان تخزين الملفات (Where to Store Files)
بدءًا من الإصدار 1.2.0، صار استخدام العناوين (URL) لمجلدات نظام الملفات المهمة متاحًا. العناوين تكون على الشكل: file:///path/to/spot/
، ويمكن تحويلها إلى كائنٍ DirectoryEntry
باستخدام التابع window.resolveLocalFileSystemURL()
.
cordova.file.applicationDirectory
- المجلد الذي ثُبِّت فيه التطبيق، وهو للقراءة فقط. (iOS، أندرويد، BlackBerry 10، OSX، ويندوز)cordova.file.applicationStorageDirectory
- المجلد الجذري لصندوق للتطبيق (application's sandbox)؛ على منصتي iOS وويندوز، يكون هذا المجلد للقراءة فقط (لكن بعض المجلدات الفرعية [مثل /Documents
في منصة iOS أو /localState
في ويندوز] قابلة للقراءة والكتابة معًا). جميع البيانات المضمنة داخل هذا المجلد ستبقى مخصوصة بالتطبيق. (iOS وأندرويد و BlackBerry 10 و OSX)cordova.file.dataDirectory
- مجلد لتخزين البيانات الدائمة والخاصة داخل صندوق التطبيق (application's sandbox) باستخدام الذاكرة الداخلية (على منصة أندرويد، إن كنت بحاجة إلى استخدام ذاكرة خارجية، فاستخدم .externalDataDirectory
). على منصة iOS، لا يُزامَن هذا المجلد مع السحابة iCloud (استخدم .syncedDataDirectory
). (ويندوز، أندرويد، iOS و BlackBerry 10)cordova.file.cacheDirectory
- مجلد للتخزين المؤقت لملفات البيانات، أو الملفات التي يمكن للتطبيق إعادة إنشائها بسهولة. قد يحذف نظام التشغيل هذه الملفات عندما يشعر بانحسار ذاكرة الجهاز، ولكن يجب ألا تعتمد التطبيقات على نظام التشغيل لحذف الملفات الموجودة في هذا المجلد. (iOS، أندرويد، BlackBerry 10، OSX، ويندوز)cordova.file.externalApplicationStorageDirectory
- مساحة التطبيق على وحدة التخزين الخارجية - external storage - (أندرويد)cordova.file.externalDataDirectory
- المجلد الذي ستوضع فيه ملفات البيانات الخاصة بالتطبيق على وحدة التخزين الخارجية. (أندرويد)cordova.file.externalCacheDirectory
- ذاكرة التخزين المؤقت للتطبيق في وحدة التخزين الخارجية. (أندرويد)cordova.file.externalRootDirectory
- المجلد الجذري (root) لوحدة التخزين الخارجية (بطاقة SD). (أندرويد، BlackBerry 10)cordova.file.tempDirectory
- مجلد يضم الملفات المؤقتة التي يمكن لنظام التشغيل مسحها في أي وقت. لا تعتمد على نظام التشغيل لمحو محتويات هذا المجلد. يجب أن يزيل تطبيقك دائمًا الملفات الموجودة في هذا التطبيق بحسب الاقتضاء. (iOS، OSX، ويندوز)cordova.file.syncedDataDirectory
- يحتوي هذا المجلد ملفات التطبيق التي يجب مزامنتها (مثلًا، مع السحابة iCloud). (ويندوز، iOS)cordova.file.documentsDirectory
- يضم هذا المجلد الملفات الخاصة بالتطبيق، والتي لها أهمية للتطبيقات الأخرى (مثل ملفات Office). لاحظ أنه في منصة OSX، هذا المجلد هو مجلد المستخدم ~/Documents
. (iOS، OSX)cordova.file.sharedDirectory
- يحتوي هذا المجلد على الملفات المتاحة لجميع التطبيقات (BlackBerry 10)
بنيات نظام الملفات (File System Layouts)
على الرغم من أن بنيات نظام الملفات من الناحية الفنية تُعد من تفاصيل التقديم (implementation)، إلا أنه قد يكون من المفيد معرفة كيفية الربط بين الخاصيات cordova.file.*
وبين المسارات الفعلية على الجهاز الحقيقي.
بنية نظام الملفات في منصة iOS
مسار الجهاز | cordova.file.*
|
iosExtraFileSystems
|
كتابة/قراءة؟ | مستمرة؟ | أيمحوه نظام التشغيل؟ | مزامنة | خاص |
---|---|---|---|---|---|---|---|
/var/mobile/Applications/<UUID>/
|
applicationStorageDirectory
|
-
|
ق | غ/م | غ/م | غ/م | نعم |
appname.app/
|
applicationDirectory
|
bundle
|
ق | غ/م | غ/م | غ/م | نعم |
www/
|
-
|
-
|
ق | غ/م | غ/م | غ/م | نعم |
Documents/
|
documentsDirectory
|
documents
|
ق/ك | نعم | لا | نعم | نعم |
NoCloud/
|
-
|
documents-nosync
|
ق/ك | نعم | لا | لا | نعم |
Library
|
-
|
library
|
ق/ك | نعم | لا | نعم؟ | نعم |
NoCloud/
|
dataDirectory
|
library-nosync
|
ق/ك | نعم | لا | لا | نعم |
Cloud/
|
syncedDataDirectory
|
-
|
ق/ك | نعم | لا | نعم | نعم |
Caches/
|
cacheDirectory
|
cache
|
ق/ك | نعم* | نعم*** | لا | نعم |
tmp/
|
tempDirectory
|
-
|
ق/ك | لا** | نعم*** | لا | نعم |
- غ/م => غير متوفر أو غير معروف.
*
=> ملفات تستمر في الذاكرة حتى بعد إعادة تشغيل التطبيق وترقيته، ولكن يمكن أن يمحو نظام التشغيل هذا المجلد في أي وقت. يجب أن يكون تطبيقك قادرًا على إعادة إنشاء أي محتوى مهدد بالحذف.
**
=> قد تستمر هذه الملفات عبر إعادة تشغيل التطبيق، ولكنّ ذلك ليس أكيدًا. لا يمكن ضمان استمرار هذه الملفات عبر التحديثات. يجب أن يزيل تطبيقك الملفات من هذا المجلد بنفسه، لأنّه لا توجد ضمانة على أنّ نظام التشغيل سيمحوا (أو متى يفعل ذلك) هذه الملفات.
***
=> قد يمحو نظام التشغيل محتويات هذا المجلد متى رأى أنّ ذلك ضروري، ولكن لا تعتمد على هذا السلوك. يجب عليك مسح هذا المجلد بما يتناسب مع تطبيقك.
بنية نظام الملفات في أندرويد
مسار الجهاز | cordova.file.*
|
AndroidExtraFileSystems
|
كتابة/قراءة؟ | مستمرة؟ | أيمحوه نظام التشغيل؟ | خاص |
---|---|---|---|---|---|---|
file:///android_asset/
|
applicationDirectory
|
assets
|
ق | غ/م | غ/م | نعم |
/data/data/<app-id>/
|
applicationStorageDirectory
|
-
|
ق/ك | غ/م | غ/م | نعم |
cache
|
cacheDirectory
|
cache
|
ق/ك | نعم | نعم* | نعم |
files
|
dataDirectory
|
files
|
ق/ك | نعم | لا | نعم |
Documents
|
-
|
documents
|
ق/ك | نعم | لا | نعم |
<sdcard>/
|
externalRootDirectory
|
sdcard
|
ق/ك | نعم | لا | لا |
Android/data/<app-id>/
|
externalApplicationStorageDirectory
|
-
|
ق/ك | نعم | لا | لا |
cache
|
externalCacheDirectory
|
cache-external
|
ق/ك | نعم | لا** | لا |
files
|
externalDataDirectory
|
files-external
|
ق/ك | نعم* | لا | لا |
- غ/م => غير متوفر أو غير معروف.
*
=> قد يمحو نظام التشغيل هذا المجلد بشكل دوري، ولكن لا تعتمد على هذا السلوك. امسح محتويات هذا المجلد بالشكل المناسب لتطبيقك. في حالة قيام المستخدم بمسح ذاكرة التخزين المؤقت يدويًا، ستزال محتويات هذا المجلد.
**
=> قلا يمحو نظام التشغيل هذا المجلد تلقائيًا؛ فأنت المسؤول عن إدارة محتويات المجلد بنفسك. عندما يمحو المستخدم ذاكرة التخزين المؤقت يدويا، ستزال محتويات هذا المجلد.
ملاحظة: إذا تعذر تركيب وحدة التخزين الخارجية، ستساوي الخاصيات cordova.file.external*
القيمة null
.
بنية نظام ملفات منصة OS X
مسار الجهاز | cordova.file.*
|
iosExtraFileSystems
|
كتابة/قراءة؟ | أيمحوه نظام التشغيل؟ | خاص |
---|---|---|---|---|---|
/Applications/<appname>.app/
|
-
|
bundle
|
ق | غ/م | نعم |
Content/Resources/
|
applicationDirectory
|
-
|
ق | غ/م | نعم |
~/Library/Application Support/<bundle-id>/
|
applicationStorageDirectory
|
-
|
ق/ك | لا | نعم |
files/
|
dataDirectory
|
-
|
ق/ك | لا | نعم |
~/Documents/
|
documentsDirectory
|
documents
|
ق/ك | لا | لا |
~/Library/Caches/<bundle-id>/
|
cacheDirectory
|
cache
|
ق/ك | لا | نعم |
/tmp/
|
tempDirectory
|
-
|
ق/ك | نعم* | نعم |
/
|
rootDirectory
|
root
|
ق/ك | لا** | لا |
ملاحظة: هذه هي البنية الخاصة بالتطبيقات غير المحصنة (non sandboxed applications). إذا قمت بتحصين (sandboxing) التطبيق، فسيصبح الملفapplicationStorageDirectory
داخل المجلد ~/Library/Containers/<bundle-id>/Data/Library/Application Support
.
*
= > ملفات تستمر بعد إعادة تشغيل التطبيق أو ترقيته، ولكن يمكن أن يمحو نظام التشغيل هذا المجلد في أي وقت. يجب أن يكون تطبيقك قادرًا على إعادة إنشاء أي محتوى قد يتم حذفه. يجب عليك مسح هذا المجلد بنفسك بما يلائم تطبيقك.
**
=> يتيح الوصول إلى نظام الملفات بأكمله. وهذا غير متوفر إلا للتطبيقات غير المحصنة.
بنية نظام ملفات ويندوز
مسار الجهاز | cordova.file.*
|
كتابة/قراءة؟ | أمستمر؟ | أيمحوه نظام التشغيل؟ | خاص |
---|---|---|---|---|---|
ms-appdata:///
|
applicationDirectory
|
ق | غ/م | غ/م | نعم |
local/
|
dataDirectory
|
ق/ك | غ/م | لا | نعم |
temp/
|
cacheDirectory
|
ق/ك | لا | نعم* | نعم |
temp/
|
tempDirectory
|
ق/ك | لا | نعم* | نعم |
roaming/
|
syncedDataDirectory
|
ق/ك | لا | لا | نعم |
*
=> قد يمحو نظام التشغيل هذا المجلد دوريًا
ملاحظات خاصة بمنصة أندرويد
موضع التخزين الدائم في أندرويد
هناك عدة مواضع صالحة لتخزين الملفات بشكل دائم على أجهزة أندرويد . راجع هذه الصفحة لمعلومات مفصلة بخصوص مختلف إمكانيات التخزين المتاحة.
كانت الإصدارات السابقة من هذه الإضافة تختار موضع الملفات المؤقتة والمستمرة (persistent) عند بدء التشغيل، بحسب ما إذا تم تركيب بطاقة الذاكرة SD (أو أي أداة تخزين مكافئة) على الجهاز أم لا. إن رُكِّبت بطاقة الذاكرة SD، أو إن توفرت مساحة تخزين داخلية (على أجهزة Nexus مثلاً)، فستُخزّن الملفات المستقرة في المجلد الجذري لتلك المساحة. هذا يعني أن جميع تطبيقات كورودوفا ستكون قادرة على رؤية جميع الملفات المتوفرة على البطاقة.
في الإصدارات السابقة، إذا لم تكن بطاقة الذاكرة SD متوفرة، فستُخزّن البيانات ضمن المجلد /data/data/<packageId>
، والذي يعزل التطبيقات عن بعضها البعض، ولكن قد يسمح بتشارك البيانات بين المستخدمين.
من الممكن الآن الاختيار بين تخزين الملفات في وحدة التخزين الداخلية (internal storage)، أو استخدام المقاربة السابقة، يمكنك فعل هذا عبر الوسم preference
في الملف config.xml
. عبر إضافة أحد هذين السطرين إليه:
<preference name="AndroidPersistentFileLocation" value="Internal" />
<preference name="AndroidPersistentFileLocation" value="Compatibility" />
بدون هذا السطر، ستستخدم إضافة الملفات القيمة Internal
كإعداد افتراضي. وفي حال كان الوسم preference
حاضرًا، ولم تكن له إحدى هذه القيم، فلن يعمل التطبيق.
إذا سبق وأرسلت تطبيقك إلى المستخدمين باستخدام إصدار قديم (قبل الإصدار 3.0.0) من هذه الإضافة، وكان التطبيق قد خزّن الملفات في نظام الملفات الدائمة (persistent filesystem)، فيجب إعطاء الوسم preference
القيمة Compatibility
إذا لم يحدد الملف config.xml
موضع نظام الملفات الدائمة. قد يؤدي تبديل موضع التخزين وجعله "داخليا" (Internal
) إلى عدم استطاعة المستخدمين الحاليين الذين يقومون بترقية تطبيقاتهم من الوصول إلى ملفاتهم المخزنة مسبقًا، وذلك اعتمادًا على الجهاز المستخدم.
إذا كان تطبيقك جديدًا، أو لم يسبق له تخزين الملفات في نظام الملفات الدائمة، فيفضل عمومًا استخدام الإعداد Internal
.
العمليات العودية البطيئة على المجلد /android_asset
العمل على مجلدات الأصول (asset directories) بطيئة جدا في أندرويد. يمكنك تسريع ذلك عن طريق إضافة src/android/build-extras.gradle
إلى جذر مشروع أندرويد (يتطلب الإصدار cordova-android@4.0.0 أو ما بعده).
الإذن في الكتابة في وحدة التخزين الخارجية عندما لا تكون مُركّبة في منصة Marshmallow
تتطلب منصة Marshmallow أن تستأذن التطبيقات قبل القراءة أو الكتابة في المواضع الخارجية. افتراضيًا، يملك تطبيقك الإذن في الكتابة في cordova.file.applicationStorageDirectory
و cordova.file.externalApplicationStorageDirectory
، ولن يكون على الإضافة طلب إذن للكتابة في هذين المجلدين إلا إذا لم تُركّب وحدة تخزين خارجية. وفي هذه الحالة، فستطلب الإضافة الإذن للكتابة في cordova.file.externalApplicationStorageDirectory
.
ملاحظات خاصة بمنصة IOS
cordova.file.applicationStorageDirectory
للقراءة فقط؛ ستفشل أي محاولة لتخزين الملفات داخل المجلد الجذري. استخدم أحد الخاصياتcordova.file.*
الأخرى المحددة لأجل منصة iOS (وحدهما المجلدانapplicationDirectory
وapplicationStorageDirectory
للقراءة فقط).FileReader.readAsText(blob, encoding)
- المعامل
encoding
غير مدعوم، والترميز UTF-8 هو المعتمد دائمًا.
موضع التخزين الدائم في منصة iOS
هناك موضعان يصلحان لتخزين الملفات الدائمة على جهاز iOS: مجلد المستندات (Documents directory) ومجلد المكتبة (Library directory). الإصدارات السابقة من الإضافة كانت تخزّن الملفات الدائمة حصرًا في مجلد المستندات. وهذا جعل جميع ملفات التطبيق مرئية في تطبيق iTunes، وهو ما لم يكن مقصودًا غالبًا، خاصة للتطبيقات التي تتعامل مع الكثير من الملفات الصغيرة، بدلاً من إنتاج مستندات كاملة لتصديرها، وهو الغرض المقصود من المجلد.
من الممكن الآن اختيار تخزين الملفات في مجلد المستندات أو مجلد المكتبة، عبر الوسم preference
في الملف config.xml
الخاص بتطبيقك. عبر إضافة أحد هذين السطرين إلى config.xml
:
<preference name="iosPersistentFileLocation" value="Library" />
<preference name="iosPersistentFileLocation" value="Compatibility" />
بدون هذا السطر، ستستخدم الإضافة Compatibility
كإعداد افتراضي. في حال كان الوسم preference
حاضرًا، ولم يكن يساوي إحدى هذه القيم، فلن يعمل التطبيق.
إن سبق وأرسلت تطبيقك إلى المستخدمين باستخدام إصدار قديم (قبل الإصدار 1.0) من هذه الإضافة، وكان قد خزّن الملفات في نظام الملفات الدائمة، فعليك إعطاء الوسم preference
القيمة Compatibility
. تحويل الموضع إلى المكتبة (Library
) يعني أن المستخدمين الحاليين الذين يقومون بترقية تطبيقاتهم لن يتمكنوا من الوصول إلى ملفاتهم المخزنة مسبقًا.
إن كان تطبيقك جديدًا، أو لم يسبق له تخزين الملفات في نظام الملفات الدائمة، فيفضل عمومًا استخدام الإعداد Library
.
ملاحظات خاصة بالمتصفحات (Browsers)
ملاحظات خاصة وتوضيحات
- يستخدم كل متصفح نظام ملفات محصّن (sandboxed) خاص به. يستخدم المتصفحان IE و فايرفوكس الواجهة البرمجية IndexedDB. كما تستخدم جميع المتصفحات عارضة مائلة للأمام ("
/
") كفاصلة داخل المسار. - يجب إنشاء مدخلات المجلد بالتتابع. على سبيل المثال، سيفشل استدعاء التابع
fs.root.getDirectory('dir1/dir2', {create:true}, successCallback, errorCallback)
إذا لم يكن المجلدdir1
موجودًا. - تستأذن الإضافة من المستخدم لاستخدام التخزين الدائم عند بدء التطبيق لأول مرة.
- تدعم الإضافة
cdvfile://localhost
(الموارد المحلية) فقط. أي أنّ البروتوكولcdvfile
لا يدعم الموارد الخارجية. - لا تتقيّد الإضافة "بتسميات الواجهة البرمجية لنظام الملفات 8.3".
- الكائن Blob و التابع
close
غير مدعومان. - لا تدعم هذه الإضافة
FileSaver
وBlobBuilder
، وليس لهما أكواد مُجتزأة (stubs). - الإضافة لا تدعم الدالة
requestAllFileSystems
. هذه الدالة غير موجودة في المواصفات أيضًا. - لن تُزال المُدخلات (Entries) من المجلد إن كنت تستخدم الراية
create: true
مع مجلد موجود. - الملفات المُنشأة عبر الباني (constructor) ليست مدعومة. عليك استخدام التابع
entry.file
بدلاً من ذلك. - يستخدم كل متصفح شكلًا خاصًا من عناوين blob.
- الدالة
readAsDataURL
مدعومة، لكنّ نوع الوسيطmediatype
في متصفح كروم يعتمد على امتداد اسم المُدخلات (entry name extension)، نوع الوسيطmediatype
في المتصفح IE يكون دائمًا فارغًا (وهو أمر مماثل لـtext-plain
وفقًا للمواصفات)، أما في متصفح فايرفوكس فإنّ نوع الوسيطmediatype
يساوي دائمًاapplication/octet-stream
. على سبيل المثال، إن كان المحتوى هوabcdefg
، فحينئذٍ سيعيد فايرفوكس القيمةdata:application/octet-stream;base64,YWJjZGVmZw==
، وسيعيد المتصفح IE القيمةdata:;base64,YWJjZGVmZw==
، فيما سيعيد المتصفح كروم القيمةdata:<mediatype depending on extension of entry name>;base64,YWJjZGVmZw==
. - تُعيد الخاصية
toInternalURL
المسار وفق الصيغةfile:///persistent/path/to/entry
(على فايرفوكس و IE). فيما يعيد كروم المسار وفق الصيغةcdvfile://localhost/persistent/file
.
ملاحظات خاصة بمتصفح كروم
- نظام الملفات في متصفح كروم لا يكون جاهزًا فور إطلاق الحدث
deviceready
. كحل بديل، يمكنك الاشتراك في الحدثfilePluginIsReady
. مثال:
window.addEventListener('filePluginIsReady', function(){ console.log('File plugin is ready');}, false);
يمكنك استخدام الدالة window.isFilePluginReadyRaised
للتحقق مما إن كان الحدث قد أُطلِق بالفعل.
- حصة نظامي الملفات
window.requestFileSystem
المؤقت (TEMPORARY) والدائم (PERSISTENT) غير محدودة في متصفح كروم. - لزيادة سعة التخزين الدائم (persistent storage) في كروم، يلزمك استدعاء التابع
window.initPersistentFileSystem
. افتراضيًا، تبلغ حصة التخزين الدائم 5 ميغابايت. - يتطلب كروم تمرير الوسيط
--allow-file-access-from-files
إلى الأمرrun
لدعم الواجهة البرمجية (API) عبر البروتوكولfile:///
. - لن يُغيّر الكائن
File
إن كنت تستخدم الراية{create:true}
عند الحصول على مدخلEntry
موجود. - تُضبط خاصية الأحداث
cancelable
عند القيمةtrue
في متصفح كروم. على خلاف ما تقوله المواصفات. - تعيد الدالة
toURL
في كروم مسارًا مسبوقا بالبادئةfilesystem:
بناءً على التطبيق المُضيف. مثل:filesystem:file:///persistent/somefile.txt
وfilesystem:http://localhost:8080/persistent/somefile.txt
.
- لا تحتوي نتيجة الدالة
toURL
على شرطة مائلة في حالةdirectoryEntry
. مع ذلك، يحُل كروم المجلدات ذات العناوين (url) التي تنتهي بشرطة مائلة بشكلٍ صحيح. - يتطلب التابع
resolveLocalFileSystemURL
أن يبدأ العنوان الخلفي بالبادئةfilesystem
. على سبيل المثال، يجب أن يكون المعاملurl
الخاص بالتابعresolveLocalFileSystemURL
مكتوبًا وفق الصيغةfilesystem:file:///persistent/somefile.txt
بدلاً من الصيغةfile:///persistent/somefile.txt
المعمول بها في أندرويد. - الدالة
toNativeURL
ليست مدعومة، وليس لديها شيفرة مجتزأة (stub). - الدالة
setMetadata
ليست مذكورة في المواصفات وليست مدعومة. - يُطلق الخطأ
INVALIDMODIFICATIONERR
(الكود: 9) بدلاً من الخطأSYNTAX_ERR
(الكود: 8) عند طلب (requesting) نظام ملفات غير موجود. - يُطلق الخطأ
INVALIDMODIFICATIONERR
(الكود: 9) بدلاً من الخطأPATHEXISTSERR
(الكود: 12) عند محاولة إنشاء ملف أو مجلد موجود مسبقاً. - يُطلق الخطأ
INVALIDMODIFICATIONERR
(الكود: 9) بدلاً من الخطأNOMODIFICATIONALLOWED_ERR
(الكود: 6) عند محاولة استدعاءremoveRecursively
على المجلد الجذري (root) لنظام الملفات. - يُطلق الخطأ
INVALIDMODIFICATIONERR
(الكود: 9) بدلاً من الخطأNOTFOUNDERR
(الكود: 1) عند محاولة الانتقال إلى مجلد غير موجود.
ملاحظات خصاصة بالمنصات التي تستخدم IndexedDB
(فايرفوكس و IE)
- الصيغتان
.
و..
غير مدعومتان. - لا يدعم المتصفح IE العناوين
file:///
؛ ولكن يدعم الوضع المستضاف فقط (http://localhost:xxxx). - حجم نظام الملفات في فايرفوكس غير محدود، ولكن عند كل تمديد للمساحة بـ 50 ميغابايت، فسيُطلب إذن المستخدم. يتيح المتصفح IE10 إلى حدود 10 ميغابايت من الذاكرتين AppCache و IndexedDB المُستخدمتين في نظام الملفات دون المطالبة بالإذن، وبمجرد أن تصل إلى هذا المستوى، سيُطلب منك الإذن بزيادة هذا الحجم إلى 250 ميغابايت كحد أقصى لكل موقع. لذلك لا يؤثر المعامل
size
الخاص بالدالةrequestFileSystem
على نظام الملفات في المتصفحين فايرفوكس و IE. - الدالة
readAsBinaryString
لم تُذكر في المواصفات، وليست مدعومة في المتصفح IE وليس لها جذع (stub). - الخاصية
file.type
تساوي دائماnull
. - عليك ألا تنشئ مُدخلات (entries) باستخدام نتيجة دالة الاستجابة (callback) الخاصة بنسخة
DirectoryEntry
المحذوفة. وإلا فستحصل على مُدخلة مُعلّقة (hanging entry). - قبل أن تتمكن من قراءة ملف مكتوب للتّو، عليك أن تحصل أولا على نسخة جديدة من ذلك الملف.
- الدالة
setMetadata
، والتي لم تُذكر في المواصفات، تدعم تغيير الحقلmodificationTime
فقط. - لا تدعم الدالتان
copyTo
وmoveTo
المجلدات. - البيانات الوصفية (metadata) للمجلدات غير مدعومة.
- لا يفشل التابعان
Entry.remove
وdirectoryEntry.removeRecursively
عند إزالة المجلدات غير الفارغة - إذ يمحوان المجلدات المُزالة مع محتوياتها. - الدالتان
abort
وtruncate
غير مدعومتان. - لا يتم إطلاق أحداث التقدم (progress events). على سبيل المثال، لن يُنفّذ معالج الأحداث التالي:
javascript
writer.onprogress = function() { /*commands*/ };
ملاحظات حول الترقية
في الإصدار 1.0.0 من هذه الإضافة، تغيرت بِنيتَا الكائنينFileEntry
و DirectoryEntry
، لتكونا أكثر انسجاما مع المواصفات المنشورة.
الإصدارات السابقة (قبل 1.0.0) من الإضافة كانت تُخزن device-absolute-file-location
في الخاصية fullPath
في الكائن Entry
. هذه المسارات تبدو عادة كالتالي:
/var/mobile/Applications/<application UUID>/Documents/path/to/file (iOS)
/storage/emulated/0/path/to/file (Android)
تُعاد هذه المسارات أيضًا من قبل التابع toURL()
الخاص بالكائن Entry
.
في الإصدار 1.0.0، صارت الخاصية fullPath
تمثل مسار الملف نسبةً إلى المجلد الجذري لنظام ملفات HTML. لذلك، فالمسارات المذكورة أعلاه سيمثّلها الآن الكائن FileEntry
كمسار كامل (fullPath)
على النحو التالي:
/path/to/file
إن كان تطبيقك يعمل مع device-absolute-paths
، وقمت سابقًا باسترداد هذه المسارات عبر الخاصية fullPath
من كائنات Entry
، فعليك تحديث شيفرتك البرمجية لاستخدام entry.toURL()
بدلاً من ذلك.
للتوافق مع الإصدارات القديمة، سيقبل التابع resolveLocalFileSystemURL()
المعامل device-absolute-path
، وسيُعيد كائنًا Entry
مقابلًا له، طالما أنّ الملف موجود داخل أحد نظامي الملفات المؤقتة (TEMPORARY
) أو المستمرة (PERSISTENT)
.
كانت هذه مشكلة خاصة بالإضافة File-Transfer، إذ كانت تستخدم سابقًا مسارات مطلقة للجهاز device-absolute-paths
(ولا تزال تقبلها). وقد تم تحديثها لتعمل بشكل صحيح مع روابط نظام الملفات (FileSystem
URLs)، لذلك، فاستبدال entry.fullPath
بـ entry.toURL()
سيحل أية مشاكل قد تواجه الإضافة فيما يخص العمل على الملفات الموجودة على الجهاز.
في الإصدار 1.1.0، تم تغيير القيمة المعادة من الدالة toURL()
(انظر الصفحة CB-6394)، إذ باتت تعيد الرابط المطلق "file://
" ما أمكن. للحصول على رابط داخلي 'cdvfile:
'، يمكنك استخدام التابع toInternalURL()
. والذي سيعيد الآن عناوين نظام الملفات وفق الصيغة التالية:
cdvfile://localhost/persistent/path/to/file
والتي يمكن استخدامها لتحديد الملف بدقة.
البروتوكول cdvfile
الهدف
يمكن استخدام cdvfile://localhost/persistent|temporary|another-fs-root*/path/to/file
في مسارات الملفات المستقلة عن المنصات (platform-independent). المسارات cdvfile
مدعومة من قبل الإضافات الأساسية (core plugins)، فعلى سبيل المثال، يمكنك تنزيل ملف mp3 إلى مسار cdvfile
عبر الإضافة cordova-plugin-file-transfer
ثم تشغيله عبر الإضافة cordova-plugin-media
.
ملاحظة: راجع الفقرات مكان تخزين الملفات وبنيات نظام الملفات وتعديل إعددات الإضافة لمزيد من التفاصيل حول جذور نظام الملفات المتاحة.
لاستخدام cdvfile
كخاصية وَسْمِية src
، يمكنك تحويلها إلى مسار أصلي عبرالتابع toURL()
الخاص بالكائن fileEntry
الناتج، والذي يمكنك الحصول عليه عبر resolveLocalFileSystemURL
- راجع الأمثلة أدناه.
يمكنك أيضًا استخدام المسارات cdvfile://
مباشرةً داخل الشِّعب (DOM)، على سبيل المثال:
<img src="cdvfile://localhost/persistent/img/logo.png" />
ملاحظة: يتطلب هذا التابع تحديثات الأمان التالية:
- أضف
cdvfile:
إلى الوسم الوصفيContent-Security-Policy
في صفحة الفهرس، على سبيل المثال:
<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap:cdvfile:https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">
- أضف
<access origin="cdvfile://*" />
إلىconfig.xml
.
تحويل cdvfile://
إلى مسار أصلي:
resolveLocalFileSystemURL('cdvfile://localhost/temporary/path/to/file.mp4', function(entry) {
var nativePath = entry.toURL();
console.log('Native URI: ' + nativePath);
document.getElementById('video').src = nativePath;
تحويل مسار أصلي إلى cdvfile://
:
resolveLocalFileSystemURL(nativePath, function(entry) {
console.log('cdvfile URI: ' + entry.toInternalURL());
استخدام cdvfile://
في الإضافات الأساسية:
fileTransfer.download(uri, 'cdvfile://localhost/temporary/path/to/file.mp3', function (entry) { ...
var my_media = new Media('cdvfile://localhost/temporary/path/to/file.mp3', ...);
my_media.play();
ملاحظات خاصة بالبروتوكول cdvfile
- استخدام مسارات
cdvfile://
في الشِّعب (DOM) غير مدعوم في منصة ويندوز (يمكن تحويل المسار إلى مسار أصلي لتجاوز ذلك).
لائحة أكواد الأخطاء ومعانيها
عند إطلاق خطأ، سيتم استخدام أحد الأكواد التالية:
كود الخطأ | الثابتة |
---|---|
1
|
NOT_FOUND_ERR
|
2
|
SECURITY_ERR
|
3
|
ABORT_ERR
|
4
|
NOT_READABLE_ERR
|
5
|
ENCODING_ERR
|
6
|
NO_MODIFICATION_ALLOWED_ERR
|
7
|
INVALID_STATE_ERR
|
8
|
SYNTAX_ERR
|
9
|
INVALID_MODIFICATION_ERR
|
10
|
QUOTA_EXCEEDED_ERR
|
11
|
TYPE_MISMATCH_ERR
|
12
|
PATH_EXISTS_ERR
|
تعديل إعدادات الإضافة (اختياري)
يمكن تعديل إعدادات أنظمة الملفات المتاحة لكل منصة على حدة. تتعرف المنصتان iOS و أندرويد على وسم في الملف config.xml
، والذي يحتوي أسماء أنظمة الملفات المراد تثبيتها. افتراضيًا، يتم تمكين كل جذور (roots) نظام الملفات.
<preference name="iosExtraFilesystems" value="library,library-nosync,documents,documents-nosync,cache,bundle,root" />
<preference name="AndroidExtraFilesystems" value="files,files-external,documents,sdcard,cache,cache-external,assets,root" />
أندرويد
files
: مجلد التخزين الداخلي للملفاتfiles-external
: مجلد التخزين الخارجي للملفاتsdcard
: مجلد التخزين الخارجي العام للملفات - global external file storage - (والذي يساوي جذر بطاقة الذاكرة SD، إن كانت مُركّبة). يجب أن يكون لديك الإذنandroid.permission.WRITE_EXTERNAL_STORAGE
لاستخدامه.cache
: مجلد التخزين المؤقت الداخلي للتطبيقcache-external
: مجلد التخزين المؤقت الخارجي للتطبيقassets
: حزمة (bundle) التطبيق (للقراءة فقط)root
: نظام ملفات الجهاز بأكمله
يدعم أندرويد أيضًا نظام ملفات خاص باسم "documents
"، والذي يمثل مجلداً فرعيًا "/Documents/
" داخل نظام الملفات "files
".
iOS
library
: مجلد مكتبة التطبيقdocuments
: مجلد مستندات (Documents) التطبيقcache
: مجلد ذاكرة التخزين المؤقت للتطبيقbundle
: حزمة التطبيق، وهو موضع التطبيق نفسه على القرص (للقراءة فقط)root
: نظام ملفات الجهاز بأكمله
افتراضيًا، يمكن مزامنة مجلدي المستندات (documents) والمكتبة (library) مع السحابة iCloud. يمكنك أيضًا طلب (request) نظامي ملفات إضافيين، وهما library-nosync
و documents-nosync
، واللذان يمثلان مجلدًا خاصًا غير متزامن داخل نظام الملفات /Library
أو /Documents
.
مثال توضيحي
تتيح لك إضافة الملفات (File) تنفيذ العديد من الأشياء، مثل تخزين الملفات في موقع تخزين مؤقت أو دائم لأجل استخدامه من قبل تطبيقك (تخزين مُحصّن [sandboxed storage])، أو تخزين الملفات في مواقع أخرى بحسب المنصة المُستخدمة.
توضح الشيفرات البرمجية في هذا القسم بعض هذه الأمور، مثل:
إنشاء ملف دائم
قبل استخدام الواجهات البرمجية لإضافة الملفات، يمكنك الوصول إلى نظام الملفات باستخدام requestFileSystem
. عند القيام بذلك، يمكنك طلب استخدام التخزين الدائم أو المؤقت. حيث لن يُزال التخزين الدائم إلا بإذن المستخدم.
عندما تحصل على إذن الوصول إلى نظام الملفات عبر requestFileSystem
، يُمنح إذن الوصول لنظام الملفات المحصّن (sandboxed) فقط (يقصُر وضع التحصين [sandbox] حق الوصول على التطبيق وحده)، ولا يمنح حق الوصول العام إلى أي موضع في نظام الملفات على الجهاز. (للوصول إلى مواضع نظام الملفات الواقعة خارج المخزن المُحصّن، استخدم توابع أخرى مثل التابع window.resolveLocalFileSystemURL
، والذي يدعم المواضع المخصوصة بمنصات معينة. لمثال على ذلك، انظر أدناه فقرة الإضافة في ملف.)
في هذا المثال تجد طلبًا للتخزين المستمر.
ملاحظة: عند استهداف عملاء العارض WebView (بدلاً من المتصفح) أو التطبيقات الأصلية (ويندوز)، فلا تحتاج إلى استخدام requestQuota
قبل استخدام التخزين الدائم.
window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, function (fs) {
console.log('file system open: ' + fs.name);
fs.root.getFile("newPersistentFile.txt", { create: true, exclusive: false }, function (fileEntry) {
console.log("fileEntry is file?" + fileEntry.isFile.toString());
// fileEntry.name == 'someFile.txt'
// fileEntry.fullPath == '/someFile.txt'
writeFile(fileEntry, null);
}, onErrorCreateFile);
}, onErrorLoadFs);
تتلقى دالة النجاح (success callback) كائنًا FileSystem
. إن أردت إعادة كائنٍ DirectoryEntry
، فاستخدم fs.root
، والذي يمكنك استخدامه لإنشاء أو الحصول على ملف (عن طريق استدعاء التابع getFile
). يمثل fs.root
في هذا المثال كائنًا DirectoryEntry
، والذي يمثل التخزين الدائم في نظام الملفات المُحصّن (sandboxed file system).
تتلقى دالة النجاح (success callback) الخاصة بالتابع getFile
كائناً FileEntry
. والذي يمكنك استخدامه لتنفيذ عمليات الكتابة والقراءة على الملف.
إنشاء ملف مؤقت
في ما يلي مثال لطلب تخزينٍ مؤقت. تذكر أنه قد يتم حذف التخزين المؤقت من قبل نظام التشغيل في حال انحسار ذاكرة الجهاز.
window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
console.log('file system open: ' + fs.name);
createFile(fs.root, "newTempFile.txt", false);
}, onErrorLoadFs);
عندما تستخدم التخزين المؤقت، يمكنك إنشاء أو الحصول على الملف عن طريق استدعاء التابع getFile
. وكما في مثال التخزين الثابت، سيعطيك هذا كائنًا FileEntry
، والذي يمكنك استخدامه لأجل عمليات القراءة أو الكتابة.
function createFile(dirEntry, fileName, isAppend) {
// انشاء ملف جديد أو إعادةالملف إن كان موجودا سلفا
dirEntry.getFile(fileName, {create: true, exclusive: false}, function(fileEntry) {
writeFile(fileEntry, null, isAppend);
}, onErrorCreateFile);
}
الكتابة في ملف
بمجرد الحصول على الكائن FileEntry
، يمكنك الكتابة في الملف عن طريق استدعاء التابع createWriter
، والذي يعيد كائنًا FileWriter
في دالة النجاح (success callback).
استدع التابع write
الخاص بالكائن FileWriter
للكتابة في الملف.
function writeFile(fileEntry, dataObj) {
// (log.txt) FileEntry لأجل الكائن FileWriter انشاء
fileEntry.createWriter(function (fileWriter) {
fileWriter.onwriteend = function() {
console.log("Successful file write...");
readFile(fileEntry);
};
fileWriter.onerror = function (e) {
console.log("Failed file write: " + e.toString());
};
// dataObj في حال عدم تمرير كائن البيانات
// جديد Blob أنشئ كائن.
if (!dataObj) {
dataObj = new Blob(['some file data'], { type: 'text/plain' });
}
fileWriter.write(dataObj);
});
}
قراءة ملف
تحتاج إلى كائن FileEntry
لقراءة ملف موجود. استخدم الخاصية file
في الكائن FileEntry
للحصول على مرجع الملف، ثم أنشئ كائنًا جديدًا من النوع FileReader
. يمكنك استخدام توابع مثل التابع readAsText
لبدء عملية القراءة.
عند اكتمال عملية القراءة، ستخزن الخاصية this.result
نتيجة عملية القراءة.
function readFile(fileEntry) {
fileEntry.file(function (file) {
var reader = new FileReader();
reader.onloadend = function() {
console.log("Successful file read: " + this.result);
displayFileData(fileEntry.fullPath + ": " + this.result);
};
reader.readAsText(file);
}, onErrorReadFile);
}
إضافة محتوى إلى ملف باستخدام توابع بديلة
ستحتاج غالبًا إلى إضافة محتوًى إلى الملفات الموجودة بدلاً من إنشاء ملفات جديدة. إليك مثالًا على ذلك.
يوضح هذا المثال طريقة أخرى يمكنك من خلالها الوصول إلى نظام الملفات باستخدام window.resolveLocalFileSystemURL
. في هذا المثال، قم بتمرير عنوان الملف المستقل عن المنصات cordova.file.dataDirectory
إلى الدالة. تتلقى دالة النجاح (success callback) كائنًا DirectoryEntry
، والذي يمكنك استخدامه للقيام بعدة أمورـ مثل إنشاء ملفٍ.
window.resolveLocalFileSystemURL(cordova.file.dataDirectory, function (dirEntry) {
console.log('file system open: ' + dirEntry.name);
var isAppend = true;
createFile(dirEntry, "fileToAppend.txt", isAppend);
}, onErrorLoadFs);
بالإضافة إلى هذا، يمكنك استخدام التابع resolveLocalFileSystemURL
للوصول إلى بعض مواضع نظام الملفات التي لا تدخل في نظام التخزين المحصّن. راجع فقرة مكان تخزين الملفات لمزيد من المعلومات؛ العديد من مواضع التخزين هذه مخصوصة بالمنصات. يمكنك أيضًا تمرير مواضع نظام ملفات مستقلة عن المنصات إلى التابع resolveLocalFileSystemURL
باستخدام البروتوكول cdvfile
.
بالنسبة إلى عملية الإضافة (append)، لا يوجد شيء جديد في الدالة createFile
التي استدعيناها في الشيفرة البرمجية السابقة (راجع الأمثلة السابقة لمطالعة الشيفرات الفعلية). حيث تستدعي createFile
الدالة writeFile
. عليك أن تتحقق في writeFile
مما إذا كانت عملية الإضافة مطلوبة أم لا.
بمجرد الحصول على كائن FileWriter
، استدع التابع seek
، ومرّر إليه فهرس الموضع الذي تريد الكتابة عنده.
في هذا المثال، سنتحقق أيضًا من وجود الملف. وبعد استدعاء التابع seek
، سنستدع التابع write
الخاصة بالكائن FileWriter
.
function writeFile(fileEntry, dataObj, isAppend) {
// (log.txt) FileEntry لأجل الكائن FileWriter انشاء
fileEntry.createWriter(function (fileWriter) {
fileWriter.onwriteend = function() {
console.log("Successful file read...");
readFile(fileEntry);
};
fileWriter.onerror = function (e) {
console.log("Failed file read: " + e.toString());
};
// في حال إضافة بيانات إلى الملف، اذهب إلى نهاية الملف
if (isAppend) {
try {
fileWriter.seek(fileWriter.length);
}
catch (e) {
console.log("file doesn't exist!");
}
}
fileWriter.write(dataObj);
});
}
تخزين ملف ثنائي موجود (Store an existing binary file )
سبق ووضحنا كيفية الكتابة في ملف أنشأته للتو في نظام الملفات المُحصّن. لكن ماذا لو احتجت إلى الوصول إلى ملف موجود، وأردت جعله قابلًا للتخزين على جهازك؟ في هذا المثال، ستحصل على ملف باستخدام طلبية xhr (xhr request)، ثم ستحفظه في ذاكرة التخزين المؤقت في نظام الملفات المُحصّنة.
قبل الحصول على الملف، عليك الحصول أولًا على مرجع لكائن FileSystem
باستخدام التابع requestFileSystem
. مع إعطائه القيمةwindow.TEMPORARY
(كما فعلنا من قبل)، يمثل الكائن FileSystem
المعاد ذاكرة التخزين المؤقت في نظام االملفات المُحصّنة.
استخدم fs.root
للحصول على الكائن DirectoryEntry
الذي تحتاجه.
window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
console.log('file system open: ' + fs.name);
getSampleFile(fs.root);
}, onErrorLoadFs);
في الختام، إليك طلبية xhr للحصول على بقعة الصورة (Blob image). لا يوجد أي شيء خاص بكوردوفا في هذه الشيفرة، باستثناء أنك ستقوم بإعادة توجيه مرجع DirectoryEntry
الذي حصلت عليه بالفعل كوسيط للدالة saveFile
. سوف تقوم بحفظ بقعة الصورة (Blob image) وعرضها في وقت لاحق بعد قراءة الملف (للتحقق من صحة العملية).
function getSampleFile(dirEntry) {
var xhr = new XMLHttpRequest();
xhr.open('GET', 'http://cordova.apache.org/static/img/cordova_bot.png', true);
xhr.responseType = 'blob';
xhr.onload = function() {
if (this.status == 200) {
var blob = new Blob([this.response], { type: 'image/png' });
saveFile(dirEntry, blob, "downloadedImage.png");
}
};
xhr.send();
}
ملاحظة: كجزء من إجراءات الأمان في كوردوفا 5، تتطلب الشيفرة السابقة إضافة اسم النطاق، http://cordova.apache.org، إلى العنصر Content-Security-Policy
في الملف index.html
.
بعد الحصول على الملف، انسخ المحتويات في ملف جديد. الكائن DirectoryEntry
الحالي مرتبط بالفعل مع المخزن المؤقت (cache) للتطبيق.
function saveFile(dirEntry, fileData, fileName) {
dirEntry.getFile(fileName, { create: true, exclusive: false }, function (fileEntry) {
writeFile(fileEntry, fileData);
}, onErrorCreateFile);
}
ستمرر كائن الملف Blob إلى الدالة writeFile
باعتباره كائن البيانات dataObj
، وستحفظه في الملف الجديد.
function writeFile(fileEntry, dataObj, isAppend) {
// (log.txt) FileEntry لأجل الكائن FileWriter انشاء
fileEntry.createWriter(function (fileWriter) {
fileWriter.onwriteend = function() {
console.log("Successful file write...");
if (dataObj.type == "image/png") {
readBinaryFile(fileEntry);
}
else {
readFile(fileEntry);
}
};
fileWriter.onerror = function(e) {
console.log("Failed file write: " + e.toString());
};
fileWriter.write(dataObj);
});
}
بعد الكتابة في الملف، اقرأه وقم بعرضه. وبما أنّك حفظت الصورة على هيئة بيانات ثنائية (binary data)، فيمكنك قراءتها باستخدام التابع FileReader.readAsArrayBuffer.
function readBinaryFile(fileEntry) {
fileEntry.file(function (file) {
var reader = new FileReader();
reader.onloadend = function() {
console.log("Successful file write: " + this.result);
displayFileData(fileEntry.fullPath + ": " + this.result);
var blob = new Blob([new Uint8Array(this.result)], { type: "image/png" });
displayImage(blob);
};
reader.readAsArrayBuffer(file);
}, onErrorReadFile);
}
بعد قراءة البيانات، يمكنك عرض الصورة باستخدام الشيفرة التالية. استخدم window.URL.createObjectURL
للحصول على السلسلة النصية للشِّعب (DOM) الخاصة ببقعة الصورة (Blob image).
function displayImage(blob) {
// استخدم الصورة إن كانت النتيجة عبارة عن سلسلة نصية تمثل صورة صالحة في الشِّعب
var elem = document.getElementById('imageFile');
// عند إنهاء الصورة window.URL.revokeObjectURL ملاحظة:استخدم
elem.src = window.URL.createObjectURL(blob);
}
عرض ملف صورة
لعرض صورة باستخدام FileEntry
، يمكنك استدعاء التابع toURL
.
function displayImageByFileURL(fileEntry) {
var elem = document.getElementById('imageFile');
elem.src = fileEntry.toURL();
}
إن كنت تستخدم عناوين مخصوصة بمنصات معينة بدلاً من FileEntry
، وأردت عرض صورة، فقد تحتاج إلى تضمين الجزء الرئيسي من العنوان في العنصر Content-Security-Policy
في الملف index.html
.
على سبيل المثال، في ويندوز 10، يمكنك تضمين ms-appdata:
في ذلك العنصر. كما يوضح المثال التالي:
<meta http-equiv="Content-Security-Policy" content="default-src 'self' data: gap: ms-appdata: https://ssl.gstatic.com 'unsafe-eval'; style-src 'self' 'unsafe-inline'; media-src *">
إنشاء المجلدات
في الشيفرة التالية، ستنشئ مجلدات في المجلد الجذري للمخزن (root storage location) الخاص بالتطبيق. يمكنك استخدام هذه الشيفرة مع أي موضع تخزين قابل للكتابة (DirectoryEntry
). في هذا المثال، ستكتب في ذاكرة التخزين المؤقت للتطبيق (على افتراض أنك حصلت على الكائن FileSystem
عبر window.TEMPORARY
) عن طريق تمرير fs.root
إلى هذه الدالة.
تنشئ هذه الشيفرة المجلد /NewDirInRoot/images
في المخزن المؤقت للتطبيق (بخصوص القيم المخصوصة بمنصات معينة، راجع فقرة بنيات نظام الملفات أعلاه.)
function createDirectory(rootDirEntry) {
rootDirEntry.getDirectory('NewDirInRoot', { create: true }, function (dirEntry) {
dirEntry.getDirectory('images', { create: true }, function (subDirEntry) {
createFile(subDirEntry, "fileInNewSubDir.txt");
}, onErrorGetDir);
}, onErrorGetDir);
}
عند إنشاء مجلدات فرعية، عليك إنشاء كل مجلد على حدة كما هو موضح في الشيفرة البرمجية السابقة.
انظر أيضا
- صفحة الأحداث.