搜尋套件、儲存庫與 APP 分類

套件詳情v0.8.0

haptic_feedback

用於觸覺反饋的 Flutter 外掛程式。雖然它使用標準的 iOS 觸覺反饋,但旨在於 Android 上模擬相同的觸覺模式,以實現跨平台的一致體驗。

AndroidiOS
近 30 天下載
4.8萬
喜歡數
136
Pub 分數
160

安裝套件

flutter pub add haptic_feedback

套件介紹

根據套件公開資料產生的選型評估,僅供參考。

haptic_feedback 套件在 Flutter 應用中為 Android 與 iOS 平台提供一致的觸覺反饋。它利用原生 iOS 觸覺技術,同時在 Android 上模擬類似模式,以確保統一的使用者體驗。專為尋求應用中觸覺回應的開發者設計,支援標準觸覺模式,如衝擊、通知與選擇。此外,該套件輕量且易於整合,非常適合增強行動應用中的互動回饋。

適用情境

  • 透過觸覺反饋增強觸控互動
  • 透過物理提示改善可訪問性
  • 在遊戲應用中添加響應式反饋
  • 創造沉浸式使用者體驗
  • 支援手勢導航
  • 為操作提供確認反饋

主要特色

  • 跨平台觸覺一致性
  • 在 Android 上模擬 iOS 觸覺反饋
  • 用於常見觸覺模式的簡單 API
  • 輕量且高效
  • 支援影響、通知和選擇類型
  • 透過 Flutter pub 實現輕鬆整合

適合對象

  • 面向 Android 和 iOS 的移動應用開發者
  • 以可存取性為重點的應用程式設計
  • 需要觸覺回饋的互動式UI組件
  • 遊戲化或手勢驅動的介面
  • 使用者回饋提升易用性的應用

使用建議

  • 僅限基本觸覺模式
  • Android 模擬可能會因裝置而異
  • 並非所有裝置都支援進階觸覺反饋
  • 需要平台特定權限
  • 行為在不同平台之間略有差異
  • 依賴硬體功能以獲得最佳效果

原始 README

以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。

haptic_feedback

A haptic feedback plugin for both iOS and Android.

While it utilizes standard iOS haptics, it aims to emulate these same haptic patterns on Android for a consistent experience across platforms.

For a guide on when to use each haptic type, see Missing haptic types, and which to use when by Kamran.

Getting Started

1. Add the dependency
flutter pub add haptic_feedback
2. Use the plugin
final canVibrate = await Haptics.canVibrate();

await Haptics.vibrate(HapticsType.success);
await Haptics.vibrate(HapticsType.warning);
await Haptics.vibrate(HapticsType.error);

await Haptics.vibrate(HapticsType.light);
await Haptics.vibrate(HapticsType.medium);
await Haptics.vibrate(HapticsType.heavy);

await Haptics.vibrate(HapticsType.rigid);
await Haptics.vibrate(HapticsType.soft);

await Haptics.vibrate(HapticsType.selection);

If you want to be defensive, you can wrap calls in a try/catch to handle a PlatformException. Native exceptions are caught and returned as PlatformException (code: VIBRATION_ERROR) so they won't crash your app, but you can log or react if needed:

try {
  await Haptics.vibrate(HapticsType.success);
} on PlatformException catch (e) {
  // Handle or log as needed
}

Android-specific options

// Use native Android haptic constants (default: false)
// When true, uses HapticFeedbackConstants like CONFIRM, REJECT, etc.
// When false, uses custom vibration primitives that are more aligned
// with iOS haptics
await Haptics.vibrate(
  HapticsType.success,
  useAndroidHapticConstants: false,  // default
);

// On Android 13+, you can hint how the system should treat this vibration
// (alarm, communicationRequest, hardwareFeedback, media, notification, physicalEmulation, ringtone, touch, unknown)
await Haptics.vibrate(
  HapticsType.success,
  usage: HapticsUsage.media,
);

The optional usage parameter is a hint for the system. It can influence how the vibration is routed and which volume / haptics settings control it (for example, notification vs touch feedback).

Use a concrete value whenever the vibration clearly matches one of the defined categories (for example HapticsUsage.notification for reminders or status updates), and keep the default HapticsUsage.unknown for simple taps and other lightweight UI feedback.

iOS: SwiftPM vs CocoaPods

Flutter can consume this plugin via Swift Package Manager (SPM) or CocoaPods. SPM support in Flutter is still experimental:

  1. To enable SPM (Flutter 3.24+): flutter config --enable-swift-package-manager or add to pubspec.yaml:

    flutter:
      config:
        enable-swift-package-manager: true
    

    If you hit Xcode build issues after switching, do a one-time clean: flutter clean and remove Xcode DerivedData for this app (e.g., rm -rf ~/Library/Developer/Xcode/DerivedData/Runner-*), then rebuild.

  2. To stick with CocoaPods (or if you hit SPM issues): disable SPM with flutter config --no-enable-swift-package-manager or by adding to pubspec.yaml:

    flutter:
      config:
        enable-swift-package-manager: false
    

The plugin still supports CocoaPods; SPM is available for native iOS apps and newer Flutter toolchains.

Platform Implementation

iOS

Uses Apple's native haptic feedback APIs:

  • UINotificationFeedbackGenerator for success, warning, and error
  • UIImpactFeedbackGenerator for light, medium, heavy, rigid, and soft
  • UISelectionFeedbackGenerator for selection
Android

