fetch()
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
(en-US), 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
(en-US) e/ou
Response.status
(en-US).
O método fetch()
é controlado pela diretiva connect-src
da Content Security Policy em vez da diretiva dos recursos que está recuperando.
Note: Os parâmetros do método
fetch()
são idênticos aos do construtorRequest()
.
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 (en-US) — 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 (en-US) — 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 bug 1508661). headers
-
Qualquer cabeçalho que você queira adicionar à sua requisição, contido dentro de um objeto
Headers
(en-US) 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
(en-US), ou um objetoReadableStream
(en-US). 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.Note: 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
(en-US) 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
(en-US) 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 (en-US) 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()
(en-US). signal
-
Uma instância de objeto
AbortSignal
; permite comunicar com uma requisição fetch e abortá-la, se desejado, por meio de umAbortController
(en-US).
Valor de retorno
Exceções
AbortError
-
A requisição foi abortada devido a uma chamada ao
AbortController
(en-US) ou ao métodoabort()
(en-US). 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()
(en-US) 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 nos navegadores
BCD tables only load in the browser