omni-crop

v1.0.1

Published

5 days ago

High performance cross-platform image cropper for WeChat Miniprogram, Taro, uni-app, React Native and Web

0High
0Medium
0Low

agions

cropper image-cropper miniprogram wechat taro uni-app react-native wxs canvas-2d pinch-zoom

omni-crop

📖 目录

🌟 为什么选择 OmniCrop？

在小程序和移动端开发中，传统的图片裁剪方案通常存在三大痛点：

跨线程通信卡顿：逻辑层 JS 与渲染层 WebView 频繁传递 touch 事件与坐标，在千元机或长列表场景下 this.setData() 导致严重丢帧（仅 20~30 FPS），手势拖拽迟滞。
Canvas 导出黑屏与内存溢出 (OOM)：依赖已废弃的旧版 Canvas API，在 iOS 与高端 Android 上加载高像素相机原图（4K/8K）时极易造成 WebView 进程被系统直接杀掉（闪退）。
多端分包割裂繁琐：不同框架平台各自一套轮子，API 无法复用，工程维护成本极高。

OmniCrop 为解决这些痛点而生：

🏗️ 系统架构总览

OmniCrop 采用高度解耦的分层状态机与驱动架构：

┌────────────────────────────────────────────────────────────────────────┐
│                        应用层 (Platform Adapters)                      │
│  omni-crop/weixin   omni-crop/taro   omni-crop/uni-app   omni-crop/rn  │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
┌──────────────────────────────────▼─────────────────────────────────────┐
│                    状态机与手势控制层 (Core Controller)                │
│  · 双模裁剪逻辑 (固定框/自由框)       · 双指捏合缩放算法 (Pinch Engine)   │
│  · 边界防露白判定 (Boundary Restrict) · 弹性阻尼回弹动效 (Elastic Damping)│
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
┌──────────────────────────────────▼─────────────────────────────────────┐
│                      图像渲染与导出流水线 (Exporter)                    │
│  · 跨端 Canvas 2D 驱动 (Wechat / Web)  · EXIF Orientation 自动矫正     │
│  · 高 DPR 物理清晰度超采样            · 保比例智能降采样 (防 OOM 闪退) │
└────────────────────────────────────────────────────────────────────────┘

📦 安装与 Subpath 导出规范

只需统一安装 omni-crop 单包：

npm install omni-crop
# 或
pnpm add omni-crop

通过标准的 Package Subpath 语法，在不同的业务场景中按需引入：

🚀 各端开箱即用实战

1. 微信原生小程序 (WeChat Miniprogram)

💡 源码仓库内置了完整运行的演示项目：examples/miniprogram-demo，可直接在微信开发者工具中一键打开体验！

(1) 安装与构建 npm

npm install omni-crop

在微信开发者工具菜单栏点击：【工具】 -> 【构建 npm】。

(2) 在页面配置中引入组件 (`index.json`)

{
  "navigationBarTitleText": "图片裁剪",
  "usingComponents": {
    "omni-crop": "omni-crop/weixin"
  }
}

(3) 页面结构与缩放滑块设计 (`index.wxml`)

<view class="cropper-page">
  <!-- 裁剪主体组件 -->
  <view class="cropper-stage">
    <omni-crop
      id="omniCropper"
      image="{{imageSrc}}"
      aspect="{{aspect}}"
      cropShape="{{cropShape}}"
      showGrid="{{true}}"
      restrictPosition="{{true}}"
      bindcropcomplete="onCropComplete"
      bindzoomchange="onZoomChange"
    />
  </view>

  <!-- 缩放控制微调滑杆 (对齐专业图像软件设计) -->
  <view class="zoom-slider-bar">
    <text class="slider-btn" bindtap="handleZoomOut">–</text>
    <slider
      min="1"
      max="3"
      step="0.01"
      value="{{zoom}}"
      activeColor="#07c160"
      backgroundColor="#333333"
      block-size="18"
      bindchanging="onSliderChanging"
      bindchange="onSliderChange"
    />
    <text class="slider-btn" bindtap="handleZoomIn">+</text>
    <view class="reset-btn" bindtap="handleReset">⟳ 重置</view>
  </view>

  <!-- 底部操作按钮 -->
  <view class="action-footer">
    <button bindtap="handleRotate">🔄 旋转90°</button>
    <button bindtap="handleFlip">↔️ 翻转</button>
    <button type="primary" bindtap="handleExport">确定裁剪</button>
  </view>
