Tài liệu tham khảo API xúc giác của Android

Phần này giới thiệu các API phản hồi xúc giác có trong Android. Phần này cũng đề cập đến thời điểm và cách kiểm tra xem có cần hỗ trợ thiết bị nào để đảm bảo hiệu ứng xúc giác phát như bạn dự định hay không.

Có nhiều cách khác nhau để tạo hiệu ứng xúc giác và bạn cần cân nhắc các nguyên tắc thiết kế về hiệu ứng xúc giác trên Android khi chọn một trong số các cách đó. Bảng sau đây tóm tắt các thuộc tính cấp cao này của từng phương pháp:

  • Tính sẵn có đặc biệt quan trọng khi lập kế hoạch cho hành vi dự phòng và cần kết hợp với việc kiểm tra khả năng hỗ trợ của từng thiết bị.
  • Phản hồi xúc giác rõ ràng là những cảm giác sắc nét và rõ ràng, ít gây khó chịu cho người dùng.
  • Tương tác xúc giác phong phú có khả năng biểu đạt cao hơn và thường yêu cầu phần cứng có nhiều tính năng hơn.
Nền tảng API Phạm vi cung cấp Xoá phản hồi xúc giác Phản hồi xúc giác đa dạng
HapticFeedbackConstants Android 1.5 trở lên
(mỗi hằng số)
Predefined VibrationEffect Android 10 trở lên
Thành phần VibrationEffect Android 11 trở lên (theo hằng số)
Rung bật/tắt, rung một lần và rung theo dạng sóng Android 1

Ngoài ra, API thông báo (được mô tả trên trang này) cho phép bạn tuỳ chỉnh các hiệu ứng xúc giác phát cho thông báo đến.

Ngoài ra, trang này cũng mô tả các khái niệm bổ sung trải rộng trên các nền tảng API:

  • Thiết bị có bộ rung không?
  • Chế độ kiểm soát biên độ cho phép tạo hiệu ứng xúc giác mượt mà và phong phú hơn, nhưng không phải thiết bị nào cũng hỗ trợ chế độ này.
  • VibrationAttributes() giúp bạn phân loại chế độ rung dựa trên mục đích sử dụng, đảm bảo chế độ cài đặt phù hợp cho người dùng sẽ được áp dụng cho chế độ rung đó và do đó tránh gây bất ngờ cho người dùng.

HapticFeedbackConstants

Lớp HapticFeedbackConstants cung cấp các hằng số dựa trên thao tác để cho phép các ứng dụng thêm phản hồi xúc giác nhất quán trong trải nghiệm trên thiết bị, thay vì mỗi ứng dụng có các hiệu ứng khác nhau cho các thao tác phổ biến.

Khả năng tương thích và yêu cầu

Việc sử dụng phương thức View.performHapticFeedback với các hằng số này không yêu cầu ứng dụng có bất kỳ quyền đặc biệt nào. Phương thức này tuân theo thuộc tính View.hapticFeedbackEnabled. Nếu bạn đặt thuộc tính này thành false, thì tất cả các lệnh gọi phản hồi xúc giác trên khung hiển thị sẽ bị vô hiệu hoá, kể cả các lệnh gọi mặc định. Chế độ cài đặt chính có liên quan là thuộc tính View.hapticFeedbackEnabled. Nếu bạn đặt thuộc tính này thành false, thì tất cả các lệnh gọi phản hồi xúc giác trên khung hiển thị sẽ bị vô hiệu hoá, kể cả các lệnh gọi mặc định. Phương thức này cũng tuân theo chế độ cài đặt hệ thống của người dùng để bật phản hồi khi chạm.

Yếu tố duy nhất cần cân nhắc về khả năng tương thích là cấp SDK của hằng số cụ thể cho thao tác.

Bạn không cần cung cấp hành vi dự phòng khi sử dụng HapticFeedbackConstants.

Mức sử dụng HapticsFeedbackConstants

Để biết thông tin chi tiết về cách sử dụng HapticFeedbackConstants, hãy xem phần Thêm phản hồi xúc giác vào các sự kiện.

Được xác định trước VibrationEffect

Lớp VibrationEffect cung cấp một số hằng số được xác định trước, chẳng hạn như CLICK, TICK và DOUBLE_CLICK. Các hiệu ứng này có thể được tối ưu hoá cho thiết bị.

Khả năng tương thích và yêu cầu

Để phát bất kỳ VibrationEffect nào, bạn cần có quyền VIBRATE trong tệp kê khai ứng dụng.

Bạn không cần cung cấp hành vi dự phòng khi sử dụng VibrationEffect được xác định trước, vì các hằng số không có chế độ triển khai được tối ưu hoá cho thiết bị sẽ quay về chế độ dự phòng tiêu chuẩn của nền tảng.

