Cordova/cordova plugin globalization

تمكّن إضافة العولمة (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

navigator.globalization.getPreferredLanguage

يعيد هذا التابع وسم لغة المستخدم الحالية وفق المعيار 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.

navigator.globalization.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 وسم اللغة في المتصفح.

navigator.globalization.dateToString

يعيد هذا التابع تاريخًا (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).

navigator.globalization.getCurrencyPattern

يعيد هذا التابع سلسلةً نصيةً تمثل التنسيق الذي سيُستخدم لأجل تحليل (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

يُعيد هذا التابع مصفوفةً تتألف من أسماء الأشهر أو أيام الأسبوع، بناءً على تفضيلات المستخدم والتقويم الخاص به.

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 عنصرًا.

navigator.globalization.getDatePattern

يُعيد هذا التابع سلسلةً نصيةً تمثل النمط (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

يعيد هذا التابع أول يوم من الأسبوع وفقًا لتفضيلات المستخدم وتقويمه الزمني.

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 في هذا التابع.

navigator.globalization.getNumberPattern

يُعيد هذا التابع سلسلة نصيةً تمثل النمط (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.

navigator.globalization.isDayLightSavingsTime

يتحقّق هذا التابع ممّا إذا كان التوقيت الصيفي (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

يعيد هذا التابع عددًا منسقًا على شكل سلسلةٍ نصيةٍ وفقًا لتفضيلات المستخدم.

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 غير مدعوم.

navigator.globalization.stringToDate

يحلّل (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

يحلل هذا التابع عددًا منسقًا على شكل سلسلة نصية وفقًا لتفضيلات المستخدم، ثم يعيد العدد المقابل.

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: 0
  • GlobalizationError.FORMATTING_ERROR: 1
  • GlobalizationError.PARSING_ERROR: 2
  • GlobalizationError.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');
    };‎

انظر أيضًا

• إضافة مربعات الحوار
• إضافة تحديد الموقع الجغرافي
• دليل تطوير الإضافات في كوردوفا

مصادر

• صفحة cordova-plugin-globalization في توثيق كوردوفا الرسمي.