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

title: formatRelativeTime
description: 格式化相对时间值，例如几分钟前或几天后。formatRelativeTime 的 API 参考。

---

在 [GT](/docs/platform/core/reference/gt-class/constructor) 实例上，根据区域设置的惯例，使用显式的时间单位格式化相对时间值。General Translation 使用内置的 `Intl.RelativeTimeFormat` API 生成诸如“2 小时前”或“3 天后”之类的表达。

## 概览 [#overview]

在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `formatRelativeTime`，传入一个数值、一个时间单位，以及一个可选的选项对象。负值表示过去，正值表示未来。该方法会返回格式化后的字符串。

```typescript
const gt = new GT();

const formatted = gt.formatRelativeTime(-1, 'day', {
  locales: 'en-US',
  numeric: 'auto',
});
// "昨天"
```

签名：

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

*注意：`formatRelativeTime` 使用 `Intl.RelativeTimeFormat` 在本地运行，无需 API 密钥。省略 `locales` 时，它会默认使用该实例的渲染区域设置。若要在没有 `GT` 实例的情况下进行格式化，请参阅独立的 [`formatRelativeTime`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time)。*

## 工作方式 [#how-it-works]

* **区域设置解析。** 省略 `locales` 时，该方法会回退到实例的渲染区域设置。
* **基于 Intl。** 格式化由浏览器原生的 [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) 负责。
* **默认值。** `numeric` 默认为 `'auto'` (因此 `-1 day` 会显示为“昨天”而不是“1 天前”) ，`style` 默认为 `'long'`。

## 参数 [#parameters]

| 参数                    | 描述                  | 类型                            | 可选 | 默认值 |
| --------------------- | ------------------- | ----------------------------- | -- | --- |
| [`value`](#value)     | 相对时间值 (过去为负，未来为正) 。 | `number`                      | 否  | —   |
| [`unit`](#unit)       | 时间单位。               | `Intl.RelativeTimeFormatUnit` | 否  | —   |
| [`options`](#options) | 格式设置。               | `object`                      | 是  | —   |

### `value` [#value]

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

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

### `unit` [#unit]

**Type** `Intl.RelativeTimeFormatUnit` · **必填**

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

### `options` [#options]

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

格式化配置：

| 名称              | 描述                         | 类型                              | 可选 | 默认值          |
| --------------- | -------------------------- | ------------------------------- | -- | ------------ |
| `locales`       | 用于格式化的区域设置。默认回退到实例的渲染区域设置。 | `string \| string[]`            | 是  | 实例区域设置       |
| `numeric`       | 是否始终使用数字形式输出。              | `'always' \| 'auto'`            | 是  | `'auto'`     |
| `style`         | 输出形式的长度。                   | `'long' \| 'short' \| 'narrow'` | 是  | `'long'`     |
| `localeMatcher` | 使用的区域设置匹配算法。               | `'best fit' \| 'lookup'`        | 是  | `'best fit'` |

## 返回值 [#returns]

**类型** `string`

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

## 示例 [#examples]

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

const gt = new GT();

// 过去时间
gt.formatRelativeTime(-2, 'hour', { locales: 'en-US' });
// 返回："2 hours ago"

// 未来时间
gt.formatRelativeTime(3, 'day', { locales: 'fr-FR' });
// 返回："dans 3 jours"

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

## 注意事项 [#notes]

* 默认值为 `numeric: 'auto'` 和 `style: 'long'`。
* 底层使用 `Intl.RelativeTimeFormat`。
* 如需根据 `Date` 自动选择时间单位，请使用 [`formatRelativeTimeFromDate`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time-from-date)。