一、引言二维码已经渗透到日常生活的每个角落。扫码支付、扫码加好友、扫码连接 WiFi、扫码打开网页——二维码从技术上讲是一种信息编码方式但从产品体验上讲它是一种物理世界到数字世界的快捷入口。几乎每个 App 都有生成二维码的能力分享链接时生成二维码让朋友扫码打开、设备配网时生成二维码让用户扫描连接、个人名片页生成二维码方便交换联系方式。二维码的生成原理并不复杂——将字符串按 QR Code 标准编码为黑白像素矩阵。但不复杂不代表容易实现。如果在应用中自己编写 QR Code 编码算法需要考虑纠错等级选择、版本自适应、掩码模式、数据编码模式等底层细节——这些在任何编程语言中都是一项不小的工程。HarmonyOS 提供了QRCode组件——一个内置于 ArkUI 的二维码生成组件。开发者只需要传入一个字符串QRCode 自动完成编码、纠错、版本选择、矩阵渲染的全部过程。生成的二维码图案以组件形式直接渲染到 UI 中响应式更新——输入内容变化时二维码自动重新生成无需手动触发。本文通过一个二维码生成器Demo 深入讲解 QRCode 组件的核心用法如何生成不同类型内容的二维码如何自定义前景色和背景色如何调整二维码尺寸如何实现实时生成阅读完本文你将能够使用 QRCode 组件生成 URL、纯文本、电话、邮箱、WiFi 配置等二维码使用color()和backgroundColor()自定义二维码的外观配色结合 TextInput 的onChange实现输入内容实时生成二维码调整二维码尺寸以适应不同的展示场景二、QRCode 组件 API 总览2.1 构造函数QRCode(value:ResourceStr)QRCode 的构造函数极其简洁——接收一个字符串参数自动将其编码为二维码。字符串可以是任何内容网址、纯文本、电话号码、WiFi 配置等。// 生成网址二维码QRCode(https://www.harmonyos.com)// 生成纯文本二维码QRCode(你好鸿蒙)// 生成电话号码二维码QRCode(tel:13800138000)构造函数没有额外的配置项——所有定制都通过链式方法完成。2.2 核心方法QRCode 的方法极其精简只有两个样式方法方法用途默认值示例color(value: ResourceColor)二维码图案颜色前景色#000000.color(#1677FF)backgroundColor(value: ResourceColor)二维码背景颜色#FFFFFF.backgroundColor(#F2F3F5)注意QRCode 继承自CommonMethod因此也拥有通用的尺寸方法width/height、背景方法等。2.3 基本用法模式StateqrContent:stringhttps://www.harmonyos.com;StateqrColor:string#1a1a2e;StateqrBgColor:string#FFFFFF;QRCode(this.qrContent).color(this.qrColor).backgroundColor(this.qrBgColor).width(200).height(200)最简用法只需要一行构造函数——QRCode 自动处理编码和渲染QRCode(https://www.harmonyos.com)2.4 响应式更新QRCode 是声明式组件当构造函数的参数字符串或链式方法的参数颜色、尺寸发生变化时二维码自动重新生成。这意味着你不需要手动调用任何刷新方法——绑定 State 变量即为实时更新Statecontent:string;TextInput({placeholder:输入内容,text:this.content}).onChange((value:string){this.contentvalue;})QRCode(this.content)// content 变化时自动重新生成二维码.width(200).height(200)2.5 二维码内容格式QRCode 接受的字符串内容可以按特定格式编码以适配不同的终端识别行为内容类型编码格式扫码行为网址链接https://example.com直接打开网页纯文本你好鸿蒙显示文本内容电话号码tel:13800138000弹出拨号界面邮箱地址mailto:helloexample.com打开发送邮件界面WiFi 配置WIFI:S:SSID;T:WPA;P:password;;自动连接 WiFi短信SMSTO:13800138000:你好打开短信编辑界面地理坐标geo:39.9087,116.3975打开地图定位其中 WiFi 配置的格式最为固定WIFI:S:网络名;T:加密方式;P:密码;;S:后是 WiFi 的 SSID网络名称T:后是加密类型WPA最常见、WEP、nopass无密码P:后是密码如果T:nopass则省略此字段末尾的;;是格式要求的结束标记不同扫码 App 对这些格式的支持程度不同但 URL、文本、电话和邮件是通用标准。三、Demo 设计二维码生成器3.1 功能概述Demo 是一个二维码生成器页面模拟实际 App 中的分享二维码或扫码加好友功能5 种内容类型预设网址、文本、电话、邮箱、WiFi——用户点击预设按钮快速切换实时生成二维码随输入内容变化实时更新前景色选择器8 种预设颜色黑、蓝、绿、红、粉、橙、紫、青供用户选择背景色选择器7 种背景色白、灰、暖黄、浅绿、浅蓝、浅粉、黑供用户选择尺寸调节三种预设尺寸150×150、200×200、250×250实时预览二维码放大显示在页面中央当前内容类型在下方标注3.2 内容类型预设interfaceTypePreset{label:string;type:string;value:string;}privatetypePresets:TypePreset[][{label:网址,type:URL,value:https://www.harmonyos.com},{label:文本,type:Text,value:你好鸿蒙Hello HarmonyOS},{label:电话,type:Phone,value:tel:13800138000},{label:邮箱,type:Email,value:mailto:helloharmonyos.com},{label:WiFi,type:WiFi,value:WIFI:S:HarmonyOS_5G;T:WPA;P:12345678;;}];每个预设包含展示名称label、类型标识type和实际的编码字符串value。用户点击预设按钮时二维码内容和标签同步更新.onClick((){this.contentTypepreset.type;this.contentLabelpreset.label;this.qrContentpreset.value;})预设按钮使用选中/未选中的双色样式选中状态蓝色背景白字未选中状态灰色背景黑字——与分段控制器的视觉模式一致。3.3 QRCode 核心渲染QRCode(this.qrContent).color(this.qrColor).backgroundColor(this.qrBgColor).width(this.qrSize).height(this.qrSize)四个参数全部绑定到 State 变量this.qrContent从 TextInput 或预设按钮获取的内容字符串this.qrColor从前景色选择器获取的颜色值this.qrBgColor从背景色选择器获取的颜色值this.qrSize从尺寸按钮获取的尺寸值150/200/250当任意状态变化时二维码自动重新生成——这就是声明式 UI 的优势变量改变即 UI 刷新不需要手动调用重新生成函数。3.4 颜色选择器前景色和背景色选择器采用彩色圆点阵列Flex 自动换行布局当前选中的颜色显示蓝色外圈Flex({wrap:FlexWrap.Wrap}){ForEach(this.presetColors,(color:string){Column().width(32).height(32).borderRadius(16).backgroundColor(color).border({width:this.qrColorcolor?3:1,color:this.qrColorcolor?#1677FF:#E8E8ED}).onClick((){this.qrColorcolor;})})}.width(100%)使用Flex({ wrap: FlexWrap.Wrap })而非Row是因为颜色较多8 个前背景色 7 个背景色屏幕宽度可能放不下——Flex 自动换行确保所有色块可见。3.5 尺寸调节尺寸使用三个预设按钮小/中/大点击后直接设置qrSizeButton(小).onClick((){this.qrSize150;})Button(中).onClick((){this.qrSize200;})Button(大).onClick((){this.qrSize250;})150vp 适合卡片内嵌场景200vp 适合详情页展示250vp 适合全屏展示——三种尺寸覆盖了常见的业务需求。3.6 页面结构┌──────────────────────────────────────────┐ │ 二维码生成器深色标题栏 │ ├──────────────────────────────────────────┤ │ QRCode 组件说明卡片 │ ├──────────────────────────────────────────┤ │ ┌ 二维码预览 ──────────────────────┐ │ │ │ │ │ │ │ ████████████████████████ │ │ │ │ ████ ██████ ██ ████ │ │ │ │ ████ ██████ ██ ████ │ │ │ │ ████████████████████████ │ │ │ │ ... │ │ │ │ │ │ │ │ 200 × 200 │ │ │ │ 当前内容网址链接 │ │ │ └───────────────────────────────────┘ │ ├──────────────────────────────────────────┤ │ ┌ 内容类型 ────────────────────────┐ │ │ │ [网址] [文本] [电话] [邮箱] [WiFi]│ │ │ └───────────────────────────────────┘ │ ├──────────────────────────────────────────┤ │ ┌ 自定义内容 ──────────────────────┐ │ │ │ [请输入文本或链接... ] │ │ │ └───────────────────────────────────┘ │ ├──────────────────────────────────────────┤ │ ┌ 前景色 ──────────────────────────┐ │ │ │ ⬤ ⬤ ⬤ ⬤ ⬤ ⬤ ⬤ ⬤ │ │ │ └───────────────────────────────────┘ │ ├──────────────────────────────────────────┤ │ ┌ 背景色 ──────────────────────────┐ │ │ │ ○ ○ ○ ○ ○ ○ ○ │ │ │ └───────────────────────────────────┘ │ ├──────────────────────────────────────────┤ │ ┌ 尺寸调节 ────────────────────────┐ │ │ │ 200×200 [小] [中] [大] │ │ │ └───────────────────────────────────┘ │ └──────────────────────────────────────────┘四、QRCode 组件的最佳实践4.1 颜色对比度二维码识别的核心是前景色与背景色之间有足够的对比度。扫描器通过检测明暗模块的排列来解码如果前景色和背景色对比度不足例如浅灰前景 白色背景扫描器可能无法正确识别。推荐组合深色前景 浅色背景如#1a1a2e#FFFFFF——最高对比度100% 可扫描品牌色前景 白色背景如#1677FF#FFFFFF——兼顾品牌和可读性白色前景 深色背景如#FFFFFF#1a1a2e——深色模式下的反转配色避免的组合浅色前景 浅色背景如黄色 白色相近色前景和背景如深蓝 深紫红色前景 绿色背景色盲用户完全无法分辨4.2 尺寸与扫描距离二维码的显示尺寸直接影响扫描距离和成功率屏幕尺寸推荐扫描距离适用场景100vp 15cm卡片内嵌的小型二维码150vp15~30cm列表项中的二维码200vp30~50cm详情页展示250vp50~100cm大屏设备、平板一般来说二维码尺寸不应小于 100vp——再小的话摄像头在正常距离下无法对焦到足够的模块细节。4.3 实时生成的性能QRCode 组件在每次参数变化时重新编码和渲染。当用户在 TextInput 中输入时onChange每次触发都会更新 State导致二维码重新生成。对于几十个字符的短内容这是完全流畅的。但如果绑定到很长的文本1000 字符每次输入都重新生成可能有可见延迟。优化策略在onChange中使用防抖300~500ms 延迟后才更新 State对于长文本提供一个生成按钮手动触发而非实时生成使用cachedCount如果 QRCode 在 Swiper 等容器中预缓存渲染结果不过对于典型的二维码使用场景网址、联系方式等短文本实时生成完全不需要优化。4.4 QRCode 与 Image 的选择QRCode 组件生成的是原生矢量矩阵图案Image 组件加载的是预先准备好的 PNG/JPG 图片。两者的选择场景推荐方案原因用户内容动态生成QRCode无需预生成图片响应式更新固定不变的公司二维码Image一次生成后反复使用节省编码开销需要在弹窗/浮层中展示QRCode声明式渲染与弹窗生命周期绑定需要分享到其他 App截屏或导出QRCode 本身不能直接导出为图片文件QRCode 组件生成的是屏幕渲染结果不是图片文件。如果需要保存二维码为图片文件用于分享到微信等需要额外使用截图 API 或 Canvas 导出。4.5 纠错等级QR Code 标准有四个纠错等级L7%、M15%、Q25%、H30%。百分比表示即使这么多面积被遮挡仍可正确扫描。QRCode 组件不暴露纠错等级配置自动选择最优等级但在设计二维码展示时需要注意高纠错等级会生成更密集的图案更多模块需要更大的尺寸才能清晰扫描如果计划在二维码中央叠加 Logo如品牌标志系统会自动使用更高的纠错等级以补偿 Logo 遮挡4.6 安全性考虑二维码是一种所见非所得的信息载体——用户看到的是一堆黑白方块但扫码后的行为打开网页、拨打电话、发送邮件可能出乎意料。作为开发者预览真实内容在二维码下方显示实际会被解码的内容如本文 Demo 的当前内容标签让用户在扫码前就能判断二维码的可信度不编码敏感信息不要在二维码中编码密码、Token、身份证号等敏感信息——二维码的内容是明文存储的任何扫描器都能读取WiFi 密码注意WiFi 类型的二维码包含了明文密码应仅在受控环境中使用如家庭路由器配置不要在公开场合展示五、完整代码结构QRCodePage (~275 行) ├── 接口 │ └── TypePreset — 内容类型预设接口 ├── 状态变量 │ ├── State qrContent — 二维码内容字符串 │ ├── State qrColor — 前景色 │ ├── State qrBgColor — 背景色 │ ├── State qrSize — 二维码尺寸 │ ├── State contentType — 当前内容类型标识 │ └── State contentLabel — 当前内容类型标签 ├── 数据 │ ├── presetColors: string[] — 8 种前景色预设 │ ├── presetBgColors: string[] — 7 种背景色预设 │ └── typePresets: TypePreset[] — 5 种内容类型预设 ├── 视图 │ ├── 标题栏 — 二维码生成器 │ ├── 说明卡片 — QRCode 组件介绍 │ ├── 二维码预览区 │ ├── 内容类型预设按钮 │ ├── 自定义内容 TextInput │ ├── 前景色选择器 │ ├── 背景色选择器 │ └── 尺寸调节按钮 └── 无 Builder——所有布局内联六、总结本文通过一个二维码生成器Demo 深入讲解了 HarmonyOS 中的QRCode 二维码组件。QRCode 将复杂的 QR Code 编码算法封装为一个简单的声明式组件——开发者只需要传入字符串即可生成二维码图案内容的编码、纠错、版本适配、渲染全部由 QRCode 内部完成。核心要点回顾QRCode 是字符串 → 像素矩阵的转换器构造函数接收字符串内部完成 QR Code 标准的全部编码流程输出可扫描的二维码图案。开发者不需要理解 QR Code 的编码算法。color 和 backgroundColor 是唯二的外观控制方法前景色控制二维码模块的颜色背景色控制底层背景。两者之间需要足够的对比度以保证可扫描性。声明式更新是 QRCode 的核心使用模式绑定 State 变量到构造函数和样式方法变量变化时二维码自动重新生成。结合 TextInput 的onChange即可实现输入内容实时生成二维码。不同内容格式决定扫码行为URL打开网页、tel拨号、mailto发邮件、WiFi连接网络——QRCode 只负责生成图案格式的正确性由开发者保证。二维码尺寸应在 100~250vp 之间太小难以扫描太大浪费空间。200vp 是大多数场景的最佳选择。安全性不容忽视二维码内容对扫描者完全透明。在二维码下方标注内容摘要、避免在二维码中编码敏感信息——是开发者的基本责任。QRCode 是 ArkUI 中最即插即用的组件之一——API 只有三个方法构造函数 color backgroundColor但实际价值远超其复杂度。任何一个需要分享或传输功能的 App 都离不开二维码而 QRCode 让这个看似复杂的任务变得简单自然。七、扩展思考QRCode 组件覆盖了基础的二维码生成需求但在实际项目中二维码的展示和使用还有更多维度在二维码中央叠加 Logo很多品牌的二维码会在中央放置一个小型品牌 Logo。QRCode 组件本身不支持叠加图片但可以通过 Stack 布局将 QRCode 和 Image 叠加在一起——Logo 的尺寸应不超过二维码面积的 15%以保留足够的纠错冗余。导出二维码为图片QRCode 是屏幕上的渲染结果不是图片文件。如果需要将二维码保存为文件用于分享到微信、保存到相册需要结合 Canvas 的截图能力或使用第三方库手动编码。二维码与 RFID/NFC 的协同在物联网场景中二维码和 NFC 标签可以互为补充——近距离用 NFC 触碰配对远距离用二维码扫描配对。两者的编码内容应保持一致。二维码美化QRCode 组件只提供纯色设置。如果需要渐变、圆角模块等高级美化效果需要超出 QRCode 的能力范围——这类定制通常需要使用 Canvas 从头绘制。动态二维码某些场景如双因素认证需要在页面刷新时生成新的二维码。结合setInterval定时更新 State 变量QRCode 会自动重新生成——这是动态二维码的简单实现方式。理解 QRCode 的定位——字符串到二维码图案的声明式转换组件——是正确使用它的关键。它不是一个集成化的分享二维码业务组件不含弹出菜单、保存按钮、社交分享等而是专注于一个核心任务将字符串编码为二维码并在屏幕上渲染。这种单一职责使得 QRCode 可以无缝嵌入到任何需要二维码的场景中——从支付码到分享码、从设备配网到名片交换。通过本文的 Demo——二维码生成器页面你将 QRCode 组件与 TextInput、颜色选择器和尺寸控制组合在一起构建了一个完整的二维码实时生成工具。这个页面展示了 QRCode 作为即插即用组件的核心价值——用最少的 API 完成最常见的任务。