</view>

(4) 页面样式参考 (`index.wxss`)

page {
  background-color: #000;
  color: #fff;
  height: 100vh;
}
.cropper-page {
  display: flex;
  flex-direction: column;
  height: 100vh;
}
.cropper-stage {
  flex: 1;
  position: relative;
}
.zoom-slider-bar {
  display: flex;
  align-items: center;
  padding: 12px 20px;
  background: rgba(20, 20, 20, 0.9);
}
.zoom-slider-bar slider {
  flex: 1;
  margin: 0 12px;
}
.slider-btn {
  font-size: 20px;
  color: #fff;
  width: 30px;
  text-align: center;
}
.reset-btn {
  font-size: 13px;
  color: #07c160;
  padding: 4px 8px;
}
.action-footer {
  display: flex;
  justify-content: space-around;
  padding: 16px;
  background: #111;
}

(5) 页面交互与导出控制 (`index.js`)

Page({
  data: {
    imageSrc: 'https://cdn.example.com/sample.jpg',
    aspect: 4 / 3,
    cropShape: 'rect',
    zoom: 1,
  },

  onReady() {
    this.cropper = this.selectComponent('#omniCropper');
  },

  onCropComplete(e) {
    const { croppedAreaPixels, croppedAreaPercentages } = e.detail;
    console.log('裁剪像素坐标:', croppedAreaPixels);
  },

  onZoomChange(e) {
    // 监听双指缩放触发的数值更新，同步回滑块 UI
    this.setData({ zoom: e.detail.zoom });
  },

  onSliderChanging(e) {
    this.cropper.setZoom(e.detail.value);
  },

  onSliderChange(e) {
    this.cropper.setZoom(e.detail.value);
  },

  handleZoomIn() {
    this.cropper.zoomIn(0.2);
  },

  handleZoomOut() {
    this.cropper.zoomOut(0.2);
  },

  handleRotate() {
    this.cropper.rotate(90);
  },

  handleFlip() {
    this.cropper.flipHorizontal();
  },

  handleReset() {
    this.cropper.reset();
  },

  async handleExport() {
    wx.showLoading({ title: '正在高清导出...' });
    try {
      const res = await this.cropper.exportCroppedImage({
        format: 'jpg',
        quality: 0.9,
        dpr: 2, // 启用 2 倍物理超采样，彻底告别锯齿与模糊
      });
      wx.hideLoading();

      // 预览或保存到本地相册
      wx.previewImage({ urls: [res.uri] });
    } catch (err) {
      wx.hideLoading();
      wx.showToast({ title: '导出失败', icon: 'none' });
    }
  }
});

2. Taro 3 (React / Vue)

import React, { useRef, useState } from 'react';
import { View, Button } from '@tarojs/components';
import { OmniCrop, OmniCropRef } from 'omni-crop/taro';
import Taro from '@tarojs/taro';

export default function TaroCropPage() {
  const cropperRef = useRef<OmniCropRef>(null);
  const [imgUrl] = useState('https://cdn.example.com/sample.jpg');

  const onConfirm = async () => {
    Taro.showLoading({ title: '导出中' });
    const result = await cropperRef.current?.exportCroppedImage({
      format: 'png',
      dpr: 2,
    });
    Taro.hideLoading();
    console.log('导出图片临时地址:', result?.uri);
  };

  return (
    <View style={{ width: '100vw', height: '100vh', background: '#000' }}>
      <OmniCrop
        ref={cropperRef}
        image={imgUrl}
        aspect={1}
        cropShape="round"
        showGrid={true}
      />
      <View style={{ position: 'absolute', bottom: 30, width: '100%', display: 'flex', justifyContent: 'space-around' }}>
        <Button onClick={() => cropperRef.current?.rotate(90)}>旋转</Button>
        <Button onClick={() => cropperRef.current?.reset()}>重置</Button>
        <Button type="primary" onClick={onConfirm}>确认裁剪</Button>
      </View>
    </View>
  );
}

