واجهة برمجة التطبيقات Intl.NumberFormat

مقدمة

لنفترض عرض الرقم 1234567.89 في تطبيقك. استخدام toString() ينتج "1234567.89"، وهو صعب القراءة ويفترض أن الجميع يستخدمون النقاط للفواصل العشرية ويقرؤون الأرقام من اليسار إلى اليمين. يتوقع الأمريكيون "1,234,567.89"، بينما يتوقع الألمان "1.234.567,89"، ويتوقع المستخدمون في الهند "12,34,567.89" مع قواعد تجميع مختلفة.

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

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

تنسيق رقم بالإعدادات الافتراضية

أنشئ أداة تنسيق من خلال استدعاء new Intl.NumberFormat() مع سلسلة نصية للغة المحلية، ثم استدع طريقة format() الخاصة بها مع رقم.

const formatter = new Intl.NumberFormat('en-US');
formatter.format(1234567.89);
// "1,234,567.89"

تضيف أداة التنسيق فواصل الآلاف وتنسق الفاصلة العشرية وفقاً للغة المحلية. بدون تحديد لغة محلية، تستخدم أداة التنسيق اللغة المحلية الافتراضية لبيئة التشغيل، والتي تعتمد عادةً على إعدادات نظام المستخدم.

const formatter = new Intl.NumberFormat('de-DE');
formatter.format(1234567.89);
// "1.234.567,89"

تستخدم الاتفاقيات الألمانية النقاط لفواصل الآلاف والفواصل للفواصل العشرية، وهو عكس الاتفاقيات الأمريكية. تتعامل أداة التنسيق مع هذه الاختلافات تلقائياً.

فهم رموز اللغات المحلية

يحدد رمز اللغة المحلية لغة ومنطقة اختيارية، ويُكتب على شكل language-REGION. تستخدم اللغة رمز ISO 639-1 المكون من حرفين مثل en أو es. تستخدم المنطقة رمز ISO 3166-1 المكون من حرفين مثل US أو MX.

new Intl.NumberFormat('en-US').format(1234.56);
// "1,234.56" (American English)

new Intl.NumberFormat('en-GB').format(1234.56);
// "1,234.56" (British English)

new Intl.NumberFormat('es-ES').format(1234.56);
// "1234,56" (European Spanish)

new Intl.NumberFormat('es-MX').format(1234.56);
// "1,234.56" (Mexican Spanish)

تستخدم كلتا النسختين الإنجليزيتين نفس التنسيق، لكن النسخ الإسبانية تختلف. تحذف الإسبانية الأوروبية فواصل الآلاف للأرقام المكونة من أربعة أرقام وتستخدم الفواصل للكسور العشرية، بينما تتبع الإسبانية المكسيكية الاصطلاحات الأمريكية.

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

اختر نمط التنسيق

يحدد خيار style فئة التنسيق. مرر كائن خيارات كوسيطة ثانية إلى المُنشئ.

new Intl.NumberFormat('en-US', {
  style: 'decimal'
}).format(1234.56);
// "1,234.56"

نمط decimal هو الافتراضي. الأنماط الأخرى هي currency وpercent وunit.

تنسيق العملة بالرموز والأكواد

يتطلب نمط currency خيار currency مع رمز عملة ISO 4217.

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
}).format(1234.56);
// "$1,234.56"

يضيف المنسق علامة الدولار وينسق إلى منزلتين عشريتين افتراضياً، وهو المعيار لمعظم العملات. تضع اللغات المحلية المختلفة الرمز في مواضع مختلفة.

new Intl.NumberFormat('de-DE', {
  style: 'currency',
  currency: 'EUR'
}).format(1234.56);
// "1.234,56 €"

يضع التنسيق الألماني رمز اليورو بعد المبلغ مع مسافة. يحدد خيار currency العملة التي سيتم عرضها، وليس الاصطلاحات المحلية التي يجب اتباعها. تحدد اللغة المحلية اصطلاحات التنسيق، بينما تحدد العملة الرمز.

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'EUR'
}).format(1234.56);
// "€1,234.56"

