
Render QR codes and barcodes via Canvas with built-in QR/Code128/EAN-13 encoders, logo overlay, automatic mask selection, shape/gradient styling, dynamic refresh, state-aware transitions and customization.
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 标准逐条校验),
完全本地生成,无网络、无原生依赖。
minVersion 版本下限(防止文本变短时二维码尺寸跳变)textProvider 数据变化自动重绘,
SUCCESS 态变化时双画布过渡动画(直接切换 / 交叉淡化 / 上下推移,响应式检测无轮询)stateProvider 传入 SUCCESS / LOADING / EMPTY / ERROR,
各态可注入自定义视图(loadingView / emptyView / errorView),取数/重试/轮换定时器由宿主业务自管onError 事件Code128Reader / UPCEANReader / EAN13Reader)逐条校验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
}
}组件只负责展示:取数、重试、轮换定时器由宿主业务自管,通过响应式 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() }
}
}loadingView 可注入任意自定义效果)emptyView / errorView 可整体替换| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 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 | - | 暂无内容/加载失败/灰 | 默认占位样式 |
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 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 | 文本样式 |
// 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 代码(零平台分支),两种方式:
kuiklyCode 模块加入宿主 KuiklyUI 工程的鸿蒙构建
(settings.ohos.gradle.kts include + 模块内 build.ohos.gradle.kts 已就位);-ohos 变体:在配置了 KuiklyBase ohos toolchain 的工程中执行
./gradlew -c settings.ohos.gradle.kts :kuiklyCode:publishToMavenLocal,宿主从 mavenLocal 引用。组件代码已在鸿蒙 Next 生产应用(五端电商 App)中随业务页运行验证。
官方市场另有 QRose(alexzhirkevich/qrose 的 Kuikly Compose DSL 适配版)。
本组件面向经典 Kuikly DSL(com.tencent.kuikly.core)工程:
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。
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 标准逐条校验),
完全本地生成,无网络、无原生依赖。
minVersion 版本下限(防止文本变短时二维码尺寸跳变)textProvider 数据变化自动重绘,
SUCCESS 态变化时双画布过渡动画(直接切换 / 交叉淡化 / 上下推移,响应式检测无轮询)stateProvider 传入 SUCCESS / LOADING / EMPTY / ERROR,
各态可注入自定义视图(loadingView / emptyView / errorView),取数/重试/轮换定时器由宿主业务自管onError 事件Code128Reader / UPCEANReader / EAN13Reader)逐条校验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
}
}组件只负责展示:取数、重试、轮换定时器由宿主业务自管,通过响应式 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() }
}
}loadingView 可注入任意自定义效果)emptyView / errorView 可整体替换| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 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 | - | 暂无内容/加载失败/灰 | 默认占位样式 |
| 属性 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 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 | 文本样式 |
// 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 代码(零平台分支),两种方式:
kuiklyCode 模块加入宿主 KuiklyUI 工程的鸿蒙构建
(settings.ohos.gradle.kts include + 模块内 build.ohos.gradle.kts 已就位);-ohos 变体:在配置了 KuiklyBase ohos toolchain 的工程中执行
./gradlew -c settings.ohos.gradle.kts :kuiklyCode:publishToMavenLocal,宿主从 mavenLocal 引用。组件代码已在鸿蒙 Next 生产应用(五端电商 App)中随业务页运行验证。
官方市场另有 QRose(alexzhirkevich/qrose 的 Kuikly Compose DSL 适配版)。
本组件面向经典 Kuikly DSL(com.tencent.kuikly.core)工程:
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。