Skip to content

About

Kuikly QR code & Code128 barcode views (classic DSL, pure Kotlin common) | 二维码/条形码组件

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

kuikly-code

Kuikly 二维码 / 条形码渲染组件 —— 纯 Kotlin common 实现,一套代码跨 Android / iOS / 鸿蒙 / Web。

基于经典 Kuikly DSL(com.tencent.kuikly.core)的 Canvas 绘制,内置 QR 编码引擎(qrcode-kotlin 血统,MIT)、 Code 128-B/C 编码器与 EAN-13 编码器(编码表均对照 zxing / ISO 标准逐条校验), 完全本地生成,无网络、无原生依赖。

功能特性

QRCodeView(二维码)

  • 纯 Canvas 绘制,四端渲染一致
  • 模块形状:方形 / 圆点 / 圆角方形 / 菱形
  • 前景支持纯色与线性渐变;定位图案可强制保持方形(保证扫码定位)
  • 中心 logo 叠加(白底圆角卡片,建议配合 HIGH 级纠错)
  • 掩码自动最优选择(ISO 18004 惩罚分规则评估 8 种掩码,可指定覆盖)
  • minVersion 版本下限(防止文本变短时二维码尺寸跳变)
  • 动态刷新(0.4.0+,付款码轮换):组件只管展示——textProvider 数据变化自动重绘, SUCCESS 态变化时双画布过渡动画(直接切换 / 交叉淡化 / 上下推移,响应式检测无轮询)
  • 四态展示(0.4.0+):stateProvider 传入 SUCCESS / LOADING / EMPTY / ERROR, 各态可注入自定义视图(loadingView / emptyView / errorView),取数/重试/轮换定时器由宿主业务自管
  • 四纠错级别(L/M/H/Q)与标准静区(默认 4 模块,可配)
  • onError 事件

BarcodeView(条形码)

  • Code 128:数字段自动切换 Code C(密度约翻倍,可关),校验和按 ISO 15417
  • EAN-13:12 位自动补校验位 / 13 位严格校验,零售商品码标配
  • 编码表对照 zxing(Code128Reader / UPCEANReader / EAN13Reader)逐条校验
  • 标准静区(默认 10 模块,可配)
  • 人眼可读文本行 Canvas 绘制(EAN-13 为经典三段式布局)
  • 非法输入触发 onError 事件并安全跳过绘制(不崩溃)

平台支持

平台 状态 接入方式
Android ✅ Maven 依赖(见下)
iOS ✅ 同一 Maven 坐标,宿主 shared 模块 gradle 引用后随 framework 编译
Web (JS) ✅ 同一 Maven 坐标(core 官方产物含 js 变体)
鸿蒙 ✅ 纯 common 代码零原生分支;宿主 KuiklyUI 工程以源码模块或 -ohos 变体接入(见下)

快速开始

宿主 shared 模块 build.gradle.kts:

repositories {
    mavenCentral()
    // Kuikly 官方产物仓库
    maven { url = uri("https://mirrors.tencent.com/repository/maven-tencent/") }
}

dependencies {
    implementation("io.github.zhanghaifei1997:kuiklyCode:0.4.0")
}

纯视图组件,无需注册任何原生模块,直接在页面中使用:

import com.kuikly.code.BarcodeFormat
import com.kuikly.code.BarcodeView
import com.kuikly.code.QRCodeShape
import com.kuikly.code.QRCodeView

// 二维码:圆点风格 + 渐变 + 中心 logo(建议 HIGH 纠错)
QRCodeView {
    attr {
        textProvider = { viewModel.payUrl }    // 响应式
        size = 248f
        shape = QRCodeShape.CIRCLE
        useGradient = true
        gradientStartColor = Color(0xFF0052D9)
        gradientEndColor = Color(0xFF7B61FF)
        errorCorrectionLevel = ErrorCorrectionLevel.HIGH
        logoPath = "logo.png"                  // 中心 logo(0.2.0+)
    }
    event {
        error { code, msg -> /* 兜底 UI */ }
    }
}

// 条形码:Code 128(数字段自动切 C,密度翻倍)+ 人眼可读文本
BarcodeView {
    attr {
        textProvider = { viewModel.payCode }
        barcodeWidth = 320f
        barcodeHeight = 90f
        showText = true
    }
}

// EAN-13 零售商品码(0.2.0+):12 位自动补校验位
BarcodeView {
    attr {
        textProvider = { "690102818029" }
        format = BarcodeFormat.EAN13
        barcodeWidth = 320f
        showText = true
    }
}

动态刷新与状态展示(0.4.0+,付款码轮换)

组件只负责展示:取数、重试、轮换定时器由宿主业务自管,通过响应式 Provider 传入「数据 + 状态」。

// ── ViewModel(业务侧,示意)──────────────────────────
// val state = observable(QRDisplayState.LOADING)   // 状态机
// val payCode = observable("")
// fun rotate() { state = LOADING; api.fetch { code -> payCode = code; state = SUCCESS } ... }
// fun start() { postDelayed(60_000) { rotate(); start() } }   // 轮换节奏业务自定

// ── 视图(组件侧)────────────────────────────────────
QRCodeView {
    attr {
        textProvider = { vm.payCode }
        stateProvider = { vm.state }                 // SUCCESS/LOADING/EMPTY/ERROR
        transition = QRTransition.CROSS_FADE         // SUCCESS 数据变化时的过渡动画
        // emptyView = { YourEmptyView() }            // 空态自定义(可选)
        // errorView = { YourRetryView() }            // 异常态自定义,重试按钮放这里(可选)
    }
    event {
        error { code, msg -> vm.onQrEncodeError() }
    }
}
  • 数据变化 → 自动重绘;配置过渡动画时旧码/新码双画布交叉(响应式检测,无轮询)
  • LOADING:默认旋转圆弧 loading(loadingView 可注入任意自定义效果)
  • EMPTY / ERROR:默认 Canvas 占位图形+文案,emptyView / errorView 可整体替换