تنتج اصطلاحات التنسيق الأمريكية مع رمز اليورو علامة يورو قبل المبلغ، متبعة اصطلاحات الوضع الأمريكية بدلاً من الأوروبية.

التحكم في تنسيق عرض العملة

يغير خيار currencyDisplay كيفية ظهور العملة في السلسلة المنسقة.

const amount = 1234.56;

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'symbol'
}).format(amount);
// "$1,234.56"

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'code'
}).format(amount);
// "USD 1,234.56"

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'name'
}).format(amount);
// "1,234.56 US dollars"

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'narrowSymbol'
}).format(amount);
// "$1,234.56"

خيار symbol هو الافتراضي ويعرض رمز العملة مثل $ أو €. يعرض خيار code رمز العملة المكون من ثلاثة أحرف. يكتب خيار name اسم العملة بالكامل. يستخدم خيار narrowSymbol رمز العملة الضيق للغة المحلية، والذي قد يكون غامضاً لكنه يوفر المساحة.

يظهر الفرق بين symbol وnarrowSymbol بوضوح مع العملات التي تتشارك الرموز.

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'CAD',
  currencyDisplay: 'symbol'
}).format(100);
// "CA$100.00"

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'CAD',
  currencyDisplay: 'narrowSymbol'
}).format(100);
// "$100.00"

تظهر الدولارات الكندية كـ CA$ مع خيار symbol لتمييزها عن الدولارات الأمريكية، لكنها تظهر كـ $ فقط مع narrowSymbol.

تنسيق المبالغ النقدية السالبة باستخدام الترميز المحاسبي

يتحكم خيار currencySign في كيفية ظهور المبالغ السالبة.

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencySign: 'standard'
}).format(-1234.56);
// "-$1,234.56"

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  currencySign: 'accounting'
}).format(-1234.56);
// "($1,234.56)"

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

تنسيق النسب المئوية

يقوم نمط percent بضرب الرقم في 100 وإضافة علامة النسبة المئوية.

new Intl.NumberFormat('en-US', {
  style: 'percent'
}).format(0.1234);
// "12%"

new Intl.NumberFormat('en-US', {
  style: 'percent'
}).format(0.1256);
// "13%"

يقوم المنسق بالتقريب إلى أقرب عدد صحيح افتراضياً. تحكم في المنازل العشرية باستخدام خيارات الأرقام.

new Intl.NumberFormat('en-US', {
  style: 'percent',
  minimumFractionDigits: 2
}).format(0.1234);
// "12.34%"

مرر الشكل العشري للنسبة المئوية، وليس الشكل المضروب. يتولى المنسق عملية الضرب.

تنسيق القياسات بالوحدات

يتطلب نمط unit خيار unit مع معرف الوحدة.

new Intl.NumberFormat('en-US', {
  style: 'unit',
  unit: 'kilometer-per-hour'
}).format(100);
// "100 km/h"

new Intl.NumberFormat('en-GB', {
  style: 'unit',
  unit: 'mile-per-hour'
}).format(100);
// "100 mph"

تشمل الوحدات المتاحة قياسات الطول (meter، kilometer، mile)، والمدد الزمنية (second، minute، hour)، والتخزين الرقمي (byte، kilobyte، megabyte)، ودرجات الحرارة (celsius، fahrenheit)، والعديد من الوحدات الأخرى. تجمع الوحدات المركبة مثل kilometer-per-hour بين الوحدات البسيطة باستخدام الشرطات.

يتحكم خيار unitDisplay في تنسيق الوحدة.

const distance = 1234.5;

new Intl.NumberFormat('en-US', {
  style: 'unit',
  unit: 'kilometer',
  unitDisplay: 'long'
}).format(distance);
// "1,234.5 kilometers"

new Intl.NumberFormat('en-US', {
  style: 'unit',
  unit: 'kilometer',
  unitDisplay: 'short'
}).format(distance);
// "1,234.5 km"

new Intl.NumberFormat('en-US', {
  style: 'unit',
  unit: 'kilometer',
  unitDisplay: 'narrow'
}).format(distance);
// "1,234.5km"

