قراءة الملفات في JavaScript

Kayce Basques

Pete LePage

Thomas Steiner

إنّ اختيار الملفات والتفاعل معها على الجهاز المحلي للمستخدم هو أحد الميزات الأكثر استخدامًا على الويب. ويسمح هذا الإذن للمستخدمين باختيار الملفات وتحميلها إلى خادم، على سبيل المثال، عند مشاركة الصور أو إرسال مستندات تتعلّق بالضرائب. ويسمح أيضًا للمواقع الإلكترونية بقراءتها ومعالجتها بدون الحاجة إلى نقل البيانات عبر الشبكة. توضِّح هذه الصفحة كيفية استخدام JavaScript للتفاعل مع الملفات.

واجهة برمجة التطبيقات File System Access API الحديثة

توفّر واجهة برمجة التطبيقات File System Access API طريقة لقراءة الملفات والأدلة وكتابة البيانات فيها على النظام المحلي للمستخدم. وتتوفّر هذه الميزة في معظم المتصفّحات المستندة إلى Chromium، مثل Chrome وEdge. للاطّلاع على مزيد من المعلومات، يُرجى الرجوع إلى File System Access API.

بما أنّ واجهة برمجة التطبيقات File System Access API غير متوافقة مع جميع المتصفّحات، ننصح باستخدام browser-fs-access، وهي مكتبة مساعدة تستخدِم واجهة برمجة التطبيقات الجديدة حيثما كانت متاحة وتعود إلى الأساليب القديمة عندما لا تكون متاحة.

العمل مع الملفات بالطريقة الكلاسيكية

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

اختيار الملفات

هناك طريقتان أساسيتان لاختيار الملفات: باستخدام عنصر إدخال HTML واستخدام منطقة السحب والإفلات.

عنصر إدخال HTML

أسهل طريقة للمستخدمين لاختيار الملفات هي استخدام العنصر <input type="file"> ، وهو متاح في كل المتصفحات الرئيسية. عند النقر عليه، يسمح للمستخدم بتحديد ملف أو ملفات متعددة في حال تضمين السمة multiple ، وذلك باستخدام واجهة مستخدم تحديد الملفات المضمّنة في نظام التشغيل. عندما ينتهي المستخدم من اختيار ملف أو ملفات، يتم تشغيل الحدث change للعنصر. يمكنك الوصول إلى قائمة الملفات من event.target.files، وهو كائن FileList. كل عنصر في FileList هو كائن File.

<!-- The `multiple` attribute lets users select multiple files. -->
<input type="file" id="file-selector" multiple>
<script>
  const fileSelector = document.getElementById('file-selector');
  fileSelector.addEventListener('change', (event) => {
    const fileList = event.target.files;
    console.log(fileList);
  });
</script>

يتيح المثال التالي للمستخدم اختيار ملفات متعددة باستخدام واجهة مستخدم اختيار الملفات المضمّنة في نظام التشغيل، ثم تسجيل كل ملف تم اختياره في وحدة التحكّم.

حصر أنواع الملفات التي يمكن للمستخدمين اختيارها

في بعض الحالات، قد تحتاج إلى حصر أنواع الملفات التي يمكن للمستخدمين اختيارها. على سبيل المثال، يجب أن يقبل تطبيق تعديل الصور الصور فقط، وليس الملفات النصية. لضبط قيود أنواع الملفات، أضِف سمة accept إلى عنصر الإدخال لتحديد أنواع الملفات المقبولة:

<input type="file" id="file-selector" accept=".jpg, .jpeg, .png">

السحب والإفلات المخصّص

في بعض المتصفّحات، يكون العنصر <input type="file"> أيضًا هدف إسقاط، ما يسمح للمستخدمين بسحب الملفات وإفلاتها في تطبيقك. ومع ذلك، فإنّ هدف الإسقاط هذا صغير ويمكن أن يكون من الصعب استخدامه. بدلاً من ذلك، بعد توفير الميزات الأساسية باستخدام عنصر <input type="file">، يمكنك توفير سطح إشغال شاشة كبير ومخصّص لعمليات السحب والإفلات.

اختيار منطقة إسقاط المحتوى

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

يتيح تطبيق Squoosh لضغط الصور للمستخدم سحب صورة إلى أي مكان في النافذة، والنقر على اختيار صورة لتشغيل عنصر<input type="file">. أيًا كانت المنطقة التي تختارها لعرض الملفات، احرص على توضيح للمستخدم أنّه يمكنه سحب الملفات إلى تلك المساحة.

تحديد منطقة الإسقاط

