File System Observer एपीआई का ऑरिजिन ट्रायल

Thomas Steiner

File System Access API और Origin Private File System API, दोनों ही डेवलपर को उपयोगकर्ता के डिवाइस पर मौजूद फ़ाइलें और डायरेक्ट्री ऐक्सेस करने की अनुमति देते हैं. पहले वाले फ़ाइल सिस्टम की मदद से डेवलपर, उपयोगकर्ताओं को दिखने वाले सामान्य फ़ाइल सिस्टम को पढ़ सकते हैं और उसमें बदलाव कर सकते हैं. बाद वाला विकल्प, उपयोगकर्ता के फ़ाइल सिस्टम से छिपा एक खास फ़ाइल सिस्टम खोलता है. यह हर साइट की ऑरिजिन के लिए निजी होता है और इसे परफ़ॉर्मेंस के कुछ फ़ायदे मिलते हैं. दोनों ही मामलों में, डेवलपर FileSystemHandle ऑब्जेक्ट, फ़ाइलों के लिए FileSystemFileHandle, और डायरेक्ट्री के लिए FileSystemDirectoryHandle का इस्तेमाल करके, फ़ाइलों और डायरेक्ट्री के साथ इंटरैक्ट करते हैं. अब तक, किसी भी फ़ाइल सिस्टम में फ़ाइल या डायरेक्ट्री में होने वाले बदलावों के बारे में जानकारी होने के लिए, किसी न किसी तरह की पोलिंग और lastModified टाइमस्टैंप या फ़ाइल के कॉन्टेंट की तुलना करना ज़रूरी था.

Chrome 129 के ऑरिजिन ट्रायल में, File System Observer API से, इसमें बदलाव किया जाता है. साथ ही, कोई बदलाव होने पर डेवलपर को अपने-आप सूचना मिलती है. इस गाइड में बताया गया है कि यह सुविधा कैसे काम करती है और इसका इस्तेमाल कैसे किया जा सकता है.

उपयोग के उदाहरण

फ़ाइल सिस्टम में होने वाले संभावित बदलावों के बारे में जानकारी देने के लिए, यह ज़रूरी है कि उन ऐप्लिकेशन में File System Observer API का इस्तेमाल किया जाता हो.

  • वेब पर आधारित इंटिग्रेटेड डेवलपमेंट एनवायरमेंट (आईडीई) जो प्रोजेक्ट के फ़ाइल सिस्टम ट्री को दिखाते हैं.
  • ऐसे ऐप्लिकेशन जो सर्वर के साथ फ़ाइल सिस्टम के बदलावों को सिंक करते हैं. उदाहरण के लिए, SQLite डेटाबेस फ़ाइल.
  • वे ऐप्लिकेशन जिन्हें किसी वर्कर या किसी दूसरे टैब से, फ़ाइल सिस्टम के मुख्य थ्रेड में हुए बदलावों की सूचना देने की ज़रूरत होती है.
  • ऐसे ऐप्लिकेशन जो संसाधनों की डायरेक्ट्री पर नज़र रखते हैं. जैसे, इमेज अपने-आप ऑप्टिमाइज़ होने की सुविधा.

फ़ाइल सिस्टम ऑब्ज़र्वर एपीआई को इस्तेमाल करने का तरीका

सुविधा की पहचान

यह देखने के लिए कि File System Observer API काम करता है या नहीं, इस उदाहरण में बताए गए तरीके से फ़ीचर टेस्ट करें.

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

फ़ाइल सिस्टम ऑब्ज़र्वर शुरू करना

फ़ाइल सिस्टम पर्यवेक्षक को new FileSystemObserver() कॉल करके शुरू करें. साथ ही, उसे तर्क के तौर पर callback फ़ंक्शन दें.

const observer = new FileSystemObserver(callback);

किसी फ़ाइल या डायरेक्ट्री को देखना शुरू करें

