chrome.fileSystem

الوصف

استخدِم واجهة برمجة التطبيقات chrome.fileSystem لإنشاء نظام الملفات المحلي للمستخدم وقراءته والتنقّل فيه والكتابة إليه. باستخدام واجهة برمجة التطبيقات هذه، يمكن لتطبيقات Chrome القراءة والكتابة في موقع جغرافي يختاره المستخدم. على سبيل المثال، يمكن لتطبيق محرِّر النصوص استخدام واجهة برمجة التطبيقات لقراءة المستندات المحلية وكتابتها. يتم الإبلاغ عن جميع حالات التعذُّر من خلال chrome.runtime.lastError.

الأذونات

fileSystem

مدى التوفّر

في المقدّمة فقط

الأنواع

AcceptOption

الخصائص

  • الوصف

    string اختياري

    هذا هو الوصف النصي الاختياري لهذا الخيار. في حال عدم توفّر وصف، سيتم إنشاء وصف تلقائيًا، ويحتوي عادةً على قائمة موسّعة من الإضافات الصالحة (على سبيل المثال، قد يتم توسيع "text/html" إلى "‎*.html, *.htm").

  • إضافات

    string[] اختياري

    الامتدادات التي يتم قبولها، مثل "jpg" و"gif" و"crx".

  • mimeTypes

    string[] اختياري

    أنواع MIME التي يتم قبولها، مثل "image/jpeg" أو "audio/*‎". يجب أن يحتوي أحد mimeTypes أو الإضافات على عنصر صالح واحد على الأقل.

ChooseEntryOptions

الخصائص

  • يقبل

    AcceptOption[] اختيارية

    قائمة اختيارية بخيارات القبول لأداة فتح الملفات هذه سيتم عرض كل خيار كمجموعة فريدة للمستخدم النهائي.

  • acceptsAllTypes

    قيمة منطقية اختيارية

    ما إذا كان سيتم قبول جميع أنواع الملفات، بالإضافة إلى الخيارات المحدّدة في وسيطة accepts. وتكون القيمة التلقائية مضبوطة على true. إذا لم يتم ضبط حقل accepts أو لم يتضمّن أي إدخالات صالحة، ستتم إعادة ضبطه دائمًا على القيمة true.

  • acceptsMultiple

    قيمة منطقية اختيارية

    ما إذا كان سيتم قبول ملفات متعددة أم لا لا يتوفّر هذا الخيار إلا لـ openFile وopenWritableFile. سيتم استدعاء دالة الاستدعاء chooseEntry مع قائمة بالإدخالات إذا تم ضبط هذا الخيار على "صحيح". وإلا سيتم استدعاؤها باستخدام إدخال واحد.

  • suggestedName

    string اختياري

    اسم الملف المقترَح الذي سيتم عرضه للمستخدم كاسم تلقائي للحفظ. هذا الإجراء اختياري وينطبق فقط على "saveFile".

  • النوع

    ChooseEntryType اختياري

    نوع الطلب المطلوب عرضه القيمة التلقائية هي "openFile".

ChooseEntryType

Enum

"openFile"
يطلب من المستخدم فتح ملف حالي ويعرض FileEntry عند النجاح. بدءًا من الإصدار 31 من Chrome، سيكون FileEntry قابلاً للكتابة إذا كان التطبيق يملك إذن "الكتابة" ضمن "fileSystem"، وإلا سيكون FileEntry للقراءة فقط.

‫"openWritableFile"
يطلب من المستخدم فتح ملف حالي ويعرض FileEntry قابلاً للكتابة عند النجاح. ستتعذّر المكالمات التي تستخدم هذا النوع بسبب خطأ أثناء التشغيل إذا لم يكن التطبيق يملك إذن "الكتابة" ضمن "fileSystem".