Các API Vibrator.areEffectsSupported và Vibrator.areAllEffectsSupported dùng để xác định xem có chế độ triển khai được tối ưu hoá cho thiết bị hay không. Bạn vẫn có thể sử dụng các hiệu ứng được xác định trước mà không cần triển khai được tối ưu hoá và sử dụng cơ chế dự phòng tiêu chuẩn của nền tảng. Do đó, bạn chỉ cần các API areEffectsSupported này nếu ứng dụng muốn xem xét việc hiệu ứng có được tối ưu hoá cho thiết bị hay không.

Các phương thức kiểm tra hiệu ứng có thể trả về một trong ba giá trị:

Vì giá trị UNKNOWN cho biết API kiểm tra không hoạt động, nên giá trị này thường được trả về cho tất cả hiệu ứng hoặc không có hiệu ứng nào. Các thiết bị này sẽ tự động chuyển về chế độ dự phòng.

Mức sử dụng VibrationEffect được xác định trước

Để biết thông tin chi tiết về cách sử dụng VibrationEffect được xác định trước, hãy xem phần Sử dụng VibrationEffect được xác định trước để tạo phản hồi xúc giác.

Envelope VibrationEffect

Chế độ rung dựa trên bao thư cho phép kiểm soát chính xác biên độ và tần số rung theo thời gian bằng cách xác định một chuỗi các điểm kiểm soát. Điều này cho phép nhà phát triển tạo ra trải nghiệm phản hồi xúc giác phong phú và tinh tế hơn. Bạn có thể tạo những chế độ rung này bằng các lớp BasicEnvelopeBuilder và WaveformEnvelopeBuilder.

Khả năng tương thích và yêu cầu

Để phát bất kỳ hiệu ứng rung nào, ứng dụng của bạn phải khai báo quyền VIBRATE trong tệp kê khai ứng dụng.

Để kiểm tra xem có hỗ trợ hiệu ứng phong bì hay không, hãy gọi Vibrator.areEnvelopeEffectsSupported().

Trình tạo phong bì cơ bản

Để tạo ra trải nghiệm xúc giác mượt mà và liền mạch, hiệu ứng bao phải bắt đầu và kết thúc với cường độ \( 0.0 \). API thực thi điều này bằng cách cố định cường độ bắt đầu ở mức 0 và gửi một ngoại lệ nếu cường độ kết thúc không phải là 0. Ràng buộc này ngăn chặn các hiệu ứng động không mong muốn trong chế độ rung do sự gián đoạn về biên độ có thể ảnh hưởng tiêu cực đến cảm nhận xúc giác của người dùng.

Để cung cấp hiệu ứng kết xuất nhất quán trên các thiết bị, khung này yêu cầu các thiết bị hỗ trợ tính năng này có thể xử lý thời lượng tối thiểu là 20 mili giây giữa các điểm kiểm soát và ít nhất 16 điểm cho hiệu ứng phong bì.

Công cụ tạo đường bao dạng sóng

Khung này không sửa đổi các giá trị tần số và biên độ mà nhà phát triển cung cấp. Tuy nhiên, API này cũng cố định biên độ bắt đầu ở mức 0 để tạo hiệu ứng chuyển đổi mượt mà.

Để giúp bạn tối ưu hoá các hiệu ứng bao sóng của ứng dụng và đảm bảo khả năng tương thích trên nhiều thiết bị, Android cung cấp các API để truy vấn những chức năng quan trọng của thiết bị. Các phương thức này cung cấp thông tin về những hạn chế của thiết bị, chẳng hạn như thời lượng chuyển đổi tối đa và tối thiểu giữa các điểm kiểm soát và số lượng điểm kiểm soát tối đa được hỗ trợ cho một hiệu ứng duy nhất:

getMaxSize()
Truy xuất số lượng điểm kiểm soát tối đa được hỗ trợ cho hiệu ứng phong bì.
getMinControlPointDurationMillis()
Truy xuất thời lượng tối thiểu được hỗ trợ (tính bằng mili giây) giữa hai điểm điều khiển trong hiệu ứng phong bì.
getMaxControlPointDurationMillis()
Truy xuất thời lượng tối đa được hỗ trợ (tính bằng mili giây) giữa hai điểm kiểm soát trong hiệu ứng phong bì.
getMaxDurationMillis()
Truy xuất thời lượng tối đa được hỗ trợ cho hiệu ứng phong bì (tính bằng mili giây).

