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

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

* **自动选择时间单位。** 该方法会计算 `date` 与 `baseDate` 之间的差值，并自动选出最合适的时间单位 (如秒、分钟、小时、天等) 。
* **基准日期。** 比较时以 `baseDate` 为基准，其默认值为 `new Date()` (当前时间) 。
* **区域设置解析。** 省略 `locales` 时，该方法会使用实例的目标区域设置，然后依次使用源区域设置和 `en`。
* **默认值。** `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'>` · **可选**

格式化配置。下表列出了 `baseDate`、`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` |
| `baseDate`      | 用于比较的基准日期。    | `Date`                          | 是  | `new Date()`                           |
| `numeric`       | 是否始终使用数字形式输出。 | `'always' \| 'auto'`            | 是  | `'auto'`                               |
| `style`         | 输出形式的长短。      | `'long' \| 'short' \| 'narrow'` | 是  | `'long'`                               |
| `localeMatcher` | 使用的区域设置匹配算法。  | `'best fit' \| 'lookup'`        | 是  | `'best fit'`                           |

`baseDate` 是仅限 Core 的字段，不会传递给 `Intl.RelativeTimeFormat`。Core 还会将上游的 `numeric` 默认值从 `'always'` 改为 `'auto'`。

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

## Sitemap

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