Android dokunma teknolojisi API referansı

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

Dokunsal efektler oluşturmanın birkaç farklı yolu vardır ve bunlar arasından seçim yaparken Android dokunsal 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 Dokunsal geri bildirimi temizleme Zengin dokunma teknolojisi
HapticFeedbackConstants Android 1.5+
(sabit başına)
Önceden tanımlanmış VibrationEffect Android 10 ve sonraki sürümler
VibrationEffect Composition Android 11 ve sonraki sürümler (sabit başına)
Açma/kapatma, tek seferlik 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 kullanmak zorunda kalmaz.

Uyumluluk ve şartlar

Bu sabitlerle View.performHapticFeedback yönteminin kullanılması için uygulamada özel izinler gerekmez. Bu yöntem, View.hapticFeedbackEnabled özelliğine tabidir. false olarak ayarlanırsa varsayılanlar da dahil olmak üzere görünümdeki tüm dokunsal geri bildirim çağrıları devre dışı bırakılır. Birincil ilgili ayar, View.hapticFeedbackEnabled özelliğidir. Bu özellik false olarak ayarlanırsa varsayılanlar da dahil olmak üzere görünümdeki tüm dokunsal geri bildirim ç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ğlamanıza gerek yoktur.

HapticsFeedbackConstants kullanımı

HapticFeedbackConstants kullanma hakkında ayrıntılı bilgi 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 uygulama içermeyen sabitler, standart bir platform yedeğine geri döner.

Vibrator.areEffectsSupported ve Vibrator.areAllEffectsSupported API'leri, cihaz için optimize edilmiş bir uygulamanın olup olmadığını belirlemek için kullanılır. Önceden tanımlanmış efektler, optimize edilmiş bir uygulama olmadan da kullanılabilir ve standart platform geri dönüşünü kullanır. Dolayısıyla, bu areEffectsSupported API'ler yalnızca bir uygulama, efektin cihaz için optimize edilip edilmediğini dikkate almak istiyorsa 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 noktaları 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, uygulama manifestinde VIBRATE iznini beyan etmelidir.

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

Temel Zarf Oluşturucu

Sorunsuz ve kesintisiz 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 sabitleyerek bunu zorunlu kılar ve bitiş yoğunluğu sıfır değilse istisna oluşturur. Bu kısıtlama, genlikteki süreksizlikler nedeniyle titreşimlerde istenmeyen dinamik efektlerin oluşmasını önler. Bu efektler, kullanıcının dokunsal algısını olumsuz etkileyebilir.

Çerçeve, cihazlarda 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, yumuşak geçişler oluşturmak için başlangıç genliğini sıfır olarak da düzeltir.

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. effect.
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

VibrationEffect kompozisyonu, VibrationEffect.startComposition API kullanılarak oluşturulan bir titreşim efektidir. Bu API, özelleştirilmiş gecikmeler ve yoğunluklarla bir dizi temel öğe oluşturarak zengin dokunsal geri bildirimler sağlar. Ancak tutarsız bir genel deneyim yaşamamak için cihazın, birleştirilen özellikleri desteklediğinden emin olmaya özen gösterin.

Uyumluluk ve şartlar

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

Tüm cihazlar, Composition API'nin tüm özelliklerini desteklemez ve temel öğelerin kullanılabilir olduğundan emin olmak önemlidir.

Titreşim ilkel desteğini kontrol etme

Öğ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, her temel öğe için desteği AND ile kontrol etmeye eşdeğerdir.

VibrationEffect Compositions kullanımı

VibrationEffect kompozisyonlarını kullanma hakkında ayrıntılı bilgi için Titreşim 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 dokunsal geri bildirimler oluşturabildiklerinden 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/kapama titreşimlerinin en yaygın kullanım alanı, ne olursa olsun titreşim istenen bildirimlerdir. Dalga biçimli titreşimler, zil sesinde olduğu gibi bir kalıbın süresiz olarak tekrarlanmasına da olanak tanır.

Tek seferlik titreşim, 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çiminde, ilk biçimin örtülü açma-kapama özelliği yerine her zamanlama figürüyle eşleşecek ek bir genlik dizisi bulunur. Ancak, amaçlanan ölçeklendirmenin elde edilebilmesi için cihazın genlik kontrolünü desteklediğini kontrol etmek önemlidir.

Uyumluluk ve şartlar

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

VibrationEffect veya eski stil vibrate görüşmelerini 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 etme

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ü başlıklı makaleyi inceleyin.

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 her bildirim kanalıyla bir kalıp ilişkilendirmek için aşağıdaki API'lerden birini kullanabilirsiniz:

Bu formların tümü, daha önce açıklandığı gibi temel bir açma/kapama dalga formu desenine sahiptir. İlk giriş, titreşimi açmadan ö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ı edinebilirsiniz. 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 saplama (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ı olabilirsiniz. Bu, uygulamanız arka plandayken titreşim başlatmak için gereklidir. Arka planda 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şim motorunda genlik kontrolü varsa farklı yoğunluklarda titreşimler oynatılabilir. Bu, zengin dokunsal geri bildirimler üretmek ve kullanıcının varsayılan dokunsal yoğunlukları kontrol etmesine olanak tanımak için önemli bir özelliktir.

Genlik kontrolü desteği, Vibrator.hasAmplitudeControl işlevi çağrılarak kontrol edilebilir. Bir titreşim motoru genlik desteğine sahip değilse tüm genlik değerleri, sıfır veya sıfır olmayan değerler olmasına bağlı olarak kapalı/açık olarak eşlenir. Dolayısıyla, farklı genliklerde zengin dokunsal geri bildirim 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ı destekleyip mümkün kılarak daha zengin dokunsal deneyimler için yoğunluk ve keskinlik üzerinde daha hassas kontrol sağlar. Cihazınızın bu özelliği destekleyip desteklemediğini belirlemek için Vibration.areEnvelopeEffectsSupported kullanın. Aksi takdirde, zarf tabanlı titreşimler yok sayılır.