QR Code

在终端中将文本或 URL 显示为可扫描的标准二维码。QRCodeRenderable 使用半块单元格渲染 QR Code Model 2 模块，使符号在终端字符几何中保持正方形。

需要单独安装二维码包：

bun install @opentui/qrcode

基本用法

Renderable API

import { createCliRenderer } from "@opentui/core"
import { QRCodeRenderable } from "@opentui/qrcode"

const renderer = await createCliRenderer()

const qr = new QRCodeRenderable(renderer, {
  id: "docs-link",
  content: "https://opentui.com/docs/getting-started",
  quietZone: 4,
  scale: 2,
})

renderer.root.add(qr)

React JSX

import { createRoot } from "@opentui/react"
import { registerQRCode } from "@opentui/qrcode/react"

registerQRCode()

createRoot(renderer).render(
  <qr-code
    content="https://opentui.com/docs/getting-started"
    quietZone={4}
    scale={2}
    foregroundColor="#111827"
    backgroundColor="#ffffff"
  />,
)

Solid JSX

import { render } from "@opentui/solid"
import { registerQRCode } from "@opentui/qrcode/solid"

registerQRCode()

render(() => (
  <qr_code
    content="https://opentui.com/docs/getting-started"
    quietZone={4}
    scale={2}
    foregroundColor="#111827"
    backgroundColor="#ffffff"
  />
))

尺寸调整

QRCodeRenderable 根据编码的 QR 版本、静区和请求的缩放比例自动计算自身尺寸。默认的 fit: "contain" 允许二维码缩小以适应受限制的父容器，同时保持有效的正方形模块网格。

const qr = new QRCodeRenderable(renderer, {
  content: "opentui.com",
  quietZone: 4,
  scale: 2,
  fit: "contain",
})

当你希望使用配置的缩放比例作为唯一渲染尺寸时，请使用 fit: "none"。

标准 QR Code 的 quietZone 至少需要 4 个模块。OpenTUI 会验证矩阵和静区几何，但扫描器的可靠性仍取决于终端字体、单元格宽高比、显示对比度和相机条件。

回退内容

当容器过小，无法渲染哪怕缩放比例为 1 的二维码时，显示回退文本而非空白区域：

const qr = new QRCodeRenderable(renderer, {
  content: "https://opentui.com/docs/getting-started",
  fallbackContent: "Resize for QR",
  fallbackColor: "#94a3b8",
})

纠错级别

通过二维码包的纠错枚举设置 errorCorrectionLevel：

import { ErrorCorrectionLevel, QRCodeRenderable } from "@opentui/qrcode"

const qr = new QRCodeRenderable(renderer, {
  content: "opentui.com",
  errorCorrectionLevel: ErrorCorrectionLevel.H,
})

更高的纠错级别可提升容错能力，但对于较长的内容可能会增加 QR 版本和渲染尺寸。

属性