"saveFile"
يطلب من المستخدم فتح ملف حالي أو ملف جديد ويعرض FileEntry قابلاً للكتابة عند النجاح. ستتعذّر المكالمات التي تستخدم هذا النوع بسبب خطأ أثناء التشغيل إذا لم يكن التطبيق يملك إذن "الكتابة" ضمن "fileSystem".

"openDirectory"
يطلب من المستخدم فتح دليل ويعرض DirectoryEntry عند النجاح. ستتعذّر المكالمات التي تستخدم هذا النوع مع ظهور خطأ أثناء التشغيل إذا لم يكن التطبيق يمتلك إذن "الدليل" ضمن "fileSystem". إذا كان التطبيق يمتلك إذن "الكتابة" ضمن "fileSystem"، سيكون DirectoryEntry الذي تم عرضه قابلاً للكتابة، وإلا سيكون للقراءة فقط. الجديد في الإصدار 31 من Chrome

RequestFileSystemOptions

الإصدار 44 من Chrome أو الإصدارات الأحدث

الخصائص

  • volumeId

    سلسلة

    رقم تعريف المجلد المطلوب

  • قابل للكتابة

    قيمة منطقية اختيارية

    ما إذا كان يجب أن يكون نظام الملفات المطلوب قابلاً للكتابة. الإعداد التلقائي هو "للقراءة فقط".

Volume

الإصدار 44 من Chrome أو الإصدارات الأحدث

الخصائص

  • volumeId

    سلسلة

  • قابل للكتابة

    قيمة منطقية

VolumeListChangedEvent

الإصدار 44 من Chrome أو الإصدارات الأحدث

الخصائص

الطُرق

chooseEntry()

chrome.fileSystem.chooseEntry(
  options?: ChooseEntryOptions,
  callback: function,
): void

اطلب من المستخدم اختيار ملف أو دليل.

المعلمات

  • الخيارات

    ChooseEntryOptions اختياري

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (entry?: Entry, fileEntries?: FileEntry[]) => void

    • إدخال

      الإدخال اختياري

    • fileEntries

      ‫FileEntry[] اختياري

getDisplayPath()

Promise 
chrome.fileSystem.getDisplayPath(
  entry: Entry,
  callback?: function,
): Promise<string>

الحصول على مسار العرض لعنصر Entry يستند مسار العرض إلى المسار الكامل للملف أو الدليل في نظام الملفات على الجهاز، ولكن يمكن جعله أكثر قابلية للقراءة لأغراض العرض.

المعلمات

  • إدخال

    إدخال

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (displayPath: string) => void

    • displayPath

      سلسلة

المرتجعات

  • وعد<سلسلة>

    الإصدار 117 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getVolumeList()

Promise الإصدار 44 من Chrome والإصدارات الأحدث 
chrome.fileSystem.getVolumeList(
  callback?: function,
): Promise<Volume[] | undefined>

تعرض هذه الدالة قائمة بالمجلدات المتاحة لـ requestFileSystem(). يجب الحصول على إذن البيان "fileSystem": {"requestFileSystem"}. متاح لتطبيقات Kiosk التي تعمل في جلسة Kiosk فقط. في حال حدوث خطأ، لن يتم تحديد volumes وسيتم ضبط chrome.runtime.lastError.

المعلمات

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (volumes?: Volume[]) => void

    • مجلدات

      Volume[] اختيارية

المرتجعات

  • Promise<Volume[] | undefined>

    الإصدار 117 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getWritableEntry()

chrome.fileSystem.getWritableEntry(
  entry: Entry,
  callback: function,
): void

الحصول على إدخال قابل للكتابة من إدخال آخر سيتعذّر إجراء هذا الطلب بسبب خطأ أثناء التشغيل إذا لم يكن لدى التطبيق إذن "الكتابة" ضمن "fileSystem". إذا كان الإدخال هو DirectoryEntry، سيتعذّر إجراء هذه المكالمة إذا لم يكن التطبيق لديه إذن "الدليل" ضمن "fileSystem".

