كيفية تنسيق الأرقام للغات المختلفة في TanStack Start v1

المشكلة

تُكتب الأرقام بشكل مختلف حول العالم. ما يظهر كـ 10,000.5 في الولايات المتحدة يصبح 10.000,5 في ألمانيا—حيث تتبادل الفواصل والنقاط الأدوار بالكامل. هذا ليس مسألة تفضيل أو أسلوب، بل مسألة وضوح. قد يقرأ المستخدم الألماني الذي يرى 10,000.5 الرقم على أنه عشرة، متجاهلاً فواصل التجميع. قد يقرأ المستخدم الأمريكي الذي يرى 10.000,5 الرقم على أنه عشرة آلاف، متجاهلاً الفاصل العشري. نفس الأرقام، معانٍ متعاكسة.

عندما تعرض التطبيقات الأرقام دون مراعاة اتفاقيات التنسيق الإقليمية، فإنها تخلق ارتباكاً وتقوض الثقة. يتوقع المستخدمون أن تتبع الأرقام الأنماط التي تعلموها، والانحرافات عن تلك الأنماط تجبرهم على التوقف وإعادة التفسير والتساؤل عما إذا كانت البيانات صحيحة.

الحل

تنسيق الأرقام بناءً على لغة المستخدم، باستخدام القواعد الإقليمية للفواصل العشرية وفواصل التجميع. هذا يحول القيم الرقمية إلى سلاسل نصية تتبع قواعد التنسيق المألوفة للمستخدمين في منطقتهم.

توفر react-intl مكونات وخطافات تستفيد من واجهة برمجة التطبيقات Intl.NumberFormat المدمجة في المتصفح لتطبيق التنسيق الخاص باللغة. من خلال تمرير قيمة رقمية واللغة الحالية، تختار هذه الأدوات تلقائياً الفواصل الصحيحة وتجميع الأرقام والاتفاقيات الإقليمية الأخرى. النتيجة هي سلسلة نصية منسقة تطابق توقعات المستخدم دون معالجة يدوية للسلاسل النصية أو منطق خاص باللغة في مكوناتك.

الخطوات

1. إنشاء مكون لعرض الأرقام باستخدام FormattedNumber

قم ببناء مكون يقبل قيمة رقمية ويعرضها بتنسيق مناسب للغة باستخدام مكون FormattedNumber من react-intl.

import { FormattedNumber } from "react-intl";

interface PriceDisplayProps {
  value: number;
}

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

يطبق مكون FormattedNumber تلقائيًا فواصل الأعداد العشرية والتجميع الخاصة بالمنطقة. يقرأ المنطقة من أقرب IntlProvider في شجرة المكونات ويقوم بتنسيق الرقم وفقًا لذلك.

2. تنسيق الأرقام بأنماط محددة

خصص تنسيق الأرقام عن طريق تمرير خيارات النمط إلى FormattedNumber للعملات أو النسب المئوية أو الوحدات.

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>
  );
}

تتحكم الخاصية style في وضع التنسيق. يتطلب تنسيق العملة رمز currency، ويقوم تنسيق النسبة المئوية تلقائيًا بالضرب في 100، ويتطلب تنسيق الوحدة معرف unit. تحترم جميع الأنماط اصطلاحات المنطقة النشطة.

3. تنسيق الأرقام بشكل إجرائي باستخدام useIntl

استخدم خطاف useIntl لتنسيق الأرقام في السياقات التي لا تكون فيها المكونات مناسبة، مثل إنشاء سمات ديناميكية أو إعداد البيانات لواجهات برمجة التطبيقات غير الخاصة بـ React.

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>;
}

تُرجع طريقة formatNumber سلسلة نصية منسقة فورًا، مما يجعلها مناسبة للسمات أو تسميات aria أو أي سياق تحتاج فيه إلى القيمة المنسقة كسلسلة نصية بدلاً من عنصر React.

4. تطبيق خيارات تنسيق مخصصة

تحكم في الدقة والتجميع والترميز عن طريق تمرير Intl.NumberFormatOptions إلى FormattedNumber أو formatNumber.

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>
  );
}

تتحكم خيارات مثل notation وminimumFractionDigits وmaximumFractionDigits في كيفية عرض الرقم. يحول الترميز المضغوط الأرقام الكبيرة إلى أشكال مختصرة مثل "1.2M" مع احترام الاختصارات الخاصة بالمنطقة.