fetch()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2017.
O método global fetch()
inicia o processo de busca de um recurso da rede, retornando uma promessa que é cumprida assim que a resposta estiver disponível.
A promessa é resolvida para o objeto Response
que representa a resposta à sua solicitação. A promessa não rejeita erros de HTTP - apenas rejeita erros de rede. Você deve usar os manipuladores then
para chechar erros de HTTP.
WindowOrWorkerGlobalScope
é implementado por Window
e
WorkerGlobalScope
, o que significa que o método fetch()
está disponível em praticamente qualquer contexto no qual você queira buscar recursos.
Uma promessa fetch()
só é rejeitada quando um erro de rede é encontrado (que é geralmente quando há um problema de permissão ou
similar). Uma promessa fetch()
não rejeita erros HTTP (404
, etc.). Em vez disso, um manipulador
then()
deve checar as propriedades Response.ok
e/ou
Response.status
.
O método fetch()
é controlado pela diretiva connect-src
da Content Security Policy em vez da diretiva dos recursos que está recuperando.
Nota: Os parâmetros do método fetch()
são idênticos
aos do construtor Request()
.
Sintaxe
const fetchResponsePromise = fetch(resource [, init])
Parâmetros
resource
-
Isto define o recurso que você deseja buscar. Isto pode ser:
- String ou qualquer outro objeto com um stringifier — incluindo um objeto
URL
— que fornece a URL do recurso que você deseja buscar. - Um objeto
Request
.
- String ou qualquer outro objeto com um stringifier — incluindo um objeto
init
Optional-
Um objeto contendo quaisquer configurações customizadas que você deseja aplicar à solicitação. As opções possíveis são:
method
-
O método da requisição, por exemplo
GET
,POST
. Observe que o cabeçalhoOrigin
não é definido em requisições Fetch com um método deHEAD
ouGET
. (Este comportamento foi corrigido no Firefox 65 — consulte Erro do Firefox 1508661). headers
-
Qualquer cabeçalho que você queira adicionar à sua requisição, contido dentro de um objeto
Headers
ou um objeto literal com valoresString
. Observe que alguns nomes são proibidos. body
-
Qualquer corpo que você queira adicionar à sua requisição: podendo ser um
Blob
,BufferSource
,FormData
,URLSearchParams
,USVString
, ou um objetoReadableStream
. Note que uma requisição usando os métodosGET
orHEAD
não pode ter um corpo. mode
-
O modo que deseja usar para a requisição, por exemplo,
cors
,no-cors
, ousame-origin
. credentials
-
Controla o que os navegadores fazem com as credenciais (cookies, entradas de Autenticação HTTP, e certificados de cliente TLS). Deve ser uma das seguintes strings:
omit
-
Diz aos navegadores para excluir credenciais da requisição, e ignorar quaisquer credenciais enviadas de volta na resposta (por exemplo, qualquer cabeçalho
Set-Cookie
). same-origin
-
Diz aos navegadores para incluir credenciais com requisições para URLs da mesma origem, e usar quaisquer credenciais enviadas de volta nas respostas de URLs da mesma origem.
include
-
Diz aos navegadores para incluir credenciais em ambas requisições
same-origin
ecross-origin
, e sempre use as credenciais enviadas de volta nas respostas.Nota: As credenciais podem ser incluídas em requisições cross-origin simples e "finais", mas não devem ser incluídas em requisições de comprovação de CORS.
cache
-
Uma string indicando como a requisição vai interagir com o cache HTTP do navegador. Os valores possíveis,
default
,no-store
,reload
,no-cache
,force-cache
, eonly-if-cached
, estão documentados no artigo para a propriedadecache
do objetoRequest
. redirect
-
Como lidar com uma resposta
redirect
:follow
: Segue os redirecionamentos automaticamente. A menos que esteja definido de outra forma, o redirecionamento é definido, por padrão, comofollow
.error
: Aborta com um erro se o redirecionamento ocorrer.-
manual
: O autor da chamada pretende processar a resposta em outro contexto. Veja WHATWG fetch standard para mais informações.
referrer
-
Uma
USVString
especificando o referenciador da requisição. Isso pode ser uma URL same-origin,about:client
, ou uma string vazia. referrerPolicy
-
Especifica a referrer policy para usar para a requisição. Pode ser
no-referrer
,no-referrer-when-downgrade
,same-origin
,origin
,strict-origin
,origin-when-cross-origin
,strict-origin-when-cross-origin
ouunsafe-url
. integrity
-
Contém o valor subresource integrity da requisição (por exemplo,
sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=
). keepalive
-
A opção
keepalive
pode ser usada para permitir que a requisição sobreviva à página. A busca com a flagkeepalive
é uma substituição para a APINavigator.sendBeacon()
. signal
-
Uma instância de objeto
AbortSignal
; permite comunicar com uma requisição fetch e abortá-la, se desejado, por meio de umAbortController
.
Valor de retorno
Exceções
AbortError
-
A requisição foi abortada devido a uma chamada ao
AbortController
ou ao métodoabort()
. TypeError
-
Pode ocorrer pelos seguintes motivos:
Motivo | Exemplos de falha |
---|---|
Nome do cabeçalho inválido |
// space in "C ontent-Type" const headers = { "C ontent-Type": "text/xml", "Breaking-Bad": "<3" }; fetch('https://example.com/', { headers }); |
Valor do cabeçalho inválido. O objeto header deve conter exatamente dois elementos. |
const headers = [ ["Content-Type", "text/html", "extra"], ["Accept"], ]; fetch('https://example.com/', { headers }); |
URL inválida ou esquema, ou está usando um esquema que fetch não suporta, ou está usando um esquema que não é suportado por um modo de requisição específico. |
fetch('blob://example.com/', { mode: 'cors' }) |
URL que inclui credenciais |
fetch('https://user:password@example.com/') |
URL de referência inválida |
fetch('https://example.com/', { referrer: './abc\u0000df' }) |
Modos inválidos (navigate and websocket ) |
fetch('https://example.com/', { mode: 'navigate' }) |
Se o modo de cache da requisição é "only-if-cached" e o modo da requisição é diferente de "same-origin". |
fetch('https://example.com/', { cache: 'only-if-cached', mode: 'no-cors' }) |
Se o método da requisição for um token de nome inválido ou um dos cabeçalhos proibidos: CONNECT, TRACE or TRACK |
fetch('https://example.com/', { method: 'CONNECT' }) |
Se o modo da requisição é "no-cors" e o método da requisição não é um método CORS-safe-listed (GET, HEAD ou POST) |
fetch('https://example.com/', { method: 'CONNECT', mode: 'no-cors' }) |
Se o método da requisição é GET ou HEAD e o corpo não for nulo(null) ou undefined. |
fetch('https://example.com/', { method: 'GET', body: new FormData() }) |
Se fetch gera um erro de rede. |
Exemplos
No nosso exemplo de requisição Fetch (veja Fetch Request live) nós criamos um novo objeto Request
usando um constructor relevante, depois buscamos isso usando uma chamada ao fetch()
. Uma vez que estamos buscando uma imagem, executamos
Response.blob()
na resposta para dar a ela o tipo MIME adequado para que lidemos adequadamente
handled properly, então criamos um Objeto URL disso e exibimos isso em um elemento
<img>
.
const myImage = document.querySelector("img");
let myRequest = new Request("flowers.jpg");
fetch(myRequest)
.then(function (response) {
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return response.blob();
})
.then(function (response) {
let objectURL = URL.createObjectURL(response);
myImage.src = objectURL;
});
No exemplo Fetch
with init then Request (veja Fetch
Request init live), nós fazemos a mesma coisa exceto que passamos em um objeto
init
quando invocamos o fetch()
:
const myImage = document.querySelector("img");
let myHeaders = new Headers();
myHeaders.append("Accept", "image/jpeg");
const myInit = {
method: "GET",
headers: myHeaders,
mode: "cors",
cache: "default",
};
let myRequest = new Request("flowers.jpg");
fetch(myRequest, myInit).then(function (response) {
// ...
});
Você também poderia passar o objeto init
com o constructor
Request
para obter o mesmo efeito:
let myRequest = new Request("flowers.jpg", myInit);
Você também pode usar um object literal como headers
em
init
.
const myInit = {
method: "GET",
headers: {
Accept: "image/jpeg",
},
mode: "cors",
cache: "default",
};
let myRequest = new Request("flowers.jpg", myInit);
Especificações
Specification |
---|
Fetch Standard # fetch-method |
Compatibilidade com navegadores
BCD tables only load in the browser