آزمایش اولیه API File System Observer

توماس اشتاینر

File System Access API و Origin Private File System API هر دو به توسعه دهندگان اجازه می دهند به فایل ها و دایرکتوری ها در دستگاه کاربر دسترسی داشته باشند. اولی به توسعه دهندگان این امکان را می دهد که در سیستم فایل معمولی و قابل مشاهده توسط کاربر بخوانند و بنویسند، و دومی یک فایل خاص پنهان از سیستم فایل کاربر را باز می کند که برای مبدا هر سایت خصوصی است و دارای مزایای عملکردی خاصی است. نحوه تعامل توسعه دهندگان با فایل ها و دایرکتوری ها در هر دو مورد، از طریق اشیاء FileSystemHandle ، به طور دقیق تر، FileSystemFileHandle برای فایل ها، و FileSystemDirectoryHandle برای دایرکتوری ها است. تا کنون، اطلاع از تغییرات یک فایل یا دایرکتوری در هر یک از سیستم های فایل نیازمند نوعی نظرسنجی و مقایسه مهر زمانی lastModified یا حتی خود محتویات فایل بود.

File System Observer API، در نسخه آزمایشی اولیه کروم 129، آن را تغییر می‌دهد و به توسعه‌دهندگان اجازه می‌دهد به طور خودکار در صورت وقوع تغییرات هشدار داده شوند. این راهنما توضیح می دهد که چگونه کار می کند و چگونه این ویژگی را امتحان کنید.

موارد استفاده کنید

از File System Observer API در برنامه هایی استفاده کنید که باید به محض وقوع تغییرات احتمالی سیستم فایل مطلع شوند.

  • محیط های توسعه یکپارچه مبتنی بر وب (IDE) که نمایشی از درخت سیستم فایل پروژه را نشان می دهد.
  • برنامه هایی که تغییرات سیستم فایل را با سرور همگام می کنند. به عنوان مثال، یک فایل پایگاه داده SQLite.
  • برنامه‌هایی که باید از یک کارگر یا برگه دیگر به رشته اصلی سیستم فایل اطلاع دهند.
  • برنامه هایی که فهرستی از منابع را مشاهده می کنند، به عنوان مثال، برای بهینه سازی خودکار تصاویر.
  • تجربه‌هایی که از بارگذاری مجدد داغ سود می‌برند، مانند اسلایدهای مبتنی بر HTML که در آن بارگذاری مجدد با تغییر فایل آغاز می‌شود.

نحوه استفاده از File System Observer API

تشخیص ویژگی

برای اینکه ببینید آیا File System Observer API پشتیبانی می‌شود یا خیر، یک تست ویژگی را مانند مثال زیر اجرا کنید.

if ('FileSystemObserver' in self) {
  // The File System Observer API is supported.
}

یک ناظر سیستم فایل را راه اندازی کنید

با فراخوانی new FileSystemObserver() و ارائه تابع callback به عنوان آرگومان، یک مشاهده‌گر سیستم فایل را راه‌اندازی کنید.

const observer = new FileSystemObserver(callback);

مشاهده یک فایل یا دایرکتوری را شروع کنید

برای شروع مشاهده یک فایل یا دایرکتوری، متد asynchronous observe() نمونه FileSystemObserver را فراخوانی کنید. به این روش FileSystemHandle فایل یا دایرکتوری انتخاب شده را به عنوان آرگومان ارائه دهید. هنگام مشاهده دایرکتوری، یک آرگومان options اختیاری وجود دارد که به شما امکان می دهد انتخاب کنید که آیا می خواهید به صورت بازگشتی از تغییرات دایرکتوری مطلع شوید (یعنی برای خود دایرکتوری و همه زیر شاخه ها و فایل های موجود). گزینه پیش‌فرض این است که فقط خود دایرکتوری و فایل‌های حاوی مستقیم را مشاهده کنید.

// Observe a file.
await observer.observe(fileHandle);
// Observe a directory.
await observer.observe(directoryHandle);
// Observe a directory recursively.
await observer.observe(directoryHandle, {recursive: true});

عملکرد برگشت به تماس

هنگامی که تغییرات در سیستم فایل اتفاق می افتد، یک تابع فراخوانی با records تغییر سیستم فایل و خود observer به عنوان آرگومان های آن فراخوانی می شود. می‌توانید از آرگومان observer استفاده کنید، به‌عنوان مثال، وقتی فایل‌های مورد نظر شما همگی حذف می‌شوند، مشاهده‌گر را قطع کنید ( به توقف مشاهده سیستم فایل مراجعه کنید).

const callback = (records, observer) => {
  for (const record of records) {
    console.log('Change detected', record);
  }
};