المعلمات

  • إدخال

    إدخال

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (entry: Entry) => void

    • إدخال

      إدخال

isRestorable()

Promise 
chrome.fileSystem.isRestorable(
  id: string,
  callback?: function,
): Promise<boolean>

تعرض هذه الدالة ما إذا كان التطبيق يملك الإذن باستعادة الإدخال الذي يحمل رقم التعريف المحدّد.

المعلمات

  • id

    سلسلة

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (isRestorable: boolean) => void

    • isRestorable

      قيمة منطقية

المرتجعات

  • Promise<boolean>

    الإصدار 117 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

isWritableEntry()

Promise 
chrome.fileSystem.isWritableEntry(
  entry: Entry,
  callback?: function,
): Promise<boolean>

تحدّد ما إذا كان هذا الإدخال قابلاً للكتابة أم لا.

المعلمات

  • إدخال

    إدخال

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (isWritable: boolean) => void

    • isWritable

      قيمة منطقية

المرتجعات

  • Promise<boolean>

    الإصدار 117 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

requestFileSystem()

Promise الإصدار 44 من Chrome والإصدارات الأحدث 
chrome.fileSystem.requestFileSystem(
  options: RequestFileSystemOptions,
  callback?: function,
): Promise<FileSystem | undefined>

يطلب هذا الإذن الوصول إلى نظام ملفات لوحدة تخزين يمثّلها options.volumeId. إذا تم ضبط السياسة options.writable على "صحيح"، سيكون نظام الملفات قابلاً للكتابة. وإذا لم يكن كذلك، سيكون متاحًا للقراءة فقط. يتطلّب الخيار writable توفُّر الإذن "fileSystem": {"write"} في ملف البيان. متاح لتطبيقات Kiosk التي تعمل في جلسة Kiosk فقط. بالنسبة إلى وضع Kiosk الذي يتم تشغيله يدويًا، سيظهر مربّع حوار للتأكيد أعلى نافذة التطبيق النشط. في حال حدوث خطأ، لن يتم تحديد fileSystem وسيتم ضبط chrome.runtime.lastError.

المعلمات

  • الخيارات

    RequestFileSystemOptions

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (fileSystem?: FileSystem) => void

    • fileSystem

      FileSystem اختياري

المرتجعات

  • Promise<FileSystem | undefined>

    الإصدار 117 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

restoreEntry()

chrome.fileSystem.restoreEntry(
  id: string,
  callback: function,
): void

تعرض هذه الطريقة إدخال الملف الذي يحمل المعرّف المحدّد إذا كان من الممكن استعادته. وإلا، سيتعذّر إجراء هذا الطلب بسبب خطأ أثناء التشغيل.

المعلمات

  • id

    سلسلة

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (entry: Entry) => void

    • إدخال

      إدخال

retainEntry()

chrome.fileSystem.retainEntry(
  entry: Entry,
): string

تعرض هذه الطريقة معرّفًا يمكن تمريره إلى restoreEntry لاستعادة إمكانية الوصول إلى إدخال ملف معيّن. يتم الاحتفاظ بآخر 500 إدخال تم استخدامها فقط، حيث يتم احتساب طلبات retainEntry وrestoreEntry كاستخدام. إذا كان التطبيق يملك إذن "retainEntries" ضمن "fileSystem"، يتم الاحتفاظ بالإدخالات إلى أجل غير مسمى. وإلا، يتم الاحتفاظ بالإدخالات فقط أثناء تشغيل التطبيق وعبر عمليات إعادة التشغيل.

المعلمات

  • إدخال

    إدخال

المرتجعات

  • سلسلة

الفعاليات

onVolumeListChanged

الإصدار 44 من Chrome أو الإصدارات الأحدث 
chrome.fileSystem.onVolumeListChanged.addListener(
  callback: function,
)

يتم استدعاء هذه الطريقة عند تغيير قائمة وحدات التخزين المتاحة.

المعلمات