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 والذي يمثل المتغيرات المحلية المقابلة للإعدادات اللغوية، مفصولة بشرطة.
• لاحظ أن المتغير الإقليمي هو أحد خصائص إعداد "اللغة" ولا يتم تحديده بواسطة الإعداد المنفصل "البلد/المنطقة" في Windows Phone.

ملاحظات خاصة بمنصة ويندوز

• في هذه المنصة، يُعاد رمز اللغة، وهو رمزٌ مكون من حرفين يمثلان اللغة متوافقٌ مع المعيار ISO 639-1، ورمز الدولة وفق معيار ISO 3166-1 والذي يمثل المتغيرات المحلية المقابلة للإعدادات اللغوية، مفصولة بشرطة.

ملاحظات خاصة بالمتصفحات (Browsers)

• في المتصفحات يتم الحصول على النتيجة من الدالة getLocaleName

navigator.globalization.getLocaleName

يعيد هذا التابع الوسم المتوافق مع المعيار BCP 47 الذي يمثل الإعدادات المحلية الحالية للعميل.

navigator.globalization.getLocaleName(successCallback, errorCallback);‎

الوصف

يعيد هذا التابع سلسلة نصية تمثل مُعرّف اللغة المتوافق مع المعيار BCP 47، ويمررها إلى الدالة successCallback مع إعطائها الكائن properties كمعامل. يجب أن يكون لهذا الكائن خاصية value ذات قيمة نصية (String). سيتكون الوسم المحلي من رمزٍ مكونٍ من حرفين صغيرين يمثلان اللغة، ورمز مكونٌ من حرفين كبيرين يمثلان البلد، ورمز متغير (غير محدد)، مفصولة بشرطة.

إن حدث هناك خطأ أثناء محاولة الحصول على الإعدادات المحلية، فستُنفّذ الدالة 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

يعيد هذا التابع تاريخًا على هيئة سلسلة نصيةٍ مُنسّقةٍ وفقًا للإعدادات المحلية للعميل ومنطقته الزمنية.

navigator.globalization.dateToString(date, successCallback, errorCallback, options);‎

الوصف

يعيد هذا التابع التاريخ المنسق String عبر خاصية 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 فقط.
• النمط الخاص بالمُحدّد "date and time" هو دائمًا تنسيق كامل للتاريخ datetime.
• بناءً على لغة المستخدم، فقد لا تكون القيمة المُعادة متوافقةً مع المعيار ICU بشكلٍ كاملٍ.

ملاحظات خاصة بمنصة ويندوز

• لا يدعم الخيار formatLength إلا القيمتين short و full فقط.
• النمط الخاص بالمُحدّد "date and time" هو دائمًا تنسيق كامل للتاريخ datetime.
• بناءً على لغة المستخدم، فقد لا تكون القيمة المُعادة متوافقةً مع المعيار 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: تمثل هذه الخاصية نمط العملة الذي ستُنسّق العملات وتُحلّل قيمها بناءً عليه. الأنماط تتبع المعيار Unicode Technical Standard #35. (سلسلة نصية)
• code: رمز العملة وفق المعيار ISO 4217 لأجل النمط. (سلسلة نصية)
• fraction: عدد المنازل العشرية التي ستُستخدم عند تحليل البيانات وتنسيقها. (عدد)
• rounding: التقريب الزائد (rounding increment) الذي سيُستخدم عند التحليل والتنسيق. (عدد)
• decimal: الرمز العشري الذي سيُستخدم في التحليل والتنسيق. (سلسلة نصية)
• grouping: رمز التجميع (grouping symbol) الذي سيُستخدم في التحليل والتنسيق. (سلسلة نصية)

يجب أن يكون المعامل المنفصل 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 مع تحتوي مصفوفة من السلاسل النصية Array String. تشتمل المصفوفة على أسماء تبدأ من الشهر الأول في السنة، أو اليوم الأول من الأسبوع، وفقًا للخيار المحدد.

