كيفية تنسيق المبالغ النقدية في TanStack Start v1

المشكلة

تجمع الأسعار بين تحديين في التوطين: تمثيل العملة وتنسيق الأرقام. تظهر نفس القيمة النقدية كـ $1,200.50 في الولايات المتحدة و 1 200,50 € في ألمانيا. ينتقل رمز العملة، وتتبادل الفواصل العشرية وفواصل التجميع، وحتى المسافات تتغير.

هذه الاتفاقيات ليست تفضيلات بل توقعات. عرض الأسعار بتنسيق غير مألوف يجعل المستخدمين يتساءلون عما إذا كانوا يرون المبلغ الصحيح. السعر المعروض كـ "1200.50 EUR" لمستخدم ألماني أو "1.200,50$" لمستخدم أمريكي يخلق احتكاكاً ويقوض الثقة.

الحل

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

استخدم طريقة formatNumber من react-intl مع خيار style: 'currency' لتطبيق كل من رمز العملة واتفاقيات التنسيق الخاصة بلغة المستخدم. تتعامل واجهة برمجة التطبيقات Intl.NumberFormat في المتصفح مع موضع الرمز واختيار الفاصل والمسافات تلقائياً.

الخطوات

1. إنشاء مكون لتنسيق العملة

قم ببناء مكون قابل لإعادة الاستخدام يقبل قيمة رقمية ورمز عملة، ثم ينسق السعر باستخدام لغة المستخدم.

import { useIntl } from "react-intl";

interface PriceProps {
  value: number;
  currency: string;
}

export function Price({ value, currency }: PriceProps) {
  const intl = useIntl();

  const formattedPrice = intl.formatNumber(value, {
    style: "currency",
    currency: currency,
  });

  return <span>{formattedPrice}</span>;
}

يوفر الخطاف useIntl الوصول إلى واجهة برمجة تطبيقات التنسيق. تطبق طريقة formatNumber مع style: 'currency' كلاً من رمز العملة وتنسيق الأرقام الخاص باللغة.

2. استخدام المكون مع عملات مختلفة

اعرض الأسعار في جميع أنحاء تطبيقك عن طريق تمرير المبلغ الرقمي ورمز العملة.

export default function ProductCard() {
  return (
    <div>
      <h2>Premium Plan</h2>
      <Price value={1200.5} currency="USD" />
    </div>
  );
}

يقوم المكون بتنسيق السعر تلقائيًا وفقًا للإعدادات المحلية للمستخدم. يرى المستخدم الأمريكي "$1,200.50" بينما يرى المستخدم الألماني "1.200,50 $".

3. تنسيق الأسعار بدقة عشرية مخصصة

تحكم في عدد المنازل العشرية المعروضة عن طريق إضافة خيارات minimumFractionDigits و maximumFractionDigits.

export function PriceWithPrecision({ value, currency }: PriceProps) {
  const intl = useIntl();

  const formattedPrice = intl.formatNumber(value, {
    style: "currency",
    currency: currency,
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  });

  return <span>{formattedPrice}</span>;
}

يضمن هذا عرضًا متسقًا للمنازل العشرية عبر جميع الأسعار، حتى عندما تكون القيمة عددًا صحيحًا مثل 100.

4. إنشاء دالة مساعدة للتنسيق المضمن

في الحالات التي لا تكون فيها حاجة لمكون غلاف، قم بإنشاء دالة مساعدة للتنسيق.

import { useIntl } from "react-intl";

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

  return (value: number, currency: string) => {
    return intl.formatNumber(value, {
      style: "currency",
      currency: currency,
    });
  };
}

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

export function CheckoutSummary({ total }: { total: number }) {
  const formatCurrency = useFormatCurrency();

  return (
    <button aria-label={`Pay ${formatCurrency(total, "USD")}`}>Checkout</button>
  );
}

تُرجع الدالة المساعدة نصًا عاديًا مناسبًا لأي سياق لا يمكن فيه استخدام مكونات JSX.