二维码QR Code已经成为连接物理世界和数字世界的重要桥梁。从微信扫码加好友到支付宝付款从 WiFi 密码分享到名片交换——二维码让信息传输从打字输入变成了扫一下。HarmonyOS NEXT ArkUI 提供了 QRCode 组件只需提供文本内容即可自动渲染为二维码图像无需第三方库或 Canvas 手动绘制。本文将通过一个二维码生成器实战案例深入讲解 QRCode 组件的使用方法、实时生成机制、模板化内容切换和视觉效果定制。同时讨论 TextInput 联动更新、二维码颜色与尺寸设计原则以及安全使用建议。关键词HarmonyOS、ArkUI、QRCode、二维码、实时生成、模板切换一、QRCode 组件基础1.1 API 概述QRCode 是 ArkUI 提供的二维码生成组件接收一个字符串参数自动将其编码为标准 QR Code 并渲染为图像QRCode(value:string).width(number).height(number).color(Color)// 码块颜色默认黑色.backgroundColor(Color)// 背景颜色默认白色核心属性说明value待编码的字符串内容。可以是 URL、纯文本、vCard 名片格式、WiFi 配置字符串等任何符合 QR Code 规范的文本。color二维码的前景色码块颜色。默认为黑色可自定义为任意颜色。注意对比度——浅色码块在白色背景上会难以扫描。backgroundColor二维码的背景色。默认为白色。不建议使用深色背景因为大多数二维码扫描器针对黑码白底做了优化。width / height二维码的尺寸。设置为相同值以保证方形QR Code 本质是方形非方形会导致拉伸变形。1.2 QR Code 的工作原理QR CodeQuick Response Code是一种二维矩阵码由黑白方块称为模块组成。它通过不同位置的图案来编码信息定位图案Finder Pattern三个角落的回字形方块帮助扫描器识别方向和位置校正图案Alignment Pattern辅助精确定位在较大尺寸的二维码中出现时序图案Timing Pattern两组黑白交替的模块帮助确定码的网格数据区域实际编码信息的模块纠错码区域允许部分损坏后仍可读取QRCode 组件内部处理了编码字符串 → 二进制 → QR Code 矩阵、纠错码生成、掩码应用和图像渲染——开发者只需提供字符串其他全部自动完成。1.3 内容长度与二维码版本QR Code 有 40 个版本从 21×21 模块版本 1到 177×177 模块版本 40。容纳的内容越多版本越高模块越密集。短 URL如 “https://a.co”只需版本 1-2长 URL 或 vCard 名片可能需要版本 5-10。在固定像素尺寸下如 200×200vp版本越高的二维码每个模块越小模块越密集。对于高版本二维码需要确保渲染尺寸足够大——每个模块至少占 2-3 个物理像素才能被摄像头准确识别。本文 Demo 使用的四种模板内容都在版本 2-6 范围内在 200×200vp 的显示尺寸下完全可识别。二、实时生成机制2.1 TextInput 联动二维码的内容通过 TextInput 输入输入的文字通过State变量inputText实时同步到 QRCode 组件StateinputText:stringhttps://www.harmonyos.com;TextInput({placeholder:输入文本、网址或其它内容,text:this.inputText}).onChange((value:string){this.inputTextvalue;})QRCode(this.inputText.length0?this.inputText: ).width(this.qrSize).height(this.qrSize).color(this.qrColor).backgroundColor(#FFFFFF)用户每输入一个字符onChange触发 →inputText更新 →State通知框架 → QRCode 重新生成。整个过程在毫秒级完成用户感知到的效果是边打字边生成二维码。空内容处理当inputText为空字符串时传入单个空格 给 QRCode——避免空字符串可能导致的不渲染。二维码中间会出现一个代表空格的码块图案视觉上是一个小黑块周围白色的区域。字符计数在输入框下方显示已输入 N 个字符帮助用户了解信息量。对于二维码而言字符越多模块越密扫描难度越大。字符计数是一种隐性的复杂度提示。2.2 清除按钮输入框右侧显示清除按钮✕仅在内容不为空时出现if(this.inputText.length0){Text(✕).width(36).height(36).borderRadius(18).backgroundColor(#F2F3F5).onClick((){this.clearInput();})}清除按钮是一个条件渲染的圆形容器36×36vp灰色背景#F2F3F5与输入框间距 8vp。圆形按钮的设计与输入框的圆角矩形形成对比——帮助用户快速区分输入区域和操作按钮。三、模板化内容切换3.1 四种使用场景二维码不只是链接——不同的内容格式对应不同的使用场景。本文提供四种预设模板1. 网址URLhttps://www.harmonyos.com最常用的二维码场景——扫码后浏览器自动打开网址。URL 格式的二维码被所有扫描器原生支持。2. 纯文本你好鸿蒙世界Hello HarmonyOS NEXT任意文本信息。扫码后显示为可阅读的文本。适用于快速分享一段话、一个代码片段或简短说明。扫码器通常展示为文本结果。3. WiFi 配置WIFI:T:WPA;S:MyWiFi;P:12345678;;这是 WiFi 配置的通用格式由 ZXing 项目推广T:WPA— 安全类型WPA / WEP / 不加密S:MyWiFi— WiFi 名称 (SSID)P:12345678— 密码;;— 结束符扫描后iOS 和 Android 系统会识别此格式并提示加入 Wi-Fi 网络用户只需点一下即可连接——无需手动输入密码。4. 名片vCardBEGIN:VCARD VERSION:3.0 FN:张三 TEL:13800000000 EMAIL:zhangsanexample.com END:VCARDvCard 是电子名片的国际标准格式RFC 6350。常见的字段包括FN— 全名Formatted NameTEL— 电话号码EMAIL— 邮箱地址ORG— 组织TITLE— 职位扫描后手机会弹出添加到通讯录的界面所有字段自动填充——交换名片从手敲号码升级为扫一下。3.2 模板切换 UI四种模板以 Chip 卡片形式排列点击即用ForEach(this.presets,(p:PresetItem,idx:number){Column(){Text(p.icon).fontSize(24).margin({bottom:4})Text(p.label).fontSize(11).fontColor(idxthis.activePreset?#FFFFFF:#666677).fontWeight(idxthis.activePreset?FontWeight.Bold:FontWeight.Normal)}.width(72).backgroundColor(idxthis.activePreset?#1677FF:#F2F3F5).onClick((){this.applyPreset(idx);})})每个 Chip 包含 emoji 图标和两字标签。选中态为蓝色底色 白色文字未选中态为灰色底色 灰色文字。applyPreset同时更新activePreset和inputText填入预置模板文本。模板切换后用户可以在预置文本的基础上自由修改——例如将 WiFi 模板中的密码改为自己的实际密码、将名片模板中的手机号改为自己的实际号码。模板是起点而非终态。四、视觉效果定制4.1 码颜色二维码的前景色默认为黑色但 QRCode 组件允许自定义颜色QRCode(value).color(#1677FF)// 蓝色码块本文 Demo 提供三种颜色选择黑色经典对比度最高、蓝色品牌感适合 URL 分享、绿色新鲜感适合文本/WiFi。颜色选择的注意事项颜色与白色背景的对比度必须足够高。浅色码块如 #CCCCDD在白色背景上几乎不可见扫描器难以识别。彩色二维码看起来更个性但黑色二维码的识别速度和成功率最高——扫描器的算法针对黑/白对比做了深度优化。如果一定要用彩色选择深色系深蓝、深绿、深紫避免浅色系浅粉、浅黄、浅蓝。4.2 尺寸选择二维码尺寸通过 Chip 按钮切换——160 / 200 / 240 vpForEach(this.sizes,(s:number){Text(s.toString()).backgroundColor(this.qrSizes?#1677FF:#F2F3F5).onClick((){this.qrSizes;})})三种尺寸的适用场景160vp紧凑型适合在页面内与其他内容并排展示如联系人详情页的二维码按钮200vp标准型适合独立的二维码展示页面本文默认240vp大型适合需要远距离扫描的场景如在会议大屏上展示二维码尺寸越大二维码中的每个模块占据的物理像素越多摄像头越容易识别。但过大的尺寸会浪费屏幕空间。160-240vp 是移动端的实用范围。4.3 容器与阴影二维码周围有 12vp 的白色边距通过外层容器 padding 实现和轻微的卡片阴影Column(){QRCode(value).width(this.qrSize).height(this.qrSize).color(this.qrColor).backgroundColor(#FFFFFF)}.width(this.qrSize24).height(this.qrSize24).justifyContent(FlexAlign.Center).borderRadius(12).backgroundColor(#FFFFFF).shadow({radius:12,color:#00000010,offsetX:0,offsetY:4})白色边距是二维码可扫描性的静区Quiet Zone——QR Code 规范要求在码周围保持至少 4 个模块宽度的空白区域帮助扫描器区分二维码和背景。12vp 边距 阴影的浮起效果让二维码像贴在页面上从背景中清晰分离。五、安全使用建议5.1 扫码前预览内容二维码本质上是不透明的——用户看不到它编码了什么只有扫描后才知道。这导致了安全风险恶意二维码可能指向钓鱼网站或下载恶意软件。在使用 QRCode 组件生成分享二维码时建议在二维码下方或旁边同时显示文字版的内容预览——让接收方在扫码前就能看到这个码指向哪个网址或这个码包含什么信息。5.2 URL 可读性对于 URL 类型的二维码https 开头是安全的标志浏览器会检查 HTTPS 证书。避免生成 http非加密协议的 URL 二维码——用户扫描后发现是不安全连接会立即产生不信任感。5.3 敏感信息加密WiFi 密码、个人信息等内容直接编码到二维码中。二维码是公开的——任何人拍到都可以扫描。在公共场所办公室、咖啡厅展示包含密码的二维码时要意识到密码对在场所有人可见通过扫描获取。WiFi 二维码的密码字段是明文存储的——不要在不可信的二维码生成器中使用真实密码。本文的 Demo 使用的是示例密码 “12345678”。六、完整交互流程6.1 初始状态进入页面默认选中网址模板显示 harmonyos.com 的 URL 二维码。二维码使用 200vp 尺寸、黑色码块。输入框显示当前 URL 文本。6.2 输入自定义内容在输入框中输入自定义文本二维码实时更新。输入框显示已输入字符数。输入为空时下方提示请输入内容生成二维码。6.3 切换模板点击WiFi Chip 切换到 WiFi 配置模板。二维码立即变为 WiFi 配置码200vp、黑色。输入框自动填入 WiFi 配置字符串。用户可在模板文本基础上修改 SSID 和密码。再点击名片 Chip二维码切换为 vCard 名片码。用户可修改姓名为自己的名字。6.4 改变颜色在颜色选择区点击蓝色圆点二维码码块变为蓝色#1677FF。码块颜色切换即刻生效——之前的黑色码变为蓝色码。切换回黑色恢复标准外观。6.5 调整尺寸点击240尺寸 Chip二维码放大到 240×240vp。模块间距变大看起来更清晰。再点160缩小到紧凑型。不同尺寸下二维码的模块密度不同但编码内容完全相同。6.6 清除内容点击输入框右侧的 ✕ 按钮清空内容。二维码显示为空码单个空格的编码结果提示文字变为请输入内容生成二维码。重新输入任意内容后二维码恢复生成。七、进阶扩展方向7.1 二维码保存到相册将生成的二维码导出为图片保存到系统相册方便离线分享。可以结合 ArkUI 的截图 API 或 Canvas 导出能力将二维码组件范围内的像素保存为 PNG 文件。7.2 自定义 Logo 叠加在二维码中心叠加应用 Logo如微信二维码中间的头像。这需要将 QRCode 组件和 Image 组件放在 Stack 中。注意 Logo 不应遮挡定位图案角落的回字且 Logo 尺寸不应超过二维码面积的 30%QR Code 的纠错能力可以承受部分内容被遮挡。7.3 批量生成一次生成多个二维码如一页多个 WiFi 热点码。使用 Column ForEach QRCode 组件列表实现。每个二维码下方配文字说明。7.4 二维码扫描检测检测输入内容中是否已包含二维码格式如以 https:// 开头、包含 BEGIN:VCARD 等智能推荐模板类型。inputText.startsWith(https://)→ 自动切换为网址模板。7.5 扫一扫功能集成在二维码生成器的基础上增加二维码扫描功能使用系统相机 API。形成生成 扫描的闭环——用户在生成和扫描之间无缝切换。八、总结本文通过二维码生成器这个实战案例全面讲解了 ArkUI QRCode 组件的使用方法。核心知识点包括QRCode APIvalue / color / backgroundColor / width / height 五个核心属性实时生成机制TextInput.onChange → State 更新 → QRCode 重新渲染四种模板格式URL网址直达、纯文本信息分享、WiFi 配置免密连接、vCard 名片联系人导入视觉效果定制码颜色选择对比度原则 尺寸切换160/200/240vp 静区与阴影安全使用建议内容预览、HTTPS 优先、敏感信息保护模板化 UIChip 选择器 预设文本 自由修改QRCode 组件的价值在于简单而强大——只需一个字符串和几个属性就能生成标准的可扫描二维码。它消除了手写二维码编码逻辑的需要矩阵生成、纠错码计算、掩码选择让开发者专注于二维码在业务流程中的位置什么时候生成、展示什么内容、用户如何使用而非二维码如何生成。