DEV Community

Jorge Soares
Jorge Soares

Posted on

Javascript - Entendendo o toLocaleDateString

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
Enter fullscreen mode Exit fullscreen mode

ou

const option = { weekday: 'long'}
const locale = 'pt-br'
new Date().toLocaleDateString( locale, option)
// domingo
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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'

Enter fullscreen mode Exit fullscreen mode

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)

Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode


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)
Enter fullscreen mode Exit fullscreen mode

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

Top comments (5)

Collapse
 
daniloac profile image
danilo-ac • Edited

cara, sensacional! muito bem explicado e didático. me ajudou bastante!

Collapse
 
brayancomb profile image
Brayancomb

Mano, muito bem explicado, eu que vim só confirmar uma duvida e acabei aprendendo coisas novas, ajudou demais obrigado @kurybr

Collapse
 
kurybr profile image
Jorge Soares

Que bom que de alguma forma agregou pra ti Brayan ! Tmj

Collapse
 
eumatheusmoura profile image
Matheus Moura

Cara, realmente, que conteúdo rico. Muito obrigado por compartilhar. Me ajudou demais em meu projeto.

Collapse
 
daniel_santana profile image
Daniel Santana Silva

Parabéns, conteúdo show de bola!