# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<RelativeTime>`
URL: https://generaltranslation.com/ja/docs/react/reference/components/relative-time.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 「2時間前」のようなローカライズされた相対時間をフォーマットします。`<RelativeTime>` コンポーネントの API リファレンス。

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

* **2つのモード。** `Date` (`children` または `date` 経由) を渡すと、コンポーネントは `baseDate` に対する最適な単位を自動的に選択します。あるいは、`Intl.RelativeTimeFormat` と同様に、`value` と `unit` を明示的に指定することもできます。
* **ローカルでの書式設定。** 相対時間の計算と書式設定はブラウザ内で行われ、値が General Translation API に送信されることはありません。
* **入力がない場合は何もレンダリングしません。** `date` も `value` も指定されていない場合、コンポーネントは `null` をレンダリングします。

## Props [#props]

| Prop                     | 説明                                   | Type                             | 任意 | デフォルト                                |
| ------------------------ | ------------------------------------ | -------------------------------- | -- | ------------------------------------ |
| [`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]

**Type** `number` · **Optional**

相対時間の数値を明示的に指定します (たとえば、「昨日」を表す `-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' }`

この prop には [`Intl.RelativeTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options) を使用します。現在、`<RelativeTime>` は以下の options を受け取ります。

| オプション           | 説明                                     | 型                               | 任意 | デフォルト        |
| --------------- | -------------------------------------- | ------------------------------- | -- | ------------ |
| `localeMatcher` | ロケール照合アルゴリズム。                          | `'lookup' \| 'best fit'`        | はい | `'best fit'` |
| `style`         | 相対時刻の表現の長さ。                            | `'long' \| 'short' \| 'narrow'` | はい | `'long'`     |
| `numeric`       | 常に数値を使用するか、「昨日」や「明日」などの表現を使用できるようにするか。 | `'always' \| 'auto'`            | はい | `'auto'`     |

`Intl.RelativeTimeFormatOptions` のより広範な TypeScript 型に含まれるその他のフィールドは、`<RelativeTime>` には渡されません。

最新の標準 options については、[`Intl.RelativeTimeFormat` の options に関するドキュメント](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options)を参照してください。現在 `<RelativeTime>` でサポートされている options については、上記の表を確認してください。

### `locales` [#locales]

**型** `string[]` · **任意** · **既定値** アクティブなロケール

フォーマットに使用するロケールです。省略した場合は、アクティブなロケールが使用されます。[locales argument](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' を指定すると、"yesterday" の代わりに "1 day ago" と出力されます
}
```

## ハイドレーションエラーを避ける [#hydration]

`<RelativeTime>` は相対時間をローカルで計算するため、サーバーとクライアントで異なる出力になり、ハイドレーションエラーが発生することがあります。通常、これは次のような場合に起こります。

* **`baseDate` がレンダリング時に `new Date()` になる場合。** サーバーとクライアントではレンダリングされるタイミングがわずかに異なります。その間に相対時間が単位の切り替わりをまたぐと (たとえば、&quot;59 seconds ago&quot; → &quot;1 minute ago&quot;) 、出力が一致しなくなります。
* **環境ごとにデフォルトロケールが異なる場合**、生成される文字列も異なります (たとえば、&quot;hace 2 horas&quot; と &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.