عرض مصدر Cordova/cordova plugin inappbrowser

<noinclude>{{DISPLAYTITLE:إضافة المتصفح الداخلي في كوردوفا}}</noinclude>
[[تصنيف: Cordova]]
تساعد إضافة المتصفح الداخلي (<code>cordova-plugin-inappbrowser</code>) 
[[تصنيف: Plugin]]
على عرض المقالات ومقاطع الفيديو وموارد الويب المفيدة داخل تطبيقك. كما تمُكن المستخدمين من الاطلاع على صفحات الويب دون مغادرة تطبيقك. 

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

توفر هذه الإضافة مُتصفحا يمكن عرضه عند استدعاء التابع <code>cordova.InAppBrowser.open()‎</code>. 
<syntaxhighlight lang="javascript">var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');‎</syntaxhighlight> 

لقد تم تعريف التابع<code>cordova.InAppBrowser.open()‎</code> ليكون بديلًا للدالة <code>window.open()‎</code>. يمكن لاستدعاءات الدالة <code>window.open()</code> ‎الحالية أن تسنخدم نافذةَ <code>InAppBrowser</code>، عن طريق استبدال <code>window.open</code>، كما هو موضح في المثال التالي: 
<syntaxhighlight lang="javascript">window.open = cordova.InAppBrowser.open;‎</syntaxhighlight> 

تتصرف النافذة <code>InAppBrowser</code> كمتصفح عادي، ولا يمكنها الوصول إلى الواجهات البرمجية لكوردوفا. لهذا السبب، يُنصح باستخدام <code>InAppBrowser</code> إذا احتجت إلى تحميل محتوى خارجي (غير موثوق به)، بدلاً من تحميله في [[Cordova/webviews|عارض]] كوردوفا الرئيسي. <code>InAppBrowser</code> ليس معنيًا [[Cordova/whitelist|باللوائح البيضاء]]، ولا يفتح روابط في متصفح النظام. 

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

للتوافق مع الإصدارات القديمة، تنشُبُ (hooks) هذه الإضافة أيضًا الدالةَ <code>window.open</code>. ومع ذلك، يمكن أن يكون [[Cordova/hooks|لخُطّاف]] <code>window.open</code> الذي تنشُبه الإضافة تأثيرات جانبية غير مقصودة (خاصة إذا تم تضمين هذه الإضافة كارتباط لإضافة أخرى). سيُزال [[Cordova/hooks|خطاف]] <code>window.open</code> في إصدار رئيسي مستقبلًا. إلى حين إزالة الخطاف من الإضافة، يمكن للتطبيقات استعادة السلوك الافتراضي يدويًا: 
<syntaxhighlight lang="javascript">delete window.open // إعادة رد النداء إلى وضعه الافتراضي</syntaxhighlight> 

على الرغم من أن <code>window.open</code> موجودٌ في النطاق العام، إلا أنّ الكائن <code>InAppBrowser</code> لن يكون متوفرًا إلا بعد إطلاق الحدث <code>[[Cordova/events#deviceready|deviceready]]</code>. 
<syntaxhighlight lang="javascript">document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    console.log("window.open works well");
}‎</syntaxhighlight> 

==التثبيت==
<syntaxhighlight lang="shell">cordova plugin add cordova-plugin-inappbrowser‎</syntaxhighlight> 

ان كنت تريد أن تُعرض جميع الصفحات المُحملة في تطبيقك في InAppBrowser، فيمكنك ببساطة أن تنشُب في [[Cordova/hooks|الخطاف]] <code>window.open</code> أثناء التهيئة. مثلا: 
<syntaxhighlight lang="javascript">document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    window.open = cordova.InAppBrowser.open;
}‎</syntaxhighlight> 

== قرطبة.InAppBrowser.open== 

يفتح هذا التابع عنوان URL في نسخة جديدة (instance) من <code>InAppBrowser</code>، أو في نسخة من المتصفح الحالي، أو متصفح النظام. 
<syntaxhighlight lang="javascript">var ref = cordova.InAppBrowser.open(url, target, options);‎</syntaxhighlight> 
* '''ref''': يشير إلى النافذة <code>InAppBrowser</code> عندمت يُضبط المعامل target عند القيمة <code>'_blank'</code>. (InAppBrowser) 
* '''url''': العنوان المراد تحميله (سلسلة نصية). استدع على هذا المعامل الدالةَ <code>encodeURI()</code> إن كان العنوان URL يحتوي على أحرف اليونيكود. 
* '''target''': يحدد المكان الذي سيُحمّل فيه عنوان URL، وهو معامل اختياري، قيمته الافتراضية تساوي <code>_self</code>. (سلسلة نصية) 
* <code>_self</code>: يُفتح العنوان في [[Cordova/webviews|عارض]] كوردوفا إن كان موجودًا في اللائحة البيضاء، وإلا فسيُفتح في <code>InAppBrowser</code>. 
* <code>_blank</code>: يُفتح في <code>InAppBrowser</code>. 
* <code>_system</code>: يفتح في متصفح النظام. 
* '''options''': خيارات للنافذة <code>InAppBrowser</code>. اختياري، قيمته الافتراضية تساوي <code>location=yes</code>. (سلسلة نصية) 