3. uni-app (Vue 3 `<script setup>`)

<template>
  <view class="uni-crop-container">
    <OmniCrop
      ref="cropRef"
      :image="imageUrl"
      :aspect="16 / 9"
      @cropComplete="onCropComplete"
    />

    <view class="toolbar">
      <button @click="cropRef?.rotate(90)">顺时针90°</button>
      <button @click="cropRef?.flipHorizontal()">水平翻转</button>
      <button type="primary" @click="handleExport">确定导出</button>
    </view>
  </view>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import { OmniCrop } from 'omni-crop/uni-app';

const cropRef = ref<InstanceType<typeof OmniCrop>>();
const imageUrl = ref('https://cdn.example.com/sample.jpg');

const onCropComplete = (pixels: any, percent: any) => {
  console.log('像素数据:', pixels);
};

const handleExport = async () => {
  const res = await cropRef.value?.exportCroppedImage({
    format: 'jpg',
    quality: 0.9,
  });
  console.log('裁剪文件路径:', res?.uri);
};
</script>

<style scoped>
.uni-crop-container {
  width: 100vw;
  height: 100vh;
  background-color: #000;
}
.toolbar {
  position: absolute;
  bottom: 40rpx;
  width: 100%;
  display: flex;
  justify-content: space-around;
}
</style>

4. React Native

import React, { useRef } from 'react';
import { StyleSheet, View, Button } from 'react-native';
import { OmniCropRN, OmniCropRNRef } from 'omni-crop/react-native';

export default function App() {
  const cropRef = useRef<OmniCropRNRef>(null);

  return (
    <View style={styles.container}>
      <OmniCropRN
        ref={cropRef}
        image="https://cdn.example.com/demo.jpg"
        aspect={1}
        cropShape="rect"
      />
      <View style={styles.actions}>
        <Button title="旋转90°" onPress={() => cropRef.current?.rotate(90)} />
        <Button title="重置" onPress={() => cropRef.current?.reset()} />
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, backgroundColor: '#000' },
  actions: { flexDirection: 'row', justifyContent: 'space-around', paddingBottom: 40 },
});

5. Web (React)

import React, { useRef } from 'react';
import { OmniCrop, OmniCropWebRef } from 'omni-crop';

export function WebCropDemo() {
  const cropperRef = useRef<OmniCropWebRef>(null);

  return (
    <div style={{ width: '100vw', height: '100vh', position: 'relative' }}>
      <OmniCrop
        ref={cropperRef}
        image="https://cdn.example.com/sample.jpg"
        aspect={4 / 3}
        showGrid={true}
      />
    </div>
  );
}

🛠️ 完整 API 字典参考

组件属性 (Props)

组件事件 (Events)

| 事件名 | 返回参数 (e.detail) | 触发时机 | | :--- | :--- | :--- | | bindcropcomplete | { croppedAreaPixels, croppedAreaPercentages } | 手势离开、缩放结束或尺寸初始化完成时回调精准几何坐标 | | bindzoomchange | { zoom: number } | 双指缩放或滑块调整使得缩放比例产生变化时实时回传 | | bindcropchange | { x: number, y: number } | 图片在裁剪容器内的偏移量发生变化时触发 |

实例方法 (Imperative Ref Methods)

通过小程序 this.selectComponent('#id') 或 React/Vue ref 调用：

导出配置 (ExportOptions)

export interface ExportOptions {
  /** 输出格式：'jpg' | 'png' | 'webp'，默认 'jpg' */
  format?: 'jpg' | 'png' | 'webp';
  /** 压缩质量 (0.1 - 1.0)，默认 0.9 */
  quality?: number;
  /** 设备像素比 (DPR)，默认为当前屏幕 DPR，传入 2 或 3 可获得物理级超清无损图像 */
  dpr?: number;
  /** 最大分辨率限制，默认 4096，超出时自动执行保比例下采样防止 OOM 闪退 */
  maxResolution?: number;
}

