Skip to content

Kaikki WordPressistä, web-kehityksestä — ja paljon muuta

📤 Tiedostojen lähetys raahaa ja pudota -menetelmällä Dropzone.js:n ja PHP:n avulla
Verkkokehitys
7 min1,467 sanaa

📤 Tiedostojen lähetys raahaa ja pudota -menetelmällä Dropzone.js:n ja PHP:n avulla

Käyttäjät odottavat voivansa ladata tiedostoja verkkosivustolle yksinkertaisesti raahaamalla ne selainikkunaan. "Valitse tiedosto" -painiketta ja tiedostoselainta pidetään jo turhina välivaiheina. Mutta raahaa-ja-pudota-toiminnon kirjoittaminen alusta asti JavaScriptillä tarkoittaa useita satoja rivejä koodia, edistymispalkkeja, esikatseluja ja virheenkäsittelyä. Onneksi on olemassa valmis kirjasto, joka hoitaa kaiken tämän suoraan paketista.

Dropzone.js on avoimen lähdekoodin JavaScript-kirjasto raahaa-ja-pudota-tiedostolatauksiin. Se näyttää kuvien esikatselut, edistymispalkin eikä vaadi jQuerya. Se toimii millä tahansa palvelinpuolen kielellä: PHP, Node.js, Python. Tässä oppaassa käydään läpi koko sykli asennuksesta tuotantokäyttöönottoon kuudessa vaiheessa.

💡 Pikaopas:

  • Mitä se tekee: Dropzone.js-kirjasto muuttaa minkä tahansa HTML-elementin tiedostojen pudotusalueeksi, josta ne lähetetään AJAXilla palvelimelle.
  • Miten asennetaan: CDN-linkki (unpkg tai jsDelivr) tai npm-paketti; molemmat vaihtoehdot käsitellään ensimmäisessä vaiheessa.
  • Miten käsitellään palvelimella: PHP-skripti vastaanottaa tiedoston $_FILES-muuttujan kautta, aivan kuten tavallisessa lomakkeessa; kolmas vaihe sisältää valmiin koodin.
  • Mihin sovelletaan: yhteydenottolomakkeet liitetiedostoilla, avatar-lataukset, kuvien massatuonti WordPressin galleriaan.

Vaihe 1: Dropzone.js:n asentaminen

Nopein tapa on sisällyttää kirjasto CDN:n kautta. Lisää tämä tagi sivusi <head>-osioon:

1<script src="https://unpkg.com/dropzone@5/dist/min/dropzone.min.js"></script>

CSS-tiedosto sisällytetään erikseen:

1<link rel="stylesheet" href="https://unpkg.com/dropzone@5/dist/min/dropzone.min.css" />

Jos käytät bundleria, asenna npm:n kautta:

1npm install dropzone

Ja importtaa se JS-tiedostossasi:

1import Dropzone from "dropzone";

Huomaa, että versio 5.9 on uusin vakaa julkaisu vuoden 2026 alussa. Versio kuusi on beta-vaiheessa, eikä sitä vielä suositella tuotantokäyttöön. Projektin repositorio sijaitsee nyt osoitteessa github.com/dropzone/dropzone (aiemmin enyo/dropzone).

Vaihe 2: HTML-perusmerkintä ja alustus

Luo lomake, jolla on dropzone-luokka. Dropzone löytää sen automaattisesti ja muuttaa sen pudotusalueeksi:

1<form action="/upload.php"
2      class="dropzone"
3      id="my-dropzone"></form>

Siinä kaikki. Kun käyttäjä raahaa tiedoston tähän lomakkeeseen, kirjasto lähettää sen AJAX-pyynnöllä action-attribuutissa määriteltyyn URL-osoitteeseen. Palvelinpuolella tiedosto saapuu $_FILES['file']-muuttujaan, täsmälleen kuten tavallisessa <input type="file">-lähetyksessä.

Kehittäjä kirjoittaa koodia tiedostojen lähetykseen

Jos tarvitset varavaihtoehdon selaimille, joissa ei ole JavaScriptiä, lisää lomakkeeseen tavallinen kenttä:

1<form action="/upload.php" class="dropzone">
2  <input name="file" type="file" multiple />
3</form>

"Valitse tiedosto" -painike näkyy vain, kun JavaScript ei ole käytettävissä. Kun JS on käytössä, Dropzone piilottaa sen ja näyttää oman pudotusalueensa.

