הפניית API של Android haptics

בקטע הזה מוסבר על ממשקי ה-API השונים של Haptics שזמינים ב-Android. בנוסף, מוסבר בה מתי ואיך לבדוק אם יש תמיכה במכשיר שנדרשת כדי לוודא שהאפקטים המישושיים יפעלו כמו שרוצים.

יש כמה דרכים שונות ליצור אפקטים של משוב מישוש, וחשוב להביא בחשבון את עקרונות העיצוב של משוב מישוש ב-Android כשבוחרים ביניהם. בטבלה הבאה מסוכמים המאפיינים הכלליים של כל אחת מהגישות:

  • הזמינות חשובה במיוחד כשמתכננים חזרה להתנהגות ברירת המחדל, וצריך לשלב אותה עם בדיקת התמיכה במכשיר ספציפי.
  • משוב פיזי ברור הוא תחושות חדות ונקיות שפחות מטרידות את המשתמשים.
  • משוב פיזי עשיר הוא יותר מגוון ולרוב דורש חומרה עם יותר תכונות.
פלטפורמת ה-API זמינות מחיקת המשוב הפיזי משוב פיזי עשיר
HapticFeedbackConstants ‫Android 1.5 ואילך
(לכל קבוע)
Predefined VibrationEffect ‫Android 10 ואילך
VibrationEffect הרכב (מועדף) ‫Android 16 ואילך (26Q4)
VibrationEffect primitives composition ‫Android מגרסה 11 ואילך (לכל קבוע)
רטט הפעלה/השבתה, רטט חד-פעמי ורטט של צורת גל ‫Android 1

בנוסף, ממשקי API של התראות, שמתוארים בדף הזה, מאפשרים לכם להתאים אישית את האפקטים של המשוב המישוש שמופעלים כשמתקבלות התראות.

בדף הזה מתוארים גם מושגים נוספים שרלוונטיים לכל ממשקי ה-API:

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 נדרשים רק אם האפליקציה רוצה לקחת בחשבון אם האפקט עבר אופטימיזציה למכשיר או לא.

השיטות לבדיקת ההשפעה יכולות להחזיר אחד משלושה ערכים:

הערך UNKNOWN מציין שה-API לבדיקה לא זמין, ולכן הוא מוחזר בדרך כלל לכל האפקטים או לאף אחד מהם. המכשירים האלה חוזרים באופן דינמי לגרסה הקודמת.

שימוש ב-VibrationEffect שהוגדרו מראש

פרטים על שימוש בVibrationEffect מוגדר מראש זמינים במאמר שימוש בVibrationEffect מוגדר מראש ליצירת משוב הפטי.

Envelope VibrationEffect

רטט מבוסס-מעטפת מאפשר שליטה מדויקת במשרעת ובתדירות של הרטט לאורך זמן, על ידי הגדרת רצף של נקודות בקרה. כך מפתחים יכולים ליצור חוויות עשירות ומורכבות יותר של משוב הפטי. אפשר ליצור את הרטטים האלה באמצעות המחלקות BasicEnvelopeBuilder ו-WaveformEnvelopeBuilder.

תאימות ודרישות

כדי להפעיל אפקטים של רטט, האפליקציה צריכה להצהיר על ההרשאה VIBRATE בקובץ מניפסט של אפליקציה.

כדי לבדוק אם יש תמיכה באפקטים של מעטפות, מתקשרים אל Vibrator.areEnvelopeEffectsSupported().

כלי בסיסי ליצירת מעטפות

כדי ליצור חוויה חלקה ורציפה של משוב הפטי, אפקטים של מעטפת צריכים להתחיל ולהסתיים בעוצמה של \( 0.0 \). ה-API אוכף את זה על ידי הגדרת עוצמת ההתחלה לאפס, וזורק חריגה אם עוצמת הסיום לא אפס. המגבלה הזו מונעת אפקטים דינמיים לא רצויים ברעידות, בגלל חוסר רציפות במשרעת שעלול לפגוע בתפיסה המישושית של המשתמש.