إن حدث خطأ أثناء محاولة الحصول على الأسماء، فستُنفّذ الدالة 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: نمط التاريخ والوقت الذي ستُنسّق التواريخ وتُحلل على وِفقه. اتتبع هذه لأنماط المعيار Unicode Technical Standard #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 تعيد التاريخ (datetime) بتنسيق كامل فقط.
• تعيد الخاصية timezone الاسم الكامل للمنطقة الزمنية.
• الخاصية dst_offset غير مدعومة، وتعيد دائمًا القيمة صفر.
• بناءً على الإعدادات المحلية للمستخدم، فقد لا يكون النمط متوافقًا تمامًا مع المعيار ICU.

ملاحظات خاصة بمنصة ويندوز

• لا تدعم الخاصيةُ formatLength إلا القيمتين short و full.
• الخاصية pattern الخاصة بالنمط date and time تعيد التاريخ (datetime) بتنسيق كامل فقط.
• تعيد الخاصية 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: نمط تنسيق الأرقام وتحليلها. الأنماط تتبع المعيار Unicode Technical Standard #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

يحلّل هذا التابع تاريخًا مُنسّقًا على هيئة سلسلة نصيةٍ، وفقًا لتفضيلات المستخدم وتقويمه الزمني باستخدام المنطقة الزمنية للعميل، ويعيد هذا التابع كائنَ التاريخ (date object) المقابل.

navigator.globalization.stringToDate(dateString, successCallback, errorCallback, options);‎

الوصف

يعيد هذا التابع التاريخ ويمرره إلى رد نداء النجاح مع إعطائه كائنًا 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 فقط.
• النمط الخاص بالمُحدّد "date and time" يكون دائمًا تنسيقًا كاملًا للتاريخ datetime.
• يجب أن يُصاغ المعامل المنفصل dateString بالتوافق مع النمط المُعاد من قِبل التابع getDatePattern. بناءً على الإعدادات المحلية للمستخدم، قد لا يكون النمط متوافقًا تمامًا مع المعيار ICU.

ملاحظات خاصة بمنصة ويندوز

• لا تدعم الخاصيةُ formatLength إلا القيمتين short و full فقط.
• النمط الخاص بالمُحدّد "date and time" هو دائمًا تنسيق كامل للتاريخ datetime.
• يجب أن يُصاغ المعامل المنفصل dateString بالتوافق مع النمط المُعاد من قِبل getDatePattern. بناءً على الإعدادات المحلية للمستخدم، قد لا يكون هذا النمط متوافقًا تمامًا مع المعيار ICU.

ملاحظات خاصة بالمتصفحات (Browsers)

• لا يتم دعم إلا 79 إعدادًا محليًا فقط، نظرًا لاستخدام الملف moment.js لهذا التابع.
• يجب أن تكون السلسلة النصية المنفصلة متوافقة مع تنسيق المُخرجات 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' إن كانت معامل النوع يساوي 'percent'.
• يجب ألا تُجمّع أرقام النسب المئوية percent حتى تُحلّل بالشكل الصحيح.

GlobalizationError

يمثل هذا الكائن خطأ من واجهة Globalization البرمجية.

خاصيات

• code: تمثل الرموز التالية نوع الخطأ (عدد)
• GlobalizationError.UNKNOWN_ERROR: 0
• GlobalizationError.FORMATTING_ERROR: 1
• GlobalizationError.PARSING_ERROR: 2
• GlobalizationError.PATTERN_ERROR: 3
• message: تمثل هذه الخاصية رسالة نصية تتضمن شرح الخطأ أو تفاصيله. (سلسلة نصية)

الوصف

يُنشأ هذا الكائن ويُملؤ من قبل كوردوفا، ثم يُعاد إلى رد نداءٍ في حالة حدوث خطأ.

المنصات المدعومة

• Amazon Fire OS
• أندرويد
• بلاك بيري 10
• Firefox OS
• iOS
• Windows Phone 8
• ويندوز

مثال

عند تنفيذ رد نداء الخطأ التالي، فسيعرض مربع حوار منبثقٍ يحتوي نصا مشابها للسلسلتين النصيتين code: 3 و message:

function errorCallback(error) {
        alert('code: ' + error.code + '\n' +
              'message: ' + error.message + '\n');
    };‎

مصادر

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