feat: add a smooth transition effect when gestures enter (#29)

Author: AmosHuKe

CHANGELOG.md

@@ -3,6 +3,29 @@
 > [!IMPORTANT]  
 > See the [Migration Guide](guides/migration_guide.md) for the details of breaking changes between versions.
 
+## 3.3.0
+
+### New features
+
+- By default, add a smooth transition effect when gestures (hover and touch) enter. ([#29](https://github.com/fluttercandies/flutter_tilt/pull/29))
+  - Configurable via:
+    - `TiltConfig.enterDuration`
+    - `TiltConfig.moveDuration`
+    - `TiltConfig.enterToMoveDuration`
+    - `TiltConfig.enterToMoveCurve`
+
+  If you prefer to disable this effect:
+
+  ```diff
+  Tilt(
+    tiltConfig: TiltConfig(
+      enterToMoveDuration: Duration.zero,
+      ...
+    )
+    ...
+  )
+  ```
+
 ## 3.2.3
 
 ### Improvements

README-ZH.md

@@ -19,7 +19,7 @@
   <a href="https://pub.dev/packages/flutter_tilt/score"><img src="https://img.shields.io/pub/points/flutter_tilt?color=2E8B57&label=%E5%88%86%E6%95%B0&logo=flutter" alt="pub points" /></a>
   <a href="https://www.codefactor.io/repository/github/fluttercandies/flutter_tilt"><img src="https://img.shields.io/codefactor/grade/github/fluttercandies/flutter_tilt?color=0CAB6B&label=%E4%BB%A3%E7%A0%81%E8%B4%A8%E9%87%8F&logo=codefactor" alt="CodeFactor" /></a>
   <a href="https://codecov.io/gh/fluttercandies/flutter_tilt"><img src="https://img.shields.io/codecov/c/github/fluttercandies/flutter_tilt?label=%E6%B5%8B%E8%AF%95%E8%A6%86%E7%9B%96&logo=codecov" alt="codecov" /></a>
-  <a href="https://pub.dev/packages/flutter_tilt"><img src="https://img.shields.io/github/languages/top/fluttercandies/flutter_tilt?color=00B4AB" alt="top language" /></a>
+  <a href="https://pub.dev/packages/flutter_tilt/license"><img src="https://img.shields.io/github/license/fluttercandies/flutter_tilt?label=%E8%AE%B8%E5%8F%AF%E8%AF%81&color=8EBC06" alt="license" /></a>
 </p>
 
 <p align="center">
@@ -318,9 +318,12 @@ tiltStreamController.add(
 | enableGestureTouch | `bool` | `true` | Touch 手势触发倾斜。 <br/> 仅以下手势生效： <br/> `GesturesType.touch` |  
 | enableRevert | `bool` | `true` | 启用倾斜复原，会复原至初始状态。 <br/> 仅以下手势生效： <br/> `GesturesType.touch` <br/> `GesturesType.hover` <br/> `GesturesType.controller` |  
 | enableOutsideAreaMove | `bool` | `true` | 可以继续在区域外触发倾斜。 <br/> 仅以下手势生效： <br/> `GesturesType.touch` <br/> `GesturesType.controller` |  
+| enterDuration | `Duration` | `Duration(milliseconds: 1000)` | 手势刚进入时的动画持续时间，需要搭配 `[moveDuration]` 和 `[enterToMoveDuration]` 使用。 <br/> 仅以下手势生效： <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
 | moveDuration | `Duration` | `Duration(milliseconds: 100)` | 手势移动时的动画持续时间。 <br/> 仅以下手势生效： <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
+| enterToMoveDuration | `Duration` | `Duration(milliseconds: 600)` | 手势从 Enter 过渡至 Move 的持续时间，需要搭配 `[enterDuration]` 和 `[moveDuration]` 使用。 <br/> 仅以下手势生效： <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
 | leaveDuration | `Duration` | `Duration(milliseconds: 300)` | 手势离开后的动画持续时间。 <br/> 仅以下手势生效： <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
 | moveCurve | `Curve` | `Curves.linear` | 手势移动时的动画曲线。 <br/> 仅以下手势生效： <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
+| enterToMoveCurve | `Curve` | `Curves.easeOutCubic` | 手势从 Enter 过渡至 Move 的曲线，需要搭配 `[enterToMoveDuration]` 使用。 <br/> 仅以下手势生效： <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
 | leaveCurve | `Curve` | `Curves.linear` | 手势离开后的动画曲线。 <br/> 仅以下手势生效： <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
 | controllerMoveDuration | `Duration` | `Duration(milliseconds: 100)` | controller 手势移动时的动画持续时间。 <br/> 仅以下手势生效： <br/> `GesturesType.controller` |  
 | controllerLeaveDuration | `Duration` | `Duration(milliseconds: 300)` | controller 手势离开后的动画持续时间。 <br/> 仅以下手势生效： <br/> `GesturesType.controller` |  

README.md

@@ -19,7 +19,7 @@
   <a href="https://pub.dev/packages/flutter_tilt/score"><img src="https://img.shields.io/pub/points/flutter_tilt?color=2E8B57&logo=flutter" alt="pub points" /></a>
   <a href="https://www.codefactor.io/repository/github/fluttercandies/flutter_tilt"><img src="https://img.shields.io/codefactor/grade/github/fluttercandies/flutter_tilt?color=0CAB6B&logo=codefactor" alt="CodeFactor" /></a>
   <a href="https://codecov.io/gh/fluttercandies/flutter_tilt"><img src="https://img.shields.io/codecov/c/github/fluttercandies/flutter_tilt?label=coverage&logo=codecov" alt="codecov" /></a>
-  <a href="https://pub.dev/packages/flutter_tilt"><img src="https://img.shields.io/github/languages/top/fluttercandies/flutter_tilt?color=00B4AB" alt="top language" /></a>
+  <a href="https://pub.dev/packages/flutter_tilt/license"><img src="https://img.shields.io/github/license/fluttercandies/flutter_tilt?color=8EBC06" alt="license" /></a>
 </p>
 
 <p align="center">
@@ -65,7 +65,7 @@ Check out the [Live Demo][].
 
 - [Sensors compatibility][]
 
-- [Gestures priority](#gestures-priority-)
+- [Gesture priority](#gesture-priority-)
 
 - [Simple usage](#simple-usage-)
 
@@ -160,7 +160,7 @@ Platforms without sensors support do not affect the normal use of other features
 <!-- > After that maybe replace it with [DeviceMotionEvent][]. -->
 
 
-## Gestures priority 📱
+## Gesture priority 📱
 
 When multiple gestures are enabled, they are triggered based on priority:
 
@@ -318,9 +318,12 @@ tiltStreamController.add(
 | enableGestureTouch | `bool` | `true` | Touch gesture triggered tilt. <br/> Only the following gestures: <br/> `GesturesType.touch` |  
 | enableRevert | `bool` | `true` | Enable tilt revert, will revert to the initial state. <br/> Only the following gestures: <br/> `GesturesType.touch` <br/> `GesturesType.hover` <br/> `GesturesType.controller` |  
 | enableOutsideAreaMove | `bool` | `true` | Tilt can continue to be triggered outside the area. <br/> Only the following gestures: <br/> `GesturesType.touch` <br/> `GesturesType.controller` |  
+| enterDuration | `Duration` | `Duration(milliseconds: 1000)` | Animation duration during gesture enter, must be used with `[moveDuration]` and `[enterToMoveDuration]`. <br/> Only the following gestures: <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
 | moveDuration | `Duration` | `Duration(milliseconds: 100)` | Animation duration during gesture move. <br/> Only the following gestures: <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
+| enterToMoveDuration | `Duration` | `Duration(milliseconds: 600)` | The duration of the transition from enter to move, must be used with `[enterDuration]` and `[moveDuration]`. <br/> Only the following gestures: <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
 | leaveDuration | `Duration` | `Duration(milliseconds: 300)` | Animation duration after gesture leave. <br/> Only the following gestures: <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
 | moveCurve | `Curve` | `Curves.linear` | Animation curve during gesture move. <br/> Only the following gestures: <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
+| enterToMoveCurve | `Curve` | `Curves.easeOutCubic` | The curve of the transition from enter to move, must be used with `[enterToMoveDuration]`. <br/> Only the following gestures: <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
 | leaveCurve | `Curve` | `Curves.linear` | Animation curve after gesture leave. <br/> Only the following gestures: <br/> `GesturesType.touch` <br/> `GesturesType.hover` |  
 | controllerMoveDuration | `Duration` | `Duration(milliseconds: 100)` | Animation duration during controller gesture move. <br/> Only the following gestures: <br/> `GesturesType.controller` |  
 | controllerLeaveDuration | `Duration` | `Duration(milliseconds: 300)` | Animation duration after controller gesture leave. <br/> Only the following gestures: <br/> `GesturesType.controller` |  

lib/src/config/tilt_config.dart

@@ -33,9 +33,12 @@ class TiltConfig {
     this.enableGestureTouch = true,
     this.enableRevert = true,
     this.enableOutsideAreaMove = true,
+    this.enterDuration = const Duration(milliseconds: 1000),
     this.moveDuration = const Duration(milliseconds: 100),
+    this.enterToMoveDuration = const Duration(milliseconds: 600),
     this.leaveDuration = const Duration(milliseconds: 300),
     this.moveCurve = Curves.linear,
+    this.enterToMoveCurve = Curves.easeOutCubic,
     this.leaveCurve = Curves.linear,
     this.controllerMoveDuration = const Duration(milliseconds: 100),
     this.controllerLeaveDuration = const Duration(milliseconds: 300),
@@ -275,6 +278,26 @@ class TiltConfig {
   ///
   final bool enableOutsideAreaMove;
 
+  /// Animation duration during gesture enter,
+  ///
+  /// must be used with [moveDuration] and [enterToMoveDuration].
+  ///
+  /// Only the following gestures:
+  /// [GesturesType.touch]
+  /// [GesturesType.hover]
+  ///
+  /// ------
+  ///
+  /// 手势刚进入时的动画持续时间，
+  ///
+  /// 需要搭配 [moveDuration] 和 [enterToMoveDuration] 使用。
+  ///
+  /// 仅以下手势生效：
+  /// [GesturesType.touch]
+  /// [GesturesType.hover]
+  ///
+  final Duration enterDuration;
+
   /// Animation duration during gesture move.
   ///
   /// Only the following gestures:
@@ -291,6 +314,26 @@ class TiltConfig {
   ///
   final Duration moveDuration;
 
+  /// The duration of the transition from enter to move,
+  ///
+  /// must be used with [enterDuration] and [moveDuration].
+  ///
+  /// Only the following gestures:
+  /// [GesturesType.touch]
+  /// [GesturesType.hover]
+  ///
+  /// ------
+  ///
+  /// 手势从 Enter 过渡至 Move 的持续时间，
+  ///
+  /// 需要搭配 [enterDuration] 和 [moveDuration] 使用。
+  ///
+  /// 仅以下手势生效：
+  /// [GesturesType.touch]
+  /// [GesturesType.hover]
+  ///
+  final Duration enterToMoveDuration;
+
   /// Animation duration after gesture leave.
   ///
   /// Only the following gestures:
@@ -323,6 +366,26 @@ class TiltConfig {
   ///
   final Curve moveCurve;
 
+  /// The curve of the transition from enter to move,
+  ///
+  /// must be used with [enterToMoveDuration].
+  ///
+  /// Only the following gestures:
+  /// [GesturesType.touch]
+  /// [GesturesType.hover]
+  ///
+  /// ------
+  ///
+  /// 手势从 Enter 过渡至 Move 的曲线，
+  ///
+  /// 需要搭配 [enterToMoveDuration] 使用。
+  ///
+  /// 仅以下手势生效：
+  /// [GesturesType.touch]
+  /// [GesturesType.hover]
+  ///
+  final Curve enterToMoveCurve;
+
   /// Animation curve after gesture leave.
   ///
   /// Only the following gestures:
@@ -382,9 +445,12 @@ class TiltConfig {
     bool? enableGestureTouch,
     bool? enableRevert,
     bool? enableOutsideAreaMove,
+    Duration? enterDuration,
     Duration? moveDuration,
+    Duration? enterToMoveDuration,
     Duration? leaveDuration,
     Curve? moveCurve,
+    Curve? enterToMoveCurve,
     Curve? leaveCurve,
     Duration? controllerMoveDuration,
     Duration? controllerLeaveDuration,
@@ -406,9 +472,12 @@ class TiltConfig {
       enableRevert: enableRevert ?? this.enableRevert,
       enableOutsideAreaMove:
           enableOutsideAreaMove ?? this.enableOutsideAreaMove,
+      enterDuration: enterDuration ?? this.enterDuration,
       moveDuration: moveDuration ?? this.moveDuration,
+      enterToMoveDuration: enterToMoveDuration ?? this.enterToMoveDuration,
       leaveDuration: leaveDuration ?? this.leaveDuration,
       moveCurve: moveCurve ?? this.moveCurve,
+      enterToMoveCurve: enterToMoveCurve ?? this.enterToMoveCurve,
       leaveCurve: leaveCurve ?? this.leaveCurve,
       controllerMoveDuration:
           controllerMoveDuration ?? this.controllerMoveDuration,
@@ -442,9 +511,12 @@ class TiltConfig {
         other.enableGestureTouch == enableGestureTouch &&
         other.enableRevert == enableRevert &&
         other.enableOutsideAreaMove == enableOutsideAreaMove &&
+        other.enterDuration == enterDuration &&
         other.moveDuration == moveDuration &&
+        other.enterToMoveDuration == enterToMoveDuration &&
         other.leaveDuration == leaveDuration &&
         other.moveCurve == moveCurve &&
+        other.enterToMoveCurve == enterToMoveCurve &&
         other.leaveCurve == leaveCurve &&
         other.controllerMoveDuration == controllerMoveDuration &&
         other.controllerLeaveDuration == controllerLeaveDuration;
@@ -468,9 +540,12 @@ class TiltConfig {
       enableGestureTouch,
       enableRevert,
       enableOutsideAreaMove,
+      enterDuration,
       moveDuration,
+      enterToMoveDuration,
       leaveDuration,
       moveCurve,
+      enterToMoveCurve,
       leaveCurve,
       controllerMoveDuration,
       controllerLeaveDuration,

lib/src/internal/controllers/tilt_gestures_controller.dart

@@ -84,32 +84,40 @@ class TiltGesturesController {
 
   /// 过滤 TiltStream
   TiltStreamModel filterTiltStream(TiltStreamModel tiltStreamModel) {
-    /// 当前手势是否高优先级
-    final isHighPriority = gesturesTypePriority(
-          tiltStreamModel.gesturesType,
-          latestTiltStreamModel.gesturesType,
-        ) ==
-        tiltStreamModel.gesturesType;
-
     switch (tiltStreamModel.gesturesType) {
       case GesturesType.none:
         break;
       case GesturesType.touch || GesturesType.hover || GesturesType.controller:
-        if (isHighPriority || !latestTiltStreamModel.gestureUse) {
-          latestTiltStreamModel = tiltStreamModel;
-        }
+        {
+          if (latestTiltStreamModel == tiltStreamModel) {
+            return tiltStreamModel;
+          }
 
-        /// 避免 sensors 与其他手势触发冲突
-        if (!tiltStreamModel.gestureUse) {
-          _handleGestureConflict(tiltStreamModel.gesturesType);
-          _enableSensors = true;
-        } else {
-          _enableSensors = false;
+          /// 当前手势是否高优先级
+          final isHighPriority = gesturesTypePriority(
+                tiltStreamModel.gesturesType,
+                latestTiltStreamModel.gesturesType,
+              ) ==
+              tiltStreamModel.gesturesType;
+
+          if (isHighPriority || !latestTiltStreamModel.gestureUse) {
+            latestTiltStreamModel = tiltStreamModel;
+          }
+
+          /// 避免 sensors 与其他手势触发冲突
+          if (!tiltStreamModel.gestureUse) {
+            _handleGestureConflict(tiltStreamModel.gesturesType);
+            _enableSensors = true;
+          } else {
+            _enableSensors = false;
+          }
         }
       case GesturesType.sensors:
-        // 避免 sensors 与其他手势触发冲突
-        if (_enableSensors && _gesturesHarmonizerTimer == null) {
-          _updateSensorTiltPosition(tiltStreamModel);
+        {
+          /// 避免 sensors 与其他手势触发冲突
+          if (_enableSensors && _gesturesHarmonizerTimer == null) {
+            _updateSensorTiltPosition(tiltStreamModel);
+          }
         }
     }
     return latestTiltStreamModel;
@@ -150,6 +158,7 @@ class TiltGesturesController {
   ///
   /// 避免其他手势离开后的动画与 sensors 冲突（出现闪现）
   void _gesturesHarmonizer(Duration duration) {
+    if (_gesturesHarmonizerTimer != null) return;
     _gesturesHarmonizerTimer?.cancel();
     _gesturesHarmonizerTimer = async.Timer(
       duration,

lib/src/internal/mixin/tilt_decoration_mixin.dart

@@ -3,7 +3,7 @@ import 'package:flutter/widgets.dart';
 import '../../enums.dart';
 import '../../utils.dart';
 
-mixin TiltDecoration {
+mixin TiltDecorationMixin {
   /// 计算提供的方向进度
   ///
   /// 范围：0-1