# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<RelativeTime>`
URL: https://generaltranslation.com/ru/docs/react/reference/components/relative-time.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Форматирование локализованного относительного времени, например «2 часа назад». Справочник по API компонента `<RelativeTime>`.

Компонент `<RelativeTime>` отображает формулировки относительного времени с использованием единицы времени и правил формулирования активной локали. Он может либо автоматически выбирать наиболее подходящую единицу времени на основе `Date`, либо работать с явно заданными значением и единицей времени.

*Доступно в `gt-react`, `gt-next`, `gt-tanstack-start` и `gt-react-native`.*

## Обзор [#overview]

Передайте объект `Date` в `children`, и `<RelativeTime>` сам выберет наиболее подходящую единицу времени и отформатирует время относительно `baseDate`.

```tsx
<RelativeTime>{someDate}</RelativeTime>
// Вывод: "2 hours ago"
```

Все форматирование выполняется локально с помощью [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat).

*Примечание: `<RelativeTime>` может вызывать ошибки гидратации React в приложениях с серверным рендерингом. См. раздел [Как избежать ошибок гидратации](#hydration).*

## Как это работает [#how-it-works]

* **Два режима.** Передайте `Date` (через `children` или `date`), и компонент автоматически выберет наиболее подходящую единицу времени относительно `baseDate`, либо явно задайте `value` и `unit` — по аналогии с `Intl.RelativeTimeFormat`.
* **Локальное форматирование.** Относительное время вычисляется и форматируется в браузере; значение никогда не отправляется в API General Translation.
* **Без входных данных ничего не отображается.** Если не переданы ни дата, ни значение, компонент возвращает `null`.

## Пропсы [#props]

| Проп                     | Описание                                                                    | Тип                              | Необязательный | По умолчанию                         |
| ------------------------ | --------------------------------------------------------------------------- | -------------------------------- | -------------- | ------------------------------------ |
| [`children`](#children)  | `Date`, относительно которого вычисляется относительное время.              | `Date`                           | Да             | —                                    |
| [`date`](#date)          | `Date`, от которого выполняется вычисление. Имеет приоритет над `children`. | `Date`                           | Да             | —                                    |
| [`value`](#value)        | Явно заданное числовое значение. Требует указания `unit`.                   | `number`                         | Да             | —                                    |
| [`unit`](#unit)          | Единица времени, используется вместе с `value`.                             | `Intl.RelativeTimeFormatUnit`    | Да             | —                                    |
| [`baseDate`](#base-date) | Дата, относительно которой выполняется отсчёт.                              | `Date`                           | Да             | `new Date()`                         |
| [`options`](#options)    | Параметры `Intl.RelativeTimeFormat`.                                        | `Intl.RelativeTimeFormatOptions` | Да             | `{ numeric: 'auto', style: 'long' }` |
| [`locales`](#locales)    | Переопределяет локаль для форматирования.                                   | `string[]`                       | Да             | Активная локаль                      |
| [`name`](#name)          | Имя переменной для записи.                                                  | `string`                         | Да             | —                                    |

### `children` [#children]

**Тип** `Date` · **Необязательно**

Объект `Date`. Компонент автоматически выбирает наиболее подходящую единицу времени (от секунд до лет) и форматирует время относительно даты `baseDate`.

### `date` [#date]

**Тип** `Date` · **Необязательный**

Объект `Date`, от которого вычисляется относительное время. Если указаны и `date`, и `children`, приоритет у `date`.

### `value` [#value]

**Тип** `number` · **Необязательно**

Явно заданное числовое значение для относительного времени (например, `-1` для «вчера»). Должно использоваться вместе с `unit`.

### `unit` [#unit]

**Тип** `Intl.RelativeTimeFormatUnit` · **Необязательно**

Единица времени, например `'second'`, `'minute'`, `'hour'`, `'day'`, `'week'`, `'month'` или `'year'`. Обязателен при использовании `value`.

### `baseDate` [#base-date]

**Тип** `Date` · **Необязательный** · **По умолчанию** `new Date()`

Базовая дата, относительно которой рассчитывается относительное время. По умолчанию используется `new Date()` на момент рендеринга. Задайте её явно, чтобы избежать ошибок гидратации — см. [ниже](#hydration).

### `options` [#options]

**Тип** `Intl.RelativeTimeFormatOptions` · **Необязательный** · **По умолчанию** `{ numeric: 'auto', style: 'long' }`

Проп использует [`Intl.RelativeTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options). В настоящее время `<RelativeTime>` учитывает следующие параметры:

| Параметр        | Описание                                                                          | Тип                             | Необязательный | По умолчанию |
| --------------- | --------------------------------------------------------------------------------- | ------------------------------- | -------------- | ------------ |
| `localeMatcher` | Алгоритм сопоставления локалей.                                                   | `'lookup' \| 'best fit'`        | Да             | `'best fit'` |
| `style`         | Полнота формулировки относительного времени.                                      | `'long' \| 'short' \| 'narrow'` | Да             | `'long'`     |
| `numeric`       | Всегда ли использовать число или допускать формулировки вроде «вчера» и «завтра». | `'always' \| 'auto'`            | Да             | `'auto'`     |

Другие поля более широкого типа TypeScript `Intl.RelativeTimeFormatOptions` не передаются в `<RelativeTime>`.

Актуальный список стандартных параметров см. в [документации по параметрам `Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options). Поддерживаемые в настоящее время параметры `<RelativeTime>` перечислены в таблице выше.

### `locales` [#locales]

**Тип** `string[]` · **Необязательно** · **По умолчанию** Активная локаль

Локали, для которых выполняется форматирование. Если этот параметр опущен, используется активная локаль. См. [аргумент locales](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument).

### `name` [#name]

**Тип** `string` · **Необязательно**

Необязательное имя записи, используемое в качестве метаданных.

## Примеры [#examples]

*В примерах импортируется `gt-react`; вместо него импортируйте пакет для своего фреймворка.*

```tsx title="PostTimestamp.tsx"
import { RelativeTime } from 'gt-react';

export default function PostTimestamp({ post }) {
  return <RelativeTime>{post.createdAt}</RelativeTime>; // [!code highlight]
  // Вывод: "2 hours ago", "3 days ago", "in 5 minutes" и т.д.
}
```

```tsx title="PostTimestamp.tsx"
import { RelativeTime } from 'gt-react';

export default function PostTimestamp({ post }) {
  return <RelativeTime date={post.createdAt} />; // [!code highlight]
}
```

```tsx title="Reminder.tsx"
import { RelativeTime } from 'gt-react';

export default function Reminder() {
  return (
    <p>
      Your trial ends <RelativeTime value={3} unit="day" />. // [!code highlight]
    </p>
  );
  // Вывод: "Your trial ends in 3 days."
}
```

```tsx title="Comment.tsx"
import { T, RelativeTime } from 'gt-react';

export default function Comment({ comment }) {
  return (
    <T>
      Posted <RelativeTime>{comment.createdAt}</RelativeTime> // [!code highlight]
    </T>
  );
}
```

```tsx title="NumericTimestamp.tsx"
import { RelativeTime } from 'gt-react';

export default function NumericTimestamp({ date }) {
  return (
    <RelativeTime
      options={{
        numeric: 'always', // [!code highlight]
        style: 'narrow', // [!code highlight]
      }}
    >
      {date}
    </RelativeTime>
  );
  // При numeric: 'always', результат — "1 day ago" вместо "yesterday"
}
```

## Как избежать ошибок гидратации [#hydration]

Поскольку `<RelativeTime>` вычисляет относительное время локально, на сервере и на клиенте он может выдавать разный результат, что приводит к ошибке гидратации. Обычно это происходит, когда:

* **`baseDate` по умолчанию равен `new Date()` на момент рендеринга.** Сервер и клиент рендерят страницу с небольшой разницей во времени. Если за это время относительное время переходит через границу единицы времени (например, &quot;59 seconds ago&quot; → &quot;1 minute ago&quot;), результат не совпадёт.
* **Локаль по умолчанию различается в разных окружениях**, из-за чего получаются разные строки (например, &quot;hace 2 horas&quot; vs. &quot;2 hours ago&quot;).

Явно задайте и локаль, и общий `baseDate`, чтобы сервер и клиент всегда выдавали одну и ту же строку:

```tsx
const now = new Date(); // вычисляется один раз, передаётся и серверу, и клиенту

<RelativeTime locales={['en-US']} baseDate={now}>
  {post.createdAt}
</RelativeTime>
```

## Sitemap

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