chrome.fileSystem

توضیحات

از API chrome.fileSystem برای ایجاد، خواندن، پیمایش و نوشتن در سیستم فایل محلی کاربر استفاده کنید. با استفاده از این API، برنامه‌های Chrome می‌توانند در یک مکان انتخاب شده توسط کاربر، فایل‌ها را بخوانند و در آن بنویسند. به عنوان مثال، یک برنامه ویرایشگر متن می‌تواند از API برای خواندن و نوشتن اسناد محلی استفاده کند. همه خرابی‌ها از طریق chrome.runtime.lastError اطلاع داده می‌شوند.

مجوزها

fileSystem

در دسترس بودن

فقط پیش‌زمینه

انواع

AcceptOption

خواص

  • توضیحات

    رشته اختیاری

    این توضیحات متنی اختیاری برای این گزینه است. در صورت عدم وجود، توضیحاتی به طور خودکار ایجاد می‌شود؛ که معمولاً شامل لیست گسترده‌ای از پسوندهای معتبر است (مثلاً "text/html" ممکن است به "*.html، *.htm" گسترش یابد).

  • افزونه‌ها

    رشته[] اختیاری

    پسوندهایی که باید پذیرفته شوند، مانند "jpg"، "gif"، "crx".

  • انواع mime

    رشته[] اختیاری

    انواع MIME برای پذیرش، مثلاً "image/jpeg" یا "audio/*". یکی از MIMETypeها یا افزونه‌ها باید حداقل شامل یک عنصر معتبر باشد.

ChooseEntryOptions

خواص

  • می‌پذیرد

    گزینه پذیرش [] اختیاری

    فهرست اختیاری گزینه‌های پذیرش برای این بازکننده فایل. هر گزینه به عنوان یک گروه منحصر به فرد به کاربر نهایی ارائه می‌شود.

  • همه نوع‌ها را می‌پذیرد

    بولی اختیاری

    آیا علاوه بر گزینه‌های مشخص شده در آرگومان accepts، همه انواع فایل‌ها پذیرفته شوند یا خیر. مقدار پیش‌فرض true است. اگر فیلد accepts تنظیم نشده باشد یا حاوی هیچ ورودی معتبری نباشد، این مقدار همیشه به true بازنشانی می‌شود.

  • چندگانه را می‌پذیرد

    بولی اختیاری

    اینکه آیا چندین فایل پذیرفته شود یا خیر. این فقط برای openFile و openWritableFile پشتیبانی می‌شود. اگر این مقدار روی true تنظیم شده باشد، تابع callback به chooseEntry با لیستی از ورودی‌ها فراخوانی می‌شود. در غیر این صورت، با یک ورودی واحد فراخوانی خواهد شد.

  • نام پیشنهادی

    رشته اختیاری

    نام فایل پیشنهادی که به عنوان نام پیش‌فرض برای ذخیره به کاربر ارائه می‌شود. این اختیاری است و فقط برای 'saveFile' اعمال می‌شود.

  • نوع

    انتخاب نوع ورود اختیاری است

    نوع اعلانی که نمایش داده می‌شود. مقدار پیش‌فرض «openFile» است.

ChooseEntryType

شمارشی

"فایل باز"
از کاربر می‌خواهد که یک فایل موجود را باز کند و در صورت موفقیت، یک FileEntry برمی‌گرداند. از کروم ۳۱ به بعد، اگر برنامه مجوز «نوشتن» را در بخش «fileSystem» داشته باشد، FileEntry قابل نوشتن خواهد بود؛ در غیر این صورت، FileEntry فقط خواندنی خواهد بود.

"فایل قابل نوشتن باز"
از کاربر می‌خواهد که یک فایل موجود را باز کند و در صورت موفقیت، یک FileEntry قابل نوشتن برمی‌گرداند. فراخوانی‌هایی که از این نوع استفاده می‌کنند، در صورتی که برنامه مجوز «نوشتن» را در زیر «fileSystem» نداشته باشد، با خطای زمان اجرا مواجه می‌شوند.

"ذخیره فایل"
از کاربر می‌خواهد که یک فایل موجود یا یک فایل جدید را باز کند و در صورت موفقیت، یک FileEntry قابل نوشتن برمی‌گرداند. فراخوانی‌هایی که از این نوع استفاده می‌کنند، در صورتی که برنامه مجوز «نوشتن» را در زیر «fileSystem» نداشته باشد، با خطای زمان اجرا مواجه می‌شوند.

"دایرکتوری باز"
از کاربر می‌خواهد که یک دایرکتوری را باز کند و در صورت موفقیت، یک DirectoryEntry برمی‌گرداند. فراخوانی‌هایی که از این نوع استفاده می‌کنند، در صورتی که برنامه مجوز 'directory' را در 'fileSystem' نداشته باشد، با خطای زمان اجرا مواجه می‌شوند. اگر برنامه مجوز 'write' را در 'fileSystem' داشته باشد، DirectoryEntry برگردانده شده قابل نوشتن خواهد بود؛ در غیر این صورت فقط خواندنی خواهد بود. این قابلیت در کروم ۳۱ جدید است.

RequestFileSystemOptions

کروم ۴۴+

خواص

  • شناسه حجم

    رشته

    شناسه‌ی حجم درخواستی.

  • قابل نوشتن

    بولی اختیاری

    اینکه آیا سیستم فایل درخواستی باید قابل نوشتن باشد یا خیر. پیش‌فرض فقط خواندنی است.

Volume

کروم ۴۴+

