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

توفر إضافة حالة الشبكة (cordova-plugin-network-information) تقديمًا لإصدار قديم من الواجهة البرمجية لمعلومات الشبكة. إذ توفر معلومات حول اتصال الجهاز الخلوي، واللاسكلي (wifi)، وتتحقق مما إذا كان الجهاز متصلا بالإنترنت.

للحصول على بعض الأفكار حول كيفية استخدام هذه الإضافة، اذهب إلى المثال التوضيحي في أسفل هذه الصفحة.

التثبيت

يمكن تثبيت هذه الإضافة عبر الأمر:

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 دون الإصدار السابع اكتشافَ نوع الاتصال الخلوي بالشبكة.
تُعيّن الخاصية 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 لإرفاق مُنصتٍ للأحداث (event listener) بمجرد إطلاق الحدث deviceready.

مثال سريع

document.addEventListener("offline", onOffline, false);
function onOffline() {
    // offline معالجة الحدث 
}‎

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

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

`online`

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

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

تفاصيل

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

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

مثال سريع

document.addEventListener("online", onOnline, false);
function onOnline() {
    // online معالجة الحدث 
}‎

ملاحظات خاصة بمنصة 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);
        // انشاء ملف جديد، أو فتح ملف موجود
        fs.root.getFile("data.txt", { create: true, exclusive: false }, function (fileEntry) {
          dataFileEntry = fileEntry;
        }, onErrorCreateFile);
    }, onErrorLoadFs);
}‎

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

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

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

function onOnline() {
    // online معالجة الحدث
    var networkState = navigator.connection.type;
    if (networkState !== Connection.NONE) {
        if (dataFileEntry) {
            tryToUploadFile();
        }
    }
    display('Connection type: ' + networkState);
}‎

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

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

ملاحظة: يتطلب هذا المثال تثبيت الإضافة FileTransfer.

function tryToUploadFile() {
    // يحتوي على عنوان صالح يُشير إلى ملف نصي على الجهاز fileURL نفترض أن المتغير
    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();
    // Content-Security-Policy تأكد من إضافة نطاق عنوان الخادم إلى الوسم
    // index.html في الملف
    ft.upload(fileURL, encodeURI(SERVER), success, fail, options);
};‎

إليك شيفرة الدالة offlineWrite.

ملاحظة: يتطلب هذا المثال إضافة الملفات.

function offlineWrite(offlineData) {
    // FileEntry لأجل FileWriter انشاء كائن
    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() {
    // offline معالجة الحدث
    console.log("lost connection");
}‎

انظر أيضا

مصادر

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