Javascript - Entendendo o toLocaleDateString

#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 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