الفرق بين المراجعتين ل"Cordova/cordova plugin inappbrowser"
سطر 27: | سطر 27: | ||
==التثبيت== | ==التثبيت== | ||
− | <syntaxhighlight lang="shell">cordova plugin add cordova-plugin-inappbrowser</syntaxhighlight> | + | يمكنك تثبيت هذه الإضافة عبر الأمر التالي:<syntaxhighlight lang="shell">cordova plugin add cordova-plugin-inappbrowser</syntaxhighlight> |
− | ان كنت تريد أن تُعرض جميع الصفحات المُحملة في تطبيقك في | + | ان كنت تريد أن تُعرض جميع الصفحات المُحملة في تطبيقك في <code>InAppBrowser</code>، يمكنك ببساطة أن تنشُب <code>window.open</code> أثناء التهيئة. مثلًا: |
<syntaxhighlight lang="javascript">document.addEventListener("deviceready", onDeviceReady, false); | <syntaxhighlight lang="javascript">document.addEventListener("deviceready", onDeviceReady, false); | ||
function onDeviceReady() { | function onDeviceReady() { | ||
سطر 35: | سطر 35: | ||
}</syntaxhighlight> | }</syntaxhighlight> | ||
− | == | + | == cordova.InAppBrowser.open== |
− | يفتح هذا التابع | + | يفتح هذا التابع عنوانًا في نسخة جديدة (instance) من <code>InAppBrowser</code>، أو في نسخة من المتصفح الحالي، أو متصفح النظام. |
− | <syntaxhighlight lang="javascript">var ref = cordova.InAppBrowser.open(url, target, options);</syntaxhighlight> | + | <syntaxhighlight lang="javascript">var ref = cordova.InAppBrowser.open(url, target, options);</syntaxhighlight>يشير المتغير <code>ref</code> إلى النافذة <code>InAppBrowser</code> عندما يُضبط المعامل <code>target</code> عند القيمة <code>'_blank'</code>. (<code>InAppBrowser</code>) |
− | + | ||
− | + | === المعاملات === | |
− | + | <code>url</code> العنوان المراد تحميله (سلسلة نصية). مرّر هذا المعامل إلى الدالةَ <code>encodeURI()</code> إن كان العنوان يحتوي على أحرف اليونيكود. | |
− | * <code>_self</code>: يُفتح | + | |
+ | <code>target</code> يحدد المكان الذي سيُحمّل فيه العنوان، وهو معامل اختياري، قيمته الافتراضية تساوي <code>_self</code>. (سلسلة نصية) | ||
+ | * <code>_self</code>: يُفتح في [[Cordova/webviews|عارض]] كوردوفا إن كان العنوان مُدرجًا في [[Cordova/whitelist|اللائحة البيضاء]]، وإلا فسيُفتح في نافذة <code>InAppBrowser</code>. | ||
* <code>_blank</code>: يُفتح في <code>InAppBrowser</code>. | * <code>_blank</code>: يُفتح في <code>InAppBrowser</code>. | ||
* <code>_system</code>: يفتح في متصفح النظام. | * <code>_system</code>: يفتح في متصفح النظام. | ||
− | + | <code>options</code> | |
− | يجب ألا تحتوي السلسلة النصية <code>options</code> على أية مسافة فارغة، ويجب أن تُفصل أزواج الميزات name/value بفاصلة. أسماء الميزات غير حساسة لحالة الأحرف. | + | خيارات النافذة <code>InAppBrowser</code>. وهو معامل اختياري، وقيمته الافتراضية هي<code>location=yes</code>.(سلسلة نصية). يجب ألا تحتوي السلسلة النصية <code>options</code> على أية مسافة فارغة، ويجب أن تُفصل أزواج الميزات name/value بفاصلة. كما أنّ أسماء الميزات غير حساسة لحالة الأحرف. |
− | جميع المنصات تدعم: | + | جميع المنصات تدعم الخيار التالي: |
− | * | + | * <code>location</code>: اضبط هذه الخاصية عند القيمة <code>yes</code> أو <code>no</code> لإظهار شريط التصفح (location bar) في <code>InAppBrowser</code> أو إخفائه. |
+ | يدعم أندرويد هذه الخيارات الإضافية: | ||
+ | * <code>hidden</code>: اضبطه هذا الخيار عند القيمة <code>yes</code> لإنشاء المتصفح وتحميل الصفحة بدون إظهاره. يُطلق الحدث <code>loadstop</code> عند اكتمال التحميل. احذف هذا الخيار أو اضبطه عند القيمة <code>no</code> (القيمة الافتراضية) لفتح المتصفح وتحميل الصفحة بشكل طبيعي. | ||
− | + | * <code>clearcache</code>: اضبط هذا الخيار عند القيمة <code>yes</code> لمحو ذاكرة التخزين المؤقت لملف تعريف الارتباط (cookie cache) في المتصفح قبل فتح النافذة الجديدة | |
− | * | + | * <code>clearsessioncache</code>: اضبط هذا الخيار عند القيمة <code>yes</code> لمحو ذاكرة التخزين المؤقت لملف تعريف الارتباط قبل فتح النافذة الجديدة |
− | + | * <code>closebuttoncaption</code>: اعط لهذا الخيار سلسلةً نصيةً لاستخدامها كتسميةٍ للزر بدلًا من الحرف <code>X</code>. تذكّر أنه سيكون عليك مراعاة الإعدادات اللغوية المحلية لهذه القيمة بنفسك. | |
− | * | + | * <code>closebuttoncolor</code>: اعط لهذا الخيار سلسلةً نصية تمثل قيمة لونية سداسي عشرية (hex color) صالحة، مثل: <code>#00ff00</code>، لأجل تغيير لون زر الإغلاق الافتراضي، سواءً كان نصًا، أو كان يساوي القيمة الافتراضية <code>X</code>. لا يكون لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الخيار location إلى القيمة <code>yes</code>. |
− | * | + | * <code>footer</code>: اضبط هذا الخيار عند القيمة <code>yes</code> لإظهار زر الإغلاق في أسفل النافذة بشكل مماثلٍ للزر <code>Done</code> في منصة iOS. سيظهر زر الإغلاق بشكل مماثلٍ لترويسة (header) النافذة، لذلك استخدم <code>closebuttoncaption</code> و <code>closebuttoncolor</code> لتعيين خصائصه. |
− | * | + | * <code>footercolor</code>: اعط لهذا الخيار سلسلة نصية تمثل لونًا سداسي عشريًا (hex color) صالحًا، مثل <code>#00ff00</code> أو <code>#CC00ff00</code> (<code>#aarrggbb</code>)، لتغيير لون تذييل النافذة الافتراضي. ليس لهذا الخيار تأثيرٌ إلا إن عيّن المُستخدم الخيارَ <code>footer</code> إلى القيمة <code>yes</code>. |
− | * | + | * <code>hardwareback</code>: اضبط هذا الخيار عند القيمة <code>yes</code> لاستخدام زر الرجوع الخاص بالجهاز للرجوع للخلف بحسب تاريخ النافذة <code>InAppBrowser</code>. إذا لم تكن هناك صفحات سابقة، فسيتم إغلاق <code>InAppBrowser</code>. القيمة الافتراضية هي <code>yes</code>، إن كنت تريد أن تجعل زر الرجوع يغلق <code>InAppBrowser</code> ، فععيّن هذا الخيار إلى القيمة <code>no</code> . |
− | * | + | * <code>hidenavigationbuttons</code>: اضبط هذا الخيار عند القيمة <code>yes</code> لإخفاء أزرار التصفح (navigation buttons) على شريط التصفح، ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الخيار <code>location</code> عند القيمة <code>yes</code>. القيمة الافتراضية هي <code>no</code>. |
− | * | + | * <code>hideurlbar</code>: اضبط هذا الخيار عند القيمة <code>yes</code> لإخفاء شريط العنوان من شريط التصفح، ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الخيار <code>location</code> عند القيمة <code>yes</code>. القيمة الافتراضية هي <code>no</code>. |
− | * | + | * <code>navigationbuttoncolor</code>: اعط لهذا الخيار سلسلة نصية تمثل لونًا سداسي عشريًا (hex color) صالحًا، مثل: <code>#00ff00</code>، لتغيير لون أزرار التصفح الافتراضي. ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الخيار <code>location</code> عند القيمة <code>yes</code>، ولم يُعيّن الخيار <code>hidenavigationbuttons</code> عند القيمة <code>yes</code>. |
− | * | + | * <code>toolbarcolor</code>: اعط لهذا الخيار سلسلة نصية تمثل لونًا سداسي عشريًا (hex color) صالحًا، مثل: <code>#00ff00</code>، لتغيير لون شريط الأدوات لافتراضي. ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الخيار <code>location</code> عند القيمة <code>yes</code>. |
− | * | + | * <code>zoom</code>: اضبط هذا الخيار عند القيمة <code>yes</code> لعرض عناصر التحكم في الحجم في متصفح أندرويد، أو اضبطه عند القيمة <code>no</code> إن أردت إخفاءها. القيمة الافتراضية هي <code>yes</code>. |
− | * | + | * <code>mediaPlaybackRequiresUserAction</code>: اضبط هذا الخيار عند القيمة <code>yes</code> لمنع صوتيات أو فيديوها HTML5 من التشغيل التلقائي (القيمة الافتراضية هي <code>no</code>). |
− | * | + | * <code>shouldPauseOnSuspend</code>: اضبط هذا الخيار عند القيمة <code>yes</code> لإيقاف [[Cordova/webviews|عارض]] <code>InAppBrowser</code> أو استئنافه مع التطبيق، وذلك لإيقاف صوت الخلفية (قد يكون هذا ضروريًا لتجنب المشكلات التي تخص Google Play كما هو موضح في الصفحة [https://issues.apache.org/jira/browse/CB-11013 CB-11013]). |
− | * | + | * <code>useWideViewPort</code>: يحدد هذا الخيار ما إذا كان [[Cordova/webviews|العارض]] سيدعم وسم [[HTML]] الوصفي "<code>viewport</code>"، أو أنّ عليه أن يستخدم إطار عرضٍ (viewport) واسعٍ. عندما يُعطى هذا الخيار القيمة <code>no</code>، سيُعيّن عرض المخطط (layout) إلى قيمة عرض [[Cordova/webviews|العارض]] محسوبةً بوحدة البكسل المستقلة عن الجهاز (CSS). إما إن أُعطي هذا الخيار القيمة <code>yes</code>، وكانت الصفحة تحتوي الوسم الوصفي <code>viewport</code>، فستُستخدم قيمة العرض المحددة في الوسم. إن لم تحتوِ الصفحة على الوسم، أو لم تحدد قيمةً للعرض، فسيُستخدم إطار عرضٍ واسعٍ. (القيمة الافتراضية هي <code>yes</code>). |
− | * | ||
− | * | ||
تدعم منصة iOS الخيارات الإضافية التالية: | تدعم منصة iOS الخيارات الإضافية التالية: | ||
− | * | + | * <code>hidden</code>: اضبط هذا الخيار عند القيمة <code>yes</code> لإنشاء المتصفح وتحميل الصفحة، ولكن دون إظهاره. سيُطلق الحدث <code>loadstop</code> عند اكتمال التحميل. احذف هذا الخيار أو اضبطه عند القيمة <code>no</code> (الافتراضية) لفتح المتصفح وتحميله بشكل طبيعي. |
− | * | + | * <code>clearcache</code>: اضبط هذا الخيار عند القيمة <code>yes</code> لمحو ذاكرة التخزين المؤقت لملفات تعريف الارتباط (cookie cache) للمتصفح قبل فتح النافذة الجديدة |
− | * | + | * <code>clearsessioncache</code>: اضبط هذا الخيار عند القيمة <code>yes</code> لمحو ذاكرة التخزين المؤقت لملفات تعريف الارتباط قبل فتح النافذة الجديدة |
− | * | + | * <code>closebuttoncolor</code>: اعط لهذا الخيار سلسلةً نصيةً تمثل لونًا سداس عشريًا (hex color) صالحًا، مثل: <code>#00ff00</code>، لتغيير لون الزر <code>Done</code> الافتراضي. لا يُطبق هذا الإعداد إلا عند تفعيل شريط الأدوات. |
− | * | + | * <code>closebuttoncaption</code>: اعط لهذا الخيار سلسلةً نصيةً لاستخدامها كتسميةِ للزر <code>Done</code>. تذكر أن عليك مراعاة الإعدادات اللغوية المحلية بنفسك. |
− | * | + | * <code>disallowoverscroll</code>: يُضبط هذا الخيار عند القيمة <code>yes</code> أو <code>no</code> (الإعداد الافتراضي هو <code>no</code>). لتشغيل أو إيقاف الخاصية <code>UIWebViewBounce</code>. |
− | * | + | * <code>hidenavigationbuttons</code>: اضبط هذا الخيار عند القيمة <code>yes</code> أو <code>no</code> لإظهار أزرار التصفح (navigation buttons) في شريط الأدوات أو إخفائها (الإعداد الافتراضي هو <code>no</code>). لا يُطبّق هذا الخيار إلا عند تفعيل شريط الأدوات. |
− | * | + | * <code>navigationbuttoncolor</code>: اعط لهذا الخيار سلسلةًً نصيةًً تمثل لونًا سداس عشريًا (hex color) صالحًا، مثل: <code>#00ff00</code>، لتغيير اللون الافتراضي. لا يُطبّق هذا الخيار إلا عند إظهار أزرار التصفح. |
* '''toolbar''': اعط لهذا الخيار <code>yes</code> أو <code>no</code> لتشغيل شريط الأدوات أو تعطيله في InAppBrowser (الإعداد الافتراضي هو <code>yes</code>) | * '''toolbar''': اعط لهذا الخيار <code>yes</code> أو <code>no</code> لتشغيل شريط الأدوات أو تعطيله في InAppBrowser (الإعداد الافتراضي هو <code>yes</code>) | ||
* '''toolbarcolor''': اعط لهذا الخيار سلسلةً نصيةً تمثل لونًا سداس عشريًا (hex color) صالحًا، مثل: <code>#00ff00</code>، لتغيير اللون الافتراضي لشريط الأدوات. لا يُطبّق هذا الخيار إلا عند تفعيل شريط الأدوات. | * '''toolbarcolor''': اعط لهذا الخيار سلسلةً نصيةً تمثل لونًا سداس عشريًا (hex color) صالحًا، مثل: <code>#00ff00</code>، لتغيير اللون الافتراضي لشريط الأدوات. لا يُطبّق هذا الخيار إلا عند تفعيل شريط الأدوات. |
مراجعة 13:55، 20 ديسمبر 2018
تساعد إضافة المتصفح الداخلي (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).
للتوافق مع الإصدارات القديمة، تنشُبُ (hooks) هذه الإضافة أيضًا الدالةَ 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
(القيمة الافتراضية) لفتح المتصفح وتحميل الصفحة بشكل طبيعي.
clearcache
: اضبط هذا الخيار عند القيمة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
إلى القيمةyes
.hardwareback
: اضبط هذا الخيار عند القيمةyes
لاستخدام زر الرجوع الخاص بالجهاز للرجوع للخلف بحسب تاريخ النافذةInAppBrowser
. إذا لم تكن هناك صفحات سابقة، فسيتم إغلاقInAppBrowser
. القيمة الافتراضية هيyes
، إن كنت تريد أن تجعل زر الرجوع يغلقInAppBrowser
، فععيّن هذا الخيار إلى القيمةno
.hidenavigationbuttons
: اضبط هذا الخيار عند القيمةyes
لإخفاء أزرار التصفح (navigation buttons) على شريط التصفح، ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الخيارlocation
عند القيمةyes
. القيمة الافتراضية هيno
.hideurlbar
: اضبط هذا الخيار عند القيمةyes
لإخفاء شريط العنوان من شريط التصفح، ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الخيارlocation
عند القيمةyes
. القيمة الافتراضية هيno
.navigationbuttoncolor
: اعط لهذا الخيار سلسلة نصية تمثل لونًا سداسي عشريًا (hex color) صالحًا، مثل:#00ff00
، لتغيير لون أزرار التصفح الافتراضي. ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الخيارlocation
عند القيمةyes
، ولم يُعيّن الخيارhidenavigationbuttons
عند القيمةyes
.toolbarcolor
: اعط لهذا الخيار سلسلة نصية تمثل لونًا سداسي عشريًا (hex color) صالحًا، مثل:#00ff00
، لتغيير لون شريط الأدوات لافتراضي. ليس لهذا الخيار تأثير إلا إن كان المستخدم قد عيّن الخيارlocation
عند القيمةyes
.zoom
: اضبط هذا الخيار عند القيمةyes
لعرض عناصر التحكم في الحجم في متصفح أندرويد، أو اضبطه عند القيمةno
إن أردت إخفاءها. القيمة الافتراضية هيyes
.mediaPlaybackRequiresUserAction
: اضبط هذا الخيار عند القيمةyes
لمنع صوتيات أو فيديوها HTML5 من التشغيل التلقائي (القيمة الافتراضية هيno
).shouldPauseOnSuspend
: اضبط هذا الخيار عند القيمةyes
لإيقاف عارضInAppBrowser
أو استئنافه مع التطبيق، وذلك لإيقاف صوت الخلفية (قد يكون هذا ضروريًا لتجنب المشكلات التي تخص Google Play كما هو موضح في الصفحة CB-11013).useWideViewPort
: يحدد هذا الخيار ما إذا كان العارض سيدعم وسم HTML الوصفي "viewport
"، أو أنّ عليه أن يستخدم إطار عرضٍ (viewport) واسعٍ. عندما يُعطى هذا الخيار القيمةno
، سيُعيّن عرض المخطط (layout) إلى قيمة عرض العارض محسوبةً بوحدة البكسل المستقلة عن الجهاز (CSS). إما إن أُعطي هذا الخيار القيمةyes
، وكانت الصفحة تحتوي الوسم الوصفيviewport
، فستُستخدم قيمة العرض المحددة في الوسم. إن لم تحتوِ الصفحة على الوسم، أو لم تحدد قيمةً للعرض، فسيُستخدم إطار عرضٍ واسعٍ. (القيمة الافتراضية هيyes
).
تدعم منصة iOS الخيارات الإضافية التالية:
hidden
: اضبط هذا الخيار عند القيمةyes
لإنشاء المتصفح وتحميل الصفحة، ولكن دون إظهاره. سيُطلق الحدثloadstop
عند اكتمال التحميل. احذف هذا الخيار أو اضبطه عند القيمةno
(الافتراضية) لفتح المتصفح وتحميله بشكل طبيعي.clearcache
: اضبط هذا الخيار عند القيمةyes
لمحو ذاكرة التخزين المؤقت لملفات تعريف الارتباط (cookie cache) للمتصفح قبل فتح النافذة الجديدةclearsessioncache
: اضبط هذا الخيار عند القيمةyes
لمحو ذاكرة التخزين المؤقت لملفات تعريف الارتباط قبل فتح النافذة الجديدةclosebuttoncolor
: اعط لهذا الخيار سلسلةً نصيةً تمثل لونًا سداس عشريًا (hex color) صالحًا، مثل:#00ff00
، لتغيير لون الزرDone
الافتراضي. لا يُطبق هذا الإعداد إلا عند تفعيل شريط الأدوات.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
). لا يُطبّق هذا الخيار إلا عند تفعيل شريط الأدوات. - enableViewportScale: اضبط هذا الخيار عند القيمة
yes
أوno
لمنع تعديل حجم إطار العرض (viewport) عبر وسم وصفي (القيمة الافتراضية هي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
لتعيين presentation style (القيمة الافتراضية هيfullscreen
). - transitionstyle: اعط لهذا الخيار
fliphorizontal
أوcrossdissolve
أوcoververtical
لتعيين transition style (القيمة الافتراضية هيcoververtical
). - toolbarposition: اضبط هذا الخيار عند القيمة
top
أوbottom
(الإعداد الافتراضي هوbottom
). لجعل شريط الأدوات في أعلى النافذة أو أسفلها. - hidespinner: اضبط هذا الخيار عند القيمة
yes
أوno
لتغيير مستوى رؤية (visibility) مؤشر التحميل (القيمة الافتراضية هيno
).
تدعم منصة ويندوز الخيارات الإضافية التالية:
- hidden: اضبط هذا الخيار عند القيمة
yes
لإنشاء المتصفح وتحميل الصفحة، دون إظهاره. يُطلق الحدث loadstop عند اكتمال التحميل. احذف هذا الخيار أو اضبطه عند القيمةno
(الافتراضية) لفتح المتصفح وتحميله بشكل طبيعي. - hardwareback: يعمل هذا الخيار بطريقة مشابهة لمنصة أندرويد.
- fullscreen: اضبط هذا الخيار عند القيمة
yes
لإنشاء مركبة المتصفح بدون إحاطته بحدود. يرجى ملاحظة أنه إذا تم تحديد location=no أيضًا، فلن يُقدّم للمستخدم أي مُركّبةٍ (control) لإغلاق نافذة IAB.
المنصات المدعومة
- أندرويد
- Browser
- iOS
- OSX
- ويندوز
مثال
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،
- لم يتم تقديم تاريخ التصفح بعدُ (الزِّران
back
وforward
في شريط التصفح LocationBar).
InAppBrowser
الكائن المُعاد من استدعاء التابع cordova.InAppBrowser.open
عند تعيين الهدف target إلى القيمة '_blank'
.
التوابع
- addEventListener
- removeEventListener
- close
- show
- hide
- executeScript
- insertCSS
InAppBrowser.addEventListener
يضيف هذا التابع مُنصتًا (listener) لحدثٍ من InAppBrowser
. (متاح فقط عند ضبط الهدف عند القيمة '_blank'
)
ref.addEventListener(eventname, callback);
- ref: يُشير إلى نافذة
InAppBrowser
(InAppBrowser) - eventname: الحدث المُراد الإنصات إليه (سلسلة نصية)
- loadstart: يُطلق هذا الحدث عندما يبدأ
InAppBrowser
في تحميل عنوان URL. - loadstop: يُطلق هذا الحدث عند انتهاء
InAppBrowser
من تحميل عنوان URL. - loaderror: يُطلق هذا الحدث عندما يواجه
InAppBrowser
خطأً أثناء تحميل عنوان URL. - exit: يُطلق هذا الحدث عند إغلاق نافذة
InAppBrowser
. - callback: الدالة التي ستنفذ عند إطلاق الحدث. يُمرّر إلى هذه الدالة كائن
InAppBrowserEvent
كمعاملٍ.
مثال
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 + "'");
}
}
خاصيات InAppBrowserEvent
- type: اسم الحدث، والذي يساوي إمّا
loadstart
أوloadstop
أوloaderror
أوexit
. ((سلسلة نصية) - url: العنوان الذي تم تحميله. (سلسلة نصية)
- code: رمز الخطأ، لا تكون هذه الخاصية مُتاحةً إلا في حال إطلاق الحدث
loaderror
. ((عدد) - message: رسالة الخطأ، لا تكون هذه الخاصية مُتاحةً إلا في حال إطلاق الحدث
loaderror
. (سلسلة نصية)
المنصات المدعومة
- أندرويد
- Browser
- iOS
- ويندوز
- OSX
ملاحظات خاصة بالمتصفحات (Browsers)
في هذه المنصات، لا يُطلق الحدثان loadstart
و loaderror
.
مثال سريع
var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstart', function(event) { alert(event.url); });
InAppBrowser.removeEventListener
يزيل هذا التابع مُنصِتا لحدثٍ من InAppBrowser
. (متاح فقط عند ضبط الهدف عند القيمة '_blank'
)
ref.removeEventListener(eventname, callback);
- ref: تُشير إلى النافذة
InAppBrowser
. (InAppBrowser) - eventname: الحدث المُراد التوقف عن الإنصات له. (سلسلة نصية)
- loadstart: يُطلق هذا الحدث عندما يبدأ
InAppBrowser
في تحميل عنوان URL. - loadstop: يُطلق هذا الحدث عند انتهاء
InAppBrowser
من تحميل عنوان URL. - loaderror: يُطلق هذا الحدث عندما يواجه
InAppBrowser
خطأ أثناء تحميل عنوان URL. - exit: يُطلق هذا الحدث عند إغلاق نافذةِ
InAppBrowser
. - callback: الدالة التي سيتم تنفيذها عند إطلاق الحدث. يُمرّر إلى هذه الدالة كائنٌ
InAppBrowserEvent
.
المنصات المدعومة
- أندرويد
- Browser
- iOS
- ويندوز
مثال سريع
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
- ويندوز
مثال سريع
var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.close();
InAppBrowser.show
يظهر هذا التابع نافذة InAppBrowser فُتِحت مخفية. استدعاء هذا التابع لن يكون له أي تأثير إن كان InAppBrowser مرئيًا بالفعل.
ref.show();
- ref: يُشير إلى نافذة InAppBrowser (
InAppBrowser
)
المنصات المدعومة
- أندرويد
- Browser
- iOS
- ويندوز
مثال سريع
var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'hidden=yes');
// some time later...
ref.show();
InAppBrowser.hide
يُخفي هذا التابع نافذة InAppBrowser. استدعاء هذا التابع ليس له أي تأثير إن كان InAppBrowser مخفيًا مسبقاً.
ref.hide();
- ref: يُشير إلى نافذة InAppBrowser (
InAppBrowser
)
المنصات المدعومة
- أندرويد
- iOS
- ويندوز
مثال سريع
var ref = cordova.InAppBrowser.open('http://apache.org', '_blank');
// some time later...
ref.hide();
InAppBrowser.executeScript
يحقن (Injects) هذا التابع شيفرة جافااسكريبت في نافذة InAppBrowser
. (متاح فقط عند ضبط الهدف [target] عند القيمة '_blank'
)
ref.executeScript(details, callback);
- ref: يُشير إلى النافذةة
InAppBrowser
. (InAppBrowser) - injectDetails: تفاصيل البرنامج النصي المراد تنفيذه، مع تحديد إما المفتاح
file
أوcode
. (كائن) - file: عنوان النص المراد حقنُه.
- code: نص الشيفرة البرمجية المراد حقنُها.
- callback: الدالة التي سُتنفّذ بعد حقن شيفرة جافااسكريبت.
- إن كان البرنامج النصي المحقون من النوع
code
، فسُينفّذ رد النداء مع إعطائه معاملًا واحدًا، والذي هو القيمة التي يُعيدها البرنامج النصي، مُغلّفةً في مصفوفة (Array
). بالنسبة للنصوص النصية متعددة الأسطر، فالقيمة ستكون هي قيمة آخر تعبير (statement)، أو آخر تعبير مُقيّمٍ.
المنصات المدعومة
- أندرويد
- Browser
- iOS
- ويندوز
مثال سريع
var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstop', function() {
ref.executeScript({file: "myscript.js"});
});
ملاحظات خاصة بالمتصفحات (Browsers)
- لا تدعم هذه المنصة إلا المفتاح code.
ملاحظات خاصة بمنصة ويندوز
رجوعًا إلى MSDN docs، لا يمكن للبرنامج النصي المستدعي أن يُعيد إلا القيم النصية فقط، وإلا فإن المعامل الذي سيُمرّر إلى callback سيساوي [null]
.
InAppBrowser.insertCSS
يحقن هذا التابع أنماط CSS في نافذة InAppBrowser
. (متاح فقط عند ضبط الهدف (target) عند القيمة '_blank'
)
ref.insertCSS(details, callback);
- ref: يُشير إلى نافذة
InAppBrowser
(InAppBrowser) - injectDetails: تفاصيل البرنامج النصي المُراد تشغيله، مع تحديد إما المفتاح
file
أوcode
. (كائن) - file: عنوان ورقة الأنماط المراد حقنها.
- code: نص ورقة الأنماط المُراد حقنها.
- callback: الدالة التي ستُنفذ بعد حقن CSS.
المنصات المدعومة
- أندرويد
- iOS
- ويندوز
مثال سريع
var ref = cordova.InAppBrowser.open('http://apache.org', '_blank', 'location=yes');
ref.addEventListener('loadstop', function() {
ref.insertCSS({file: "mystyles.css"});
});
__
عينة: عرض صفحات المساعدة مع 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].
منح المستخدمين طريقة لطلب المساعدة
هناك الكثير من الطرق لفعل هذا في تطبيقك. تُعد القوائم المنسدلة إحدى أبسط الطرق للقيام بذلك.
<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 functio) في أحد ملفات المكتبة المشتركة. اسم دالة المساعدة هو 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
لعرض رسالة الحالة، أو شريط التقدم (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
لمعرفة ما إذا كانت المحاولة ناجحة. إذا لم ينجح الأمر، فسنكتفي نعرض رسالة الخطأ في وسم
على الصفحة.
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'); // 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
محتوى المُدرج في اللائحة البيضاء
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
العناوين غير المُدرجة في اللائحة البيضاء
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
مصادر