إضافة العولمة في كوردوفا

تمكّن إضافة العولمة (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 في توثيق كوردوفا الرسمي.