Cordova/cordova plugin inappbrowser

تساعد إضافة المتصفح الداخلي (cordova-plugin-inappbrowser) على عرض المقالات ومقاطع الفيديو وموارد الويب المفيدة داخل تطبيقك. كما تمُكن المستخدمين أيضًا من الاطلاع على صفحات الويب دون مغادرة التطبيق.

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

توفر هذه الإضافة مُتصفحًا يمكن عرضه عند استدعاء التابع cordova.InAppBrowser.open()‎.

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');‎

لقد تم تعريف التابع cordova.InAppBrowser.open()‎ ليكون بديلًا للدالة window.open()‎. يمكن لاستدعاءات الدالةwindow.open() ‎ الحالية أن تستخدم نافذةَ InAppBrowser عن طريق استبدال window.open كما هو موضح في المثال التالي:

window.open = cordova.InAppBrowser.open;‎

تتصرف النافذة InAppBrowser كمتصفح عادي، ولا يمكنها الوصول إلى الواجهات البرمجية لكوردوفا. لهذا السبب، يُنصَح باستخدام InAppBrowser إذا احتجت إلى تحميل محتوى خارجي (غير موثوق به)، بدلًا من تحميله في عارض كوردوفا الرئيسي. InAppBrowser ليس معنيًا باللوائح البيضاء، ولا يفتح روابط في متصفح النظام.

يوفر InAppBrowser بشكل افتراضي عناصر الواجهة الرسومية (GUI) للمستخدم (back, forward, done).

للتوافق مع الإصدارات القديمة، تربط هذه الإضافةُ الدالةَ window.open مع خطّاف. لكن يمكن أن يكون للخطّاف الذي رُبطَت فيه الدالة window.open تأثيرات جانبية غير مقصودة (خاصة إذا تم تضمين هذه الإضافة كارتباط لإضافة أخرى). سيُزال خطاف الدالة window.open في الإصدار الرئيسي مستقبلًا. إلى حين إزالة ذلك الخطاف من الإضافة، يمكن للتطبيقات استعادة السلوك الافتراضي يدويًا عبر تنفيذ الأمر التالي:

delete window.open // إعادة رد النداء إلى وضعه الافتراضي

على الرغم من أنَّ الدالة window.open موجودة في النطاق العام، إلا أنّ الكائن InAppBrowser لن يكون متوفرًا إلا بعد إطلاق الحدث deviceready.

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log("window.open works well");
}‎

التثبيت

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

cordova plugin add cordova-plugin-inappbrowser‎

إن كنت تريد أن تُعرض جميع الصفحات المُحملة في تطبيقك في نافذة InAppBrowser، يمكنك ببساطة أن تربط الدالة window.open بخطاف أثناء التهيئة. إليك المثال التالي:

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    window.open = cordova.InAppBrowser.open;
}‎

cordova.InAppBrowser.open

يفتح هذا التابع عنوانًا في نسخة جديدة (instance) من InAppBrowser، أو في نسخة من المتصفح الحالي، أو في متصفح النظام:

var ref = cordova.InAppBrowser.open(url, target, options);‎

المعاملات المُمرَّرة إلى هذه الدالة هي:

• ref: يشير إلى النافذة InAppBrowser عندما يُضبَط المعامل target إلى القيمة '‎_blank'. ‏(InAppBrowser)

• url: سلسلة نصية تمثِّل العنوان المراد تحميله. مرّر هذا المعامل إلى الدالةَ encodeURI()‎ إن كان العنوان يحتوي على محارف يونيكود.

• target: سلسلة نصية تحدِّد المكان الذي سيُحمّل فيه العنوان. وهو معامل اختياري، قيمته الافتراضية تساوي ‎_self.
  • _self: يُفتح في عارض كوردوفا إن كان العنوان مُدرجًا في اللائحة البيضاء، وإلا فسيُفتح في نافذة InAppBrowser.
  • _blank: يُفتح في InAppBrowser.
  • _system: يفتح في متصفح النظام.

• options: سلسلة نصية تحوي خيارات النافذة InAppBrowser. وهو معامل اختياري، وقيمته الافتراضية هي location=yes. يجب ألا تحتوي السلسلة النصية options على أية مسافة فارغة، ويجب أن تُفصل الأزواج اسم/قيمة (name/value) للميزات بفاصلة. كما أنّ أسماء الميزات غير حساسة لحالة الأحرف.

تدعم جميع المنصات الخيار التالي:

• location: اضبط هذه الخاصية إلى القيمة yes أو no لإظهار شريط التصفح (location bar) في InAppBrowser أو إخفائه.

تدعم منصة أندرويد هذه الخيارات الإضافية:

