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

استخدم الدالة resolvedOptions()‎ لفحص التكوين الفعلي لأي منسق Intl

مقدمة

عند إنشاء منسق Intl في JavaScript، فإن الخيارات التي تطلبها ليست دائماً الخيارات التي تحصل عليها. يقوم المتصفح بإجراء التفاوض على اللغة، وملء القيم الافتراضية، وتطبيع إعداداتك لإنشاء التكوين النهائي. تتيح لك الدالة 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);
// Likely outputs: 'de-AT' or 'de'

console.log(options.calendar);
// Likely outputs: 'gregory' (if Buddhist calendar is not supported)

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

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

console.log(options.style);
// Outputs: 'decimal'

console.log(options.minimumFractionDigits);
// Outputs: 0

console.log(options.maximumFractionDigits);
// Outputs: 3

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

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

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

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

console.log(options.locale);
// Outputs the first supported locale from the list

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

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

console.log(options.locale);
// Might output: 'en-US'

console.log(options.numberingSystem);
// Might output: 'arab' or 'latn' depending on support

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

بالنسبة لـ 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);
// Outputs: 'numeric'

console.log(options.month);
// Outputs: 'long'

console.log(options.day);
// Outputs: 'numeric'

console.log(options.timeZone);
// Outputs: 'America/New_York'

console.log(options.calendar);
// Outputs: 'gregory'

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

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

const options = formatter.resolvedOptions();

console.log(options.dateStyle);
// Outputs: undefined

console.log(options.weekday);
// Outputs: 'long'

console.log(options.year);
// Outputs: 'numeric'

console.log(options.month);
// Outputs: 'long'

console.log(options.day);
// Outputs: 'numeric'

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

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

console.log(options);
// Shows default date component options for Japanese locale

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

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

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

const options = formatter.resolvedOptions();

console.log(options.style);
// Outputs: 'currency'

console.log(options.currency);
// Outputs: 'USD'

console.log(options.currencyDisplay);
// Outputs: 'symbol'

console.log(options.minimumFractionDigits);
// Outputs: 2

console.log(options.maximumFractionDigits);
// Outputs: 2

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

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

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

const options = formatter.resolvedOptions();

console.log(options.minimumSignificantDigits);
// Outputs: 3

console.log(options.maximumSignificantDigits);
// Outputs: 5

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

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

بالنسبة لـ Intl.ListFormat، تُظهر لك النوع والأسلوب.

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

const options = formatter.resolvedOptions();

console.log(options.locale);
// Outputs: 'en-US'

console.log(options.style);
// Outputs: 'long'

console.log(options.type);
// Outputs: 'conjunction'

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

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

const options = formatter.resolvedOptions();

console.log(options.locale);
// Outputs: 'en-US'

console.log(options.type);
// Outputs: 'ordinal'

console.log(options.minimumIntegerDigits);
// Outputs: 1

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

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

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

console.log(formatter.format(new Date()));
// Check the output

console.log(formatter.resolvedOptions());
// See exactly which options produced that output

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

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

const options = formatter.resolvedOptions();

if (options.calendar === 'islamic') {
  console.log('Islamic calendar is supported');
} else {
  console.log('Islamic calendar is not supported, using ' + options.calendar);
}

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

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

console.log(options.locale);
// Outputs: the user's preferred locale

console.log(options.timeZone);
// Outputs: the user's time zone

console.log(options.hourCycle);
// Outputs: the user's hour cycle preference (12 or 24 hour)

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

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

const options = formatter1.resolvedOptions();

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

// formatter2 will format numbers identically to formatter1

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

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

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

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