# generaltranslation: General Translation Core SDK: formatRelativeTime
URL: https://generaltranslation.com/zh/docs/core/functions/formatting/format-relative-time.mdx
---
title: formatRelativeTime
description: 用于根据区域设置惯例格式化相对时间值的独立函数
---

## 概述

独立使用的 `formatRelativeTime` 函数可在无需 GT 实例的情况下，按照特定于区域设置的惯例，使用显式单位格式化相对时间值。

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

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


## 参考资料

### 参数

| 名称        | 类型                            | 说明                                                                         |
| --------- | ----------------------------- | -------------------------------------------------------------------------- |
| `value`   | `number`                      | 相对时间值 (过去为负数，未来为正数)                                                        |
| `unit`    | `Intl.RelativeTimeFormatUnit` | 时间单位 (`'second'`、`'minute'`、`'hour'`、`'day'`、`'week'`、`'month'`、`'year'`)  |
| `options` | `object`                      | 格式化配置                                                                      |

### 选项

| 名称               | 类型                              | 说明                         |
| ---------------- | ------------------------------- | -------------------------- |
| `locales`        | `string \| string[]`            | **必填。**用于格式化的 locales 列表        |
| `numeric?`       | `'always' \| 'auto'`            | 是否始终使用数字形式的输出。默认为 `'auto'` |
| `style?`         | `'long' \| 'short' \| 'narrow'` | 输出形式的长度。默认为 `'long'`       |
| `localeMatcher?` | `'best fit' \| 'lookup'`        | 使用的区域设置匹配算法                |

### 返回值

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

***

## 示例

### 基本用法

```typescript copy
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 copy
import { formatRelativeTime } from 'generaltranslation';

// 长格式（默认）
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"
```


### 多个 locales

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

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
```

***


## 注意事项

* 默认为 `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)
* 为提升重复使用相同区域设置/选项组合时的性能，结果会在内部缓存

## 后续步骤

* 如需了解如何根据 Date 自动选择时间单位，请参阅 [`formatRelativeTimeFromDate`](/docs/core/functions/formatting/format-relative-time-from-date)
* 如需了解独立的日期/时间格式化，请参阅 [`formatDateTime`](/docs/core/functions/formatting/format-date-time)
* 如需了解基于实例的用法，请参阅 GT 类的 [`formatRelativeTime`](/docs/core/class/methods/formatting/format-relative-time)