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

Envelope VibrationEffect

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

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

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

للتحقّق من توفّر تأثيرات المظروف، يُرجى الاتصال بالرقم Vibrator.areEnvelopeEffectsSupported().

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

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

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

أداة إنشاء مغلفات الأشكال الموجية

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

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

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

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

استخدام تأثيرات اهتزاز الغلاف

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

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. إذا لم يكن جهاز الاهتزاز متوافقًا مع مقياس الشدة، سيتم ربط جميع قيم الشدة بحالة "إيقاف" أو "تشغيل" استنادًا إلى ما إذا كانت صفر/غير صفرية. نتيجةً لذلك، يجب أن تفكر التطبيقات التي تستخدم تقنية لمس حسية غنية مع اتّجاهات مختلفة في إيقافها إذا كان الجهاز لا يتضمّن ميزة التحكّم في السعة.

التوافق مع تأثيرات المغلّفات

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