On Android, the plugin defaults to high-fidelity haptic primitives on API 30+ (great on devices with advanced/HD hardware); falls back to waveforms on API 26-29 and legacy timing-only vibration on older SDKs; and can opt into system HapticFeedbackConstants via useAndroidHapticConstants on supported SDKs. The plugin uses a multi-strategy approach for the best possible haptic experience:

Strategy 1: Native HapticFeedbackConstants (when enabled)

When useAndroidHapticConstants: true, the plugin uses Android's system-level haptic constants via View.performHapticFeedback():

Type Android Constant API Level
success CONFIRM ≥ 30
error REJECT ≥ 30
light VIRTUAL_KEY ≥ 5
medium KEYBOARD_PRESS (≥ 27) / KEYBOARD_TAP (≥ 8) ≥ 8
heavy CONTEXT_CLICK ≥ 23
selection CLOCK_TICK ≥ 21

Note: warning, rigid, and soft don't have direct Android mappings and fall back to primitives/waveforms/legacy.

Strategy 2: Haptic Primitives (API 30+)

When native constants aren't available or useAndroidHapticConstants: false (default), the plugin uses VibrationEffect.Composition, which is tuned to resemble the iOS patterns:

Type Primitive(s) Description
success CLICK × 2 Two clicks with increasing intensity
warning CLICK × 2 Two clicks with decreasing intensity
error CLICK × 4 Four clicks with an accented third pulse
light TICK Subtle, light feedback
medium CLICK Moderate feedback
heavy THUD Strong, deep feedback
rigid CLICK Sharp, crisp feedback
soft SPIN* Gentle, longer feedback
selection TICK Subtle selection feedback

* SPIN requires API 31+; falls back to TICK on API 30.

Strategy 3: Waveform Vibrations (API 26-29)

For devices without primitive support, the plugin uses VibrationEffect.createWaveform() with amplitude control.

Strategy 4: Legacy Vibration (API < 26)

Basic timing-only patterns for older devices.

For detailed timing specifications and implementation rationale, see HAPTIC_PATTERNS.md.

Testing

When testing widgets that use haptic feedback, defaultTargetPlatform is TargetPlatform.android by default, but the default platform implementation still calls the method channel and will throw MissingPluginException unless you register a mock. If you swap in a mock platform that returns true, Haptics.canVibrate() will return true even on a non-mobile host unless you override the target platform.

To test widgets that use haptic feedback, you can:

  1. Use debugDefaultTargetPlatformOverride to test platform-specific behavior:
import 'package:flutter/foundation.dart';

void main() {
  testWidgets('test on iOS', (tester) async {
    debugDefaultTargetPlatformOverride = TargetPlatform.iOS;
    addTearDown(() => debugDefaultTargetPlatformOverride = null);

    // Your test code here
  });
}
  1. Mock the platform interface in your tests:
import 'package:haptic_feedback/src/haptic_feedback_platform_interface.dart';
import 'package:plugin_platform_interface/plugin_platform_interface.dart';

class MockHapticFeedbackPlatform extends Mock
    with MockPlatformInterfaceMixin
    implements HapticFeedbackPlatform {}

void main() {
  testWidgets('my widget test', (tester) async {
    final mockPlatform = MockHapticFeedbackPlatform();
    HapticFeedbackPlatform.instance = mockPlatform;
    
    when(() => mockPlatform.canVibrate()).thenAnswer((_) async => true);
    when(() => mockPlatform.vibrate(any())).thenAnswer((_) async {});
    
    // Your test code here
  });
}
  1. Mock the method channel to avoid MissingPluginException while using the real platform class:
import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:haptic_feedback/src/haptic_feedback_method_channel.dart';
import 'package:haptic_feedback/src/haptics_type.dart';

void main() {
  const channel = MethodChannelHapticFeedback.methodChannel;
  TestDefaultBinaryMessengerBinding.ensureInitialized();

  setUp(() {
    final binding = TestDefaultBinaryMessengerBinding.instance;
    binding.defaultBinaryMessenger.setMockMethodCallHandler(
      channel,
      (MethodCall call) async {
        if (call.method == 'canVibrate') return true;
        return null; // success for vibrate calls
      },
    );
  });

  tearDown(() {
    final binding = TestDefaultBinaryMessengerBinding.instance;
    binding.defaultBinaryMessenger.setMockMethodCallHandler(channel, null);
  });

  test('canVibrate works with mocked channel', () async {
    expect(await MethodChannelHapticFeedback().canVibrate(), isTrue);
  });

  test('vibrate forwards to mocked channel', () async {
    await MethodChannelHapticFeedback().vibrate(HapticsType.success);
  });
}

You can find these examples as runnable tests in example/test on GitHub.

Automatic Permissions Inclusion

Android VIBRATE Permission

When you integrate the haptic_feedback plugin into your Flutter project, it will automatically include the necessary VIBRATE permission in the final merged AndroidManifest.xml of your app. This is due to the permission being declared in the plugin's manifest.

What this means for you:
  • No Manual Action Required: You don't have to add the <uses-permission android:name="android.permission.VIBRATE"/> permission to your app's AndroidManifest.xml manually. It will be automatically merged when building the app.

  • Transparency: By using the haptic_feedback plugin, your app will request the VIBRATE permission. Ensure that you are aware of all permissions your app requires, especially if you publish it on app stores. Some users may be sensitive to app permissions, even if they don't require explicit consent.

  • Permission Overview: To review all permissions that your app requests due to plugins and your own declarations, inspect the final merged AndroidManifest.xml after a build. This will provide a comprehensive view of all permissions and other manifest entries.

所屬分類

依賴

依賴清單 1 項

  • plugin_platform_interface^2.0.0

原始碼儲存庫

使用此套件的專案