HTML input type="file" ile Dosya Yükleme

Dosya alanının teknik özeti

MDN'in her input türü için verdiği "Technical summary" tablosu, o türün hangi öznitelikleri ve olayları desteklediğini tek bakışta gösterir. Dosya alanı için bu tablonun Türkçe özeti şöyledir:

Tablo bir şeyi de dolaylı olarak söyler: minlength, pattern veya placeholder gibi metin alanlarına ait öznitelikler dosya alanında yer almaz. Dosya alanında HTML ile koyabileceğiniz doğrulama kuralı yalnızca zorunluluktur.

Dosyayı sunucuya göndermek: method ve enctype

Bir form varsayılan olarak verileri application/x-www-form-urlencoded biçiminde kodlar. Bu biçim dosyanın içeriğini taşımaz. MDN'in <form> sayfası, formda dosya alanı varsa enctype değerinin multipart/form-data olması gerektiğini söyler; enctype ise yalnızca method="post" olduğunda anlam taşır. Bu iki öznitelikten biri eksikse dosyanın kendisi sunucuya gitmez.

<form action="/yukle" method="post" enctype="multipart/form-data">
  <label for="belge">Yüklenecek belge</label>
  <input type="file" id="belge" name="belge" required />
  <button type="submit">Yükle</button>
</form>

Aynı formu method="get" ile gönderirseniz ne olur? MDN'in multiple sayfasındaki açıklamaya göre bu durumda seçilen her dosyanın yalnızca adı URL parametresi olarak eklenir: ?uploads=img1.jpg&uploads=img2.svg. Dosya içeriği gitmez. Bir gönder düğmesi formenctype özniteliğiyle formun enctype değerini o düğme için geçersiz kılabilir; ayrıntılar button etiketi yazısında.

value neden C:\fakepath\ ile başlar?

Dosya alanının value değeri seçilen dosyanın yolunu temsil eden bir dizedir. Henüz dosya seçilmemişse boş dizedir. Birden çok dosya seçildiyse value listedeki ilk dosyayı gösterir; diğerlerine files özelliğiyle ulaşılır. MDN, bu değerin gerçek yol olmadığını, her zaman C:\fakepath\ önekli dosya adı olduğunu ve bunun kötü amaçlı yazılımların kullanıcının dosya yapısını tahmin etmesini önlemek için yapıldığını açıklar. Bu davranış belirtimde tanımlıdır.

İkinci önemli kural: dosya alanının değerini betikle ayarlayamazsınız. MDN'e göre input.value = "foo" gibi bir atama hiçbir etki yapmaz. Bu da güvenlikle ilgilidir; bir sayfa kullanıcının haberi olmadan diskinden dosya seçemez.

accept: hangi dosya türleri önerilsin?

accept, virgülle ayrılmış bir veya daha fazla "benzersiz dosya türü belirteci" alır. MDN beş biçim tanımlar:

• Nokta ile başlayan, büyük küçük harf duyarsız bir dosya uzantısı: .jpg, .pdf, .doc.
• Uzantı içermeyen geçerli bir MIME türü: image/png, application/pdf.
• audio/*: herhangi bir ses dosyası.
• video/*: herhangi bir video dosyası.
• image/*: herhangi bir görsel dosyası.

Bu belirteçler karıştırılabilir. Örneğin görsel olarak sunulabilecek her şeyi ve PDF dosyalarını kabul etmek için accept="image/*,.pdf" yazılır. Aynı dosya türü birden çok şekilde tanımlanabildiği için MDN, belirli bir biçim istediğinizde kapsamlı bir liste vermenizi önerir. Word belgeleri için verdiği örnek hem uzantıları hem MIME türlerini içerir:

<label for="cv">Özgeçmişiniz (Word belgesi)</label>
<input
  type="file"
  id="cv"
  name="cv"
  accept=".doc,.docx,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document" />

<label for="avatar">Profil fotoğrafı (PNG veya JPEG)</label>
<input type="file" id="avatar" name="avatar" accept="image/png, image/jpeg" />

MDN'in notuna göre accept="image/*" kullanıldığında birçok mobil cihaz kullanıcıya kamerayla fotoğraf çekme seçeneği de sunar. Bir zamanlar accept özniteliği <form> öğesinde de destekleniyordu; MDN bunun kaldırıldığını ve özniteliğin artık yalnızca dosya alanına ait olduğunu belirtir.

multiple: birden çok dosya seçmek

multiple Boolean özniteliği eklendiğinde kullanıcı seçicide birden fazla dosya seçebilir. Seçimin nasıl yapılacağı platforma bağlıdır; MDN, Shift veya Control tuşunu basılı tutup tıklamayı örnek verir. Öznitelik yoksa her alan için tek dosya seçilebilir. Çoklu seçim yapılabildiğini etikette belirtmek iyi bir uygulamadır; MDN de multiple kullanılan her yerde kullanıcıya birden çok değer girebileceğini söylemenizi önerir.

<label for="galeri">Galeri görselleri (birden çok seçebilirsiniz; JPG, PNG, GIF)</label>
<input type="file" id="galeri" name="galeri" accept=".jpg, .jpeg, .png, .gif" multiple />

capture: kameradan veya mikrofondan doğrudan almak

capture, accept görsel veya video istediğinde yeni bir kaydın hangi cihazla yapılacağını belirtir. İki değeri vardır: user kullanıcıya bakan kamerayı veya mikrofonu, environment dışarıya bakan kamerayı veya mikrofonu ister. Öznitelik yoksa tarayıcı ne yapacağına kendisi karar verir; istenen yön kullanılamıyorsa kendi varsayılanına dönebilir. MDN, capture özniteliğinin daha önce bir Boolean öznitelik olduğunu da not eder.

<label for="selfie">Yüzünüzün fotoğrafını çekin</label>
<input type="file" id="selfie" name="selfie" accept="image/*" capture="user" />

<label for="hasar">Hasarlı ürünün fotoğrafını arka kamerayla çekin</label>
<input type="file" id="hasar" name="hasar" accept="image/*" capture="environment" />

MDN'e göre bu öznitelik mobil cihazlarda daha iyi çalışır; masaüstü bir bilgisayarda büyük olasılıkla normal dosya seçicisi açılır. Bu yüzden capture kullandığınız alanın, kamera olmadan da normal dosya seçimiyle çalışabileceğini varsayarak formu tasarlayın.

Seçilen dosyalar: files özelliği

Seçilen dosyalara HTMLInputElement.files özelliğiyle ulaşılır. Bu özellik dizi gibi davranan bir FileList nesnesi döndürür; length değeri seçilen dosya sayısını verir. Listedeki her File nesnesi şu bilgileri taşır:

Kullanıcı seçimi değiştirmediğinde, yani aynı dosyaları yeniden seçtiğinde ya da seçiciyi iptal düğmesi veya Escape tuşuyla kapattığında alanda cancel olayı tetiklenir. Seçim değiştiğinde ise change ve input olayları çalışır. Bunlar betik tarafının konusudur; temeller için JavaScript öğrenme rehberine bakabilirsiniz.

Dosya boyutunu sınırlamak

Doğrulama öznitelikleri arasında dosya boyutu için bir kısıt yoktur. Dosya alanında HTML ile koyabileceğiniz tek doğrulama kuralı required'dır; dosya seçilmezse valueMissing oluşur. MDN'in doğrulama rehberi, gönderimden önce boyutu kontrol etmek için Constraint Validation API'deki setCustomValidity() metodunu File API ile birleştiren bir örnek verir. Aşağıdaki kısa betik o örneğin uyarlamasıdır:

const alan = document.querySelector("#belge");

alan.addEventListener("change", () => {
  const dosya = alan.files[0];
  if (dosya && dosya.size > 75 * 1000) {
    alan.setCustomValidity("Dosya 75 kB'tan büyük olamaz.");
    alan.reportValidity();
    return;
  }
  alan.setCustomValidity("");   // hata yoksa mesajı temizle
});

Bu kontrol kullanıcıya erken geri bildirim içindir. Sunucu da boyut sınırını ayrıca uygulamalıdır, çünkü istemci tarafındaki her kural atlanabilir. Kilobayt hesabında MDN'in örneği 1 kB için 1000 bayt kullanır ve sistemlerin bu birimi farklı tanımlayabildiğini hatırlatır; kesin sınır önemliyse kullanıcıya hangi birimi kullandığınızı açıkça yazın. Özel mesajın neden boş dizeyle temizlenmesi gerektiği form doğrulama yazısında anlatılıyor.

Seçilen dosyaları önizlemek

MDN'in dosya alanı sayfasındaki tam örnek, kullanıcı görsel seçtiğinde bir önizleme listesi oluşturur. Akış şöyledir: alanın change olayı dinlenir; olay geldiğinde önceki önizleme temizlenir ve files listesi okunur. Liste boşsa "henüz dosya seçilmedi" mesajı yazılır. Değilse her dosya için bir liste öğesi oluşturulur; dosyanın type değeri izin verilen MIME türleri listesinde mi diye bakılır, uygunsa adı ve okunabilir boyutu yazılır ve URL.createObjectURL(file) ile üretilen adres bir <img> öğesinin src değerine verilerek küçük resim gösterilir. Tür uygun değilse kullanıcıya başka bir dosya seçmesi söylenir.

Bu örnekten çıkarılacak ders, accept filtresinin istemci tarafında bile tek başına yeterli sayılmadığıdır: örnek, seçilen dosyanın türünü betikle bir kez daha kontrol eder. Önizleme görsellerine de alt metni verilir; MDN örneğinde bunun için dosya adı kullanılır. Görsel öğesinin öznitelikleri için img etiketi yazısına bakabilirsiniz.

Klasör seçimi: webkitdirectory

webkitdirectory Boolean özniteliği varsa seçicide yalnızca klasörler seçilebilir. MDN, bu özniteliğin HTML'de değil File and Directory Entries API'de tanımlandığını ve adını bir tarayıcıya özgü API olarak doğmasından aldığını açıklar. Klasör seçildiğinde içindeki dosyaların göreli yolları webkitRelativePath ile okunur; bu özellik standart dışıdır. Tarayıcı desteği için MDN uyumluluk tablosuna bakın.

Görünümü özelleştirirken erişilebilirliği korumak

Dosya alanının düğmesi tarayıcıdan tarayıcıya farklı görünür ve doğrudan biçimlendirmesi zordur. MDN'in tam örneği yaygın bir çözüm kullanır: input görsel olarak gizlenir ve ona bağlı <label> bir düğme gibi biçimlendirilir. Etikete tıklamak alanı etkinleştirdiği için kullanıcı yine dosya seçicisini açabilir.

Burada kritik ayrıntı gizleme yöntemidir. MDN, alanın opacity ile saydam yapılmasını, visibility: hidden veya display: none kullanılmamasını önerir; çünkü yardımcı teknolojiler son ikisini alanın etkileşimli olmadığı şeklinde yorumlar. Etiketin metni ne yüklenmesi gerektiğini ve hangi türlerin kabul edildiğini söylemelidir. Etiketleme kuralları için label ve fieldset yazısına bakın.

Uygulamalı mini örnek: başvuru formu

Aşağıdaki form bir iş başvurusu için iki dosya alır. Özgeçmiş zorunludur ve PDF veya Word olmalıdır; portföy görselleri isteğe bağlıdır ve birden çok seçilebilir. Kabul edilen türler ve boyut sınırı etiketlerde açıkça yazılıdır, çünkü accept filtresi kullanıcıya her zaman görünmez.

<form action="/basvuru" method="post" enctype="multipart/form-data">
  <fieldset>
    <legend>Belgeler</legend>
    <p>
      <label for="ozgecmis">Özgeçmiş (zorunlu, PDF veya Word, en fazla 2 MB)</label>
      <input type="file" id="ozgecmis" name="ozgecmis" required
        accept=".pdf,.doc,.docx,application/pdf,application/msword" />
    </p>
    <p>
      <label for="portfoy">Portföy görselleri (isteğe bağlı, birden çok seçilebilir)</label>
      <input type="file" id="portfoy" name="portfoy" accept="image/*" multiple />
    </p>
  </fieldset>
  <button type="submit">Başvuruyu gönder</button>
</form>

Sunucu tarafı bu formdan gelen her dosyanın türünü, boyutunu ve sayısını yeniden kontrol etmelidir. Yüklenen dosyaları barındırdığınız sunucudaki yükleme sınırları da ayrıca ayarlanır; bu ayarlar HTML'in değil sunucu yazılımının konusudur.

Sık yapılan hatalar

• enctype="multipart/form-data" yazmamak. MDN'e göre dosya alanı içeren formlarda bu değer gerekir; yoksa dosyanın içeriği sunucuya gitmez.
• method="get" ile dosya göndermeye çalışmak. GET ile yalnızca dosya adları URL'ye eklenir.
• accept özniteliğini güvenlik kontrolü sanmak. Kullanıcı filtreyi kaldırabilir; türü sunucuda doğrulayın.
• Dosya türünü tek bir biçimle tanımlamak. Aynı tür birden çok uzantı ve MIME türüyle tanımlanabilir; kapsamlı liste verin.
• value değerinden gerçek yolu okumaya çalışmak. Değer her zaman C:\fakepath\ önekli addır.
• Değeri betikle ayarlamaya çalışmak. Dosya alanına değer atamak etkisizdir.
• Alanı display: none ile gizlemek. Yardımcı teknolojiler alanı etkileşimsiz sayar; MDN opacity önerir.
• Boyut sınırını yalnızca istemcide uygulamak. Sunucu da sınırı uygulamalıdır.

Sık Sorulan Sorular

Dosya alanı neden sunucuya boş geliyor?

En sık neden formdaki enctype="multipart/form-data" veya method="post" eksikliğidir. Ayrıca input'un name özniteliği olduğundan emin olun.

Yalnızca görsel yüklenmesine nasıl izin veririm?

Seçicide görsellerin önerilmesi için accept="image/*" yazın, ama asıl sınırlamayı sunucuda dosyanın türünü kontrol ederek yapın.

Dosya boyutu HTML ile sınırlanabilir mi?

Doğrudan bir öznitelik yoktur. MDN'in gösterdiği yol, files ile seçilen dosyanın size değerini okuyup setCustomValidity() ile hata atamaktır; sunucu sınırı da ayrıca gerekir.

Birden çok dosyanın hepsi value içinde görünür mü?

Hayır. value yalnızca ilk dosyayı temsil eder. Seçilen bütün dosyalara files özelliğindeki FileList üzerinden ulaşılır. MDN'in GET örneğinde de her dosya aynı name altında ayrı bir parametre olarak görünür.

capture masaüstünde çalışır mı?

MDN'e göre öznitelik mobil cihazlarda daha iyi çalışır; masaüstünde genellikle normal dosya seçicisi açılır.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: HTML öğrenme rehberi · HTML form etiketi · HTML form doğrulama · label ve fieldset · button etiketi · input türleri