لتفعيل عنصر كمنطقة سحب وإفلات، أنشئ أدوات معالجة لحدثين: dragover وdrop. يعدّل الحدث dragover واجهة مستخدم المتصفّح للإشارة بصريًا إلى أنّه يتم إنشاء نسخة من الملف من خلال إجراء السحب والإفلات. يتم تشغيل الحدث drop بعد أن يسقط المستخدم الملفات على السطح. كما هو الحال مع عنصر الإدخال، يمكنك الوصول إلى قائمة الملفات من event.dataTransfer.files، وهو عنصر FileList. كل عنصر في FileList هو عنصر File.

const dropArea = document.getElementById('drop-area');

dropArea.addEventListener('dragover', (event) => {
  event.stopPropagation();
  event.preventDefault();
  // Style the drag-and-drop as a "copy file" operation.
  event.dataTransfer.dropEffect = 'copy';
});

dropArea.addEventListener('drop', (event) => {
  event.stopPropagation();
  event.preventDefault();
  const fileList = event.dataTransfer.files;
  console.log(fileList);
});

يوقف event.stopPropagation() وevent.preventDefault() السلوك التلقائي للمتصفّح ويسمح بتنفيذ الرمز البرمجي بدلاً من ذلك. بدون هذه الإعدادات، سينتقل المتصفّح بعيدًا عن صفحتك ويفتح الملفات التي أسقطها المستخدم في نافذة المتصفّح.

للاطّلاع على عرض توضيحي مباشر، يُرجى الرجوع إلى السحب والإفلات المخصّص.

ماذا عن الأدلة؟

لا تتوفّر طريقة جيدة للوصول إلى دليل باستخدام JavaScript.

تتيح سمة webkitdirectory في العنصر <input type="file"> للمستخدم اختيار دليل أو أدلة. تتوفّر هذه الميزة في معظم المتصفّحات الرئيسية باستثناء Firefox لأجهزة Android وSafari على أجهزة iOS.

في حال تفعيل ميزة السحب والإفلات، قد يحاول المستخدم سحب دليل إلى منطقة الإفلات. عند بدء حدث إسقاط الملفات، يتضمّن الحدث عنصر File للملف ، ولكن لا يمنح إذن الوصول إلى أي من الملفات في الدليل.

قراءة البيانات الوصفية للملف

يحتوي عنصر File على بيانات وصفية عن الملف. تقدِّم معظم المتصفّحات اسم الملف وحجمه ونوع MIME، ولكن قد تقدِّم المتصفّحات المختلفة معلومات مختلفة أو إضافية، وذلك استنادًا إلى المنصة.

function getMetadataForFileList(fileList) {
  for (const file of fileList) {
    // Not supported in Safari for iOS.
    const name = file.name ? file.name : 'NOT SUPPORTED';
    // Not supported in Firefox for Android or Opera for Android.
    const type = file.type ? file.type : 'NOT SUPPORTED';
    // Unknown cross-browser support.
    const size = file.size ? file.size : 'NOT SUPPORTED';
    console.log({file, name, type, size});
  }
}

يمكنك الاطّلاع على طريقة عمل هذه الميزة في input-type-file الإصدار التجريبي.

قراءة محتوى ملف

استخدِم FileReader لقراءة محتوى عنصر File في الذاكرة. يمكنك توجيه FileReader إلى قراءة ملف كمخطّط تخزين مؤقت للصفيف أو عنوان URL للبيانات أو نص:

function readImage(file) {
  // Check if the file is an image.
  if (file.type && !file.type.startsWith('image/')) {
    console.log('File is not an image.', file.type, file);
    return;
  }

  const reader = new FileReader();
  reader.addEventListener('load', (event) => {
    img.src = event.target.result;
  });
  reader.readAsDataURL(file);
}

يقرأ هذا المثال File يقدّمه المستخدم، ثم يحوله إلى عنوان URL للبيانات، ويستخدم عنوان URL للبيانات هذا لعرض الصورة في عنصر img. لمعرفة كيفية التأكّد من اختيار المستخدم لملف صورة، يمكنك الرجوع إلى الإصدار التمهيدي من read-image-file.

تتبُّع مستوى تقدُّم قراءة ملف

عند قراءة ملفات كبيرة، قد يكون من المفيد توفير بعض ميزات تجربة المستخدم لإعلام المستخدم بمدى تقدّم عملية القراءة. لهذا الغرض، استخدِم الحدث progress الذي يوفّره FileReader. يتضمّن حدث progress سمتَين: loaded (الكمية المقروءة) وtotal (الكمية المطلوب قراءتها).

function readFile(file) {
  const reader = new FileReader();
  reader.addEventListener('load', (event) => {
    const result = event.target.result;
    // Do something with result
  });

  reader.addEventListener('progress', (event) => {
    if (event.loaded && event.total) {
      const percent = (event.loaded / event.total) * 100;
      console.log(`Progress: ${Math.round(percent)}`);
    }
  });
  reader.readAsDataURL(file);
}

الصورة الرئيسية لفنسانت بوتا من Unsplash