• hidden: اضبط هذا الخيار إلى القيمة yes لإنشاء المتصفح وتحميل الصفحة بدون إظهاره. يُطلق الحدث loadstop عند اكتمال التحميل. احذف هذا الخيار أو اضبطه إلى القيمة no (القيمة الافتراضية) لفتح المتصفح وتحميل الصفحة بشكل طبيعي.
• beforeload: عين هذا الخيار لتمكين الحدث Beforeeload من تعديل الصفحات التي حُمِّلت فعليا في المتصفح. القيم المقبولة هي:
  • get: لاعتراض طلبات GET فقط
  • post: لاعتراض طلبات POST
  • yes: لاعتراض طلبات GET و POST معا. لاحظ أنّ طلبات POST غير مدعومة حاليًا وستُتجاهل (إذا قمت بتعيين القيمة beforeload = post، فسيؤدي ذلك إلى إطلاق خطأ).

• cbeforeloadlearcache: اضبط هذا الخيار إلى القيمة yes لمحو ذاكرة التخزين المؤقت لملفات تعريف الارتباط (cookie cache) في المتصفح قبل فتح النافذة الجديدة
• clearsessioncache: اضبط هذا الخيار إلى القيمة yes لمحو ذاكرة التخزين المؤقت لملفات تعريف الارتباط قبل فتح النافذة الجديدة
• closebuttoncaption: أعطِ لهذا الخيار سلسلةً نصيةً لاستخدامها كتسميةٍ للزر بدلًا من الحرف X. تذكّر أنه سيكون عليك مراعاة الإعدادات اللغوية المحلية بنفسك.
• closebuttoncolor: أعطِ لهذا الخيار سلسلةً نصيةً تمثل قيمة لونية ست عشرية (hex color) صالحة، مثل: ‎#00ff00، لأجل تغيير لون زر الإغلاق الافتراضي، سواءً كان نصًا، أو كان يساوي القيمة الافتراضية X. لا يكون لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الخيار location إلى القيمة yes.
• footer: اضبط هذا الخيار إلى القيمة yes لإظهار زر الإغلاق في أسفل النافذة بشكل مماثلٍ للزر Done في منصة iOS، سيظهر زر الإغلاق بشكل مماثلٍ لترويسة (header) النافذة، لذلك استخدم closebuttoncaption و closebuttoncolor لتعيين خصائصه.
• footercolor: أعطِ لهذا الخيار سلسلةً نصيةً تمثل لونًا ست عشريًا (hex color) صالحًا، مثل ‎#00ff00 أو ‎#CC00ff00 (#aarrggbb)‎، لتغيير لون تذييل (footer) النافذة الافتراضي. ليس لهذا الخيار تأثيرٌ إلا إن عيّن المُستخدم الخيارَ footer إلى القيمة yes.
• hardwareback: اضبط هذا الخيار إلى القيمة yes لاستخدام زر الرجوع الخاص بالجهاز للرجوع للخلف إلى الصفحات الموجودة في تاريخ نافذة InAppBrowser (الصفحات التي جرى زيارتها من قبل). إذا لم تكن هناك صفحات سابقة، فسيتم إغلاق InAppBrowser. القيمة الافتراضية هي yes، إن كنت تريد أن تجعل زر الرجوع يغلق نافذة InAppBrowser، فعيّن هذا الخيار إلى القيمة no .
• hidenavigationbuttons: اضبط هذا الخيار إلى القيمة yes لإخفاء أزرار التصفح (navigation buttons) على شريط التصفح (location toolbar)، ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الخيار location إلى القيمة yes. القيمة الافتراضية هي no.
• hideurlbar: اضبط هذا الخيار إلى القيمة yes لإخفاء شريط العنوان من شريط التصفح، ليس لهذا الخيار تأثيرًا إلا إن كان المستخدم قد عيّن الخيار location إلى القيمة yes. القيمة الافتراضية هي no.
• navigationbuttoncolor: أعطِ لهذا الخيار سلسلة نصية تمثل لونًا ست عشريًا (hex color) صالحًا، مثل: ‎#00ff00، لتغيير لون أزرار التصفح الافتراضي. ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الخيار location إلى القيمة yes، وكانت قيمة الخيار hidenavigationbuttons تخالف yes.
• toolbarcolor: أعطِ لهذا الخيار سلسلة نصية تمثل لونًا ست عشريًا صالحًا، مثل: ‎#00ff00، لتغيير لون شريط الأدوات الافتراضي. ليس لهذا الخيار تأثيرًا إلا إن كان المستخدم قد عيّن الخيار location إلى القيمة yes.
• lefttoright: اضبط هذا الخيار إلى القيمة yes لأجل تبديل مواضع أزرار التنقل وزر الإغلاق. على وجه التحديد، ستتحول أزرار التنقل إلى الزر الأيسر وينتقل زر الإغلاق إلى اليمين.
• zoom: اضبط هذا الخيار إلى القيمة yes لعرض عناصر التحكم في الحجم في متصفح أندرويد، أو اضبطه إلى القيمة no إن أردت إخفاءها. القيمة الافتراضية هي yes.
• mediaPlaybackRequiresUserAction: اضبط هذا الخيار إلى القيمة yes لمنع صوتيات أو فيديوها HTML5 من التشغيل التلقائي. القيمة الافتراضية هي no.
• shouldPauseOnSuspend: اضبط هذا الخيار إلى القيمة yes لإيقاف عارض InAppBrowser أو استئنافه مع التطبيق، وذلك لإيقاف صوت الخلفية (قد يكون هذا ضروريًا لتجنب المشكلات التي تخص Google Play كما هو موضح في الصفحة CB-11013).
• useWideViewPort: يحدِّد هذا الخيار ما إذا كان العارض سيدعم وسم HTML الوصفي "viewport"، أو أنّ عليه أن يستخدم إطار عرضٍ (viewport) واسعٍ. عندما يُعطَى هذا الخيار القيمة no، سيُعيّن عرض المخطط (layout) إلى قيمة العرض في العارض محسوبةً بوحدات بكسل مستقلة عن الجهاز المُستخدم (device-independent pixels). إن أُعطي هذا الخيار القيمة yes وكانت الصفحة تحتوي الوسم الوصفي viewport، فستُستخدَم قيمة العرض المحددة في الوسم. إن لم تحتوِ الصفحة على الوسم، أو لم تحدد قيمةً للعرض، فسيُستخدم إطار عرضٍ واسعٍ. القيمة الافتراضية هي yes.

