QR-it — Vite 工具站模板

SHA-256: 67d591952a8a11b5f0c7e632dd738d764a9560be633730d59b6d4eace98029b2

2026-10-17T10:04:54.746Z

# QR-it 🎨
## Live Demo
[Open QR-it](https://qr-it.raztom.com/)

A free, no-signup QR code generator with custom designs, templates, logo support, scannability checks, and PNG/SVG exports. Built with React, Vite, and Tailwind CSS.

## ✨ Features

### Core Functionality
- **Universal QR Generation**: Generate QR codes for URLs, text, email, phone, SMS, WiFi networks, and vCards
- **Real-time Preview**: See changes instantly as you customize your design
- **Scan Validation**: Automatic quality assessment with warnings for potential scanning issues
- **Multiple Export Formats**: Download as PNG, SVG, or print-ready high-DPI images

### Design Customization
- **Full Color Picker**: Choose any color with hex input, not just presets
- **Gradient Colors**: Apply linear or radial gradients to dots, corners, and backgrounds
- **Metallic Presets**: Gold, Silver, Bronze, Rose Gold, Chrome, and Holographic finishes
- **Multiple Dot Styles**: Square, dots, rounded, extra-rounded, classy, and classy-rounded
- **Corner Styles**: Customize corner squares and corner dots independently
- **QR Shape**: Square (default) or Circle shape
- **Logo Integration**: Add your brand logo with automatic high error correction
- **Transparent Background**: Export QR codes without background for placement on any surface

### Scan Quality Features
- **Contrast Validation**: Real-time contrast checking between foreground and background
- **Low Contrast Warnings**: Visual warnings when colors may cause scanning issues
- **Margin Recommendations**: Guidance on quiet zone requirements
- **Logo Size Limits**: Automatic recommendations to keep logos scannable

### User Experience
- **Dark/Light Mode**: Toggle between themes with system preference detection
- **Pre-made Templates**: Quick-start templates for common use cases
- **Responsive Design**: Works on desktop and mobile devices

### Export Options
- **PNG**: Raster images with optional transparent background
- **SVG**: Scalable vectors with optional transparent background
- **Print-Ready**: High-resolution exports at 300 DPI

## 🚀 Quick Start

### Prerequisites
- Node.js 18+ 
- npm or yarn

### Installation

```bash
# Clone the repository
git clone https://github.com/talktome8/QR-it.git
cd QR-it

# Install dependencies
npm install

# Start development server
npm run dev
```

The app will be available at `http://localhost:3000`

### Build for Production

```bash
# Create production build
npm run build

# Preview production build
npm run preview
```

## 📁 Project Structure

```
qr-it/
├── public/
│   └── favicon.svg
├── src/
│   ├── assets/               # Static assets
│   ├── components/
│   │   ├── common/           # Reusable UI components
│   │   │   ├── Button.jsx
│   │   │   ├── Input.jsx
│   │   │   ├── Modal.jsx
│   │   │   ├── ColorPicker.jsx
│   │   │   ├── AdvancedColorPicker.jsx  # Gradient & metallic colors
│   │   │   ├── Select.jsx
│   │   │   ├── Slider.jsx
│   │   │   ├── Tabs.jsx
│   │   │   ├── Card.jsx
│   │   │   └── Toast.jsx
│   │   ├── layout/
│   │   │   ├── Layout.jsx
│   │   │   ├── Header.jsx
│   │   │   └── Footer.jsx
│   │   └── qr/
│   │       ├── QRPreview.jsx      # QR rendering & download
│   │       ├── QRInput.jsx        # Data input forms
│   │       └── QRCustomizer.jsx   # Style controls
│   ├── hooks/
│   │   ├── useQRContext.jsx       # QR state management
│   │   ├── useTheme.jsx           # Dark/light mode
│   │   └── useLocalStorage.js     # Persistent storage
│   ├── pages/
│   │   ├── HomePage.jsx
│   │   ├── GeneratorPage.jsx
│   │   ├── TemplatesPage.jsx
│   │   └── SavedPage.jsx
│   ├── services/
│   │   └── qrService.js           # QR generation service
│   ├── utils/
│   │   ├── helpers.js
│   │   └── validators.js
│   ├── styles/
│   │   └── index.css
│   ├── App.jsx
│   └── main.jsx
├── package.json
├── vite.config.js
├── tailwind.config.js
└── README.md
```

## 🎨 How to Use

### Creating a QR Code

1. **Enter Data**: Go to the Generator page and enter your URL or text
2. **Choose Style**: Use the tabs to customize:
   - **Presets**: Quick-start templates
   - **Colors**: Full color picker with gradients and metallic options
   - **Style**: Dot and corner styles, QR shape (square/circle)
   - **Logo**: Upload a center logo (auto-sets high error correction)
   - **Settings**: Error correction, size, and margins
3. **Download**: Click Download and choose PNG, SVG, or Print-Ready

### Transparent Background Export

1. Go to the **Colors** tab in the customizer
2. Check **"Transparent Background"**
3. The preview will show a checkerboard pattern indicating transparency
4. Download as PNG or SVG - the background will be transparent

### QR Shape Options

The app supports two QR shapes that are fully scannable:

| Shape | Description |
|-------|-------------|
| **Square** | Standard rectangular QR code (default) |
| **Circle** | Round QR code with circular boundary |

Both shapes maintain full scan reliability.

### Scan Quality Validation

The app automatically validates scan quality and shows warnings:

- **Excellent/Good**: ✅ No issues, QR will scan reliably
- **Fair**: ⚠️ May have issues - suggestions provided
- **Poor**: ❌ Likely to fail - immediate action needed

Common warnings:
- Low contrast between QR and background
- Small quiet zone (margin)
- Logo too large
- Missing high error correction with logo

### Color & Gradient System

**Solid Colors**: Use the color picker to choose any hex color

**Gradients**: Switch to gradient mode and configure:
- Gradient type (linear/radial)
- Rotation angle
- Multiple color stops

**Metallic Presets**: One-click metallic finishes:
- Gold, Silver, Bronze
- Rose Gold, Chrome, Holographic

## 🔧 Technical Details

### QR Code Generation

Uses [qr-code-styling](https://github.com/nicklasoverby/qr-code-styling) library which provides:
- Multiple dot and corner styles
- Gradient support
- Logo embedding
- Circle shape mask
- High-quality SVG and PNG export

### Error Correction Levels

| Level | Recovery | Best For |
|-------|----------|----------|
| L (Low) | 7% | Smallest QR, clean environments |
| M (Medium) | 15% | Balanced size and recovery |
| Q (Quartile) | 25% | Recommended default |
| H (High) | 30% | Required when using logos |

## 🛠️ Development

### Available Scripts

```bash
npm run dev      # Start development server
npm run build    # Build for production
npm run preview  # Preview production build
npm run lint     # Run ESLint
```

### Technologies Used

- **React 18**: UI framework
- **Vite 5**: Build tool
- **Tailwind CSS 3**: Styling
- **qr-code-styling**: QR generation
- **react-colorful**: Color picker
- **lucide-react**: Icons
- **react-router-dom**: Routing

## 📝 License

MIT License - feel free to use in your projects.

## 🙏 Acknowledgments

- [qr-code-styling](https://github.com/nicklasoverby/qr-code-styling) for the QR generation library
- [react-colorful](https://github.com/omgovich/react-colorful) for the color picker
- [Lucide](https://lucide.dev/) for the beautiful icons