כדי לספק עיבוד עקבי של אפקט המעטפת בכל המכשירים, נדרש שהמכשירים שתומכים בתכונה הזו יוכלו לטפל במשך מינימלי של 20 אלפיות השנייה בין נקודות הבקרה, ולפחות ב-16 נקודות לאפקטים של מעטפת.

Waveform Envelope Builder

המסגרת לא משנה את ערכי התדירות והאמפליטודה שסופקו על ידי המפתח. עם זאת, ה-API גם מתקן את אמפליטודת ההתחלה לאפס כדי ליצור מעברים חלקים.

כדי לעזור לכם לבצע אופטימיזציה של אפקטים של מעטפת צורת גל באפליקציה ולספק תאימות בין מכשירים, מערכת Android מספקת ממשקי API לשאילתות לגבי יכולות חשובות של המכשיר. השיטות האלה מספקות מידע על המגבלות של המכשיר, כמו משך המעבר המקסימלי והמינימלי בין נקודות בקרה ומספר נקודות הבקרה המקסימלי שנתמכות לאפקט יחיד:

getMaxSize()
מאחזר את המספר המקסימלי של נקודות בקרה שנתמכות באפקט של מעטפת.
getMinControlPointDurationMillis()
מאחזר את משך הזמן המינימלי הנתמך, באלפיות השנייה, בין שתי נקודות בקרה באפקט של מעטפת.
getMaxControlPointDurationMillis()
מאחזר את משך הזמן המקסימלי הנתמך, באלפיות השנייה, בין שתי נקודות בקרה בתוך אפקט מעטפה.
getMaxDurationMillis()
‫
Retrieves the maximum duration supported for an envelope effect, in milliseconds.

אם אפקט חורג מהמגבלות של המכשיר – למשל אם הוא מאפשר יותר מדי נקודות בקרה או משך זמן שחורג מהמקסימום – המסגרת מתאימה את האפקט באופן אוטומטי כדי שלא יחרוג מהגבולות המותרים. במהלך תהליך ההתאמה, המערכת מנסה לשמור על הכוונה המקורית ועל התחושה של העיצוב ככל האפשר.

שימוש באפקטים של רטט במעטפה

לפרטים על יצירת אפקטים של צורת גל של מעטפת, אפשר לעיין במאמר בנושא יצירת צורת גל של רטט באמצעות מעטפות.

VibrationEffect יצירה מוזיקלית

החל מ-Android 16 (רבעון 4 של 2026),‏ VibrationEffect.Builder הוא ה-API המועדף ליצירת אפקטים עשירים ובעלי הבעה של משוב הפטי על ידי סידור של כמה אלמנטים הפטיים לאורך ציר זמן מתוכנן. הוא מחליף את VibrationEffect.Composition כי הוא מציע תזמון שמוגדר לפי ציר זמן, אנקפסולציה אטומית, תמיכה באירועים מעורבים (שילוב של הגדרות קבועות מראש ומעטפות) ונסיגה אוטומטית מובנית.

אבני בניין

הכלי מאפשר לכם ליצור רצף של הרכיבים הבאים של משוב הפטי:

  • ‫VibrationEffect.Preset: תחושות מישוש מוגדרות מראש שמייצגות פולסים קצרים נפוצים, כמו PRESET_CLICK, ‏PRESET_TICK ו-PRESET_LOW_TICK. הגדרות קבועות מראש מחליפות את הפרימיטיבים הקצרים מ-VibrationEffect.Composition API. כדי ליצור אפקטים ארוכים יותר, רציפים או מתגברים (שבעבר נוצרו באמצעות rise,‏ fall ופרימיטיבים אחרים), משתמשים במקום זאת במעטפות (PWLE). אפשר לשנות את ההגדרות הקבועות מראש מ-0.0f ל-1.0f באמצעות Preset.create(presetId, scale).
  • ‫VibrationEffect.Envelope: מעטפות ליניאריות מקוטעות (PWLE) שנוצרו באמצעות BasicEnvelopeBuilder (עם עוצמה וחדות) או WaveformEnvelopeBuilder (עם תדירות ואמפליטודה). המעטפות נוצרות באמצעות Envelope.create(builder).
  • ‫VibrationEffect.Event: אירועים בציר הזמן שאוחזרו מVibrationEffect קיים באמצעות getEvents(). אפשר להוסיף אותם עם היסט של ציר הזמן באמצעות addEvents(startTimeShiftMillis, events).

תזמון ואימות של ציר זמן

כל רכיב מתווסף לכלי עם הערך startTimeMillis שמייצג את הזמן שחלף (באלפיות השנייה) מתחילת היצירה:

  • אימות בזמן הבנייה: צריך להוסיף את האלמנטים בסדר עולה של זמני ההתחלה שלהם. הכלי לבניית אפליקציות מבצע אימות מיטבי בזמן הבנייה על ידי בדיקה של משך הזמן המינימלי (למשל, מילישנייה אחת להגדרות קבועות מראש או משכי זמן ידועים למעטפות). אם מזוהה חפיפה בזמן הבנייה, מוצגת שגיאת IllegalArgumentException.
  • התאמה של תזמון ההפעלה: המסגרת מספקת תמיכה בתזמון כמיטב היכולת במהלך ההפעלה. אם אירוע קודם עדיין פועל כשמגיע זמן ההתחלה של האירוע המתוזמן הבא, המסגרת מעבירה אוטומטית את האירוע הבא למשבצת הזמן הפנויה המוקדמת ביותר. כך נמנע חפיפה בין אירועים במהלך הפעלה פיזית, ומוודאים שלא יושמטו אירועים של משוב הפטי.

אפקטים חוזרים

אפשר להוסיף אפקט שחוזר על עצמו לקומפוזיציה באמצעות setRepeatingEffect(startTimeMillis, repeatingEffect, durationMillis). אחרי שמגדירים אפקט חוזר, אי אפשר להוסיף עוד רכיבים לכלי ליצירת סרטונים.

תמיכה בגיבוי

תמיכה אוטומטית בחזרה למצב קודם ברמת המסגרת מופעלת כברירת מחדל עבור רטט שנוצר על ידי VibrationEffect.Builder:

  • מעבר שקוף לפלטפורמה חלופית: אם מכשיר לא תומך ב-Preset או ב-Envelope שנדרשים, המסגרת מחליפה באופן אוטומטי את הרכיב שלא נתמך ברטט מתאים שנתמך בזמן הריצה, כמיטב היכולת. האפליקציה לא צריכה לבדוק באופן ידני את היכולות של המכשיר (למשל isPresetSupported) לפני הפעלת קומפוזיציות שנוצרו באמצעות VibrationEffect.Builder.
  • חריג לגבי WaveformEnvelopeBuilder: לאפקטים של מעטפת שנוצרו על ידי WaveformEnvelopeBuilder (שמציינים תדרים פיזיים מוחלטים בהרץ ואמפליטודות ב-G) אין תמיכה אוטומטית בגיבוי. מכיוון ש-PWLE מתקדמים מסתמכים על עקומות תדר של חומרה ספציפית (FOAM), החלפה אוטומטית שלהם תפגע בכוונת העיצוב. אם המכשיר לא תומך באפקטים של PWLE או בתדרים המבוקשים, הרטט לא יופעל. לשם תאימות אוניברסלית, מומלץ להשתמש ב-BasicEnvelopeBuilder.

שימוש ב-VibrationEffect.Builder

דוגמאות לקוד ליצירת אפקטים באמצעות VibrationEffect.Builder זמינות במאמר יצירת קומפוזיציות שמעוגנות לציר הזמן באמצעות VibrationEffect.Builder.

VibrationEffect primitives composition

קומפוזיציה של פרימיטיבים VibrationEffect היא אפקט של רטט שנוצר באמצעות VibrationEffect.startComposition API. ה-API הזה מאפשר ליצור רצף של פרימיטיבים.

תאימות ודרישות

כדי להפעיל VibrationEffect כלשהו, צריך את ההרשאה VIBRATE במניפסט של האפליקציה.

בדיקת התמיכה בפרימיטיבים

