# General Translation Platform: formatRelativeTime
URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time.mdx
Docs index: https://generaltranslation.com/llms.txt
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 密钥。默认使用实例的目标区域设置，然后回退到源区域设置和 `en`。若要在没有 `GT` 实例的情况下进行格式化，请参阅独立的 [`formatRelativeTime`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time)。*

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

* **区域设置解析。** 省略 `locales` 时，该方法会依次使用实例的目标区域设置、源区域设置和 `en`。

- **基于 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'`/`'seconds'`、`'minute'`/`'minutes'`、`'hour'`/`'hours'`、`'day'`/`'days'`、`'week'`/`'weeks'`、`'month'`/`'months'`、`'quarter'`/`'quarters'` 和 `'year'`/`'years'`。

### `options` [#options]

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

格式设置。下表列出了已发布的 Core 类型公开的常用选项及其实际生效的 Core 默认值。 (有关补充的标准和运行时特定详细信息，请参阅 [`Intl.RelativeTimeFormat` 构造函数选项](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options)) 。

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

Core 将上游 `numeric` 默认值从 `'always'` 更改为 `'auto'`；其他标准默认值来自 `Intl.RelativeTimeFormat`。

## 返回值 [#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)。

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.