تدعم منصة iOS الخيارات الإضافية التالية:

• usewkwebview: اضبط هذا الخيار إلى القيمة yes لأجل استخدام محرك WKWebView في InappBrowser. احذف الخيار أو أو اضبطه إلى القيمة no لأجل استخدام UIWebView. ملاحظة: يتطلب استخدام usewkwebview=yes تثبيت إضافة محرك WKWebView في مشروع كوردوفا (مثل cordova-plugin-wkwebview أو cordova-plugin-ionic-webview).

• hidden: اضبط هذا الخيار إلى القيمة yes لإنشاء المتصفح وتحميل الصفحة، ولكن دون إظهاره. سيُطلق الحدث loadstop عند اكتمال التحميل. احذف هذا الخيار أو اضبطه إلى القيمة no (الافتراضية) لفتح المتصفح وتحميله بشكل طبيعي.
• beforeload: عين هذا الخيار لتمكين الحدث Beforeeload من تعديل الصفحات التي حُمِّلت فعليا في المتصفح. القيم المقبولة هي:
  • get: لاعتراض طلبات GET فقط
  • post: لاعتراض طلبات POST
  • yes: لاعتراض طلبات GET و POST معا. لاحظ أنّ طلبات POST غير مدعومة حاليًا وستُتجاهل (إذا قمت بتعيين القيمة beforeload = post، فسيؤدي ذلك إلى إطلاق خطأ).