يقوم خيار long بكتابة اسم الوحدة بالكامل. يستخدم خيار short الاختصارات. يستخدم خيار narrow الشكل الأكثر إيجازاً، والذي قد يكون غامضاً.

عرض الأرقام الكبيرة بالترميز المدمج

يغير خيار notation كيفية التعبير عن الأرقام. تستخدم قيمة compact أشكالاً مختصرة خاصة باللغة المحلية للأرقام الكبيرة.

new Intl.NumberFormat('en-US', {
  notation: 'compact'
}).format(1234567);
// "1.2M"

new Intl.NumberFormat('en-US', {
  notation: 'compact'
}).format(987654321);
// "988M"

يقوم الترميز المدمج بالتقريب إلى منزلة عشرية واحدة افتراضياً ويضيف لواحق مثل K للآلاف، وM للملايين، وB للمليارات. يظهر هذا التنسيق في عدد المتابعين على وسائل التواصل الاجتماعي، وعدد مشاهدات الفيديو، ولوحات التحليلات.

يتحكم خيار compactDisplay في طول اللاحقة.

new Intl.NumberFormat('en-US', {
  notation: 'compact',
  compactDisplay: 'short'
}).format(1234567);
// "1.2M"

new Intl.NumberFormat('en-US', {
  notation: 'compact',
  compactDisplay: 'long'
}).format(1234567);
// "1.2 million"

خيار short هو الافتراضي ويستخدم الرموز. يقوم خيار long بكتابة كلمة الحجم بالكامل. تستخدم اللغات المحلية المختلفة لواحق مختلفة.

new Intl.NumberFormat('zh-CN', {
  notation: 'compact'
}).format(123456789);
// "1.2亿"

تستخدم اللغة الصينية 亿 لمئات الملايين، مما يعكس نظام التجميع العددي للغة.

التعبير عن الأرقام الكبيرة جداً أو الصغيرة جداً بالترميز العلمي

يعبر ترميز scientific عن الأرقام كمعامل مضروب في قوة العشرة.

new Intl.NumberFormat('en-US', {
  notation: 'scientific'
}).format(123456789);
// "1.235E8"

new Intl.NumberFormat('en-US', {
  notation: 'scientific'
}).format(0.00000123);
// "1.23E-6"

يعمل هذا التنسيق بشكل جيد للأرقام الكبيرة جداً (المسافات الفلكية، عدد الجزيئات) والأرقام الصغيرة جداً (كتل الجسيمات، القياسات النانوية). يظهر الأس دائماً كمضاعف للواحد.

استخدام الترميز الهندسي للتطبيقات التقنية

يشبه ترميز engineering الترميز العلمي ولكنه يقيد الأسس بمضاعفات الثلاثة.

new Intl.NumberFormat('en-US', {
  notation: 'engineering'
}).format(123456789);
// "123.457E6"

new Intl.NumberFormat('en-US', {
  notation: 'engineering'
}).format(1234);
// "1.234E3"

يتماشى الترميز الهندسي مع بادئات وحدات النظام الدولي (كيلو، ميجا، جيجا)، مما يجعله معياراً في سياقات الهندسة والفيزياء. يتراوح المعامل من 1 إلى 999.

التحكم في الأرقام العشرية باستخدام أرقام الكسور

يتحكم الخياران minimumFractionDigits وmaximumFractionDigits في عدد الأرقام التي تظهر بعد الفاصلة العشرية.

new Intl.NumberFormat('en-US', {
  minimumFractionDigits: 2,
  maximumFractionDigits: 2
}).format(1234.5);
// "1,234.50"

new Intl.NumberFormat('en-US', {
  minimumFractionDigits: 2,
  maximumFractionDigits: 2
}).format(1234.567);
// "1,234.57"

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

new Intl.NumberFormat('en-US', {
  minimumFractionDigits: 0,
  maximumFractionDigits: 0
}).format(1234.567);
// "1,235"

يؤدي تعيين كليهما إلى صفر إلى التقريب لأقرب عدد صحيح.

التحكم في الدقة الإجمالية باستخدام الأرقام المعنوية

