إضافة العولمة في كوردوفا
تمكّن إضافة العولمة (cordova-plugin-globalization) من الحصول على معلومات حول الإعدادات المحلية واللغوية والزمنية للمستخدم.
لاحظ الفرق بين الإعدادات المحلية (locale) وبين اللغة: الإعدادات المحلية تتحكم في كيفية عرض الأرقام والتواريخ والأوقات في منطقة معيّنةٍ، بينما تحدد "اللغة" لغةَ النصوص، بصرف النظر عن الإعدادات المحلية. يستخدم المطورون في كثير من الأحيان الإعدادات المحلية لضبط كلا الإعدادين، ولكن لا يوجد سبب يمنع المستخدم من تعيين اللغة إلى "العربية"، مع تعيين الإعدادات المحلية إلى "الفرنسية"، بحيث يتم عرض النص باللغة العربية، ولكن مع عرض التواريخ والأوقات وغيرها كما تُعرض في فرنسا. للأسف، لا تميز معظم منصات الجوّال حاليًا بين هذه الإعدادات.
تعرّف هذه الإضافة كائنًا عامًّا navigator.globalization
. وعلى الرغم من أنّ هذا الكائن موجود في النطاق العام (global scope)، إلا أنه لن يكون متوفرًا إلا بعد إطلاق الحدث deviceready
.
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
console.log(navigator.globalization);
}
ملاحظة متعلقة بالإهمال
مع دعم واجهة العولمة البرمجية من ECMA على أجهزة iOS و أندرويد وويندوز، لم تعد هذه الإضافة ضروريةً بعد الآن. الانتقال من هذه الإضافة إلى تلك الواجهة البرمجية مُوضح في هذا المقال.
التثبيت
يمكن تثبيت هذه الأضافة عبر الأمر:
cordova plugin add cordova-plugin-globalization
الكائنات
GlobalizationError
التوابع
navigator.globalization.getPreferredLanguage
navigator.globalization.getLocaleName
navigator.globalization.dateToString
navigator.globalization.stringToDate
navigator.globalization.getDatePattern
navigator.globalization.getDateNames
navigator.globalization.isDayLightSavingsTime
navigator.globalization.getFirstDayOfWeek
navigator.globalization.numberToString
navigator.globalization.stringToNumber
navigator.globalization.getNumberPattern
navigator.globalization.getCurrencyPattern
يعيد هذا التابع وسم لغة المستخدم الحالية وفق المعيار BCP 47.
navigator.globalization.getPreferredLanguage(successCallback, errorCallback);
الوصف
يُعيد هذا التابع وسم معرف اللغة وفق المعيار BCP-47، ويمرره إلى الدالة successCallback
مع إعطائها الكائن properties
كمعاملٍ. يجب أن يملك هذا الكائن الخاصية value
ذات قيمة نصية (String
).
إن حدث خطأ أثناء محاولة الحصول على اللغة، فستُنفّذ الدالة errorCallback
مع تمرير الكائن GlobalizationError
إليها كمعاملٍ. رمز الخطأ المتوقع هو GlobalizationError.UNKNOWN_ERROR
.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- Browser
- فايرفكس
- iOS
- Windows Phone 8
- ويندوز
مثال
عند ضبط لغة المتصفح إلى القيمة en-US
، فستعرضُ الشيفرةُ البرمجية التالية مربع حوارٍ منبثقٍ يحتوي النص language: en-US
:
navigator.globalization.getPreferredLanguage(
function (language) {alert('language: ' + language.value + '\n');},
function () {alert('Error getting language\n');}
);
ملاحظات خاصة بمنصة أندرويد
- في منصة أندرويد، يُعاد رمز اللغة، وهوم رمزٌ مكون من حرفين يمثلان اللغة وفق المعيار ISO 639-1، ورمزٌ يمثل البلد وفق المعيار ISO 3166-1 مفصولان بشرطةٍ مثل: "
en
" و "en-US
" و "US
"
ملاحظات خاصة بمنصة Windows Phone 8
- في هذه المنصة، يُعاد رمز اللغة، وهو رمزٌ مكون من حرفين يمثلان اللغة وفق المعيار ISO 639-1، ورمز الدولة وفق المعيار ISO 3166-1 الذي يمثل المتغيرات المحلية المقابلة للإعدادات اللغوية، مفصولان بشرطة.
- لاحظ أنّ المتغير الإقليمي (regional variant) هو أحد خصائص إعداد "اللغة"، ولا يتم تحديده من قبل الإعداد المنفصل "البلد/المنطقة" (Country/Region) في منصة Windows Phone.
ملاحظات خاصة بمنصة ويندوز
- في هذه المنصة، يُعاد رمز اللغة، وهو رمزٌ مكون من حرفين يمثلان اللغة وفق المعيار ISO 639-1، ورمز الدولة وفق معيار ISO 3166-1 الذي يمثل المتغيرات المحلية المقابلة للإعدادات اللغوية، مفصولان بشرطة.
ملاحظات خاصة بالمتصفحات (Browsers)
- في المتصفحات، يتم الحصول على النتيجة من التابع
getLocaleName
.
يعيد هذا التابع الوسم الذي يمثل الإعدادات المحلية الحالية للعميل وفق المعيار BCP 47.
navigator.globalization.getLocaleName(successCallback, errorCallback);
الوصف
يعيد هذا التابع سلسلة نصية تمثل مُعرّف الإعدادات المحلية (locale identifier) وفق المعيار BCP 47، ثم يمررها إلى الدالة successCallback
مع إعطائها الكائن properties
كمعامل. يجب أن يكون لهذا الكائن خاصية value
ذات قيمة نصية (String
). الوسم المحلي يتكون من رمزٍ مكونٍ من حرفين صغيرين يمثلان اللغة، ورمز مكونٌ من حرفين كبيرين يمثلان البلد، ورمز متغير (variant code) (غير محدد)، مفصولان بشرطة.
إن حدث هناك خطأ أثناء محاولة الحصول على الإعدادات المحلية، فستُنفّذ الدالة errorCallback
مع إعطائها الكائن GlobalizationError
كمعامل. رمز الخطأ المتوقع هو GlobalizationError.UNKNOWN_ERROR
.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- فايرفوكس
- iOS
- Windows Phone 8
- ويندوز
- Browser
مثال
عند ضبط المتصفح عند اللغة en-US
، سيُعرض مربع حوار منبثق يحتوي النص locale: en-US
.
navigator.globalization.getLocaleName(
function (locale) {alert('locale: ' + locale.value + '\n');},
function () {alert('Error getting locale\n');}
);
ملاحظات خاصة بمنصة أندرويد
- لا تميز لغة Java بين الإعدادين "
langauge
" و "locale
"، لذلك فإنّ هذا التابع مكافئٌ للتابعnavigator.globalization.getPreferredLanguage()
.
ملاحظات خاصة بمنصة Windows Phone 8
- في هذه المنصة، يُعاد رمز اللغة وفق المعيار ISO 639-1، والمكون من حرفين، إضافة إلى رمز الدولة وفق المعيار ISO 3166-1، والموافق للمتغير الإقليمي (Regional variant) المقابل لإعداد "التنسيق الإقليمي" (Regional Format)، مفصولان بشرطةٍ.
ملاحظات خاصة بمنصة ويندوز
- يمكن تغيير إعدادات اللغة من الموضعين
Control Panel -> Clock و Language and Region -> Region -> Formats -> Format
وSettings -> Region -> Regional Format
على منصة Windows Phone 8.1.
ملاحظات خاصة بالمتصفحات (Browsers)
- يعيد المتصفح IE الإعدادات المحلية لنظام التشغيل. فيما يعيد متصفحا Chrome و Firefox وسم اللغة في المتصفح.
يعيد هذا التابع تاريخًا (date) على شكل سلسلة نصيةٍ مُنسّقةٍ وفقًا للإعدادات المحلية للعميل ومنطقته الزمنية.
navigator.globalization.dateToString(date, successCallback, errorCallback, options);
الوصف
يعيد هذا التابع سلسلة نصية تحتوي التاريخ المنسق عبر خاصيةٍ value
يمكن الوصول إليها من الكائن الذي مُرِّر كمُعامل إلى الدالة successCallback
.
يجب أن يكون المُعامل المنفصل (inbound parameter) date
من النوع Date
.
إن حدث خطأ أثناء محاولة تنسيق التاريخ، فستُنفّذ الدالة errorCallback
مع إعطائها الكائن GlobalizationError
كمُعامل. رمز الخطأ المتوقع هو GlobalizationError.FORMATTING_ERROR
.
المُعامل options
اختياري، وقيمه الافتراضية هي:
{formatLength:'short', selector:'date and time'}
يمكن أن تساوي قيمة الخيار options.formatLength
إمَّا short
أو medium
أو long
أو full
.
ويمكن أن تساوي قيمةُ الخيار options.selector
إما date
أو time
أو date and time
.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- فايرفوكس
- iOS
- Windows Phone 8
- ويندوز
- Browser
مثال
إن ضُبط المتصفّح إلى الإعداد المحلي en_US
، فسيُعرض مربع حوارٍ منبثقٍ يحتوي نصًّا مشابهًا للنص date: 9/25/2012 4:21PM
باستخدام الخيارات الافتراضية:
navigator.globalization.dateToString(
new Date(),
function (date) { alert('date: ' + date.value + '\n'); },
function () { alert('Error getting dateString\n'); },
{ formatLength: 'short', selector: 'date and time' }
);
ملاحظات خاصة بمنصة أندرويد
- الخيارات
formatLength
هي مجموعة فرعية من مجموعة اليونيكود UTS #35. يعتمد الخيار الافتراضيshort
على تنسيق التاريخ الذي حدده المستخدمُ من الموضعSettings -> System -> Date & time -> Choose date format
، والذي يعرض قيمة السنةyear
على شكل أربعة أرقام فقط، وليس رقمين. وهذا يعني أنه غير متوافقٍ بشكلٍ كاملٍ مع المعيار ICU.
ملاحظات خاصة بمنصة Windows Phone 8
- لا يدعم الخيار
formatLength
إلا القيمتينshort
وfull
. - عندما تساوي الخاصية
pattern
القيمةdate and time
، فستعيد دائمًا تنسيقًا كاملًا للتاريخ (full datetime format). - بناءً على لغة المستخدم، فقد لا تكون القيمة المُعادة متوافقةً مع المعيار ICU بشكلٍ كاملٍ.
ملاحظات خاصة بمنصة ويندوز
- لا يدعم الخيار
formatLength
إلا القيمتينshort
وfull
فقط. - عندما تساوي الخاصية
pattern
القيمةdate and time
، فستعيد دائمًا تنسيقًا كاملًا للتاريخ (full datetime format). - بناءً على لغة المستخدم، فقد لا تكون القيمة المُعادة متوافقةً مع المعيار ICU بشكلٍ كاملٍ.
ملاحظات خاصة بالمتصفحات (Browsers)
- لا يتم دعم إلا 79 إعدادًا محليًا فقط، نظرًا لاستخدام الملف
moment.js
في هذا التابع. - بناءً على لغة المستخدم، فقد لا تكون القيمة المُعادة متوافقةً مع المعيار ICU بشكلٍ كاملٍ.
- لا يدعم المُحدِّد
time
إلا القيمتينfull
وshort
في الخيارformatLength
.
ملاحظات خاصة بمنصة Firefox
- لا يُميّز الخيار
formatLength
بينlong
وfull
. - هناك طريقة واحدةً فقط لعرض التاريخ (لا يوجد نمطٌ طويل
long
وآخر كاملfull
).
يعيد هذا التابع سلسلةً نصيةً تمثل التنسيق الذي سيُستخدم لأجل تحليل (parse) وتنسيق قيم العملات وفقًا لتفضيلات المستخدم ورمز ISO 4217 الخاص بالعملة.
navigator.globalization.getCurrencyPattern(currencyCode, successCallback, errorCallback);
الوصف
يُعيد هذا التابع النمط (pattern) ويمرّره إلى الدالة successCallback
مع إعطائها الكائن properties
كمعامل. يجب أن يحتوي ذلك الكائن على الخاصيات التالية:
pattern
: سلسلة نصية تمثل هذه الخاصية نمط العملة الذي ستُنسّق العملات وتُحلّل قيمها بناءً عليه. الأنماط تتبع معيار يونيكود التقني #35.code
: سلسلة نصية تمثِّل رمز العملة الخاص بالنمط وفق المعيار ISO 4217.fraction
: عدد المنازل العشرية التي ستُستخدم عند تحليل البيانات وتنسيقها.rounding
: عدد يحدِّد التقريب الزائد (rounding increment) الذي سيُستخدم عند التحليل والتنسيق.decimal
: سلسلة نصية تمثِّل الرمز العشري الذي سيُستخدم في التحليل والتنسيق.grouping
: سلسلة نصية تمثِّل رمز التجميع (grouping symbol) الذي سيُستخدَم في التحليل والتنسيق.
يجب أن يكون المعامل المنفصل (inbound parameter) currencyCode
سلسلةً نصيةً (String
) تتضمّن أحد رموز العملة وفق المعيار ISO 4217، على سبيل المثال "USD
".
إن حدث خطأ أثناء محاولة الحصول على النمط، فستُنفّذ الدالة errorCallback
مع إعطائها الكائن GlobalizationError
كمعامل. رمز الخطأ المتوقع هو GlobalizationError.FORMATTING_ERROR
.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- iOS
- ويندوز
مثال
عند ضبط الإعدادات المحلية للمتصفح عند القيمة en_US
، وعند اختيار العملة الأمريكية (الدولار)، فسيعرض هذا المثال مربع حوار منبثق يحتوي نصًّا مشابهًا للنتائج التالية:
navigator.globalization.getCurrencyPattern(
'USD',
function (pattern) {
alert('pattern: ' + pattern.pattern + '\n' +
'code: ' + pattern.code + '\n' +
'fraction: ' + pattern.fraction + '\n' +
'rounding: ' + pattern.rounding + '\n' +
'decimal: ' + pattern.decimal + '\n' +
'grouping: ' + pattern.grouping);
},
function () { alert('Error getting pattern\n'); }
);
النتيجة المتوقعة:
pattern: $#,##0.##;($#,##0.##)
code: USD
fraction: 2
rounding: 0
decimal: .
grouping: ,
ملاحظات خاصة بمنصة ويندوز
- لا يدعم ويندوز إلا الخاصيتين "
code
" و "fraction
".
يُعيد هذا التابع مصفوفةً تتألف من أسماء الأشهر أو أيام الأسبوع، بناءً على تفضيلات المستخدم والتقويم الخاص به.
navigator.globalization.getDateNames(successCallback, errorCallback, options);
الوصف
يُعيد هذا التابع مصفوفةً من الأسماء ويمررها إلى الدالة successCallback
مع إعطائها الكائن properties
كمعامل. يحتوي هذا الكائن على خاصية value
تحتوي مصفوفةً من السلاسل النصية. تشتمل المصفوفة على أسماء تبدأ من الشهر الأول في السنة، أو اليوم الأول من الأسبوع، وفقًا للخيار المحدد.
إن حدث خطأ أثناء محاولة الحصول على الأسماء، فستُنفّذ الدالة errorCallback
مع إعطائها الكائن GlobalizationError
كمعامل. رمز الخطأ المتوقع هو GlobalizationError.UNKNOWN_ERROR
.
المُعامل options
اختياري، وقيمه الافتراضية هي:
{type:'wide', item:'months'}
يمكن أن تساوي قيمة الخيار options.type
إما narrow
وإما wide
.
يمكن أن تساوي قيمة الخيار options.item
إما months
وإما days
.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- فايرفوكس
- iOS
- Windows Phone 8
- ويندوز
- Browser
مثال
عند ضبط الإعدادات المحلية للمتصفح عند القيمة en_US
، فسيعرض هذا المثال سلسلة من 12 مربع حوارٍ منبثقٍ، واحدًا لكل شهر، مع نص مشابهٍ للسلسلة النصية "month: January
":
navigator.globalization.getDateNames(
function (names) {
for (var i = 0; i < names.value.length; i++) {
alert('month: ' + names.value[i] + '\n');
}
},
function () { alert('Error getting names\n'); },
{ type: 'wide', item: 'months' }
);
ملاحظات خاصة بمنصة Firefox
- تدعم الخاصية
options.type
القيمةgenitive
، وهو أمرٌ مهم لبعض اللغات.
ملاحظات خاصة بمنصة Windows Phone 8
- مصفوفة الشهور تحتوي على 13 عنصرًا.
- بناءً على الإعدادات المحلية للمستخدم، فقد لا تكون المصفوفة المُعادة متوافقةً مع المعيار ICU بشكلٍ كاملٍ.
ملاحظات خاصة بمنصة ويندوز
- مصفوفة الشهور تحتوي على 12 عنصرًا.
- بناءً على لغة المستخدم، فقد لا تكون المصفوفة المُعادة متوافقةً مع المعيار ICU بشكلٍ كاملٍ.
ملاحظات خاصة بالمتصفحات (Browsers)
- لا تتماشى أسماء التواريخ تمامًا مع المعيار ICU.
- مصفوفة الشهور تحتوي على 12 عنصرًا.
يُعيد هذا التابع سلسلةً نصيةً تمثل النمط (pattern) الذي ستُنسّق التواريخ وتُحلّل على أساسه، ووفقًا لتفضيلات المستخدم.
navigator.globalization.getDatePattern(successCallback, errorCallback, options);
الوصف
يُعيد هذا التابع نمطًا ويمرره إلى الدالة successCallback
. يحتوي الكائن الذي تم تمريره كمعامل على الخاصيات التالية:
pattern
: سلسلة نصية تمثِّل نمط التاريخ والوقت الذي ستُنسّق التواريخ وتُحلل وِفقَه. تتّبع هذه الأنماط معيار اليونيكود التقني 35#.timezone
: سلسلة نصية تمثِّل الاسم المختصر للمنطقة الزمنية للعميل.iana_timezone
: سلسلة نصية تمثِّل اسم IANA (هيئة تعيين أرقام الإنترنت) الخاص بالمنطقة الزمنية للعميل.utc_offset
: عدد يحدِّد الاختلاف الحالي بعدد الثواني بين المنطقة الزمنية للعميل، والوقت العالمي المنسق (coordinated universal time).dst_offset
: عدد يحدِّد فرق التوقيت الصيفي (daylight saving time) الحالي بالثواني بين المنطقة الزمنية غير الصيفية (non-daylight saving's time) والمنطقة الزمنية الصيفية (daylight saving's time) للعميل.
إن حدث خطأ أثناء محاولة الحصول على النمط، ستُنفذ الدالة errorCallback
مع إعطائها الكائن GlobalizationError
كمعامل. رمز الخطأ المتوقع هو GlobalizationError.PATTERN_ERROR
.
المعامل options
اختياري، وقيمه الافتراضية هي:
{formatLength:'short', selector:'date and time'}
يمكن أن تساوي قيمة الخيار options.formatLength
إمَّا short
أو medium
أو long
أو full
. كما يمكن أن تساوي قيمة الخيار الآخر options.selector
إمَّا date
أو time
أو date and time
.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- iOS
- Windows Phone 8
- ويندوز
- Browser
مثال
عند ضبط الإعدادات المحلية للمتصفح عند القيمة en_US
، فسيعرضُ هذا المثالُ مربعَ حوارٍ منبثقٍ يحتوي على نصٍّ وفق الصيغة pattern: M/d/yyyy h:mm a
:
function checkDatePattern() {
navigator.globalization.getDatePattern(
function (date) { alert('pattern: ' + date.pattern + '\n'); },
function () { alert('Error getting pattern\n'); },
{ formatLength: 'short', selector: 'date and time' }
);
}
ملاحظات خاصة بمنصة Windows Phone 8
- لا يدعم الخيار
formatLength
إلا القيمتينshort
وfull
. - عندما تساوي الخاصية
pattern
القيمةdate and time
، فستعيد دائمًا تنسيقًا كاملًا للتاريخ (full datetime format). - تعيد الخاصية
timezone
الاسم الكامل للمنطقة الزمنية. - الخاصية
dst_offset
غير مدعومة، وتعيد دائمًا القيمة صفر. - بناءً على الإعدادات المحلية للمستخدم، فقد لا يكون النمط متوافقًا تمامًا مع المعيار ICU.
ملاحظات خاصة بمنصة ويندوز
- لا تدعم الخاصيةُ
formatLength
إلا القيمتينshort
وfull
. - عندما تساوي الخاصية
pattern
القيمةdate and time
، فستعيد دائمًا تنسيقًا كاملًا للتاريخ (full datetime format). - تعيد الخاصية
timezone
الاسم الكامل للمنطقة الزمنية. - الخاصية
iana_timezone
غير مدعومة، وتُعيد دائمًا سلسلة نصية فارغة. - الخاصية
dst_offset
غير مدعومة، وتعيد دائمًا الصفر. - بناءً على الإعدادات المحلية للمستخدم، فقد لا يكون النمط متوافقًا تمامًا مع المعيار ICU.
ملاحظات خاصة بالمتصفحات (Browsers)
- الخاصية "
pattern
" غير مدعومة، وتعيد سلسلة نصية فارغة. - Chrome هو المتصفح الوحيد الذي يعيد الخاصية
timezone
. وفق الصيغة "منطقة من العالم/مدينة" ("{Part of the world/{City"). المتصفحات الأخرى تعيد سلسلةً نصيةً فارغةً.
يعيد هذا التابع أول يوم من الأسبوع وفقًا لتفضيلات المستخدم وتقويمه الزمني.
navigator.globalization.getFirstDayOfWeek(successCallback, errorCallback);
الوصف
يتم ترقيم أيام الأسبوع بدءًا من العدد 1
، الذي يُفترض أن يمثل يوم الأحد. يُعيد هذا التابع اليوم ويمرّره إلى الدالة successCallback
مع إعطائها الكائن properties
كمعامل. يجب أن يكون لهذا الكائن خاصية value
ذات قيمة عددية (Number
).
إن حدث خطأ أثناء محاولة الحصول على النمط، فستُنفّذ الدالة errorCallback
مع إعطائها الكائن GlobalizationError
كمعامل. رمز الخطأ المتوقع هو GlobalizationError.UNKNOWN_ERROR
.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- Firefox OS
- iOS
- Windows Phone 8
- ويندوز
- Browser
مثال
عند ضبط الإعدادات اللغوية للمتصفح عند القيمة en_US
، فستعرض هذه الشيفرة مربع حوار منبثق يحتوي نصًّا مشابهًا للسلسلة النصية day: 1
.
navigator.globalization.getFirstDayOfWeek(
function (day) {alert('day: ' + day.value + '\n');},
function () {alert('Error getting day\n');}
);
ملاحظات خاصة بمنصة ويندوز
- في منصتي ويندوز 8.0 و8.1، تعتمد القيمة المعادة على تفضيلات التقويم الزمني للمستخدم. أما في منصةWindows Phone 8.1، فتعتمد القيمة على الإعدادات المحلية الحالية.
ملاحظات خاصة بالمتصفحات (Browsers)
- لا يتم دعم إلا 79 إعدادًا محليًا فقط، نظرًا لاستخدام الملف
moment.js
في هذا التابع.
يُعيد هذا التابع سلسلة نصيةً تمثل النمط (pattern) الذي ستُنسّق الأعداد وتُحلّل على أساسه، ووفقًا لتفضيلات المستخدم.
navigator.globalization.getNumberPattern(successCallback, errorCallback, options);
الوصف
يُعيد هذا التابع النمط (pattern) ويمرّره إلى الدالة successCallback
مع إعطائها الكائن properties
كمعامل. يحتوي هذا الكائن على الخاصيات التالية:
pattern
: سلسلة نصية تمثِّل نمط تنسيق الأرقام وتحليلها. الأنماط تتبع معيار اليونيكود التقني 35#.symbol
: سلسلة نصية تمثِّل الرمز الذي سيتم استخدامه عند التنسيق والتحليل، مثل رمز النسبة المئوية أو العملة.fraction
: عدد المنازل العشرية التي ستُستخدم عند تحليل البيانات وتنسيقها.rounding
: عدد يحدِّد التقريب الزائد (rounding increment) الذي سيُستخدم عند التحليل والتنسيق.positive
: سلسلة نصية تمثِّل الرمز الذي سيُستخدم مع الأرقام الموجبة عند التحليل والتنسيق.negative
: سلسلة نصية تمثِّل الرمز الذي سيُستخدم مع الأعداد السالبة عند التحليل والتنسيق.decimal
: سلسلة نصية تمثِّل الرمز العشري الذي سيُستخدم في التحليل والتنسيق.grouping
: سلسلة نصية تمثِّل رمز التجميع (grouping symbol) الذي سيُستخدم في التحليل والتنسيق.
إن حدث خطأ أثناء محاولة الحصول على النمط، فستُنفّذ الدالة errorCallback
مع إعطائها الكائن GlobalizationError
كمعامل. رمز الخطأ المتوقع هو GlobalizationError.PATTERN_ERROR
.
المُعامل options
اختياري، وقيمته الافتراضية هي:
{type:'decimal'}
يمكن أن تساوي قيمة الخاصية options.type
إما decimal
أو percent
أو currency
.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- iOS
- Windows Phone 8
- ويندوز
- Browser
مثال
عند ضبط الإعدادات المحلية للمتصفح إلى القيمة en_US
، فستعرض هذه الشيفرة مربع حوار منبثق يحتوي نصًا مشابهًا للنتائج التالية:
navigator.globalization.getNumberPattern(
function (pattern) {alert('pattern: ' + pattern.pattern + '\n' +
'symbol: ' + pattern.symbol + '\n' +
'fraction: ' + pattern.fraction + '\n' +
'rounding: ' + pattern.rounding + '\n' +
'positive: ' + pattern.positive + '\n' +
'negative: ' + pattern.negative + '\n' +
'decimal: ' + pattern.decimal + '\n' +
'grouping: ' + pattern.grouping);},
function () {alert('Error getting pattern\n');},
{type:'decimal'}
);
ناتج تنفيذ هذا المثال هو:
pattern: #,##0.###
symbol: .
fraction: 0
rounding: 0
positive:
negative: -
decimal: .
grouping: ,
ملاحظات خاصة بمنصة Windows Phone 8
- الخاصية
pattern
غير مدعومة، وتعيد سلسلة نصيةً فارغة. - الخاصية
fraction
غير مدعومة، وتعيد الصفر.
ملاحظات خاصة بمنصة ويندوز
- الخاصية
pattern
غير مدعومة، وتعيد سلسلةً نصيةً فارغةً.
ملاحظات خاصة بالمتصفحات (Browsers)
- التابع
getNumberPattern
غير مدعوم إلا في متصفح Chrome؛ والخاصية الوحيدة المُعرّفة هيpattern
.
يتحقّق هذا التابع ممّا إذا كان التوقيت الصيفي (daylight savings time) ساري المفعول عند تاريخ معين، بحسب المنطقة والتقويم الزمني للعميل.
navigator.globalization.isDayLightSavingsTime(date, successCallback, errorCallback);
الوصف
يعيد هذا التابع قيمة منطقية تحدِّد ما إذا كان التوقيت الصيفي ساري المفعول، ويمرر النتيجة إلى الدالة successCallback
مع إعطائها الكائن properties
كمعامل. يجب أن يكون لهذا الكائن الخاصية dst
ذات قيمة منطقية (Boolean
). القيمة true
تشير إلى أنّ التوقيت الصيفي ساري المفعول عند التاريخ المحدد، فيما تشير القيمة false
إلى عكس ذلك.
المعامل المنفصل date
يجب أن يكون من النوع Date
.
إن حدث خطأ أثناء محاولة قراءة التاريخ، فستُنفّذ الدالة errorCallback
. رمز الخطأ المتوقع هو GlobalizationError.UNKNOWN_ERROR
.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- Firefox OS
- iOS
- Windows Phone 8
- ويندوز
- Browser
مثال
خلال فصل الصيف، وفي حال ضبْط المتصفح عند منطقة زمنية يسري فيها التوقيت الصيفي (DST-enabled timezone)، فستعرض هذه الشيفرة مربع حوار منبثقٍ يحتوي نصًّا مشابها للسلسلة النصية dst: true
:
navigator.globalization.isDayLightSavingsTime(
new Date(),
function (date) {alert('dst: ' + date.dst + '\n');},
function () {alert('Error getting names\n');}
);
يعيد هذا التابع عددًا منسقًا على شكل سلسلةٍ نصيةٍ وفقًا لتفضيلات المستخدم.
navigator.globalization.numberToString(number, successCallback, errorCallback, options);
الوصف
يعيد هذا التابع سلسلة نصية منسقة تمثل العدد، وتمررها إلى الدالة successCallback
مع إعطائها الكائن properties
كمعامل. يجب أن يكون لهذا الكائن خاصية value
ذات قيمة نصية (String
).
إن حدث خطأ أثناء محاولة تنسيق العدد، فستُنفّذ الدالة errorCallback
مع إعطائها الكائن GlobalizationError
كمُعامل. رمز الخطأ المتوقع هو GlobalizationError.FORMATTING_ERROR
.
المُعامل options
اختياري، وقيمته الافتراضية هي:
{type:'decimal'}
القيم الممكنة للخيار options.type
هي decimal
و percent
و currency
.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- iOS
- Windows Phone 8
- ويندوز
- Browser
مثال
عند ضبط الإعدادات المحلية للمتصفح عند القيمة en_US
، فستعرض هذه الشيفرة مربع حوار منبثق يحتوي نصًّا مشابهًا للسلسلة النصية number: 3.142
:
navigator.globalization.numberToString(
3.1415926,
function (number) {alert('number: ' + number.value + '\n');},
function () {alert('Error getting number\n');},
{type:'decimal'}
);
ملاحظات خاصة بمنصة ويندوز
- لا تدعم منصة Windows 8.0 تقريب الأعداد (number rounding)، وبالتالي لن يتم تقريب القيم تلقائيًا.
- في منصتيWindows 8.1 و Windows Phone 8.1، يتم اقتطاع الجزء الكسري بدلًا من تقريبه في حالة الأعداد التي تمثل النسب المئوية (
percent
)، لذلك يُعيّن عدد كسور الأرقام إلى القيمة 0. - لا يتم تجميع الأرقام التي تمثل النسب المئوية
percent
، إذ لا يمكن تحليلها وتحويلها من نصٍّ إلى عدد (stringToNumber) في حال تجميعها.
ملاحظات خاصة بالمتصفحات (Browsers)
- النوع
currency
غير مدعوم.
يحلّل (Parses) هذا التابع تاريخًا مُنسّقًا على هيئة سلسلة نصيةٍ، وفقًا لتفضيلات المستخدم وتقويمه الزمني باستخدام المنطقة الزمنية للعميل، ويعيد هذا التابع كائنَ التاريخ (date object) المقابل.
navigator.globalization.stringToDate(dateString, successCallback, errorCallback, options);
الوصف
يعيد هذا التابع التاريخَ ويمرره إلى رد نداء النجاح (success callback)، مع إعطائه كائنًا properties
كمعامل. يجب أن يحتوي ذلك الكائن على الخاصيات التالية:
year
: عدد يمثِّل السنةَ معبّرًا عنها بأربعة أرقام.month
: عدد يمثِّل الشهر (من 0 إلى 11).day
: عدد يمثِّل اليوم (من 1 إلى 31).hour
: عدد يمثِّل الساعة (من 0 إلى 23).minute
: عدد يمثِّل الدقيقة (من 0 إلى 59).second
: عدد يمثِّل الثانية (من 0 إلى 59).millisecond
: عدد يمثِّل أجزاء الثانية (ميلي ثانية من 0 إلى 999)، وهي غير متوفرة على جميع المنصات.
يجب أن يكون المُعامل المنفصل (inbound parameter) dateString
سلسلة نصية (أي من النوع String
).
المعامل options
اختياري، وقيمه الافتراضية هي:
{formatLength:'short', selector:'date and time'}
يمكن أن تساوي قيمة الخيار options.formatLength
إما short
أو medium
أو long
أو full
. أما الخيار options.selector
، فقيمته يمكن أن تساوي إما date
أو time
أو date and time
.
إن حدث خطأ أثناء محاولة تنسيق السلسلة النصية التي تحتوي على التاريخ، فستُنفّذ الدالة errorCallback
مع إعطائها الكائن GlobalizationError
كمُعامل. رمز الخطأ المتوقع هو GlobalizationError.PARSING_ERROR
.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- Firefox OS
- iOS
- Windows Phone 8
- ويندوز
- Browser
مثال
عند ضبط الإعدادات اللغوية للمتصفح إلى القيمة en_US
، فستعرض هذه الشيفرة مربع حوار منبثق يحتوي نصًّا مشابهًا للسلسلة النصية month:8 day:25 year:2012
. لاحظ أنّ العدد الصحيح الذي يمثل الشهر أقل بواحدٍ من القيمة المُحتواة في السلسلة النصية، لأنّ العدد الصحيح المقابل للشهر يمثل فهرس المصفوفة.
navigator.globalization.stringToDate(
'9/25/2012',
function (date) {alert('month:' + date.month +
' day:' + date.day +
' year:' + date.year + '\n');},
function () {alert('Error getting date\n');},
{selector: 'date'}
);
ملاحظات خاصة بمنصة Windows Phone 8
- لا تدعم الخاصيةُ
formatLength
إلا القيمتينshort
وfull
. - عندما تساوي الخاصية
pattern
القيمةdate and time
، فسيُعاد دائمًا تنسيقًا كاملًا للتاريخ (full datetime format). - يجب أن يُصاغ المعامل المنفصل
dateString
بالتوافق مع النمط المُعاد من قِبل التابعgetDatePattern
. بناءً على الإعدادات المحلية للمستخدم، فقد لا يكون النمط متوافقًا تمامًا مع المعيار ICU.
ملاحظات خاصة بمنصة ويندوز
- لا تدعم الخاصيةُ
formatLength
إلا القيمتينshort
وfull
. - عندما تساوي الخاصية
pattern
القيمةdate and time
، فستعيد دائمًا تنسيقًا كاملًا للتاريخ (full datetime format). - يجب أن يُصاغ المعامل المنفصل
dateString
بالتوافق مع النمط المُعاد من قِبل التابعgetDatePattern
. بناءً على الإعدادات المحلية للمستخدم، فقد لا يكون هذا النمط متوافقًا تمامًا مع المعيار ICU.
ملاحظات خاصة بالمتصفحات (Browsers)
- لا يتم دعم إلا 79 إعدادًا محليًا فقط، نظرًا لاستخدام الملف
moment.js
في هذا التابع. - يجب أن تكون السلسلة النصية المنفصلة (Inbound string) متوافقة مع تنسيق المُخرجات
dateToString
، وقد لا تتماشى تمامًا مع المعيار ICU اعتمادًا على الإعدادات المحلية للمستخدم. - لا يدعم المحدد
time
إلا القيمتينfull
وshort
الخاصتين بالخيارformatLength
.
يحلل هذا التابع عددًا منسقًا على شكل سلسلة نصية وفقًا لتفضيلات المستخدم، ثم يعيد العدد المقابل.
navigator.globalization.stringToNumber(string, successCallback, errorCallback, options);
الوصف
يُعيد هذا التابع العدد ويمرّره إلى الدالة successCallback
مع إعطائها الكائن properties
كمعامل. يجب أن يكون لهذا الكائن الخاصية value
ذات قيمة عددية (Number
).
إن حدث خطأ أثناء محاولة تحليل السلسلة النصية التي تحتوي العدد، فستُنفّذ الدالة errorCallback
مع إعطائها الكائن GlobalizationError
كمعامل. رمز الخطأ المتوقع هو GlobalizationError.PARSING_ERROR
.
المعامل options
اختياري، وقيمته الافتراضية هي:
{type:'decimal'}
يمكن أن تساوي قيمة الخاصية options.type
إمَّا decimal
أو percent
أو currency
.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- iOS
- Windows Phone 8
- ويندوز
مثال
عند ضبط الإعدادات المحلية للمتصفح عند القيمة en_US
، فستعرض هذه الشيفرة مربع حوار منبثق يحتوي نصًّا مشابهًا للسلسلة النصية number: 1234.56
:
navigator.globalization.stringToNumber(
'1234.56',
function (number) {alert('number: ' + number.value + '\n');},
function () {alert('Error getting number\n');},
{type:'decimal'}
);
ملاحظات خاصة بمنصة Windows Phone 8
- بالنسبة للنوع
percent
، لا تُقسَّم القيمة المُعادة على 100.
ملاحظات خاصة بمنصة ويندوز
- يجب أن تتوافق السلسلة النصية بشكل تام مع تنسيق الإعدادات المحلية. على سبيل المثال، يجب فصل رمز النسبة المئوية في الإعداد المحلي '
en-US
' إن كان المعاملtype
يساوي 'percent
'. - يجب ألا تُجمّع أرقام النسب المئوية
percent
لكي تُحلّل بالشكل الصحيح.
GlobalizationError
يمثل هذا الكائن خطأ، ويُعرَّف من قبل الواجهة البرمجية لإضافة العولمة (Globalization API).
الخاصيات
code
: عدد يمثل الرموز التالية التي تحدِّد نوع الخطأ:GlobalizationError.UNKNOWN_ERROR
: 0GlobalizationError.FORMATTING_ERROR
: 1GlobalizationError.PARSING_ERROR
: 2GlobalizationError.PATTERN_ERROR
: 3
message
: تمثل هذه الخاصية سلسلة نصية تتضمن شرح الخطأ أو تفاصيله.
الوصف
يُنشَأ هذا الكائن ويُملَأ من قبل كوردوفا، ثم يُعاد إلى رد نداءٍ (callback) في حالة حدوث خطأ.
المنصات المدعومة
- Amazon Fire OS
- أندرويد
- بلاك بيري 10
- Firefox OS
- iOS
- Windows Phone 8
- ويندوز
مثال
عند تنفيذ رد نداء الخطأ (error callback) التالي، فسيعرض مربع حوار منبثقٍ يحتوي نصًّا مشابهًا للسلسلتين النصيتين code: 3
و message:
:
function errorCallback(error) {
alert('code: ' + error.code + '\n' +
'message: ' + error.message + '\n');
};