Date.prototype.toLocaleTimeString()

El método toLocaleTimeString() devuelve una cadena con una representación de la parte del tiempo de esta fecha sensible al idioma. Los nuevos argumentos locales y options le permiten a la aplicación especificar el idioma cuyas convenciones de formato deben usarse y personalizan el comportamiento de esta función. En implementaciones antiguas que ignoran los argumentos locales y options la localidad usada y la forma de la cadena devuelta son completamente dependientes de la implementación.

Sintaxis

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

Parámetros

Los argumentos locales y options personalizan el comportamiento de la función y le permiten a la aplicación especificar el idioma cuyas convenciones de formato deben usarse. En las implementaciones que ignoran los argumentos locales y options, la localidad y la forma de la cadena devuelta son dependientes por completo de la implementación.

Vea el constructor Intl.DateTimeFormat() para los detalles de estos parámetros y sobre cómo usarlos.

El valor predeterminado de cada componente de fecha-hora es undefined, pero si las propiedades weekday, year, month y day son todas undefined, entonces year, month y day se asumen como "numeric".

Valor devuelto

Una cadena representando la porción de tiempo de la instancia Date dada, conforme a las convenciones específicas del idioma.

Ejemplos

Usando toLocaleTimeString()

En el uso básico sin especificar una localidad, una cadena con formato en la localidad y opciones predeterminadas es devuelta.

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

// toLocaleTimeString() sin argumentos depende de la implementación,
// la localidad y la zona horaria predeterminadas
console.log(date.toLocaleTimeString());
// → "21:00:00" si se ejecuta en la localidad es-MX con la zona horaria America/Mexico_City

Verificando el soporte de argumentos locales y options

Los argumentos locales y options aún no están soportados en todos los navegadores. Para verificar si alguna implementación ya los soporta, puede usar el requerimiento de que etiquetas inválidas son rechazadas con una excepción RangeError:

function toLocaleTimeStringSoportaLocales() {
  try {
    new Date().toLocaleTimeString('i');
  } catch (e) {
    return e​.name === 'RangeError';
  }
  return false;
}

Usando locales

Este ejemplo muestra una de las variaciones en formatos de tiempo localizados. Para obtener el formato del idioma usado en la interfaz de su aplicación, asegúrese de especificar ese idioma (y posiblemente algunos de fallback) usando el argumento locales:

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

// los siguientes formatos asumen la zona horaria de la localidad;
// America/Los_Angeles para los EEUU

// El inglés americano usa formato de 12 horas con AM/PM
console.log(fecha.toLocaleTimeString('en-US'));
// → "7:00:00 PM"

// El inglés británico usa formato de 24 horas sin AM/PM
console.log(date.toLocaleTimeString('en-GB'));
// → "03:00:00"

// El koreano usa formato de 12 horas con AM/PM
console.log(date.toLocaleTimeString('ko-KR'));
// → "오후 12:00:00"

// En muchos países donde hablan árabe se usan dígitos árabes
console.log(date.toLocaleTimeString('ar-EG'));
// → "٧:٠٠:٠٠ م"

// cuando se pide un idioma que puede no estar disponible, como
// balinés, incluya un idioma de respaldo, como en este caso, indonesio
console.log(date.toLocaleTimeString(['ban', 'id']));
// → "11.00.00"

Usando options

Los resultados provistos por toLocaleTimeString() pueden ser personalizados usando el argumento options:

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

// una aplicación puede querer usar UTC y visibilizarlo:
var options = { timeZone: 'UTC', timeZoneName: 'short' };
console.log(date.toLocaleTimeString('en-US', options));
// → "3:00:00 AM GMT"

// algunas veces incluso en EEUU necesitan el tiempo en 24 horas
console.log(date.toLocaleTimeString('en-US', { hour12: false }));
// → "19:00:00"

// mostrar únicamente horas y minutos, use options con la localidad predeterminada - usar un arreglo vacío
console.log(date.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }));
// → "20:01"

Rendimiento

Cuando se da formato a un gran número de fechas, es mejor crear un objeto Intl.DateTimeFormat y usar su método format.

Especificaciones

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

Compatibilidad con navegadores

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome para AndroidFirefox para AndroidOpera para AndroidSafari en iOSSamsung InternetNode.js
toLocaleTimeStringChrome Soporte completo 1Edge Soporte completo 12Firefox Soporte completo 1IE Soporte completo 5.5Opera Soporte completo 5Safari Soporte completo 1WebView Android Soporte completo 1Chrome Android Soporte completo 18Firefox Android Soporte completo 4Opera Android Soporte completo 10.1Safari 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 Soporte completo 14Safari 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
Ver notas de implementación.
Ver notas de implementación.

Ver también