يجب ألا تحتوي السلسلة النصية <code>options</code> على أية مسافة فارغة، ويجب أن تُفصل أزواج الميزات name/value بفاصلة. أسماء الميزات غير حساسة لحالة الأحرف. 

جميع المنصات تدعم: 
* '''location''': اضبط هذه الخاصية إلى القيمة <code>yes</code> أو <code>no</code> لإظهار شريط الموقع في <code>InAppBrowser</code> أو إخفائه. 

يدعم أندرويد هذه الخيارات الإضافية: 
* '''hidden''': اضبطه هذا الخيار إلى القيمة <code>yes</code> لإنشاء المتصفح وتحميل الصفحة، بدون إظهاره. يُطلق الحدث loadstop عند اكتمال التحميل. احذف هذا الخيار أو اضبطه عند القيمة <code>no</code> (افتراضية) لفتح المتصفح وتحميل الصفحة بشكل طبيعي. 
* '''clearcache''': اضبط هذا الخيار عند القيمة <code>yes</code> لمحو ذاكرة التخزين المؤقت لملف تعريف الارتباط () في المتصفح قبل فتح النافذة الجديدة 
* '''clearsessioncache''': اضبط هذا الخيار عند القيمة <code>yes</code> لمحو ذاكرة التخزين المؤقت لملف تعريف الارتباط (cookie) قبل فتح النافذة الجديدة 
* '''closebuttoncaption''': اعط لهذا الخيار سلسلةً نصيةً لاستخدامها كتسميةٍ للزر بدلًا من الحرف X. تذطر أنه سيكون عليك ترجمة هذه القيمة بنفسك. 
* '''closebuttoncolor''': اعط لهذا الخيار سلسلةً نصية تمثل قيمة لونية سداسي عشرية (hex color) صالحة، مثل: <code>#00ff00</code>، وسيتغيّر لون زر الإغلاق من اللون الافتراضي، سواءً كان نصًا، أو الحرف الافتراضيً X. لا يكون لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن قيمة الموقع (location) إلى <code>yes</code>. 
* '''footer''': اضبط هذا الخيار عند القيمة <code>yes</code> لإظهار زر لإغلاق في أسفل النافذة، بشكل مماثلٍ للزر '''Done''' في iOS. سيظهر زر الإغلاق في رأس النافذة، ومن ثم استخدم '''closebuttoncaption''' و '''closebuttoncolor''' لتعيين خصائصه. 
* '''footercolor''': اعط لهذا الخيار سلسلة نصية تمثل لونًا سداسي عشريًا (hex color) صالحًا، مثل <code>#00ff00</code> أو <code>#CC00ff00</code> (<code>#aarrggbb</code>)، وسيتغيّر لون تذييل النافذة عن اللون الافتراضي. ليس لهذا الخيار تأثيرٌ إلا إن عيّن المُستخدم '''footer''' إلى القيمة <code>yes</code>. 
* '''hardwareback''': اضبط هذا الخيار عند القيمة <code>yes</code> لاستخدام زر الرجوع الخاص بالجهاز للرجوع للخلف خلال تاريخ النافذة <code>InAppBrowser</code>. إذا لم تكن هناك صفحات سابقة، فسيتم إغلاق <code>InAppBrowser</code>. القيمة الافتراضية هي <code>yes</code>، لذا يجب تعيينها إلى القيمة <code>no</code> إن كنت تريد أن تجعل زر الرجوع يغلق InAppBrowser. 
* '''hidenavigationbuttons''': اضبط هذا الخيار عند القيمة <code>yes</code> لإخفاء أزرار التنقل على شريط الأدوات، ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الموقع (location) عند القيمة <code>yes</code>. القيمة الافتراضية هي <code>no</code>. 
* '''hideurlbar''': اضبط هذا الخيار عند القيمة <code>yes</code> لإخفاء شريط العنوان من شريط أدوات الموقع، ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الموقع (location) عند القيمة <code>yes</code>. القيمة الافتراضية هي <code>no</code>. 
* '''navigationbuttoncolor''': اعط لهذا الخيار سلسلة نصية تمثل لونًا سداسي عشريًا (hex color) صالحًا، مثل: <code>#00ff00</code>، وسيغير لون أزرار التنقل عن اللون الافتراضي. ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الموقع (location) عند القيمة <code>yes</code>، ولم تُعيّن hidenavigationbuttons عند القيمة <code>yes</code>. 
* '''toolbarcolor''': اعط لهذا الخيار سلسلة نصية تمثل لونًا سداسي عشريًا (hex color) صالحًا، مثل: <code>#00ff00</code>، وسيغير لون شريط الأدوات من اللون الافتراضي. يكون له تأثير فقط إذا تم تعيين موقع (location) المستخدم عند القيمة <code>yes</code>. 
* '''zoom''': اضبط هذا الخيار عند القيمة <code>yes</code> لعرض عناصر التحكم في الحجم في متصفح أندرويد، أو اضبطه عند القيمة <code>no</code> إن أردت إخفاءها. القيمة الافتراضية هي <code>yes</code>. 
* '''mediaPlaybackRequiresUserAction''': اضبط هذا الخيار عند القيمة <code>yes</code> لمنع صوتيات أو فيديوها HTML5 من التشغيل التلقائي (القيمة الافتراضية هي <code>no</code>). 
* '''shouldPauseOnSuspend''': اضبط هذا الخيار عند القيمة <code>yes</code> لجعل [[Cordova/webviews|عارض]] InAppBrowser يتوقف أو يستأنف مع التطبيق، لإيقاف صوت الخلفية (قد يكون هذا ضروريًا لتجنب المشكلات التي تخص Google Play كما هو موضح في [https://issues.apache.org/jira/browse/CB-11013 CB-11013]). 
* '''useWideViewPort''': يحدد هذا الخيار ما إذا كان [[Cordova/webviews|العارض]] يجب أن يدعم الوسم الوصفي "viewport" الخاص بـ HTML، أو يجب أن يستخدم معرضًا (viewport) واسعًا. عندما يُعطى هذا الإعداد القيمة <code>no</code>، سيُعيّن عرض المخطط (layout) إلى قيمة عرض [[Cordova/webviews|العارض]] بوحدة البكسل المستقلة عن الجهاز (CSS). إما إن أُعطي هذا الإعداد القيمة <code>yes</code>، وكانت الصفحة تحتوي الوسم الوصفي viewport، فستُستخدم قيمة العرض المحددة في الوسم. إن لم تحتوِ الصفحة على الوسم، أو لم تحدد قيمةً للعرض، فسيُستخدام [[Cordova/webviews|عارض]] واسعٌ. (القيمة الافتراضية هي <code>yes</code>). 

تدعم منصة iOS الخيارات الإضافية التالية: 
* '''hidden''': اضبط هذا الخيار عند القيمة <code>yes</code> لإنشاء المتصفح وتحميل الصفحة، ولكن دون إظهارها. سيُطلق الحدث loadstop عند اكتمال التحميل. احذف هذا الخيار أو اضبطه عند القيمة <code>no</code> (الافتراضية) لفتح المتصفح وتحميله بشكل طبيعي. 
* '''clearcache''': اضبط هذا الخيار عند القيمة <code>yes</code> لمحو ذاكرة التخزين المؤقت لملف تعريف الارتباط (cookie cache) للمتصفح قبل فتح النافذة الجديدة 
* '''clearsessioncache''': اضبط هذا الخيار عند القيمة <code>yes</code> لمحو ذاكرة التخزين المؤقت لملف تعريف الارتباط (cookie) قبل فتح النافذة الجديدة 
* '''closebuttoncolor''': اعط لهذا الخيار سلسلةً نصيةً تمثل لونًا سداس عشريًا (hex color) صالحًا، مثل: <code>#00ff00</code>، لتغيير لون الزر '''Done''' الافتراضي. لا يُطبق هذا الإعداد إلا عند تفعيل شريط الأدوات. 
* '''closebuttoncaption''': اعط هذا الخيار سلسلةً نصيةً لاستخدامها كتسميةِ للزر '''Done'''. تذكر أن عليك مراعاة الإعدادات اللغوية المحلية بنفسك. 
* '''disallowoverscroll''': يُضبط هذا الخيار عند القيمة <code>yes</code> أو <code>no</code> (الإعداد الافتراضي هو <code>no</code>). لتشغيل أو إيقاف الخاصية UIWebViewBounce. 
* '''hidenavigationbuttons''': اضبط هذا الخيار عند القيمة <code>yes</code> أو <code>no</code> لتشغيل أزرار التنقل (navigation buttons) في شريط الأدوات أو تعطيلها(الإعداد الافتراضي هوظ <code>no</code>). لا يُطبّق هذا الخيار إلا عند تفعيل شريط الأدوات. 
* '''navigationbuttoncolor''': اعط لهذا الخيار سلسلةًً نصيةًً تمثل لونًا سداس عشريًا (hex color) صالحًا، مثل: <code>#00ff00</code>، لتغيير اللون الافتراضي. لا يُطبّق هذا الخيار إلا إذا عند إظهار أزرار التنقل. 
* '''toolbar''': اعط لهذا الخيار <code>yes</code> أو <code>no</code> لتشغيل شريط الأدوات أو تعطيله في InAppBrowser (الإعداد الافتراضي هو <code>yes</code>) 
* '''toolbarcolor''': اعط لهذا الخيار سلسلةً نصيةً تمثل لونًا سداس عشريًا (hex color) صالحًا، مثل: <code>#00ff00</code>، لتغيير اللون الافتراضي لشريط الأدوات. لا يُطبّق هذا الخيار إلا عند تفعيل شريط الأدوات. 
* '''toolbartranslucent''': اعط لهذا الخيار <code>yes</code> أو <code>no</code> لجعل شريط الأدوات شبه شفاف (translucent) (القيمة الافتراضية هي <code>yes</code>). لا يُطبّق هذا الخيار إلا عند تفعيل شريط الأدوات. 
* '''enableViewportScale''': اضبط هذا الخيار عند القيمة <code>yes</code> أو <code>no</code> لمنع تعديل حجم إطار العرض (viewport) عبر وسم وصفي (القيمة الافتراضية هي <code>no</code>). 
* '''mediaPlaybackRequiresUserAction''': اضبط هذا الخيار عند القيمة <code>yes</code> لمنع صوتيات أو فيديوهات HTML5 من التشغيل التلقائي (القيمة الافتراضية هي <code>no</code>). 
* '''allowInlineMediaPlayback''': اضبط هذا الخيار عند القيمة <code>yes</code> أو <code>no</code> للسماح بتشغيل وسائط HTML5 المُدرجة على السطر (in-line)، وعرضها في نافذة المتصفح بدلاً من واجهة تشغيلٍ خاصةٍ بالجهاز. يجب أن يشتمل عنصر <code>video</code> في HTML على الخاصية <code>webkit-playsinline</code> (القيمة الافتراضية هي <code>no</code>) 
* '''keyboardDisplayRequiresUserAction''': اضبط هذا الخيار عند القيمة <code>yes</code> أو <code>no</code> لفتح لوحة المفاتيح عندما تتلقى عناصر النموذج (form) التركيز (focus) عبر استدعاء دالة [[JavaScript|جافااسكريبت]] <code>focus()</code> (القيمة الافتراضية هي <code>yes</code>). 
* '''suppressesIncrementalRendering''': اضبط هذا الخيار عند القيمة <code>yes</code> أو <code>no</code> للانتظار حتى يتم استلام كل محتوى إطار العرض الجديد قبل عرضه (القيمة الافتراضية هي <code>no</code>). 
* '''presentationstyle''': اعط لهذا الخيار القيمة <code>pagesheet</code> أو <code>formsheet</code> أو <code>fullscreen</code> لتعيين [http://developer.apple.com/library/ios/documentation/UIKit/Reference/UIViewController_Class/Reference/Reference.html#//apple_ref/occ/instp/UIViewController/modalPresentationStyle presentation style] (القيمة الافتراضية هي <code>fullscreen</code>). 
* '''transitionstyle''': اعط لهذا الخيار <code>fliphorizontal</code> أو <code>crossdissolve</code> أو <code>coververtical</code> لتعيين [http://developer.apple.com/library/ios/#documentation/UIKit/Reference/UIViewController_Class/Reference/Reference.html#//apple_ref/occ/instp/UIViewController/modalTransitionStyle transition style] (القيمة الافتراضية هي <code>coververtical</code>). 
* '''toolbarposition''': اضبط هذا الخيار عند القيمة <code>top</code> أو <code>bottom</code> (الإعداد الافتراضي هو <code>bottom</code>). لجعل شريط الأدوات في أعلى النافذة أو أسفلها. 
* '''hidespinner''': اضبط هذا الخيار عند القيمة <code>yes</code> أو <code>no</code> لتغيير مستوى رؤية (visibility) مؤشر التحميل (القيمة الافتراضية هي <code>no</code>). 

تدعم منصة ويندوز الخيارات الإضافية التالية: 
* '''hidden''': اضبط هذا الخيار عند القيمة <code>yes</code> لإنشاء المتصفح وتحميل الصفحة، دون إظهاره. يُطلق الحدث loadstop عند اكتمال التحميل. احذف هذا الخيار أو اضبطه عند القيمة <code>no</code> (الافتراضية) لفتح المتصفح وتحميله بشكل طبيعي. 
* '''hardwareback''': يعمل هذا الخيار بطريقة مشابهة لمنصة أندرويد. 
* '''fullscreen''': اضبط هذا الخيار عند القيمة <code>yes</code> لإنشاء مركبة المتصفح بدون إحاطته بحدود. يرجى ملاحظة أنه إذا تم تحديد '''location=no''' أيضًا، فلن يُقدّم للمستخدم أي مُركّبةٍ (control) لإغلاق نافذة IAB. 
=== المنصات المدعومة === 
*أندرويد 
*Browser 
*iOS 
* OSX 
*ويندوز 
=== مثال === 
<syntaxhighlight lang="javascript">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');‎</syntaxhighlight> 
=== ملاحظات خاصة بمنصة OSX === 

في الوقت الحالي، الهدف (target) الوحيد المدعوم في OSX هو <code>_system</code>. 

لم يتم بعدُ تقديم الهدفين <code>_blank</code> و <code>_self</code>، وسيُتجاهلان بصمت. هي موضع تقدير كبير طلبات سحب والتصحيحات للحصول على هذه للعمل. 
=== ملاحظات خاصة بالمتصفحات (Browsers) === 
* هذه الإضافة مُقدّمة عبر الإطار الذكي iframe، 
* لم يتم تقديم تاريخ التصفح بعدُ (الزِّران <code>back</code> و <code>forward</code> في شريط التصفح LocationBar). 

==InAppBrowser== 

الكائن المُعاد من استدعاء التابع <code>cordova.InAppBrowser.open</code> عند تعيين الهدف target إلى القيمة <code>'_blank'</code>. 
=== التوابع === 
* addEventListener 
* removeEventListener 
*close 
*show 
*hide 
* executeScript 
* insertCSS 

==InAppBrowser.addEventListener== 
يضيف هذا التابع مُنصتًا (listener) لحدثٍ من <code>InAppBrowser</code>. (متاح فقط عند ضبط الهدف عند القيمة <code>'_blank'</code>) 
<syntaxhighlight lang="javascript">ref.addEventListener(eventname, callback);‎</syntaxhighlight> 
* '''ref''': يُشير إلى نافذة <code>InAppBrowser</code> ‏(‎InAppBrowser) 
* '''eventname''': الحدث المُراد الإنصات إليه (سلسلة نصية) 
* '''loadstart''': يُطلق هذا الحدث عندما يبدأ <code>InAppBrowser</code> في تحميل عنوان URL. 
* '''loadstop''': يُطلق هذا الحدث عند انتهاء <code>InAppBrowser</code> من تحميل عنوان URL. 
* '''loaderror''': يُطلق هذا الحدث عندما يواجه <code>InAppBrowser</code> خطأً أثناء تحميل عنوان URL. 
* '''exit''': يُطلق هذا الحدث عند إغلاق نافذة <code>InAppBrowser</code>. 
* '''callback''': الدالة التي ستنفذ عند إطلاق الحدث. يُمرّر إلى هذه الدالة كائن <code>InAppBrowserEvent</code> كمعاملٍ. 

== مثال == 
<syntaxhighlight lang="javascript">var inAppBrowserRef;
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);
}
function loadStartCallBack() {
    $('#status-message').text("loading please wait ...");
}
function loadStopCallBack() {
    if (inAppBrowserRef != undefined) {
        inAppBrowserRef.insertCSS({ code: "body{font-size: 25px;" });
        $('#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 + "'");
    }
}‎</syntaxhighlight> 
=== خاصيات InAppBrowserEvent === 
* '''type''': اسم الحدث، والذي يساوي إمّا <code>loadstart</code> أو <code>loadstop</code> أو <code>loaderror</code> أو <code>exit</code>. ((سلسلة نصية) 
* '''url''': العنوان الذي تم تحميله. (سلسلة نصية) 
* '''code''': رمز الخطأ، لا تكون هذه الخاصية مُتاحةً إلا في حال إطلاق الحدث <code>loaderror</code>. ((عدد) 
* '''message''': رسالة الخطأ، لا تكون هذه الخاصية مُتاحةً إلا في حال إطلاق الحدث <code>loaderror</code>. (سلسلة نصية) 
=== المنصات المدعومة === 
*أندرويد 
*Browser 
*iOS 
*ويندوز 
* OSX 
=== ملاحظات خاصة بالمتصفحات (Browsers) === 

في هذه المنصات، لا يُطلق الحدثان <code>loadstart</code> و <code>loaderror</code>. 
=== مثال سريع === 
<syntaxhighlight lang="javascript">var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstart', function(event) { alert(event.url); });‎</syntaxhighlight> 

==InAppBrowser.removeEventListener== 
يزيل هذا التابع مُنصِتا لحدثٍ من <code>InAppBrowser</code>. (متاح فقط عند ضبط الهدف عند القيمة <code>'_blank'</code>) 
<syntaxhighlight lang="javascript">ref.removeEventListener(eventname, callback);‎</syntaxhighlight> 
* '''ref''': تُشير إلى النافذة <code>InAppBrowser</code>. (InAppBrowser) 
* '''eventname''': الحدث المُراد التوقف عن الإنصات له. (سلسلة نصية) 
* '''loadstart''': يُطلق هذا الحدث عندما يبدأ <code>InAppBrowser</code> في تحميل عنوان URL. 
* '''loadstop''': يُطلق هذا الحدث عند انتهاء <code>InAppBrowser</code> من تحميل عنوان URL. 
* '''loaderror''': يُطلق هذا الحدث عندما يواجه <code>InAppBrowser</code> خطأ أثناء تحميل عنوان URL. 
* '''exit''': يُطلق هذا الحدث عند إغلاق نافذةِ <code>InAppBrowser</code>. 
* '''callback''': الدالة التي سيتم تنفيذها عند إطلاق الحدث. يُمرّر إلى هذه الدالة كائنٌ <code>InAppBrowserEvent</code>. 
=== المنصات المدعومة === 
*أندرويد 
*Browser 
*iOS 
*ويندوز 
=== مثال سريع === 
<syntaxhighlight lang="javascript">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);‎</syntaxhighlight> 

==InAppBrowser.close== 
يغلق هذا التابع نافذة <code>InAppBrowser</code>. 
<syntaxhighlight lang="javascript">ref.close();‎</syntaxhighlight> 
* '''ref''': تشيرُ إلى نافذة <code>InAppBrowser</code> ‏(InAppBrowser) 
=== المنصات المدعومة === 
*أندرويد 
*Browser 
*iOS 
*ويندوز 
=== مثال سريع === 
<syntaxhighlight lang="javascript">var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.close();‎</syntaxhighlight> 

==InAppBrowser.show== 
يظهر هذا التابع نافذة InAppBrowser فُتِحت مخفية. استدعاء هذا التابع لن يكون له أي تأثير إن كان InAppBrowser مرئيًا بالفعل. 
<syntaxhighlight lang="javascript">ref.show();‎</syntaxhighlight> 
* '''ref''': يُشير إلى نافذة InAppBrowser ‏(<code>InAppBrowser</code>) 
=== المنصات المدعومة === 
*أندرويد 
*Browser 
*iOS 
*ويندوز 
=== مثال سريع === 
<syntaxhighlight lang="javascript">var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'hidden=yes');
// some time later...
ref.show();‎</syntaxhighlight> 

==InAppBrowser.hide== 
يُخفي هذا التابع نافذة InAppBrowser. استدعاء هذا التابع ليس له أي تأثير إن كان InAppBrowser مخفيًا مسبقاً. 
<syntaxhighlight lang="javascript">ref.hide();‎</syntaxhighlight> 
* '''ref''': يُشير إلى نافذة InAppBrowser ‏(<code>InAppBrowser</code>) 
=== المنصات المدعومة === 
*أندرويد 
*iOS 
*ويندوز 
=== مثال سريع === 
<syntaxhighlight lang="javascript">var ref = cordova.InAppBrowser.open('http://apache.org', '_blank');
// some time later...
ref.hide();‎</syntaxhighlight> 

==InAppBrowser.executeScript== 
يحقن (Injects) هذا التابع شيفرة [[JavaScript|جافااسكريبت]] في نافذة <code>InAppBrowser</code>. (متاح فقط عند ضبط الهدف [target] عند القيمة <code>'_blank'</code>) 
<syntaxhighlight lang="javascript">ref.executeScript(details, callback);‎</syntaxhighlight> 
* '''ref''': يُشير إلى النافذةة <code>InAppBrowser</code>. (InAppBrowser) 
* '''injectDetails''': تفاصيل البرنامج النصي المراد تنفيذه، مع تحديد إما المفتاح <code>file</code> أو <code>code</code>. (كائن) 
* '''file''': عنوان النص المراد حقنُه. 
* '''code''': نص الشيفرة البرمجية المراد حقنُها. 
* '''callback''': الدالة التي سُتنفّذ بعد حقن شيفرة [[JavaScript|جافااسكريبت]]. 
* إن كان البرنامج النصي المحقون من النوع <code>code</code>، فسُينفّذ رد النداء مع إعطائه معاملًا واحدًا، والذي هو القيمة التي يُعيدها البرنامج النصي، مُغلّفةً في مصفوفة (<code>Array</code>). بالنسبة للنصوص النصية متعددة الأسطر، فالقيمة ستكون هي قيمة آخر تعبير (statement)، أو آخر تعبير مُقيّمٍ. 
=== المنصات المدعومة === 
*أندرويد 
*Browser 
*iOS 
*ويندوز 
=== مثال سريع === 
<syntaxhighlight lang="javascript">var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstop', function() {
    ref.executeScript({file: "myscript.js"});
});‎</syntaxhighlight> 
=== ملاحظات خاصة بالمتصفحات (Browsers) === 
* لا تدعم هذه المنصة إلا المفتاح '''code'''. 
=== ملاحظات خاصة بمنصة ويندوز === 

رجوعًا إلى [https://msdn.microsoft.com/en-us/library/windows.ui.xaml.controls.webview.invokescriptasync.aspx MSDN docs]، لا يمكن للبرنامج النصي المستدعي أن يُعيد إلا القيم النصية فقط، وإلا فإن المعامل الذي سيُمرّر إلى '''callback''' سيساوي <code>[null]</code>. 

==InAppBrowser.insertCSS== 
يحقن هذا التابع أنماط CSS في نافذة <code>InAppBrowser</code>. (متاح فقط عند ضبط الهدف (target) عند القيمة <code>'_blank'</code>) 
<syntaxhighlight lang="javascript">ref.insertCSS(details, callback);‎</syntaxhighlight> 
* '''ref''': يُشير إلى نافذة <code>InAppBrowser</code> ‏(InAppBrowser) 
* '''injectDetails''': تفاصيل البرنامج النصي المُراد تشغيله، مع تحديد إما المفتاح <code>file</code> أو <code>code</code>. (كائن) 
* '''file''': عنوان ورقة الأنماط المراد حقنها. 
* '''code''': نص ورقة الأنماط المُراد حقنها. 
* '''callback''': الدالة التي ستُنفذ بعد حقن CSS. 
=== المنصات المدعومة === 
*أندرويد 
*iOS 
*ويندوز 
=== مثال سريع === 
<syntaxhighlight lang="javascript">var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstop', function() {
    ref.insertCSS({file: "mystyles.css"});
});‎</syntaxhighlight> 