Vaihe 3: Tiedostojen käsittely palvelimella

PHP-skripti vastaanottaa lähetykset samalla tavalla kuin tavallinen lomake. Tässä on minimaalinen toimiva versio:

1<?php
2if (!empty($_FILES)) {
3    $uploadDir = __DIR__ . '/uploads/';
4 
5    if (!is_dir($uploadDir)) {
6        mkdir($uploadDir, 0755, true);
7    }
8 
9    $originalName = basename($_FILES['file']['name']);
10    $targetPath   = $uploadDir . time() . '_' . $originalName;
11 
12    if (move_uploaded_file($_FILES['file']['tmp_name'], $targetPath)) {
13        http_response_code(200);
14        echo json_encode(['status' => 'ok', 'file' => $targetPath]);
15    } else {
16        http_response_code(500);
17        echo json_encode(['status' => 'error', 'message' => 'Failed to save file']);
18    }
19}

Mitä tässä tapahtuu:

  • Skripti luo uploads/-kansion, jos sitä ei ole olemassa.
  • time() lisätään alkuperäiseen tiedostonimeen, mikä estää nimikonfliktit.
  • basename() poistaa polkuhyökkäysyritykset (yritykset paeta kansiosta ../-merkinnällä).
  • Dropzone odottaa palvelimelta HTTP 200 -vastausta; muuten se tulkitsee lähetyksen epäonnistuneeksi ja näyttää virheen.

Tuotantokäyttöä varten lisää tiedostopäätteen ja MIME-tyypin validointi:

1$allowed = ['jpg', 'jpeg', 'png', 'gif', 'pdf', 'zip'];
2$ext = strtolower(pathinfo($originalName, PATHINFO_EXTENSION));
3 
4if (!in_array($ext, $allowed)) {
5    http_response_code(400);
6    echo json_encode(['status' => 'error', 'message' => 'Invalid file type']);
7    exit;
8}

Vaihe 4: Tiedostojen määrän, koon ja tyypin rajoittaminen

Kolme yleisimmin tarvittavaa Dropzone-asetusta määritetään JavaScript-konfiguraatiolla:

1Dropzone.options.myDropzone = {
2  maxFiles: 10,
3  maxFilesize: 5,          // In megabytes
4  acceptedFiles: 'image/*,.pdf',
5  dictDefaultMessage: 'Drag files here or click to select'
6};

