React Native无损图片裁剪：缩放平移边界限制问题排查

问题描述 #

在React Native应用中实现保持宽高比的无损图片裁剪，通过缩放平移手势让用户调整图片，再保存参数。目前缩放平移功能正常，但无法正确限制平移范围，图片仍能移出边界。尝试过两种计算方式均无效：

1. 初始计算：

const maximumXOffset = ((scale.value - 1) / 2) * originalWidth
const maximumYOffset = ((scale.value - 1) / 2) * originalHeight

2. 后续尝试：存储原始尺寸和缩放后尺寸，用两者差值的一半作为偏移限制，依然无效。

完整组件代码如下：

// imports elided

function SingleCard({
    uri,
    dateString,
    id,
    canZoom,
}) {
    const dispatch = useDispatch()
   
    const selectTransformsForId = useMemo(makeSelectTransformsForId, [])
    const transformsForId = useSelector((state) =>
        selectTransformsForId(state, id)
    )

    const updateRedux = useCallback(
        (transforms) => {
            dispatch(updateTransforms({ id, transforms }))
        },
        [dispatch, id]
    )

    const zoom = useSharedValue(transformsForId.scale)
    const zoomStart = useSharedValue(zoom.value)
    const offset = useSharedValue({
        x: transformsForId.translateX,
        y: transformsForId.translateY,
    })
    const offsetStart = useSharedValue({ x: offset.value.x, y: offset.value.y })
    const originalSize = useSharedValue({ height: 0, width: 0 })
    const currentSize = useSharedValue({ height: 0, width: 0 })

    const zoomStyle = useAnimatedStyle(() => ({
        transform: [
            { scale: zoom.value },
            { translateX: offset.value.x },
            { translateY: offset.value.y },
        ],
    }))

    const containerRef = useAnimatedRef()
    const imageRef = useAnimatedRef()

    const zoomGesture = Gesture.Pinch()
        .onStart(() => {
            zoomStart.value = zoom.value
            const measurement = measure(containerRef)
            originalSize.value = {
                height: measurement.height,
                width: measurement.width,
            }
        })
        .onUpdate((e) => {
            zoom.value = Math.max(zoomStart.value * e.scale, 1)

            const imageMeasurement = measure(imageRef)
            currentSize.value = {
                height: imageMeasurement.height,
                width: imageMeasurement.width,
            }
        })
        .onEnd(() => {
            runOnJS(updateRedux)({ scale: zoom.value })
        })
        .enabled(canZoom)
        .shouldCancelWhenOutside(false)

    const dragGesture = Gesture.Pan()
        .averageTouches(true)
        .onStart(() => {
            offsetStart.value = offset.value
        })
        .onUpdate((e) => {
            const maximumXOffset =
                (currentSize.value.width - originalSize.value.width) / 2
            const maximumYOffset =
                (currentSize.value.height - originalSize.value.height) / 2

            const xOffset = Math.min(
                Math.max(e.translationX + offsetStart.value.x, -maximumXOffset),
                maximumXOffset
            )
            const yOffset = Math.min(
                Math.max(e.translationY + offsetStart.value.y, -maximumYOffset),
                maximumYOffset
            )
            offset.value = {
                x: xOffset,
                y: yOffset,
            }
        })
        .onEnd(() => {
            runOnJS(updateRedux)({
                translateX: offset.value.x,
                translateY: offset.value.y,
            })
        })
        .minPointers(2)
        .shouldCancelWhenOutside(false)
        .enabled(canZoom)

    const composed = Gesture.Simultaneous(dragGesture, zoomGesture)

    return (
        <View ref={containerRef}>
            <GestureDetector gesture={composed}>
                <AnimatedImage
                    style={[styles.image, zoomStyle]}
                    source={{ uri }}
                    ref={imageRef}
                />        
            </GestureDetector>
        </View>
    )
}

const styles = StyleSheet.create({
    image: {
        width: '100%',
        aspectRatio: 3 / 4,
        position: 'relative',
    }
})

export default memo(SingleCard)

问题根源与修复方案 #

1. Transform 顺序错误 #

当前transform先执行scale再执行translate，这会导致translate的数值被缩放倍数放大。比如scale=2时，translateX=10会实际位移20，完全打乱了边界限制计算。

修复：调换transform顺序，先translate再scale，这样位移数值不会被缩放影响：

const zoomStyle = useAnimatedStyle(() => ({
    transform: [
        { translateX: offset.value.x },
        { translateY: offset.value.y },
        { scale: zoom.value },
    ],
}))

2. 尺寸测量逻辑错误 #

• 你在捏合手势开始时才测量容器尺寸作为originalSize，但此时图片可能未完全加载，或容器尺寸不是最终显示尺寸。
• 通过measure(imageRef)获取缩放后尺寸不可靠，因为measure返回的是经过transform后的布局尺寸，和实际缩放逻辑不匹配。

修复：

• 用图片的onLoad事件获取真实原始尺寸：

// 新增状态存储图片真实原始尺寸
const [imageNaturalSize, setImageNaturalSize] = useState({ width: 0, height: 0 });

// 在AnimatedImage中添加onLoad回调
<AnimatedImage
    style={[styles.image, zoomStyle]}
    source={{ uri }}
    ref={imageRef}
    onLoad={(e) => {
        setImageNaturalSize({
            width: e.nativeEvent.source.width,
            height: e.nativeEvent.source.height,
        });
    }}
/>

• 提前测量容器尺寸，监听屏幕旋转等尺寸变化：

const [containerSize, setContainerSize] = useState({ width: 0, height: 0 });

useLayoutEffect(() => {
    const measureContainer = () => {
        containerRef.current?.measure((x, y, width, height) => {
            setContainerSize({ width, height });
        });
    };
    measureContainer();
    // 监听屏幕尺寸变化，更新容器尺寸
    const subscription = Dimensions.addEventListener('change', measureContainer);
    return () => subscription?.remove();
}, []);

3. 平移边界计算逻辑错误 #

之前的计算没有考虑图片缩放后与容器的尺寸关系，正确的边界应该是：图片缩放后超出容器的部分的一半，这样平移时图片始终能覆盖容器。

修复：修改dragGesture的onUpdate逻辑：

const dragGesture = Gesture.Pan()
    .averageTouches(true)
    .onStart(() => {
        offsetStart.value = offset.value
    })
    .onUpdate((e) => {
        // 计算缩放后的图片尺寸
        const scaledWidth = imageNaturalSize.width * zoom.value;
        const scaledHeight = imageNaturalSize.height * zoom.value;

        // 计算可允许的最大偏移量：超出容器部分的一半，不能为负数（缩放不足1时不允许平移）
        const maxX = Math.max(0, (scaledWidth - containerSize.width) / 2);
        const maxY = Math.max(0, (scaledHeight - containerSize.height) / 2);

        // 限制偏移量在[-maxX, maxX]和[-maxY, maxY]之间
        const newX = Math.min(Math.max(e.translationX + offsetStart.value.x, -maxX), maxX);
        const newY = Math.min(Math.max(e.translationY + offsetStart.value.y, -maxY), maxY);

        offset.value = { x: newX, y: newY };
    })
    // 其他逻辑保持不变

4. 移除冗余代码 #

删除originalSize和currentSize这两个SharedValue，因为现在用imageNaturalSize和计算出来的scaledWidth/scaledHeight完全替代它们的功能。

最终效果 #

修复后，图片缩放时只能在容器范围内平移，不会移出边界；缩放倍数为1时无法平移，符合预期。

内容的提问来源于stack exchange，提问作者resistor