مرجع Android haptics API

این بخش به معرفی API های لمسی مختلف موجود در اندروید می پردازد. همچنین زمان و نحوه بررسی پشتیبانی از هر دستگاهی را که برای اطمینان از پخش جلوه‌های لمسی شما به دلخواه شما ضروری است، پوشش می‌دهد.

چندین روش مختلف برای ایجاد جلوه های لمسی وجود دارد و هنگام انتخاب از بین آنها، رعایت اصول طراحی لمسی اندروید بسیار مهم است. جدول زیر این ویژگی های سطح بالای هر رویکرد را خلاصه می کند:

• در دسترس بودن به ویژه هنگام برنامه ریزی مجدد رفتار مهم است و باید با بررسی پشتیبانی دستگاه جداگانه ترکیب شود.
• لمسی شفاف، احساسات واضح و تمیزی هستند که کمتر برای کاربران آزاردهنده هستند.
• لمسی های غنی بیانگر بیشتری دارند و اغلب به سخت افزار با ویژگی های بیشتری نیاز دارند.

علاوه بر این، API های اعلان ، که در این صفحه توضیح داده شده اند، به شما امکان می دهند جلوه های لمسی را که برای اعلان های دریافتی پخش می شوند، سفارشی کنید.

همچنین در این صفحه مفاهیم اضافی توضیح داده شده است که سطوح API را در بر می گیرد:

• آیا دستگاه ویبراتور دارد؟
• کنترل دامنه اجازه می دهد تا جلوه های لمسی روان تر و غنی تر داشته باشید، اما توسط همه دستگاه ها پشتیبانی نمی شود.
• VibrationAttributes() به شما کمک می کند لرزش را بر اساس کاربرد آن طبقه بندی کنید، اطمینان حاصل کنید که تنظیمات کاربر مناسب روی آن اعمال می شود و بنابراین از تعجب کاربر جلوگیری می کند.

HapticFeedbackConstants

کلاس HapticFeedbackConstants ثابت‌های مبتنی بر کنش را فراهم می‌کند تا به برنامه‌ها اجازه دهد بازخورد لمسی را که در سراسر تجربه دستگاه سازگار است، اضافه کنند، به‌جای اینکه هر برنامه جلوه‌های متفاوتی برای اقدامات معمول داشته باشد.

سازگاری و الزامات

استفاده از روش View.performHapticFeedback با این ثابت ها نیازی به مجوز خاصی برای برنامه ندارد. تابع ویژگی View.hapticFeedbackEnabled است، که اگر روی false تنظیم شود، همه تماس‌های بازخورد لمسی، از جمله تماس‌های پیش‌فرض، غیرفعال می‌شود. تنظیم اولیه مربوط به ویژگی View.hapticFeedbackEnabled ، که اگر روی false تنظیم شود، همه تماس‌های بازخورد لمسی غیرفعال می‌شود. در نما، از جمله موارد پیش فرض. این روش همچنین تنظیمات سیستم کاربر را برای فعال کردن بازخورد لمسی مورد احترام قرار می دهد.

تنها مورد توجه سازگاری، سطح SDK ثابت خاص برای عمل است.

هنگام استفاده از HapticFeedbackConstants نیازی به ارائه رفتار بازگشتی نیست.

استفاده از HapticsFeedbackConstants

برای جزئیات استفاده از HapticFeedbackConstants ، به افزودن بازخورد لمسی به رویدادها مراجعه کنید.

VibrationEffect از پیش تعریف شده

کلاس VibrationEffect چندین ثابت از پیش تعریف شده مانند CLICK ، TICK و DOUBLE_CLICK را ارائه می دهد. این اثرات ممکن است برای دستگاه بهینه شده باشند.

سازگاری و الزامات

پخش هر گونه VibrationEffect به مجوز VIBRATE در مانیفست برنامه نیاز دارد.

هنگام استفاده از VibrationEffect از پیش تعریف شده، نیازی به ارائه رفتار بازگشتی نیست، زیرا ثابت‌هایی که پیاده‌سازی بهینه‌سازی شده برای دستگاه ندارند، به یک پلتفرم بازگشتی استاندارد برمی‌گردند.

APIهای Vibrator.areEffectsSupported و Vibrator.areAllEffectsSupported برای تعیین اینکه آیا پیاده سازی بهینه شده برای دستگاه وجود دارد یا خیر. جلوه‌های از پیش تعریف‌شده همچنان می‌توانند بدون اجرای بهینه‌سازی شده استفاده شوند و از پلتفرم استاندارد بازگشتی استفاده می‌کنند. در نتیجه، این APIهای areEffectsSupported تنها زمانی مورد نیاز هستند که برنامه‌ای بخواهد در نظر بگیرد که آیا افکت برای دستگاه بهینه شده است یا خیر.

روش‌های بررسی اثر می‌توانند یکی از سه مقدار را برگردانند:

