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

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

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

  • Доступность особенно важна при планировании отката поведения и должна сочетаться с проверкой поддержки отдельных устройств.
  • Чистая тактильная чувствительность создает четкие и ясные ощущения, которые не вызывают раздражения у пользователей.
  • Богатая тактильная чувствительность обладает большей выразительностью и часто требует более функционального оборудования.
API поверхность Доступность Ясные тактильные ощущения Богатые тактильные ощущения
Константы HapticFeedback Андроид 1.5+
(на константу)
Предопределенный эффект вибрации Андроид 10+
Композиция VibrationEffect Android 11+ (постоянно)
Вибрации включения/выключения, однократные и волнообразные Андроид 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 для создания тактильной обратной связи .

Композиция VibrationEffect

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

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

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

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

Проверьте примитивную поддержку вибрации

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

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

Подробную информацию об использовании композиций VibrationEffect см. в разделе Создание вибрационных композиций .

Вибрации включения-выключения, однократные и волновые

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

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

Однократная вибрация подразумевает однократную вибрацию в течение 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 Touch , в этом случае эффекты обратной связи касания должны быть подавлены. Эту настройку можно запросить с помощью ключа HAPTIC_FEEDBACK_ENABLED , где значение ноль означает отключение.

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

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

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

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

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

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

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