الفرق بين المراجعتين لصفحة: «Cordova/cordova plugin file»

المراجعة الحالية بتاريخ 08:48، 23 يونيو 2022

تقدم إضافة الملفات (cordova-plugin-file) واجهة برمجية للملفات، والتي يمكن استخدامها للقراءة أو الكتابة في الملفات الموجودة على الجهاز.

هذه الإضافة مبنية على عدة مواصفات، منها:

دورة تطوير التطبيقات باستخدام لغة JavaScript

71 ساعة فيديو تدريبية
من الصفر دون الحاجة لخبرة مسبقة
شهادة معتمدة من أكاديمية حسوب
متابعة أثناء الدورة من فريق مختص

اشترك الآن

الواجهة البرمجية للملفات في 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)‎.

مكان تخزين الملفات

بدءًا من الإصدار 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) باستخدام الذاكرة الداخلية (على منصة أندرويد، إن كنت بحاجة إلى استخدام ذاكرة خارجية، فاستخدم ‎.externalDataDirector). على منصة 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`	ق/ك	لا	لا	نعم

* => قد يمحو نظام التشغيل هذا المجلد دوريًا.

ملاحظات خاصة بمنصة أندرويد

موضع التخزين الدائم في أندرويد (Android Persistent storage location)

هناك عدة مواضع صالحة لتخزين الملفات بشكل دائم على أجهزة أندرويد . راجع هذه الصفحة لمعلومات مفصلة بخصوص مختلف إمكانيات التخزين المتاحة.

كانت الإصدارات السابقة من هذه الإضافة تختار موضع الملفات المؤقتة والمستمرة (persistent) عند بدء التشغيل، بحسب ما إذا تم وصل (mounted) بطاقة الذاكرة 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، ولن يكون على الإضافة الاستئذان للكتابة في هذين المجلدين إلا إذا لم توصل (mounte) وحدة تخزين خارجية. وفي هذه الحالة، فستطلب الإضافة الإذن للكتابة في 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: نظام ملفات الجهاز بأكمله.
applicationDirectory: للقراءة فقط مع وصول مقيد. يمكن نسخ الملفات في هذا المجلد، ولكن في حال محاولة قرائتها مباشرة سينتج عن ذلك تنبيه "file not found". يدعم أندرويد أيضًا نظام ملفات خاص باسم "documents"، والذي يمثل مجلدًا فرعيًا "/Documents/" داخل نظام الملفات "files".

منصة iOS

library: مجلد مكتبة التطبيق.
documents: مجلد مستندات (Documents) التطبيق.
cache: مجلد ذاكرة التخزين المؤقت للتطبيق.
bundle: حزمة التطبيق، وهو موضع التطبيق نفسه على القرص (للقراءة فقط).
root: نظام ملفات الجهاز بأكمله.

افتراضيًا، يمكن مزامنة مجلدي المستندات (documents) والمكتبة (library) مع السحابة iCloud. يمكنك أيضًا طلب (request) نظامي ملفات إضافيين، وهما library-nosync و documents-nosync اللذان يمثلان مجلدًا خاصًا غير متزامن داخل نظام الملفات ‎/Library أو ‎/Documents.

مثال عملي

تتيح لك إضافة الملفات تنفيذ العديد من الأشياء، مثل تخزين الملفات في موقع تخزين مؤقت أو دائم لأجل استخدامه من قبل تطبيقك (تخزين تجريبي [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. لا يوجد أي شيء خاص بكوردوفا في هذه الشيفرة، باستثناء أنك ستقوم بإعادة توجيه مرجع DirectoryEntry الذي حصلت عليه بالفعل إلى الدالة saveFile كوسيط. سوف تقوم بحفظ الصورة وعرضها في وقت لاحق بعد قراءة الملف (للتحقق من صحة العملية).

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.

function displayImage(blob) {
    // استخدم الصورة إن كانت النتيجة عبارة عن 
    // DOM سلسلة نصية تمثل صورة صالحة في
    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);
}‎

عند إنشاء مجلدات فرعية، عليك إنشاء كل مجلد على حدة كما هو موضح في الشيفرة البرمجية السابقة.

انظر أيضًا

دليل تطوير الإضافات في كوردوفا

مصادر

صفحة cordova-plugin-file في توثيق كوردوفا الرسمي.