إضافة حال الشبكة في كوردوفا

 توفر هذه الإضافة تقديمًا لإصدار قديم من Network Information API. إذ توفر معلومات حول اتصال الجهاز الخلوي، والواي فاي، وتتحقق مما إذا كان الجهاز متصلا بالإنترنت. للحصول على بعض الأفكار حول كيفية استخدام هذه الإضافة، اذهب إلى [#sample sample] في أسفل هذه الصفحة، أو انتقل مباشرةً إلى محتوى [#reference reference].

الإبلاغ عن مشكلات في هذه الإضافة على Apache Cordova issue tracker

التثبيت

cordova plugin add cordova-plugin-network-information‎

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

• أندرويد
• Browser
• iOS
• ويندوز

Connection يوفر الكائن connection، الذي يمكن الحصول عليه عبر navigator.connection، معلومات حول اتصال الجهاز الخلوي، واللاسلكي.

خاصيات

• connection.type

ثوابت

• Connection.UNKNOWN
• Connection.ETHERNET
• Connection.WIFI
• Connection.CELL_2G
• Connection.CELL_3G
• Connection.CELL_4G
• Connection.CELL
• Connection.NONE

connection.type

توفر هذه الخاصية طريقة سريعة لتحديد حالة اتصال الجهاز بالشبكة، ونوع الاتصال.

مثال سريع

function checkConnection() {
    var networkState = navigator.connection.type;
    var states = {};
    states[Connection.UNKNOWN]  = 'Unknown connection';
    states[Connection.ETHERNET] = 'Ethernet connection';
    states[Connection.WIFI]     = 'WiFi connection';
    states[Connection.CELL_2G]  = 'Cell 2G connection';
    states[Connection.CELL_3G]  = 'Cell 3G connection';
    states[Connection.CELL_4G]  = 'Cell 4G connection';
    states[Connection.CELL]     = 'Cell generic connection';
    states[Connection.NONE]     = 'No network connection';
    alert('Connection type: ' + states[networkState]);
}
checkConnection();‎

التغييرات في الواجهة البرمجية

حتى الإصدار 2.3.0 من كوردوفا، كان المطورون يصلون إلى الكائن Connection عبر التعبير navigator.network.connection، وبعد ذلك تم تغييره إلى navigator.connection ليتطابق مع مواصفات W3C. لا يزال متوفرًا في موقعه القديم، ولكن مٌهملٌ الآن، وسيزال في إصدار قادمٍ.

ملاحظات خاصة بمنصة iOS

• يتعذر على منصات iOS الأقل من 7 اكتشاف نوع اتصال الخلوي بالشبكة.
• تُعييّن الخاصية navigator.connection.type إلى القيمة Connection.CELL لجميع البيانات الخلوية.

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

• عند تشغيل التطبيق على محاكي Windows Phone 8.1، فدائمًا تكون navigator.connection.type مساوية للقيمة Connection.ETHERNET.

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

• لا يمكن للمتصفح اكتشاف نوع الاتصال بالشبكة. يتم ضبط navigator.connection.type دائمًا عند القيمة Connection.UNKNOWN عند الاتصال بالإنترنت.

أحداث متعلقة بالشبكة

offline

يُطلق هذا الحدث عند انقطاع اتصال التطبيق (offline)، وعندما لا يكون الجهاز متصلاً بالإنترنت.

document.addEventListener("offline", yourCallbackFunction, false);‎

تفاصيل

يُطلق الحدث offline عندما يفقد جهاز مُتصلٌ بالشبكة الاتصالا بالشبكة بحيث يتعذر على التطبيق الوصول إلى الإنترنت. وهو يعتمد على نفس معلومات مثل الواجهة البرمجية للكائن Connection، ويُطلق عندما تصبح قيمة الخاصية connection.type مساوية للقيمة NONE.

في العادة، يجب أن تستخدم التطبيقات document.addEventListener لإرفاق مُنصتٍ (listener) بمجرد إطلاق الحدث deviceready.

مثال سريع

document.addEventListener("offline", onOffline, false);
function onOffline() {
    // Handle the offline event
}‎

ملاحظات خاصة بمنصة iOS

أثناء بدء التشغيل الأولي، يستغرق أول حدث offline (إن كان مُطبّقا) ثانيةً واحدةً على الأقل لإطلاقه.

online

يُطلق هذا الحدث عند يربط أحد التطبيقات الاتصال بالإنترنت، وعند توصيل الجهاز بالإنترنت.

document.addEventListener("online", yourCallbackFunction, false);‎

تفاصيل

يُطلق الحدث online عندما يربط جهاز غير متصل سابقًا الاتصال بالشبكة للسماح بوصول تطبيقٍ ما إلى الإنترنت. ويعتمد على نفس معلومات الواجهة البرمجية للكائن Connection، ويُطلق عندما تتغير قيمة الخاصية connection.type من NONE إلى أي قيمة أخرى.

في العادة، يجب أن تستخدم التطبيقات document.addEventListener لإرفاق منصتٍ بحدثٍ بمجرد إطلاق الحدث deviceready.

مثال سريع

document.addEventListener("online", onOnline, false);
function onOnline() {
    // Handle the online event
}‎

ملاحظات خاصة بمنصة iOS

أثناء بدء التشغيل الأولي، يستغرق الحدث online الأول (إن وُجد) ثانية واحدةً على الأقل قبل إطلاقه، إذ تكون قيمة الخاصية connection.type قبل ذلك مساوية للقيمة UNKNOWN.

عينة: قم بتحميل ملف اعتمادًا على حالة الشبكة لديك

تعرض الشيفرات البرمجية الموجودة في هذا القسم أمثلة لتغيير سلوك التطبيق باستخدام الحدثين online و offline وحالات الاتصال بالشبكة.

سنبدأ بإنشاء كائنٍ FileEntry جديدٍ (data.txt) لاستخدامه لجمع البيانات. استدع الدالة التالية من معالج الحدث deviceready. ملاحظة: يتطلب هذا المثال تثبيت إضافة الملفات.

var dataFileEntry;
function createSomeData() {
    window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
        console.log('file system open: ' + fs.name);
        // Creates a new file or returns an existing file.
        fs.root.getFile("data.txt", { create: true, exclusive: false }, function (fileEntry) {
          dataFileEntry = fileEntry;
        }, onErrorCreateFile);
    }, onErrorLoadFs);
}‎

