Date.prototype.toLocaleDateString()

O método toLocaleDateString() retorna uma string com a representação de parte da data baseando-se no idioma. Os novos argumentos lacales e options deixam as aplicações especificarem o idioma cujas convenções de formatação devem ser usadas e permitem customizar o comportamento da função. Em implementações antigas, nas quais ignoram os argumentos locales e options,  o locale usado e a forma da string retornada são inteiramente dependente da implementação nativa.

Sintáxe

dateObj.toLocaleDateString([locales [, options]])

Parametros

Verifique a seção Compatibilidade entre navegadores para ver quais navegadores dão suporte aos argumentos locales e options, e o Example:  Verificação para suporte dos argumentos locales e options para detectar a funcionalidade.

Return value

Uma representação em string de parte da data dada a instância Date de acordo com as convenções específicas do idioma. 

Examples

Usando toLocaleDateString()

Em uso básico sem especificação de locale, uma string formatada no padrão do locale e com as opções padrões é retornada.

var date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));

// toLocaleDateString() sem argumentos depende da implementação,
// o locale padrão, e o time zone padrão
console.log(date.toLocaleDateString());
// → "12/11/2012" se rondando em locale en-US com time zone de America/Los_Angeles

Checagem para o suporte dos argumentos locales e options

Os argumentos locales e options não são suportados em todos os browser ainda.  Para verificar se uma uma implementação já suporta eles, você pode usar o requisito de que tags de idioma ilegal são rejeitadas com uma exceção RangeError:

function toLocaleDateStringSupportsLocales() {
  try {
    new Date().toLocaleDateString('i');
  } catch (e) {
    return e.name === 'RangeError';
  }
  return false;
}

Usando locales

Esse exemplo mostra algumas das variações em formatos de data localizados. A fim de obter oformato do idioma usado na interface de usuário da usa aplicação, certifique-se de especificar esse idioma (e possivelmente algumas outros idiomas de reserva) usando o argumento locales: 

var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// os formatos abaixo assumem o time zone local do locale;
// America/Los_Angeles for the US

// Inglês americano usa a ordem mês-dia-ano
console.log(date.toLocaleDateString('en-US'));
// → "12/19/2012"

// Inglês Britânico usa a ordem dia-mês-ano
console.log(date.toLocaleDateString('en-GB'));
// → "20/12/2012"

// Coreano usa a ordem ano-mês-dia
console.log(date.toLocaleDateString('ko-KR'));
// → "2012. 12. 20."

// Árabe na maioria dos países de língua árabe usa dígitos árabes reais
console.log(date.toLocaleDateString('ar-EG'));
// → "٢٠‏/١٢‏/٢٠١٢"

// para Japonês, aplicações podem querer usar o calendário japonês,
// onde 2012 foi o ano 24 da era Heisei
console.log(date.toLocaleDateString('ja-JP-u-ca-japanese'));
// → "24/12/20"

// quando um idioma que pode não ser suportado é requerido, tal como 
// Balinês, inclua um idioma de reserva, nesse caso Indonésio
console.log(date.toLocaleDateString(['ban', 'id']));
// → "20/12/2012"

Usando options

O resultados gerados por toLocaleDateString() podem ser customizado usando o argumento options:

var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// requer um dia da semana jutamente com uma data longa
var options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
console.log(date.toLocaleDateString('de-DE', options));
// → "Donnerstag, 20. Dezember 2012"

// uma aplicação pode querer usar UTC e fazê-lo visível
options.timeZone = 'UTC';
options.timeZoneName = 'short';
console.log(date.toLocaleDateString('en-US', options));
// → "Thursday, December 20, 2012, GMT"

Performance

Ao formatar um grande número de datas, é melhor criar um objeto Intl.DateTimeFormat e usar a função fornecido porsua propriedade format.

Specifications

Browser compatibility

[1] Chrome 24 also added support for passing timeZones other than UTC.

Veja também

• Intl.DateTimeFormat
• Date.prototype.toLocaleString()
• Date.prototype.toLocaleTimeString()
• Date.prototype.toString()