https://github.com/lizychy0329/we-cropper
A simple WeChat-style image cropper, implemented with vue-advanced-cropper.
https://github.com/lizychy0329/we-cropper
cropper tailwindcss typescript vue vue3 wechat
Last synced: about 1 month ago
JSON representation
A simple WeChat-style image cropper, implemented with vue-advanced-cropper.
- Host: GitHub
- URL: https://github.com/lizychy0329/we-cropper
- Owner: lizyChy0329
- License: mit
- Created: 2024-08-05T09:15:44.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-29T02:05:49.000Z (over 1 year ago)
- Last Synced: 2025-01-30T18:39:29.823Z (over 1 year ago)
- Topics: cropper, tailwindcss, typescript, vue, vue3, wechat
- Language: Vue
- Homepage: https://lizychy0329.github.io/we-cropper/
- Size: 2.14 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
we-cropper
A simple and powerful WeChat-style image cropper with Vue 3
## Features
- ✨ **Easy to Use**: Simple API with just one core `useCropper` hook
- 🦾 **Strongly Typed**: Full TypeScript support with comprehensive type definitions
- 🌍 **i18n Support**: Built-in internationalization with 9 languages and custom locale support
- 🚀 **Fixed Cropping Box**: Consistent cropping area with configurable aspect ratio
- 🎯 **Auto Zoom**: Automatically zooms in on the crop area for precise editing
- ⭕ **Multiple Shapes**: Support for both rectangle and circle cropping modes
- ❄️ **ESM / UMD Support**: Works seamlessly in both modern and legacy environments
## Requirements
```json
{
"peerDependencies": {
"vue": "^3.0.0"
}
}
```
## Installation
```bash
pnpm add @lizychy0329/we-cropper
```
## Quick Start
```typescript
import { fileToBase64, useCropper } from '@lizychy0329/we-cropper'
// Initialize cropper with basic configuration
const { showCropper, onCrop } = useCropper({
el: '#cropper-container', // defaults to document.body
aspectRatio: 1 / 1,
locale: 'en' // built-in English support
})
// Handle file selection with @vueuse/useFileDialog
const { onChange } = useFileDialog({
multiple: false,
accept: 'image/*'
})
const croppedImage = ref('')
onChange(async (files) => {
const base64String = await fileToBase64(files[0])
showCropper(base64String)
})
// Handle cropped result
onCrop((base64String) => {
croppedImage.value = base64String
// Upload to your server or further processing
})
```
### Circle Cropping Example
```typescript
import { fileToBase64, useCropper } from '@lizychy0329/we-cropper'
// Initialize cropper with circle shape for avatar cropping
const { showCropper, onCrop } = useCropper({
shape: 'circle', // Use circle cropping mode
aspectRatio: 1 / 1, // Perfect square ratio for circle
locale: 'en'
})
// Usage remains the same
const { onChange } = useFileDialog({
multiple: false,
accept: 'image/*'
})
const avatarImage = ref('')
onChange(async (files) => {
const base64String = await fileToBase64(files[0])
showCropper(base64String, {
shape: 'circle', // Or Use circle cropping mode in showCropper Dynamic
})
})
onCrop((base64String) => {
avatarImage.value = base64String
// Perfect circular avatar ready for upload
})
```
## Internationalization (i18n)
### Built-in Languages
we-cropper supports 9 languages out of the box:
| Code | Language | File |
|------|----------|------|
| `en` | English | en.ts |
| `zh-CN` | Chinese (Simplified) | zh-CN.ts |
| `zh-TW` | Chinese (Traditional) | zh-TW.ts |
| `ja` | Japanese | ja.ts |
| `ko` | Korean | ko.ts |
| `fr` | French | fr.ts |
| `de` | German | de.ts |
| `es` | Spanish | es.ts |
| `ru` | Russian | ru.ts |
### Basic Usage
```typescript
import { useCropper } from '@lizychy0329/we-cropper'
// Use built-in language
const { showCropper } = useCropper({
locale: 'zh-CN' // Chinese interface
})
showCropper('data:image/png;base64,...')
```
### Dynamic Language Switching
```typescript
import { useCropper } from '@lizychy0329/we-cropper'
const { showCropper, setLocale, currentLocale } = useCropper({
locale: 'en'
})
// Switch language dynamically
function switchToChinese(): void {
setLocale('zh-CN')
console.log(currentLocale.value) // 'zh-CN'
}
// Show cropper with current language
showCropper('data:image/png;base64,...')
```
### Custom Localization
```typescript
import { useCropper } from '@lizychy0329/we-cropper'
const customLocale = {
en: {
loading: 'Processing image...',
reset: 'Reset Image',
confirm: 'Confirm Crop',
cancel: 'Cancel Operation',
rotate: 'Rotate Image',
error: {
loadImage: 'Failed to load image',
cropImage: 'Failed to crop image'
},
tooltip: {
rotate: 'Click to rotate image',
reset: 'Reset to original state'
}
}
}
const { showCropper } = useCropper({
locale: 'en',
customLocale
})
```
## API Reference
### useCropper
```typescript
function useCropper(options?: UseCropperOptions): {
onCrop: EventHookOn // Crop completion event
showCropper: (src: string) => void // Display cropper
setLocale: (locale: LocaleCode) => void // Set language
currentLocale: ComputedRef // Current language
}
```
### UseCropperOptions
```typescript
interface UseCropperOptions {
locale?: LocaleCode // Language setting
customLocale?: CustomLocale // Custom language pack
aspectRatio?: number // Crop ratio (default: 1)
shape?: 'rectangle' | 'circle' // Crop shape (default: 'rectangle')
el?: HTMLElement | string // Mount element (default: document.body)
// Legacy text props (deprecated but still supported)
loadingText?: string
resetText?: string
confirmText?: string
cancelText?: string
}
```
## Utility Functions
```typescript
// Convert base64 to Blob
export function base64ToBlob(base64String: string): Promise
// Convert File to base64
export function fileToBase64(file: File): Promise
// Convert URL to base64
export function urlToBase64(url: string, mineType?: string): Promise
```
## Screenshot
## Development
```bash
# Start development server
pnpm dev
# Build library
pnpm build:lib
# Build documentation
pnpm build:docs
```
## License
MIT