API

QRCodeViewAttr

属性 类型 默认 说明
textProvider (() -> String)? null 编码文本(响应式)
size Float 248 宽=高
foregroundColor / bgColor Color 黑/白 前景/背景
errorCorrectionLevel ErrorCorrectionLevel MEDIUM L/M/H/VERY_HIGH
shape QRCodeShape SQUARE SQUARE / CIRCLE / ROUND_RECT / DIAMOND
roundRectRadiusRatio Float 0.3 圆角比例(仅 ROUND_RECT)
useGradient + gradientStart/EndColor Boolean/Color false 线性渐变前景
probeSquareStyle Boolean true 定位图案保持方形
quietZoneModules Int 4 静区模块数(ISO 建议 4)
minVersion Int 1 版本下限(防尺寸跳变,0.2.0+)
maskPattern MaskPattern? null 指定掩码;null=自动最优(0.2.0+)
logoPath / logoSize String? / Float null/0 中心 logo;size 0=自动 22%(0.2.0+)
logoPadding / logoCornerRadius / logoBgColor - 4/0/白 logo 白底卡片样式
stateProvider (() -> QRDisplayState)? null(=SUCCESS) 展示状态(SUCCESS/LOADING/EMPTY/ERROR,0.4.0+)
transition QRTransition CROSS_FADE 数据更新过渡:NONE/CROSS_FADE/SLIDE_VERTICAL(0.4.0+)
transitionDurationMs Int 350 过渡时长
loadingView / emptyView / errorView builder? null 各状态自定义视图(重试按钮等自行实现)
emptyText / errorText / placeholderColor - 暂无内容/加载失败/灰 默认占位样式

BarcodeViewAttr

属性 类型 默认 说明
textProvider (() -> String)? null 编码文本
format BarcodeFormat CODE128 CODE128 / EAN13(0.2.0+)
autoSubset Boolean true Code128 数字段自动切 C(0.2.0+)
barcodeWidth / barcodeHeight Float 650/120 条码区域尺寸(高度不含文本行)
foregroundColor / bgColor Color 黑/白 条/空颜色
quietZoneModules Int 10 静区模块数(ISO 建议 10)
showText Boolean false 显示人眼可读文本
textFontSize / textColor / textMarginTop - 24/灰/8 文本样式

编码 API(脱离 UI 直接取矩阵)

// QR:富元数据矩阵(含方块类型:定位/校正/定时/数据,可用于自定义渲染)
// maskPattern=null 自动最优掩码;minVersion 版本下限
val matrix = QRCodeEngine.encode("Hello", ErrorCorrectionLevel.HIGH, null, minVersion = 3)
val bools = QRCodeEngine.encodeToBooleanMatrix("Hello")

// Code 128-B(纯 B 子集)
val bars = Code128Encoder.encode("ABC123")
// Code 128 自动 B/C 混合(数字段密度翻倍,zxing 同款策略)
val dense = Code128Encoder.encodeAuto("ABC123456DEF")

// EAN-13:12 位补校验位 / 13 位校验
val ean = EAN13Encoder.encode("690102818029")     // → 6901028180297
val check = EAN13Encoder.calcCheckDigit("690102818029")  // → 7
val ok = EAN13Encoder.isValid("6901028180297")    // → true

鸿蒙接入

组件为纯 Kotlin common 代码(零平台分支),两种方式:

  1. 源码模块(推荐):把 kuiklyCode 模块加入宿主 KuiklyUI 工程的鸿蒙构建 (settings.ohos.gradle.kts include + 模块内 build.ohos.gradle.kts 已就位);
  2. -ohos 变体:在配置了 KuiklyBase ohos toolchain 的工程中执行 ./gradlew -c settings.ohos.gradle.kts :kuiklyCode:publishToMavenLocal,宿主从 mavenLocal 引用。

组件代码已在鸿蒙 Next 生产应用(五端电商 App)中随业务页运行验证。

与 QRose 的差异

官方市场另有 QRose(alexzhirkevich/qrose 的 Kuikly Compose DSL 适配版)。 本组件面向经典 Kuikly DSL(com.tencent.kuikly.core)工程:

  • 不依赖 Compose 模块,classic DSL 工程零额外引入
  • 引擎内联(qrcode-kotlin 移植 + 方块元数据扩展),单依赖体积极小
  • Code 128-B 条形码 + 人眼可读文本 + 标准/可配静区

演示

demo/pages/CodeDemoPage.kt:二维码(方形/圆点/圆角渐变)+ 条形码(带/不带文本)完整示例。

测试

./gradlew :kuiklyCode:iosSimulatorArm64Test   # 或 jsNodeTest

覆盖:Code128 编码表 vs zxing 全量对照、auto B/C 混合手算向量、EAN-13 表形/双源对照/校验位向量/结构布局、 QR 矩阵结构不变量(定位/定时图案、版本尺寸、确定性、纠错级别差异、UTF-8)、掩码惩罚分与最优性。

许可证

MIT(见 LICENSE)。QR 引擎基于 qrcode-kotlin(MIT) 移植改造,见 THIRD_PARTY_NOTICES.md。

About

Kuikly QR code & Code128 barcode views (classic DSL, pure Kotlin common) | 二维码/条形码组件

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages