ข้อมูลอ้างอิง API ของการสัมผัสของ Android

ส่วนนี้จะแนะนำ API การสัมผัสต่างๆ ที่มีให้ใช้งานใน Android รวมถึงกล่าวถึงกรณีที่ควรและวิธีตรวจสอบการรองรับอุปกรณ์ที่จำเป็นเพื่อให้แน่ใจว่าเอฟเฟกต์การสัมผัสจะเล่นตามที่คุณต้องการ

การสร้างเอฟเฟกต์การสัมผัสทำได้หลายวิธี และคุณควรคำนึงถึงหลักการออกแบบการสัมผัสของ Android เมื่อเลือกวิธี ตารางต่อไปนี้สรุปแอตทริบิวต์ระดับสูงเหล่านี้ของแนวทางแต่ละวิธี

  • ความพร้อมใช้งานมีความสําคัญอย่างยิ่งเมื่อวางแผนการรองรับลักษณะการทํางานสำรอง และจะต้องควบคู่ไปกับการตรวจสอบการรองรับอุปกรณ์แต่ละรุ่น
  • การสัมผัสที่ชัดเจนคือความรู้สึกที่คมชัดและชัดเจนซึ่งทำให้ผู้ใช้รู้สึกไม่กระวนกระวาย
  • การสัมผัสที่สมจริงจะแสดงออกได้ดีกว่าและมักต้องใช้ฮาร์ดแวร์ที่มีคุณสมบัติหลากหลายมากขึ้น
แพลตฟอร์ม API ความพร้อมใช้งาน การโต้ตอบการสัมผัสที่ชัดเจน การโต้ตอบการสัมผัสที่หลากหลาย
HapticFeedbackConstants Android 1.5 ขึ้นไป
(ตามค่าคงที่)
VibrationEffect ที่กําหนดไว้ล่วงหน้า Android 10 ขึ้นไป
VibrationEffect Composition Android 11 ขึ้นไป (ตามค่าคงที่)
การสั่นเปิด/ปิด การสั่นแบบครั้งเดียว และการสั่นตามรูปแบบคลื่น Android 1

นอกจากนี้ Notification 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 ในไฟล์ Manifest ของแอป

คุณไม่จําเป็นต้องระบุลักษณะการทํางานสำรองเมื่อใช้VibrationEffectที่กําหนดไว้ล่วงหน้า เนื่องจากค่าคงที่ที่ไม่มีการใช้งานที่ปรับให้เหมาะกับอุปกรณ์จะเปลี่ยนกลับไปใช้ค่ามาตรฐานของแพลตฟอร์ม

API Vibrator.areEffectsSupported และ Vibrator.areAllEffectsSupported มีไว้เพื่อระบุว่ามีการใช้งานที่เพิ่มประสิทธิภาพสำหรับอุปกรณ์หรือไม่ คุณยังคงใช้เอฟเฟกต์ที่กําหนดไว้ล่วงหน้าได้โดยไม่ต้องมีการใช้งานแบบเพิ่มประสิทธิภาพ และใช้เอฟเฟกต์สำรองของแพลตฟอร์มมาตรฐาน ดังนั้น คุณจึงต้องใช้areEffectsSupported API เหล่านี้ก็ต่อเมื่อแอปพลิเคชันต้องการพิจารณาว่าเอฟเฟกต์ได้รับการเพิ่มประสิทธิภาพสำหรับอุปกรณ์หรือไม่

วิธีการตรวจสอบผลลัพธ์จะแสดงผลลัพธ์ค่าใดค่าหนึ่งต่อไปนี้

  • VIBRATION_EFFECT_SUPPORT_YES บ่งชี้ว่าอุปกรณ์รองรับเอฟเฟกต์นี้อย่างมีประสิทธิภาพ
  • VIBRATION_EFFECT_SUPPORT_NO บ่งชี้ว่าอุปกรณ์ไม่มีการสนับสนุนแบบเพิ่มประสิทธิภาพ แต่ยังคงใช้แพลตฟอร์มสำรอง
  • VIBRATION_EFFECT_SUPPORT_UNKNOWN บ่งบอกว่าระบบไม่ทราบว่าการใช้งานได้รับการเพิ่มประสิทธิภาพหรือไม่

เนื่องจากค่า UNKNOWN บ่งบอกว่า API การตรวจสอบไม่พร้อมใช้งาน ระบบจึงมักจะแสดงผลสำหรับเอฟเฟกต์ทั้งหมดหรือไม่มีเอฟเฟกต์ใดเลย อุปกรณ์เหล่านี้จะเปลี่ยนไปใช้รูปแบบอื่นแบบไดนามิก

การใช้ VibrationEffect ที่กําหนดไว้ล่วงหน้า