• VIBRATION_EFFECT_SUPPORT_YES نشان می دهد که دستگاه از این جلوه پشتیبانی بهینه کرده است.
• VIBRATION_EFFECT_SUPPORT_NO نشان می دهد که دستگاه پشتیبانی بهینه ندارد، اما همچنان از پلتفرم بازگشتی استفاده می کند.
• VIBRATION_EFFECT_SUPPORT_UNKNOWN نشان می دهد که سیستم نمی داند که آیا پیاده سازی بهینه شده است یا خیر.

از آنجایی که مقدار UNKNOWN نشان می‌دهد که API در حال بررسی در دسترس نیست، معمولاً برای همه افکت‌ها یا هیچ یک از آنها برگردانده می‌شود. این دستگاه ها به صورت پویا عقب می افتند.

استفاده از VibrationEffect از پیش تعریف شده

برای جزئیات بیشتر در مورد استفاده از VibrationEffect از پیش تعریف شده، به استفاده از VibrationEffect از پیش تعریف شده برای ایجاد بازخورد لمسی مراجعه کنید.

ترکیب VibrationEffect

ترکیب VibrationEffect یک افکت لرزشی است که با استفاده از VibrationEffect.startComposition API ایجاد می شود. این API با ایجاد دنباله‌ای از موارد اولیه با تأخیرها و شدت‌های سفارشی‌شده، اجازه می‌دهد لمسی غنی بیانگر را ایجاد کند. با این حال، مراقب باشید تا مطمئن شوید که دستگاه از ویژگی‌های ترکیب شده پشتیبانی می‌کند تا از یک تجربه کلی ناسازگار جلوگیری شود.

سازگاری و الزامات

پخش هر گونه VibrationEffect به مجوز VIBRATE در مانیفست برنامه نیاز دارد.

همه دستگاه‌ها از همه ویژگی‌های ترکیب API پشتیبانی نمی‌کنند، و مهم است که اطمینان حاصل شود که اولیه‌ها در دسترس هستند.

پشتیبانی اولیه ارتعاشی را بررسی کنید

پشتیبانی Per-primitive را می توان با استفاده از روش Vibrator.arePrimitivesSupported بازیابی کرد. از طرف دیگر، ممکن است مجموعه‌ای از اولیه‌ها با استفاده از روش Vibrator.areAllPrimitivesSupported با هم بررسی شوند - این معادل AND -ing پشتیبانی از هر ابتدایی است.

استفاده از ترکیبات VibrationEffect

برای جزئیات در مورد استفاده از ترکیب‌های VibrationEffect ، به ایجاد ترکیب‌های لرزشی مراجعه کنید.

ارتعاشات روشن خاموش، تک شات و شکل موج

قدیمی ترین شکل لرزش پشتیبانی شده در اندروید، الگوهای روشن و خاموش ویبراتور ساده با مدت زمان قابل تنظیم است. این APIها معمولاً به خوبی با اصول طراحی Haptics همسو نیستند، زیرا می توانند هاپتیک های وزوز ایجاد کنند. از آنها اجتناب کنید مگر به عنوان آخرین راه حل.

رایج‌ترین مورد استفاده برای لرزش‌های روشن و خاموش، اعلان‌ها است، جایی که، مهم نیست که چه چیزی، کمی لرزش مورد نظر است. ارتعاشات شکل موج همچنین به طور منحصر به فردی به یک الگو اجازه می دهد تا به طور نامحدود تکرار شود، همانطور که ممکن است برای یک آهنگ زنگ تصور کنید.

الگوی تک شات به لرزش یک بار برای N میلی ثانیه اشاره دارد.

دو نوع الگوی شکل موج وجود دارد:

• فقط زمان‌بندی این نوع شکل موج توصیفی از مدت زمان های متناوب صرف شده و مدت زمان صرف شده در آن است. زمان بندی ها با مدت زمان صرف شده شروع می شود. در نتیجه، الگوهای شکل موج اغلب با مقدار صفر شروع می شوند تا نشان دهند که بلافاصله شروع به ارتعاش می کنند.
• زمان ها و دامنه ها. این نوع شکل موج دارای یک آرایه دامنه اضافی برای مطابقت با هر رقم زمان بندی است، به جای روشن و خاموش شدن ضمنی شکل اول. با این حال، مهم است که بررسی کنید که دستگاه از کنترل دامنه پشتیبانی می کند تا مطمئن شوید که مقیاس مورد نظر می تواند به دست آید.

سازگاری و الزامات

از آنجایی که ارتعاشات روشن و خاموش قدیمی‌ترین شکل ارتعاش هستند، این لرزش‌ها تقریباً در همه دستگاه‌های دارای ویبراتور پشتیبانی می‌شوند، همانطور که در ادامه این صفحه توضیح داده شد.

پخش هر گونه VibrationEffect یا تماس‌های vibrate قدیمی‌تر، به مجوز VIBRATE در مانیفست برنامه نیاز دارد.

هنگام استفاده از مقادیر دامنه مختلف در یک شکل موج، ما قویاً به شما توصیه می کنیم که دستگاه از کنترل دامنه پشتیبانی کند.

