Date.prototype.toLocaleDateString()

El método toLocaleDateString() devuelve una cadena con una representación de la fecha sensible al lenguaje. Los nuevos argumentos locales y options permiten a las aplicaciones especificar el lenguaje cuyas convenciones de formato deben usarse y permitir personalizar el comportamiento de la función. En implementaciones anteriores, las cuales ignoran los argumentos locales y options, el configuración regional usada y el formato de cadena devuelto dependen completamente de la implementación.

Sintaxis

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

Parámetros

Compruebe la sección de Compatibilidad con su navegador para ver qué navegadores suportan los argumentos locales y options, y el Ejemplo: Comprobando el soporte para los argumentos locales y options para detectar dicha característica.

locales Optional

A string with a BCP 47 language tag, or an array of such strings. To use the browser's default locale, omit this argument or pass undefined. Unicode extension are supported (for example "en-US-u-ca-buddhist"). For the general form and interpretation of the locales argument, see the Intl page. The following Unicode extension keys are allowed:

nu
Numbering system. Possible values include: "arab", "arabext", "bali", "beng", "deva", "fullwide", "gujr", "guru", "hanidec", "khmr", "knda", "laoo", "latn", "limb", "mlym", "mong", "mymr", "orya", "tamldec", "telu", "thai", "tibt".
ca
Calendar. Possible values include: "buddhist", "chinese", "coptic", "ethiopia", "ethiopic", "gregory", "hebrew", "indian", "islamic", "iso8601", "japanese", "persian", "roc".
hc
Hour cycle. Possible values include: "h11", "h12", "h23", "h24".
options Optional

An object with some or all of the following properties:

dateStyle
The date formatting style to use when calling format(). Possible values include:
  • "full"
  • "long"
  • "medium"
  • "short"
timeStyle
The time formatting style to use when calling format(). Possible values include:
  • "full"
  • "long"
  • "medium"
  • "short
fractionalSecondDigits
The number of fractional seconds to apply when calling format(). Valid values are 0-3.
calendar
Calendar. Possible values include: "buddhist", "chinese", " coptic", "ethiopia", "ethiopic", "gregory", " hebrew", "indian", "islamic", "iso8601", " japanese", "persian", "roc".
dayPeriod
The way day periods should be expressed. Possible values include: "narrow", "short", " long".
numberingSystem
Numbering System. Possible values include: "arab", "arabext", " bali", "beng", "deva", "fullwide", " gujr", "guru", "hanidec", "khmr", " knda", "laoo", "latn", "limb", "mlym", " mong", "mymr", "orya", "tamldec", " telu", "thai", "tibt".
localeMatcher
The locale matching algorithm to use. Possible values are "lookup" and "best fit"; the default is "best fit". For information about this option, see the Intl page.
timeZone
The time zone to use. The only value implementations must recognize is "UTC"; the default is the runtime's default time zone. Implementations may also recognize the time zone names of the IANA time zone database, such as "Asia/Shanghai", "Asia/Kolkata", "America/New_York".
hour12
Whether to use 12-hour time (as opposed to 24-hour time). Possible values are true and false; the default is locale dependent. This option overrides the hc language tag and/or the hourCycle option in case both are present.
hourCycle
The hour cycle to use. Possible values are "h11", "h12", "h23", or "h24". This option overrides the hc language tag, if both are present, and the hour12 option takes precedence in case both options have been specified.
formatMatcher
The format matching algorithm to use. Possible values are "basic" and "best fit"; the default is "best fit". See the following paragraphs for information about the use of this property.

The following properties describe the date-time components to use in formatted output, and their desired representations. Implementations are required to support at least the following subsets:

  • weekday, year, month, day, hour, minute, second
  • weekday, year, month, day
  • year, month, day
  • year, month
  • month, day
  • hour, minute, second
  • hour, minute

Implementations may support other subsets, and requests will be negotiated against all available subset-representation combinations to find the best match. Two algorithms are available for this negotiation and selected by the formatMatcher property: A fully specified "basic" algorithm and an implementation-dependent "best fit" algorithm.

