إضافة الوصول إلى الملفات في كوردوفا
تقدم إضافة الملفات (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
: المجلد لتخزين الملفات الخارجية العامة (والذي سيكون جذر بطاقة الذاكرة 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. يمكنك أيضًا طلب نظامي ملفات إضافيين، وهما library-nosync
و documents-nosync
، واللذان يمثلان مجلدًا خاصًا غير متزامن داخل نظام الملفات /Library
أو /Documents
.
نموذج: إنشاء ملفات والمجلدات، كتابة، قراءة، وإلحاق الملفات
تتيح لك الإضافة File تنفيذ أشياء مثل تخزين الملفات في موقع تخزين مؤقت أو دائم لأجل تطبيقك (تخزين مُحصّن [sandboxed storage])، ولتخزين الملفات في مواقع أخرى بحسب على المنصة المُستخدمة. توضح الشيفرات البرمجية في هذا القسم بعض الأمور، مثل:
- [#persistent Accessing the file system]
- استخدام عناوين (URL) ملفات مستقلة عن المنصات لتخزين ملفاتك [#appendFile store your files] (راجع فقرة مكان تخزين الملفات لمزيد من المعلومات)
- إنشاء [#persistent files] و [#createDir directories]
- [#writeFile Writing to files]
- [#readFile Reading files]
- [#appendFile Appending files]
- [#displayImage Display an image file]
إنشاء ملف دائم
قبل استخدام الواجهات البرمجية الإضافة الملفات File، يمكنك الوصول إلى نظام الملفات باستخدام 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. استخدم fs.root
لإعادة كائنٍ DirectoryEntry، والذي يمكنك استخدامه لإنشاء أو الحصول على ملف (عن طريق استدعاء getFile
). في هذا المثال، fs.root
هو كائنٌ DirectoryEntry يمثل التخزين الدائم في نظام الملفات المُحصّن.
تتلقى دالة النجاح (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) {
// Creates a new file or returns the file if it already exists.
dirEntry.getFile(fileName, {create: true, exclusive: false}, function(fileEntry) {
writeFile(fileEntry, null, isAppend);
}, onErrorCreateFile);
}
الكتابة في ملف
بمجرد أن يكون لديك كائن FileEntry، يمكنك الكتابة في الملف عن طريق استدعاء createWriter
، والذي يعيد كائنًا FileWriter في دالة النجاح. استدع التابع write
الخاص بالكائن FileWriter للكتابة إلى الملف.
function writeFile(fileEntry, dataObj) {
// Create a FileWriter object for our FileEntry (log.txt).
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());
};
// If data object is not passed in,
// create a new Blob instead.
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) {
// Create a FileWriter object for our FileEntry (log.txt).
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 we are appending data to file, go to the end of the file.
if (isAppend) {
try {
fileWriter.seek(fileWriter.length);
}
catch (e) {
console.log("file doesn't exist!");
}
}
fileWriter.write(dataObj);
});
}
تخزين ملف ثنائي موجود
سبق ووضحنا كيفية الكتابة في ملف أنشأته للتو في نظام الملفات المُحصّن. ماذا لو احتجت إلى الوصول إلى ملف موجود وجعله قابلًا للتخزين على جهازك؟ في هذا المثال، ستحصل على ملف باستخدام طلبية xhr، ثم ستحفظه في ذاكرة التخزين المؤقت في نظام الملفات المُحصّنة.
قبل الحصول على الملف، احصل على مرجع لكائن 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 الحالي مرتبط بالفعل مع التخزين المؤقت للتطبيق.
function saveFile(dirEntry, fileData, fileName) {
dirEntry.getFile(fileName, { create: true, exclusive: false }, function (fileEntry) {
writeFile(fileEntry, fileData);
}, onErrorCreateFile);
}
في writeFile، يمكنك تمرير في كائن الملف Blob باعتباره dataObj، وستحفظه في الملف الجديد.
function writeFile(fileEntry, dataObj, isAppend) {
// Create a FileWriter object for our FileEntry (log.txt).
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) {
// Displays image if result is a valid DOM string for an image.
var elem = document.getElementById('imageFile');
// Note: Use window.URL.revokeObjectURL when finished with image.
elem.src = window.URL.createObjectURL(blob);
}
عرض ملف صورة
لعرض صورة باستخدام FileEntry، يمكنك استدعاء التابع toURL
.
function displayImageByFileURL(fileEntry) {
var elem = document.getElementById('imageFile');
elem.src = fileEntry.toURL();
}
إن كنت تستخدم عناوين مخصوصة بمنصات معينة بدلاً من FileEntry، وأردت عرض صورة، فقد تحتاج إلى تضمين الجزء الرئيسي من العنوان URI في العنصر 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 *">
إنشاء المجلدات
في الشفرة التالية، ستنشئ مجلدات في جذر موضع التخزين الخاص بالتطبيق. يمكنك استخدام هذه الشيفرة مع أي موضع تخزين قابل للكتابة (DirectoryEntry). في هذا المثال، ستكتب في ذاكرة التخزين المؤقت للتطبيق (على افتراض أنك استخدمت window.TEMPORARY للحصول على الكائن FileSystem) عن طريق تمرير 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);
}
عند إنشاء مجلدات فرعية، عليك إنشاء كل مجلد على حدة كما هو موضح في الشيفرة البرمجية السابقة.