Zahlen für verschiedene Locales in TanStack Start v1 formatieren

Problem

Zahlen werden weltweit unterschiedlich geschrieben. Was in den Vereinigten Staaten als 10,000.5 erscheint, wird in Deutschland zu 10.000,5 – Kommas und Punkte tauschen ihre Rollen vollständig. Dies ist keine Frage der Präferenz oder des Stils, sondern der Lesbarkeit. Ein deutscher User, der 10,000.5 sieht, könnte es als zehn lesen und die Gruppierungstrennzeichen ignorieren. Ein amerikanischer User, der 10.000,5 sieht, könnte es als zehntausend lesen und das Dezimaltrennzeichen ignorieren. Dieselben Ziffern, gegensätzliche Bedeutungen.

Wenn Anwendungen Zahlen ohne Berücksichtigung regionaler Formatierungskonventionen anzeigen, erzeugen sie Verwirrung und untergraben das Vertrauen. User erwarten, dass Zahlen den Mustern folgen, die sie gelernt haben, und Abweichungen von diesen Mustern zwingen sie, innezuhalten, neu zu interpretieren und zu hinterfragen, ob die Daten korrekt sind.

Lösung

Formatieren Sie Zahlen basierend auf dem Locale des Users unter Verwendung regionaler Regeln für Dezimal- und Gruppierungstrennzeichen. Dies wandelt numerische Werte in Strings um, die den Formatierungsregeln folgen, die Usern in ihrer Region vertraut sind.

React-intl bietet Komponenten und Hooks, die die im Browser integrierte Intl.NumberFormat-API nutzen, um locale-spezifische Formatierung anzuwenden. Durch Übergabe eines numerischen Werts und des aktuellen Locales wählen diese Tools automatisch die korrekten Trennzeichen, Zifferngruppierung und andere regionale Konventionen aus. Das Ergebnis ist ein formatierter String, der den Erwartungen der User entspricht, ohne manuelle String-Manipulation oder locale-spezifische Logik in Ihren Komponenten.

Schritte

1. Erstellen Sie eine Zahlenanzeige-Komponente mit FormattedNumber

Erstellen Sie eine Komponente, die einen numerischen Wert akzeptiert und ihn mit locale-gerechter Formatierung unter Verwendung der FormattedNumber-Komponente von react-intl rendert.

import { FormattedNumber } from "react-intl";

interface PriceDisplayProps {
  value: number;
}

export function PriceDisplay({ value }: PriceDisplayProps) {
  return (
    <div>
      <FormattedNumber value={value} />
    </div>
  );
}

Die FormattedNumber-Komponente wendet automatisch die Dezimal- und Gruppierungstrennzeichen der Locale an. Sie liest die Locale vom nächstgelegenen IntlProvider im Komponentenbaum und formatiert die Zahl entsprechend.

2. Zahlen mit spezifischen Stilen formatieren

Passen Sie die Zahlenformatierung an, indem Sie Stiloptionen an FormattedNumber für Währungen, Prozentsätze oder Einheiten übergeben.

import { FormattedNumber } from "react-intl";

interface MetricsProps {
  revenue: number;
  growthRate: number;
  fileSize: number;
}

export function Metrics({ revenue, growthRate, fileSize }: MetricsProps) {
  return (
    <div>
      <p>
        Revenue:{" "}
        <FormattedNumber value={revenue} style="currency" currency="USD" />
      </p>
      <p>
        Growth: <FormattedNumber value={growthRate} style="percent" />
      </p>
      <p>
        Size:{" "}
        <FormattedNumber
          value={fileSize}
          style="unit"
          unit="megabyte"
          unitDisplay="short"
        />
      </p>
    </div>
  );
}

Die style-Prop steuert den Formatierungsmodus. Die Währungsformatierung erfordert einen currency-Code, die Prozentformatierung multipliziert automatisch mit 100, und die Einheitenformatierung erfordert einen unit-Identifier. Alle Stile respektieren die Konventionen der aktiven Locale.

3. Zahlen imperativ mit useIntl formatieren

Verwenden Sie den useIntl-Hook, um Zahlen in Kontexten zu formatieren, in denen Komponenten nicht geeignet sind, wie z. B. beim Generieren dynamischer Attribute oder beim Vorbereiten von Daten für Nicht-React-APIs.

import { useIntl } from "react-intl";

interface ChartTooltipProps {
  dataPoint: number;
}

export function ChartTooltip({ dataPoint }: ChartTooltipProps) {
  const intl = useIntl();
  const formattedValue = intl.formatNumber(dataPoint, {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  });

  return <div title={formattedValue}>{formattedValue}</div>;
}

Die formatNumber-Methode gibt sofort einen formatierten String zurück und eignet sich daher für Attribute, ARIA-Labels oder jeden Kontext, in dem Sie den formatierten Wert als String und nicht als React-Element benötigen.

4. Benutzerdefinierte Formatierungsoptionen anwenden

Steuern Sie Präzision, Gruppierung und Notation, indem Sie Intl.NumberFormatOptions an FormattedNumber oder formatNumber übergeben.

import { FormattedNumber } from "react-intl";

interface StatisticProps {
  value: number;
  compact?: boolean;
}

export function Statistic({ value, compact }: StatisticProps) {
  return (
    <div>
      <FormattedNumber
        value={value}
        notation={compact ? "compact" : "standard"}
        minimumFractionDigits={0}
        maximumFractionDigits={2}
      />
    </div>
  );
}

Optionen wie notation, minimumFractionDigits und maximumFractionDigits steuern, wie die Zahl angezeigt wird. Die kompakte Notation konvertiert große Zahlen in abgekürzte Formen wie "1,2 Mio." und respektiert dabei locale-spezifische Abkürzungen.