Документация по Android Haptics API

В этом разделе рассказывается о различных API для тактильной обратной связи, доступных в Android. Также в нем рассказывается, когда и как проверять, поддерживается ли устройство, чтобы тактильные эффекты воспроизводились правильно.

Существует несколько способов создания тактильных эффектов, и при выборе между ними важно учитывать принципы дизайна тактильной обратной связи Android. В таблице ниже приведены основные характеристики каждого из этих подходов.

Поверхность API Доступность Отключить вибрацию Расширенная тактильная обратная связь
HapticFeedbackConstants Android 1.5+
(на константу)
Predefined VibrationEffect Android 10 и более поздние версии
VibrationEffect композиция (предпочтительно) Android 16+ (4 квартал 2026 г.)
композиция примитивов VibrationEffect 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 используются для определения того, есть ли реализация, оптимизированная для устройства. Стандартные эффекты можно использовать и без оптимизированной реализации. В этом случае будет применяться стандартный резервный вариант платформы. Таким образом, эти APIareEffectsSupported нужны только в том случае, если приложение должно учитывать, оптимизирован ли эффект для устройства.

Методы проверки эффектов могут возвращать одно из трех значений:

  • VIBRATION_EFFECT_SUPPORT_YES указывает, что устройство поддерживает этот эффект.
  • VIBRATION_EFFECT_SUPPORT_NO означает, что устройство не поддерживает оптимизированную версию, но использует резервную платформу.
  • VIBRATION_EFFECT_SUPPORT_UNKNOWN означает, что система не знает, оптимизирована ли реализация.

Поскольку значение UNKNOWN указывает на то, что API проверки недоступен, оно обычно возвращается для всех эффектов или ни для одного из них. Эти устройства переключаются на резервный вариант динамически.

Использование стандартного параметра VibrationEffect

Подробнее о том, VibrationEffect как использовать стандартный VibrationEffect для создания тактильной обратной связи…

Envelope VibrationEffect

Вибрация на основе огибающей позволяет точно управлять амплитудой и частотой вибрации с течением времени, определяя последовательность контрольных точек. Это позволяет разработчикам создавать более насыщенный и детализированный виброотклик. Эти вибрации можно создать с помощью классов BasicEnvelopeBuilder и WaveformEnvelopeBuilder.

Совместимость и требования

Чтобы воспроизводить вибрацию, приложению необходимо разрешение VIBRATE, указанное в манифесте.

Чтобы проверить, поддерживаются ли эффекты огибающей, вызовите метод Vibrator.areEnvelopeEffectsSupported().

Basic Envelope Builder

Чтобы тактильные ощущения были плавными и непрерывными, огибающие эффекты должны начинаться и заканчиваться с интенсивностью \( 0.0 \). API обеспечивает это, устанавливая начальную интенсивность на ноль и вызывая исключение, если конечная интенсивность не равна нулю. Это ограничение позволяет избежать нежелательных динамических эффектов вибрации из-за скачков амплитуды, которые могут негативно повлиять на тактильное восприятие пользователя.

Чтобы обеспечить одинаковое воспроизведение эффекта огибающей на разных устройствах, фреймворк требует, чтобы устройства, поддерживающие эту функцию, могли обрабатывать минимальную продолжительность в 20 мс между контрольными точками и не менее 16 точек для эффектов огибающей.

Конструктор огибающей сигнала

Фреймворк не изменяет запрошенные значения частоты и амплитуды, предоставленные разработчиком. Однако API также фиксирует начальную амплитуду на нуле, чтобы создать плавные переходы.

Чтобы помочь вам оптимизировать эффекты огибающей формы волны и обеспечить совместимость с разными устройствами, Android предоставляет API для запроса важных возможностей устройства. Эти методы предоставляют информацию об ограничениях устройства, например о максимальной и минимальной продолжительности перехода между контрольными точками и максимальном количестве контрольных точек, поддерживаемых для одного эффекта:

getMaxSize()
Возвращает максимальное количество опорных точек, поддерживаемых для эффекта огибающей.
getMinControlPointDurationMillis()
Возвращает минимальную поддерживаемую длительность в миллисекундах между двумя контрольными точками в эффекте огибающей.
getMaxControlPointDurationMillis()
Возвращает максимальную поддерживаемую продолжительность (в миллисекундах) между двумя контрольными точками в эффекте огибающей.
getMaxDurationMillis()
Возвращает максимальную длительность, поддерживаемую для эффекта огибающей, в миллисекундах.

Если эффект превышает ограничения устройства, например содержит слишком много контрольных точек или его продолжительность превышает максимальную, фреймворк автоматически корректирует эффект, чтобы он соответствовал допустимым границам. При этом мы стараемся сохранить исходный замысел и стиль дизайна.

Использование EnvelopeVibrationEffects

Подробнее о том, как создавать формы волны вибрации с огибающими…

VibrationEffect композиция