Nếu một hiệu ứng vượt quá giới hạn của thiết bị (chẳng hạn như cho phép quá nhiều điểm kiểm soát hoặc thời lượng vượt quá mức tối đa), thì khung sẽ tự động điều chỉnh hiệu ứng đó cho phù hợp với các ranh giới được phép. Quy trình điều chỉnh này cố gắng giữ nguyên ý định và cảm giác ban đầu của thiết kế càng nhiều càng tốt.

Sử dụng Envelope VibrationEffects

Để biết thông tin chi tiết về cách tạo hiệu ứng dạng sóng bao, hãy xem phần tạo dạng sóng rung có bao.

VibrationEffect thành phần

Thành phần VibrationEffect là hiệu ứng rung được tạo bằng API VibrationEffect.startComposition. API này cho phép tạo ra phản hồi xúc giác phong phú bằng cách tạo một chuỗi các thành phần cơ bản với độ trễ và cường độ tuỳ chỉnh. Tuy nhiên, hãy đặc biệt chú ý để đảm bảo rằng thiết bị hỗ trợ các tính năng đang được kết hợp để tránh trải nghiệm tổng thể không nhất quán.

Khả năng tương thích và yêu cầu

Để phát bất kỳ VibrationEffect nào, bạn cần có quyền VIBRATE trong tệp kê khai ứng dụng.

Không phải thiết bị nào cũng hỗ trợ tất cả các tính năng của API thành phần và điều quan trọng là phải đảm bảo rằng các thành phần cơ bản đều có sẵn.

Kiểm tra xem có hỗ trợ nguyên hàm rung hay không

Bạn có thể truy xuất chế độ hỗ trợ cho từng thành phần bằng phương thức Vibrator.arePrimitivesSupported. Ngoài ra, bạn có thể kiểm tra một nhóm các thành phần cơ bản cùng nhau bằng cách sử dụng phương thức Vibrator.areAllPrimitivesSupported. Phương thức này tương đương với việc AND hỗ trợ cho từng thành phần cơ bản.

Mức sử dụng thành phần VibrationEffect

Để biết thông tin chi tiết về cách sử dụng các thành phần VibrationEffect, hãy xem bài viết Tạo thành phần rung.

Rung bật/tắt, rung một lần và rung theo dạng sóng

Hình thức rung lâu đời nhất được hỗ trợ trên Android là các mẫu bật/tắt bộ rung đơn giản với thời lượng có thể định cấu hình. Các API này thường không phù hợp với các nguyên tắc thiết kế về phản hồi xúc giác vì chúng có thể tạo ra phản hồi xúc giác rung; hãy tránh dùng các API này trừ phi không còn cách nào khác.

Trường hợp sử dụng phổ biến nhất cho chế độ rung bật/tắt là thông báo, trong đó, dù thế nào đi nữa, người dùng vẫn muốn có chế độ rung. Rung theo dạng sóng cũng cho phép một kiểu rung lặp lại vô thời hạn, như bạn có thể hình dung đối với nhạc chuông.

Mẫu rung một lần là mẫu rung một lần trong N mili giây.

Có hai loại mẫu dạng sóng:

  • Chỉ có thời gian. Loại dạng sóng này là nội dung mô tả về thời lượng thay thế đã tắt và thời lượng đã bật. Thời gian bắt đầu bằng khoảng thời gian ở trạng thái tắt. Do đó, các mẫu dạng sóng thường bắt đầu bằng giá trị 0 để cho biết cần bắt đầu rung ngay lập tức.
  • Thời gian và biên độ. Loại dạng sóng này có thêm một mảng biên độ để khớp với từng số liệu thời gian, thay vì bật/tắt ngầm định của dạng đầu tiên. Tuy nhiên, bạn cần kiểm tra để đảm bảo thiết bị hỗ trợ tính năng kiểm soát biên độ nhằm đảm bảo đạt được mức thu phóng dự kiến.

Khả năng tương thích và yêu cầu

Vì chế độ rung bật/tắt là hình thức rung lâu đời nhất, nên chế độ này được hỗ trợ trên hầu hết mọi thiết bị có bộ rung, như mô tả sau trên trang này.

Để phát cuộc gọi VibrationEffect hoặc cuộc gọi vibrate kiểu cũ, bạn cần có quyền VIBRATE trong tệp kê khai ứng dụng.

Khi sử dụng các giá trị biên độ khác nhau trong dạng sóng, bạn nên đảm bảo rằng thiết bị hỗ trợ chế độ kiểm soát biên độ.

Kiểm tra xem có hỗ trợ kiểm soát biên độ hay không

Các giá trị biên độ khác 0 sẽ được làm tròn lên 100% trên những thiết bị không có chế độ kiểm soát biên độ. Vì vậy, bạn cần kiểm tra xem thiết bị có hỗ trợ chế độ này hay không bằng cách dùng Vibrator.hasAmplitudeControl. Hãy xem phần kiểm soát biên độ để biết thêm thông tin chi tiết.