לכן, כשמשתמשים ב-VibrationEffect.Composition API, צריך לבדוק את התמיכה בכל פרימיטיב באמצעות Vibrator.arePrimitivesSupported או Vibrator.areAllPrimitivesSupported לפני ההפעלה.

אפשר לאחזר את התמיכה בכל פרימיטיב באמצעות השיטה Vibrator.arePrimitivesSupported. לחלופין, אפשר לבדוק כמה פרימיטיבים ביחד באמצעות ה-method‏ Vibrator.areAllPrimitivesSupported. זה שווה ערך ל-method‏ AND לבדיקת התמיכה בכל פרימיטיב.

שימוש בקומפוזיציות של פרימיטיבים VibrationEffect

פרטים על השימוש בפרימיטיבים של VibrationEffect זמינים במאמר יצירת קומפוזיציות של פרימיטיבים של רטט.

רטט עם הפעלה והשבתה, רטט חד-פעמי ורטט של צורת גל

הצורה הכי ישנה של רטט שנתמכת ב-Android היא דפוסי הפעלה וכיבוי פשוטים של הרטט עם משכי זמן שניתנים להגדרה. בדרך כלל, ממשקי ה-API האלה לא מתאימים לעקרונות העיצוב של אפקטים הפטיים כי הם יכולים ליצור אפקטים הפטיים רועשים. כדאי להימנע מהם, אלא אם אין ברירה אחרת.

התרחיש הנפוץ ביותר לשימוש ברטט לסירוגין הוא התראות, שבהן רצוי שיהיה רטט כלשהו, לא משנה מה. רטטים של צורת גל מאפשרים גם חזרה אינסופית על תבנית, כמו שאפשר לדמיין לגבי רינגטון.

תבנית חד-פעמית מתייחסת לרטט חד-פעמי למשך N אלפיות השנייה.

יש שני סוגים של דפוסי צורת גל:

  • תזמונים בלבד. צורת הגל הזו היא תיאור של משכי זמן לסירוגין שבהם המכשיר כבוי, ומשכי זמן שבהם הוא פועל. התזמונים מתחילים עם משך הזמן שבו המכשיר כבוי. לכן, דפוסי צורת הגל מתחילים לעיתים קרובות עם ערך אפס כדי לציין שהמכשיר צריך להתחיל לרטוט באופן מיידי.
  • תזמונים ואמפליטודות. לצורת גל כזו יש מערך נוסף של אמפליטודות שמתאים לכל נתון תזמון, ולא רק מצב מרומז של הפעלה או השבתה כמו בצורה הראשונה. עם זאת, חשוב לבדוק שהמכשיר תומך בשליטה בעוצמת הקול כדי לוודא שאפשר להשיג את ההתאמה הרצויה.

תאימות ודרישות

רטט עם מצב הפעלה ומצב השבתה הוא הצורה הכי ישנה של רטט, ולכן הוא נתמך כמעט בכל המכשירים עם מנגנון רטט, כמו שמתואר בהמשך הדף הזה.

כדי להפעיל שיחות מסוג VibrationEffect או שיחות בסגנון הישן vibrate, צריך להגדיר את ההרשאה VIBRATE בקובץ המניפסט של האפליקציה.

כשמשתמשים בערכי אמפליטודה שונים בצורת גל, מומלץ מאוד לוודא שהמכשיר תומך בשליטה באמפליטודה.

בדיקה אם יש תמיכה בבקרה על עוצמת הקול

ערכי אמפליטודה שאינם אפס מעוגלים כלפי מעלה ל-100% במכשירים ללא שליטה באמפליטודה, ולכן חשוב לבדוק אם התמיכה קיימת באמצעות Vibrator.hasAmplitudeControl. פרטים נוספים זמינים במאמר בנושא שליטה בעוצמת הקול.

כדאי לשקול היטב אם לאפקט יש איכות מספקת בלי שליטה בעוצמת הקול. יכול להיות שעדיף להשתמש ברטט שנועד במפורש להפעלה או להשבתה.

שימוש ברטט עם הפעלה והשבתה

ברמות חדשות יותר של SDK, כל מצבי הרטט אוחדו לקטגוריה אחת של VibrationEffect, שבה נוצרים הרטטים הפשוטים האלה באמצעות VibrationEffect.createOneShot או VibrationEffect.createWaveform.

