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

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

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

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

เครื่องมือสร้างซองจดหมายพื้นฐาน

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

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

เครื่องมือสร้างซองจดหมายของรูปแบบคลื่น

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

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

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

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

การใช้ Envelope VibrationEffects

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

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

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

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

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

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

ตรวจสอบการรองรับองค์ประกอบการสั่น

คุณสามารถเรียกข้อมูลการรองรับต่อองค์ประกอบได้โดยใช้วิธี 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

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 เพื่อดูว่าอุปกรณ์ของคุณ รองรับฟีเจอร์นี้หรือไม่ หากไม่เป็นเช่นนั้น ระบบจะไม่สนใจการสั่นสะเทือนตามซองจดหมาย