Date.prototype.toLocaleTimeString()

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.

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.

Pruébalo

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.

js
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:

js
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:

js
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:

js
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 Language Specification
# sec-date.prototype.tolocaletimestring
ECMAScript Internationalization API Specification
# sup-date.prototype.tolocaletimestring

Compatibilidad con navegadores

BCD tables only load in the browser

Ver también