• clearcache: اضبط هذا الخيار إلى القيمة yes لمحو ذاكرة التخزين المؤقت لملفات تعريف الارتباط (cookie cache) للمتصفح قبل فتح النافذة الجديدة
• clearsessioncache: اضبط هذا الخيار إلى القيمة yes لمحو ذاكرة التخزين المؤقت لملفات تعريف الارتباط قبل فتح النافذة الجديدة.
• closebuttoncolor: أعطِ لهذا الخيار سلسلةً نصيةً تمثل لونًا ست عشريًا (hex color) صالحًا، مثل: ‎#00ff00، لتغيير لون الزر Done الافتراضي. لا يُطبق هذا الإعداد إلا عند تفعيل شريط الأدوات.
• cleardata: اضبط هذا الخيار إلى القيمة yes لمسح كامل التخزين المحلي للمتصفح (ملفات تعريف الارتباط، وتخزين HTML5 المحلي، و IndexedDB ...) قبل فتح النافذة الجديدة.
• closebuttoncaption: أعطِ لهذا الخيار سلسلةً نصيةً لاستخدامها كتسميةِ للزر Done. تذكر أن عليك مراعاة الإعدادات اللغوية المحلية بنفسك.
• disallowoverscroll: يُضبط هذا الخيار إلى القيمة yes أو no (القيمة الافتراضية هي no) لتشغيل أو إيقاف الخاصية UIWebViewBounce.
• hidenavigationbuttons: اضبط هذا الخيار إلى القيمة yes أو no لإظهار أزرار التصفح (navigation buttons) في شريط الأدوات أو إخفائها (القيمة الافتراضية هي no). لا يُطبّق هذا الخيار إلا عند تفعيل شريط الأدوات.
• navigationbuttoncolor: أعطِ لهذا الخيار سلسلةًً نصيةًً تمثل لونًا ست عشريًا (hex color) صالحًا، مثل: ‎#00ff00، لتغيير اللون الافتراضي. لا يُطبّق هذا الخيار إلا عند إظهار أزرار التصفح.
• toolbar: أعطِ لهذا الخيار القيمة yes أو no لإظهار شريط الأدوات أو إخفائه في نافذة InAppBrowser (القيمة الافتراضية هي yes).
• toolbarcolor: أعطِ لهذا الخيار سلسلةً نصيةً تمثل لونًا ست عشريًا (hex color) صالحًا، مثل: ‎#00ff00، لتغيير اللون الافتراضي لشريط الأدوات. لا يُطبّق هذا الخيار إلا عند تفعيل شريط الأدوات.
• toolbartranslucent: أعطِ لهذا الخيار القيمة yes أو no لجعل شريط الأدوات شبه شفاف (translucent). القيمة الافتراضية هي yes. لا يُطبّق هذا الخيار إلا عند تفعيل شريط الأدوات.
• lefttoright: اضبط هذا الخيار إلى القيمة yes لأجل تبديل مواضع أزرار التنقل وزر الإغلاق. على وجه التحديد، ستتحول أزرار التنقل إلى الزر الأيسر وينتقل زر الإغلاق إلى اليمين.
• enableViewportScale: اضبط هذا الخيار إلى القيمة yes أو no لمنع تعديل حجم إطار العرض (viewport) عبر الوسم <meta> الوصفي. القيمة الافتراضية هي no.
• mediaPlaybackRequiresUserAction: اضبط هذا الخيار إلى القيمة yes لمنع صوتيات أو فيديوهات HTML5 من التشغيل التلقائي. القيمة الافتراضية هي no.
• allowInlineMediaPlayback: اضبط هذا الخيار إلى القيمة yes أو no للسماح بتشغيل وسائط HTML5 المُدرجة على السطر (in-line)، وعرضها في نافذة المتصفح بدلًا من واجهة تشغيلٍ خاصةٍ بالجهاز. يجب أن يشتمل عنصر video في HTML على الخاصية webkit-playsinline. القيمة الافتراضية هي no.
• keyboardDisplayRequiresUserAction: اضبط هذا الخيار إلى القيمة yes أو no لفتح لوحة المفاتيح عندما تتلقى عناصر النموذج (form) التركيز (focus) عبر استدعاء دالة جافاسكريبت focus()‎. القيمة الافتراضية هي yes.
• suppressesIncrementalRendering: اضبط هذا الخيار إلى القيمة yes أو no للانتظار حتى يتم استلام كل محتوى إطار العرض الجديد قبل عرضه. القيمة الافتراضية هي no.
• presentationstyle: اعط لهذا الخيار القيمة pagesheet أو formsheet أو fullscreen لتعيين نمط العرض. القيمة الافتراضية هي fullscreen.
• transitionstyle: اعط لهذا الخيار القيمة fliphorizontal أو crossdissolve أو coververtical لتعيين نمط الانتقال. القيمة الافتراضية هي coververtical.
• toolbarposition: اضبط هذا الخيار إلى القيمة top أو bottom لجعل شريط الأدوات في أعلى النافذة أو أسفلها. القيمة الافتراضية هي bottom.
• hidespinner: اضبط هذا الخيار إلى القيمة yes أو no لتغيير رؤية (visibility) مؤشر التحميل. القيمة الافتراضية هي no.

تدعم منصة ويندوز الخيارات الإضافية التالية:

• hidden: اضبط هذا الخيار إلى القيمة yes لإنشاء المتصفح وتحميل الصفحة دون إظهاره. يُطلَق الحدث loadstop عند اكتمال التحميل. احذف هذا الخيار أو اضبطه إلى القيمة no (القيمة الافتراضية) لفتح المتصفح وتحميله بشكل طبيعي.
• hardwareback: يعمل هذا الخيار بطريقة مشابهة لعمله على منصة أندرويد.
• fullscreen: اضبط هذا الخيار إلى القيمة yes لإنشاء متصفحٍ وعرضه بدون إحاطته بحدود. يرجى ملاحظة أنه إذا تم تحديد الخيار location=no أيضًا، فلن يتوافر للمستخدم أي تحكم (control) لإغلاق النافذة IAB.

المنصات المدعومة هي:

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

مثال عن استعمال cordova.InAppBrowser.open:

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
var ref2 = cordova.InAppBrowser.open(encodeURI('http://ja.m.wikipedia.org/wiki/ハングル'), '_blank', 'location=yes');

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

في الوقت الحالي، القيمة الوحيدة المدعومة للمعامل target في منصة OSX هي ‎_system.

