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

<noinclude>{{DISPLAYTITLE:إضافة التحكم بالاهتزاز في كوردوفا}}</noinclude>
[[تصنيف: Cordova]]
[[تصنيف: Cordova Plugin]]
هذه الإضافة متوافقة مع [http://www.w3.org/TR/vibration/ مواصفات الاهتزاز] في W3، إذ توفر طريقة للتحكم في اهتزاز الجهاز.

تعرّف هذه الإضافة كائناتٍ عامة، من بينها الكائن <code>navigator.vibrate</code>. 

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

== التثبيت ==
يمكن تثبيت هذه الإضافة عبر الأمر التالي:<syntaxhighlight lang="shell">cordova plugin add cordova-plugin-vibration‎</syntaxhighlight> 

== المنصات المدعومة ==
*[[Cordova/platforms android|أندرويد]] 
*[[Cordova/platforms ios|iOS]] 
*[[Cordova/platforms windows|ويندوز]] 

يدعم [[Cordova/webviews|عارض]] أندرويد (ذو الواجهة البرمجية من المستوى 19 وما يليه) [https://www.w3.org/TR/vibration/ الواجهةَ البرمجية لمواصفات الاهتزاز من W3C] بشكل أصلي؛ وتبعًا لذلك، فقد تم تجاهل مواصفات التقديم (implementation) الخاص بأندرويد لهذه الإضافة. 

==<code>vibrate</code>== 

تقوم هذه الدالة بثلاث وظائف مختلفة، بناءً على المعاملات المُمرّرة إليها. 
=== الاهتزاز العادي (Standard vibrate) === 

عند تمرير عددٍ أو مصفوفة تحتوي عددًا واحدًا غير معدومٍ إلى هذه الدالة، فسيهتز الجهاز للفترة التي يحددها ذلك العدد. 
<syntaxhighlight lang="javascript">navigator.vibrate(time)‎
// أو
navigator.vibrate([time])‎</syntaxhighlight> 

يمثِّل المعامل <code>time</code> عدد صحيح أو مصفوفة تحدِّد مدة الاهتزاز بالميلي ثواني. 

إليك المثال التالي:<syntaxhighlight lang="javascript">// الاهتزاز لثلاث ثواني
navigator.vibrate(3000);
// الاهتزاز لثلاث ثواني
navigator.vibrate([3000]);‎</syntaxhighlight> 
====ملاحظات خاصة بمنصة أندرويد ==== 

استدعاء <code>navigator.vibrate</code> سيعيد فورًا القيمة <code>false</code> إذا لم ينقر المستخدم على الإطار (frame) أو أي إطار مضمن خلال الاهتزاز. يرجى مراجعة هذه [https://issues.apache.org/jira/browse/CB-14022 الصفحة] لمزيد من المعلومات.  

==== ملاحظات خاصة بمنصة iOS ====
* تتجاهل منصة iOS الوقت المحدد عبر المعامل <code>time</code>، إذ يهتز الجهاز لمدة محددة مسبقًا. 
<syntaxhighlight lang="javascript">navigator.vibrate (3000)  // 3000  يتم تجاهله  </syntaxhighlight>

==== ملاحظات خاصة بويندوز ====
* الحد الأقصى للمدة الزمنية المحددة باستعمال المعامل <code>time</code> هو 5000 ميلي ثانية (5 ثوانٍ)، والحد الأدنى هو 1 ميلي ثانية 
<syntaxhighlight lang="javascript">navigator.vibrate (8000)  // 5000 سيتم تحويلها إلى   </syntaxhighlight>
=== الاهتزاز وفق نمط معين (أندرويد وويندوز فقط) === 

عند تمرير مصفوفة غير أحادية، فسيهتز الجهاز وفق نمط معين. 
<syntaxhighlight lang="javascript">navigator.vibrate(pattern);‎</syntaxhighlight>يمثِّل المعامل <code>pattern</code> مصفوفة من الأعداد تحوي تسلسلًا من الفترات الزمنية (بالميلي ثانية) لتشغيل الاهتزاز أو إيقافه.

اطلع على المثال التالي الذي يشرح ما سبق:<syntaxhighlight lang="javascript">// الاهتزاز لثانية واحدة
// ثم الانتظار ثانية واحدة
// ثم الاهتزاز ثلاث ثوانٍ
// ثم الانتظار ثانية واحدة
// ثم الاهتزاز لخمس ثوانٍ
navigator.vibrate([1000, 1000, 3000, 1000, 5000]);‎</syntaxhighlight> 
=== إلغاء الاهتزاز (غير مدعوم في منصة iOS) === 

للإلغاء الفوري لأيّ اهتزاز حاليً، مرر الصفر، أو مصفوفة تحتوي على الصفر فقط، أو مصفوفة فارغة إلى التابع <code>vibrate</code>. 
<syntaxhighlight lang="javascript">navigator.vibrate(0)‎
// أو
navigator.vibrate([])
// أو
navigator.vibrate([0])</syntaxhighlight>سيؤدي تمرير  القيمة <code>0</code>، أو مصفوفة فارغة، أو مصفوفة أحادية تحتوي <code>0</code> إلى إلغاء الاهتزازات.

== انظر أيضًا ==
* إضافة <nowiki/>[[Cordova/cordova plugin battery status|حالة البطارية]]
* إضافة [[Cordova/cordova plugin device|حالة الجهاز]]
* [[Cordova/plugins|دليل تطوير الإضافات في كوردوفا]]

==مصادر==
*[https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-vibration/index.html صفحة cordova-plugin-vibration في توثيق كوردوفا الرسمي.]