TanStack Start v1で相対時間をフォーマットする方法

問題

「2日前」や「3時間後」のような相対的な時間表現でタイムスタンプを表示することで、ユーザーにとって時間情報がより直感的になります。しかし、これらのフレーズは言語によって異なる複雑な文法規則に従います。英語では過去の時間表現に「ago」を後置し、未来の時間表現に「in」を前置しますが、他の言語では語順が異なったり、時間単位が変化したり、まったく異なる文法構造を使用したりする場合があります。文字列の連結で手動でこれらのフレーズを構築すると、ハードコードした言語以外のすべての言語で不正確な出力が生成されます。

基本となるフォーマットAPIは数値と時間単位を必要としますが、タイムスタンプはDateオブジェクトまたはミリ秒値として到着します。タイムスタンプを適切な単位と値に変換するには、現在の時点との差を計算し、その差を表現するのに最も自然な単位を選択する必要があります。

解決策

タイムスタンプと現在の時点との時間差を計算し、その差に最も適切な単位を選択し、ロケール固有の相対時間フォーマットを使用して結果をフォーマットします。これにより、生のタイムスタンプがユーザーの言語に適応した文法的に正しいフレーズに変換されます。

react-intlの相対時間フォーマットと、最適な単位を決定するヘルパー関数を使用します。ヘルパーは時間差を各単位のしきい値と比較し、数値と単位名の両方を返します。フォーマッタはその後、アクティブなロケールに対して正しい文法規則を適用します。

ステップ

1. 単位選択ヘルパーを作成する

時間差を計算し、それを表現するのに最も自然な単位を選択する関数を構築します。

type RelativeTimeUnit =
  | "second"
  | "minute"
  | "hour"
  | "day"
  | "week"
  | "month"
  | "year";

interface RelativeTimeValue {
  value: number;
  unit: RelativeTimeUnit;
}

export function selectRelativeTimeUnit(
  timestamp: Date | number,
  baseTime: Date | number = Date.now(),
): RelativeTimeValue {
  const date = typeof timestamp === "number" ? timestamp : timestamp.getTime();
  const base = typeof baseTime === "number" ? baseTime : baseTime.getTime();
  const diffMs = date - base;
  const absDiff = Math.abs(diffMs);

  const minute = 60 * 1000;
  const hour = 60 * minute;
  const day = 24 * hour;
  const week = 7 * day;
  const month = 30 * day;
  const year = 365 * day;

  if (absDiff < minute) {
    return { value: Math.round(diffMs / 1000), unit: "second" };
  }
  if (absDiff < hour) {
    return { value: Math.round(diffMs / minute), unit: "minute" };
  }
  if (absDiff < day) {
    return { value: Math.round(diffMs / hour), unit: "hour" };
  }
  if (absDiff < week) {
    return { value: Math.round(diffMs / day), unit: "day" };
  }
  if (absDiff < month) {
    return { value: Math.round(diffMs / week), unit: "week" };
  }
  if (absDiff < year) {
    return { value: Math.round(diffMs / month), unit: "month" };
  }
  return { value: Math.round(diffMs / year), unit: "year" };
}

この関数は、時間差を固定のしきい値と比較することで、タイムスタンプを相対的な値と単位に変換します。過去の時間に対しては負の値を、未来の時間に対しては正の値を返し、フォーマッタがそれを正しく解釈します。

2. 相対時間コンポーネントを作成する

単位選択ヘルパーとreact-intlのフォーマット機能を組み合わせたコンポーネントを構築します。

import { FormattedRelativeTime } from "react-intl";
import { selectRelativeTimeUnit } from "./selectRelativeTimeUnit";

interface RelativeTimeProps {
  date: Date | number;
  numeric?: "always" | "auto";
  style?: "long" | "short" | "narrow";
}

export function RelativeTime({
  date,
  numeric = "auto",
  style = "long",
}: RelativeTimeProps) {
  const { value, unit } = selectRelativeTimeUnit(date);

  return (
    <FormattedRelativeTime
      value={value}
      unit={unit}
      numeric={numeric}
      style={style}
    />
  );
}

このコンポーネントはタイムスタンプとフォーマットオプションを受け取り、相対的な値と単位を計算し、ロケール対応のレンダリングのためにreact-intlのコンポーネントに処理を委譲します。numeric="auto"オプションは、適切な場合に「1日前」ではなく「昨日」のようなフレーズを生成します。

3. ルート内でコンポーネントを使用する

相対的なタイムスタンプを表示する必要がある場所でコンポーネントをインポートしてレンダリングします。

import { createFileRoute } from "@tanstack/react-router";
import { RelativeTime } from "../components/RelativeTime";

export const Route = createFileRoute("/posts/$postId")({
  component: PostPage,
});

function PostPage() {
  const post = {
    title: "Understanding Relative Time",
    publishedAt: new Date("2024-11-15T10:30:00Z"),
    updatedAt: new Date(Date.now() - 2 * 60 * 60 * 1000),
  };

  return (
    <article>
      <h1>{post.title}</h1>
      <p>
        Published <RelativeTime date={post.publishedAt} />
      </p>
      <p>
        Updated <RelativeTime date={post.updatedAt} style="short" />
      </p>
    </article>
  );
}

このコンポーネントはサーバーレンダリングとクライアントレンダリングの両方のコンテキストで動作します。サーバー上では初期の相対時間フレーズを生成し、クライアント上ではIntlProviderからユーザーのロケールを使用して同じフレーズを表示します。

4. 命令型フォーマットオプションを追加する

フォーマットされた文字列を直接必要とする場合のために、フックベースのヘルパーを作成します。

import { useIntl } from "react-intl";
import { selectRelativeTimeUnit } from "./selectRelativeTimeUnit";

export function useRelativeTime() {
  const intl = useIntl();

  return (
    date: Date | number,
    options?: {
      numeric?: "always" | "auto";
      style?: "long" | "short" | "narrow";
    },
  ) => {
    const { value, unit } = selectRelativeTimeUnit(date);
    return intl.formatRelativeTime(value, unit, options);
  };
}

このフックはタイムスタンプを命令的にフォーマットする関数を返します。テキスト属性の設定やJSX外での値の計算に役立ちます。

5. コンポーネント以外のコンテキストでフックを使用する

属性やロジックのためにフォーマットされた文字列が必要なコンポーネントでフックを呼び出します。

import { createFileRoute } from "@tanstack/react-router";
import { useRelativeTime } from "../hooks/useRelativeTime";

export const Route = createFileRoute("/events/$eventId")({
  component: EventPage,
});

function EventPage() {
  const formatRelativeTime = useRelativeTime();
  const event = {
    name: "Product Launch",
    startTime: new Date(Date.now() + 3 * 24 * 60 * 60 * 1000),
  };

  const timeUntil = formatRelativeTime(event.startTime);

  return (
    <div>
      <h1>{event.name}</h1>
      <time dateTime={event.startTime.toISOString()} title={timeUntil}>
        {timeUntil}
      </time>
    </div>
  );
}

このフックは関数形式で同じフォーマットロジックを提供するため、属性、計算値、またはコンポーネントをレンダリングできない場所で相対時間の文字列を使用できます。