โปรดดูรายละเอียดเกี่ยวกับการใช้ VibrationEffect ที่กําหนดไว้ล่วงหน้าที่หัวข้อใช้ VibrationEffect ที่กําหนดไว้ล่วงหน้าเพื่อสร้างการตอบกลับด้วยระบบสัมผัส

Envelope VibrationEffect

การสั่นสะเทือนตามรูปคลื่นช่วยให้ควบคุมแอมพลิจูดและความถี่ของการสั่นสะเทือนได้อย่างแม่นยำเมื่อเวลาผ่านไป โดยกำหนดลำดับของจุดควบคุม ซึ่งช่วยให้นักพัฒนาแอปสร้างประสบการณ์การสัมผัสที่สมบูรณ์ยิ่งขึ้นและละเอียดยิ่งขึ้น คุณสร้างการสั่นเหล่านี้ได้โดยใช้คลาส BasicEnvelopeBuilder และ WaveformEnvelopeBuilder

ความเข้ากันได้และข้อกำหนด

หากต้องการเล่นเอฟเฟกต์การสั่น แอปของคุณต้องประกาศสิทธิ์ VIBRATE ในไฟล์ Manifest ของแอป

หากต้องการตรวจสอบการรองรับเอฟเฟกต์ของโฟลเดอร์ ให้โทรไปที่ Vibrator.areEnvelopeEffectsSupported()

เครื่องมือสร้างโฟลเดอร์พื้นฐาน

เพื่อสร้างประสบการณ์การสัมผัสที่ราบรื่นและต่อเนื่อง ผลลัพธ์ของอีนวelope ต้องเริ่มต้นและสิ้นสุดด้วยระดับ \( 0.0 \)API จะบังคับใช้ข้อกำหนดนี้โดยกำหนดความเข้มเริ่มต้นเป็น 0 และแสดงข้อยกเว้นหากความเข้มสิ้นสุดไม่ใช่ 0 ข้อจำกัดนี้ช่วยป้องกันไม่ให้การสั่นเกิดเอฟเฟกต์แบบไดนามิกที่ไม่พึงประสงค์เนื่องจากความต่อเนื่องของแอมพลิจูดที่อาจส่งผลเสียต่อความรู้สึกสัมผัสของผู้ใช้

เฟรมเวิร์กกำหนดให้อุปกรณ์ที่รองรับฟีเจอร์นี้สามารถจัดการระยะเวลาขั้นต่ำ 10 มิลลิวินาทีระหว่างจุดควบคุมและจุดอย่างน้อย 16 จุดสำหรับเอฟเฟกต์เสียงห่อ

Waveform Envelope Builder

เฟรมเวิร์กจะไม่แก้ไขค่าความถี่และความกว้างของคลื่นที่นักพัฒนาแอประบุ อย่างไรก็ตาม API จะแก้ไขแอมพลิจูดเริ่มต้นที่ 0 เพื่อให้การเปลี่ยนเป็นไปอย่างราบรื่นด้วย

Android มี API สําหรับการค้นหาความสามารถที่สําคัญของอุปกรณ์เพื่อช่วยคุณเพิ่มประสิทธิภาพเอฟเฟกต์รูปคลื่นของแอปและมอบความเข้ากันได้ในอุปกรณ์ต่างๆ วิธีการเหล่านี้จะให้ข้อมูลเกี่ยวกับข้อจำกัดของอุปกรณ์ เช่น ระยะเวลาการเปลี่ยนขั้นต่ำและสูงสุดระหว่างจุดควบคุม และจำนวนจุดควบคุมสูงสุดที่รองรับสำหรับเอฟเฟกต์เดียว

getMaxSize()
ดึงข้อมูลจำนวนจุดควบคุมสูงสุดที่รองรับสำหรับเอฟเฟกต์อีนเวลอป
getMinControlPointDurationMillis()
ดึงข้อมูลระยะเวลาขั้นต่ำที่รองรับเป็นมิลลิวินาทีระหว่างจุดควบคุม 2 จุดภายในเอฟเฟกต์อีนเวลอป
getMaxControlPointDurationMillis()
ดึงข้อมูลระยะเวลาสูงสุดที่รองรับเป็นมิลลิวินาทีระหว่างจุดควบคุม 2 จุดภายในเอฟเฟกต์อีนเวลอป
getMaxDurationMillis()
เรียกข้อมูลระยะเวลาสูงสุดที่รองรับสำหรับเอฟเฟกต์ของอีนเวลอปเป็นมิลลิวินาที

หากเอฟเฟกต์เกินขีดจํากัดของอุปกรณ์ เช่น อนุญาตให้ใช้จุดควบคุมมากเกินไปหรือระยะเวลาเกินกว่าค่าสูงสุด เฟรมเวิร์กจะปรับเอฟเฟกต์ให้อยู่ภายในขอบเขตที่อนุญาตโดยอัตโนมัติ กระบวนการปรับนี้พยายามที่จะคงไว้ซึ่งเจตนาและความรู้สึกเดิมของการออกแบบให้ได้มากที่สุด

การใช้ Envelope VibrationEffects

โปรดดูรายละเอียดเกี่ยวกับการสร้างเอฟเฟกต์รูปแบบคลื่นของอีแวลอบป์ที่หัวข้อสร้างรูปแบบคลื่นการสั่นด้วยอีแวลอบป์

VibrationEffect การเรียบเรียงเพลง

องค์ประกอบ VibrationEffect คือเอฟเฟกต์การสั่นที่สร้างโดยใช้ VibrationEffect.startComposition API API นี้ช่วยให้คุณแสดงการสัมผัสที่สมจริงได้ด้วยการสร้างขึ้นตามลําดับขององค์ประกอบพื้นฐานที่มีเวลาหน่วงและระดับที่กำหนดเอง อย่างไรก็ตาม โปรดตรวจสอบอย่างละเอียดว่าอุปกรณ์รองรับฟีเจอร์ที่จะรวมเข้าด้วยกัน เพื่อไม่ให้ประสบการณ์การใช้งานโดยรวมไม่สอดคล้องกัน

ความเข้ากันได้และข้อกำหนด

การเล่น VibrationEffect ใดๆ ก็ตามต้องใช้สิทธิ์ VIBRATE ในไฟล์ Manifest ของแอป

อุปกรณ์บางรุ่นอาจไม่รองรับฟีเจอร์ทั้งหมดของ Composition API และคุณควรตรวจสอบว่าองค์ประกอบพื้นฐานพร้อมใช้งาน

ตรวจสอบการรองรับรูปแบบการสั่น

คุณสามารถเรียกข้อมูลการสนับสนุนต่อองค์ประกอบพื้นฐานได้โดยใช้เมธอด Vibrator.arePrimitivesSupported หรือจะตรวจสอบชุดของพรอมต์พร้อมกันโดยใช้เมธอด Vibrator.areAllPrimitivesSupported ก็ได้ ซึ่งเทียบเท่ากับการ AND การรองรับต่อพรอมต์

การใช้ผลงานประพันธ์ VibrationEffect รายการ

โปรดดูรายละเอียดเกี่ยวกับการใช้การประพันธ์ VibrationEffect ที่หัวข้อสร้างการประพันธ์การสั่น

การสั่นแบบเปิด/ปิด การสั่นแบบครั้งเดียว และการสั่นแบบรูปคลื่น

รูปแบบการสั่นที่เก่าแก่ที่สุดที่ Android รองรับคือรูปแบบการสั่นเปิด/ปิดแบบง่ายที่มีระยะเวลาที่กำหนดได้ โดยปกติแล้ว API เหล่านี้จะไม่สอดคล้องกับหลักการการออกแบบการสัมผัส เนื่องจากอาจสร้างการสัมผัสที่ทำให้เกิดเสียงรบกวน ดังนั้นโปรดหลีกเลี่ยงการใช้ API เหล่านี้ ยกเว้นในกรณีที่ไม่มีทางเลือกอื่น

Use Case ที่พบบ่อยที่สุดสำหรับการสั่นแบบเปิด/ปิดคือการแจ้งเตือน ซึ่งผู้ใช้ต้องการการสั่นไม่ว่าในกรณีใดก็ตาม การสั่นรูปแบบคลื่นยังช่วยให้รูปแบบซ้ำไปเรื่อยๆ แบบไม่จำกัดได้ด้วย ดังที่คุณอาจจินตนาการไว้สำหรับริงโทน

รูปแบบแบบครั้งเดียวหมายถึงการสั่น 1 ครั้งเป็นเวลา N มิลลิวินาที

รูปแบบรูปแบบคลื่นมี 2 ประเภทดังนี้

  • เฉพาะช่วงเวลา รูปแบบคลื่นประเภทนี้เป็นคำอธิบายของระยะเวลาที่เปิดและปิดสลับกัน ช่วงเวลาเริ่มต้นด้วยระยะเวลาที่ปิดอยู่ ด้วยเหตุนี้ รูปแบบรูปแบบคลื่นจึงมักเริ่มต้นด้วยค่า 0 เพื่อบ่งบอกว่าให้เริ่มสั่นทันที
  • ช่วงเวลาและความกว้างของคลื่น รูปแบบคลื่นประเภทนี้มีอาร์เรย์ของระดับความดังเพิ่มเติมเพื่อให้ตรงกับตัวเลขการกําหนดเวลาแต่ละรายการ แทนการเปิด/ปิดโดยนัยของรูปแบบแรก อย่างไรก็ตาม คุณต้องตรวจสอบว่าอุปกรณ์รองรับการควบคุมระดับความดังเพื่อให้แน่ใจว่าการปรับขนาดที่ต้องการจะทำได้

