عرض مصدر HTML/input/file

<noinclude>{{DISPLAYTITLE:الحقل <code>file</code>}}</noinclude>
عناصر <code>[[HTML/input|<input>]]</code> ذات النوع <code>file</code> تسمح للمستخدم باختيار ملف أو أكثر لرفعها إلى الخادوم أو تعديلها باستخدام الواجهة البرمجية <code>File</code>.
== الخاصية <code>value</code> ==
تحتوي الخاصية <code>value</code> في الحقل <code>file</code> على سلسلة نصية (<code>DOMString</code>) التي تُمثِّل المسار إلى الملف (أو الملفات) المختارة. بعض الأمور التي عليك أن تضعها بالحسبان:
* إذا تم اختيار عدِّة ملفات، فقيمة الخاصية <code>value</code> ستُمثِّل أوّل ملف مختار، لكن يمكن الوصول إلى الملفات الأخرى عبر الخاصية <code>FileList</code> في DOM التابعة للعنصر <code>[[HTML/input|<input>]]</code>.
* إذا لم يتم اختيار ملف بعد، فستكون قيمة الخاصية <code>value</code> فارغةً.
* سيتم [https://www.w3.org/TR/html5/forms.html#fakepath-srsly إسباق السلسلة النصية بالمسار <code>C:\fakepath\</code>‎] لمنع البرمجيات الخبيثة من معرفة بنية نظام الملفات عند المستخدم.
== استخدام حقل رفع الملفات ==
=== حقل رفع ملفات بسيط ===
<syntaxhighlight lang="html">
<form>
 <div>
   <label for="file">Choose file to upload</label>
   <input type="file" id="file" name="file" multiple>
 </div>
 <div>
   <button>Submit</button>
 </div>
</form>
</syntaxhighlight>بغض النظر عن جهاز المستخدم أو نظام التشغيل، سيوفِّر هذا الحقل زرًا سيفتح نافذة منتقي الملفات للسماح للمستخدم باختيار ملف.

استخدام الخاصية <code>multiple</code> -كما في المثال أعلاه- سيُمكِّن المستخدم من اختيار أكثر من ملف معًا، ويمكن للمستخدم اختيار عدِّة ملفات في منتقي الملفات بأي طريقة يسمح بها نظام تشغيله (مثلًا: بالضغط على زر <code>Shift</code> أو <code>Ctrl</code> والنقر بالفأرة). إذا كنت تريد أن تسمح للمستخدم باختيار ملف واحد في كل حقل <code>file</code> فاحذف الخاصية <code>multiple</code>.

عند إرسال النموذج في المثال السابق، فسيُضاف اسم كل ملف مُختار إلى رابط URL كما يلي: ‎<code>?file=file1.txt&file=file2.txt</code>.
=== الحصول على معلومات عن الملفات المختارة ===
ستُعاد الملفات المختارة عبر الخاصية <code>HTMLInputElement.files</code>، التي ستُعيد الكائن <code>FileList</code> الذي يحتوي على قائمة بكائنات من النوع <code>File</code>، وسيسلك الكائن <code>FileList</code> سلوك مصفوفة، أي بإمكاننا استخدام الخاصية <code>length</code> عليه للحصول على عدد الملفات المختارة.

كل كائن <code>File</code> يحتوي على المعلومات الآتية:
* <code>name</code>: اسم الملف.
* <code>lastModified</code>: رقم يُمثِّل التاريخ الذي عُدِّل فيه الملف آخر مرة على شكل بصمة وقت (Unix timestamp).
* <code>lastModifiedDate</code>: كائن <code>Date</code> يُمثِّل الوقت والتاريخ الذي عُدِّل فيه الملف آخر مرة.
* <code>size</code>: رقم يُمثِّل حجم الملف التخزيني مقدرًا بالبايت.
* <code>type</code>: سلسلة نصية (<code>DOMString</code>) تمثِّل نوع MIME للملف.

=== وضع قيود على أنواع الملفات المسموحة ===
لن ترغب في أغلبية الأوقات في السماح للمستخدم برفع أيّ نوعٍ يشاء من الملفات، فلو كان حقل رفع الملفات يستخدم لرفع صورة لحساب المستخدم، فربما تريد السماح لأنواع الصور المتوافقة مع الويب مثل JPEG أو PNG فقط.

يمكن تحديد أنواع الملفات التي يقبلها الخادوم باستخدام الخاصية <code>accept</code>، وبقية الأنواع سيتجاهلها المتصفح، يجب أن تكون قيمة هذه الخاصية هي قائمة مفصولة بفاصلة لمُحدِّدات أنواع الملفات الآتية:
* امتداد الملف الذي يجب أن يبدأ بنقطة (مثل ‎<code>.jpg</code> أو ‎<code>.png</code> أو ‎<code>.doc</code>).
* نوع MIME صحيح
* السلسلة النصية <code>audio/*‎</code> التي تُمثِّل الملفات الصوتية.
* السلسلة النصية <code>video/*‎</code> التي تُمثِّل ملفات الفيديو.
* السلسلة النصية <code>image/*‎</code> التي تُمثِّل الصور.
هذا مثال عن استخدام حقل رفع الملفات للسماح للمستخدم برفع صورة لحسابه بصيغة JPEG أو PNG:<syntaxhighlight lang="html">
<form>
  <div>
    <label for="profile_pic">Choose file to upload</label>
    <input type="file" id="profile_pic" name="profile_pic"
          accept=".jpg, .jpeg, .png">
  </div>
  <div>
    <button>Submit</button>
  </div>
</form>
</syntaxhighlight>إذا حاولت اختيار ملف في المثال السابق فسترى أنَّ منتقي الملفات لا يسمح لك إلا باختيار أنواع الملفات المُحدَّدة عبر الخاصية <code>accept</code> (قد يختلف سلوك منتقي الملفات بين المتصفحات وبين أنظمة التشغيل).

لا تتحقق الخاصية <code>accept</code> من نوع الملفات المُحدَّدة، وإنما توفّر «تلميحةً» للمتصفحات لكي توجِّه المستخدم إلى اختيار نوع الملفات الصحيح، لكن من الممكن (في أغلبية الحالات) أن يتمكن المستخدم من تفعيل خيار في منتقي الملفات لجعل جميع الملفات قابلة للاختيار ومن ثم اختيار نوع ملفات غير صحيح.

وبالتالي علينا أن نحرص على التحقق من نوع الملف بالطرائق المناسبة في جهة الخادوم.

== أمثلة ==
سنُنشِئ في هذا الملف منتقي ملفات متقدم نسبيًا الذي يستفيد من معلومات الملف المتوافرة في خاصية <code>HTMLInputElement.files</code>، وسنستعرض بعض الحيل المفيدة.

يمكنك النظر إلى [https://github.com/mdn/learning-area/blob/master/html/forms/file-examples/file-example.html الشيفرة الكاملة] أو تجربة [https://mdn.github.io/learning-area/html/forms/file-examples/file-example.html المثال الحي]، لكننا لن نشرح أنماط CSS لأن تركيزنا سيكون على JavaScript.

لننظر أوّلًا إلى شيفرة HTML:<syntaxhighlight lang="html">
<form>
  <div>
    <label for="image_uploads">Choose images to upload (PNG, JPG)</label>
    <input type="file" id="image_uploads" name="image_uploads" accept=".jpg, .jpeg, .png" multiple>
  </div>
  <div class="preview">
    <p>No files currently selected for upload</p>
  </div>
  <div>
    <button>Submit</button>
  </div>
</form>
</syntaxhighlight>الشيفرة السابقة تشبه ما قد سلف، لذا لا حاجة إلى شرحها.

أما في شيفرة JavaScript فحصلنا في أوّل عدِّة أسطر منها على مرجعيات إلى عنصر <code>[[HTML/input|<input>]]</code> وعنصر <code>[[HTML/div|<nowiki><div></nowiki>]]</code> ذي الفئة <code>preview</code>. ثم سنخفي الحقل <code>file</code> لأنَّ شكله الافتراضي بشع وغير متناسق في جميع المتصفحات، يمكن تفعيل العنصر بالضغط على العنصر <code>[[HTML/label|<label>]]</code> المرتبط معه، لذا من الأفضل -بصريًا- إخفاء الحقل وتنسيق اللافتة الخاصة به لتشبه الزر، لكي يعرف المستخدم أنَّ بإمكانه الضغط عليها إذا أراد رفع الملفات:<syntaxhighlight lang="javascript">
var input = document.querySelector('input');
var preview = document.querySelector('.preview');

input.style.opacity = 0;
</syntaxhighlight>ملاحظة: استخدمنا الخاصية <code>opacity</code> لإخفاء حقل رفع الملفات بدلًا من <code>visibility: hidden</code> أو <code>display: none</code> لأن التقنيات المساعدة في قابلية الوصول ستُفسِّر آخر خاصيتين على أنهما تجعلان حقل رفع الملفات غير تفاعلي.

ثم سنضيف دالة لمعالجة الأحداث المرتبطة بالحقل عندما يتم تغيير قيمته (أي عندما يختار المستخدم بعض الملفات)، وقوع الحدث <code>change</code> سيؤدي إلى استدعاء الدالة <code>updateImageDisplay()‎</code> التي سنعرفها لاحقًا.<syntaxhighlight lang="javascript">
input.addEventListener('change', updateImageDisplay);

</syntaxhighlight>عند استدعاء الدالة <code>updateImageDisplay()‎</code> فستقوم الشيفرة بما يلي:
* استخدام حلقة <code>while</code> لحذف المحتوى السابق لعنصر <code>[[HTML/div|<nowiki><div></nowiki>]]</code> الذي يستخدم لعرض مصغرات للصور المرفوعة.
* الحصول على الكائن <code>FileList</code> الذي يحتوي على معلومات عن جميع الملفات المختارة، وتخزينه في متغير باسم <code>curFiles</code>.
* التحقق إذا تم اختيار أيّة ملفات، عبر النظر إن كانت قيمة الخاصية <code>curFile.length</code> تساوي <code>0</code>، فإذا كانت كذلك فستُطبَع رسالة إلى عنصر <code>[[HTML/div|<nowiki><div></nowiki>]]</code> (الذي يستخدم لعرض المصغرات) تُشير إلى عدم تحديد أيّة ملفات.
* إذا تم اختيار ملفات، فسنمر عليها كلها بحلقة تكرار ونطبع معلومات عنها في عنصر <code>[[HTML/div|<nowiki><div></nowiki>]]</code>.
* لاحظ أننا نستخدم الدالة <code>validFileType()‎</code> للتأكد أنَّ نوع الملف صحيح (أي أنَّه صورة).
* إذا كان نوع الملف صالحًا، فسوف:
** نطبع اسمه وحجمه التخزيني داخل العنصر <code>[[HTML/div|<nowiki><div></nowiki>]]</code> (سنحصل عليهما من الخاصيتين <code>curFiles[i].name</code> و <code>curFiles[i].size</code>)، الدالة <code>returnFileSize()‎</code> ستُعيد حجم الملف بعد تنسيقه بصيغة مقروءة (مع وضع الواحدة bytes أو KB أو MB) فالمتصفحات تُعيد حجم الملف بواحدة البايت دومًا.
** توليد مُصغرات للصور باستدعاء الدالة <code>‎window.URL.createObjectURL(curFiles[i])‎</code> وتقليل حجم الصورة باستخدام CSS ثم إضافة الصورة في القائمة أيضًا.
* أما إذا كان نوع الملف غير صالح، فسنعرض رسالة ضمن القائمة تخبر المستخدم بأن يختار ملفًا من النوع الصحيح.
<syntaxhighlight lang="javascript">
function updateImageDisplay() {
  while(preview.firstChild) {
    preview.removeChild(preview.firstChild);
  }

  var curFiles = input.files;
  if(curFiles.length === 0) {
    var para = document.createElement('p');
    para.textContent = 'No files currently selected for upload';
    preview.appendChild(para);
  } else {
    var list = document.createElement('ol');
    preview.appendChild(list);
    for(var i = 0; i < curFiles.length; i++) {
      var listItem = document.createElement('li');
      var para = document.createElement('p');
      if(validFileType(curFiles[i])) {
        para.textContent = 'File name ' + curFiles[i].name + ', file size ' + returnFileSize(curFiles[i].size) + '.';
        var image = document.createElement('img');
        image.src = window.URL.createObjectURL(curFiles[i]);

        listItem.appendChild(image);
        listItem.appendChild(para);

      } else {
        para.textContent = 'File name ' + curFiles[i].name + ': Not a valid file type. Update your selection.';
        listItem.appendChild(para);
      }

      list.appendChild(listItem);
    }
  }
}
</syntaxhighlight>الدالة <code>validFileType()‎</code> تأخذ الكائن <code>File</code> كوسيط، ثم ستمر على مصفوفة بأنواع الملفات المسموحة وتتحقق من مطابقة نوع الملف لأحدها، وإن عُثِرَ على مُطابقة فستعيد الدالة القيمة <code>true</code> وإلا فستُعيد <code>false</code>.<syntaxhighlight lang="javascript">
var fileTypes = [
  'image/jpeg',
  'image/pjpeg',
  'image/png'
]

function validFileType(file) {
  for(var i = 0; i < fileTypes.length; i++) {
    if(file.type === fileTypes[i]) {
      return true;
    }
  }

  return false;
}
</syntaxhighlight>تأخذ الدالة <code>returnFileSize()‎</code> عددًا (مُقدرًا بالبايت، ومأخوذًا من الخاصية <code>size</code>) وتحوِّله إلى حجم سهل القراءة:<syntaxhighlight lang="javascript">
function returnFileSize(number) {
  if(number < 1024) {
    return number + 'bytes';
  } else if(number > 1024 && number < 1048576) {
    return (number/1024).toFixed(1) + 'KB';
  } else if(number > 1048576) {
    return (number/1048576).toFixed(1) + 'MB';
  }
}
</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable" style="width: 50%;"
 !| Chrome
 ! Firefox
 ! Edge
 ! Safari
 ! Opera
|-
|مدعوم
|مدعوم
|مدعوم
|مدعوم
|مدعوم
|}
[[تصنيف:HTML|{{SUBPAGENAME}}]]
[[تصنيف:HTML Forms|{{SUBPAGENAME}}]]
[[تصنيف:HTML Input Types|{{SUBPAGENAME}}]]