nginstack

Class: FormData

FormData

new FormData()

Classe que representa um conjunto de campos de uma requisição multipart/form-data.

Mais detalhes em MDN FormData.

Essa implementação é parcial em relação à Web API FormData disponível nos navegadores.

  • Não há suporte a Blob. Em seu lugar, a API suporta as classes File e MemoryStream.
  • Os métodos entries, keys, values e forEach não estão disponíveis.
  • XMLHttpRequest.send transmite este objeto como corpo multipart/form-data.
  • Um campo binário retornado por get e getAll é um objeto da classe File.
  • A classe também expõe contentType, boundary, size e toBytes para permitir a inspeção e leitura do conteúdo do formulário.

Members

boundary :string

Delimitador utilizado na serialização deste objeto. Cada instância recebe um delimitador próprio.

Type:
  • string

contentType :string

Cabeçalho Content-Type do corpo, no formato multipart/form-data; boundary=<boundary>.

Type:
  • string

size :number

Quantidade de campos armazenados.

Type:
  • number

Methods

append(name, value [, fileName])

Acrescenta um campo. Campos com o mesmo nome são mantidos.

É permitido adicionar vários campos com o mesmo nome, mas essa prática não é recomendada. O tratamento de vários campos com o mesmo nome pode não ser bem suportado por todos os servidores.

Diferentemente da Web API FormData disponível nos navegadores, são suportados os tipos string, File, MemoryStream, Uint8Array e ArrayBuffer. O tipo Blob atualmente não é implementado no sistema e não é suportado.

O argumento fileName só é utilizado para valores binários e é ignorado quando o valor é convertido para texto. O tipo de conteúdo de um valor binário é inferido a partir de fileName ou, quando ele é omitido, a partir do conteúdo.

Parameters:
Name Type Argument Description
name string

Nome do campo.
value string | File | MemoryStream | Uint8Array | ArrayBuffer

Valor do campo.
fileName string <optional>

Nome de arquivo associado a um valor binário. É importante que fileName seja um nome com a extensão de arquivo correta, para que o tipo do conteúdo seja inferido corretamente.
Example
const formData = new FormData();
formData.append('descricao', 'Relatório');
formData.append('anexo', pdfFile, 'anexo.pdf')
formData.size; // => 2

delete(name)

Remove todos os campos com o nome informado.

Parameters:
Name Type Description
name string

Nome do campo.

get(name)

Retorna o primeiro campo com o nome informado.

Campos de texto retornam uma string e campos binários retornam um File com os bytes do campo. Cada consulta devolve um arquivo novo. Alterá-lo ou fechá-lo não modifica o campo armazenado. Quando não há campo com o nome informado, o retorno é null.

Parameters:
Name Type Description
name string

Nome do campo.
Returns:

Valor do campo, ou null quando ele não existe.

Type
string | File | null
Example
const formData = new FormData();
formData.append('descricao', 'Relatório');
formData.get('descricao'); // => 'Relatório'

formData.append('anexo', new Uint8Array([65, 66, 67]), 'relatorio.bin');
const anexo = formData.get('anexo');
anexo.size; // => 3
anexo.read(); // => 'ABC'

getAll(name)

Retorna todos os campos com o nome informado, na ordem em que foram acrescentados. A forma de cada elemento é a mesma de #get. Quando não há campo com o nome informado, o retorno é um array vazio.

Parameters:
Name Type Description
name string

Nome do campo.
Returns:

Valores dos campos encontrados.

Type
Array.<(string|File)>
Example
const formData = new FormData();
formData.append('item', 'texto');
formData.append('item', new Uint8Array([65]), 'a.bin');
const items = formData.getAll('item');
items[0]; // => 'texto'
items[1].read(); // => 'A'

has(name)

Indica se existe algum campo com o nome informado.

Parameters:
Name Type Description
name string

Nome do campo.
Returns:

true quando existe ao menos um campo com o nome informado.

Type
boolean

set(name, value [, fileName])

Substitui todos os campos com o nome informado. Se não houver campo com esse nome, o valor é acrescentado. As restrições de tipo do valor são as mesmas de #append.

Parameters:
Name Type Argument Description
name string

Nome do campo.
value string | File | MemoryStream | Uint8Array | ArrayBuffer

Valor do campo.
fileName string <optional>

Nome de arquivo associado a um valor binário. É importante que fileName seja um nome com a extensão de arquivo correta, para que o tipo do conteúdo seja inferido corretamente.

toBytes()

Serializa os campos no formato multipart/form-data.

Returns:

Corpo da requisição.

Type
Uint8Array