لم يتم بعدُ تقديم الهدفين ‎_blank و ‎_self، وسيُتاجهلان بصمت.

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

• تُقدِّم هذه الإضافة عبر الإطار الذكي iframe،
• لم يتم تقديم تاريخ التصفح (Navigation history) بعدُ (أي الزِّرين back و forward في شريط التصفح LocationBar).

الكائن InAppBrowser

يمثل الكائن المُعاد من استدعاء التابع cordova.InAppBrowser.open عند تعيين المعامل target إلى القيمة '‎_blank'.

التوابع التي يمكن استعمالها معه هي:

• addEventListener
• removeEventListener
• close
• show
• hide
• executeScript
• insertCSS

InAppBrowser.addEventListener

يضيف هذا التابع مُنصتًا (listener) لحدثٍ من InAppBrowser. (متاح فقط عند ضبط الخيار target إلى القيمة '‎_blank').

ref.addEventListener(eventname, callback);‎

المعاملات المُرَّرة إلى هذا التابع هي:

• ref : يشير إلى نافذة InAppBrowser ‏(‎InAppBrowser).

• eventname: سلسلة نصية تمثِّل الحدث المُراد ربط منصت به.
  • loadstart: يُطلق هذا الحدث عندما يبدأ InAppBrowser في تحميل عنوان URL.
  • loadstop: يُطلق هذا الحدث عند انتهاء InAppBrowser من تحميل عنوان URL.
  • loaderror: يُطلق هذا الحدث عندما يواجه InAppBrowser خطأً أثناء تحميل عنوان URL.
  • exit: يُطلق هذا الحدث عند إغلاق نافذة InAppBrowser.
  • beforeload: يُطلق هذا الحدث عندما يقرر InAppBrowser إن كان سيُحمِّل عنوان URL أو لا (فقط عند تعيين الخيار beforeload)
  • message: يُطلق هذا الحدث عندما يتلقى InAppBrowser رسالة من الصفحة التي تم تحميلها داخل عارض InAppBrowser .
• callback: دالة رد النداء التي ستنفذ عند إطلاق الحدث. يُمرّر إليها الكائن InAppBrowserEvent كمعاملٍ.

إليك المثال التالي:

var inAppBrowserRef;

function showHelp(url) {

    var target = "_blank";

    var options = "location=yes,hidden=yes,beforeload=yes";

    inAppBrowserRef = cordova.InAppBrowser.open(url, target, options);

    inAppBrowserRef.addEventListener('loadstart', loadStartCallBack);

    inAppBrowserRef.addEventListener('loadstop', loadStopCallBack);

    inAppBrowserRef.addEventListener('loaderror', loadErrorCallBack);

    inAppBrowserRef.addEventListener('beforeload', beforeloadCallBack);

    inAppBrowserRef.addEventListener('message', messageCallBack);
}

function loadStartCallBack() {

    $('#status-message').text("loading please wait ...");

}

function loadStopCallBack() {

    if (inAppBrowserRef != undefined) {

        inAppBrowserRef.insertCSS({ code: "body{font-size: 25px;" });

        inAppBrowserRef.executeScript({ code: "\
            var message = 'this is the message';\
            var messageObj = {my_message: message};\
            var stringifiedMessageObj = JSON.stringify(messageObj);\
            webkit.messageHandlers.cordova_iab.postMessage(stringifiedMessageObj);"
        });

        $('#status-message').text("");

        inAppBrowserRef.show();
    }

}

function loadErrorCallBack(params) {

    $('#status-message').text("");

    var scriptErrorMesssage =
       "alert('Sorry we cannot open that page. Message from the server is : "
       + params.message + "');"

    inAppBrowserRef.executeScript({ code: scriptErrorMesssage }, executeScriptCallBack);

    inAppBrowserRef.close();

    inAppBrowserRef = undefined;

}

function executeScriptCallBack(params) {

    if (params[0] == null) {

        $('#status-message').text(
           "Sorry we couldn't open that page. Message from the server is : '"
           + params.message + "'");
    }

}

function beforeloadCallBack(params, callback) {

    if (params.url.startsWith("http://www.example.com/")) {

        // Load this URL in the inAppBrowser.
        callback(params.url);
    } else {

        // The callback is not invoked, so the page will not be loaded.
        $('#status-message').text("This browser only opens pages on http://www.example.com/");
    }

}

function messageCallBack(params){
    $('#status-message').text("message received: "+params.data.my_message);
}

خاصيات الكائن InAppBrowserEvent

الخاصيات المتاحة لاستعمالها مع الكائن InAppBrowserEvent هي:

• type: سلسلة نصية تمثِّل اسم الحدث، والذي يساوي إمّا loadstart أو loadstop أو loaderror أو exit.
• url: سلسلة نصية تشير إلى العنوان الذي تم تحميله.
• code: عدد يمثِّل رمز الخطأ. لا تكون هذه الخاصية مُتاحةً إلا في حال إطلاق الحدث loaderror.
• message: سلسلة نصية تمثِّل رسالة الخطأ، لا تكون هذه الخاصية مُتاحةً إلا في حال إطلاق الحدث loaderror.
• data: محتويات الرسالة، لا تعمل إلا في حال تعيين message. وهي كائن JSON (سلسلة نصية).

المنصات المدعومة هي:

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

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

في هذه المنصات، لا تُطلق الأحداث loadstart و loaderror و message.

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

في هذه المنصة، لا يُطلق الحدث message.

إليك مثالا سريعا عن التابع addEventListener:

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstart', function(event) { alert(event.url); });‎

InAppBrowser.removeEventListener

يزيل هذا التابع مُنصِتا لحدثٍ من أحداث InAppBrowser. وهو متاح فقط عند ضبط الخيار target عند القيمة '‎_blank'.

ref.removeEventListener(eventname, callback);‎

المعاملات المُرَّرة إلى هذا التابع هي:

• ref:يشير إلى النافذة InAppBrowser.

• eventname: سلسلة نصية تمثل الحدثَ المُراد التوقف عن الإنصات له.
  • loadstart: يُطلق هذا الحدث عندما يبدأ InAppBrowser في تحميل عنوان URL.
  • loadstop: يُطلق هذا الحدث عند انتهاء InAppBrowser من تحميل عنوان URL.
  • loaderror: يُطلق هذا الحدث عندما يواجه InAppBrowser خطأ أثناء تحميل عنوان URL.
  • exit: يُطلق هذا الحدث عند إغلاق نافذةِ InAppBrowser.
  • message: يُطلق هذا الحدث عندما يتلقى InAppBrowser رسالة من الصفحة التي تم تحميلها داخل عارض InAppBrowser .
• callback: دالة رد النداء التي سيتم تنفيذها عند إطلاق الحدث والتي سيُمرّر إليها الكائنٌ InAppBrowserEvent.

المنصات المدعومة هي:

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

إليك المثال التالي عن استعمال التابع removeEventListener:

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
var myCallback = function(event) { alert(event.url); }
ref.addEventListener('loadstart', myCallback);
ref.removeEventListener('loadstart', myCallback);

InAppBrowser.close

يغلق هذا التابع نافذة InAppBrowser.

ref.close();‎

المتغير ref يُشير إلى نافذة InAppBrowser ‏(InAppBrowser).

المنصات المدعومة هي:

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

مثال عن استعمال التابع close:

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.close();‎

InAppBrowser.show

يُظهر هذا التابع نافذة InAppBrowser فُتِحت وهي مخفية. استدعاء هذا التابع لن يكون له أي تأثير إن كانت نافذة InAppBrowser مرئيًةً.

ref.show();‎

المتغير ref يُشير إلى نافذة InAppBrowser.

المنصات المدعومة هي:

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

الق نظرة على المثال التالي:

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'hidden=yes');
// ...بعد برهة من الزمن
ref.show();‎

InAppBrowser.hide

يُخفي هذا التابع نافذة InAppBrowser. استدعاء هذا التابع ليس له أي تأثير إن كانت نافذة InAppBrowser مخفيًةً مسبقًا.

ref.hide();‎

المتغير ref يُشير إلى نافذة InAppBrowser.

المنصات المدعومة هي:

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

إليك المثال التالي:

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank');
// ...بعد بُرهة
ref.hide();‎

InAppBrowser.executeScript

يحقن (Injects) هذا التابع شيفرة JavaScript في نافذة InAppBrowser. (متاح فقط عند ضبط الخيار target عند القيمة '‎_blank').

ref.executeScript(details, callback);‎

المعاملات المُمرَّرة إلى هذا التابع هي:

• ref: يشير إلى نافذة InAppBrowser.‏

• injectDetails: كائن يمثل تفاصيل البرنامج النصي المراد تنفيذه، مع تحديد أحد المفتاحين file أو code.
  • file: عنوان النص المراد حقنُه.
  • code: نص الشيفرة البرمجية المراد حقنُها.
• callback: دالة رد النداء التي ستُنفّذ بعد حقن شيفرة JavaScript.
  • إن كان البرنامج النصي المحقون من النوع code، فسُينفّذ رد النداء (callback) مع إعطائه معاملًا واحدًا، والذي يساوي القيمة التي يُعيدها البرنامج النصي مُغلّفةً في مصفوفةٍ (Array). بالنسبة للنصوص النصية متعددة الأسطر، فالقيمة ستساوي قيمة آخر تعليمة (statement)، أو آخر تعبير (expression) مُقيّمٍ.

المنصات المدعومة هي:

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

