Android dokunma teknolojisi API referansı

Bu belgede, Android'de bulunan çeşitli dokunsal geribildirim API'leri tanıtılmakta, farklı dokunsal efektlerin nasıl oluşturulacağı ve gerekli cihaz desteğinin nasıl kontrol edileceği açıklanmaktadır. keywords_public: > Android, dokunsal, API'ler, titreşim, HapticFeedbackConstants, VibrationEffect, envelope haptics, haptic feedback, notification, amplitude control

Bu bölümde, Android'de bulunan çeşitli dokunma teknolojisi API'leri tanıtılmaktadır. Ayrıca, dokunsal efektlerinizin istediğiniz gibi oynatılmasını sağlamak için cihaz desteğini ne zaman ve nasıl kontrol edeceğiniz de açıklanır.

Dokunsal efektler oluşturmanın çeşitli yolları vardır. Bunlar arasından seçim yaparken Android dokunma teknolojisi tasarım ilkelerini göz önünde bulundurmanız önemlidir. Aşağıdaki tabloda, her yaklaşımın bu üst düzey özellikleri özetlenmektedir:

  • Kullanılabilirlik, özellikle davranış geri dönüşü planlarken önemlidir ve tek tek cihaz desteğini kontrol etmeyle birlikte kullanılmalıdır.
  • Net dokunsal geri bildirimler, kullanıcılar için daha az rahatsız edici olan keskin ve temiz hislerdir.
  • Zengin dokunsal geri bildirimler daha etkileyicidir ve genellikle daha fazla özellik içeren donanım gerektirir.
API yüzeyi Kullanılabilirlik Dokunma teknolojisini temizleme Zengin dokunma teknolojisi
HapticFeedbackConstants Android 1.5+
(sabit başına)
Önceden tanımlanmış VibrationEffect Android 10 veya sonraki sürümler
VibrationEffect kompozisyon (Tercih edilen) Android 16+ (26Q4)
VibrationEffect temel öğe kompozisyonu Android 11 ve sonraki sürümler (sabit başına)
Açma/kapatma, tek titreşim ve dalga biçimli titreşimler Android 1

Ayrıca, bu sayfada açıklanan bildirim API'leri, gelen bildirimler için oynatılan dokunsal efektleri özelleştirmenize olanak tanır.

Bu sayfada, API yüzeylerini kapsayan ek kavramlar da açıklanmaktadır:

HapticFeedbackConstants

HapticFeedbackConstants sınıfı, uygulamaların cihaz deneyimi genelinde tutarlı dokunsal geri bildirim eklemesine olanak tanıyan işleme dayalı sabitler sağlar. Böylece, her uygulama ortak işlemler için farklı efektler kullanmaz.

Uyumluluk ve şartlar

Bu sabitlerle View.performHapticFeedback yönteminin kullanılması için uygulama herhangi bir özel izin gerektirmez. Bu yöntem, View.hapticFeedbackEnabled özelliğine tabidir. Bu özellik false olarak ayarlanırsa varsayılan olanlar da dahil olmak üzere görünümdeki tüm dokunsal geribildirim çağrıları devre dışı bırakılır. Birincil ilgili ayar, View.hapticFeedbackEnabled özelliğidir. Bu özellik false olarak ayarlanırsa varsayılan olanlar da dahil olmak üzere görünümdeki tüm dokunsal geribildirim çağrıları devre dışı bırakılır. Bu yöntem, kullanıcının dokunma geri bildirimini etkinleştirmek için yaptığı sistem ayarını da dikkate alır.

Tek uyumluluk değerlendirmesi, işlem için belirli sabitin SDK düzeyidir.

HapticFeedbackConstants kullanılırken yedek davranış sağlamaya gerek yoktur.

HapticsFeedbackConstants kullanımı

HapticFeedbackConstants simgesini kullanmayla ilgili ayrıntılar için Etkinliklere dokunsal geri bildirim ekleme başlıklı makaleyi inceleyin.

Önceden tanımlanmış VibrationEffect

VibrationEffect sınıfı, CLICK, TICK ve DOUBLE_CLICK gibi önceden tanımlanmış çeşitli sabitler sağlar. Bu efektler cihaz için optimize edilmiş olabilir.

Uyumluluk ve şartlar

Herhangi bir VibrationEffect öğesini oynatmak için uygulama manifestinde VIBRATE izni gerekir.

Önceden tanımlanmış VibrationEffect kullanılırken yedek davranış sağlamaya gerek yoktur. Cihaz için optimize edilmiş bir uygulaması olmayan sabitler, standart bir platform yedeğine geri döner.