يتحكم الخياران minimumSignificantDigits وmaximumSignificantDigits في الدقة الإجمالية بغض النظر عن موضع الفاصلة العشرية.

new Intl.NumberFormat('en-US', {
  minimumSignificantDigits: 3,
  maximumSignificantDigits: 3
}).format(1234.567);
// "1,230"

new Intl.NumberFormat('en-US', {
  minimumSignificantDigits: 3,
  maximumSignificantDigits: 3
}).format(0.001234);
// "0.00123"

تحسب الأرقام المعنوية جميع الأرقام باستثناء الأصفار البادئة. يقرب المثال الأول إلى ثلاثة أرقام، منتجًا 1230. يحتفظ المثال الثاني بثلاثة أرقام بعد الأصفار البادئة، منتجًا 0.00123.

تتجاوز خيارات الأرقام المعنوية خيارات أرقام الكسور عند تحديد كليهما.

اختيار استراتيجية تقريب باستخدام أوضاع التقريب

يحدد الخيار roundingMode كيفية تقريب الأرقام عند الحاجة إلى الاقتطاع.

const value = 1.5;

new Intl.NumberFormat('en-US', {
  maximumFractionDigits: 0,
  roundingMode: 'halfExpand'
}).format(value);
// "2"

new Intl.NumberFormat('en-US', {
  maximumFractionDigits: 0,
  roundingMode: 'halfTrunc'
}).format(value);
// "1"

يعد الوضع halfExpand هو الافتراضي ويقرب 0.5 بعيدًا عن الصفر، وهي استراتيجية تقريب شائعة تُدرس في المدارس. يقرب الوضع halfTrunc الرقم 0.5 نحو الصفر.

تشمل الأوضاع الأخرى:

ceil: التقريب دائمًا نحو اللانهاية الموجبة
floor: التقريب دائمًا نحو اللانهاية السالبة
expand: التقريب دائمًا بعيدًا عن الصفر
trunc: التقريب دائمًا نحو الصفر
halfCeil: تقريب 0.5 نحو اللانهاية الموجبة
halfFloor: تقريب 0.5 نحو اللانهاية السالبة
halfEven: تقريب 0.5 نحو أقرب رقم زوجي

const prices = [1.5, 2.5, 3.5];

prices.map(price =>
  new Intl.NumberFormat('en-US', {
    maximumFractionDigits: 0,
    roundingMode: 'halfEven'
  }).format(price)
);
// ["2", "2", "4"]

يختار وضع halfEven، المعروف أيضاً بالتقريب المصرفي، أقرب رقم زوجي عند تقريب 0.5، مما يقلل من انحياز التقريب في العمليات الحسابية المتكررة. ينتج عن هذا 2 لكل من 1.5 و2.5، ولكن 4 لـ 3.5.

تستخدم التطبيقات المالية ceil لتقريب الرسوم للأعلى وfloor لتقريب المبالغ المستردة للأسفل. تستخدم التطبيقات الإحصائية halfEven لتقليل أخطاء التقريب التراكمية.

التحكم في فواصل الآلاف باستخدام خيارات التجميع

يتحكم خيار useGrouping في ظهور فواصل الآلاف.

new Intl.NumberFormat('en-US', {
  useGrouping: true
}).format(123456);
// "123,456"

new Intl.NumberFormat('en-US', {
  useGrouping: false
}).format(123456);
// "123456"

القيمة true هي الافتراضية. تزيل القيمة false جميع الفواصل. توفر القيم النصية تحكماً أدق.

new Intl.NumberFormat('en-US', {
  useGrouping: 'always'
}).format(1234);
// "1,234"

new Intl.NumberFormat('en-US', {
  useGrouping: 'min2'
}).format(1234);
// "1234"

تستخدم القيمة always الفواصل في جميع الحالات. تحذف القيمة min2 الفواصل للأرقام المكونة من أربعة أرقام. تتبع القيمة auto تفضيلات اللغة المحلية، والتي عادةً ما تطابق سلوك min2.

يستخدم الترميز المضغوط min2 افتراضياً لأن الأرقام المضغوطة نادراً ما تحتاج إلى فواصل داخلية.

