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

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

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

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

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

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

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 في بيان التطبيق.

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

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

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

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

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

الاهتزازات التي يتم تشغيلها بدون تشتيت وحركة واحدة والشكل الموجي

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

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

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

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

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

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

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

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