WindowOrWorkerGlobalScope.fetch()
O método fetch()
do mixin WindowOrWorkerGlobalScope
inicia um processo de busca de um recurso da rede. Este, retorna uma promessa que resolve o objeto Response
que representa a resposta a sua requisição.
WorkerOrGlobalScope
é implementado por Window
e WorkerGlobalScope
, o que significa que o método fetch()
está disponível em praticamente qualquer contexto em que você possa querer obter recursos.
Uma promessa fetch()
rejeita com um TypeError
quando um erro de rede é encontrado, embora isso geralmente signifique um problema de permissões ou similar. Uma verificação precisa de um fetch()
bem-sucedido incluiria a verificação de uma promessa resolvida, e depois verificando se a propriedade Response.ok
possui valor true
. Um status HTTP 404 não constitui um erro de rede.
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
Promise<Response> fetch(input[, init]);
Parâmetros
- input
- Isto define o recurso que você deseja buscar. Isto pode ser:
- init Optional
- Um objeto opcional que contém configurações personalizadas que você pode aplicar à requisição. As opções possíveis são:
method
: Método HTTP, por exemplo,GET
,POST
.headers
: Qualquer cabeçalho que você queira adicionar à sua requisição, contido dentro de um objetoHeaders
ou um objeto literal com valoresByteString
.body
: Qualquer corpo que você queira adicionar à sua requisição: podendo ser umBlob
,BufferSource
,FormData
,URLSearchParams
, ou um objetoUSVString
. Note que uma requisição usando os métodosGET
ouHEAD
não pode ter um corpo.mode
: O modo que deseja usar para a requisição, por exemplo,cors
,no-cors
, ousame-origin.
credentials
: A credencial que deseja usar para a requisição:omit
,same-origin
, ouinclude
. Para enviar automaticamente cookies para o domínio atual, esta opção deve ser fornecida. Começando com o Chrome 50, essa propriedade também usa uma instânciaFederatedCredential
ou uma instânciaPasswordCredential
.cache
: O modo de cache que deseja usar na requisição:default
,no-store
,reload
,no-cache
,force-cache
, ouonly-if-cached
.redirect
: O modo de redirecionamento pode usar:follow
(segue automaticamente o redirecionamento),error
(aborta com um erro se ocorrer um redirecionamento), oumanual
(manipula redirecionamentos manualmente). No Chrome o padrão foifollow
antes do Chrome 47 emanual
a partir do Chrome 47.referrer
: UmUSVString
especificandono-referrer
,client
, ou uma URL. O padrão éclient
.referrerPolicy
: Especifica o valor do cabeçalho HTTP referer. Pode ser um destes:no-referrer
,no-referrer-when-downgrade
,origin
,origin-when-cross-origin
,unsafe-url
.integrity
: Contém o valor de integridade de subrecurso da requisição (por exemplo,sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=
).signal
: Uma instância do objetoFetchSignal
; permite que você se comunique com um pedido de busca e controle-o através de umFetchController
.observe
: Um objetoObserverCallback
— o objetivo exclusivo deste objeto é fornecer uma função de retorno de chamada que é executada quando a solicitação fetch é executada. Isto retorna um objetoFetchObserver
que pode ser usado para recuperar informações sobre o status de uma solicitação fetch.
Valor de Retorno
Exceptions
Tipo | Descrição |
---|---|
TypeError |
Desdo o Firefox 43, fetch() lançará um TypeError se a URL tiver credenciais, como http://user:password@example.com . |
Example
In our Fetch Request example (see Fetch Request live) we create a new Request
object using the relevant constructor, then fetch it using a fetch()
call. Since we are fetching an image, we run Body.blob()
on the response to give it the proper MIME type so it will be handled properly, then create an Object URL of it and display it in an <img>
element.
var myImage = document.querySelector('img');
var myRequest = new Request('flowers.jpg');
fetch(myRequest).then(function(response) {
return response.blob();
}).then(function(response) {
var objectURL = URL.createObjectURL(response);
myImage.src = objectURL;
});
In our Fetch with init then Request example (see Fetch Request init live) we do the same thing except that we pass in an init object when we invoke fetch()
:
var myImage = document.querySelector('img');
var myHeaders = new Headers();
myHeaders.append('Content-Type', 'image/jpeg');
var myInit = { method: 'GET',
headers: myHeaders,
mode: 'cors',
cache: 'default' };
var myRequest = new Request('flowers.jpg');
fetch(myRequest,myInit).then(function(response) {
...
});
Note that you could also pass the init object in with the Request
constructor to get the same effect, e.g.:
var myRequest = new Request('flowers.jpg', myInit);
You can also use an object literal as headers
in init
.
var myInit = { method: 'GET',
headers: {
'Content-Type': 'image/jpeg'
},
mode: 'cors',
cache: 'default' };
var myRequest = new Request('flowers.jpg', myInit);
Specifications
Specification | Status | Comment |
---|---|---|
Fetch The definition of 'fetch()' in that specification. |
Padrão em tempo real | Defined in a WindowOrWorkerGlobalScope partial in the newest spec. |
Fetch The definition of 'fetch()' in that specification. |
Padrão em tempo real | Initial definition |
Credential Management Level 1 | Rascunho atual | Adds FederatedCredential or PasswordCredential instance as a possible value for init.credentials . |
Browser compatibility
Feature | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari (WebKit) |
---|---|---|---|---|---|---|
Basic support | 42 | 14 | 34 (34)[1] 39 (39) 52 (52)[2] |
Não suportado | 29 28[1] |
Não suportado |
Streaming response body | 43 | 14 | ? | ? | ? | ? |
Support for blob: and data: |
48 | Não suportado | ? | ? | ? | ? |
referrerPolicy |
52 | ? | ? | ? | 39 | ? |
signal and observer |
Não suportado | Não suportado | Não suportado[3] | Não suportado | Não suportado | Não suportado |
Feature | Android | Android Webview | Edge | Firefox Mobile (Gecko) | IE Phone | Opera Mobile | Safari Mobile | Chrome for Android |
---|---|---|---|---|---|---|---|---|
Basic support | Não suportado | 42 | 14 | 52.0 (52)[2] | Não suportado | Não suportado | Não suportado | 42 |
Streaming response body | Não suportado | 43 | 14 | ? | ? | ? | ? | 43 |
Support for blob: and data: |
Não suportado | 43 | Não suportado | ? | ? | ? | ? | 43 |
referrerPolicy |
Não suportado | 52 | ? | ? | ? | 39 | ? | 52 |
signal and observer |
Não suportado | Não suportado | Não suportado | Não suportado[3] | Não suportado | Não suportado | Não suportado | Não suportado |
[1] API is implemented behind a preference.
[2] fetch()
now defined on WindowOrWorkerGlobalScope
mixin.
[3] Hidden behind a preference in 55+ Nightly. In about:config, you need to create two new boolean prefs — dom.fetchObserver.enabled
and dom.fetchController.enabled
— and set the values of both to true
.