# General Translation Platform: formatRelativeTime
URL: https://generaltranslation.com/zh/docs/platform/core/reference/utility-functions/formatting/format-relative-time.mdx
---

title: formatRelativeTime
description: 无需 GT 实例即可格式化相对时间值。formatRelativeTime 的 API 参考。

---

[`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time) 是 General Translation 核心库中的一个独立实用函数，可按照区域设置的特定规则，使用显式的时间单位格式化相对时间值。它会返回诸如“2 小时前”或“3 天后”之类的字符串。

## 概览 [#overview]

直接从 `generaltranslation` 导入 `formatRelativeTime`，并传入一个值、一个时间单位和一个选项对象进行调用。它既不需要 API Key，也不需要 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例。如需使用会继承实例区域设置的实例格式化方式，请改用 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上的 [`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time) 方法。若要根据 `Date` 自动选择时间单位，请使用 [`formatRelativeTimeFromDate`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time-from-date)。

```typescript
import { formatRelativeTime } from 'generaltranslation';

const formatted = formatRelativeTime(-1, 'day', {
  locales: 'en-US',
  numeric: 'auto',
});
// 返回："yesterday"
```

签名：

```typescript
formatRelativeTime(
  value: number,
  unit: Intl.RelativeTimeFormatUnit,
  options?: { locales?: string | string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>
): string
```

## 工作原理 [#how-it-works]

* **底层 API。** 内部基于 [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat)。
* **符号约定。** 负值表示过去；正值表示将来。
* **数值模式。** 默认为 `numeric: 'auto'`，因此像 `-1 day` 这样的值会生成“昨天”，而不是“1 天前”。设置 `numeric: 'always'` 可强制输出数字形式。
* **区域设置解析。** 省略 `locales` 时，会回退到库的默认区域设置 `en`。
* **缓存。** 为了在重复使用相同区域设置和选项组合时提升性能，结果会在内部缓存。

## 参数 [#parameters]

| 参数                    | 描述                  | 类型                                                                                   | 可选 | 默认值  |
| --------------------- | ------------------- | ------------------------------------------------------------------------------------ | -- | ---- |
| [`value`](#value)     | 相对时间值 (过去为负，未来为正) 。 | `number`                                                                             | 否  | —    |
| [`unit`](#unit)       | 时间单位。               | `Intl.RelativeTimeFormatUnit`                                                        | 否  | —    |
| [`options`](#options) | 格式化配置，包括目标区域设置。     | `{ locales?: string \| string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>` | 是  | `{}` |

### `value` [#value]

**类型** `number` · **必填**

相对时间的值。负数表示过去，正数表示未来。

### `unit` [#unit]

**类型** `Intl.RelativeTimeFormatUnit` · **必填**

时间单位：`'second'`、`'minute'`、`'hour'`、`'day'`、`'week'`、`'month'` 或 `'year'`。

### `options` [#options]

**类型** `{ locales?: string | string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>` · **可选** · **默认值** `{}`

格式化配置：

| 属性              | 描述            | 类型                              | 可选 | 默认值          |
| --------------- | ------------- | ------------------------------- | -- | ------------ |
| `locales`       | 用于格式化的区域设置。   | `string \| string[]`            | 是  | `en`         |
| `numeric`       | 是否始终使用数字形式输出。 | `'always' \| 'auto'`            | 是  | `'auto'`     |
| `style`         | 输出格式的长短。      | `'long' \| 'short' \| 'narrow'` | 是  | `'long'`     |
| `localeMatcher` | 使用的区域设置匹配算法。  | `'best fit' \| 'lookup'`        | 是  | `'best fit'` |

## 返回值 [#returns]

**类型** `string`

格式化后的相对时间字符串。

## 示例 [#examples]

```typescript
import { formatRelativeTime } from 'generaltranslation';

// 过去时间
console.log(formatRelativeTime(-2, 'hour', { locales: 'en-US' }));
// 输出："2 hours ago"

// 未来时间
console.log(formatRelativeTime(3, 'day', { locales: 'en-US' }));
// 输出："in 3 days"

// 使用 numeric: 'auto'（默认值）
console.log(formatRelativeTime(-1, 'day', { locales: 'en-US' }));
// 输出："yesterday"
```

```typescript
// 格式化样式

// 长样式（默认）
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'long',
}));
// 输出："2 days ago"

// 短样式
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'short',
}));
// 输出："2 days ago"（在某些区域设置中可能缩写）

// 紧凑样式
console.log(formatRelativeTime(-2, 'day', {
  locales: 'en-US',
  style: 'narrow',
}));
// 输出："2d ago"
```

```typescript
// 多个区域设置
const locales = ['en-US', 'fr-FR', 'ja-JP', 'de-DE'];

locales.forEach((locale) => {
  console.log(`${locale}: ${formatRelativeTime(-3, 'hour', { locales: locale })}`);
});
// 输出：
// en-US: 3 hours ago
// fr-FR: il y a 3 heures
// ja-JP: 3 時間前
// de-DE: vor 3 Stunden
```

## 注意事项 [#notes]

* 默认值为 `numeric: 'auto'` 和 `style: 'long'`。
* 当使用 `numeric: 'auto'` 时，`-1 day` 这样的值会生成“昨天”，而不是“1 天前”。
* 底层基于 [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) 实现。
* 为提升性能，对于重复的区域设置/选项组合，结果会在内部缓存。