إليك مثال عن استعمال التابع executeScript:

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstop', function() {
    ref.executeScript({file: "myscript.js"});
});‎

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

• لا تدعم هذه المنصة إلا المفتاح code.

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

بحسَب توثيق MSDN، لا يمكن للبرنامج النصي المستدعى أن يُعيد إلا قيمًا نصيةً، وإلا فإنّ المعامل الذي سيُمرّر إلى رد النداء callback سيساوي [null].

InAppBrowser.insertCSS

يحقن هذا التابع شيفرة CSS في نافذة InAppBrowser (متاح فقط عند ضبط الخيار target عند القيمة '‎_blank').

ref.insertCSS(details, callback);‎

المتغير ref يُشير إلى نافذة InAppBrowser.

• injectDetails: كائن يمثِّل تفاصيل البرنامج النصي المُراد تشغيله، مع تحديد أحد المفتاحين file أو code.
  • file: عنوان شيفرة الأنماط المراد حقنها.
  • code: محتوى شيفرة الأنماط المُراد حقنها.
• callback: الدالة التي ستُنفذ بعد حقن شيفرة CSS.

المنصات المدعومة هي:

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

توضح الشيفرة التالية كيفية استعمال التابع insertCSS:

var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstop', function() {
    ref.insertCSS({file: "mystyles.css"});
});‎

مثال توضيحي

يمكنك استخدام هذه الإضافة لعرض صفحات توثيقٍ في تطبيقك. بحيث يمكن للمستخدمين عرض وثائق المساعدة عبر الإنترنت ثمَّ إغلاقها دون مغادرة التطبيق.

في هذه الفقرة تجد بعض المقتطفات البرمجية التي توضح كيفية القيام بذلك.

منح المستخدمين طريقة لطلب المساعدة

هناك الكثير من الطرق لفعل هذا. وتُعد القوائم المنسدلة من أبسطها.

<select id="help-select">
    <option value="default">Need help?</option>
    <option value="article">Show me a helpful article</option>
    <option value="video">Show me a helpful video</option>
    <option value="search">Search for other topics</option>
</select>‎

قم بتجميع اختيارات المستخدمين في دالة الصفحة onDeviceReady، ثم أرسل عنوانًا (URL) مناسبًا لدالة المساعدة (helper function) في أحد ملفات المكتبة المشتركة. اسم دالة المساعدة في هذا المثال هو showHelp()‎، والتي سنعرّفها في الفقرة التالية.

$('#help-select').on('change', function (e) {

    var url;

    switch (this.value) {

        case "article":
            url = "https://cordova.apache.org/docs/en/latest/"
                        + "reference/cordova-plugin-inappbrowser/index.html";
            break;

        case "video":
            url = "https://youtu.be/F-GlVrTaeH0";
            break;

        case "search":
            url = "https://www.google.com/#q=inAppBrowser+plugin";
            break;
    }

    showHelp(url);

});

تحميل صفحة المساعدة

سنستخدم الدالة open لتحميل صفحة المساعدة. وسنضبط الخاصية hidden إلى القيمة yes، لكي نحرص على أن يُعرَض المتصفح بعد تحميل محتوى الصفحة. فبهذه الطريقة، لن يرى المستخدمون متصفحًا فارغًا أثناء انتظار ظهور المحتوى. عندما يُطلق الحدث loadstop، سنعرف متى تم تحميل المحتوى (سنتعامل مع هذا الحدث بعد قليل).

function showHelp(url) {

    var target = "_blank";

    var options = "location=yes,hidden=yes";

    inAppBrowserRef = cordova.InAppBrowser.open(url, target, options);

    inAppBrowserRef.addEventListener('loadstart', loadStartCallBack);

    inAppBrowserRef.addEventListener('loadstop', loadStopCallBack);

    inAppBrowserRef.addEventListener('loaderror', loadErrorCallBack);

}

إعلام المستخدمين بجاهزية صفحتهم

لا يظهر المتصفح على الفور، لذلك سنستخدم الحدث loadstart لعرض رسالة الحالة (status message)، أو شريط التقدم (progress bar)، أو أي مؤشرٍ آخر. هذا يؤكد للمستخدمين أن المحتوى في خضمِّ التحميل.

function loadStartCallBack() {
    $('#status-message').text("loading please wait ...");
}‎

عرض صفحة المساعدة

عندما يُطلق الحدث loadstopcallback، نعلم أن المحتوى قد حُمِّل، وحينها يمكننا إظهار المتصفح. هذه الحيلة ستخلق انطباعًا لدى المستخدم بسرعة التحميل. والحقيقة هي أنه، سواء أعرضت المتصفح قبل تحميل المحتوى أم لا، فإنّ وقت التحميل لن يتغير.

