Javascript - Entendendo o toLocaleDateString
Tags: javascript, tips, date, terça
Published: 2020-03-24 02:58:08

---
title: Javascript - Entendendo o toLocaleDateString
published: true
description: Uma dica rápida sobre formatação de data sem necessidade de usar outras ferramentas, usando apenas a própria classe Date do javascript
tags: javascript, tips, date, terça
---


Fala pessoal, a um tempo atrás descobri uma coisa bem legal do Javascript e queria compartilhar com vocês.

Quem usa o [moment](https://momentjs.com/) ou então outra lib apenas para dar aquela formatada básica, para o padrão da sua região, tem um jeito que é bem simples, e extremamente leve, que é usando uma função nativa da Classe `Date`, que é o `toLocaleDateString`


```javascript
const locale = 'pt-br'
new Date('03-22-2020').toLocaleDateString(locale)
// 22/03/2020
```

ou

```javascript
const option = { weekday: 'long'}
const locale = 'pt-br'
new Date().toLocaleDateString( locale, option)
// domingo
```

Um exemplo completo de uso para o uso dessa função seria algo mais ou menos assim:

```javascript
const option = {
	year: 'numeric',
	month: ('long' || 'short' || 'numeric'),
	weekday: ('long' || 'short'),
	day: 'numeric',
	hour: 'numeric',
	minute: 'numeric',
	second: 'numeric',
	era: ('long' || 'short'),
	timeZoneName: ('long' || 'short')
}
const locale = 'pt-br'
new Date().toLocaleDateString( locale, option)
// domingo, 22 de março de 2020 depois de Cristo 18:56:20 Horário Padrão de Brasília
```

Só com isso já conseguimos perceber a força que essa função tem na hora de fazer a formatação de uma data não é mesmo ? 

Se eu quisesse passar para a linguagem americana, russa, ou de qualquer outra região do mundo; Apenas trocando o `locale`, já estaria retornando na lingua. 

```javascript
const option = {
	year: 'numeric',
	month: 'long',
	weekday: 'long',
	day: 'numeric',
	hour: 'numeric',
	minute: 'numeric',
	second: 'numeric',
	era: 'long',
	timeZoneName: 'long'
}

// Português Brasil
new Date().toLocaleDateString( 'pt-br', option)
// domingo, 22 de março de 2020 depois de Cristo 18:56:20 Horário Padrão de Brasília

// Africano
new Date().toLocaleDateString( 'af', option)
// 'Maandag 23 Maart 2020 na Christus 22:30:43 Brasilia-standaardtyd'

// Arabe - Libia
new Date().toLocaleDateString( 'ar-ly', option)
// 'الاثنين، 23 مارس 2020 ميلادي 10:31:46 م توقيت برازيليا الرسمي'

// Alemão - Alemanha
new Date().toLocaleDateString( 'de-de', option)
'Montag, 23. März 2020 n. Chr., 22:33:09 Brasília-Normalzeit'

```

<small> *Vou deixar no fim do artigo um link para a lista de Localidades que você pode usar.* <small>

Agora queria detalhar um pouco mais o uso de alguns atributos dentro das opções disponíveis, até para entender o quão poderoso é essa função;

Além dos parametros básicos que fazem a formatação de uma data:

```javascript
let options = { 	
	second: ('numeric' || '2-digit'), 
	minute: ('numeric' || '2-digit'),
	hour: ('numeric' || '2-digit'), 
	day: ('numeric' || '2-digit'), 
	weekday: ('narrow' || 'long' || 'short'),
	month: ('narrow' || 'long' || 'numeric' || '2-digit' || 'short'),
	year: ('numeric' || '2-digit'),
	era: ('short' || 'long'),
	timeZoneName: ('long' || 'short')2
}
new Date().toLocaleDateString('pt-br', options)

```

Temos alguns `alias` para facilitar a formação de datas sem precisar passar essa quantidade imensa de parametros acima.

```javascript
let options = { 	
	dateStyle: ('full' || 'long' || 'medium' || 'short' ), 
	timeStyle: ('full' || 'long' || 'medium' || 'short' ), 
}
new Date().toLocaleDateString('pt-br', options)

// new Date().toLocaleDateString('pt-Br',{ dateStyle: 'full' } )
// "domingo, 22 de março de 2020"
// new Date().toLocaleDateString('pt-Br',{ dateStyle: 'long' } )
// "22 de março de 2020"
// new Date().toLocaleDateString('pt-Br',{ dateStyle: 'medium' } )
// "22 de mar. de 2020"
// new Date().toLocaleDateString('pt-Br',{ dateStyle: 'short' } )
// "22/03/2020"

// new Date().toLocaleDateString('pt-Br',{ timeStyle: 'full' } )
// "20:55:24 Horário Padrão de Brasília"
// new Date().toLocaleDateString('pt-Br',{ timeStyle: 'long' } )
// "20:55:29 BRT"
// new Date().toLocaleDateString('pt-Br',{ timeStyle: 'medium' } )
// "20:55:33"
// new Date().toLocaleDateString('pt-Br',{ timeStyle: 'short' } )
// "20:55"
```

Agora os casos mais especificos, porém podem dar uma configuração maior a *String* são:

```javascript
let options = {
	timeZone: 'America/Sao_Paulo', // Lista de Timezones no fim do artigo
	hour12: true, // Alterna entre a mostragem dos horários em 24 horas, ou então AM/PM
}
new Date().toLocaleDateString('pt-br', options)
```

O Parametro de hourCycle é usada para "Ajustar" a forma que é contado o relógio em determinado lugar, por exemplo:

> O `h23` significa que o dia, vai até as 23h59m depois muda para 00h00m, já o `h24` significa que o dia, vai até as 24h59 depois muda para 01h00m

Segue abaixo uma tabela simples para ajudar vocês

| Ciclo de horas  | Descrição  |
|---|---|
| h12  | O Sistema usado de horas é 1-12, correspondido pelo 'h' no padrão; Um relógio de 12 horas, com a meia noite iniciando as 12:00 am |
| h23  | O Sistema usado de horas é 0-23, correspondido pelo 'H' no padrão; Um relógio de 24 horas, com a meia noite iniciando as 00:00 am  |
| h24  | O Sistema usado de horas é 1-24, correspondido pelo 'k' no padrão; Um relógio de 24 horas, com a meia noite iniciando as 24:00 am  |
| h11  | O Sistema usado de horas é 0-11, correspondido pelo 'K' no padrão; Um relógio de 12 horas, com a meia noite iniciando as 00:00 am  |


```javascript
let options = {
	hourCycle: 'h23'
}
new Date().toLocaleDateString('pt-br', options)
```


<sup><sup>
[Informações mais detalhadas sobre o hourCycle](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Locale/hourCycle)
</sup></sup>


> Confesso que não entendi muito bem o funcionamento do parametro formatMatcher, porém vou deixar ele registrado aqui, quem conseguir me explicar o conceito dele, e compartilhar com o pessoal, eu agradeço 


```javascript
let options = {
	formatMatcher: ('basic' || 'best-fit') // best-fit é o formato default.
}
new Date().toLocaleDateString('pt-br', options)
```


## Considerações Finais.


Pessoal, esse é o meu primeiro texto um pouco mais técnico, tentando detalhar o funcionamento de alguma coisa.
A ideia é que com o tempo eu consiga explicar de forma melhor, e claro aprender junto com vocês;

Espero que de alguma forma esse artigo venha a ajudar outras pessoas, que assim como eu, estão em busca de conhecimento direto.


Até a próxima,



Vou deixar aqui abaixo, alguns links que usei como referencia, pra quem quiser buscar mais informações sobre algum dos assuntos que falei

### Referencias
[Lista de Código de Localidade](https://www.science.co.il/language/Locale-codes.php) </br> 
[Lista de Timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) </br>
[I Can Use](https://caniuse.com/#feat=date-tolocaledatestring) </br>
[Stack Overflow - How to Format a Javascript Date](https://stackoverflow.com/questions/3552461/how-to-format-a-javascript-date/33131823)