Asetusten selitykset:

  • maxFiles: kuinka monta tiedostoa käyttäjä voi ladata kerralla. Oletuksena rajaa ei ole; esimerkissä enintään 10.
  • maxFilesize: yksittäisen tiedoston enimmäiskoko megatavuina. Arvo 5 tarkoittaa 5 Mt. Vanhemmissa kirjastoversioissa oletus oli 256 Mt; nykyisessä 5.x:ssä se on myös 256, joten määritä oma rajasi eksplisiittisesti.
  • acceptedFiles: pilkuilla eroteltu merkkijono MIME-tyyppejä. Kaava image/* sallii kaikki kuvat, .pdf lisää PDF:n listalle. Katso täydellinen MIME-tyyppilista Dropzonen dokumentaatiosta.
  • dictDefaultMessage: teksti, jonka käyttäjä näkee tyhjässä latausalueessa (tässä esimerkissä englanniksi).

Avain myDropzone kohdassa Dropzone.options.myDropzone on HTML-attribuutin id="my-dropzone" camelCase-versio. Tavuviivat poistetaan ja jokainen seuraava sana kirjoitetaan isolla alkukirjaimella: my-dropzone → myDropzone, file-upload-area → fileUploadArea.

resizeWidth- ja resizeHeight-asetuksilla voit pienentää kuvia asiakaspäässä ennen lähettämistä. Tämä säästää käyttäjän kaistaa ja vähentää palvelimen kuormaa, erityisesti kun kävijät lataavat puhelimella otettuja 10-15 Mt:n valokuvia. Määritä molemmat parametrit yhdessä:

1Dropzone.options.myDropzone = {
2  resizeWidth: 1200,
3  resizeHeight: 1200,
4  resizeQuality: 0.8,
5  resizeMethod: 'contain'
6};

contain-metodi sovittaa kuvan annettuihin rajoihin rajaamatta, kun taas crop rajaa tarkkoihin mittoihin. Laatu 0.8 on käytännössä erottamaton alkuperäisestä, mutta pienentää tiedostokoon 4-7 kertaa pienemmäksi. Tärkeää: koon muuttaminen toimii vain kuvatiedostoilla; PDF:t ja arkistot menevät läpi sellaisenaan. Selain suorittaa koon muuttamisen Canvas API:n kautta, joten lisäkirjastoja ei tarvita.

Vaihe 5: Manuaalinen tiedostojen lähetys

Oletuksena Dropzone lähettää tiedoston palvelimelle heti, kun se on lisätty. Tämä ei ole aina kätevää: joskus käyttäjän on annettava täyttää lomakekenttiä latausalueen vieressä ja lähettää kaikki yhdellä painikkeella.

Poista automaattinen lähetys käytöstä autoProcessQueue: false -lipulla ja liitä lähetys ulkoiseen painikkeeseen:

1Dropzone.options.myDropzone = {
2  autoProcessQueue: false,
3  maxFilesize: 5,
4  init: function () {
5    const myDropzone = this;
6    const submitBtn = document.querySelector('#btnUpload');
7 
8    submitBtn.addEventListener('click', function () {
9      if (myDropzone.getQueuedFiles().length === 0) {
10        alert('No files to upload');
11        return;
12      }
13      myDropzone.processQueue();
14    });
15 
16    this.on('success', function (file, response) {
17      console.log('File uploaded:', file.name);
18    });
19  }
20};

Avainkohta tässä on processQueue()-metodi. Se käynnistää kaikkien jonoon kertyneiden tiedostojen lähetyksen. success-tapahtuma laukeaa jokaiselle tiedostolle erikseen, jolloin voit päivittää käyttöliittymää tai tallentaa ladatun tiedoston ID:n piilotettuun lomakekenttään.

Vaihe 6: Lisädatan lähettäminen tiedoston mukana

Joskus lähetykseen on liitettävä palveluparametreja: käyttäjätunnus, dokumentin tila, valittu kategoria. Dropzonessa on tätä varten sending-tapahtuma:

1Dropzone.options.myDropzone = {
2  init: function () {
3    this.on('sending', function (file, xhr, formData) {
4      formData.append('status', 'draft');
5      formData.append('user_id', currentUserId);
6    });
7 
8    this.on('success', function (file, responseText) {
9      console.log('Done:', responseText);
10    });
11  }
12};

sending-tapahtuma kutsutaan juuri ennen XMLHttpRequestin lähettämistä. Kolmas argumentti formData on tavallinen FormData-olio, johon voit lisätä mitä tahansa avain-arvo-pareja append()-metodilla. Palvelinpuolella nämä parametrit luetaan muuttujista $_POST['status'] ja $_POST['user_id'].

Käytännön skenaario: käyttäjä valitsee albumin pudotusvalikosta Dropzone-alueen vierestä, ja albumin ID lähetetään jokaisen tiedoston mukana. Palvelin lajittelee lähetykset välittömästi oikeisiin kansioihin.

Tietoturva: kolme sääntöä, joita et voi sivuuttaa

Ennen kuin otat Dropzonen tuotantokäyttöön, tarkista kolme asiaa.

Ensinnäkin. Validoi tiedostotyyppi ja koko aina palvelinpuolella, vaikka olisit jo määrittänyt acceptedFiles- ja maxFilesize-asetukset JavaScriptissä. Asiakaspään rajoitukset voi kiertää minuutissa selaimen konsolin kautta. Palvelinpuolen suodatus on ainoa todellinen suoja.

Toiseksi. Säilytä ladatut tiedostot dokumenttijuuren ulkopuolella tai kansiossa, jossa skriptien suoritus on estetty. Esimerkiksi tämä rakenne:

1/public_html        ← document root ( index.php )
2/uploads            ← folder with uploaded files (outside web access)

Silloin suora URL tiedostoon ei toimi; selain tarjoaa tiedoston vain PHP-välitysskriptin kautta, joka tarkistaa käyttöoikeudet.

Kolmanneksi. Luo palvelimella yksilölliset tiedostonimet. Älä luota asiakkaan lähettämään nimeen: se voi sisältää ../, null-merkkejä tai erikoismerkkejä. basename() + time() + satunnainen merkkijono on minimitaso.

Neljänneksi. Tarkista tiedoston sisältö, ei pelkkää päätettä. Hyökkääjä voi nimetä shell.php-tiedoston uudelleen nimellä photo.jpg ja ohittaa pathinfo()-suodattimen. Luotettava tapa: selvitä todellinen MIME-tyyppi finfo_file()-funktiolla (PHP:n sisäänrakennettu Fileinfo-moduuli) ja vertaa sallittujen listaan. Kuvien kohdalla varmista lisäksi, että getimagesize() palauttaa kelvolliset mitat; tämä suodattaa pois vioittuneet tiedostot ja naamioidut skriptit. Paljon liikennettä saavissa projekteissa kannattaa harkita latausten ulkoistamista erilliselle mikropalvelulle käänteisen välityspalvelimen taakse, joka vastaanottaa virran, tarkistaa sen virustorjunnalla (esimerkiksi ClamAV) ja vasta sitten välittää sen pääsovellukselle.

Yllä oleva lyhyt demovideo näyttää koko prosessin toiminnassa: HTML-merkintä, PHP-käsittelijä ja lopputulos selaimessa kolmessa minuutissa.

⁉️🤔 Usein kysytyt kysymykset

Toimiiko Dropzone.js ilman jQuerya?

Kyllä, kirjasto on täysin riippumaton jQuerysta. Versiosta 5.x alkaen kaikki riippuvuudet on poistettu; katso Asennusosio dropzone.dev-sivustolla. Tästä huolimatta tarjolla on erillinen jQuery-kääre niille, jotka haluavat käyttää $('.dropzone').dropzone()-syntaksia; se löytyy samasta npm-paketista polusta dist/min/dropzone-jquery.min.js.

Miten muutan virheilmoituksen tekstiä, kun tiedosto on liian suuri?

Käytä dictFileTooBig-asetusta. Esimerkki: dictFileTooBig: 'File is too big. Maximum size is {{maxFilesize}} MB'. {{maxFilesize}}-paikkamerkki lisää automaattisesti arvon asetuksistasi. Täydellinen lista lokalisointiin käytettävistä dict-avaimista löytyy dokumentaatiosta.

Voiko tiedostoja ladata palasina suuria tietomääriä varten?

Kyllä, Dropzone v5 sisältää sisäänrakennetun tuen paloitelluille latauksille asetuksilla chunking: true, chunkSize (tavuina) ja forceChunking. Palvelimen on pystyttävä kokoamaan palaset: sen on otettava jokainen pala vastaan dzchunkindex- ja dztotalchunkcount-otsakkeiden kanssa, tallennettava ne väliaikaisesti ja yhdistettävä ne viimeisen palan saavuttua. Valmis PHP-esimerkki palasten kokoamiseen löytyy Dropzonen repositoriosta.

Miten poistan tiedoston esikatselun onnistuneen latauksen jälkeen?

Kutsu myDropzone.removeFile(file) success-tapahtumankäsittelijässä. Tiedosto katoaa käyttöliittymästä, mutta säilyy palvelimella. Jos haluat poistaa sen myös palvelimelta, lisää AJAX-pyyntö samaan käsittelijään ennen removeFile-kutsua.

Onko Dropzone yhteensopiva WordPressin kanssa?

Kyllä, kirjaston voi sisällyttää teemaan tai lisäosaan wp_enqueue_script()-funktiolla. Tyypillinen WordPress-skenaario: tavallisen medialataajan korvaaminen mukautetulla ylläpitosivulla tai julkisella lomakkeella. Sinun tarvitsee vain määrittää oikea käsittelijän URL, yleensä admin_url('admin-ajax.php') rekisteröidyn AJAX-toiminnon kanssa.

Sopiiko Dropzone.js sinun projektiisi

Jos tarvitset raahaa ja pudota -tiedostolataukset "tässä ja nyt", Dropzone.js ratkaisee tehtävän nopeammin kuin mikään itse kirjoitettu koodi. Tässä viisi syytä, miksi kirjasto on edelleen relevantti vuonna 2026:

  • Ei riippuvuuksia. Ei jQuerya, Bootstrapia tai Reactia. Sisällytä yksi JS-tiedosto, ja se toimii.
  • Selaintuki. Tukee selaimia IE11:een asti ja toimii huononnetusti ilman JavaScriptiä.
  • Valmis visualisointi. Kuvaesikatselut, edistymispalkit, onnistumis-/virhekuvakkeet suoraan paketista, ilman CSS-asettelutyötä.
  • Dokumentaatio. Ajantasainen GitBook ja aktiivinen GitHub-repositorio (yli 1 700 tähteä vuonna 2026).
  • Joustavuus. Yksinkertaisesta kuvien koon muuttamisesta ennen latausta gigatavun kokoisten tiedostojen paloiteltuihin latauksiin, kaikki on säädettävissä.

Milloin Dropzone ei ole paras valinta: jos käytät jo Reactia/Vueta ja haluat natiivin komponentin ilman ulkoista DOM-manipulaatiota. React-ekosysteemissä on react-dropzone, Vuessa on vue-dropzone. Mutta vanilla JavaScriptille, jQuery-projekteille ja WordPress-sivustoille Dropzone.js on testattu työkalu, joka ei petä.

Käytännön integrointiesimerkki. Yksi tyypillinen WordPress-skenaario: "Lataa asiakirjoja" -sivu asiakasportaalissa. Käyttäjä raahaa skannaukset passista, sopimuksesta ja kiinteistökuvista. Dropzone sisällytetään wp_enqueue_script()-funktiolla teeman functions.php-tiedostossa, ja käsittelijä on mukautettu AJAX-toiminto, joka on rekisteröity wp_ajax_nopriv_-koukulla. Jokainen onnistuneesti ladattu tiedosto lisätään mediakirjastoon wp_insert_attachment()-funktiolla, ja sen ID tallennetaan käyttäjän metatietoihin. Koko frontend-koodi mahtuu 30 riviin ja palvelinpuoli 50 riviin. Vertailun vuoksi, vastaavilla ominaisuuksilla varustettu itse tehty raahaa ja pudota -ratkaisu vaatisi 400-600 riviä JavaScriptiä ja 2-3 päivää kehitystyötä.

Mitä tulee vaihtoehtoihin: Uppy (Transloaditin tekijöiltä) tarjoaa modulaarisen arkkitehtuurin liitännäisillä Reactille, Sveltelle ja S3-latauksille, mutta vaatii enemmän riippuvuuksia ja konfigurointia. Fine Uploaderia ei ole ylläpidetty vuoden 2018 jälkeen; forkkeja on olemassa, mutta ilman tietoturvatakuita. Dropzone.js voittaa "ominaisuuksia per monimutkaisuusyksikkö" -tasapainossa: yksi tiedosto, minimaalinen konfigurointi ja näkyvät tulokset viisi minuuttia integroinnin jälkeen.

Muutama lisäominaisuus, jotka kannattaa tietää ennen aloittamista. Dropzone tarjoaa täyden tapahtumasyklin: addedfile, thumbnail, uploadprogress, complete ja queuecomplete. Viimeinen on erityisen hyödyllinen: se laukeaa, kun kaikki jonossa olevat tiedostot on käsitelty, jolloin voit näyttää käyttäjälle yhteenvetoviestin tai ohjata toiselle sivulle. Verkkokatkoksia varten on sisäänrakennettu uudelleenyritys: latausvirheen sattuessa Dropzone näyttää "Yritä uudelleen" -painikkeen tiedoston esikatselun vieressä, ja uudelleenyritys kulkee saman käsittelijän kautta ilman koodin toistoa. Käyttöliittymä on täysin lokalisoitavissa dict-asetusten avulla: dictCancelUpload, dictRemoveFile, dictMaxFilesExceeded ja noin kaksi tusinaa muuta avainta. Venäjän kielen tuki on pystytetty viidessä minuutissa kopioimalla objekti dokumentaatiosta. Kirjasto painaa 28 kt pakattuna (gzip), lisäten alle 0,1 sekuntia sivun latausaikaan mobiili 4G:llä. Kaikki nämä ominaisuudet tekevät Dropzone.js:stä de facto -standardin raahaa ja pudota -latauksille projekteissa ilman frameworkeja: miljoona npm-latausta viikossa vuoden 2026 alussa, ja käyttöä WordPressin, Laravelin ja Symfony-hallintapaneeleissa.

Toimitus
ToimitusToimitustiimi→ All publications

Ammattimainen kirjoittajien ja toimittajien tiimi, joka on erikoistunut laadukkaan sisällön luomiseen.