Bạn nên cân nhắc kỹ xem hiệu ứng của mình có đủ chất lượng mà không cần kiểm soát biên độ hay không. Bạn nên chuyển về chế độ rung bật/tắt được thiết kế rõ ràng.

Sử dụng chế độ rung bật/tắt

Ở các cấp độ SDK mới hơn, tất cả chế độ rung đều được hợp nhất thành một lớp VibrationEffect biểu cảm duy nhất, trong đó các chế độ rung đơn giản này được tạo bằng VibrationEffect.createOneshot hoặc VibrationEffect.createWaveform.

API Thông báo

Khi tuỳ chỉnh thông báo của ứng dụng, bạn có thể dùng một trong các API sau để liên kết một mẫu với từng kênh thông báo:

Tất cả các dạng này đều có mẫu dạng sóng bật/tắt cơ bản, như mô tả ở trên, trong đó mục đầu tiên là độ trễ trước khi bật bộ rung.

Khái niệm chung

Một số khái niệm áp dụng cho các nền tảng API được nêu chi tiết ở trên.

Thiết bị có bộ rung không?

Bạn có thể lấy một lớp Vibrator không rỗng từ context.getSystemService(Vibrator.class). Nếu thiết bị không có bộ rung, các lệnh gọi đến API rung sẽ không có tác dụng, vì vậy, các ứng dụng không cần phải hạn chế tất cả các phản hồi xúc giác của mình theo một điều kiện. Tuy nhiên, nếu cần, một ứng dụng có thể gọi hasVibrator() để xác định xem đây có phải là một bộ rung thực (true) hay một phần giữ chỗ (false).

Người dùng có tắt phản hồi xúc giác khi chạm không?

Một số cách triển khai tuỳ chỉnh có thể yêu cầu bạn kiểm tra theo cách thủ công xem người dùng đã tắt hoàn toàn chế độ cài đặt Phản hồi khi chạm của Android hay chưa. Trong trường hợp đó, hiệu ứng phản hồi khi chạm sẽ bị tắt. Bạn có thể truy vấn chế độ cài đặt này bằng khoá HAPTIC_FEEDBACK_ENABLED, trong đó giá trị bằng 0 có nghĩa là đã tắt.

Thuộc tính rung

Bạn có thể cung cấp các thuộc tính rung (hiện ở dạng AudioAttributes) để giúp hệ thống biết được mục đích của chế độ rung. Bạn phải thực hiện việc này khi bắt đầu rung khi ứng dụng ở chế độ nền, vì chỉ có chế độ phản hồi xúc giác chú ý được hỗ trợ cho việc sử dụng ở chế độ nền.

Việc tạo AudioAttributes được đề cập trong tài liệu về lớp này và nên được coi là rung thay vì âm thanh.

Theo hướng dẫn, trong hầu hết các trường hợp, loại nội dung là CONTENT_TYPE_SONIFICATION và mức sử dụng có thể là các giá trị như USAGE_ASSISTANCE_SONIFICATION cho phản hồi khi chạm ở nền trước hoặc USAGE_ALARM cho báo thức ở nền sau. Cờ âm thanh không ảnh hưởng đến chế độ rung.

Điều khiển biên độ

Nếu có chế độ kiểm soát biên độ, thì bộ rung có thể phát ra các rung động với cường độ khác nhau. Đây là một chức năng quan trọng để tạo ra phản hồi xúc giác phong phú, cũng như có thể cho phép người dùng kiểm soát cường độ phản hồi xúc giác mặc định.

Bạn có thể kiểm tra xem có hỗ trợ điều khiển biên độ hay không bằng cách gọi Vibrator.hasAmplitudeControl. Nếu bộ rung không hỗ trợ cường độ, tất cả các giá trị cường độ sẽ được ánh xạ thành trạng thái tắt/bật dựa trên việc chúng có bằng 0 hay không. Do đó, các ứng dụng sử dụng phản hồi xúc giác đa dạng với biên độ khác nhau nên cân nhắc việc tắt phản hồi xúc giác nếu thiết bị thiếu chế độ kiểm soát biên độ.

Hỗ trợ hiệu ứng phong bì

Các bộ rung có hỗ trợ hiệu ứng bao và cho phép tạo ra các rung động linh hoạt và tinh tế hơn, mang đến khả năng kiểm soát chính xác hơn về cường độ và độ sắc nét để có trải nghiệm xúc giác phong phú hơn. Sử dụng Vibration.areEnvelopeEffectsSupported để xác định xem thiết bị của bạn có hỗ trợ tính năng này hay không. Nếu không, các chế độ rung dựa trên phong bì sẽ bị bỏ qua.