__ 

== عينة: عرض صفحات المساعدة مع InAppBrowser == 

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

إليك بعض المقتطفات التي توضح كيفية القيام بذلك. 
*[#give Give users a way to ask for help]. 
*[#load Load a help page]. 
*[#let Let users know that you're getting their page ready]. 
*[#show Show the help page]. 
*[#handle Handle page errors]. 
=== منح المستخدمين طريقة لطلب المساعدة === 

هناك الكثير من الطرق لفعل هذا في تطبيقك. تُعد القوائم المنسدلة إحدى أبسط الطرق للقيام بذلك. 
<syntaxhighlight lang="javascript"><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>‎</syntaxhighlight> 

قم بتجميع اختيارات المستخدمين في الدالة <code>onDeviceReady</code> الخاصة بالصفحة، ثم أرسل عنوانًا (URL) مناسبًا لدالة مساعدة (helper functio) في أحد ملفات المكتبة المشتركة. اسم دالة المساعدة هو <code>showHelp()</code>، وسنكتب هذه الدالة فيم يلي. 
<syntaxhighlight lang="javascript">$('#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);
});‎</syntaxhighlight> 
=== تحميل صفحة المساعدة === 

سنستخدم الدالة <code>open</code> لتحميل صفحة المساعدة. سنضبط خاصية <code>hidden</code> عند القيمة <code>yes</code>، لكي نحرص على أن يُعرض المتصفح بعد تحميل محتوى الصفحة. بهذه الطريقة، لن يرى المستخدمون متصفحًا فارغًا أثناء انتظار ظهور المحتوى. عندما يُطلق الحدث <code>loadstop</code>، سنعرف متى تم تحميل المحتوى. سنتعامل مع هذا الحدث بعد قليل. 
<syntaxhighlight lang="javascript">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);
}‎</syntaxhighlight> 
=== إعلام المستخدمين بجاهزية صفحتهم === 

نظرًا لكون المتصفح لا يظهر على الفور، يمكننا استخدام الحدث <code>loadstart</code> لعرض رسالة الحالة، أو شريط التقدم (progress bar)، أو أي مؤشرٍ آخر. هذا يؤكد للمستخدمين أن المحتوى في خضمّ التحميل. 
<syntaxhighlight lang="javascript">function loadStartCallBack() {
    $('#status-message').text("loading please wait ...");
}‎</syntaxhighlight> 
=== عرض صفحة المساعدة === 

عندما يُطلق الحدث <code>loadstopcallback</code>، نعلم أن المحتوى قد حُمِّل، وحينها يمكننا إظهار المتصفح. هذه الحيلة يمكن أن تخلق انطباعًا بتُحسّن الأداء. والحقيقة هي أنه، سواء أعرضت المتصفح قبل تحميل المحتوى أم لا، فإن وقت التحميل لن يتغير. 
<syntaxhighlight lang="javascript">function loadStopCallBack() {
    if (inAppBrowserRef != undefined) {
        inAppBrowserRef.insertCSS({ code: "body{font-size: 25px;" });
        $('#status-message').text("");
        inAppBrowserRef.show();
    }
}‎</syntaxhighlight> 

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

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

سنحاول إظهار الخطأ في مربعٍ يعرض رسالة. يمكننا القيام بذلك عن طريق حقن برنامج نصي يستدعي الدالة <code>alert</code>. المشكلة في هذا أنه لن يعمل على المتصفحات في الأجهزة التي تستخدم ويندوز، لذا سيتعين علينا التحقق من معامل دالة رد النداء <code>executeScript</code> لمعرفة ما إذا كانت المحاولة ناجحة. إذا لم ينجح الأمر، فسنكتفي نعرض رسالة الخطأ في وسم <code><div> على الصفحة. 
<syntaxhighlight lang="javascript">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 + "'");
    }
}‎</syntaxhighlight> 

