From 1f18bf08371d1fb5c621adbae612123ad493da92 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 19:28:43 -0300 Subject: [PATCH 01/21] fix: more accurate ptBr translations for "config_defaults" page --- posts/ptBR/config_defaults.md | 22 +++++++++++----------- posts/ptBR/res_schema.md | 2 +- ptBR.lang.js | 2 +- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/posts/ptBR/config_defaults.md b/posts/ptBR/config_defaults.md index 25eb6993..9b8237da 100644 --- a/posts/ptBR/config_defaults.md +++ b/posts/ptBR/config_defaults.md @@ -1,14 +1,14 @@ --- -title: 'Configurações padrões' +title: 'Configurações Padrão' prev_title: 'Esquema de respostas' prev_link: '/ptBR/docs/res_schema' next_title: 'Interceptadores' next_link: '/ptBR/docs/interceptors' --- -## Configurações padrões +## Configurações padrão -Você pode especificar configurações padrões que será aplicar em todas as requisições. +Você pode especificar configurações padrão que serão aplicadas a todas as requisições. ### Configurações globais do axios @@ -18,32 +18,32 @@ axios.defaults.headers.common['Authorization'] = AUTH_TOKEN; axios.defaults.headers.post['Content-Type'] = 'application/x-www-form-urlencoded'; ``` -### Padrões de instância personalizados +### Padrões para a instância ```js -// Define as configurações padrões quando cria a instância +// Define as configurações padrão quando cria a instância const instance = axios.create({ baseURL: 'https://api.example.com' }); -// Altera as configurações padrões após a instância ser criada +// Altera as configurações padrão após a instância ser criada instance.defaults.headers.common['Authorization'] = AUTH_TOKEN; ``` ### Ordem de precedência -As configurações serão mescladas pela ordem de precedente. A ordem é o padrão da biblioteca encontrados em [lib/defaults.js](https://github.com/axios/axios/blob/master/lib/defaults.js#L28), depos as propriedades `defaults` da instância, e finalmente `config` argumentos para a requisição. O último terá precedência sobre o primeiro. Aqui está um exemplo. +As configurações serão mescladas seguindo a ordem de precedência. A ordem é os padrões da biblioteca encontrados em [lib/defaults.js](https://github.com/axios/axios/blob/master/lib/defaults.js#L28), depois a propriedade `defaults` da instância, e finalmente o argumento `config` da requisição. Os últimos terão precedência sobre os primeiros. Aqui está um exemplo. ```js -// Cria uma instancia usando os padrões de configurações fornecidas pela biblioteca +// Cria uma instância usando os padrões de configuração fornecidos pela biblioteca // Neste ponto o valor do timeout é de `0` pois é o padrão da biblioteca const instance = axios.create(); -// Sobrescreve o valor do tempo de espera da biblioteca -// Agora todas as requisições que usarem está instancia terá que esperar 2.5 secundos antes do tempo se esgotar +// Sobrescreve o tempo de espera padrão da biblioteca +// Agora todas as requisições que usarem está instância terão que esperar 2.5 segundos antes do tempo se esgotar instance.defaults.timeout = 2500; -// Sobrescreve o tempo de espera para apenas está requisição por levar um tempo maior +// Sobrescreve o tempo de espera para apenas esta requisição pois sabemos que ela é demorada instance.get('/longRequest', { timeout: 5000 }); diff --git a/posts/ptBR/res_schema.md b/posts/ptBR/res_schema.md index 67949008..da548890 100644 --- a/posts/ptBR/res_schema.md +++ b/posts/ptBR/res_schema.md @@ -2,7 +2,7 @@ title: "Esquema de resposta" prev_title: "Configurações de requisição" prev_link: "/ptBR/docs/req_config" -next_title: "Configurações padrões" +next_title: "Configurações Padrão" next_link: "/ptBR/docs/config_defaults" --- diff --git a/ptBR.lang.js b/ptBR.lang.js index 7ddd1175..3dee1739 100644 --- a/ptBR.lang.js +++ b/ptBR.lang.js @@ -70,7 +70,7 @@ module.exports = { { type: "link", href: "/docs/config_defaults", - text: "Configurações Padrões", + text: "Configurações Padrão", }, { type: "link", From 52fe2342b1efb99aa69b7bba5caf3e2a4259b25f Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 19:38:26 -0300 Subject: [PATCH 02/21] =?UTF-8?q?fix:=20missing=20accent=20in=20"c=C3=B3pi?= =?UTF-8?q?a"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ptBR.lang.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ptBR.lang.js b/ptBR.lang.js index 3dee1739..57a26066 100644 --- a/ptBR.lang.js +++ b/ptBR.lang.js @@ -17,8 +17,8 @@ module.exports = { "Open Source": "Código aberto", Contribute: "Contribua", "Source on GitHub": "Código-fonte no GitHub", - "Fork on GitHub": "Faça uma copia no GitHub", - "Fork the Website": "Faça uma copia do Website", + "Fork on GitHub": "Faça uma cópia no GitHub", + "Fork the Website": "Faça uma cópia do Website", "Create an Issue": "Crie uma Issue", Next: "Próxima", Previous: "Anterior", From d6275d49f6c3ee2d8d181466c442b6af9fc92f10 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 19:39:20 -0300 Subject: [PATCH 03/21] chore: quotes on every property, added missing translations for the "sponsors" section --- ptBR.lang.js | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/ptBR.lang.js b/ptBR.lang.js index 57a26066..761a5f04 100644 --- a/ptBR.lang.js +++ b/ptBR.lang.js @@ -13,15 +13,17 @@ module.exports = { t: { "Get Started": "Começando", "View on GitHub": "Veja no GitHub", - Languages: "Idiomas", + "Languages": "Idiomas", "Open Source": "Código aberto", - Contribute: "Contribua", + "Contribute": "Contribua", "Source on GitHub": "Código-fonte no GitHub", "Fork on GitHub": "Faça uma cópia no GitHub", "Fork the Website": "Faça uma cópia do Website", "Create an Issue": "Crie uma Issue", - Next: "Próxima", - Previous: "Anterior", + "Next": "Próxima", + "Previous": "Anterior", + "Sponsors": "Apoiadores", + "Become a sponsor": "Seja um apoiador", }, sidebar: [ { From 9cd8b4b1b5e1df129290b1eca9b1c7fe1eff526d Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 19:59:08 -0300 Subject: [PATCH 04/21] feat: added missing translations, fixed some minor typos --- posts/ptBR/intro.md | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/posts/ptBR/intro.md b/posts/ptBR/intro.md index a271268d..e1f8cb47 100644 --- a/posts/ptBR/intro.md +++ b/posts/ptBR/intro.md @@ -1,14 +1,14 @@ --- title: 'Introdução' -description: 'Cliente HTTP baseado em promessas para o navegador e Node.js' +description: 'Cliente HTTP baseado em promessas para o navegador e node.js' next_title: 'Exemplos minimalistas' next_link: '/ptBR/docs/example' --- # O que é o Axios? -Axios é um cliente HTTP *[baseado-em-promessas](https://javascript.info/promise-basics)* para o [`node.js`](https://nodejs.org) e para o navegador. É *[isomórfico](https://www.lullabot.com/articles/what-is-an-isomorphic-application)* (= pode rodar no navegador e no node.js com a mesma base de código). No lado do servidor usa o código nativo do node.js - o modulo `http`, enquanto no lado do cliente (navegador) usa XMLHttpRequests. +Axios é um cliente HTTP *[baseado em promessas](https://javascript.info/promise-basics)* para o [`node.js`](https://nodejs.org) e para o navegador. É *[isomórfico](https://www.lullabot.com/articles/what-is-an-isomorphic-application)* (= pode rodar no navegador e no node.js com a mesma base de código). No lado do servidor usa o código nativo do node.js - o módulo `http`, enquanto no lado do cliente (navegador) usa XMLHttpRequests. -# Features +# Recursos - Faz [XMLHttpRequests](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) do navegador - Faz requisições [http](http://nodejs.org/api/http.html) do node.js @@ -16,7 +16,17 @@ Axios é um cliente HTTP *[baseado-em-promessas](https://javascript.info/promise - Intercepta requisições e respostas - Transforma os dados de requisições e de respostas - Cancela requisições -- Automaticamente transforma dados para JSON +- Timeouts +- Serializa parâmetros de consulta com suporte para aninhamento +- Serializa automaticamente o corpo da requisição para: + - JSON (`application/json`) + - Multipart / FormData (`multipart/form-data`) + - Formulário codificado para URL (`application/x-www-form-urlencoded`) +- Posta formulários HTML como JSON +- Lida automaticamente com dados JSON em respostas +- Captura progresso da requisição em navegadores e node.js com informações extra (velocidade, tempo restante) +- Define limites de largura de banda no node.js +- Compatível com FormData e Blob (inclusive no `node.js`) - Suporta proteções contra [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) no lado do cliente # Instalando @@ -49,4 +59,11 @@ Usando a CDN do unpkg: ```html -``` \ No newline at end of file +``` + +Módulos CommonJs para importação direta via require (se a resolução automática falhar) + +```js +const axios = require('axios/dist/browser/axios.cjs'); // navegador +const axios = require('axios/dist/node/axios.cjs'); // node +``` From 91052e31018eec0a6afd8f19d32704a1c57f2ee5 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 20:11:47 -0300 Subject: [PATCH 05/21] fix: improved ptBR translations, fixed some small typos --- posts/ptBR/example.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/posts/ptBR/example.md b/posts/ptBR/example.md index 241f1661..59d317e8 100644 --- a/posts/ptBR/example.md +++ b/posts/ptBR/example.md @@ -8,12 +8,12 @@ next_link: '/ptBR/docs/post_example' --- ## nota: Uso de CommonJS -Em ordem de usar o TypeScript (para intellissen e/ou preenchimento automático) enquanto usando CommonJS, importe com o `require()` utilize a seguinte abordagem: +Para usar o TypeScript (para intellisense e/ou preenchimento automático) enquanto utiliza importação via `require()` com CommonJS, utilize a seguinte abordagem: ```js const axios = require('axios').default; -// axios. agora o axios fornecerá preenchimento automático e tipagens de parâmetros +// axios. agora contará com preenchimento automático e tipagem de parâmetros ``` # Exemplo @@ -23,21 +23,21 @@ Executando uma requisição `GET` ```js const axios = require('axios'); -// Faz uma requisição a um usuarío com um ID expecifico +// Faz uma requisição a um usuário com um ID expecífico axios.get('/user?ID=12345') .then(function (response) { - // manipula o sucesso da requisição + // manipula a resposta da requisição console.log(response); }) .catch(function (error) { - // manipula erros da requisição - console.error(error); + // manipula os erros + console.log(error); }) .finally(function () { // sempre será executado }); -// Opcionalmente a requisição acima poderia ser feita assim da seguinte forma +// Opcionalmente a requisição acima poderia ser feita da seguinte maneira axios.get('/user', { params: { ID: 12345 @@ -47,13 +47,13 @@ axios.get('/user', { console.log(response); }) .catch(function (error) { - console.error(error); + console.log(error); }) .finally(function () { // sempre será executado }); -// Quer usar async/await? Adicione o prefixo `async` na sua função/método +// Quer usar async/await? Adicione o prefixo `async` à sua função/método async function getUser() { try { const response = await axios.get('/user?ID=12345'); @@ -63,5 +63,6 @@ async function getUser() { } } ``` + > **NOTA:** `async/await` faz parte do ECMAScript 2017 e não é suportado no Internet -> Explorer e versões antigas de browsers, use com cuidado. \ No newline at end of file +> Explorer e navegadores antigos, use com cuidado. \ No newline at end of file From dbdf0ae23a2c074553eb8011bf0c48747d9bb339 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 20:19:50 -0300 Subject: [PATCH 06/21] feat: added updated translations --- posts/ptBR/post_example.md | 61 +++++++++++++++++++++++++++++++++----- 1 file changed, 54 insertions(+), 7 deletions(-) diff --git a/posts/ptBR/post_example.md b/posts/ptBR/post_example.md index 60461092..e65f8e0c 100644 --- a/posts/ptBR/post_example.md +++ b/posts/ptBR/post_example.md @@ -1,13 +1,15 @@ --- title: 'Requisições POST' -description: 'Como executar uma requisição post com Axios' +description: 'Como executar uma requisição POST com Axios' prev_title: 'Exemplos minimalistas' prev_link: '/ptBR/docs/example' next_title: 'Axios API' next_link: '/ptBR/docs/api_intro' --- -Executando uma requisição `POST` +## Executando uma requisição `POST` + +### JSON ```js axios.post('/user', { @@ -18,7 +20,7 @@ axios.post('/user', { console.log(response); }) .catch(function (error) { - console.error(error); + console.log(error); }); ``` @@ -33,9 +35,54 @@ function getUserPermissions() { return axios.get('/user/1963/permissions'); } +const [acct, perm] = await Promise.all([getUserAccount(), getUserPermissions()]); + +// OU + Promise.all([getUserAccount(), getUserPermissions()]) - .then(function (results) { - const acct = results[0]; - const perm = results[1]; + .then(function ([acct, perm]) { + // ... }); -``` \ No newline at end of file +``` + +Enviando um formulário HTML como JSON + +```js +const {data} = await axios.post('/user', document.querySelector('#my-form'), { + headers: { + 'Content-Type': 'application/json' + } +}) +``` + +### Formulários + +- Multipart (`multipart/form-data`) + +```js +const {data} = await axios.post('https://httpbin.org/post', { + firstName: 'Santos', + lastName: 'Dumont', + orders: [1, 2, 3], + photo: document.querySelector('#fileInput').files + }, { + headers: { + 'Content-Type': 'multipart/form-data' + } + } +) +``` + +- Formulário codificado para URL (`application/x-www-form-urlencoded`) + +```js +const {data} = await axios.post('https://httpbin.org/post', { + firstName: 'Santos', + lastName: 'Dumont', + orders: [1, 2, 3] + }, { + headers: { + 'Content-Type': 'application/x-www-form-urlencoded' + } +}) +``` From 96f3e5b9e2ae5000e317df5ce5c2f6be688ca909 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 20:26:18 -0300 Subject: [PATCH 07/21] fix: fixed some typos, added missing aliases --- posts/ptBR/api_intro.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/posts/ptBR/api_intro.md b/posts/ptBR/api_intro.md index eda2400c..5b5bc189 100644 --- a/posts/ptBR/api_intro.md +++ b/posts/ptBR/api_intro.md @@ -12,9 +12,7 @@ Requisições podem ser feitas passando as configuraçãos relevantes para o `ax ##### axios(config) ```js -import axios from 'axios'; - -// Envia uma requisição post +// Envia uma requisição POST axios({ method: "post", url: "/user/12345", @@ -31,9 +29,10 @@ axios({ method: "get", url: "http://bit.ly/2mTM3nY", responseType: "stream", -}).then(function (response) { - response.data.pipe(fs.createWriteStream("ada_lovelace.jpg")); -}); +}) + .then(function (response) { + response.data.pipe(fs.createWriteStream("ada_lovelace.jpg")); + }); ``` ##### axios(url[, config]) @@ -43,7 +42,7 @@ axios({ axios("/user/12345"); ``` -### Apelidos para requisições +### Pseudônimos para requisições Por conveniência, foram fornecidos pseudônimos para todos os métodos de solicitação suportados. @@ -55,6 +54,8 @@ Por conveniência, foram fornecidos pseudônimos para todos os métodos de solic ##### axios.post(url[, data[, config]]) ##### axios.put(url[, data[, config]]) ##### axios.patch(url[, data[, config]]) +##### axios.postForm(url[, data[, config]]) +##### axios.putForm(url[, data[, config]]) +##### axios.patchForm(url[, data[, config]]) -###### INFO -Ao usar os pseudônimo dos métodos, as propriedades `url`,` method` e `data` não precisam ser especificadas na configuração. \ No newline at end of file +> NOTA: Ao usar os pseudônimos dos métodos, as propriedades `url`,` method` e `data` não precisam ser especificadas na configuração. From fe773688495fb0be632c79017ccd0ba5e5a97ff0 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 20:41:28 -0300 Subject: [PATCH 08/21] fix: fixed some typos, changed some translations to be more clear and concise --- posts/ptBR/req_config.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/posts/ptBR/req_config.md b/posts/ptBR/req_config.md index 08525b1c..8d0cc401 100644 --- a/posts/ptBR/req_config.md +++ b/posts/ptBR/req_config.md @@ -10,15 +10,15 @@ Estas são as configurações opcionais disponíveis para fazer uma requisição ```js { - // `url` é a url do servidor que será usada para a requisição + // `url` é a URL do servidor que será usada na requisição url: '/user', - // `method` é o método de requisição para ser usada em uma requisição + // `method` é o método a ser usado na requisição method: 'get', // padrão - // `baseURL` será pre-adicionada na url a menos que a `url` passada seja absoluta. - // Pode util definir uma `baseURL` para uma instância do axios para que possa passar URLs relativas - // para o método da instância. + // `baseURL` será adicionada antes da `url`, a menos que a `url` seja absoluta. + // Pode ser conveniente definir uma `baseURL` para uma instância do axios para que possa passar URLs relativas + // para os método dessa instância. baseURL: 'https://some-domain.com/api/', // `transformRequest` permite mudar os dados da requisição antes da mesma ser enviada para o servidor @@ -124,27 +124,27 @@ Estas são as configurações opcionais disponíveis para fazer uma requisição // `maxBodyLength` (Opção apenas para o Node) define o tamanho máximo permitido do conteúdo http em bytes maxBodyLength: 2000, - // `validateStatus` define se deve resolver ou rejeitar a promessa de um determinado - // código de status de resposta HTTP. Se `validateStatus` retornar `true` (ou for definido como `null` + // `validateStatus` define se deve resolver ou rejeitar a promessa de acordo com o + // código de status HTTP da resposta. Se `validateStatus` retornar `true` (ou for definido como `null` // ou `undefined`), a promessa será resolvida; caso contrário, a promessa será // rejeitada. validateStatus: function (status) { return status >= 200 && status < 300; // padrão }, - // `maxRedirects` define um número máximo de redirecionamento para seguir em node.js + // `maxRedirects` define um número máximo de redirecionamento para seguir no node.js // Se definido como 0, nenhum redirecionamento será permitido maxRedirects: 5, // padrão // `socketPath` define um UNIX Socket para ser usado em node.js. // e.g. '/var/run/docker.sock' para enviar requisições para o docker daemon. - // Apenas `socketPath` ou `proxy` podem ser especificado. + // Apenas `socketPath` ou `proxy` podem ser especificados. // Caso ambos sejam especificados, o `socketPath` será utilizado. socketPath: null, // padrão - // `httpAgent` e `httpsAgent` define um agente personalizado para ser usando quando performando uma requisições http - // ou https, no node.js. Isso permite opções a serem adicionadas como - // `keepAlive` que não está habilidado por padrão. + // `httpAgent` e `httpsAgent` definem agentes personalizados a serem usados pelas requisições http + // e https, respectivamente, no node.js. Isso permite adicionar opções, como + // `keepAlive`, que não estão habilidadas por padrão. httpAgent: new http.Agent({ keepAlive: true }), httpsAgent: new https.Agent({ keepAlive: true }), @@ -176,7 +176,7 @@ Estas são as configurações opcionais disponíveis para fazer uma requisição cancelToken: new CancelToken(function (cancel) { }), - // `decompress` indicar se o corpo da resposta deve ou não ser descomprimido + // `decompress` indica se o corpo da resposta deve ou não ser descomprimido // automaticamente. Se definido como `true` irá remover também o cabeçalho `content-encoding` // de todos os objetos resposta // - Apenas no Node (XHR não pode desligar a descompressão) From cbb14e4ec48515104915492de9dd571960f578ba Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 20:54:16 -0300 Subject: [PATCH 09/21] feat: added missing properties and updated existing ones --- posts/ptBR/req_config.md | 25 +++++++++++++++++++------ 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/posts/ptBR/req_config.md b/posts/ptBR/req_config.md index 8d0cc401..004b5e09 100644 --- a/posts/ptBR/req_config.md +++ b/posts/ptBR/req_config.md @@ -6,6 +6,7 @@ next_title: "Esquema de Resposta" next_link: "/ptBR/docs/res_schema" --- + Estas são as configurações opcionais disponíveis para fazer uma requisição. Apenas a `url` é obrigatória. Requisições serão setadas como padrão para `GET` se nenhum `method` for especificado. ```js @@ -21,6 +22,11 @@ Estas são as configurações opcionais disponíveis para fazer uma requisição // para os método dessa instância. baseURL: 'https://some-domain.com/api/', + // `allowAbsoluteUrls` define se URLs absolutas irão sobrescrever a `baseUrl` ou não. + // Se definido como true (padrão), valores absolutos na `url` irão sobrescrever `baseUrl`. + // Se definido como false, valores absolutos na `url` sempre serão adicionados à `baseUrl`. + allowAbsoluteUrls: true, + // `transformRequest` permite mudar os dados da requisição antes da mesma ser enviada para o servidor // Isto é aplicado apenas para requisições com os métodos 'PUT', 'POST', 'PATCH' e 'DELETE' // A última função no array deve retornar uma string ou o Buffer da instância, ArrayBuffer, @@ -28,20 +34,24 @@ Estas são as configurações opcionais disponíveis para fazer uma requisição // Você pode modificar o cabeçalho do objeto transformRequest: [function (data, headers) { // Faz o que quiser para transformar os dados + return data; }], - // `transformResponse` permite mudar os dados da responsta antes de ser passado para o then/catch + // `transformResponse` permite alterar os dados da responsta antes + // de serem passados para o then/catch transformResponse: [function (data) { - // Faça o que quiser para transformar os dados + // Faz o que quiser para transformar os dados + return data; }], // `headers` são cabeçalhos customizáveis para serem enviados headers: {'X-Requested-With': 'XMLHttpRequest'}, - // `params` são os parametros da URL para serem enviados junto com a requisição - // Deve sempre ser um objeto ou um objeto de URLSearchParams + // `params` são os parametros da URL a serem enviados junto com a requisição + // Deve ser um objeto ou um objeto URLSearchParams + // NOTE: parâmetros com valor null ou undefined não estarão presentes na URL. params: { ID: 12345 }, @@ -160,7 +170,6 @@ Estas são as configurações opcionais disponíveis para fazer uma requisição // `Proxy-Authorization` existente que você definiu usando `headres`. // Se o proxy do servidor utilizar HTTPS, então você deve definir o protocolo para `https`. - proxy: { protocol: 'https', host: '127.0.0.1', @@ -171,7 +180,10 @@ Estas são as configurações opcionais disponíveis para fazer uma requisição } }, - // `cancelToken` especifica um token de cancelamento que pode ser utilizado para cancelar a requisição + // `signal` é uma instância de AbortController, pode ser utilizada para cancelar a requisição + signal: new AbortController().signal, + + // (Obsoleto) `cancelToken` especifica um token de cancelamento que pode ser utilizado para cancelar a requisição // (veja a seção de Cancelamento abaixo para mais detalhes) cancelToken: new CancelToken(function (cancel) { }), @@ -181,5 +193,6 @@ Estas são as configurações opcionais disponíveis para fazer uma requisição // de todos os objetos resposta // - Apenas no Node (XHR não pode desligar a descompressão) decompress: true // padrão + } ``` From 9375f99741cc4107d42197d1c9a65119df3ba44a Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 21:03:14 -0300 Subject: [PATCH 10/21] feat: added missing translation for statusText --- posts/ptBR/res_schema.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/posts/ptBR/res_schema.md b/posts/ptBR/res_schema.md index da548890..11a6a175 100644 --- a/posts/ptBR/res_schema.md +++ b/posts/ptBR/res_schema.md @@ -16,7 +16,9 @@ A resposta para uma requisição contêm as seguintes informações. // `status` é o código de status HTTP da resposta do servido status: 200, - // `statusText` is the HTTP status message from the server response + // `statusText` é a mensagem de status HTTP da resposta do servidor + // A partir do HTTP/2 o texto deve estar em branco ou não será suportado. + // (HTTP/2 RFC: https://www.rfc-editor.org/rfc/rfc7540#section-8.1.2.4) statusText: 'OK', // `headers` os cabeçalhos HTTP com os quais o servidor respondeu From 378d4c1e75235c1596a3057906c9c51ad1ccc014 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 21:04:04 -0300 Subject: [PATCH 11/21] fix: fixed some typos, code formatting and mistranslations --- posts/ptBR/res_schema.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/posts/ptBR/res_schema.md b/posts/ptBR/res_schema.md index 11a6a175..296fe06a 100644 --- a/posts/ptBR/res_schema.md +++ b/posts/ptBR/res_schema.md @@ -13,7 +13,7 @@ A resposta para uma requisição contêm as seguintes informações. // `data` é a resposta que foi fornecida pelo servidor data: {}, - // `status` é o código de status HTTP da resposta do servido + // `status` é o código de status HTTP da resposta do servidor status: 200, // `statusText` é a mensagem de status HTTP da resposta do servidor @@ -29,8 +29,8 @@ A resposta para uma requisição contêm as seguintes informações. // `config` é a configuração que foi fornecida ao `axios` para a requisição config: {}, - // `request` é a requisição que gerou esta resposta - // É a última instância da requisição do cliente em node.js (em redirecionamentos) + // `request` é a requisição que gerou a resposta + // É a última instância da ClientRequest no node.js (em redirecionamentos) // e uma instância XMLHttpRequest no navegador request: {} } @@ -39,13 +39,14 @@ A resposta para uma requisição contêm as seguintes informações. Ao usar o `then`, você receberá a resposta da seguinte forma: ```js -axios.get("/user/12345").then(function (response) { - console.log(response.data); - console.log(response.status); - console.log(response.statusText); - console.log(response.headers); - console.log(response.config); -}); +axios.get("/user/12345") + .then(function (response) { + console.log(response.data); + console.log(response.status); + console.log(response.statusText); + console.log(response.headers); + console.log(response.config); + }); ``` -Ao usar `catch`, ou passar uma [`rejection callback`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then) como segundo parâmetro do `then`, a resposta estará disponível através do objeto `error` coomo explicado na seção de [manipulação de erros](/ptBR/docs/handling_errors). +Ao usar `catch`, ou passar uma [`rejection callback`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then) como segundo parâmetro do `then`, a resposta estará disponível através do objeto `error` como explicado na seção de [manipulação de erros](/ptBR/docs/handling_errors). From 07775b761f63d090fbea90ef2ad341b21e35a559 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 21:07:27 -0300 Subject: [PATCH 12/21] fix: updated translation for config defaults page title --- posts/ptBR/interceptors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/posts/ptBR/interceptors.md b/posts/ptBR/interceptors.md index 1ea19808..4feaa300 100644 --- a/posts/ptBR/interceptors.md +++ b/posts/ptBR/interceptors.md @@ -1,6 +1,6 @@ --- title: 'Interceptadores' -prev_title: 'Configurações padrões' +prev_title: 'Configurações Padrão' prev_link: '/ptBR/docs/config_defaults' next_title: 'Manipulando Erros' next_link: '/ptBR/docs/handling_errors' From 824c1ef986d73a26f76c956f149f49ae0df28c74 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 21:12:20 -0300 Subject: [PATCH 13/21] fix: more fitting translation for the "handling_errors" page title --- posts/ptBR/cancellation.md | 2 +- posts/ptBR/handling_errors.md | 2 +- posts/ptBR/interceptors.md | 2 +- ptBR.lang.js | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/posts/ptBR/cancellation.md b/posts/ptBR/cancellation.md index e5be5092..d19e635c 100644 --- a/posts/ptBR/cancellation.md +++ b/posts/ptBR/cancellation.md @@ -1,6 +1,6 @@ --- title: 'Cancelamento' -prev_title: 'Manipulando erros' +prev_title: 'Lidando com Erros' prev_link: '/ptBR/docs/handling_errors' next_title: 'Corpo de codificação de URL' next_link: '/ptBR/docs/urlencoded' diff --git a/posts/ptBR/handling_errors.md b/posts/ptBR/handling_errors.md index e7b7e072..8200e4bf 100644 --- a/posts/ptBR/handling_errors.md +++ b/posts/ptBR/handling_errors.md @@ -1,5 +1,5 @@ --- -title: 'Manipulando Erros' +title: 'Lidando com Erros' prev_title: 'Interceptadores' prev_link: '/ptBR/docs/interceptors' next_title: 'Cancelamento' diff --git a/posts/ptBR/interceptors.md b/posts/ptBR/interceptors.md index 4feaa300..e250a11d 100644 --- a/posts/ptBR/interceptors.md +++ b/posts/ptBR/interceptors.md @@ -2,7 +2,7 @@ title: 'Interceptadores' prev_title: 'Configurações Padrão' prev_link: '/ptBR/docs/config_defaults' -next_title: 'Manipulando Erros' +next_title: 'Lidando com Erros' next_link: '/ptBR/docs/handling_errors' --- diff --git a/ptBR.lang.js b/ptBR.lang.js index 761a5f04..434360b4 100644 --- a/ptBR.lang.js +++ b/ptBR.lang.js @@ -82,7 +82,7 @@ module.exports = { { type: "link", href: "/docs/handling_errors", - text: "Manipulando Erros", + text: "Lidando com Erros", }, { type: "link", From d057f58a91b8006aec404cbfdcb2cbb14cc56acb Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 21:14:48 -0300 Subject: [PATCH 14/21] fix: using console.log instead of console.error, added some clarity for the comments' translations --- posts/ptBR/handling_errors.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/posts/ptBR/handling_errors.md b/posts/ptBR/handling_errors.md index 8200e4bf..990481e3 100644 --- a/posts/ptBR/handling_errors.md +++ b/posts/ptBR/handling_errors.md @@ -11,24 +11,24 @@ axios.get('/user/12345') .catch(function (error) { if (error.response) { // A requisição foi feita e o servidor respondeu com um código de status - // que sai do alcance de 2xx - console.error(error.response.data); - console.error(error.response.status); - console.error(error.response.headers); + // que cai fora do intervalo 200 a 299 + console.log(error.response.data); + console.log(error.response.status); + console.log(error.response.headers); } else if (error.request) { // A requisição foi feita mas nenhuma resposta foi recebida // `error.request` é uma instância do XMLHttpRequest no navegador e uma instância de // http.ClientRequest no node.js - console.error(error.request); + console.log(error.request); } else { - // Alguma coisa acontenceu ao configurar a requisição que acionou este erro. - console.error('Error', error.message); + // Alguma coisa acontenceu ao configurar a requisição, gerando um erro. + console.log('Error', error.message); } - console.error(error.config); + console.log(error.config); }); ``` -Usando a configuração opcional `validadeStatus`, você pode definir o(s) código(s) HTTP que devem lançar um erro +Usando a configuração opcional `validadeStatus`, você pode definir o(s) código(s) HTTP que devem lançar um erro. ```js axios.get('/user/12345', { @@ -43,6 +43,6 @@ Usando o `toJSON` você pode receber um objeto com mais informações sobre o er ```js axios.get('/user/12345') .catch(function (error) { - console.error(error.toJSON()); + console.log(error.toJSON()); }); ``` \ No newline at end of file From f9ff45722c4155dc6bd873a4507d0b9f1b7d051e Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 21:24:03 -0300 Subject: [PATCH 15/21] fix: fixed "deprecated" translation to be more in line with other pages --- posts/ptBR/req_config.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/posts/ptBR/req_config.md b/posts/ptBR/req_config.md index 004b5e09..4c045abc 100644 --- a/posts/ptBR/req_config.md +++ b/posts/ptBR/req_config.md @@ -183,7 +183,7 @@ Estas são as configurações opcionais disponíveis para fazer uma requisição // `signal` é uma instância de AbortController, pode ser utilizada para cancelar a requisição signal: new AbortController().signal, - // (Obsoleto) `cancelToken` especifica um token de cancelamento que pode ser utilizado para cancelar a requisição + // (Descontinuado) `cancelToken` especifica um token de cancelamento que pode ser utilizado para cancelar a requisição // (veja a seção de Cancelamento abaixo para mais detalhes) cancelToken: new CancelToken(function (cancel) { }), From 8ecee75d8a3b2b3f2199d482eefdc53ba85542d1 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 21:42:26 -0300 Subject: [PATCH 16/21] feat: update translation for the whole page, adding missing translations and slightly altering existing ones --- posts/ptBR/cancellation.md | 96 ++++++++++++++++++++++++++++++++------ 1 file changed, 83 insertions(+), 13 deletions(-) diff --git a/posts/ptBR/cancellation.md b/posts/ptBR/cancellation.md index d19e635c..0b37dce2 100644 --- a/posts/ptBR/cancellation.md +++ b/posts/ptBR/cancellation.md @@ -6,9 +6,21 @@ next_title: 'Corpo de codificação de URL' next_link: '/ptBR/docs/urlencoded' --- -## AbortController +## Cancelando requisições -A partir da `v0.22.0`, o Axios oferece suporte ao [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) para cancelar requisições em forma de API fetch. +Definindo a propriedade `timeout` numa chamada do axios, lidamos com timeouts na **resposta**. + +Em alguns casos (caso a conexão com a rede torne-se indisponível, por exemplo) uma chamada do axios se beneficiaria de poder cancelar a **conexão** de forma prematura. Sem o cancelamento, a chamada ficará esperando até que a requisição exceda o tempo máximo definido no `timeout` (o que pode demorar alguns minutos em uma aplicação server-side). + +Para finalizar uma chamada você pode utilizar os seguintes métodos: +- `signal` +- `cancelToken` (descontinuado) + +Utilizando `timeout` em conjunto com um método de cancelamento (`signal`, por exemplo), podemos lidar com timeouts na **resposta** E TAMBÉM na **conexão** + +### `signal`: AbortController + +A partir da versão `v0.22.0`, Axios suporta o uso de [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) para cancelar requisições realizadas via API fetch: ```js const controller = new AbortController(); @@ -22,13 +34,40 @@ axios.get('/foo/bar', { controller.abort() ``` -## CancelToken `descontinuado` +Exemplo com timeout utilizando a API [`AbortSignal.timeout()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout) mais recente [nodejs 17.3+]: +```js +axios.get('/foo/bar', { + signal: AbortSignal.timeout(5000) // aborta a requisição após 5 segundos +}).then(function(response) { + //... +}); +``` + +Exemplo com uma função auxiliar: +```js +function newAbortSignal(timeoutMs) { + const abortController = new AbortController(); + setTimeout(() => abortController.abort(), timeoutMs || 0); + + return abortController.signal; +} + +axios.get('/foo/bar', { + signal: newAbortSignal(5000) // aborta a requisição após 5 segundos +}).then(function(response) { + //... +}); +``` + +### CancelToken `descontinuado` + +Você também pode cancelat uma requisição utilizando um *CancelToken*. -Você pode cancelar uma requisição usando um *cancel token*. +> A API que o axios utiliza é baseada na [proposta de promessas canceláveis](https://github.com/tc39/proposal-cancelable-promises). -> O token de cancelamento do axios é baseado em retirada [proposta de promessas canceláveis](https://github.com/tc39/proposal-cancelable-promises). +> Essa API foi descontinuada a partir da versão `v0.22.0` e não deve ser utilizada em novos projetos. -Você pode criar um token de cancelamento usando o `CancelToken.source` conforme mostrado abaixo: +Você pode criar um token de cancelamento por meio do método `CancelToken.source`, conforme mostrado abaixo: ```js const CancelToken = axios.CancelToken; @@ -38,9 +77,9 @@ axios.get('/user/12345', { cancelToken: source.token }).catch(function (thrown) { if (axios.isCancel(thrown)) { - console.log('Request canceled', thrown.message); + console.log('Requisição cancelada', thrown.message); } else { - // manipulando erro + // lida com erro } }); @@ -50,11 +89,11 @@ axios.post('/user/12345', { cancelToken: source.token }) -// cancela a requisição (o parâmetro de mensagem é opcional) -source.cancel('Operação cancelada pelo usuário'); +// cancela a requisição (a mensagem é opcional) +source.cancel('Operação cancelada pelo usuário.'); ``` -Você também poder criar um token de cancelamento passando uma função executora para o construtor de `CancelToken` +Você também pode criar um token de cancelamento passando uma função executora para o construtor de `CancelToken`: ```js const CancelToken = axios.CancelToken; @@ -62,7 +101,7 @@ let cancel; axios.get('/user/12345', { cancelToken: new CancelToken(function executor(c) { - // Uma função executora recebe uma função de cancelamento como parametro + // A função executora recebe como parâmetro uma função de cancelamento cancel = c; }) }); @@ -71,4 +110,35 @@ axios.get('/user/12345', { cancel(); ``` -> Nota: você pode cancelar multiplas requisições com o mesmo token de cancelamento. +> Nota: você pode cancelar várias requisições com o mesmo token / signal. + +Durante o período de transição, é possível utilizar ambas as APIs de cancelamento, até mesmo em uma única requisição: + +```js +const controller = new AbortController(); + +const CancelToken = axios.CancelToken; +const source = CancelToken.source(); + +axios.get('/user/12345', { + cancelToken: source.token, + signal: controller.signal +}).catch(function (thrown) { + if (axios.isCancel(thrown)) { + console.log('Requisição cancelada', thrown.message); + } else { + // lida com erro + } +}); + +axios.post('/user/12345', { + name: 'new name' +}, { + cancelToken: source.token +}) + +// cancela a requisição (a mensagem é opcional) +source.cancel('Operação cancelada pelo usuário.'); +// OR +controller.abort(); // não suporta mensagem +``` \ No newline at end of file From 6b40d12c17308c462f1320c1f3044680316d50fc Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 21:46:51 -0300 Subject: [PATCH 17/21] fix: fixed translation for "ulencoded" page title --- posts/ptBR/cancellation.md | 2 +- posts/ptBR/notes.md | 2 +- posts/ptBR/urlencoded.md | 2 +- ptBR.lang.js | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/posts/ptBR/cancellation.md b/posts/ptBR/cancellation.md index 0b37dce2..0b18f16d 100644 --- a/posts/ptBR/cancellation.md +++ b/posts/ptBR/cancellation.md @@ -2,7 +2,7 @@ title: 'Cancelamento' prev_title: 'Lidando com Erros' prev_link: '/ptBR/docs/handling_errors' -next_title: 'Corpo de codificação de URL' +next_title: 'Codificação de URL' next_link: '/ptBR/docs/urlencoded' --- diff --git a/posts/ptBR/notes.md b/posts/ptBR/notes.md index 48af275e..cd4127f2 100644 --- a/posts/ptBR/notes.md +++ b/posts/ptBR/notes.md @@ -1,7 +1,7 @@ --- title: 'Notas' description: 'Mais algumas notas para encerrar' -prev_title: 'Corpos de codificação de URL' +prev_title: 'Codificação de URL' prev_link: '/ptBR/docs/urlencoded' --- diff --git a/posts/ptBR/urlencoded.md b/posts/ptBR/urlencoded.md index ecc04299..ae889997 100644 --- a/posts/ptBR/urlencoded.md +++ b/posts/ptBR/urlencoded.md @@ -1,5 +1,5 @@ --- -title: 'Corpo de codificação de URL' +title: 'Codificação de URL' prev_title: 'Cancelamento' prev_link: '/ptBR/docs/cancellation' next_title: 'Notas' diff --git a/ptBR.lang.js b/ptBR.lang.js index 434360b4..d6c79733 100644 --- a/ptBR.lang.js +++ b/ptBR.lang.js @@ -92,7 +92,7 @@ module.exports = { { type: "link", href: "/docs/urlencoded", - text: "Corpo de codificação de URL", + text: "Codificação de URL", }, { type: "heading", From ec4bb7c53839b748e7774373af780be87a4d8350 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 21:57:15 -0300 Subject: [PATCH 18/21] feat: added missing translations --- posts/ptBR/urlencoded.md | 64 ++++++++++++++++++++++++++++------------ 1 file changed, 45 insertions(+), 19 deletions(-) diff --git a/posts/ptBR/urlencoded.md b/posts/ptBR/urlencoded.md index ae889997..eb023152 100644 --- a/posts/ptBR/urlencoded.md +++ b/posts/ptBR/urlencoded.md @@ -63,31 +63,57 @@ axios.post('http://something.com/', params.toString()); Você também pode utilizar a biblioteca [`qs`](https://github.com/ljharb/qs) -###### NOTE -A biblioteca `qs` é preferível se você precisar restringir objetos aninhados, pois o método `querystring` tem problemas conhecidos como este caso de uso (https://github.com/nodejs/node-v0.x-archive/issues/1665) +> Nota: A biblioteca `qs` é preferível se você precisar restringir objetos aninhados, pois o método `querystring` tem problemas conhecidos como este caso de uso (https://github.com/nodejs/node-v0.x-archive/issues/1665) -#### Form data +### 🆕 Serialização automática -No node.js, você pode usar a biblioteca [`form-data`](https://github.com/form-data/form-data) da seguinte forma: +Axios vai serializar os dados automaticamente para o formato *urlencoded* caso o cabeçalho `content-type` esteja definido como `application/x-www-form-urlencoded`. + +Isso funciona tanto no navegador quanto no `node.js`: ```js -const FormData = require('form-data'); - -const form = new FormData(); -form.append('my_field', 'my value'); -form.append('my_buffer', new Buffer(10)); -form.append('my_file', fs.createReadStream('/foo/bar.jpg')); - -axios.post('https://example.com', form, { headers: form.getHeaders() }) +const data = { + x: 1, + arr: [1, 2, 3], + arr2: [1, [2], 3], + users: [{name: 'Peter', surname: 'Griffin'}, {name: 'Thomas', surname: 'Anderson'}], +}; + +await axios.post('https://postman-echo.com/post', data, + {headers: {'content-type': 'application/x-www-form-urlencoded'}} +); ``` -Alternativamente, use um interceptador: +O servidor vai receber os dados assim ```js -axios.interceptors.request.use(config => { - if (config.data instanceof FormData) { - Object.assign(config.headers, config.data.getHeaders()); + { + x: '1', + 'arr[]': [ '1', '2', '3' ], + 'arr2[0]': '1', + 'arr2[1][0]': '2', + 'arr2[2]': '3', + 'arr3[]': [ '1', '2', '3' ], + 'users[0][name]': 'Peter', + 'users[0][surname]': 'griffin', + 'users[1][name]': 'Thomas', + 'users[1][surname]': 'Anderson' } - return config; -}); -``` \ No newline at end of file +``` + +Se o *parser* do seu framework (como o `body-parser` do `express.js`, por exemplo) suportar a decodificação de objetos aninhados, +você receberá no servidor o mesmo objeto que você submeteu. + +Exemplo (`express.js`) : + +```js + var app = express(); + + app.use(bodyParser.urlencoded({ extended: true })); // suporta objetos codificados + + app.post('/', function (req, res, next) { + res.send(JSON.stringify(req.body)); + }); + + server = app.listen(3000); +``` From ecef70f32f8851d201e0a8429a84e075bd9cec10 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 21:58:15 -0300 Subject: [PATCH 19/21] feat: added "new" emoji, in line with the english docs --- ptBR.lang.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ptBR.lang.js b/ptBR.lang.js index d6c79733..fc8648e7 100644 --- a/ptBR.lang.js +++ b/ptBR.lang.js @@ -92,7 +92,7 @@ module.exports = { { type: "link", href: "/docs/urlencoded", - text: "Codificação de URL", + text: "🆕 Codificação de URL", }, { type: "heading", From 4d4249aca28ae49f59d67eddf06bbd39eb2684d7 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 22:26:35 -0300 Subject: [PATCH 20/21] feat: translation for the "multipart" page --- posts/ptBR/multipart.md | 170 +++++++++++++++++++++++++++++++++++++++ posts/ptBR/notes.md | 4 +- posts/ptBR/urlencoded.md | 4 +- ptBR.lang.js | 5 ++ 4 files changed, 179 insertions(+), 4 deletions(-) create mode 100644 posts/ptBR/multipart.md diff --git a/posts/ptBR/multipart.md b/posts/ptBR/multipart.md new file mode 100644 index 00000000..e0405159 --- /dev/null +++ b/posts/ptBR/multipart.md @@ -0,0 +1,170 @@ +--- +title: 'Multipart' +prev_title: 'Codificação de URL' +prev_link: '/ptBR/docs/urlencoded' +next_title: 'Notas' +next_link: '/ptBR/docs/notes' +--- + +## Postando dados no formato `multipart/form-data` + +### Usando a API FormData + +#### Navegador + +```js +const form = new FormData(); +form.append('my_field', 'my value'); +form.append('my_buffer', new Blob([1,2,3])); +form.append('my_file', fileInput.files[0]); + +axios.post('https://example.com', form) +``` + +O mesmo resultado pode ser alcançado usando o serializador interno do Axios, em conjunto com método correnpondente: + +```js +axios.postForm('https://httpbin.org/post', { + my_field: 'my value', + my_buffer: new Blob([1,2,3]), + my_file: fileInput.files // FileList será separada em diferentes campos +}); +``` + +Formulários HTML podem ser passados diretamente para a requisição + +#### Node.js + +```js +import axios from 'axios'; + +const form = new FormData(); +form.append('my_field', 'my value'); +form.append('my_buffer', new Blob(['some content'])); + +axios.post('https://example.com', form) +``` + +Já que node.js não suporta a criação de um `Blob` a partir de um arquivo, você pode usar bibliotecas externas pra esse propósito. + +```js +import {fileFromPath} from 'formdata-node/file-from-path' + +form.append('my_field', 'my value'); +form.append('my_file', await fileFromPath('/foo/bar.jpg')); + +axios.post('https://example.com', form) +``` + +Pra versões anteriores à `v1.3.0`, você deve importar o pacote `form-data`. + +```js +const FormData = require('form-data'); + +const form = new FormData(); +form.append('my_field', 'my value'); +form.append('my_buffer', new Buffer(10)); +form.append('my_file', fs.createReadStream('/foo/bar.jpg')); + +axios.post('https://example.com', form) +``` + +### 🆕 Serialização automática + +A partir da versão `v0.27.0`, Axios suporta a serialização automática de objetos para o formato FormData +se o cabeçalho `content-type` da requisição estiver definido como `multipart/form-data`. + +A seguinte requisição irá submeter os dados como FormData (navegador e node.js): + +```js +import axios from 'axios'; + +axios.post('https://httpbin.org/post', { + user: { + name: 'Dmitriy' + }, + file: fs.createReadStream('/foo/bar.jpg') +}, { + headers: { + 'Content-Type': 'multipart/form-data' + } +}).then(({data})=> console.log(data)); +``` + +O serializador de FormData suporta algumas terminações especiais para realizar as seguintes operações: + +- `{}` - serializa o valor com JSON.stringify +- `[]` - separa os itens de uma lista/array em campos diferentes com a mesma key + +> NOTA: +> essas operações serão realizadas por padrão em listas/arrays e objetos FileList + +O serializador de FormData suporta opções adicionais por meio da propriedade `config.formSerializer: object` para lidar com casos especiais: + +- `visitor: Function` - função que será chamada recursivamente para serializar o objeto com os dados +para o formato `FormData` seguindo regras personalizadas. + +- `dots: boolean = false` - usa *dot notation* ao invés de colchetes para serializar listas/arrays e objetos; + +- `metaTokens: boolean = true` - adiciona a terminação especial (`user{}: '{"name": "John"}'`, por exemplo) à key do `FormData` +O *parser* do servidor pode utilizar essa meta-informação para transformar os dados para JSON automaticamente. + +- `indexes: null|false|true = false` - controla como os índices serão adicionados às keys de listas/arrays + + - `null` - não adiciona colchetes (`arr: 1`, `arr: 2`, `arr: 3`) + - `false`(padrão) - adiciona colchetes vazios (`arr[]: 1`, `arr[]: 2`, `arr[]: 3`) + - `true` - adiciona colchetes com índices (`arr[0]: 1`, `arr[1]: 2`, `arr[2]: 3`) + +Caso tenhamos um objeto como esse: + +```js +const obj = { + x: 1, + arr: [1, 2, 3], + arr2: [1, [2], 3], + users: [{name: 'Peter', surname: 'Griffin'}, {name: 'Thomas', surname: 'Anderson'}], + 'obj2{}': [{x:1}] +}; +``` + +As seguintes etapas serão executadas internamente pelo serializador do Axios: + +```js +const formData= new FormData(); +formData.append('x', '1'); +formData.append('arr[]', '1'); +formData.append('arr[]', '2'); +formData.append('arr[]', '3'); +formData.append('arr2[0]', '1'); +formData.append('arr2[1][0]', '2'); +formData.append('arr2[2]', '3'); +formData.append('users[0][name]', 'Peter'); +formData.append('users[0][surname]', 'Griffin'); +formData.append('users[1][name]', 'Thomas'); +formData.append('users[1][surname]', 'Anderson'); +formData.append('obj2{}', '[{"x":1}]'); +``` + +```js +import axios from 'axios'; + +axios.post('https://httpbin.org/post', { + 'myObj{}': {x: 1, s: "foo"}, + 'files[]': document.querySelector('#fileInput').files +}, { + headers: { + 'Content-Type': 'multipart/form-data' + } +}).then(({data})=> console.log(data)); +``` + +Axios suporta os seguintes métodos "atalho": `postForm`, `putForm`, `patchForm` +os quais consistem simplesmente no método http correspondente, com o header `content-type` predefinido para `multipart/form-data`. + +Um objeto `FileList` pode ser passado diretamente: + +```js +await axios.postForm('https://httpbin.org/post', document.querySelector('#fileInput').files) +``` + +Todos os arquivos serão enviados com o mesmo nome de campo: `files[]`; diff --git a/posts/ptBR/notes.md b/posts/ptBR/notes.md index cd4127f2..aba8d34f 100644 --- a/posts/ptBR/notes.md +++ b/posts/ptBR/notes.md @@ -1,8 +1,8 @@ --- title: 'Notas' description: 'Mais algumas notas para encerrar' -prev_title: 'Codificação de URL' -prev_link: '/ptBR/docs/urlencoded' +prev_title: 'Multipart' +prev_link: '/ptBR/docs/multipart' --- ## Semver diff --git a/posts/ptBR/urlencoded.md b/posts/ptBR/urlencoded.md index eb023152..7119b6f1 100644 --- a/posts/ptBR/urlencoded.md +++ b/posts/ptBR/urlencoded.md @@ -2,8 +2,8 @@ title: 'Codificação de URL' prev_title: 'Cancelamento' prev_link: '/ptBR/docs/cancellation' -next_title: 'Notas' -next_link: '/ptBR/docs/notes' +next_title: 'Multipart' +next_link: '/ptBR/docs/multipart' --- Por padrão o axios serializa os objetos do JavaScript para `JSON`. Para enviar os dados no formato `application/x-www-form-urlencoded`, você pode usar uma das seguintes opções. diff --git a/ptBR.lang.js b/ptBR.lang.js index fc8648e7..3b762457 100644 --- a/ptBR.lang.js +++ b/ptBR.lang.js @@ -94,6 +94,11 @@ module.exports = { href: "/docs/urlencoded", text: "🆕 Codificação de URL", }, + { + type: "link", + href: "/docs/multipart", + text: "🆕 Multipart", + }, { type: "heading", text: "Outros", From ba9374e58586857818c8ff6a67daefa0e10a02c9 Mon Sep 17 00:00:00 2001 From: jpricardo Date: Mon, 21 Apr 2025 22:37:47 -0300 Subject: [PATCH 21/21] fix: typo --- posts/ptBR/handling_errors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/posts/ptBR/handling_errors.md b/posts/ptBR/handling_errors.md index 990481e3..27654237 100644 --- a/posts/ptBR/handling_errors.md +++ b/posts/ptBR/handling_errors.md @@ -28,7 +28,7 @@ axios.get('/user/12345') }); ``` -Usando a configuração opcional `validadeStatus`, você pode definir o(s) código(s) HTTP que devem lançar um erro. +Usando a configuração opcional `validateStatus`, você pode definir o(s) código(s) HTTP que devem lançar um erro. ```js axios.get('/user/12345', {