# General Translation Platform: formatRelativeTimeFromDate
URL: https://generaltranslation.com/zh/docs/platform/core/reference/utility-functions/formatting/format-relative-time-from-date.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 无需 GT 实例即可根据日期格式化相对时间。formatRelativeTimeFromDate 的 API 参考。

[`formatRelativeTimeFromDate`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time-from-date) 是 General Translation Core 库中的一个独立工具函数，用于根据 `Date` 生成相对时间字符串，并自动选择最合适的时间单位 (秒、分钟、小时、天、周、月或年) 。

## 概览 [#overview]

直接从 `generaltranslation` 导入 `formatRelativeTimeFromDate`，并传入一个 `Date` 和一个选项对象进行调用。它不需要 API Key，也不需要 [GT](/docs/platform/core/reference/gt-class/constructor) 实例。若要使用基于实例且继承实例区域设置的格式化方式，请改用 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上的 [`formatRelativeTimeFromDate`](/docs/platform/core/reference/gt-class-methods/formatting/format-relative-time-from-date) 方法。若要自行指定具体的值和时间单位进行格式化，请使用 [`formatRelativeTime`](/docs/platform/core/reference/utility-functions/formatting/format-relative-time)。

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

const pastDate = new Date(Date.now() - 7200000); // 2小时前
const formatted = formatRelativeTimeFromDate(pastDate, {
  locales: 'en-US',
  baseDate: new Date(),
});
// 返回："2 hours ago"
```

签名：

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

## 工作原理 [#how-it-works]

* **时间单位选择。** 根据 `date` 与 `baseDate` 的差值自动选择最合适的时间单位。
* **底层 API。** 底层基于 [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) 实现。
* **数字模式。** 默认使用 `numeric: 'auto'` 和 `style: 'long'`。
* **基准日期默认值。** 如果未提供 `baseDate`，则默认使用 `new Date()`。请注意，这可能会在服务器端渲染的应用中导致 hydration 不匹配。
* **区域设置解析。** 如果省略 `locales`，则会回退到该 库 的默认区域设置 `en`。

## 参数 [#parameters]

| 参数                    | 说明                        | 类型                                                                                                       | 可选 | 默认值  |
| --------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- | -- | ---- |
| [`date`](#date)       | 相对于 `baseDate` 进行格式化的日期。  | `Date`                                                                                                     | 否  | —    |
| [`options`](#options) | 格式化配置，包括目标区域设置和作为比较基准的日期。 | `{ locales?: string \| string[] } & Omit<Intl.RelativeTimeFormatOptions, 'locales'> & { baseDate?: Date }` | 是  | `{}` |

### `date` [#date]

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

要相对于 `baseDate` 进行格式化的 `Date`。

### `options` [#options]

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

格式化配置。该表列出了 `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[]`            | 是  | `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 { formatRelativeTimeFromDate } from 'generaltranslation';

const now = new Date();

// 2小时前
const pastDate = new Date(now.getTime() - 7200000);
console.log(formatRelativeTimeFromDate(pastDate, {
  locales: 'en-US',
  baseDate: now,
}));
// 输出: "2 hours ago"

// 3天后
const futureDate = new Date(now.getTime() + 259200000);
console.log(formatRelativeTimeFromDate(futureDate, {
  locales: 'en-US',
  baseDate: now,
}));
// 输出: "in 3 days"
```

```typescript
// 多个区域设置
const pastDate = new Date(Date.now() - 86400000); // ~1天前
const now = new Date();

const locales = ['en-US', 'fr-FR', 'ja-JP', 'de-DE'];

locales.forEach((locale) => {
  console.log(`${locale}: ${formatRelativeTimeFromDate(pastDate, {
    locales: locale,
    baseDate: now,
  })}`);
});
// 输出：
// en-US: yesterday
// fr-FR: hier
// ja-JP: 昨日
// de-DE: gestern
```

## Notes [#notes]

* 根据 `date` 与 `baseDate` 之间的差值，自动选择最合适的时间单位。
* 默认值为 `numeric: 'auto'` 和 `style: 'long'`。
* 如果未提供 `baseDate`，则默认使用 `new Date()`——请注意，这可能会在服务器端渲染应用中导致 hydration 不匹配。
* 底层基于 [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat)。

## Sitemap

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