Date.prototype.toLocaleDateString()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.
O método toLocaleDateString()
retorna uma string com a representação de parte da data baseando-se no idioma. Os novos argumentos locales
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.
undefined
, mas se as propriedades `weekday`, `year`, `month`, `day` são todas
undefined
, então `year`, `month` and `day` são assumidos como "`numeric`".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.
Exemplos
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
.
Especificações
Specification |
---|
ECMAScript Language Specification # sec-date.prototype.tolocaledatestring |
ECMAScript Internationalization API Specification # sup-date.prototype.tolocaledatestring |
Compatibilidade com navegadores
BCD tables only load in the browser