كيف يمكنك التحقق من اللغة والخيارات التي يستخدمها المنسق فعليًا؟

مقدمة

عندما تقوم بإنشاء منسق Intl في جافا سكريبت، فإن الخيارات التي تطلبها ليست دائمًا الخيارات التي تحصل عليها. يقوم المتصفح بإجراء تفاوض على اللغة، وملء القيم الافتراضية، وتطبيع إعداداتك لإنشاء التكوين النهائي. تتيح لك طريقة resolvedOptions() فحص ما يستخدمه المنسق بالضبط.

كل منسق في واجهة برمجة تطبيقات Intl يحتوي على طريقة resolvedOptions(). وهذا يشمل Intl.DateTimeFormat، وIntl.NumberFormat، وIntl.ListFormat، وIntl.PluralRules، وIntl.Collator، وغيرها. تُرجع الطريقة كائنًا يحتوي على جميع تفاصيل التكوين التي انتهى بها المنسق بعد معالجة المدخلات الخاصة بك.

هذه الطريقة مفيدة بشكل أساسي لتصحيح الأخطاء، وفهم سلوك المتصفح، واكتشاف الميزات المتاحة في البيئة الحالية.

بناء الجملة الأساسي

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

const formatter = new Intl.DateTimeFormat('en-US');
const options = formatter.resolvedOptions();

console.log(options);
// {
//   locale: 'en-US',
//   calendar: 'gregory',
//   numberingSystem: 'latn',
//   timeZone: 'America/Los_Angeles',
//   ...
// }

يتضمن الكائن المُرجع دائمًا على الأقل خصائص locale وcalendar وnumberingSystem لمنسقات التاريخ، أو locale وnumberingSystem لمنسقات الأرقام. تعتمد الخصائص الإضافية على الخيارات التي حددتها وما يدعمه نوع المنسق.

لماذا تختلف الخيارات المطلوبة عن الخيارات المُحلّة

هناك ثلاثة أسباب رئيسية لاختلاف الخيارات التي طلبتها عن الخيارات المُحلّة.

أولاً، يجد تفاوض اللغة أفضل لغة متاحة عندما لا يكون طلبك المحدد مدعومًا. إذا طلبت de-AT ولكن المتصفح يحتوي فقط على de، فستكون اللغة المُحلّة هي de.

const formatter = new Intl.DateTimeFormat('de-AT-u-ca-buddhist');
const options = formatter.resolvedOptions();

console.log(options.locale);
// من المحتمل أن يُخرج: 'de-AT' أو 'de'

console.log(options.calendar);
// من المحتمل أن يُخرج: 'gregory' (إذا لم يكن التقويم البوذي مدعومًا)

ثانيًا، يملأ المتصفح القيم الافتراضية لأي خيارات لم تحددها. هذه الإعدادات الافتراضية خاصة باللغة.

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

console.log(options.style);
// يُخرج: 'decimal'

console.log(options.minimumFractionDigits);
// يُخرج: 0

console.log(options.maximumFractionDigits);
// يُخرج: 3

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

التحقق من اللغة المحلية المستخدمة فعلياً

تخبرك خاصية locale في الخيارات المحلولة بالضبط أي لغة محلية يستخدمها المنسق. هذه هي نتيجة تفاوض اللغة المحلية.

const formatter = new Intl.DateTimeFormat(['zh-TW', 'zh-CN', 'en-US']);
const options = formatter.resolvedOptions();

console.log(options.locale);
// يُخرج أول لغة محلية مدعومة من القائمة

إذا طلبت لغة محلية تتضمن كلمات مفتاحية لامتداد يونيكود، فقد لا تتضمن اللغة المحلية المحلولة تلك الكلمات المفتاحية إذا لم تكن مدعومة أو تم تطبيقها كخيارات منفصلة.

const formatter = new Intl.NumberFormat('en-US-u-nu-arab');
const options = formatter.resolvedOptions();

console.log(options.locale);
// قد يُخرج: 'en-US'

console.log(options.numberingSystem);
// قد يُخرج: 'arab' أو 'latn' اعتماداً على الدعم

فحص خيارات تنسيق التاريخ والوقت

بالنسبة لـ Intl.DateTimeFormat، تتضمن الخيارات المحلولة تفاصيل حول مكونات التاريخ والوقت التي سيتم عرضها وكيفية عرضها.

const formatter = new Intl.DateTimeFormat('en-US', {
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  timeZone: 'America/New_York'
});

const options = formatter.resolvedOptions();

console.log(options.year);
// يُخرج: 'numeric'

console.log(options.month);
// يُخرج: 'long'

console.log(options.day);
// يُخرج: 'numeric'

console.log(options.timeZone);
// يُخرج: 'America/New_York'

console.log(options.calendar);
// يُخرج: 'gregory'

عند استخدام dateStyle أو timeStyle، لا يتم تضمين تلك الاختصارات في الخيارات المحلولة. يقوم المتصفح بتوسيعها إلى خيارات مكونات فردية بناءً على اللغة المحلية.

const formatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'full'
});

const options = formatter.resolvedOptions();

console.log(options.dateStyle);
// يُخرج: undefined

console.log(options.weekday);
// يُخرج: 'long'

console.log(options.year);
// يُخرج: 'numeric'

console.log(options.month);
// يُخرج: 'long'

console.log(options.day);
// يُخرج: 'numeric'

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

const formatter = new Intl.DateTimeFormat('ja-JP');
const options = formatter.resolvedOptions();

console.log(options);
// يُظهر خيارات مكونات التاريخ الافتراضية للغة اليابانية المحلية

فحص خيارات تنسيق الأرقام

بالنسبة لـ Intl.NumberFormat، تخبرك الخيارات المحددة عن النمط والدقة والتجميع وتفاصيل التنسيق الأخرى.

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

const options = formatter.resolvedOptions();

console.log(options.style);
// الناتج: 'currency'

console.log(options.currency);
// الناتج: 'USD'

console.log(options.currencyDisplay);
// الناتج: 'symbol'

console.log(options.minimumFractionDigits);
// الناتج: 2

console.log(options.maximumFractionDigits);
// الناتج: 2

يمكنك أن ترى أنه على الرغم من أنك حددت العملة فقط، فإن المتصفح قام بملء القيم الافتراضية لـ currencyDisplay وأرقام الكسور.

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

const formatter = new Intl.NumberFormat('en-US', {
  minimumSignificantDigits: 3,
  maximumSignificantDigits: 5
});

const options = formatter.resolvedOptions();

console.log(options.minimumSignificantDigits);
// الناتج: 3

console.log(options.maximumSignificantDigits);
// الناتج: 5

فحص أنواع المنسقات الأخرى

تعمل طريقة resolvedOptions() بنفس الطريقة على جميع منسقات Intl.

بالنسبة لـ Intl.ListFormat، فإنها تظهر لك النوع والنمط.

const formatter = new Intl.ListFormat('en-US', {
  style: 'long',
  type: 'conjunction'
});

const options = formatter.resolvedOptions();

console.log(options.locale);
// الناتج: 'en-US'

console.log(options.style);
// الناتج: 'long'

console.log(options.type);
// الناتج: 'conjunction'

بالنسبة لـ Intl.PluralRules، فإنها تظهر لك النوع والحد الأدنى/الأقصى للأرقام.

const formatter = new Intl.PluralRules('en-US', {
  type: 'ordinal'
});

const options = formatter.resolvedOptions();

console.log(options.locale);
// الناتج: 'en-US'

console.log(options.type);
// الناتج: 'ordinal'

console.log(options.minimumIntegerDigits);
// الناتج: 1

حالات الاستخدام الشائعة لـ resolvedOptions()

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

const formatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'medium'
});

console.log(formatter.format(new Date()));
// تحقق من الناتج

console.log(formatter.resolvedOptions());
// انظر بالضبط أي الخيارات أنتجت هذا الناتج

حالة استخدام أخرى هي اكتشاف الميزات. يمكنك التحقق مما إذا كان تقويم معين أو نظام ترقيم أو ميزة أخرى مدعومة عن طريق طلبها ومعرفة ما تم تحديده بالفعل.

const formatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'islamic'
});

const options = formatter.resolvedOptions();

if (options.calendar === 'islamic') {
  console.log('التقويم الإسلامي مدعوم');
} else {
  console.log('التقويم الإسلامي غير مدعوم، يتم استخدام ' + options.calendar);
}

يمكنك أيضًا استخدام resolvedOptions() للحصول على تفضيلات اللغة للمستخدم. عند إنشاء منسق بدون وسيط لغة، يستخدم المتصفح تفضيلات المستخدم.

const formatter = new Intl.DateTimeFormat();
const options = formatter.resolvedOptions();

console.log(options.locale);
// الناتج: اللغة المفضلة للمستخدم

console.log(options.timeZone);
// الناتج: المنطقة الزمنية للمستخدم

console.log(options.hourCycle);
// الناتج: تفضيل دورة الساعة للمستخدم (12 أو 24 ساعة)

أخيرًا، يمكنك استخدام الخيارات المحددة لإعادة إنشاء منسق مطابق. يمكن تمرير الكائن المُرجع مرة أخرى إلى المُنشئ.

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

const options = formatter1.resolvedOptions();

const formatter2 = new Intl.NumberFormat(options.locale, options);

// سيقوم formatter2 بتنسيق الأرقام بشكل مطابق لـ formatter1

النقاط الرئيسية

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

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

استخدم resolvedOptions() بشكل أساسي لتصحيح سلوك المنسق، واكتشاف الميزات المتاحة، وفهم كيفية تفسير المتصفح لخياراتك. يمكن أيضًا استخدام الكائن المُرجع لإعادة إنشاء منسق مطابق أو فحص تفضيلات المستخدم.