weekday
The representation of the weekday. Possible values are:
  • "long" (e.g., Thursday)
  • "short" (e.g., Thu)
  • "narrow" (e.g., T). Two weekdays may have the same narrow style for some locales (e.g. Tuesday's narrow style is also T).
era
The representation of the era. Possible values are:
  • "long" (e.g., Anno Domini)
  • "short" (e.g., AD)
  • "narrow" (e.g., A)
year
The representation of the year. Possible values are:
  • "numeric" (e.g., 2012)
  • "2-digit" (e.g., 12)
month
The representation of the month. Possible values are:
  • "numeric" (e.g., 2)
  • "2-digit" (e.g., 02)
  • "long" (e.g., March)
  • "short" (e.g., Mar)
  • "narrow" (e.g., M). Two months may have the same narrow style for some locales (e.g. May's narrow style is also M).
day
The representation of the day. Possible values are:
  • "numeric" (e.g., 1)
  • "2-digit" (e.g., 01)
hour
The representation of the hour. Possible values are "numeric", "2-digit".
minute
The representation of the minute. Possible values are "numeric", "2-digit".
second
The representation of the second. Possible values are "numeric", "2-digit".
timeZoneName
The representation of the time zone name. Possible values are:
  • "long" (e.g., British Summer Time)
  • "short" (e.g., GMT+1)

El valor por defecto para cada propiedad del componente date-time es undefined, pero si las propiedades weekday, year, month, day son todas undefined, entonces year, month, y day se asumen tener el valor "numeric".

Valor devuelto

Una cadena representando una porción de fecha de la instancia Date indicada de acuerdo con las convenciones específicas del lenguaje.

Ejemplos

Usando toLocaleDateString()

En un caso básico sin especificar una configuración regional, se devolverá una cadena formateada en la configuración regional y las opciones por defecto.

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

// toLocaleDateString() sin argumentos dependientes de la implementación,
// de la configuración regional por defecto y la zona horaria por defecto
console.log(date.toLocaleDateString());
// → "12/11/2012" si se ejecuta en una configuración regional en-US con zona horaria America/Los_Angeles

Comprobando el soporte para los argumentos locales y options

Los argumentos locales y options no son soportados aún por todos los navegadores. Para comprobar si una implementación los soporta, puede usar el requerimiento To check whether an implementation supports them already, you can use the requirement that illegal language tags are rejected with a RangeError exception:

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

Using locales

Usando locales

Este ejemplo muestra algunas de las variaciones en los formatos de configuración regional de las fechas. Para poder obtener el formato del idioma usado en la interfaz de usuario de su aplicación, asegúrese de especificar el idioma (y posiblemente algunos idiomas alternativos) usando el argumento locales:

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

// Los formatos de abajo asumen la zona horaria local de la configuración regional;
// America/Los_Angeles para US

// El inglés de USA hace uso de orden mes-día-año
console.log(date.toLocaleDateString('en-US'));
// → "12/19/2012"

// El inglés británico hace uso del orden día-mes-año
console.log(date.toLocaleDateString('en-GB'));
// → "20/12/2012"

// El coreano hace uso del orden año-mes-día
console.log(date.toLocaleDateString('ko-KR'));
// → "2012. 12. 20."

// Evento para persa. Es difícil convertir manualmente la fecha a Solar Hijri
console.log(date.toLocaleDateString('fa-IR'));
// → "۱۳۹۱/۹/۳۰"

// El árave en la mayoría de paises arabehablantes hace uso de los dígitos árabes
console.log(date.toLocaleDateString('ar-EG'));
// → "٢٠‏/١٢‏/٢٠١٢"

// Para el japonés, las aplicaciones quieren poder usar el calendario japonés,
// donde 2012 era el año 24 de la era Heisei
console.log(date.toLocaleDateString('ja-JP-u-ca-japanese'));
// → "24/12/20"

// Cuando solicite un idioma que no esté soportado, por ejemplo el balinés,
// incluya un idioma alternativo, en este caso el indonesio
console.log(date.toLocaleDateString(['ban', 'id']));
// → "20/12/2012"

Usando options

Los resultados aportados por toLocaleDateString() pueden ser personalizados usando el argumento options:

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

// Solicita el día de la semana junto a una fecha larga
var options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
console.log(date.toLocaleDateString('de-DE', options));
// → "Donnerstag, 20. Dezember 2012"

// Una aplicación puede querer usar UTC y hacer que sea visible
options.timeZone = 'UTC';
options.timeZoneName = 'short';
console.log(date.toLocaleDateString('en-US', options));
// → "Thursday, December 20, 2012, GMT"

Performance

Cuando se formatea números largos de fechas, es mejor crear un objeto Intl.DateTimeFormat y usar la función aportada por esta propiedad format.

Especificaciones

Especificación
ECMAScript Latest Draft (ECMA-262)
La definición de 'Date.prototype.toLocaleDateString' en esta especificación.
ECMAScript Internationalization API 4.0 (ECMA-402)
La definición de 'Date.prototype.toLocaleDateString' en esta especificación.

Compatibilidad con el navegador

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome para AndroidFirefox para AndroidOpera para AndroidSafari en iOSSamsung InternetNode.js
toLocaleDateStringChrome Soporte completo 1Edge Soporte completo 12Firefox Soporte completo 1IE Soporte completo 5.5Opera Soporte completo SiSafari Soporte completo 1WebView Android Soporte completo 1Chrome Android Soporte completo 18Firefox Android Soporte completo 4Opera Android Soporte completo SiSafari iOS Soporte completo 1Samsung Internet Android Soporte completo 1.0nodejs Soporte completo Si
IANA time zone names in timeZone optionChrome Soporte completo 24Edge Soporte completo 14Firefox Soporte completo 52IE Sin soporte NoOpera Soporte completo 15Safari Soporte completo 6.1WebView Android Soporte completo 37Chrome Android Soporte completo 25Firefox Android Sin soporte NoOpera Android ? Safari iOS Soporte completo 7Samsung Internet Android Soporte completo 1.5nodejs Soporte completo Si
localesChrome Soporte completo 24Edge Soporte completo 12Firefox Soporte completo 29IE Soporte completo 11Opera Soporte completo 15Safari Soporte completo 10WebView Android Sin soporte NoChrome Android Soporte completo 26Firefox Android Soporte completo 56Opera Android Sin soporte NoSafari iOS Soporte completo 10Samsung Internet Android Soporte completo 1.5nodejs Soporte completo 0.12
Notas
Soporte completo 0.12
Notas
Notas Prior to NodeJS 13, only the locale data for en-us is available by default. When other English locales are specified, the function silently falls back to en-us. When other languages are specified, it throws a RangeError. In order to make full ICU (locale) data available for versions prior to 13, see docs on the --with-full-icu= flag and how to provide the data.
optionsChrome Soporte completo 24Edge Soporte completo 12Firefox Soporte completo 29IE Soporte completo 11Opera Soporte completo 15Safari Soporte completo 10WebView Android Sin soporte NoChrome Android Soporte completo 26Firefox Android Soporte completo 56Opera Android Sin soporte NoSafari iOS Soporte completo 10Samsung Internet Android Soporte completo 1.5nodejs Soporte completo Si

Leyenda

Soporte completo  
Soporte completo
Sin soporte  
Sin soporte
Compatibilidad desconocida  
Compatibilidad desconocida
Ver notas de implementación.
Ver notas de implementación.

Véase también