В Android 16 (4 квартал 2026 г.) VibrationEffect.Builder – предпочтительный API для создания сложных и выразительных тактильных эффектов путем последовательного расположения нескольких тактильных элементов на временной шкале. Он заменяет VibrationEffect.Composition, поскольку позволяет планировать события на временной шкале, атомарно инкапсулировать данные, использовать смешанные события (сочетая предустановки и огибающие) и автоматически переключаться на резервные настройки.

Блоки

Конструктор позволяет создавать последовательности из следующих тактильных элементов:

  • VibrationEffect.Preset – стандартные тактильные ощущения, представляющие собой короткие импульсы, например PRESET_CLICK, PRESET_TICK и PRESET_LOW_TICK. Наборы настроек имеют приоритет над примитивами из API VibrationEffect.Composition. Для более длинных, непрерывных или нарастающих эффектов (ранее обрабатываемых с помощью 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, которое представляет собой временной сдвиг (в миллисекундах) от начала композиции:

  • Проверка во время сборки. Элементы должны быть добавлены в порядке возрастания времени начала. При создании объекта сборщик выполняет проверку на соответствие минимальной длительности (например, 1 мс для наборов настроек или известной длительности для огибающих). Если перекрытие обнаружено во время сборки, возникает исключение IllegalArgumentException.
  • Синхронизация воспроизведения. Фреймворк обеспечивает максимально возможную синхронизацию во время воспроизведения. Если предыдущее событие ещё выполняется, когда наступает время начала следующего запланированного события, фреймворк автоматически переносит его на ближайшее доступное время. Это предотвращает перекрытие событий при воспроизведении и гарантирует, что ни одно из них не будет пропущено.

Повторяющиеся эффекты

Повторяющийся эффект можно добавить в композицию с помощью значка setRepeatingEffect(startTimeMillis, repeatingEffect, durationMillis). После настройки повторяющегося эффекта в конструктор нельзя добавить дополнительные элементы.

Поддержка резервного объявления

Автоматический переход на резервный вариант на уровне фреймворка по умолчанию включен для вибрации, созданной с помощью VibrationEffect.Builder:

  • Прозрачный переход на платформу. Если устройство не поддерживает запрошенный Preset или базовый Envelope, фреймворк автоматически заменяет неподдерживаемый элемент подходящим поддерживаемым вибрационным сигналом во время выполнения. Приложению не нужно вручную проверять возможности устройства (например, isPresetSupported), прежде чем воспроизводить композиции, созданные с помощью VibrationEffect.Builder.
  • Исключение для WaveformEnvelopeBuilder. Эффекты огибающей, созданные с помощью WaveformEnvelopeBuilder (в которых абсолютные физические частоты задаются в герцах, а амплитуды – в единицах ускорения свободного падения), не поддерживают автоматический переход на резервный вариант. Поскольку расширенные PWLE зависят от определенных кривых частоты оборудования (FOAM), их автоматическая замена нарушит замысел дизайна. Если устройство не поддерживает эффекты PWLE или запрошенные частоты, вибрация не будет воспроизводиться. Для универсальной совместимости лучше использовать BasicEnvelopeBuilder.

Использование на VibrationEffect.Builder

Примеры кода для создания эффектов с помощью VibrationEffect.Builder можно найти в статье Как создавать композиции, привязанные к временной шкале, с помощью VibrationEffect.Builder.

VibrationEffect примитивов

Композиция примитивов VibrationEffect – это эффект вибрации, созданный с помощью API VibrationEffect.startComposition. Этот API позволяет создавать последовательности примитивов.

Совместимость и требования

Для воспроизведения любого VibrationEffect требуется разрешение VIBRATE в манифесте приложения.

Проверка поддержки примитивов

Поэтому при использовании API VibrationEffect.Composition перед воспроизведением необходимо проверить поддержку примитивов с помощью Vibrator.arePrimitivesSupported или Vibrator.areAllPrimitivesSupported.

Поддержку примитивов можно получить с помощью метода Vibrator.arePrimitivesSupported. Кроме того, набор примитивов можно проверить вместе, используя метод Vibrator.areAllPrimitivesSupported. Это эквивалентно операции AND для поддержки каждого примитива.

Использование композиций примитивов VibrationEffect

Подробнее о том, как использовать композиции примитивов VibrationEffect, рассказывается в статье Как создавать композиции примитивов вибрации.

Вибрация при включении и выключении, однократная вибрация и вибрация с заданной формой волны

Самый старый тип вибрации, поддерживаемый в Android, – это простые шаблоны включения и выключения вибратора с настраиваемой продолжительностью. Эти API обычно не соответствуют принципам проектирования тактильных ощущений, поскольку могут создавать вибрирующие тактильные ощущения. Используйте их только в крайнем случае.

Чаще всего вибрация используется для уведомлений, когда она должна быть включена независимо от настроек. Вибрация с формой волны также позволяет повторять шаблон бесконечно, как это происходит с мелодией звонка.

Однократная вибрация – это вибрация в течение N миллисекунд.

Существует два типа осциллограмм:

  • Только временные метки. Такая форма волны описывает чередование периодов, когда свет выключен, и периодов, когда он включен. Временные интервалы начинаются с периода, когда вибрация отключена. Поэтому часто форма волны начинается с нулевого значения, чтобы указать на необходимость немедленно начать вибрацию.
  • Временные интервалы и амплитуды. У этого типа формы волны есть дополнительный массив амплитуд, соответствующих каждому временному показателю, а не неявное включение-выключение, как в первом случае. Однако важно убедиться, что устройство поддерживает управление амплитудой, чтобы масштабирование было выполнено правильно.

Совместимость и требования

Поскольку вибрация с включением и выключением – это старейшая форма вибрации, она поддерживается практически всеми устройствами с вибратором, как описано далее на этой странице.

Для воспроизведения любых вызовов VibrationEffect или устаревших вызовов vibrate требуется разрешение VIBRATE в манифесте приложения.

При использовании в звуковой волне разных значений амплитуды мы настоятельно рекомендуем убедиться, что устройство поддерживает управление амплитудой.

Проверка поддержки управления амплитудой

На устройствах без регулировки амплитуды все ненулевые значения амплитуды округляются до 100 %, поэтому важно проверить, поддерживается ли регулировка, с помощью Vibrator.hasAmplitudeControl. Подробнее об управлении амплитудой…

Вам следует тщательно проверить, достаточно ли качественным будет эффект без контроля амплитуды. В таких случаях лучше использовать вибрацию, специально разработанную для включения и выключения.

Использование вибрации

В более новых версиях SDK все режимы вибрации объединены в один класс VibrationEffect, в котором простые вибрации создаются с помощью VibrationEffect.createOneShot или VibrationEffect.createWaveform.

API уведомлений

При настройке уведомлений в приложении можно использовать один из следующих API, чтобы связать шаблон с каждым каналом уведомлений:

Все эти формы имеют базовый шаблон формы волны включения-выключения, как описано выше, где первая запись – это задержка перед включением вибратора.

Общие понятия

Некоторые понятия применимы ко всем описанным выше API.

Есть ли на устройстве вибромотор?

Вы можете получить ненулевой класс Vibrator из context.getSystemService(Vibrator.class). Если на устройстве нет вибромотора, вызовы API вибрации не будут иметь никакого эффекта, поэтому приложениям не нужно ограничивать все свои тактильные функции условием. Однако при необходимости приложение может вызвать метод hasVibrator(), чтобы определить, является ли объект вибратором (true) или заглушкой (false).

Отключил ли пользователь тактильную обратную связь?

В некоторых случаях при использовании специальных реализаций может потребоваться вручную проверить, отключил ли пользователь параметр Тактильная обратная связь в Android. Если это так, эффекты тактильной обратной связи должны быть отключены. Этот параметр можно запросить с помощью ключа HAPTIC_FEEDBACK_ENABLED. Значение 0 означает, что параметр отключен.

Атрибуты вибрации

Атрибуты вибрации (в настоящее время в виде AudioAttributes) можно использовать, чтобы сообщать системе о цели вибрации. Это необходимо, если вы хотите, чтобы приложение вибрировало в фоновом режиме, поскольку в этом случае поддерживается только тактильная обратная связь, привлекающая внимание.

Создание AudioAttributes описано в документации к классу. Его следует рассматривать как вибрацию, а не звук.

В большинстве случаев тип контента – CONTENT_TYPE_SONIFICATION, а использование может быть таким: USAGE_ASSISTANCE_SONIFICATION – для тактильной обратной связи на переднем плане или USAGE_ALARM – для будильника в фоновом режиме. Аудиофлаги не влияют на вибрацию.

Управление амплитудой

Если вибратор поддерживает управление амплитудой, он может воспроизводить вибрацию разной интенсивности. Это важная возможность для создания сложных тактильных ощущений, а также для того, чтобы пользователи могли управлять интенсивностью тактильной обратной связи по умолчанию.

Поддержку управления амплитудой можно проверить, вызвав метод Vibrator.hasAmplitudeControl. Если вибратор не поддерживает амплитуду, все значения амплитуды будут сопоставлены с выключенным или включенным состоянием в зависимости от того, равны они нулю или нет. Поэтому приложения, использующие сложные тактильные эффекты с разной амплитудой, должны отключать их, если устройство не поддерживает управление амплитудой.

Поддержка эффектов конверта

Вибраторы с поддержкой эффектов огибающей позволяют создавать более динамичную и нюансированную вибрацию, а также точнее управлять ее интенсивностью и резкостью, что делает тактильные ощущения более насыщенными. Чтобы узнать, поддерживает ли ваше устройство эту функцию, перейдите на страницу Vibration.areEnvelopeEffectsSupported. Если нет, вибрация на основе огибающей игнорируется.