Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Intl.RelativeTimeFormat.prototype.format() — formatear tiempo relativo

Convierte un desplazamiento temporal con signo y una unidad explícita en texto localizado. El método no calcula la diferencia entre fechas.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

const formatter = new Intl.RelativeTimeFormat(locales, options);
formatter.format(value, unit);

Intl.RelativeTimeFormat.prototype.format es un método de instancia. formatter.format(value, unit) devuelve una cadena según la configuración regional que se haya resuelto y las opciones fijadas en el constructor. La aplicación calcula el desplazamiento respecto a un punto de referencia y elige la unidad; el método no consulta el reloj ni resta fechas.

Los valores negativos indican el pasado y los positivos, el futuro. Si se usa un patrón numérico, -0 selecciona el patrón de pasado y +0 el de futuro. unit admite los identificadores exactos "second", "minute", "hour", "day", "week", "month", "quarter" y "year", así como sus formas terminadas en s. La forma del identificador no determina la gramática del resultado.

numeric: "always" (opción predeterminada) usa un patrón numérico. numeric: "auto" usa una expresión específica si está disponible, como yesterday; si no, recurre a un patrón numérico. style permite elegir "long" (opción predeterminada), "short" o "narrow". La compatibilidad depende del entorno de ejecución; incluso con la misma configuración regional, el texto puede variar, por ejemplo, por el uso de espacios de no separación. En pruebas portables, no compares el resultado con texto fijo.

El método necesita una instancia como this; llamarlo por separado sin un this válido lanza TypeError. Para usarlo como función de retorno de llamada, utiliza formatter.format.bind(formatter). Tras comprobar this, el método aplica ToNumber a value y luego ToString a unit. Por ejemplo, un BigInt como value lanza TypeError. Tras la conversión, NaN, Infinity, -Infinity o un identificador de unidad no admitido provocan RangeError.

Ejemplos

{
  const numeric = new Intl.RelativeTimeFormat("en", { numeric: "always" });
  const auto = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
  const past = numeric.format(-1, "day");
  console.log(past);
  console.log(auto.format(-1, "day"));
  console.log(past === numeric.format(-1, "days"));
}

Resultado

1 day ago
yesterday
true

Para el mismo desplazamiento de `-1` día, las dos primeras líneas muestran el texto habitual en inglés con `"always"` y `"auto"`. La tercera muestra que `"day"` y `"days"` son equivalentes.

Lecciones relacionadas

  • JavaScript · Lección 24 · Avanzado · Versión: 4

Fuentes