پشتیبانی از کنترل دامنه را بررسی کنید

مقادیر دامنه غیرصفر در دستگاه‌های بدون کنترل دامنه تا 100% گرد می‌شوند، بنابراین مهم است که با استفاده از Vibrator.hasAmplitudeControl بررسی کنید که آیا پشتیبانی وجود دارد یا خیر. برای جزئیات بیشتر به کنترل دامنه مراجعه کنید.

شما باید به دقت بررسی کنید که آیا اثر شما بدون کنترل دامنه کیفیت کافی دارد یا خیر. بازگشت به ارتعاش روشن و خاموش که به وضوح طراحی شده است ممکن است بهتر باشد.

استفاده از ارتعاشات روشن و خاموش

در سطوح جدیدتر SDK، همه حالت‌های ارتعاش در یک کلاس VibrationEffect بیانگر ادغام شدند، جایی که این ارتعاشات ساده با استفاده از VibrationEffect.createOneshot یا VibrationEffect.createWaveform ایجاد می‌شوند.

API های اعلان

هنگام سفارشی‌سازی اعلان‌های برنامه، می‌توانید از یکی از APIهای زیر برای مرتبط کردن یک الگو با هر کانال اعلان استفاده کنید:

• AndroidX
  • NotificationChannelCompat.Builder.setVibrationPattern
  • NotificationCompat.setVibrate
• اندروید
  • NotificationChannel.setVibrationPattern
  • (منسوخ شده) NotificationBuilder.setVibrate

همه این فرم ها یک الگوی اولیه شکل موج روشن و خاموش دارند، همانطور که قبلا توضیح داده شد، که در آن اولین ورودی تاخیر قبل از روشن کردن ویبراتور است.

مفاهیم کلی

چندین مفهوم در سطوح API که در بالا توضیح داده شد اعمال می شود.

آیا دستگاه ویبراتور دارد؟

می توانید یک کلاس Vibrator غیر تهی را از context.getSystemService(Vibrator.class) دریافت کنید. اگر دستگاه لرزاننده نداشته باشد، تماس‌ها با APIهای لرزشی هیچ تأثیری ندارند، بنابراین برنامه‌ها نیازی به گیت کردن تمام بخش‌های لمسی خود در شرایط خاص ندارند. با این حال، در صورت نیاز، یک برنامه کاربردی می‌تواند hasVibrator() فراخوانی کند تا مشخص کند که آیا این ویبراتور واقعی ( true ) است یا یک خرد ( false ).

آیا کاربر لمس لمسی را غیرفعال کرده است؟

برخی از پیاده‌سازی‌های سفارشی ممکن است نیاز به بررسی دستی داشته باشند که آیا کاربر تنظیمات بازخورد لمسی Android را به طور کامل غیرفعال کرده است یا خیر، در این صورت باید جلوه‌های بازخورد لمسی را حذف کرد. این تنظیم را می توان با استفاده از کلید HAPTIC_FEEDBACK_ENABLED جستجو کرد، جایی که مقدار صفر به معنای غیرفعال است.

ویژگی های ارتعاش

ویژگی‌های ارتعاش (در حال حاضر به شکل AudioAttributes ) می‌تواند برای کمک به اطلاع رسانی سیستم از هدف ارتعاش ارائه شود. هنگامی که برنامه شما در پس‌زمینه است، هنگام شروع لرزش لازم است، زیرا فقط لمسی‌های توجهی برای استفاده در پس‌زمینه پشتیبانی می‌شوند.

ایجاد AudioAttributes در مستندات کلاس آن پوشش داده شده است و باید به جای صدا به عنوان لرزش در نظر گرفته شود.

به عنوان راهنما، در بیشتر موارد، نوع محتوا CONTENT_TYPE_SONIFICATION است و میزان استفاده ممکن است مقادیری مانند USAGE_ASSISTANCE_SONIFICATION برای بازخورد لمسی در پیش‌زمینه یا USAGE_ALARM برای زنگ هشدار در پس‌زمینه باشد. پرچم های صوتی هیچ تاثیری روی ارتعاشات ندارند.

کنترل دامنه

اگر ویبراتور دارای کنترل دامنه باشد، می تواند ارتعاشات را با شدت های مختلف پخش کند. این یک قابلیت مهم برای تولید لمسی غنی و همچنین امکان کنترل بالقوه شدت لمسی پیش‌فرض توسط کاربر است.

پشتیبانی از کنترل دامنه را می توان با تماس با Vibrator.hasAmplitudeControl بررسی کرد. اگر ویبراتور پشتیبانی دامنه نداشته باشد، همه مقادیر دامنه بر اساس صفر یا غیرصفر بودن آنها به حالت خاموش/روشن نگاشت می شوند . در نتیجه، برنامه‌هایی که از هاپتیک غنی با دامنه‌های متفاوت استفاده می‌کنند، در صورتی که دستگاه فاقد کنترل دامنه باشد، باید آن‌ها را غیرفعال کنند.