إظهار العلامات بشكل صريح باستخدام خيارات عرض العلامة

يتحكم خيار signDisplay في موعد ظهور علامات الموجب والسالب.

new Intl.NumberFormat('en-US', {
  signDisplay: 'auto'
}).format(100);
// "100"

new Intl.NumberFormat('en-US', {
  signDisplay: 'always'
}).format(100);
// "+100"

القيمة auto هي الافتراضية وتُظهر علامات السالب للأرقام السالبة ولكن ليس علامات الموجب للأرقام الموجبة. تُظهر القيمة always كلتيهما.

new Intl.NumberFormat('en-US', {
  signDisplay: 'exceptZero'
}).format(0);
// "0"

new Intl.NumberFormat('en-US', {
  signDisplay: 'always'
}).format(0);
// "+0"

تحذف القيمة exceptZero العلامات لقيم الصفر حتى مع سلوك always. يمنع هذا العروض المربكة لـ +0 و-0.

new Intl.NumberFormat('en-US', {
  signDisplay: 'never'
}).format(-100);
// "100"

تزيل القيمة never العلامات بالكامل، وتعرض القيمة المطلقة فقط.

تستخدم التطبيقات المالية always لإبراز المكاسب بعلامات الزائد. تستخدم شاشات عرض درجة الحرارة exceptZero لتجنب إظهار +0° أو -0°.

تقسيم المخرجات المنسقة إلى أجزاء

تُرجع الدالة formatToParts() مصفوفة من الكائنات تمثل كل مكون من مكونات السلسلة النصية المنسقة.

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
}).formatToParts(1234.56);

يُرجع هذا:

[
  { type: 'currency', value: '$' },
  { type: 'integer', value: '1' },
  { type: 'group', value: ',' },
  { type: 'integer', value: '234' },
  { type: 'decimal', value: '.' },
  { type: 'fraction', value: '56' }
]

يحتوي كل كائن على type يحدد المكون وvalue يحتوي على السلسلة النصية. يمكن أن يكون type هو currency أو integer أو group أو decimal أو fraction أو literal أو minusSign أو plusSign أو percentSign أو غيرها.

يتيح هذا تطبيق تنسيق مخصص على المكونات الفردية.

const parts = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
}).formatToParts(1234.56);

const formatted = parts.map(part => {
  if (part.type === 'currency') {
    return `<span class="currency">${part.value}</span>`;
  }
  if (part.type === 'integer') {
    return `<span class="integer">${part.value}</span>`;
  }
  return part.value;
}).join('');

// <span class="currency">$</span><span class="integer">1</span>,<span class="integer">234</span>.56

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

تنسيق نطاقات الأرقام

تقوم الدالة formatRange() بتنسيق رقمين كنطاق.

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
}).formatRange(100, 200);
// "$100.00 – $200.00"

يستخدم المنسق فاصل نطاق خاص باللغة المحلية (شرطة متوسطة في الإنجليزية) ويتضمن رموز العملات. إذا تم تنسيق القيم إلى نفس السلسلة النصية، يُرجع المنسق قيمة واحدة مع علامة التقريب.

new Intl.NumberFormat('en-US', {
  notation: 'compact'
}).formatRange(1200, 1800);
// "~1K"

يتم تنسيق كل من 1200 و1800 كـ 1K في الترميز المضغوط، لذلك يعرض المنسق تقريباً 1K.

تُرجع الدالة formatRangeToParts() أجزاء النطاق.

new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
}).formatRangeToParts(100, 200);

هذا يُرجع:

[
  { type: 'currency', value: '$', source: 'startRange' },
  { type: 'integer', value: '100', source: 'startRange' },
  { type: 'decimal', value: '.', source: 'startRange' },
  { type: 'fraction', value: '00', source: 'startRange' },
  { type: 'literal', value: ' – ', source: 'shared' },
  { type: 'currency', value: '$', source: 'endRange' },
  { type: 'integer', value: '200', source: 'endRange' },
  { type: 'decimal', value: '.', source: 'endRange' },
  { type: 'fraction', value: '00', source: 'endRange' }
]

