Javascript - Entendendo o toLocaleDateString · kurybr

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

Quem usa o moment 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

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

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:

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.

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'

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

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:

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.

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:

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

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

^{^{Informações mais detalhadas sobre o hourCycle}}

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

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

Lista de Timezones

I Can Use

Stack Overflow - How to Format a Javascript Date