किसी फ़ाइल या डायरेक्ट्री को मॉनिटर करना शुरू करने के लिए, FileSystemObserver इंस्टेंस के एसिंक्रोनस observe() तरीके को कॉल करें. चुनी गई फ़ाइल या डायरेक्ट्री के 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): वह हैंडल जिस पर फ़ाइल सिस्टम में बदलाव का असर पड़ा है.
  • relativePathComponents (Array): root से जुड़े changedHandle का पाथ.
  • type (String): बदलाव का टाइप. इस तरह की समस्याएं हो सकती हैं:
    • "appeared": फ़ाइल या डायरेक्ट्री को बनाया गया था या root में ले जाया गया था.
    • "disappeared": फ़ाइल या डायरेक्ट्री को मिटा दिया गया है या root से बाहर ले जाया गया है.
    • "modified": फ़ाइल या डायरेक्ट्री में बदलाव किया गया.
    • "moved": फ़ाइल या डायरेक्ट्री को root में ले जाया गया था.
    • "unknown": इससे पता चलता है कि शून्य या उससे ज़्यादा इवेंट छूट गए थे. इसके जवाब में, डेवलपर को देखी गई डायरेक्ट्री की पोल करनी चाहिए.
    • "errored": निगरानी अब मान्य नहीं है. ऐसे में, आपको फ़ाइल सिस्टम को मॉनिटर करने की सुविधा बंद करनी पड़ सकती है.
  • relativePathMovedFrom (Array ज़रूरी नहीं): वह पता जहां किसी जगह को ले जाया गया था. यह विकल्प सिर्फ़ तब उपलब्ध होता है, जब type की वैल्यू "moved" होती है.

किसी फ़ाइल या डायरेक्ट्री को देखना बंद करें

FileSystemHandle को देखने से रोकने के लिए, unobserve() तरीके को कॉल करें और हैंडल को आर्ग्युमेंट के तौर पर पास करें.

observer.unobserve(fileHandle);

फ़ाइल सिस्टम को मॉनिटर करना बंद करें

फ़ाइल सिस्टम को मॉनिटर करना बंद करने के लिए, FileSystemObserver इंस्टेंस को इस तरीके से डिसकनेक्ट करें.

observer.disconnect();

एपीआई आज़माएं

File System Observer API को स्थानीय तौर पर टेस्ट करने के लिए, about:flags में #file-system-observer फ़्लैग सेट करें. असली उपयोगकर्ताओं के साथ एपीआई की जांच करने के लिए, ऑरिजिन ट्रायल के लिए साइन अप करें. इसके बाद, Chrome ऑरिजिन ट्रायल गाइड में दिए गए निर्देशों का पालन करें. ऑरिजिन ट्रायल, Chrome 129 (11 सितंबर, 2024) से Chrome 134 (26 फ़रवरी, 2025) तक चलेगा.

डेमो

एम्बेड किए गए डेमो में फ़ाइल सिस्टम ऑब्ज़र्वर एपीआई को काम करते हुए देखा जा सकता है. सोर्स कोड देखें या Glitch पर बनाया गया डेमो कोड रीमिक्स करें. डेमो के दौरान निगरानी की जा रही डायरेक्ट्री में किसी भी क्रम में फ़ाइलें बनाई जाती हैं, मिटाई जाती हैं या उनमें बदलाव किए जाते हैं. साथ ही, यह ऐप्लिकेशन विंडो के ऊपरी हिस्से में अपनी गतिविधि को लॉग करता है. इसके बाद, यह ऐप्लिकेशन विंडो के निचले हिस्से में होने वाले बदलावों को लॉग कर देता है. अगर आपने इसे किसी ऐसे ब्राउज़र पर पढ़ा है जो फ़ाइल सिस्टम ऑब्ज़र्वर एपीआई के साथ काम नहीं करता, तो डेमो का स्क्रीनशॉट देखें.

सुझाव/राय दें या शिकायत करें

अगर फ़ाइल सिस्टम ऑब्ज़र्वर एपीआई के आकार के बारे में आपका कोई सुझाव है, तो WhatWG/fs डेटा स्टोर करने की जगह में समस्या #123 पर टिप्पणी करें.

स्वीकार की गई

इस दस्तावेज़ की समीक्षा डैसल ली, नैथन मेमोट, एटियन नोएल, और रेचल एंड्रयू ने की है.