تحدد الخاصية source ما إذا كان الجزء يأتي من قيمة البداية أو قيمة النهاية أو فاصل النطاق.

تستخدم نطاقات الأسعار ونطاقات التواريخ ونطاقات القياسات هذه الطريقة للتنسيق الصحيح الحساس للغة.

فحص الخيارات المحلولة

تُرجع الطريقة resolvedOptions() كائنًا يعرض الخيارات الفعلية المستخدمة بواسطة المنسق.

const formatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
});

formatter.resolvedOptions();

هذا يُرجع:

{
  locale: 'en-US',
  numberingSystem: 'latn',
  style: 'currency',
  currency: 'USD',
  currencyDisplay: 'symbol',
  currencySign: 'standard',
  minimumIntegerDigits: 1,
  minimumFractionDigits: 2,
  maximumFractionDigits: 2,
  useGrouping: 'auto',
  notation: 'standard',
  signDisplay: 'auto',
  roundingMode: 'halfExpand'
}

يتضمن الكائن الخيارات المحددة صراحةً والقيم الافتراضية. قد يختلف locale عن اللغة المطلوبة إذا قام النظام بالحل إلى لغة مختلفة ولكن متوافقة. يعرض numberingSystem أحرف الأرقام التي يستخدمها المنسق.

تساعد هذه الطريقة في تصحيح التنسيق غير المتوقع من خلال الكشف عن جميع الإعدادات النشطة.

إعادة استخدام المنسقات لأداء أفضل

يتضمن إنشاء نسخة NumberFormat تحميل بيانات اللغة ومعالجة الخيارات. أعد استخدام النسخ عند تنسيق قيم متعددة بنفس الإعدادات.

// Inefficient: creates new formatter for each value
prices.map(price =>
  new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD'
  }).format(price)
);

// Efficient: creates formatter once
const formatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
});

prices.map(price => formatter.format(price));

النهج الثاني أسرع بكثير عند تنسيق العديد من القيم. أنشئ المنسقات خارج الحلقات ودوال عرض المكونات.

تخزن محركات JavaScript الحديثة نسخ NumberFormat داخليًا مؤقتًا، لكن إعادة الاستخدام الصريحة توفر أداءً أفضل وكودًا أوضح.

التحقق من دعم المتصفح

واجهة برمجة التطبيقات Intl.NumberFormat مدعومة في جميع المتصفحات الحديثة. دعمت Chrome وFirefox وSafari وEdge واجهة برمجة التطبيقات الأساسية منذ عام 2016. حصلت الميزات المتقدمة مثل formatRange() وformatRangeToParts() وخيارات roundingMode الموسعة على الدعم مؤخرًا ولكنها متاحة الآن في إصدارات المتصفحات الحالية.

تحقق من الدعم باستخدام:

if (typeof Intl !== 'undefined' && Intl.NumberFormat) {
  // NumberFormat is supported
  const formatter = new Intl.NumberFormat('en-US');
}

تحقق من ميزات محددة:

const formatter = new Intl.NumberFormat('en-US');

if (typeof formatter.formatRange === 'function') {
  // formatRange is supported
}

يمكن للتطبيقات التي تتطلب دعم المتصفحات القديمة استخدام polyfills مثل @formatjs/intl-numberformat، لكن معظم التطبيقات الحديثة يمكنها استخدام الـ API الأصلي دون الحاجة إلى بدائل احتياطية.

متى تستخدم NumberFormat

استخدم Intl.NumberFormat لـ:

عرض الأرقام للمستخدمين في أي سياق واجهة مستخدم
تنسيق مبالغ العملات في تطبيقات التجارة الإلكترونية
عرض النسب المئوية في لوحات التحليلات
عرض أعداد المتابعين وأعداد المشاهدات والمقاييس الاجتماعية الأخرى
تنسيق القياسات والقيم العلمية
بناء تطبيقات دولية تدعم لغات متعددة

لا تستخدم Intl.NumberFormat لـ:

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

NumberFormat هي أداة لطبقة العرض. احتفظ بالقيم الرقمية الأولية في العمليات الحسابية والتخزين، وطبق التنسيق فقط عند عرض القيم للمستخدمين.