Справочник по тактильному API Android

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

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

  • Наличие резервных вариантов поведения особенно важно при планировании и должно сочетаться с проверкой поддержки отдельных устройств.
  • Четкая тактильная отдача обеспечивает ясные и чистые ощущения, которые менее неприятны для пользователя.
  • Насыщенная тактильная обратная связь обладает большей выразительностью и часто требует более функционального оборудования.
Поверхность API Доступность Четкая тактильная отдача Насыщенная тактильная отдача
Константы тактильной обратной связи Android 1.5+
(на константу)
Предопределенный эффект вибрации Android 10+
Вибрационный эффект Состав Android 11+ (постоянно)
Вибрации типа «вкл/выкл», однократные вибрации и вибрации волновой формы Android 1

Кроме того, 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 для генерации тактильной обратной связи» .

Эффект вибрации оболочки

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

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

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

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

Базовый конструктор конвертов

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

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

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

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

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

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

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

Использование эффектов вибрации огибающей

Подробную информацию о создании эффектов огибающей волновой формы см. в разделе «Создание вибрационной волновой формы с помощью огибающей» .

Состав, VibrationEffect

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

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

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

Не все устройства поддерживают все функции API композиции, поэтому важно убедиться в доступности необходимых примитивов .

Проверьте наличие поддержки примитива вибрации.

Поддержку для каждого примитива можно получить с помощью метода 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 , где значение ноль означает отключение.

Характеристики вибрации

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

Создание AudioAttributes описано в документации к этому классу и должно рассматриваться скорее как вибрация, чем как звук .

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

Регулировка амплитуды

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

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

Поддержка эффектов оболочки

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