function loadStopCallBack() {

    if (inAppBrowserRef != undefined) {

        inAppBrowserRef.insertCSS({ code: "body{font-size: 25px;" });

        $('#status-message').text("");

        inAppBrowserRef.show();
    }

}

ربما لاحظت استدعاء الدالة insertCSS. هذا لا يخدم أي غرض معين في مثالنا هذا. ولكنه يعطيك فكرة عن كيفية استخدامها. في هذه الحالة، سنتأكد فقط من أنّ حجم خط صفحاتك يساوي قيمة معينة. يمكنك استخدام هذه الدالة لإدراج أنماط CSS التي تريد. ويمكنك حتى الإشارة إلى ملف CSS في مشروعك.

معالجة أخطاء الصفحة

في بعض الأحيان، لا تكون الصفحة المراد تحميلها مُتاحةً، أو قد يكون هناك خطأ في البرنامج النصي، أو قد لا يملك المستخدم إذن الدخول إلى موردٍ ما. التعامل مع هذه الأوضاع، وطريقة ذلك متروكة لك ولتصميمك. يمكنك ترك المتصفح يعرض رسالة خطأ، أو يمكنك عرضها بطريقة أخرى.

سنحاول إظهار الخطأ في مربعٍ يعرض رسالة. يمكننا القيام بذلك عن طريق حقن برنامج نصي يستدعي الدالة alert. المشكلة في هذا أنه لن يعمل على متصفحات ويندوز، لذا سيتعين علينا التحقق من قيمة معامل دالة رد النداء executeScript لمعرفة ما إذا كانت المحاولة ناجحة. إذا لم ينجح الأمر، فسنكتفي بعرض رسالة الخطأ في وسم <div> داخل الصفحة:

function loadErrorCallBack(params) {

    $('#status-message').text("");

    var scriptErrorMesssage =
       "alert('Sorry we cannot open that page. Message from the server is : "
       + params.message + "');"

    inAppBrowserRef.executeScript({ code: scriptErrorMesssage }, executeScriptCallBack);

    inAppBrowserRef.close();

    inAppBrowserRef = undefined;

}

function executeScriptCallBack(params) {

    if (params[0] == null) {

        $('#status-message').text(
           "Sorry we couldn't open that page. Message from the server is : '"
           + params.message + "'");
    }

}

معلومات استخدام إضافية

العناوين المحلية (المصدر في حزمة التطبيق)

var iab = cordova.InAppBrowser;
iab.open('local-url.html');                  // يُحمّل في عارض كوردوفا
iab.open('local-url.html', '_self');         // يُحمّل في عارض كوردوفا
iab.open('local-url.html', '_system');       // خطأ أمني: متصفح النظام 
                                             // (iOS) ولكن لن يُحمّل العنوان 
iab.open('local-url.html', '_blank');        // InAppBrowser يُحمّل في 
iab.open('local-url.html', 'random_string'); // InAppBrowser يُحمّل في
iab.open('local-url.html', 'random_string', 'location=no'); //  InAppBrowser يُحمّل في
                                                            // دون عرض شريط التصفح

محتوى مُدرج في اللائحة البيضاء

var iab = cordova.InAppBrowser;
iab.open('http://whitelisted-url.com');                  // يُحمّل في عارض كوردوفا
iab.open('http://whitelisted-url.com', '_self');         // يُحمّل في عارض كوردوفا
iab.open('http://whitelisted-url.com', '_system');       // يُحمّل في متصفح النظام
iab.open('http://whitelisted-url.com', '_blank');        // InAppBrowser يُحمّل في
iab.open('http://whitelisted-url.com', 'random_string'); // InAppBrowser يُحمّل في
iab.open('http://whitelisted-url.com', 'random_string', 'location=no'); // يُحمّل في 
                                                 // دون عرض شريط التصفح InAppBrowser

العناوين غير المُدرجة في اللائحة البيضاء

var iab = cordova.InAppBrowser;
iab.open('http://url-that-fails-whitelist.com');              // InAppBrowser يُحمّل في
iab.open('http://url-that-fails-whitelist.com', '_self');      //InAppBrowser يُحمّل في 
iab.open('http://url-that-fails-whitelist.com', '_system');  // يُحمل في متصفح النظام
iab.open('http://url-that-fails-whitelist.com', '_blank');   // InAppBrowser يُحمّل في
iab.open('http://url-that-fails-whitelist.com', 'random_string'); // InAppBrowser يُحمّل في
iab.open('http://url-that-fails-whitelist.com', 'random_string', 'location=no'); 
// دون عرض شريط التصفح InAppBrowser يُحمّل في

انظر أيضًا

• إضافة حالة الجهاز
• إضافة تحديد الموقع الجغرافي

• إضافة الوصول إلى الملفات

• دليل تطوير الإضافات في كوردوفا

مصادر

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