Este capítulo é sobre o envio de formulários HTML: com ou sem arquivos, com campos adicionais e assim por diante.
Objetos FormData podem ajudar com isso. Como você deve ter imaginado, é o objeto que representa os dados de um formulário HTML.
O construtor é:
let formData = new FormData([form]);Se o elemento HTML form for fornecido, ele captura automaticamente seus campos.
O que torna o FormData especial é que métodos de rede, como fetch, podem aceitar um objeto FormData como corpo. Ele é codificado e enviado com Content-Type: multipart/form-data.
Do ponto de vista do servidor, isso se parece com um envio de formulário comum.
Vamos enviar um formulário simples primeiro.
Como você pode ver, isso é quase uma linha só:
<form id="formElem">
<input type="text" name="name" value="John">
<input type="text" name="surname" value="Smith">
<input type="submit">
</form>
<script>
formElem.onsubmit = async (e) => {
e.preventDefault();
let response = await fetch('/article/formdata/post/user', {
method: 'POST',
*!*
body: new FormData(formElem)
*/!*
});
let result = await response.json();
alert(result.message);
};
</script>Neste exemplo, o código do servidor não é apresentado, já que está fora do nosso escopo. O servidor aceita a requisição POST e responde "Usuário salvo".
Podemos modificar campos em FormData com métodos:
formData.append(name, value)- adiciona um campo de formulário com onameevaluedados,formData.append(name, blob, fileName)- adiciona um campo como se fosse<input type="file">, o terceiro argumentofileNamedefine o nome do arquivo (não o nome do campo do formulário), como se fosse o nome do arquivo no sistema de arquivos do usuário,formData.delete(name)- remove o campo com onamedado,formData.get(name)- obtém o valor do campo com onamedado,formData.has(name)- se existir um campo com onamedado, retornatrue, caso contráriofalse
Um formulário é tecnicamente autorizado a ter vários campos com o mesmo name, então várias chamadas a append adicionam mais campos com o mesmo nome.
Também existe o método set, com a mesma sintaxe de append. A diferença é que .set remove todos os campos com o name dado, e então adiciona um novo campo. Então ele garante que existe só um campo com esse name, o resto é igual a append:
formData.set(name, value),formData.set(name, blob, fileName).
Também podemos iterar sobre os campos de formData usando o laço for..of:
let formData = new FormData();
formData.append('key1', 'value1');
formData.append('key2', 'value2');
// Lista os pares chave/valor
for(let [name, value] of formData) {
alert(`${name} = ${value}`); // key1 = value1, depois key2 = value2
}O formulário é sempre enviado como Content-Type: multipart/form-data, essa codificação permite enviar arquivos. Então, campos <input type="file"> também são enviados, de forma parecida com um envio de formulário comum.
Aqui está um exemplo com um formulário desse tipo:
<form id="formElem">
<input type="text" name="firstName" value="John">
Foto: <input type="file" name="picture" accept="image/*">
<input type="submit">
</form>
<script>
formElem.onsubmit = async (e) => {
e.preventDefault();
let response = await fetch('/article/formdata/post/user-avatar', {
method: 'POST',
*!*
body: new FormData(formElem)
*/!*
});
let result = await response.json();
alert(result.message);
};
</script>Como vimos no capítulo info:fetch, é fácil enviar dados binários gerados dinamicamente, por exemplo, uma imagem, como Blob. Podemos fornecê-lo diretamente como o parâmetro body do fetch.
Na prática, porém, geralmente é conveniente enviar uma imagem não separadamente, mas como parte do formulário, com campos adicionais, como "nome" e outros metadados.
Além disso, os servidores costumam estar mais preparados para aceitar formulários codificados como multipart, em vez de dados binários crus.
Este exemplo envia uma imagem de um <canvas>, junto com alguns outros campos, como um formulário, usando FormData:
<body style="margin:0">
<canvas id="canvasElem" width="100" height="80" style="border:1px solid"></canvas>
<input type="button" value="Enviar" onclick="submit()">
<script>
canvasElem.onmousemove = function(e) {
let ctx = canvasElem.getContext('2d');
ctx.lineTo(e.clientX, e.clientY);
ctx.stroke();
};
async function submit() {
let imageBlob = await new Promise(resolve => canvasElem.toBlob(resolve, 'image/png'));
*!*
let formData = new FormData();
formData.append("firstName", "John");
formData.append("image", imageBlob, "image.png");
*/!*
let response = await fetch('/article/formdata/post/image-form', {
method: 'POST',
body: formData
});
let result = await response.json();
alert(result.message);
}
</script>
</body>Observe como o Blob da imagem é adicionado:
formData.append("image", imageBlob, "image.png");Isso é o mesmo que se existisse <input type="file" name="image"> no formulário, e o visitante tivesse enviado um arquivo chamado "image.png" (3º argumento) com os dados imageBlob (2º argumento) a partir do sistema de arquivos dele.
O servidor lê os dados do formulário e o arquivo, como se fosse um envio de formulário comum.
Objetos FormData são usados para capturar um formulário HTML e enviá-lo usando fetch ou outro método de rede.
Podemos tanto criar new FormData(form) a partir de um formulário HTML, quanto criar um objeto sem nenhum formulário, e então adicionar campos com métodos:
formData.append(name, value)formData.append(name, blob, fileName)formData.set(name, value)formData.set(name, blob, fileName)
Vamos notar duas peculiaridades aqui:
- O método
setremove campos com o mesmo nome,appendnão. Essa é a única diferença entre eles. - Para enviar um arquivo, a sintaxe de 3 argumentos é necessária, o último argumento é um nome de arquivo, que normalmente é obtido do sistema de arquivos do usuário para
<input type="file">.
Outros métodos são:
formData.delete(name)formData.get(name)formData.has(name)
É isso!