خواص

  • شناسه حجم

    رشته

  • قابل نوشتن

    بولی

VolumeListChangedEvent

کروم ۴۴+

خواص

روش‌ها

chooseEntry()

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

از کاربر بخواهید یک فایل یا دایرکتوری را انتخاب کند.

پارامترها

  • گزینه‌ها

    انتخاب گزینه‌ها اختیاری است

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

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

    • ورود

      ورود اختیاری است

    • ورودی‌های فایل

      FileEntry[] اختیاری

getDisplayPath()

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

مسیر نمایش یک شیء Entry را دریافت کنید. مسیر نمایش بر اساس مسیر کامل فایل یا دایرکتوری در سیستم فایل محلی است، اما ممکن است برای اهداف نمایشی خواناتر شود.

پارامترها

  • ورود

    ورود

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (displayPath: string) => void

    • مسیر نمایش

      رشته

بازگشت‌ها

  • قول<string>

    کروم ۱۱۷+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getVolumeList()

قول کروم ۴۴+
chrome.fileSystem.getVolumeList(
  callback?: function,
): Promise<Volume[] | undefined>

فهرستی از درایوهای موجود برای requestFileSystem() را برمی‌گرداند. مجوز manifest مربوط به "fileSystem": {"requestFileSystem"} مورد نیاز است. فقط برای برنامه‌های کیوسک که در جلسه کیوسک اجرا می‌شوند، در دسترس است. در صورت بروز خطا، volumes تعریف نشده و chrome.runtime.lastError تنظیم خواهد شد.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (volumes?: Volume[]) => void

    • حجم‌ها

      حجم [] اختیاری

بازگشت‌ها

  • وعده< جلد [] | تعریف نشده>

    کروم ۱۱۷+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getWritableEntry()

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

یک ورودی قابل نوشتن از یک ورودی دیگر دریافت کنید. اگر برنامه مجوز «نوشتن» را در زیر «fileSystem» نداشته باشد، این فراخوانی با خطای زمان اجرا ناموفق خواهد بود. اگر ورودی یک DirectoryEntry باشد، اگر برنامه مجوز «دایرکتوری» را در زیر «fileSystem» نداشته باشد، این فراخوانی ناموفق خواهد بود.

پارامترها

  • ورود

    ورود

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (entry: Entry) => void

    • ورود

      ورود

isRestorable()

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

برمی‌گرداند که آیا برنامه اجازه بازیابی ورودی با شناسه داده شده را دارد یا خیر.

پارامترها

  • شناسه

    رشته

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (isRestorable: boolean) => void

    • قابل بازیابی است

      بولی

بازگشت‌ها

  • قول <boolean>

    کروم ۱۱۷+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

isWritableEntry()

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

مشخص می‌کند که آیا این ورودی قابل نوشتن است یا خیر.

پارامترها

  • ورود

    ورود

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (isWritable: boolean) => void

    • قابل نوشتن است

      بولی

بازگشت‌ها

  • قول <boolean>

    کروم ۱۱۷+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

requestFileSystem()

قول کروم ۴۴+
chrome.fileSystem.requestFileSystem(
  options: RequestFileSystemOptions,
  callback?: function,
): Promise<FileSystem | undefined>

درخواست دسترسی به سیستم فایل برای یک درایو که با options.volumeId نمایش داده می‌شود. اگر options.writable روی true تنظیم شده باشد، سیستم فایل قابل نوشتن خواهد بود. در غیر این صورت، فقط خواندنی خواهد بود. گزینه writable نیاز به مجوز "fileSystem": {"write"} در مانیفست دارد. فقط برای برنامه‌های کیوسک که در جلسه کیوسک اجرا می‌شوند، در دسترس است. برای حالت کیوسک با راه‌اندازی دستی، یک کادر محاوره‌ای تأیید در بالای پنجره برنامه فعال نشان داده می‌شود. در صورت بروز خطا، fileSystem تعریف نشده و chrome.runtime.lastError تنظیم می‌شود.

پارامترها

بازگشت‌ها

  • قول <سیستم فایل | تعریف نشده>

    کروم ۱۱۷+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

restoreEntry()

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

در صورت قابل بازیابی بودن، ورودی فایل با شناسه‌ی داده شده را برمی‌گرداند. در غیر این صورت، این فراخوانی با خطای زمان اجرا مواجه خواهد شد.

پارامترها

  • شناسه

    رشته

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (entry: Entry) => void

    • ورود

      ورود

retainEntry()

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

یک شناسه (id) را برمی‌گرداند که می‌توان آن را به تابع restoreEntry ارسال کرد تا دسترسی به یک ورودی فایل مشخص شده بازیابی شود. فقط ۵۰۰ ورودی که اخیراً استفاده شده‌اند، حفظ می‌شوند، که در آن فراخوانی‌های retainEntry و restoreEntry به عنوان استفاده محسوب می‌شوند. اگر برنامه مجوز 'retainEntries' را در 'fileSystem' داشته باشد، ورودی‌ها به طور نامحدود حفظ می‌شوند. در غیر این صورت، ورودی‌ها فقط در حین اجرای برنامه و در طول راه‌اندازی مجدد حفظ می‌شوند.

پارامترها

  • ورود

    ورود

بازگشت‌ها

  • رشته

رویدادها

onVolumeListChanged

کروم ۴۴+
chrome.fileSystem.onVolumeListChanged.addListener(
  callback: function,
)

زمانی فراخوانی می‌شود که فهرستی از حجم‌های موجود تغییر کند.

پارامترها