高级进阶 ReactNative for Harmony 项目鸿蒙化三方库集成实战：react-native-qrcode-svg
欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
📋 前言
react-native-qrcode-svg 是一个轻量级的二维码生成库，基于 SVG 实现，可以生成高质量的二维码图像。该库支持自定义颜色、大小、错误纠正级别等参数，完全兼容 Android、iOS、Web 和 HarmonyOS 多平台，是二维码生成、分享链接、数据编码的理想选择。
🎯 库简介
基本信息
- 库名称: react-native-qrcode-svg
- 版本信息:
6.2.0: 支持 RN 0.72 版本6.3.20: 支持 RN 0.77 版本
- 官方仓库: https://github.com/awesomejerry/react-native-qrcode-svg
- 主要功能:
- 二维码生成
- 自定义颜色
- 自定义大小
- 错误纠正级别
- SVG 矢量渲染
- 高质量输出
- 兼容性验证:
- RNOH：0.72.27; SDK：HarmonyOS-Next-DB1 5.0.0.29(SP1); IDE: DevEco Studio 5.0.3.400; ROM: 3.0.0.25;
- RNOH：0.72.96; SDK: HarmonyOS 5.1.1 Release SDK; IDE: DevEco Studio 5.1.1.840; ROM: 6.0.0;
- RNOH：0.77.18; SDK: HarmonyOS 5.1.1 Release SDK; IDE: DevEco Studio 5.1.1.840; ROM: 6.0.0;
为什么需要这个库？
- 用户体验: 高质量的二维码生成，提升应用品质
- 轻量级: 基于 SVG 实现，无需原生图片
- 高度可定制: 支持颜色、大小、错误纠正等参数
- 易于使用: API 简单直观，集成快速
- 跨平台: 在多平台提供一致的体验
- 分享必备: 二维码分享的标准选择
📦 安装步骤
1. 使用 npm 安装
根据您的 RN 版本选择对应的版本：
# RN 0.72
npm install react-native-qrcode-svg@6.2.0
# RN 0.77
npm install react-native-qrcode-svg@6.3.20
2. 验证安装
安装完成后,检查 package.json 文件,应该能看到新增的依赖：
{
"dependencies": {
"react-native-qrcode-svg": "^6.2.0",
// ... 其他依赖
}
}
🔧 HarmonyOS 平台配置 ⭐
重要说明
react-native-qrcode-svg 依赖 react-native-svg，需要确保项目中已安装 @react-native-oh-tpl/react-native-svg 或 @react-native-ohos/react-native-svg。
依赖关系
本库 HarmonyOS 侧实现依赖 @react-native-oh-tpl/react-native-svg 的原生端代码，如已在 HarmonyOS 工程中引入过该库，则无需再次引入，可跳过本章节步骤，直接使用。
⚠️ TextEncoder 错误解决方案
如果在运行时遇到 Property 'TextEncoder' doesn't exist 错误，请按以下步骤解决：
- 在项目根目录创建
polyfills.js文件：
// polyfills.js
if (typeof TextEncoder === 'undefined') {
global.TextEncoder = require('text-encoding').TextEncoder;
global.TextDecoder = require('text-encoding').TextDecoder;
}
- 在项目入口文件（如
index.js或App.js）顶部导入：
import './polyfills';
- 安装依赖：
npm install text-encoding
注意：此问题在 v6.2.0+ 版本中已修复，建议升级到最新版本。
💻 完整代码示例
下面是一个完整的示例,展示了 react-native-qrcode-svg 的各种使用场景:
import React, { useState } from 'react';
import {
View,
Text,
StyleSheet,
ScrollView,
TouchableOpacity,
SafeAreaView,
TextInput,
Alert,
Dimensions,
} from 'react-native';
import QRCode from 'react-native-qrcode-svg';
function QRCodeDemo(): JSX.Element {
const [qrValue, setQRValue] = useState('https://www.baidu.com');
const [qrColor, setQRColor] = useState('#000000');
const [qrSize, setQRSize] = useState(200);
const [qrBackgroundColor, setQRBackgroundColor] = useState('#FFFFFF');
const windowWidth = Dimensions.get('window').width;
const generateQRCode = () => {
if (!qrValue.trim()) {
Alert.alert('提示', '请输入二维码内容');
return;
}
Alert.alert('成功', '二维码已生成');
};
const presetQRCodes = [
{ label: '百度', value: 'https://www.baidu.com' },
{ label: 'GitHub', value: 'https://github.com' },
{ label: '微信', value: 'https://weixin.qq.com' },
{ label: '文本', value: 'Hello World' },
];
return (
<SafeAreaView style={styles.container}>
<ScrollView style={styles.content}>
<Text style={styles.title}>二维码生成器</Text>
{/* 基础二维码 */}
<View style={styles.section}>
<Text style={styles.sectionTitle}>基础二维码</Text>
<View style={styles.qrContainer}>
<QRCode
value={qrValue}
size={qrSize}
color={qrColor}
backgroundColor={qrBackgroundColor}
/>
</View>
</View>
{/* 输入控制 */}
<View style={styles.section}>
<Text style={styles.sectionTitle}>输入内容</Text>
<TextInput
style={styles.input}
value={qrValue}
onChangeText={setQRValue}
placeholder="请输入二维码内容"
placeholderTextColor="#999"
/>
<TouchableOpacity style={styles.generateButton} onPress={generateQRCode}>
<Text style={styles.generateButtonText}>生成二维码</Text>
</TouchableOpacity>
</View>
{/* 预设内容 */}
<View style={styles.section}>
<Text style={styles.sectionTitle}>预设内容</Text>
<View style={styles.presetGrid}>
{presetQRCodes.map((item) => (
<TouchableOpacity
key={item.label}
style={styles.presetButton}
onPress={() => setQRValue(item.value)}
>
<Text style={styles.presetButtonText}>{item.label}</Text>
</TouchableOpacity>
))}
</View>
</View>
{/* 尺寸控制 */}
<View style={styles.section}>
<Text style={styles.sectionTitle}>尺寸控制</Text>
<View style={styles.sizeButtons}>
{[
{ label: '小 (150)', size: 150 },
{ label: '中 (200)', size: 200 },
{ label: '大 (250)', size: 250 },
{ label: '特大 (300)', size: 300 },
].map((item) => (
<TouchableOpacity
key={item.label}
style={[
styles.sizeButton,
qrSize === item.size && styles.sizeButtonActive,
]}
onPress={() => setQRSize(item.size)}
>
<Text
style={[
styles.sizeButtonText,
qrSize === item.size && styles.sizeButtonTextActive,
]}
>
{item.label}
</Text>
</TouchableOpacity>
))}
</View>
</View>
{/* 颜色控制 */}
<View style={styles.section}>
<Text style={styles.sectionTitle}>颜色控制</Text>
<View style={styles.colorGrid}>
{[
{ label: '黑色', color: '#000000' },
{ label: '红色', color: '#FF0000' },
{ label: '蓝色', color: '#0000FF' },
{ label: '绿色', color: '#00FF00' },
{ label: '紫色', color: '#800080' },
].map((item) => (
<TouchableOpacity
key={item.label}
style={[
styles.colorButton,
{ backgroundColor: item.color },
qrColor === item.color && styles.colorButtonActive,
]}
onPress={() => setQRColor(item.color)}
>
<Text
style={[
styles.colorButtonText,
qrColor === item.color && styles.colorButtonTextActive,
]}
>
{item.label}
</Text>
</TouchableOpacity>
))}
</View>
</View>
{/* 背景颜色 */}
<View style={styles.section}>
<Text style={styles.sectionTitle}>背景颜色</Text>
<View style={styles.bgColorGrid}>
{[
{ label: '白色', color: '#FFFFFF' },
{ label: '浅灰', color: '#F5F5F5' },
{ label: '浅蓝', color: '#E3F2FD' },
{ label: '浅黄', color: '#FFF9C4' },
].map((item) => (
<TouchableOpacity
key={item.label}
style={[
styles.bgColorButton,
{ backgroundColor: item.color },
qrBackgroundColor === item.color && styles.bgColorButtonActive,
]}
onPress={() => setQRBackgroundColor(item.color)}
>
<Text
style={[
styles.bgColorButtonText,
qrBackgroundColor === item.color && styles.bgColorButtonTextActive,
]}
>
{item.label}
</Text>
</TouchableOpacity>
))}
</View>
</View>
{/* 功能说明 */}
<View style={styles.infoSection}>
<Text style={styles.infoTitle}>功能说明:</Text>
<Text style={styles.infoText}>• value: 二维码内容</Text>
<Text style={styles.infoText}>• size: 二维码尺寸</Text>
<Text style={styles.infoText}>• color: 二维码颜色</Text>
<Text style={styles.infoText}>• backgroundColor: 背景颜色</Text>
<Text style={styles.infoText}>• SVG 矢量渲染</Text>
</View>
{/* 注意事项 */}
<View style={styles.noteSection}>
<Text style={styles.noteTitle}>注意事项:</Text>
<Text style={styles.noteText}>• 依赖 react-native-svg 库</Text>
<Text style={styles.noteText}>• 支持 SVG 矢量渲染</Text>
<Text style={styles.noteText}>• 建议使用合适的尺寸</Text>
<Text style={styles.noteText}>• 导入库名使用 react-native-qrcode-svg</Text>
</View>
</ScrollView>
</SafeAreaView>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
backgroundColor: '#f5f5f5',
},
content: {
flex: 1,
padding: 15,
},
title: {
fontSize: 24,
fontWeight: 'bold',
marginBottom: 20,
textAlign: 'center',
color: '#333',
},
section: {
backgroundColor: '#fff',
borderRadius: 10,
padding: 15,
marginBottom: 20,
shadowColor: '#000',
shadowOffset: { width: 0, height: 2 },
shadowOpacity: 0.1,
shadowRadius: 4,
elevation: 3,
},
sectionTitle: {
fontSize: 16,
fontWeight: 'bold',
marginBottom: 15,
color: '#333',
},
qrContainer: {
alignItems: 'center',
justifyContent: 'center',
padding: 20,
backgroundColor: '#fafafa',
borderRadius: 8,
},
input: {
borderWidth: 1,
borderColor: '#ddd',
borderRadius: 8,
padding: 12,
fontSize: 16,
marginBottom: 15,
backgroundColor: '#fff',
},
generateButton: {
backgroundColor: '#2196F3',
borderRadius: 8,
paddingVertical: 12,
alignItems: 'center',
},
generateButtonText: {
fontSize: 16,
color: '#fff',
fontWeight: 'bold',
},
presetGrid: {
flexDirection: 'row',
flexWrap: 'wrap',
gap: 10,
},
presetButton: {
paddingHorizontal: 15,
paddingVertical: 8,
backgroundColor: '#f0f0f0',
borderRadius: 6,
},
presetButtonText: {
fontSize: 14,
color: '#333',
},
sizeButtons: {
flexDirection: 'row',
flexWrap: 'wrap',
gap: 10,
},
sizeButton: {
paddingHorizontal: 15,
paddingVertical: 8,
backgroundColor: '#f0f0f0',
borderRadius: 6,
},
sizeButtonActive: {
backgroundColor: '#2196F3',
},
sizeButtonText: {
fontSize: 14,
color: '#333',
},
sizeButtonTextActive: {
color: '#fff',
},
colorGrid: {
flexDirection: 'row',
flexWrap: 'wrap',
gap: 10,
},
colorButton: {
width: 60,
height: 40,
borderRadius: 8,
justifyContent: 'center',
alignItems: 'center',
},
colorButtonActive: {
borderWidth: 2,
borderColor: '#333',
},
colorButtonText: {
fontSize: 12,
color: '#fff',
fontWeight: 'bold',
},
colorButtonTextActive: {
color: '#333',
},
bgColorGrid: {
flexDirection: 'row',
flexWrap: 'wrap',
gap: 10,
},
bgColorButton: {
paddingHorizontal: 15,
paddingVertical: 8,
borderRadius: 6,
borderWidth: 1,
borderColor: '#ddd',
},
bgColorButtonActive: {
borderWidth: 2,
borderColor: '#2196F3',
},
bgColorButtonText: {
fontSize: 14,
color: '#333',
},
bgColorButtonTextActive: {
color: '#2196F3',
fontWeight: 'bold',
},
infoSection: {
padding: 15,
backgroundColor: '#e3f2fd',
borderRadius: 8,
borderLeftWidth: 4,
borderLeftColor: '#42a5f5',
marginBottom: 20,
},
infoTitle: {
fontSize: 16,
fontWeight: 'bold',
marginBottom: 10,
color: '#1565c0',
},
infoText: {
fontSize: 14,
color: '#1976d2',
marginBottom: 5,
},
noteSection: {
padding: 15,
backgroundColor: '#fff3cd',
borderRadius: 8,
borderLeftWidth: 4,
borderLeftColor: '#ffc107',
marginBottom: 20,
},
noteTitle: {
fontSize: 16,
fontWeight: 'bold',
marginBottom: 10,
color: '#856404',
},
noteText: {
fontSize: 14,
color: '#856404',
marginBottom: 5,
},
});
export default QRCodeDemo;
🎨 实际应用场景
react-native-qrcode-svg 可以应用于以下实际场景:
- 分享链接: 应用内分享链接生成二维码
- 数据编码: 将数据编码为二维码
- 产品信息: 商品信息二维码展示
- 支付收款: 支付二维码生成
- 身份验证: 二维码身份验证
- 活动报名: 活动报名二维码
⚠️ 注意事项与最佳实践
1. 内容长度
// ✅ 推荐: 控制内容长度
<QRCode
value="https://www.example.com"
size={200}
/>
// ❌ 避免: 内容过长导致二维码过于复杂
2. 尺寸选择
// ✅ 推荐: 根据使用场景选择合适尺寸
<QRCode
value={content}
size={200} // 中等尺寸适合大多数场景
/>
// ❌ 避免: 尺寸过大或过小
3. 颜色对比
// ✅ 推荐: 使用高对比度颜色
<QRCode
value={content}
color="#000000"
backgroundColor="#FFFFFF"
/>
// ❌ 避免: 颜色对比度不足
4. 错误纠正
// ✅ 推荐: 适当的错误纠正级别
<QRCode
value={content}
size={200}
ecl="M" // 中等错误纠正
/>
5. HarmonyOS 特殊处理
在 HarmonyOS 上,需要注意:
- 依赖: 确保已安装 react-native-svg
- 性能: SVG 渲染性能良好
- 兼容性: 所有功能完全支持
6. 最佳实践
// ✅ 推荐: 封装二维码组件
interface QRCodeProps {
value: string;
size?: number;
color?: string;
backgroundColor?: string;
}
const CustomQRCode: React.FC<QRCodeProps> = ({
value,
size = 200,
color = '#000000',
backgroundColor = '#FFFFFF',
}) => {
if (!value) {
return <View style={styles.placeholder} />;
}
return (
<QRCode
value={value}
size={size}
color={color}
backgroundColor={backgroundColor}
/>
);
};
🧪 测试验证
1. Android 平台测试
npm run android
测试要点:
- 测试二维码生成
- 验证颜色正确
- 测试尺寸调整
- 检查扫描识别
2. iOS 平台测试
npm run ios
测试要点:
- 测试二维码质量
- 验证渲染效果
- 测试不同尺寸
- 检查扫描兼容性
3. HarmonyOS 平台测试
npm run harmony
测试要点:
- 验证二维码渲染
- 测试颜色显示
- 检查扫描功能
- 验证样式一致性
4. 常见问题排查
问题 1: 二维码不显示
- 检查 value 是否为空
- 确认 size 设置正确
- 验证颜色设置
问题 2: 扫描识别率低
- 检查二维码尺寸是否合适
- 验证颜色对比度
- 确认内容长度适中
问题 3: 报错 TextEncoder 不存在
解决方案：
这是 react-native-qrcode-svg 库的已知问题，需要在项目根目录添加 polyfill：
- 在项目根目录创建
polyfills.js文件：
// polyfills.js
if (typeof TextEncoder === 'undefined') {
global.TextEncoder = require('text-encoding').TextEncoder;
global.TextDecoder = require('text-encoding').TextDecoder;
}
- 在
index.js或App.tsx顶部导入：
import './polyfills';
- 安装依赖：
npm install text-encoding
或者直接升级到 v6.2.0+ 版本，该版本已修复此问题。
📊 API 参考
QRCode 组件属性
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
| value | string | 是 | 二维码内容 |
| size | number | 否 | 二维码尺寸,默认 100 |
| color | string | 否 | 二维码颜色,默认 #000000 |
| backgroundColor | string | 否 | 背景颜色,默认 #FFFFFF |
| ecl | string | 否 | 错误纠正级别 (L/M/Q/H),默认 M |
| logo | string | 否 | Logo 图片 URL |
| logoSize | number | 否 | Logo 尺寸 |
| logoBackgroundColor | string | 否 | Logo 背景颜色 |
| logoMargin | number | 否 | Logo 边距 |
| quietZone | number | 否 | 安静区域大小 |
📊 对比：二维码方案对比
| 特性 | react-native-qrcode-svg | react-native-qrcode | react-native-qrcode-scanner |
|---|---|---|---|
| 渲染方式 | SVG | Canvas | 相机扫描 |
| 质量 | ✅ 高质量 | ⚠️ 一般 | N/A |
| 自定义颜色 | ✅ 支持 | ✅ 支持 | N/A |
| 轻量级 | ✅ 轻量 | ⚠️ 较重 | N/A |
| 鸿蒙兼容性 | ✅ 完全兼容 | ⚠️ 需适配 | ⚠️ 需适配 |
| 易用性 | ✅ 简单 | ✅ 简单 | ✅ 简单 |
📝 总结
通过集成 react-native-qrcode-svg,我们为项目添加了高质量的二维码生成功能。这个库支持自定义颜色、大小、背景色等参数,完全跨平台兼容,依赖 react-native-svg,是二维码生成的绝佳选择。
关键要点回顾
- ✅ 安装依赖:
npm install react-native-qrcode-svg@6.2.0(0.72) 或react-native-qrcode-svg@6.3.20(0.77) - ✅ 配置平台: 依赖 react-native-svg,确保已安装
- ✅ 集成代码: 使用 QRCode 组件,配置 value、size、color 等参数
- ✅ 支持功能: 自定义颜色、自定义大小、自定义背景色、SVG 渲染
- ✅ 重要: 控制内容长度,使用合适的尺寸和颜色对比度
实际效果
- Android: 高质量的二维码渲染
- iOS: 优秀的二维码效果
- HarmonyOS: 一致的二维码体验
遗留问题
- 无遗留问题,功能完整支持
希望这篇教程能帮助你顺利集成 react-native-qrcode-svg,构建出色的二维码生成体验!
