Build a Native‑Like Image Preview with Gestures Using AlloyFinger

Implementation Overview

The native QQ image preview supports paging and various gestures; this guide shows how to achieve the same experience in H5 using AlloyFinger, transform.js, and to.js.

Implementation Basics

The image preview component is built on AlloyFinger.js for gesture support, transform.js for CSS3 property manipulation, and to.js for animation transitions.

AlloyFinger provides tap, double‑tap, long‑press, drag, pinch, and rotate gestures. Transform.js adds JavaScript properties for CSS3 transforms such as translateX, translateY, scaleX, rotateZ, etc. To.js offers requestAnimationFrame‑based transition functions.

Project URLs: https://github.com/AlloyTeam/AlloyFinger, http://alloyteam.github.io/AlloyTouch/transformjs/, https://github.com/AlloyTeam/AlloyFinger/blob/master/asset/to.js

Implementation Details

1. Page Flipping

Maintain exactly three images in the container, keeping the middle one always visible. After a swipe, remove the previous image and append the next one to preserve the three‑image state, which reduces DOM nodes and improves animation performance.

2. Origin, Scale and Translate Transformations

Scaling requires setting

scale

and adjusting

origin

. When the origin changes while scale is non‑zero,

translate

must be updated to keep the image stationary. For a 100 × 100 image with origin (0,0), scale = 2, translate = (0,0), changing origin to (50,50) requires translate = (50,50).

Formula for new translateX (X‑axis example):

translateX2 = translateX1 + (originX2 - originX1) * s

During

touchstart

the origin and translate values are recomputed; during

touchmove

only

scale

changes.

3. Gesture Detail – Boundary Detection

When the image is zoomed, dragging is limited to a range so the image cannot be moved beyond its edges. For origin (0,0) and scale = s, the allowed translateX range is

[-(w*s - w), 0]

. If the origin is not (0,0), translate is first converted to the (0,0) reference using the same formula as above.

4. Gesture Detail – Auto‑Snap to Edge

After a pinch‑zoom or drag ends, the image is automatically moved to the nearest screen edge if it exceeds the boundary, using the same boundary‑checking logic.

5. Gesture Detail – Inertia

When the user releases a dragged image, an inertial slide continues for a short distance. The extension point (x3, y3) is calculated from the start point (x1, y1), end point (x2, y2) and a slide length l:

x3 = x2 + (x2 - x1) / l * l

6. Gesture Detail – Bounce Back

Scale is clamped between a minimum and maximum. If the user exceeds the limit, the image is allowed to stretch a little (max + n) and then bounces back to the limit on

touchend

.

Conclusion

The project deepens understanding of web gestures and CSS3 animations, demonstrating how to achieve a native‑like image preview experience with AlloyFinger, transform.js, and to.js.