رکورد تغییر سیستم فایل

هر رکورد تغییر سیستم فایل دارای ساختار زیر است. همه فیلدها فقط خواندنی هستند.

  • root (یک FileSystemHandle ): دسته ای که به تابع FileSystemObserver.observe() منتقل می شود.
  • changedHandle (یک FileSystemHandle ): دسته ای که تحت تأثیر تغییر سیستم فایل قرار می گیرد. این فیلد برای رویدادهای نوع "errored" ، "unknown" و "disappeared" null خواهد بود. برای اینکه ببینید کدام فایل یا دایرکتوری ناپدید شده است، از relativePathComponents استفاده کنید.
  • relativePathComponents (یک Array ): مسیر changedHandle نسبت به root .
  • type (a String ): نوع تغییر. انواع زیر ممکن است:
    • "appeared" : فایل یا دایرکتوری ایجاد شده یا به root منتقل شده است.
    • "disappeared" : فایل یا دایرکتوری حذف شده یا از root خارج شده است.
    • "modified" : فایل یا دایرکتوری اصلاح شد.
    • "moved" : فایل یا دایرکتوری در root منتقل شده است.
    • "unknown" : این نشان می دهد که صفر یا چند رویداد از دست رفته است. در پاسخ به این موضوع، توسعه‌دهندگان باید فهرست راهنمای تماشا شده را نظرسنجی کنند.
    • "errored" : مشاهده دیگر معتبر نیست. در این مورد، ممکن است بخواهید مشاهده سیستم فایل را متوقف کنید . این مقدار همچنین زمانی ارسال خواهد شد که حداکثر محدودیت مشاهدات در مبدا برسد. این محدودیت به سیستم عامل بستگی دارد و از قبل مشخص نیست. اگر این اتفاق بیفتد، سایت ممکن است تصمیم به امتحان مجدد بگیرد، اگرچه هیچ تضمینی وجود ندارد که سیستم عامل منابع کافی را آزاد کرده باشد. مورد دیگر برای ارسال این مقدار زمانی است که دسته مشاهده شده (یعنی ریشه مشاهده) حذف یا جابجا شود. در این حالت، ابتدا رویداد "disappeared" ارسال می شود و به دنبال آن یک رویداد "errored" می شود که نشان می دهد مشاهده دیگر معتبر نیست. در نهایت، زمانی که مجوز دایرکتوری یا دسته فایل حذف شود، این رویداد ارسال می شود.
  • relativePathMovedFrom (یک Array ، اختیاری): محل قبلی یک دسته جابجا شده. فقط زمانی در دسترس است که type "moved" .

مشاهده یک فایل یا دایرکتوری را متوقف کنید

برای متوقف کردن مشاهده یک FileSystemHandle ، متد unobserve() را فراخوانی کنید و آن را به عنوان آرگومان در دسته ارسال کنید.

observer.unobserve(fileHandle);

مشاهده سیستم فایل را متوقف کنید

برای توقف مشاهده سیستم فایل، نمونه FileSystemObserver را به صورت زیر قطع کنید.

observer.disconnect();

API را امتحان کنید

برای آزمایش File System Observer به صورت محلی، پرچم #file-system-observer در about:flags تنظیم کنید. برای آزمایش API با کاربران واقعی، در نسخه آزمایشی اصلی ثبت‌نام کنید و دستورالعمل‌ها را مطابق راهنمای آزمایش‌های اولیه Chrome دنبال کنید. نسخه آزمایشی اصلی از Chrome 129 (11 سپتامبر 2024) تا Chrome 134 (26 فوریه 2025) اجرا خواهد شد.

نسخه ی نمایشی

می‌توانید File System Observer API را در نسخه نمایشی تعبیه‌شده مشاهده کنید. کد منبع را بررسی کنید یا کد آزمایشی را در Glitch دوباره میکس کنید. نسخه ی نمایشی به طور تصادفی فایل ها را در یک فهرست مشاهده شده ایجاد، حذف یا تغییر می دهد و فعالیت آن را در قسمت بالای پنجره برنامه ثبت می کند. سپس تغییرات را همانطور که در قسمت پایین پنجره برنامه رخ می دهد ثبت می کند. اگر این را در مرورگری خواندید که از File System Observer API پشتیبانی نمی‌کند، تصویری از نسخه نمایشی را ببینید.

بازخورد

اگر بازخوردی در مورد شکل File System Observer API دارید، در مورد شماره 123 در مخزن WHATWG/fs نظر دهید.

قدردانی ها

این سند توسط دازول لی ، ناتان مموت ، اتین نوئل و ریچل اندرو بررسی شده است.