بعد ذلك، أضف منصتَين للحدثين online و offline في معالج الحدث deviceready.

document.addEventListener("offline", onOffline, false);
document.addEventListener("online", onOnline, false);‎

ستعالج دالة التطبيق onOnline الحدث online. في معالج الحدث، تحقق من الحالة الراهنة للشبكة. في هذا التطبيق، تعامل مع كل أنواع الاتصال باستثناء Connection..NONE. إن حصلت على اتصال، فحاول تحميل ملف.

function onOnline() {
    // Handle the online event
    var networkState = navigator.connection.type;
    if (networkState !== Connection.NONE) {
        if (dataFileEntry) {
            tryToUploadFile();
        }
    }
    display('Connection type: ' + networkState);
}‎

عند إطلاق الحدث online في الشيفرة السابقة، استدع دالة التطبيق tryToUploadFile.

إن فشل استدعاء التابع upload الخاص بالكائن FileTransfer، فاستدع دالة التطبيق offlineWrite لحفظ البيانات الحالية في مكان ما. ملاحظة: يتطلب هذا المثال الإضافة FileTransfer.

function tryToUploadFile() {
    // !! Assumes variable fileURL contains a valid URL to a text file on the device,
    var fileURL = getDataFileEntry().toURL();
    var success = function (r) {
        console.log("Response = " + r.response);
        display("Uploaded. Response: " + r.response);
    }
    var fail = function (error) {
        console.log("An error has occurred: Code = " + error.code);
        offlineWrite("Failed to upload: some offline data");
    }
    var options = new FileUploadOptions();
    options.fileKey = "file";
    options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
    options.mimeType = "text/plain";
    var ft = new FileTransfer();
    // Make sure you add the domain of your server URL to the
    // Content-Security-Policy <meta> element in index.html.
    ft.upload(fileURL, encodeURI(SERVER), success, fail, options);
};‎

هنا هي شيفرة الدالة offlineWrite. ملاحظة: تتطلب هذه الأمثلة إضافة الملفات.

function offlineWrite(offlineData) {
    // Create a FileWriter object for our FileEntry.
    dataFileEntry.createWriter(function (fileWriter) {
        fileWriter.onwriteend = function () {
            console.log("Successful file write...");
            display(offlineData);
        };
        fileWriter.onerror = function (e) {
            console.log("Failed file write: " + e.toString());
        };
        fileWriter.write(offlineData);
    });
}‎

في حالة وقوع الحدث offline، افعل شيئًا ما، مثل تنبيه المستخدم، في هذا المثال، سنعرض رسالة عبر دالة سطر الأوامر log.

function onOffline() {
    // Handle the offline event
    console.log("lost connection");
}‎

مصادر

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