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

title: formatRelativeTimeFromDate
description: 根据当前时间或另一日期，将某个日期格式化为相对时间。formatRelativeTimeFromDate 的 API 参考。

---

在 [GT](/docs/platform/core/reference/gt-class/constructor) 实例上，根据 `Date` 格式化相对时间字符串，并自动选择最合适的时间单位。General Translation 会将该日期与基准日期 (默认为当前时间) 进行比较，并生成诸如“2 小时前”或“3 天后”这样的表达。

## 概览 [#overview]

在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `formatRelativeTimeFromDate`，并传入目标 `Date` 以及一个可选的选项对象。该方法会返回格式化后的字符串，并自动选择最适合这一时间差的时间单位。

```typescript
const gt = new GT();
const pastDate = new Date(Date.now() - 7200000); // 2小时前

const formatted = gt.formatRelativeTimeFromDate(pastDate, {
  locales: 'en-US',
});
// "2小时前"
```

签名：

```typescript
formatRelativeTimeFromDate(
  date: Date,
  options?: {
    locales?: string | string[];
    baseDate?: Date;
  } & Omit<Intl.RelativeTimeFormatOptions, 'locales'>
): string
```

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

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

* **自动选择时间单位。** 该方法会计算 `date` 与 `baseDate` 之间的差值，并自动选出最合适的时间单位 (如秒、分钟、小时、天等) 。
* **基准日期。** 比较时以 `baseDate` 为基准，其默认值为 `new Date()` (当前时间) 。
* **区域设置解析。** 省略 `locales` 时，该方法会回退到该实例的渲染区域设置。
* **默认值。** `numeric` 的默认值为 `'auto'`，`style` 的默认值为 `'long'`。

## 参数 [#parameters]

| 参数                    | 描述                       | Type     | 可选 | 默认值 |
| --------------------- | ------------------------ | -------- | -- | --- |
| [`date`](#date)       | 相对于 `baseDate` 进行格式化的日期。 | `Date`   | 否  | —   |
| [`options`](#options) | 格式化配置。                   | `object` | 是  | —   |

### `date` [#date]

**类型** `Date` · **必填**

相对于 `baseDate` 进行格式化的日期。

### `options` [#options]

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

格式化配置：

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

## 返回值 [#returns]

**类型** `string`

格式化后的相对时间字符串，例如“2 小时前”或“3 天后”。

## 示例 [#examples]

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

const gt = new GT();

const now = new Date();

// 自动选择"hours"
const twoHoursAgo = new Date(now.getTime() - 7200000);
gt.formatRelativeTimeFromDate(twoHoursAgo, { locales: 'en-US', baseDate: now });
// 返回："2 hours ago"

// 自动选择"days"
const threeDaysLater = new Date(now.getTime() + 259200000);
gt.formatRelativeTimeFromDate(threeDaysLater, { locales: 'fr-FR', baseDate: now });
// 返回："dans 3 jours"
```

## 说明 [#notes]

* 会根据时间差自动选择最合适的时间单位。
* 默认值为 `numeric: 'auto'` 和 `style: 'long'`。
* 如果未提供 `baseDate`，则默认使用 `new Date()`。
* 如果需要显式指定 value + unit 进行格式化，请使用 [`formatRelativeTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time)。