مرجع واجهة برمجة التطبيقات التي تعمل باللمس على Android

يقدّم هذا القسم مقدمة عن واجهات برمجة التطبيقات المختلفة الخاصة باللمس المتاحة في Android. ويشمل أيضًا الحالات التي يجب فيها التحقّق من توفّر أي دعم للأجهزة لضمان تشغيل التأثيرات اللمسية على النحو المطلوب.

هناك عدة طرق مختلفة لإنشاء تأثيرات لمسية، ومن المهم مراعاة مبادئ تصميم اللمسات على Android عند الاختيار من بينها. يلخّص الجدول التالي هذه السمات العالية المستوى لكل طريقة:

  • تُعدّ إمكانية الوصول مهمة بشكل خاص عند التخطيط لآلية احتياطية للسلوك، ويجب دمجها مع التحقّق من توافق الأجهزة الفردية.
  • اللمسات الواضحة هي إحساسات دقيقة ونظيفة لا تزعج المستخدمين.
  • تتسم اللمسات الغنية بقدرة أكبر على التعبير، وغالبًا ما تتطلّب أجهزة مزوّدة بميزات أكثر.
مساحة عرض واجهة برمجة التطبيقات مدى التوفّر محو الحسّ اللمسي التجاوب الحسي الغني
HapticFeedbackConstants ‫Android 1.5 والإصدارات الأحدث
(لكل ثابت)
Predefined VibrationEffect ‫Android 10 والإصدارات الأحدث
VibrationEffect Composition ‫Android 11 والإصدارات الأحدث (لكل ثابت)
الاهتزازات عند التفعيل أو الإيقاف، والاهتزازات لمرة واحدة، والاهتزازات على شكل موجة Android 1

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

تتضمّن هذه الصفحة أيضًا وصفًا للمفاهيم الإضافية التي تشمل مساحات عرض واجهة برمجة التطبيقات:

HapticFeedbackConstants

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

التوافق والمتطلبات

لا يتطلّب استخدام طريقة View.performHapticFeedback مع هذه الثوابت أي أذونات خاصة للتطبيق، بل يخضع للسمة View.hapticFeedbackEnabled التي سيؤدي ضبطها على false إلى إيقاف جميع طلبات ردود الفعل اللمسية في طريقة العرض، بما في ذلك الطلبات التلقائية. الإعداد الأساسي ذو الصلة هو السمة View.hapticFeedbackEnabled التي سيؤدي ضبطها على false إلى إيقاف جميع طلبات ردود الفعل اللمسية في طريقة العرض، بما في ذلك الطلبات التلقائية. تلتزم الطريقة أيضًا بإعدادات النظام التي يضبطها المستخدم لتفعيل الملاحظات اللمسية.

الاعتبار الوحيد المتعلّق بالتوافق هو مستوى حزمة تطوير البرامج (SDK) للثابت المحدّد للإجراء.

لا حاجة إلى توفير سلوك احتياطي عند استخدام HapticFeedbackConstants.

استخدام HapticsFeedbackConstants

لمزيد من التفاصيل حول استخدام HapticFeedbackConstants، يُرجى الاطّلاع على إضافة ملاحظات حسية إلى الأحداث.

محدّدة مسبقًا VibrationEffect

يوفر صف VibrationEffect العديد من الثوابت المحددة مسبقًا، مثل CLICK وTICK وDOUBLE_CLICK. قد يتم تحسين هذه التأثيرات لتناسب الجهاز.

التوافق والمتطلبات

يتطلّب تشغيل أي VibrationEffect الحصول على إذن VIBRATE في ملف بيان التطبيق.

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

تُستخدَم واجهتا برمجة التطبيقات Vibrator.areEffectsSupported وVibrator.areAllEffectsSupported لتحديد ما إذا كان هناك تنفيذ محسّن للجهاز. سيظلّ بإمكانك استخدام التأثيرات المحدّدة مسبقًا بدون تنفيذ محسّن، وسيتم استخدام خيار التراجع التلقائي العادي للمنصة. وبالتالي، لا تكون واجهات برمجة التطبيقات areEffectsSupported هذه مطلوبة إلا إذا كان التطبيق يريد أن يأخذ في الاعتبار ما إذا كان التأثير محسّنًا للجهاز أم لا.