export interface CropResult {
  /** 导出图片的本地临时路径 (小程序端可直接用于 previewImage 或 saveImageToPhotosAlbum) */
  uri: string;
  /** 导出的物理像素宽度 */
  width: number;
  /** 导出的物理像素高度 */
  height: number;
}

🤖 自动化发布与 GitHub Actions (CI/CD)

项目已集成标准的 GitHub Actions 工作流：

1. 自动发布到 npm (`.github/workflows/publish.yml`)

触发机制：推送以 v 开头的标签（如 git tag v1.0.0 && git push origin v1.0.0），或在 GitHub Releases 页面创建新 Release。
发布条件：
1. 在 GitHub 仓库设置中配置 NPM_TOKEN（路径：Settings -> Secrets and variables -> Actions -> Repository secrets）。
2. 工作流将自动执行依赖安装、9 项数学单元测试与构建打包，并通过 npm publish --access public 安全推送到 npm 官方源。

2. 自动化部署在线文档到 GitHub Pages (`.github/workflows/deploy-pages.yml`)

触发机制：向 main 分支推送 docs/** 目录变更时自动触发。
在线体验：静态页面将自动部署到你的专属 GitHub Pages 站点，供任何人在线体验 Live Studio 演练场与查阅文档。

💡 常见问题与排错指南 (FAQ)

解答：微信小程序 Canvas 2D 规范要求外链图片必须具备合法的下载凭证。omni-crop/exporter 内部已经封装了 wx.downloadFile 自动落盘拦截机制；使用时只需确保您的 CDN 图片域名已经配置在微信公众平台的小程序后台「合法 downloadFile 域名列表」中即可。

解答：iOS Safari / 微信内置 XWeb 引擎对单张 Canvas 内存占用有严格上限（通常为 1600万~3200万像素）。当相机原图极大时，直接绘制会瞬间触发系统 OOM 崩溃杀掉进程。omni-crop/exporter 默认启用了智能保比例降采样（maxResolution: 4096），在保证最高打印级清晰度的同时，彻底杜绝闪退。

解答：手机自带相机拍摄的照片经常包含 EXIF Orientation 旋转元数据。omni-crop/exporter 拥有零依赖的纯二进制 EXIF 解析算法，会在载入图片时自动识别方向标签并与当前变换矩阵相融合，无需开发者手动处理。

📄 开源协议 (License)

本项目基于 MIT 协议开源，欢迎自由商用与深度定制！如有问题或新功能建议，欢迎提交 Issues 或 Pull Requests。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

omni-crop

📖 目录

🌟 为什么选择 OmniCrop？

🏗️ 系统架构总览

📦 安装与 Subpath 导出规范

🚀 各端开箱即用实战

1. 微信原生小程序 (WeChat Miniprogram)

(1) 安装与构建 npm

(2) 在页面配置中引入组件 (index.json)

(3) 页面结构与缩放滑块设计 (index.wxml)

(4) 页面样式参考 (index.wxss)

(5) 页面交互与导出控制 (index.js)

2. Taro 3 (React / Vue)

3. uni-app (Vue 3 <script setup>)

4. React Native

5. Web (React)

🛠️ 完整 API 字典参考

组件属性 (Props)

组件事件 (Events)

实例方法 (Imperative Ref Methods)

导出配置 (ExportOptions)

🤖 自动化发布与 GitHub Actions (CI/CD)

1. 自动发布到 npm (.github/workflows/publish.yml)

2. 自动化部署在线文档到 GitHub Pages (.github/workflows/deploy-pages.yml)

💡 常见问题与排错指南 (FAQ)

📄 开源协议 (License)

(2) 在页面配置中引入组件 (`index.json`)

(3) 页面结构与缩放滑块设计 (`index.wxml`)

(4) 页面样式参考 (`index.wxss`)

(5) 页面交互与导出控制 (`index.js`)

3. uni-app (Vue 3 `<script setup>`)

1. 自动发布到 npm (`.github/workflows/publish.yml`)

2. 自动化部署在线文档到 GitHub Pages (`.github/workflows/deploy-pages.yml`)