ความเข้ากันได้และข้อกำหนด

การสั่นแบบเปิด/ปิดเป็นรูปแบบการสั่นที่เก่าแก่ที่สุด อุปกรณ์เกือบทุกเครื่องที่มีตัวสั่นจึงรองรับการสั่นรูปแบบนี้ ตามที่อธิบายไว้ภายหลังในหน้านี้

การเล่นการเรียกใช้ VibrationEffect หรือ vibrate แบบเก่าต้องใช้สิทธิ์ VIBRATE ในไฟล์ Manifest ของแอป

เมื่อใช้ค่าแอมพลิจูดที่แตกต่างกันในรูปคลื่น เราขอแนะนําอย่างยิ่งให้ตรวจสอบว่าอุปกรณ์รองรับการควบคุมแอมพลิจูด

ตรวจสอบการรองรับการควบคุมแอมพลิจูด

ระบบจะปัดค่าแอมพลิจูดที่ไม่ใช่ 0 เป็น 100% ในอุปกรณ์ที่ไม่มีการควบคุมแอมพลิจูด ดังนั้นจึงควรตรวจสอบว่าอุปกรณ์รองรับหรือไม่โดยใช้ Vibrator.hasAmplitudeControl ดูรายละเอียดเพิ่มเติมได้ที่การควบคุมแอมพลิจูด

คุณควรพิจารณาอย่างรอบคอบว่าเอฟเฟกต์มีคุณภาพเพียงพอหรือไม่หากไม่มีการควบคุมระดับความดัง การกลับไปใช้การสั่นแบบเปิด/ปิดที่ออกแบบมาอย่างชัดเจนอาจดีกว่า

การใช้การสั่นแบบเปิด/ปิด

ใน SDK ระดับใหม่ ระบบได้รวมโหมดการสั่นทั้งหมดไว้ในคลาส VibrationEffect ที่สื่อความหมายแบบเดี่ยว ซึ่งจะสร้างการสั่นแบบง่ายเหล่านี้โดยใช้ VibrationEffect.createOneshot หรือ VibrationEffect.createWaveform

Notification API

เมื่อปรับแต่งการแจ้งเตือนของแอป คุณสามารถใช้ API รายการใดรายการหนึ่งต่อไปนี้เพื่อเชื่อมโยงรูปแบบกับช่องทางการแจ้งเตือนแต่ละช่องทาง

รูปแบบทั้งหมดเหล่านี้ใช้รูปแบบคลื่นเปิด/ปิดพื้นฐานตามที่อธิบายไว้ก่อนหน้านี้ โดยรายการแรกคือเวลาหน่วงก่อนเปิดเครื่องสั่น

แนวคิดทั่วไป

แนวคิดหลายอย่างมีผลกับแพลตฟอร์ม API ที่ระบุไว้ข้างต้น

อุปกรณ์มีมอเตอร์สั่นไหม

คุณรับคลาส Vibrator ที่ไม่ใช่ค่า Null ได้จาก 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 หากไวเบรเตอร์ไม่รองรับแอมพลิจูด ค่าแอมพลิจูดทั้งหมดจะแมปเป็นปิด/เปิดโดยขึ้นอยู่กับว่าค่าเป็น 0/ไม่ใช่ 0 ดังนั้น แอปพลิเคชันที่ใช้การสัมผัสที่สมจริงซึ่งมีระดับความดังที่แตกต่างกันจึงควรพิจารณาปิดใช้หากอุปกรณ์ไม่มีการควบคุมระดับความดัง

การรองรับเอฟเฟกต์ของโฟลเดอร์

อุปกรณ์สั่นที่มีเอฟเฟกต์ของอีนเวลอปจะรองรับและช่วยให้คุณสร้างการสั่นที่หลากหลายและละเอียดยิ่งขึ้น รวมถึงควบคุมความแรงและความคมชัดได้อย่างแม่นยำยิ่งขึ้นเพื่อให้ได้ประสบการณ์การสัมผัสที่สมบูรณ์ยิ่งขึ้น ใช้ Vibration.areEnvelopeEffectsSupported เพื่อดูว่าอุปกรณ์รองรับฟีเจอร์นี้หรือไม่ หากไม่มี ระบบจะไม่สนใจการสั่นตามโฟลเดอร์