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

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

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

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

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

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

  • هل يحتوي الجهاز على هزاز؟
  • تتيح ميزة التحكّم في الشدة الحصول على تأثيرات لمسية أكثر سلاسة وإثارة، ولكنّها غير متاحة على بعض الأجهزة.
  • يساعدك VibrationAttributes() في تصنيف الاهتزاز استنادًا إلى استخدامه، ما يضمن تطبيق إعدادات العميل المناسبة عليه وبالتالي تجنُّب مفاجآت العميل.

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 محدّد مسبقًا لإنشاء ردود فعل لمسية.

VibrationEffect تركيبة

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

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

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

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

التحقّق من توفّر واجهة برمجة تطبيقات أساسية للاهتزاز

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

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

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

اهتزازات التشغيل والإيقاف والاهتزازات لمرة واحدة وأشكال الموجات

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

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

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

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

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

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

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

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

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

التحقّق من توفّر ميزة التحكّم في الشدة

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

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

استخدام الاهتزازات المتكررة

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

Notification APIs

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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