Skip to content

Commit 84a3c49

Browse files
m-bertm-bert
committed
Migration guide
1 parent f0c518d commit 84a3c49

3 files changed

Lines changed: 246 additions & 117 deletions

File tree

‎packages/docs-gesture-handler/docs/guides/upgrading-to-2.md‎

Lines changed: 0 additions & 117 deletions
This file was deleted.

‎packages/docs-gesture-handler/docs/guides/upgrading-to-3.md‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
---
2+
id: upgrading-to-3
3+
title: Upgrading to the new API introduced in Gesture Handler 3
4+
---
5+
6+
## Migrating gestures
7+
8+
The most important change brought by the Gesture Handler 3 is the new hook API. Migration is pretty straight-forward. Instead of calling builder methods, everything is passed into configuration object. So, the code like this:
9+
10+
```tsx
11+
const gesture = Gesture.Pan()
12+
.onBegin(() => {
13+
console.log('Pan!');
14+
})
15+
.minDistance(25);
16+
```
17+
18+
Now looks like this:
19+
20+
```tsx
21+
const gesture = usePanGesture({
22+
onBegin: () => {
23+
console.log('Pan!');
24+
},
25+
minDistance: 25,
26+
});
27+
```
28+
29+
:::danger Force Touch Gesture
30+
[`ForceTouch`](/docs/2.x/gestures/force-touch-gesture) gesture is not available in hook API.
31+
:::
32+
33+
### Renamed callbacks
34+
35+
In Gesture Handler 3 some of the callbacks were renamed, namely:
36+
37+
| RNGH3 | RNGH3 |
38+
| --------- | -------------- |
39+
| `onStart` | `onActivate` |
40+
| `onEnd` | `onDeactivate` |
41+
42+
So the following code from Gesture Handler 2:
43+
44+
```tsx
45+
const gesture = Gesture.Pan()
46+
.onStart(() => {
47+
console.log('Pan start!');
48+
})
49+
.onEnd(() => {
50+
console.log('Pan end!');
51+
});
52+
```
53+
54+
in Gesture Handler 3 looks like this:
55+
56+
```tsx
57+
const gesture = usePanGesture({
58+
onActivate: () => {
59+
console.log('Pan activated!');
60+
},
61+
onDeactivate: () => {
62+
console.log('Pan deactivated!');
63+
},
64+
});
65+
```
66+
67+
<details>
68+
<summary>Full changes</summary>
69+
70+
| RNGH2 | RNGH3 |
71+
| ---------------------- | ----------------------- |
72+
| `Gesture.Pan()` | `usePanGesture()` |
73+
| `Gesture.Tap()` | `useTapGesture()` |
74+
| `Gesture.LongPress()` | `useLongPressGesture()` |
75+
| `Gesture.Rotation()` | `useRotationGesture()` |
76+
| `Gesture.Pinch()` | `usePinchGesture()` |
77+
| `Gesture.Fling()` | `useFlingGesture()` |
78+
| `Gesture.Hover()` | `useHoverGesture()` |
79+
| `Gesture.Native()` | `useNativeGesture()` |
80+
| `Gesture.Manual()` | `useManualGesture()` |
81+
| `Gesture.ForceTouch()` | |
82+
83+
</details>
84+
85+
## Migrating relations
86+
87+
### Composed gestures
88+
89+
Previously, composed gestures were created using `Gesture` object. In Gesture Handler 3, relations are set up using relation hooks. For example, the following code from Gesture Handler 2:
90+
91+
```tsx
92+
const pan1 = Gesture.Pan();
93+
const pan2 = Gesture.Pan();
94+
95+
const gesture = Gesture.Simultaneous(pan1, pan2);
96+
```
97+
98+
in Gesture Handler 3 looks like this:
99+
100+
```tsx
101+
const pan1 = usePanGesture({});
102+
const pan2 = usePanGesture({});
103+
104+
const gesture = useSimultaneousGestures(pan1, pan2);
105+
```
106+
107+
:::danger Race gesture
108+
In Gesture Handler 3 `Race` gesture was renamed to `Competing` gesture.
109+
:::
110+
111+
### Cross components relations properties
112+
113+
Properties used to define cross-components interactions were renamed. For example, the following code from Gesture Handler 2:
114+
115+
```tsx
116+
const pan1 = Gesture.Pan();
117+
const pan2 = Gesture.Pan().requireExternalGestureToFail(pan1);
118+
```
119+
120+
in Gesture Handler 3 looks like this:
121+
122+
```tsx
123+
const pan1 = usePanGesture({});
124+
const pan2 = usePanGesture({
125+
requireToFail: pan1,
126+
});
127+
```
128+
129+
<details>
130+
<summary>Full changes</summary>
131+
132+
| RNGH2 | RNGH3 |
133+
| ----------------------------------------- | --------------------------- |
134+
| `Gesture.Race()` | `useCompetingGestures()` |
135+
| `Gesture.Simultaneous()` | `useSimultaneousGestures()` |
136+
| `Gesture.Exclusive()` | `useExclusiveGestures()` |
137+
| | |
138+
| `gesture.simultaneousWithExternalGesture` | `gesture.simultaneousWith` |
139+
| `gesture.requireExternalGestureToFail` | `gesture.requireToFail` |
140+
| `gesture.blocksExternalGesture` | `gesture.block` |
141+
142+
</details>
143+
144+
## Using SVG
145+
146+
In Gesture Handler 2 it was possible to use `GestureDetector` directly on `SVG`:
147+
148+
```tsx
149+
// highlight-next-line
150+
<GestureDetector gesture={containerTap}>
151+
<Svg>
152+
// highlight-next-line
153+
<GestureDetector gesture={circleElementTap}>
154+
<Circle />
155+
</GestureDetector>
156+
</Svg>
157+
</GestureDetector>
158+
```
159+
160+
In Gesture Handler 3, the correct way to interact with `SVG` is to use `InterceptingGestureDetector` and `VirtualGestureDetector`:
161+
162+
```tsx
163+
// highlight-next-line
164+
<InterceptingGestureDetector gesture={containerTap}>
165+
<Svg>
166+
// highlight-next-line
167+
<VirtualGestureDetector gesture={circleElementTap}>
168+
<Circle />
169+
</VirtualGestureDetector>
170+
</Svg>
171+
</InterceptingGestureDetector>
172+
```
173+
174+
:::danger Detectors order
175+
`VirtualGestureDetector` has to be a child of `InterceptingGestureDetector`.
176+
:::
177+
178+
## Old components
179+
180+
Components were rewritten to use new hook API. If for some reason you need to use old components, they now also use `Legacy` prefix, e.g. `RectButton` becomes `LegacyRectButton`.
181+
182+
<details>
183+
<summary>Full changes</summary>
184+
185+
| RNGH2 | RNGH3 |
186+
| --------------------- | --------------------------- |
187+
| `RawButton` | `LegacyRawButton` |
188+
| `BaseButton` | `LegacyBaseButton` |
189+
| `RectButton` | `LegacyRectButton` |
190+
| `BorderlessButton` | `LegacyBorderlessButton` |
191+
| | |
192+
| `ScrollView` | `LegacyScrollView` |
193+
| `FlatList` | `LegacyFlatList` |
194+
| `RefreshControl` | `LegacyRefreshControl` |
195+
| `Switch` | `LegacySwitch` |
196+
| `TextInput` | `LegacyTextInput` |
197+
| `DrawerLayoutAndroid` | `LegacyDrawerLayoutAndroid` |
198+
199+
</details>
200+
201+
## Replaced types
202+
203+
Most of the types, like `TapGesture`, are still present in Gesture Handler 3. However, they are now used in new hook API. Types for old API now have `Legacy` prefix, e.g. `TapGesture` becomes `LegacyTapGesture`.
204+
205+
<details>
206+
<summary>Full changes</summary>
207+
208+
| RNGH2 | RNGH3 |
209+
| ----------------------- | ----------------------------- |
210+
| `PanGesture` | `LegacyPanGesture` |
211+
| `TapGesture` | `LegacyTapGesture` |
212+
| `LongPressGesture` | `LegacyLongPressGesture` |
213+
| `RotationGesture` | `LegacyRotationGesture` |
214+
| `PinchGesture` | `LegacyPinchGesture` |
215+
| `FlingGesture` | `LegacyFlingGesture` |
216+
| `HoverGesture` | `LegacyHoverGesture` |
217+
| `NativeGesture` | `LegacyNativeGesture` |
218+
| `ManualGesture` | `LegacyManualGesture` |
219+
| `ForceTouchGesture` | `LegacyForceTouchGesture` |
220+
| | |
221+
| `ComposedGesture` | `LegacyComposedGesture` |
222+
| `RaceGesture` | `LegacyRaceGesture` |
223+
| `SimultaneousGesture` | `LegacySimultaneousGesture` |
224+
| `ExclusiveGesture` | `LegacyExclusiveGesture` |
225+
| | |
226+
| `RawButtonProps` | `LegacyRawButtonProps` |
227+
| `BaseButtonProps` | `LegacyBaseButtonProps` |
228+
| `RectButtonProps` | `LegacyRectButtonProps` |
229+
| `BorderlessButtonProps` | `LegacyBorderlessButtonProps` |
230+
| | |
231+
| `ScrollView` | `LegacyScrollView` |
232+
| `FlatList` | `LegacyFlatList` |
233+
| `RefreshControl` | `LegacyRefreshControl` |
234+
| `Switch` | `LegacySwitch` |
235+
| `TextInput` | `LegacyTextInput` |
236+
| `DrawerLayoutAndroid` | `LegacyDrawerLayoutAndroid` |
237+
238+
</details>

‎packages/docs-gesture-handler/src/css/overrides.css‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,14 @@ table thead tr {
5555
border: transparent 2px solid;
5656
}
5757

58+
details tr {
59+
background: var(--ifm-background-color);
60+
}
61+
62+
details thead {
63+
background: var(--ifm-background-color);
64+
}
65+
5866
@media (min-width: 996px) {
5967
.header-github {
6068
margin-left: 1.5em;

0 commit comments

Comments
 (0)