ממשקי API של התראות

כשמתאימים אישית את ההתראות באפליקציה, אפשר להשתמש באחד מממשקי ה-API הבאים כדי לשייך תבנית לכל ערוץ התראות:

כל הטפסים האלה מקבלים דפוס בסיסי של צורת גל של הפעלה והשבתה, כמו שמתואר קודם, שבו הרשומה הראשונה היא העיכוב לפני הפעלת הרטט.

מושגים כלליים

יש כמה מושגים שרלוונטיים לכל ממשקי ה-API שמפורטים למעלה.

האם במכשיר יש מנגנון רטט?

אפשר לקבל כיתה Vibrator שאינה null מ-context.getSystemService(Vibrator.class). אם למכשיר אין מנגנון רטט, לקריאות לממשקי ה-API של הרטט אין השפעה, ולכן האפליקציות לא צריכות להגביל את כל הרטטים שלהן בתנאי. עם זאת, אם יש צורך, אפליקציה יכולה לקרוא ל-hasVibrator() כדי לקבוע אם מדובר בויברטור אמיתי (true) או ב-stub (false).

האם המשתמש השבית את התכונה 'תחושת מגע'?

ביישומים מותאמים אישית מסוימים, יכול להיות שיהיה צורך לבדוק באופן ידני אם המשתמש השבית לחלוטין את ההגדרה תגובה למגע ב-Android. במקרה כזה, צריך להשבית את האפקטים של התגובה למגע. אפשר לשלוח שאילתה לגבי ההגדרה הזו באמצעות המפתח HAPTIC_FEEDBACK_ENABLED, כאשר ערך של אפס מציין שההגדרה מושבתת.

מאפייני הרטט

אפשר לספק מאפייני רטט (כרגע בצורה של AudioAttributes) כדי לעזור למערכת להבין את מטרת הרטט. ההרשאה הזו נדרשת כשמפעילים רטט כשהאפליקציה פועלת ברקע, כי רק רטט שמושך את תשומת הלב נתמך לשימוש ברקע.

היצירה של AudioAttributes מוסברת במסמכי התיעוד של המחלקה, וצריך להתייחס אליה כאל רטט ולא כאל צליל.

ככלל, ברוב המקרים סוג התוכן הוא CONTENT_TYPE_SONIFICATION, והשימוש יכול להיות ערכים כמו USAGE_ASSISTANCE_SONIFICATION עבור משוב מגע בחזית, או USAGE_ALARM עבור אזעקה ברקע. הסימון של אודיו לא משפיע על הרטט.

שליטה בעוצמה

אם יש בויברטור בקרת אמפליטודה, הוא יכול להפעיל רטטים בעוצמות שונות. זו יכולת חשובה ליצירת משוב הפטי עשיר, וגם לאפשרות של המשתמשים לשלוט בעוצמות ברירת המחדל של המשוב ההפטי.

כדי לבדוק אם יש תמיכה בשליטה בעוצמת הקול, אפשר להתקשר אל Vibrator.hasAmplitudeControl. אם למנגנון הרטט אין תמיכה באמפליטודה, כל ערכי האמפליטודה ימופו למצב 'מופעל' או 'מושבת' בהתאם לערך שלהם – אפס או לא אפס. לכן, אם באפליקציות נעשה שימוש במשוב פיזי עשיר עם אמפליטודות משתנות, כדאי להשבית אותן אם במכשיר אין אמצעי בקרה על האמפליטודה.

תמיכה באפקטים של מעטפות

אפקטים של מעטפת תומכים במנגנוני רטט ומאפשרים ליצור רטטים דינמיים ומדויקים יותר, וכך לשלוט בצורה מדויקת יותר בעוצמה ובחדות של הרטט וליהנות מחוויה מישושית עשירה יותר. כדי לבדוק אם המכשיר שלכם תומך בתכונה הזו, אפשר להיעזר ב-Vibration.areEnvelopeEffectsSupported. אם לא, המערכת מתעלמת מהרטט שמבוסס על מעטפה.