يمكن أن تعرض طرق التحقّق من التأثير إحدى القيم الثلاث التالية:

  • يشير VIBRATION_EFFECT_SUPPORT_YES إلى أنّ الجهاز يوفّر دعمًا محسّنًا لهذا التأثير.
  • يشير الرمز VIBRATION_EFFECT_SUPPORT_NO إلى أنّ الجهاز لا يتوافق مع ميزة التحسين، ولكنّه لا يزال يستخدم خيار التوافق الاحتياطي للمنصة.
  • يشير الرمز VIBRATION_EFFECT_SUPPORT_UNKNOWN إلى أنّ النظام لا يعرف ما إذا كان التنفيذ محسّنًا أم لا.

بما أنّ القيمة UNKNOWN تشير إلى أنّ واجهة برمجة التطبيقات الخاصة بالتحقّق غير متاحة، يتم عرضها عادةً لجميع التأثيرات أو لا يتم عرضها لأي منها. تعود هذه الأجهزة إلى الإصدار السابق بشكلٍ ديناميكي.

استخدام VibrationEffect المحدَّدة مسبقًا

لمزيد من التفاصيل حول استخدام VibrationEffect محدَّد مسبقًا، يُرجى الاطّلاع على استخدام VibrationEffect محدَّد مسبقًا لإنشاء ملاحظات لمسية.

Envelope VibrationEffect

تتيح الاهتزازات المستندة إلى الغلاف تحكّمًا دقيقًا في سعة الاهتزاز وتردده بمرور الوقت من خلال تحديد سلسلة من نقاط التحكّم. يتيح ذلك للمطوّرين تصميم تجارب ملاحظات لمسية أكثر ثراءً ودقة. يمكن إنشاء هذه الاهتزازات باستخدام الفئتَين BasicEnvelopeBuilder وWaveformEnvelopeBuilder.

التوافق والمتطلبات

لتشغيل أي مؤثرات اهتزاز، يجب أن يدرج تطبيقك الإذن VIBRATE في بيان التطبيق.

للتأكّد من توفّر مؤثرات الظرف، انقر على Vibrator.areEnvelopeEffectsSupported().

أداة إنشاء مغلفات أساسية

لإنشاء تجربة لمسية سلسة، يجب أن تبدأ تأثيرات الغلاف وتنتهي بشدة مقدارها \( 0.0 \). تفرض واجهة برمجة التطبيقات ذلك من خلال ضبط شدة الاهتزاز عند البدء على صفر، وتُصدر استثناءً إذا لم تكن شدة الاهتزاز عند الانتهاء صفرًا. يمنع هذا القيد حدوث تأثيرات ديناميكية غير مرغوب فيها في الاهتزازات بسبب حالات عدم الاستمرارية في السعة التي يمكن أن تؤثر سلبًا في إدراك المستخدم للمس.

لتوفير عرض متسق لتأثيرات التغليف على جميع الأجهزة، يتطلّب إطار العمل أن تتمكّن الأجهزة التي تتوافق مع هذه الميزة من التعامل مع مدة لا تقل عن 20 مللي ثانية بين نقاط التحكّم و16 نقطة على الأقل لتأثيرات التغليف.

Waveform Envelope Builder

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

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

getMaxSize()
يستردّ هذا الإجراء الحد الأقصى لعدد نقاط التحكّم المتاحة لتأثير المغلف.
getMinControlPointDurationMillis()
تعرض هذه السمة الحد الأدنى للمدة المتاحة، بالمللي ثانية، بين نقطتَي تحكّم ضمن تأثير التضمين.
getMaxControlPointDurationMillis()
تعرض هذه السمة الحد الأقصى للمدة المسموح بها بالمللي ثانية بين نقطتَي تحكّم ضمن تأثير غلاف.
getMaxDurationMillis()
تعرض هذه السمة الحد الأقصى لمدة تأثير الغلاف، بالمللي ثانية.

إذا تجاوز أحد المؤثرات حدود الجهاز، مثل السماح بعدد كبير جدًا من نقاط التحكّم أو مدة تتجاوز الحد الأقصى، يعدّل إطار العمل المؤثر تلقائيًا ليتناسب مع الحدود المسموح بها. وتحاول عملية التعديل هذه الحفاظ على الغرض الأصلي للتصميم وإحساسه قدر الإمكان.

استخدام Envelope VibrationEffects

للحصول على تفاصيل حول إنشاء تأثيرات شكل الموجة في المغلف، راجِع إنشاء شكل موجة اهتزاز باستخدام المغلفات.