Vibrator.areEffectsSupported ve Vibrator.areAllEffectsSupported API'leri, cihaz için optimize edilmiş bir uygulama olup olmadığını belirlemek için kullanılır. Önceden tanımlanmış efektler, optimize edilmiş bir uygulama olmadan da kullanılabilir ve standart platform yedeklemesini kullanır. Dolayısıyla, bu areEffectsSupported API'ler yalnızca bir uygulamanın efektin cihaz için optimize edilip edilmediğini dikkate almak istemesi durumunda gereklidir.

Efekt kontrolü yöntemleri üç değerden birini döndürebilir:

UNKNOWN değeri, kontrol API'sinin kullanılamadığını gösterdiğinden genellikle tüm efektler veya hiçbir efekt için döndürülmez. Bu cihazlar dinamik olarak geri döner.

Önceden tanımlanmış VibrationEffect kullanımı

Önceden tanımlanmış bir VibrationEffect kullanma hakkında ayrıntılı bilgi için Dokunsal geri bildirim oluşturmak için önceden tanımlanmış bir VibrationEffect kullanma başlıklı makaleyi inceleyin.

Envelope VibrationEffect

Zarf tabanlı titreşimler, bir kontrol noktası dizisi tanımlayarak titreşimin genliğini ve frekansını zaman içinde hassas bir şekilde kontrol etmenize olanak tanır. Bu sayede geliştiriciler, daha zengin ve ayrıntılı dokunsal geri bildirim deneyimleri oluşturabilir. Bu titreşimler, BasicEnvelopeBuilder ve WaveformEnvelopeBuilder sınıfları kullanılarak oluşturulabilir.

Uyumluluk ve şartlar

Titreşim efektlerini oynatmak için uygulamanızın uygulama manifestinde VIBRATE iznini beyan etmesi gerekir.

Zarf efektleri desteğini kontrol etmek için Vibrator.areEnvelopeEffectsSupported() numaralı telefonu arayın.

Temel Zarf Oluşturucu

Sorunsuz bir dokunsal deneyim oluşturmak için zarf efektleri \( 0.0 \)yoğunluğuyla başlayıp bitmelidir. API, başlangıç yoğunluğunu sıfır olarak ayarlayarak bunu zorunlu kılar ve bitiş yoğunluğu sıfır değilse istisna oluşturur. Bu kısıtlama, titreşimlerde genlikteki süreksizlikler nedeniyle oluşan ve kullanıcının dokunsal algısını olumsuz etkileyebilecek istenmeyen dinamik efektleri önler.

Çerçeve, cihazlar arasında tutarlı bir zarf efekti oluşturmak için bu özelliği destekleyen cihazların kontrol noktaları arasında minimum 20 ms süre ve zarf efektleri için en az 16 nokta işleyebilmesini gerektirir.

Dalga Formu Zarfı Oluşturucu

Çerçeve, geliştirici tarafından sağlanan istenen frekans ve genlik değerlerini değiştirmez. Ancak API, sorunsuz geçişler oluşturmak için başlangıç genliğini sıfırda sabitler.

Android, uygulamanızın dalga formu zarfı efektlerini optimize etmenize ve cihazlar arasında uyumluluk sağlamanıza yardımcı olmak için önemli cihaz özelliklerini sorgulamaya yönelik API'ler sunar. Bu yöntemler, cihazın sınırlamaları hakkında bilgi sağlar. Örneğin, kontrol noktaları arasındaki maksimum ve minimum geçiş süresi ile tek bir efekt için desteklenen maksimum kontrol noktası sayısı:

getMaxSize()
Bir zarf efekti için desteklenen maksimum kontrol noktası sayısını alır.
getMinControlPointDurationMillis()
Bir zarf efektindeki iki kontrol noktası arasında desteklenen minimum süreyi milisaniye cinsinden alır.
getMaxControlPointDurationMillis()
Bir zarf efektindeki iki kontrol noktası arasında desteklenen maksimum süreyi milisaniye cinsinden alır.
getMaxDurationMillis()
Bir zarf efekti için desteklenen maksimum süreyi milisaniye cinsinden alır.

Bir efekt, cihazın sınırlamalarını (ör. çok fazla kontrol noktasına izin verme veya maksimum süreyi aşma) aşıyorsa çerçeve, efekti izin verilen sınırlar içinde kalacak şekilde otomatik olarak ayarlar. Bu ayarlama sürecinde, tasarımın orijinal amacını ve hissini mümkün olduğunca korumaya çalışılır.

Zarf Titreşim Efektlerinin Kullanımı

