qrcode

Documentation

Overview

Package qrcode 提供纯 Go（无 cgo）实现的二维码（QR Code）处理能力：

• 识别（decode）：从 png / jpeg 图片中解析二维码内容，输入支持 文件路径、[]byte、io.Reader 与 image.Image 四种形态，并提供 Decode（单码）与 DecodeAll（多码）两组入口；
• 终端输出（terminal）：把字符串渲染成可扫描的终端二维码；
• 生成（encode）：把字符串生成 png / jpeg 图片字节流或 image.Image。

内部基于 gozxing（识别）、skip2/go-qrcode（生成）与 mdp/qrterminal（终端） 三个开源库封装，公开 API 不泄露底层库类型。

Index

• Constants
• Variables
• func DecodeAllBytes(data []byte) ([]string, error)
• func DecodeAllFile(path string) ([]string, error)
• func DecodeAllImage(img image.Image) ([]string, error)
• func DecodeAllReader(r io.Reader) ([]string, error)
• func DecodeBytes(data []byte) (string, error)
• func DecodeFile(path string) (string, error)
• func DecodeImage(img image.Image) (string, error)
• func DecodeReader(r io.Reader) (string, error)
• func EncodeImage(content string, opts ...EncodeOptions) (image.Image, error)
• func EncodeJPEG(content string, opts ...EncodeOptions) ([]byte, error)
• func EncodePNG(content string, opts ...EncodeOptions) ([]byte, error)
• func EncodeToTerminal(content string, w io.Writer, opts ...TerminalOptions) error
• type EncodeOptions
• type RecoveryLevel
  • func ParseRecoveryLevel(s string) (RecoveryLevel, error)
  • func (l RecoveryLevel) String() string
  • func (l RecoveryLevel) Valid() bool
• type TerminalOptions

Constants

const (
	// DefaultSize 是生成图片的默认像素边长。
	DefaultSize = 256
	// DefaultQuality 是生成 jpeg 的默认质量（1-100）。
	DefaultQuality = 90
	// DefaultQuietZone 是终端输出默认的静区（quiet zone）模块数。
	DefaultQuietZone = 4
)

默认选项取值。

Variables

var (
	// ErrNotFound 表示图片中未识别到任何二维码。
	ErrNotFound = errors.New("qrcode: no qr code found")

	// ErrDecodeFailed 表示图片中存在疑似二维码但解码失败（如损坏至不可纠）。
	ErrDecodeFailed = errors.New("qrcode: failed to decode qr code")

	// ErrUnsupportedFormat 表示输入字节流不是 png/jpeg 图片或无法解码。
	ErrUnsupportedFormat = errors.New("qrcode: unsupported image format (only png/jpeg)")

	// ErrInvalidContent 表示内容为空或超出二维码容量。
	ErrInvalidContent = errors.New("qrcode: invalid content (empty or too long)")

	// ErrInvalidOption 表示配置选项非法。
	ErrInvalidOption = errors.New("qrcode: invalid option")

	// ErrTooNarrow 表示终端列宽不足以完整显示二维码。
	ErrTooNarrow = errors.New("qrcode: output width exceeds MaxColumns")
)

本包暴露的错误哨兵值（sentinel），可用 errors.Is / errors.As 断言。

Functions

func DecodeAllBytes

func DecodeAllBytes(data []byte) ([]string, error)

DecodeAllBytes 从 png/jpeg 字节流解码全部二维码内容。

func DecodeAllFile

func DecodeAllFile(path string) ([]string, error)

DecodeAllFile 从图片文件解码全部二维码内容，按解码器探测顺序返回 payload 列表。 图片中没有任何二维码时返回 ErrNotFound。

func DecodeAllImage

func DecodeAllImage(img image.Image) ([]string, error)

DecodeAllImage 从 image.Image 解码全部二维码内容。

func DecodeAllReader

func DecodeAllReader(r io.Reader) ([]string, error)

DecodeAllReader 从 io.Reader 读取图片并解码全部二维码内容。

func DecodeBytes

func DecodeBytes(data []byte) (string, error)

DecodeBytes 从 png/jpeg 字节流解码二维码内容，返回第一个识别到的 payload。

