Languages: English | 中文

xue_hua_qr_code #

Out-of-the-box QR code widget for Flutter. Pure Dart — no native dependencies, no platform channels.

XueHuaQrCode(value: 'https://example.com')

That is all you need: a scannable black-on-white QR code that adapts to its parent constraints.

Features #

• One required parameter — pass value, get a standard QR code with sensible defaults
• Styling — square / circle / rounded modules, colors, gradients, proportional corner radius and gaps
• Center logo — ImageProvider based, sized as a fraction of the QR content side, identical in widget and export
• Automatic mask selection — the best of 8 mask patterns is chosen per ISO/IEC 18004 penalty rules
• Robust error handling — empty / oversized content falls back to errorBuilder on the widget; a failing logo (e.g. network error) degrades to a plain, still-scannable QR code
• Export — XueHuaQrCode.toImage() and XueHuaQrCode.toPngBytes() share the exact painter used on screen
• AI agent skills — official Agent Skills ship in the package for Cursor, Claude Code, and other agents

Installation #

dependencies:
  xue_hua_qr_code: ^2.0.2

Basic usage #

import 'package:xue_hua_qr_code/xue_hua_qr_code.dart';

// Adapts to the parent's shortest bounded side.
XueHuaQrCode(value: 'https://example.com')

// Fixed size.
XueHuaQrCode(value: 'https://example.com', size: 240)

Advanced usage #

Custom style #

XueHuaQrCode(
  value: 'https://example.com',
  size: 240,
  style: const QrStyle(
    shape: QrModuleShape.roundedSquare,
    moduleRadius: 0.4,          // fraction of a module, 0~0.5
    moduleGap: 0.15,            // fraction of a module, 0~0.5
    gradient: LinearGradient(colors: [Colors.pink, Colors.blue]),
    padding: EdgeInsets.all(12), // quiet zone
  ),
)

With a logo #

XueHuaQrCode(
  value: 'https://example.com',
  size: 240,
  style: const QrStyle(shape: QrModuleShape.roundedSquare),
  logo: const QrLogo(
    image: AssetImage('assets/logo.png'), // NetworkImage / MemoryImage also work
    scale: 0.22,      // fraction of the QR content side, (0, 0.35]
    padding: 6,
    borderRadius: 8,
  ),
  // Error correction is automatically raised to `high` when a logo is present.
)

If the logo fails to load (missing asset, network error), the widget renders the full QR code without the logo — it never leaves an unscannable hole.

Error handling #

XueHuaQrCode(
  value: userInput, // may be empty or too long
  errorBuilder: (context, error, stackTrace) => const Icon(Icons.error),
)

The widget catches encoding failures. toImage / toPngBytes rethrow them (ArgumentError for empty value, InsufficientInformationDensityException when the payload exceeds version 40).

Export #

// PNG bytes — save to a file or show with Image.memory.
// `size` defaults to 512; encoding failures throw (unlike the widget).
final bytes = await XueHuaQrCode.toPngBytes(
  'https://example.com',
  size: 512,
  style: const QrStyle(shape: QrModuleShape.circle),
);

// dart:ui Image. Dispose the image when you are done with it.
final image = await XueHuaQrCode.toImage('https://example.com', size: 512);

API reference #

XueHuaQrCode #

QrErrorLevel get effectiveErrorLevel — errorCorrectionLevel if set, otherwise high when logo != null and medium otherwise.

QrStyle #

When moduleRadius / moduleGap are null, effectiveModuleRadius / effectiveModuleGap resolve by shape: square → 0.0 / 0.0, circle → 0.5 / 0.1, roundedSquare → 0.3 / 0.1.

copyWith uses ?? and cannot clear gradient back to null; construct a new QrStyle to drop a gradient.

QrLogo #

QrErrorLevel #

low (~7%), medium (~15%), quartile (~25%), high (~30%) — the approximate share of data that can be recovered.

Public fields value (format-information BCH: L=1, M=0, Q=3, H=2) and maxTypeNum (encoder version-search bound) are for the encoder. Pass the enum names from app code.

Export #

Both use the same painter as the widget. Encoding failures throw; a failed logo load degrades to a full QR without a logo. size must be > 0. Dispose the ui.Image from toImage when finished. toPngBytes may throw StateError if PNG encoding fails.

QrMatrix #

Immutable encode result. Create with QrMatrix.encode(value, {errorLevel = QrErrorLevel.medium}).

Empty value throws ArgumentError. Over-capacity throws InsufficientInformationDensityException. Equality compares value and errorLevel only.

QrPainter #

CustomPainter shared by the widget and export.

const QrPainter({
  required QrMatrix matrix,
  QrStyle style = const QrStyle(),
  QrLogo? logo,
  ui.Image? logoImage,
})

paint / shouldRepaint follow CustomPainter. A logo is drawn only when both logo and logoImage are non-null; otherwise the full matrix is painted (no hole).

InsufficientInformationDensityException #

Thrown when the payload does not fit QR version 40 at the chosen error level. Optional message includes needed vs maximum bits. toString() is InsufficientInformationDensityException: ${message ?? ''}.

There is no public version override: QrMatrix.encode always selects the smallest fitting version.

AI agent skills #

This package ships Agent Skills that teach AI coding assistants the public API. After adding the dependency, install them with:

dart run skills@ get

That scans your dependencies and copies selected skills into your agent's skills directory (for example .agents/skills/ or .cursor/skills/). Re-run after upgrading the package.

Each skill includes a references/ file with every public constructor, field, getter, and method. Agents that load skills from another directory can copy the folders under skills/ in this repository.

Example app #

cd example
flutter run

Five tabs demonstrate basic, circle, rounded, gradient, and logo styles, plus PNG export.

License #

MIT — encoding internals ported from qrcode-kotlin.