Zarf dalga biçimi efektleri oluşturma hakkında ayrıntılı bilgi için Zarflarla titreşim dalga biçimi oluşturma başlıklı makaleyi inceleyin.

VibrationEffect kompozisyon

Android 16 (26Q4) sürümünden itibaren, tasarlanmış bir zaman çizelgesi boyunca birden fazla dokunsal öğeyi sıralayarak zengin ve etkileyici dokunsal efektler oluşturmak için tercih edilen API VibrationEffect.Builder olacaktır. Zaman çizelgesine bağlı planlama, atomik kapsülleme, karma etkinlik desteği (ön ayarları ve zarfları birleştirme) ve yerleşik otomatik geri dönüş sunarak VibrationEffect.Composition yerine geçer.

Yapı taşları

Oluşturucu, aşağıdaki dokunsal öğeleri sıralamanıza olanak tanır:

  • VibrationEffect.Preset: PRESET_CLICK, PRESET_TICK ve PRESET_LOW_TICK gibi yaygın kısa titreşimleri temsil eden önceden tanımlanmış dokunsal hisler. Hazır ayarlar, VibrationEffect.Composition API'sindeki kısa temel öğelerin yerini alır. Daha uzun, kesintisiz veya artan efektler (önceden artış, düşüş ve diğer temel öğelerle işleniyordu) için bunun yerine zarfları (PWLE) kullanın. Hazır ayarlar, Preset.create(presetId, scale) kullanılarak 0.0f ile 1.0f arasında ölçeklendirilebilir.
  • VibrationEffect.Envelope: BasicEnvelopeBuilder (yoğunluk ve keskinlik ile) veya WaveformEnvelopeBuilder (sıklık ve genlik ile) kullanılarak oluşturulan parçalı doğrusal zarflar (PWLE'ler). Zarflar Envelope.create(builder) kullanılarak oluşturulur.
  • VibrationEffect.Event: getEvents() kullanılarak mevcut bir VibrationEffect öğesinden alınan zaman çizelgesi etkinlikleri. Bunlar, addEvents(startTimeShiftMillis, events) kullanılarak zaman çizelgesi farkıyla eklenebilir.

Zaman çizelgesi planlama ve doğrulama

Her öğe, beste başlangıcından itibaren zaman farkını (milisaniye cinsinden) gösteren bir startTimeMillis ile oluşturucuya eklenir:

  • Derleme zamanı doğrulama: Öğeler, başlangıç zamanlarına göre kesinlikle artan sırada eklenmelidir. Oluşturucu, derleme sırasında minimum süreye (ör. hazır ayarlar için 1 ms veya zarflar için bilinen süreler) göre kontrol yaparak en iyi çabayı göstererek doğrulama gerçekleştirir. Derleme sırasında çakışma tespit edilirse IllegalArgumentException oluşturulur.
  • Oynatma zamanlaması hizalama: Çerçeve, oynatma sırasında en iyi zamanlama desteğini sağlar. Bir önceki etkinlik, bir sonraki planlanmış etkinliğin başlangıç saati geldiğinde hâlâ yürütülüyorsa çerçeve, sonraki etkinliği otomatik olarak bir sonraki en erken kullanılabilir yuvaya kaydırır. Bu sayede, fiziksel oynatma sırasında etkinliklerin çakışması önlenir ve dokunsal etkinliklerin atlanmaması sağlanır.

Tekrarlanan efektler

setRepeatingEffect(startTimeMillis, repeatingEffect, durationMillis) simgesini kullanarak kompozisyona tekrarlanan bir efekt eklenebilir. Tekrarlanan bir efekt yapılandırıldıktan sonra oluşturucuya başka öğe eklenemez.

Yedek destek

VibrationEffect.Builder tarafından oluşturulan titreşim için çerçeve düzeyinde otomatik yedekleme desteği varsayılan olarak etkindir:

  • Şeffaf platform geri dönüşü: Bir cihaz, istenen Preset veya temel Envelope'ü desteklemiyorsa çerçeve, desteklenmeyen öğeyi çalışma zamanında en iyi şekilde uygun bir titreşimle otomatik olarak değiştirir. Uygulamanızın, VibrationEffect.Builder ile oluşturulan kompozisyonları çalmadan önce cihaz özelliklerini (ör. isPresetSupported) manuel olarak kontrol etmesi gerekmez.
  • WaveformEnvelopeBuilder için istisna: WaveformEnvelopeBuilder tarafından oluşturulan zarf efektleri (Hertz cinsinden mutlak fiziksel frekansları ve G cinsinden genlikleri belirtir) otomatik yedekleme desteğine sahip değildir. Gelişmiş PWLE'ler belirli donanım frekans eğrilerine (FOAM) dayandığından bunların otomatik olarak değiştirilmesi tasarım amacını tehlikeye atar. Cihaz, PWLE efektlerini veya istenen frekansları desteklemiyorsa bu tür titreşimler oynatılmaz. Evrensel uyumluluk için BasicEnvelopeBuilder tercih edin.

VibrationEffect.Builder kullanımı

VibrationEffect.Builder ile efekt oluşturma hakkındaki kod örnekleri için VibrationEffect.Builder ile zaman çizelgesine bağlı kompozisyonlar oluşturma başlıklı makaleyi inceleyin.

VibrationEffect temel öğe kompozisyonu

VibrationEffect temel öğe kompozisyonu, VibrationEffect.startComposition API kullanılarak oluşturulan bir titreşim efektidir. Bu API, bir dizi temel öğe oluşturmanıza olanak tanır.

Uyumluluk ve şartlar

Herhangi bir VibrationEffect öğesini oynatmak için uygulama manifestinde VIBRATE izni gerekir.

Temel destek olup olmadığını kontrol etme

Bu nedenle, VibrationEffect.Composition API'yi kullanırken oynatmadan önce Vibrator.arePrimitivesSupported veya Vibrator.areAllPrimitivesSupported kullanarak öğe başına desteği kontrol etmeniz gerekir.

Öğe başına destek, Vibrator.arePrimitivesSupported yöntemi kullanılarak alınabilir. Alternatif olarak, bir dizi temel öğe Vibrator.areAllPrimitivesSupported yöntemi kullanılarak birlikte kontrol edilebilir. Bu, temel öğe başına desteği AND ile kontrol etmeye eşdeğerdir.

VibrationEffect temel bileşenlerinin kullanımı

VibrationEffect temel öğe kompozisyonlarını kullanma hakkında ayrıntılı bilgi için Titreşim temel öğe kompozisyonları oluşturma başlıklı makaleyi inceleyin.

Açma/kapama, tek atış ve dalga biçimli titreşimler

Android'de desteklenen en eski titreşim biçimi, yapılandırılabilir sürelerle basit titreşimli açma/kapama desenleridir. Bu API'ler, titreşimli dokunma hissi oluşturabildikleri için genellikle dokunsal tasarım ilkeleriyle iyi uyum sağlamaz. Son çare olarak kullanmadığınız sürece bu API'lerden kaçının.

Açma/kapatma titreşiminin en yaygın kullanım alanı, ne olursa olsun titreşim istenen bildirimlerdir. Dalga formu titreşimleri, zil sesinde olduğu gibi bir desenin süresiz olarak tekrarlanmasına da olanak tanır.

Tek titreşimli kalıp, N milisaniye boyunca tek bir titreşimi ifade eder.

İki tür dalga biçimi vardır:

  • Yalnızca zamanlamalar. Bu tür dalga biçimi, kapalı ve açık olarak geçirilen sürelerin bir açıklamasıdır. Zamanlamalar, kapalıyken geçen süreyle başlar. Bu nedenle, titreşimin hemen başlaması için dalga biçimi desenleri genellikle sıfır değeriyle başlar.
  • Zamanlamalar ve genlikler. Bu tür dalga biçimi, ilk biçimin örtülü açma-kapama özelliği yerine her zamanlama figürüne uygun ek bir genlik dizisine sahiptir. Ancak, amaçlanan ölçeklendirmenin elde edilebilmesi için cihazın genlik kontrolünü desteklediğini kontrol etmek önemlidir.

Uyumluluk ve şartlar

Açma/kapama titreşimleri en eski titreşim biçimi olduğundan, bu sayfada daha sonra açıklandığı gibi, titreşim motoru olan neredeyse tüm cihazlarda desteklenir.

VibrationEffect veya eski stil vibrate çağrılarını oynatmak için uygulama manifestinde VIBRATE izni gerekir.

Bir dalga biçiminde farklı genlik değerleri kullanırken cihazın genlik kontrolünü desteklemesini önemle tavsiye ederiz.

Genlik kontrolü desteği olup olmadığını kontrol edin

Genlik kontrolü olmayan cihazlarda sıfır olmayan genlik değerleri% 100'e yuvarlanır. Bu nedenle, Vibrator.hasAmplitudeControl kullanarak desteğin mevcut olup olmadığını kontrol etmek önemlidir. Daha fazla bilgi için genlik kontrolü bölümüne bakın.

Efektinizin, genlik kontrolü olmadan yeterli kaliteye sahip olup olmadığını dikkatlice değerlendirmeniz gerekir. Açıkça tasarlanmış bir açma/kapama titreşimine geri dönmek daha iyi olabilir.

Açma/kapama titreşimlerinin kullanımı

Daha yeni SDK düzeylerinde tüm titreşim modları tek bir VibrationEffect sınıfında birleştirildi. Bu sınıfta basit titreşimler VibrationEffect.createOneShot veya VibrationEffect.createWaveform kullanılarak oluşturulur.

Bildirim API'leri

Uygulama bildirimlerinizi özelleştirirken aşağıdaki API'lerden birini kullanarak her bildirim kanalıyla bir kalıp ilişkilendirebilirsiniz:

Bu formların tümü, daha önce açıklandığı gibi temel bir açma/kapama dalga biçimi desenine sahiptir. İlk giriş, titreşim motorunun açılmasından önceki gecikmedir.

Genel kavramlar

Yukarıda ayrıntılı olarak açıklanan API yüzeylerinde geçerli olan çeşitli kavramlar vardır.

Cihazda titreşim özelliği var mı?

context.getSystemService(Vibrator.class) adresinden boş olmayan bir Vibrator sınıfı elde edebilirsiniz. Cihazda titreşim motoru yoksa titreşim API'lerine yapılan çağrıların herhangi bir etkisi olmaz. Bu nedenle, uygulamaların tüm dokunsal geri bildirimlerini bir koşula göre sınırlaması gerekmez. Ancak gerekirse bir uygulama, bunun gerçek bir titreşim motoru (true) mu yoksa bir kaba kod (false) mı olduğunu belirlemek için hasVibrator() çağrısı yapabilir.

Kullanıcı, dokunma titreşimini devre dışı bıraktı mı?

Bazı özel uygulamalarda, kullanıcının Android'in dokunma geri bildirimi ayarını tamamen devre dışı bırakıp bırakmadığını manuel olarak kontrol etmek gerekebilir. Bu durumda dokunma geri bildirimi efektleri devre dışı bırakılmalıdır. Bu ayar, HAPTIC_FEEDBACK_ENABLED anahtarı kullanılarak sorgulanabilir. Sıfır değeri, ayarın devre dışı olduğunu gösterir.

Titreşim özellikleri

Titreşim özellikleriyle (şu anda AudioAttributes biçiminde) sistemin titreşimin amacı hakkında bilgi sahibi olmasına yardımcı olunabilir. Bu, uygulamanız arka plandayken titreşim başlatmak için gereklidir. Arka plan kullanımı için yalnızca dikkat çekici dokunsal geri bildirimler desteklenir.

AudioAttributes oluşturma işlemi, sınıf dokümanlarında ele alınır ve ses yerine titreşim olarak düşünülmelidir.

Çoğu durumda içerik türü CONTENT_TYPE_SONIFICATION, kullanım ise ön planda dokunma geri bildirimi için USAGE_ASSISTANCE_SONIFICATION veya arka planda alarm için USAGE_ALARM gibi değerler olabilir. Ses işaretlerinin titreşimler üzerinde etkisi yoktur.

Genlik kontrolü

Titreşimli bir cihazda genlik kontrolü varsa farklı yoğunluklarda titreşimler oluşturabilir. Bu özellik, zengin dokunsal geri bildirimler üretmek ve varsayılan dokunsal yoğunlukların kullanıcı tarafından kontrol edilmesini sağlamak için önemlidir.

Genlik kontrolü desteği, Vibrator.hasAmplitudeControl işlevi çağrılarak kontrol edilebilir. Titreşim motoru genlik desteği sunmuyorsa tüm genlik değerleri, sıfır veya sıfır olmayan değerler olmasına bağlı olarak kapalı ya da açık olarak eşlenir. Dolayısıyla, farklı genliklerde zengin dokunma teknolojisi kullanan uygulamalar, cihazda genlik kontrolü yoksa bu özelliği devre dışı bırakmayı düşünmelidir.

Zarf efektleri desteği

Zarf efektli titreşim motorları, daha dinamik ve ayrıntılı titreşimler oluşturulmasını destekler ve sağlar. Bu sayede, daha zengin dokunsal deneyimler için yoğunluk ve keskinlik üzerinde daha hassas kontrol sunar. Cihazınızın bu özelliği destekleyip desteklemediğini belirlemek için Vibration.areEnvelopeEffectsSupported kullanın. Aksi takdirde, zarf tabanlı titreşimler yoksayılır.