VibrationEffect composition

تتألف تركيبة VibrationEffect من تأثير اهتزاز تم إنشاؤه باستخدام واجهة برمجة التطبيقات VibrationEffect.startComposition. تتيح واجهة برمجة التطبيقات هذه إنشاء لمسات غنية من خلال إنشاء سلسلة من العناصر الأساسية مع تأخيرات وشدة مخصّصة. ومع ذلك، يجب توخّي الحذر الشديد للتأكّد من أنّ الجهاز يتيح استخدام الميزات معًا لتجنُّب تجربة غير متسقة بشكل عام.

التوافق والمتطلبات

يتطلّب تشغيل أي VibrationEffect الحصول على إذن VIBRATE في ملف بيان التطبيق.

لا تتوافق جميع الأجهزة مع جميع ميزات واجهة برمجة التطبيقات الخاصة بالتأليف، ومن المهم التأكّد من توفّر العناصر الأساسية.

التحقّق من توفّر دعم لعناصر الاهتزاز الأساسية

يمكن استرداد معلومات حول كل عنصر أساسي باستخدام طريقة Vibrator.arePrimitivesSupported. بدلاً من ذلك، يمكن التحقّق من مجموعة من العناصر الأساسية معًا باستخدام الطريقة Vibrator.areAllPrimitivesSupported، وهذا يعادل استخدام AND مع كل عنصر أساسي.

استخدام VibrationEffect مقطوعة موسيقية

لمعرفة تفاصيل حول استخدام مقاطع VibrationEffect، يُرجى الاطّلاع على إنشاء مقاطع اهتزاز.

الاهتزازات المتواصلة والمتقطّعة والموجية

أقدم شكل من أشكال الاهتزاز المتوافق مع Android هو أنماط بسيطة لتشغيل وإيقاف الاهتزاز مع مدد زمنية قابلة للضبط. لا تتوافق واجهات برمجة التطبيقات هذه عادةً مع مبادئ تصميم ردود الفعل اللمسية لأنّها يمكن أن تنشئ ردود فعل لمسية مزعجة، لذا تجنَّب استخدامها إلا كحلّ أخير.

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

يشير النمط لمرة واحدة إلى الاهتزاز مرة واحدة لمدة N ملي ثانية.

هناك نوعان من أنماط الموجات الصوتية:

  • التوقيتات فقط: هذا النوع من أشكال الموجات هو وصف للمدّة الزمنية التي يكون فيها الجهاز مطفأً والمدّة الزمنية التي يكون فيها الجهاز مضاءً. تبدأ التوقيتات بمدة الإيقاف، وبالتالي، غالبًا ما تبدأ أنماط الموجات بقيمة صفر للإشارة إلى بدء الاهتزاز فورًا.
  • التوقيتات والسعات: يحتوي هذا النوع من أشكال الموجات على مجموعة إضافية من السعات لتتطابق مع كل رقم توقيت، بدلاً من التشغيل والإيقاف الضمنيَين في النموذج الأول. ومع ذلك، من المهم التأكّد من أنّ الجهاز يتيح التحكّم في السعة لضمان إمكانية تحقيق التوسيع المطلوب.

التوافق والمتطلبات

بما أنّ الاهتزازات المتواصلة هي أقدم أشكال الاهتزازات، فهي متوافقة مع جميع الأجهزة التي تتضمّن جهاز اهتزاز، كما هو موضّح لاحقًا في هذه الصفحة.

يتطلّب تشغيل أي مكالمات VibrationEffect أو مكالمات vibrate القديمة الحصول على إذن VIBRATE في بيان التطبيق.

عند استخدام قيم مختلفة للسعة في شكل موجي، ننصحك بشدة بالتأكّد من أنّ الجهاز يتيح التحكّم في السعة.

التحقّق من توفّر ميزة التحكّم في السعة

يتم تقريب قيم السعة غير الصفرية إلى 100% على الأجهزة التي لا تتضمّن ميزة التحكّم في السعة، لذا من المهم التحقّق من توفّر هذه الميزة باستخدام Vibrator.hasAmplitudeControl. لمزيد من التفاصيل، يُرجى الاطّلاع على عناصر التحكّم في مستوى الصوت.

عليك التفكير مليًا في ما إذا كان التأثير يتمتّع بجودة كافية بدون التحكّم في السعة. قد يكون من الأفضل الرجوع إلى اهتزاز مصمَّم بشكل صريح للتفعيل والإيقاف.

