FormData
Zbiera wartości pól formularza w pary nazwa i wartość. Gotowy obiekt można odczytać albo wysłać do serwera przez fetch().
- Zwraca
- Nowy obiekt
FormData.
Przykład
#const form = document.querySelector('#signup')
const data = new FormData(form)
console.log(data.get('nick'))
console.log(data.get('course'))
console.log(data.get('newsletter'))
console.log(data.get('code'))
console.log(Object.fromEntries(data))Zaznaczone pole wyboru bez atrybutu value ma wartość "on". Wyłączone pole code w ogóle nie trafia do danych, dlatego get() zwraca dla niego null.
Definicja i zastosowanie
#Konstruktor new FormData(form) odczytuje wszystkie pola formularza, które mają atrybut name, i zapisuje je jako pary nazwa i wartość. Nie musisz pobierać każdego pola osobno: tekst z pól, zaznaczone pola wyboru, wybrane opcje list i pliki trafiają do jednego obiektu. Pola wyłączone (disabled) oraz niezaznaczone pola wyboru są pomijane.
Metoda get(nazwa) zwraca wartość pola (napis albo plik) lub null, getAll() zwraca wszystkie wartości o danej nazwie, np. z kilku zaznaczonych pól wyboru, a has(), set(), append() i delete() pozwalają sprawdzać i zmieniać dane. Object.fromEntries(formData) zamieni je na zwykły obiekt, ale przy powtarzających się nazwach zostanie tylko ostatnia wartość.
Obiekt FormData przekazany jako body do fetch() zostanie wysłany w formacie multipart/form-data, tym samym, którego używa zwykły formularz z plikami. Nie ustawiaj wtedy ręcznie nagłówka Content-Type, bo przeglądarka musi dodać do niego granicę oddzielającą pola. Jeśli serwer oczekuje JSON, zamień dane na obiekt i wyślij go przez JSON.stringify().
Składnia
#new FormData()
new FormData(form)
new FormData(form, submitter)
formData.get(name)
formData.getAll(name)
formData.has(name)
formData.set(name, value)
formData.append(name, value)
formData.delete(name)Parametry
#form
opcjonalny, element <form>
Formularz, z którego zostaną odczytane pola z atrybutemname.submitter
opcjonalny, przycisk
Przycisk, który wysłał formularz. Jeśli ma atrybutynameivalue, jego wartość też trafi do danych.
Więcej przykładów
#const form = document.querySelector('#feedback')
form.addEventListener('submit', (event) => {
event.preventDefault()
const data = new FormData(form, event.submitter)
console.log([...data])
})
form.querySelector('button').click()Z grupy przycisków opcji trafia tylko zaznaczona wartość. Przycisk wysyłający jest w danych, bo przekazaliśmy event.submitter jako drugi argument konstruktora.
const data = new FormData(document.querySelector('#topics'))
console.log(data.get('topic'))
console.log(data.getAll('topic'))
console.log(Object.fromEntries(data))get() zwraca tylko pierwszą wartość, a Object.fromEntries() zostawia ostatnią. Wszystkie zaznaczone tematy daje dopiero getAll().
const form = document.querySelector('#avatar-form')
form.addEventListener('submit', async (event) => {
event.preventDefault()
const data = new FormData(form)
data.append('userId', '42')
const response = await fetch('/api/avatar', { method: 'POST', body: data })
console.log(await response.json())
}){ url: '/avatars/42.webp' }Przykład wymaga serwera, więc nie uruchamia się w podglądzie, a wynik to przykładowa odpowiedź API. Plik z pola <input type="file" name="avatar"> trafia do danych automatycznie, a nagłówek Content-Type ustawia sama przeglądarka.
Obsługa przeglądarek
#Szeroko dostępne
Działa we wszystkich nowoczesnych przeglądarkach, także na telefonach. Możesz używać bez obaw.
- Chrome
- Edge
- Firefox
- Safari
Dobre praktyki
#- Nadaj każdemu polu atrybut
name. Pola bez niego nie trafią doFormData, nawet jeśli mają wartość. - Wysyłając
FormDataprzezfetch(), nie ustawiaj nagłówkaContent-Type. Przeglądarka doda go sama, razem z granicą oddzielającą pola. - Dla kilku pól wyboru o tej samej nazwie używaj
getAll().get()zwróci tylko pierwszą zaznaczoną wartość.
Powiązane hasła
#- Event.preventDefault()Blokuje domyślne działanie przeglądarki dla zdarzenia, np. wysłanie formularza lub przejście pod adres linku.
- fetch()Wysyła zapytanie HTTP i zwraca obietnicę z odpowiedzią serwera (obiektem Response).
- URLSearchParamsObiekt do odczytu i budowania parametrów zapytania w adresie, czyli części po znaku ?, np. ?kurs=js&strona=2.
- Object.fromEntries()Tworzy obiekt z listy par [klucz, wartość].
- EventTarget.addEventListener()Rejestruje funkcję wywoływaną za każdym razem, gdy na elemencie wystąpi zdarzenie, np. kliknięcie.
Widzisz błąd albo brakuje przykładu? Napisz do nas.