func DecodeFile

func DecodeFile(path string) (string, error)

DecodeFile 从图片文件解码二维码内容，返回第一个识别到的 payload。 文件不存在等打开错误原样透传（可用 errors.Is(err, os.ErrNotExist) 断言）。

func DecodeImage

func DecodeImage(img image.Image) (string, error)

DecodeImage 从 image.Image 解码二维码内容，返回第一个识别到的 payload。 该入口跳过格式探测，直接送解码器。

func DecodeReader

func DecodeReader(r io.Reader) (string, error)

DecodeReader 从 io.Reader 读取图片并解码二维码内容，返回第一个识别到的 payload。

func EncodeImage

func EncodeImage(content string, opts ...EncodeOptions) (image.Image, error)

EncodeImage 生成包含 content 的二维码 image.Image，宽高等于 Size 像素 （当 Size 小于码图实际所需大小时，由底层库自动放大到码图尺寸）。

func EncodeJPEG

func EncodeJPEG(content string, opts ...EncodeOptions) ([]byte, error)

EncodeJPEG 生成包含 content 的二维码 jpeg 字节流，质量默认 DefaultQuality。

func EncodePNG

func EncodePNG(content string, opts ...EncodeOptions) ([]byte, error)

EncodePNG 生成包含 content 的二维码 png 字节流。

func EncodeToTerminal

func EncodeToTerminal(content string, w io.Writer, opts ...TerminalOptions) error

EncodeToTerminal 把 content 渲染为终端二维码并写入 w。

输出字符集：

• half-block（默认）："▀ ▄ █"（每个字符 1 列）；
• 全块：ANSI 背景色块（每个模块 2 列）。

当 MaxColumns 大于 0 且输出宽度超出该值时，返回 ErrTooNarrow， 且不会向 w 写入任何内容。

Types

type EncodeOptions

type EncodeOptions struct {
	// Level 纠错级别，默认 LevelM。
	Level RecoveryLevel
	// Size 输出图片的像素边长（宽高相等），默认 DefaultSize。
	Size int
	// Quality jpeg 输出质量（1-100），仅 EncodeJPEG 生效，默认 DefaultQuality。
	Quality int
}

EncodeOptions 是生成图片的配置项；零值字段回退到默认值 （Level=LevelM、Size=DefaultSize、Quality=DefaultQuality）。

type RecoveryLevel

type RecoveryLevel int

RecoveryLevel 表示二维码的纠错级别：LevelL < LevelM < LevelQ < LevelH。 纠错能力越强，可容纳的数据越少。

const (
	// LevelL 约可恢复 7% 的数据损坏。
	LevelL RecoveryLevel = iota + 1
	// LevelM 约可恢复 15% 的数据损坏，为默认级别。
	LevelM
	// LevelQ 约可恢复 25% 的数据损坏。
	LevelQ
	// LevelH 约可恢复 30% 的数据损坏。
	LevelH
)

func ParseRecoveryLevel

func ParseRecoveryLevel(s string) (RecoveryLevel, error)

ParseRecoveryLevel 解析纠错级别字符串，接受 L / M / Q / H（不区分大小写）。

func (RecoveryLevel) String

func (l RecoveryLevel) String() string

String 返回级别的单字母表示：L / M / Q / H。

func (RecoveryLevel) Valid

func (l RecoveryLevel) Valid() bool

Valid 报告级别是否为合法取值之一。

type TerminalOptions

type TerminalOptions struct {
	// Level 纠错级别，默认 LevelM。
	Level RecoveryLevel
	// HalfBlock 是否使用半块（half-block）字符渲染，默认 true；
	// false 时使用全块字符。nil 表示使用默认值。
	HalfBlock *bool
	// QuietZone 静区（quiet zone）宽度（模块数），默认 DefaultQuietZone。
	QuietZone int
	// MaxColumns 允许输出的最大终端列宽；大于 0 时若码图宽度超出
	// 该值则返回 ErrTooNarrow（不输出截断内容）。小于等于 0 表示不限制。
	MaxColumns int
}

TerminalOptions 是终端输出的配置项。