استخدام الاهتزازات المتناوبة

في مستويات حزمة تطوير البرامج (SDK) الأحدث، تم دمج جميع أوضاع الاهتزاز في فئة VibrationEffect واحدة معبّرة، حيث يتم إنشاء عمليات الاهتزاز البسيطة هذه باستخدام VibrationEffect.createOneshot أو VibrationEffect.createWaveform.

واجهات برمجة التطبيقات للإشعارات

عند تخصيص إشعارات تطبيقك، يمكنك استخدام إحدى واجهات برمجة التطبيقات التالية لربط نمط بكل قناة إشعارات:

تتّخذ كل هذه النماذج نمط موجة تشغيل وإيقاف أساسي، كما هو موضّح سابقًا، حيث يكون الإدخال الأول هو التأخير قبل تشغيل جهاز الاهتزاز.

المفاهيم العامة

تنطبق عدّة مفاهيم على مساحات عرض واجهة برمجة التطبيقات الموضّحة أعلاه.

هل يحتوي الجهاز على جهاز اهتزاز؟

يمكنك الحصول على فئة Vibrator غير فارغة من context.getSystemService(Vibrator.class). إذا لم يكن الجهاز مزوّدًا بمحرك اهتزاز، لن يكون لاستدعاء واجهات برمجة التطبيقات الخاصة بالاهتزاز أي تأثير، لذا ليس على التطبيقات وضع شرط على جميع وظائف اللمس. ومع ذلك، يمكن للتطبيق، إذا لزم الأمر، استدعاء hasVibrator() لتحديد ما إذا كان هذا الجهاز هو جهاز اهتزاز حقيقي (true) أو جهاز وهمي (false).

هل أوقف المستخدم الاهتزازات اللمسية؟

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

سمات الاهتزاز

يمكن تقديم سمات الاهتزاز (حاليًا في شكل AudioAttributes) للمساعدة في إعلام النظام بغرض الاهتزاز. ويكون هذا الإذن مطلوبًا عند بدء اهتزاز عندما يكون تطبيقك يعمل في الخلفية، لأنّه لا يمكن استخدام الاهتزازات التي تتطلّب الانتباه إلا في الخلفية.

يتم تناول عملية إنشاء AudioAttributes في مستندات الفئة الخاصة به، ويجب اعتباره اهتزازًا وليس صوتًا.

في معظم الحالات، يكون نوع المحتوى CONTENT_TYPE_SONIFICATION، وقد يكون الاستخدام بقيم مثل USAGE_ASSISTANCE_SONIFICATION للحصول على ملاحظات باللمس في المقدّمة، أو USAGE_ALARM لتلقّي تنبيه في الخلفية. لا تؤثّر إشارات الصوت في الاهتزازات.

التحكّم في المطال

إذا كان الهزّاز يتيح التحكّم في السعة، يمكنه تشغيل اهتزازات بدرجات شدة مختلفة. وهذه إمكانية مهمة لإنتاج ردود فعل لمسية غنية، فضلاً عن أنّها قد تتيح للمستخدم التحكّم في مستويات شدة ردود الفعل اللمسية التلقائية.

يمكن التحقّق من إمكانية التحكّم في السعة من خلال طلب Vibrator.hasAmplitudeControl. إذا كان جهاز الاهتزاز لا يتوافق مع ميزة تعديل السعة، سيتم ربط جميع قيم السعة بحالة الإيقاف/التشغيل استنادًا إلى ما إذا كانت القيمة صفرًا أو غير صفر. وبالتالي، يجب على التطبيقات التي تستخدم ميزة "اللمس الغني" مع سعات مختلفة إيقافها إذا كان الجهاز لا يتضمّن إمكانية التحكّم في السعة.

إتاحة تأثيرات المغلف

تتيح المحركات الاهتزازية التي تتوافق مع تأثيرات التغليف إنشاء اهتزازات أكثر ديناميكية ودقة، ما يوفّر تحكّمًا أكثر دقة في الشدة والحدة للحصول على تجارب لمسية أكثر ثراءً. استخدِم Vibration.areEnvelopeEffectsSupported لتحديد ما إذا كان جهازك يتوافق مع هذه الميزة. وفي حال عدم توفّرها، يتم تجاهل الاهتزازات المستندة إلى الغلاف.