A propriedade body
é responsável por definir o corpo da requisição a ser efetivada pelo fetch
. O tipo de dado que você pode passar a essa propriedade é variado, de modo que aceita:
FormData
URLSearchParams
USVString
Blob
BufferSource
ReadableStream
Os três primeiros são os mais comuns. É relativamente raro utilizar Blob
, BufferSource
e ReadableStream
no dia a dia, mas saiba que, se precisar, eles existem.
Abaixo explicarei, entre FormData
, URLSearchParams
e USVString
, qual é o mais adequado para cada situação.
Utilizar FormData
(multipart/form-data
)
Utilize o tipo FormData
na propriedade do corpo da requisição quando o servidor aceitar requisições cujo Content-Type seja multipart/form-data
. Esse Content-Type é comumente utilizado quando algum dos campos do corpo é um arquivo.
A interface de uso é extremamente simples, uma vez que o construtor FormData
aceita como argumento um elemento HTMLFormElement
, que terá os campos serializados.
Um exemplo:
// Seu elemento <form>:
const form = document.querySelector('#my-form');
fetch('https://path.to/resource', {
method: 'POST',
body: new FormData(form)
})
.then(...)
.catch(...);
Note que, quando se passa uma instância FormData
à propriedade body
, o cabeçalho Content-Type já é definido automaticamente como multipart/form-data
.
Utilizar URLSearchParams
(urlencoded
)
Utilize o tipo URLSearchParams
para requisições na qual o Content-Type esperado é application/x-www-form-urlencoded
.
Um exemplo:
// Seu elemento <form>:
fetch('https://path.to/resource', {
method: 'POST',
body: new URLSearchParams({
field1: 'Value1',
fieldN: 'ValueN'
})
})
.then(...)
.catch(...);
Quando se utiliza URLSearchParams
em body
, o cabeçalho Content-Type é definido automaticamente como application/x-www-form-urlencoded
.
Observe que o construtor URLSearchParams
não aceita uma instância de formulário diretamente (assim como FormData
faz). Você pode passar um objeto com chaves e valores, que serão corretamente serializados (conforme demonstrado no exemplo acima). Uma outra opção, conforme documentado, é passar uma instância de FormData
ao construtor URLSearchParams
, então a serialização de um formulário inteiro também se torna trivial:
const myForm = document.querySelector('form#my-form');
const urlEncodedBody = new URLSearchParams(new FormData(myForm));
// Passe `urlEncodedBody` para a propriedade `body` da requisição...
Utilizar USVString
(string como corpo da requisição)
O tipo USVString
nada mais é que uma diferente implementação de strings dos browsers. Ignorando a parte técnica (que pode ser consultada na documentação), é basicamente o tipo primitivo string
do JavaScript. Desse modo, é o tipo que deve ser utilizado quando, por exemplo, precisa-se enviar conteúdo em formato application/json
.
Um exemplo:
fetch('https://path.to/resource', {
method: 'POST',
body: JSON.stringify({
field1: 'Value1',
fieldN: 'ValueN'
}),
headers: {
'Content-Type': 'application/json'
}
})
.then(...)
.catch(...);
Note que o JSON.stringify
retorna o primitivo string
do JavaScript. Antes da requisição ser executada, a implementação converterá o tipo string
do JavaScript para o USVString
.
Observe que como passar uma string para a propriedade body
é ambíguo (pode representar diversos tipos de Content-Type diferentes), o navegador não tem como inferir esse cabeçalho corretamente. Desse modo, supondo que queremos fazer uma requisição cujo body
é do tipo application/json
, precisamos fornecer o cabeçalho explicitamente.