Práce s FormData API v JavaScriptu

FormData rozhraní poskytuje jednoduchý způsob, jak uložit páry klíč-hodnota odpovídající polím formuláře HTML a jejich hodnotám. Funguje ve všech moderních prohlížečích a Internet Exploreru 10+.

Jak název napovídá, FormData rozhraní je navrženo tak, aby uchovávalo data formulářů, což nám umožňuje sestavit objekt představující formulář HTML v JavaScriptu.

Běžně se používá, když potřebujete asynchronně odeslat data formuláře do koncového bodu RESTful API. Například nahrání jednoho nebo více souborů pomocí Fetch() API, XMLHttpRequest rozhraní nebo Axios.

Vytvoření objektu

Chcete-li vytvořit objekt z FormData jeho konstruktoru můžete zavolat pomocí new operátor, jak je uvedeno níže:

const fd = new FormData();

Ve výše uvedeném kódu fd proměnná odkazuje na instanci FormData . Nyní můžete volat metody na objektu pro přidání, odstranění nebo aktualizaci párů klíč–hodnota prezentujících pole formuláře.

Metody

FormData rozhraní poskytuje následující metody:

  • append() — Připojte k objektu nový pár klíč–hodnota. Pokud klíč již existuje, hodnota se připojí k původní hodnotě tohoto klíče.
  • delete() — Odstraňte z objektu pár klíč–hodnota.
  • entries() — Vrátí objekt iterátoru, který vám umožní procházet všechny páry klíč–hodnota přidané k tomuto objektu.
  • get() — Vrátí první hodnotu přidruženou k danému klíči.
  • getAll() — Vrátí pole všech hodnot spojených s daným klíčem.
  • has() — Vrátí booleovskou hodnotu označující, zda daný klíč v tomto objektu existuje či nikoli.
  • keys() — Vrátí objekt iterátoru, který lze použít k zobrazení seznamu dostupných klíčů v tomto objektu.
  • set() — Nastaví novou hodnotu pro existující klíč. Je užitečné nahradit existující hodnotu klíče.
  • values() — Vrátí objekt iterátoru, který lze použít k zobrazení seznamu všech dostupných hodnot v tomto objektu.

Jak jej používat?

Řekněme, že pracujeme na webové aplikaci, která uživatelům umožňuje nahrát profilový obrázek. Chceme vytvořit HTML formulář, který uživatelům umožní nahrát obrázek se jménem a e-mailovou adresou.

Naše označení HTML vypadá takto:

<form id="profile-form">
    <input type="text" id="name" name="name" placeholder="Name">
    <input type="email" id="email" name="email" placeholder="Email Address">
    <input type="file" id="avatar" name="avatar">
    <button>Submit</button>
</form>

Nyní připojte k formuláři posluchač události, který bude volán při odeslání formuláře:

const form = document.querySelector('#profile-form');

// Attach event handler to form
form.addEventListener('submit', (e) => {
    // Disable default submission
    e.preventDefault();

    // TODO: submit the form manually
});

Výše uvedený kód přidá submit obslužnou rutinu události do formuláře. Ve funkci obsluhy události deaktivujeme výchozí akci ve prospěch ručního odeslání formuláře pomocí FormData rozhraní.

Dále vytvořte novou instanci FormData a připojte do něj každý prvek:

const name = document.querySelector('#name');
const email = document.querySelector('#email');
const avatar = document.querySelector('#avatar');

// Create a new FormData object
const fd = new FormData();
fd.append('name', name.value);
fd.append('email', email.value);
fd.append('avatar', avatar.files[0]);

Nakonec odešlete FormData objekt s fetch() API a zaprotokoluje odpověď na konzoli:

fetch('/update-profile', {
    method: 'POST',
    mode: 'no-cors',
    body: fd
}).then(res => res.json())
    .then(json => console.log(json))
    .catch(err => console.error(err));

Zde je úplný příklad kódu:

const form = document.querySelector('#profile-form');

// Attach event handler to form
form.addEventListener('submit', (e) => {
    // Disable default submission
    e.preventDefault();

    // Submit form manually
    const name = document.querySelector('#name');
    const email = document.querySelector('#email');
    const avatar = document.querySelector('#avatar');

    // Create a new FormData object
    const fd = new FormData();
    fd.append('name', name.value);
    fd.append('email', email.value);
    fd.append('avatar', avatar.files[0]);

    // send `POST` request
    fetch('/update-profile', {
        method: 'POST',
        mode: 'no-cors',
        body: fd
    }).then(res => res.json())
        .then(json => console.log(json))
        .catch(err => console.error(err));
});

Chcete-li nahrát více souborů pomocí FormData rozhraní, podívejte se na tento článek.

Předávání form odkaz

Všimněte si, že FormData konstruktor může vzít odkaz na HTML <form> prvek jako argument. Pokud je uveden, FormData objekt bude naplněn aktuálními klíči-hodnotami formuláře pomocí vlastnosti name každého prvku pro klíče a jejich odeslané hodnoty pro hodnoty. Zahrnuje také vstupní obsah souboru.

Takže místo ručního volání append() pro každý vstupní prvek můžete provést následující:

const fd = new FormData(e.currentTarget);

e.currentTarget vlastnost vždy odkazuje na prvek, jehož posluchač události událost spustil. V našem případě je to <form> prvek.

Přepsání klíče

Další důležitou věcí k zapamatování je append() metoda nepřepíše klíč, pokud již existuje. Účelem je umožnit více hodnot pro jeden klíč:

const fd = new FormData();
fd.append('size', 'L');
fd.append('size', 'XL');

console.log(fd.getAll('size')); // ["L", "XL"]

Chcete-li přepsat klíč, použijte set() metoda místo toho:

// ...
fd.set('size', 'M');

console.log(fd.getAll('size')); // ["M"]

Kompatibilita prohlížeče

Kromě append() metoda, která funguje ve všech prohlížečích, všechny ostatní metody jsou dostupné pouze v moderních prohlížečích.