== معلومات استخدام إضافية == 
=== العناوين المحلية (المصدر في حزمة التطبيق) === 
<syntaxhighlight lang="javascript">var iab = cordova.InAppBrowser;
iab.open('local-url.html');                  // loads in the Cordova WebView
iab.open('local-url.html', '_self');         // loads in the Cordova WebView
iab.open('local-url.html', '_system');       // Security error: system browser, but url will not load (iOS)
iab.open('local-url.html', '_blank');        // loads in the InAppBrowser
iab.open('local-url.html', 'random_string'); // loads in the InAppBrowser
iab.open('local-url.html', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar‎</syntaxhighlight> 
=== محتوى المُدرج في اللائحة البيضاء === 
<syntaxhighlight lang="javascript">var iab = cordova.InAppBrowser;
iab.open('http://whitelisted-url.com');                  // loads in the Cordova WebView
iab.open('http://whitelisted-url.com', '_self');         // loads in the Cordova WebView
iab.open('http://whitelisted-url.com', '_system');       // loads in the system browser
iab.open('http://whitelisted-url.com', '_blank');        // loads in the InAppBrowser
iab.open('http://whitelisted-url.com', 'random_string'); // loads in the InAppBrowser
iab.open('http://whitelisted-url.com', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar‎</syntaxhighlight> 
=== العناوين غير المُدرجة في اللائحة البيضاء === 
<syntaxhighlight lang="javascript">var iab = cordova.InAppBrowser;
iab.open('http://url-that-fails-whitelist.com');                  // loads in the InAppBrowser
iab.open('http://url-that-fails-whitelist.com', '_self');         // loads in the InAppBrowser
iab.open('http://url-that-fails-whitelist.com', '_system');       // loads in the system browser
iab.open('http://url-that-fails-whitelist.com', '_blank');        // loads in the InAppBrowser
iab.open('http://url-that-fails-whitelist.com', 'random_string'); // loads in the InAppBrowser
iab.open('http://url-that-fails-whitelist.com', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar‎</syntaxhighlight>
==مصادر==
*[https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-inappbrowser/index.html صفحة cordova-plugin-inappbrowser في توثيق كوردوفا الرسمي.]