二维码（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 Code（Quick 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 组件：

@State inputText: string = 'https://www.harmonyos.com';

TextInput({ placeholder: '输入文本、网址或其它内容', text: this.inputText })
  .onChange((value: string) => { this.inputText = value; })

QRCode(this.inputText.length > 0 ? 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.length > 0) {
  Text('✕')
    .width(36).height(36)
    .borderRadius(18)
    .backgroundColor('#F2F3F5')
    .onClick(() => { this.clearInput(); })
}

清除按钮是一个条件渲染的圆形容器（36×36vp），灰色背景（#F2F3F5），与输入框间距 8vp。圆形按钮的设计与输入框的圆角矩形形成对比——帮助用户快速区分"输入区域"和"操作按钮"。
在这里插入图片描述

三、模板化内容切换

3.1 四种使用场景

二维码不只是链接——不同的内容格式对应不同的使用场景。本文提供四种预设模板：

1. 网址（URL）

https://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. 名片（vCard）

BEGIN:VCARD
VERSION:3.0
FN:张三
TEL:13800000000
EMAIL:zhangsan@example.com
END:VCARD

vCard 是电子名片的国际标准格式（RFC 6350）。常见的字段包括：

  • FN — 全名（Formatted Name）
  • TEL — 电话号码
  • 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(idx === this.activePreset ? '#FFFFFF' : '#666677')
      .fontWeight(idx === this.activePreset ? FontWeight.Bold : FontWeight.Normal)
  }
  .width(72)
  .backgroundColor(idx === this.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 vp：

ForEach(this.sizes, (s: number) => {
  Text(s.toString())
    .backgroundColor(this.qrSize === s ? '#1677FF' : '#F2F3F5')
    .onClick(() => { this.qrSize = s; })
})

三种尺寸的适用场景：

  • 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.qrSize + 24).height(this.qrSize + 24)
.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 组件的使用方法。核心知识点包括：

  1. QRCode API：value / color / backgroundColor / width / height 五个核心属性
  2. 实时生成机制：TextInput.onChange → @State 更新 → QRCode 重新渲染
  3. 四种模板格式：URL（网址直达）、纯文本（信息分享）、WiFi 配置（免密连接）、vCard 名片（联系人导入）
  4. 视觉效果定制：码颜色选择（对比度原则）+ 尺寸切换（160/200/240vp）+ 静区与阴影
  5. 安全使用建议：内容预览、HTTPS 优先、敏感信息保护
  6. 模板化 UI：Chip 选择器 + 预设文本 + 自由修改

QRCode 组件的价值在于"简单而强大"——只需一个字符串和几个属性，就能生成标准的可扫描二维码。它消除了手写二维码编码逻辑的需要（矩阵生成、纠错码计算、掩码选择），让开发者专注于"二维码在业务流程中的位置"（什么时候生成、展示什么内容、用户如何使用），而非"二维码如何生成"。

# harmonyos # 华为 # windows # 游戏 # lua
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

关于鸿蒙电脑一些开发环境的配置

DevBox 是 OpenHarmony PC 开发者工具，提供了一系列命令行工具来帮助开发者进行项目构建、调试和部署，主要包含文件和目录操作命令、网络命令、构建命令、签名工具等。BiShengJDK17-OH(BiShengJDK8-OH)是基于毕昇 JDK 的 JDK 安装器，在鸿蒙电脑上提供 JRE\JVM 等核心 Java 工具链。Python 安装器是适用于 HarmonyOS 的 Py

avatar 人工智能6S服务平台
cover

01 鸿蒙 NEXT 开发环境搭建完全指南（DevEco Studio 5.0）

avatar 人工智能6S服务平台
cover

00_开篇与项目总览：鹿鹿·笔迹心理分析 — 鸿蒙应用开发实战系列

avatar 人工智能6S服务平台