鸿蒙实战：二维码扫码分享链路

鸿蒙实战二维码扫码分享链路前言必读图鸿蒙实战二维码扫码分享链路第 66 篇 运行效果截图HarmonyOS NEXT扫码分享是连接线上分析报告与线下社交场景的桥梁。用户在海报或纸质笔记上看到二维码 → 扫码 → 直达笔迹分析报告页面。本文讲解三个层次海报模板中的 QR 码占位设计、image.createQRImage生成二维码、以及 Scan Kit 扫码解析的完整链路。图二维码分享链路——从生成二维码到扫描跳转的完整数据流分享链接 URLimage.createQRImagePixelMap 像素图Image 组件显示用户截图/打印海报用户扫码Scan Kit 扫描scanBarcode 解析获取 URL 文本解析 reportIdpushUrl 跳转报告页一、分享链路全景┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ 分享者 │ │ 二维码载体 │ │ 接收者 │ │ │ │ │ │ │ │ PosterTemplate│──→│ 海报/屏幕/纸 │──→│ Scan Kit 扫码 │ │ · 选择主题 │ │ · QR 码图案 │ │ · 解析协议 │ │ · 生成 QR │ │ · 打印/显示 │ │ · 跳转页面 │ │ · 分享/保存 │ │ │ │ · 查看报告 │ └──────────────┘ └──────────────┘ └──────────────┘二、PosterTemplate 三主题海报设计2.1 主题系统// 文件common/components/PosterTemplate.etsexporttypePosterTemplateIdwarm|quiet|roseinterfaceThemeColors{bg:string// 背景色mark:string// 强调色引号标记accent:string// 文字强调色人格类型标签tagBg:string// 标签背景色}2.2 三套主题配色主题背景色强调色风格适用场景warm温暖AppColors.PAPER米白AppColors.WARM暖棕柔和、自然默认主题通用quiet宁静AppColors.HM_BLUE_SOFT雾蓝AppColors.QUIET靛青安静、文艺心情平和时rose玫瑰#F7E9E5粉白AppColors.ROSE玫瑰红浪漫、温柔情侣分享2.3 PosterContent 数据接口exportinterfacePosterContent{name:string// 昵称personalityType:string// 人格类型energy:number// 能量值summary:string// 一句话总结date:string// 日期}2.4 海报布局┌────────────────────────────┐ │ 鹿 LULU · 笔迹心理 2026.06│ │ │ │ “ │ │ 细腻而克制 │ │ 此刻偏向疲惫但温柔 │ │ ” │ │ │ │ ┌────────┐ │ │ │ 温和理性型 │ │ │ │ 能量 62 │ │ │ └────────┘ │ │ │ │ ┌──────┐ │ │ │ ▦ QR │ 扫码看完整解读 │ │ └──────┘ LULU · 鸿蒙生态 │ └────────────────────────────┘三、QR 码占位区域设计PosterTemplate 底部的 QR 码区域使用占位符原型阶段待真实 QR 码生成后替换// 二维码占位区域PosterTemplate.etsRow(){// QR 码占位符Stack(){Text(▦).fontSize(36).fontColor(this.getTheme().accent)}.width(54).height(54).borderRadius(AppRadius.S).backgroundColor(AppColors.CARD)// 提示文字Column(){Text(扫码看完整解读).fontSize(AppFonts.CAPTION).fontColor(AppColors.TEXT)Text(LULU · 鸿蒙生态).fontSize(AppFonts.TINY).fontColor(AppColors.TEXT_3).margin({top:2})}.alignItems(HorizontalAlign.Start).margin({left:10})}占位符到真实 QR 码的转换// 将占位符替换为真实 QR 码if(this.showQRCodethis.qrCodeBuffer){// 使用 Image 组件显示 QR 码Image(this.qrCodeBuffer).width(54).height(54).borderRadius(AppRadius.S)}else{// 未生成时显示占位符Text(▦).fontSize(36).fontColor(this.getTheme().accent)}四、QR 码生成image.createQRImage4.1 API 简介鸿蒙内置的image.createQRImage可以直接在端侧生成 QR 码无需集成第三方库import{image}fromkit.ImageKit/** * 生成二维码图片 * param content 二维码内容URL 或文本 * param size 二维码尺寸px * returns PixelMap 可直接用于 Image 组件显示或保存 */asyncfunctiongenerateQRCode(content:string,size:number200):Promiseimage.PixelMap{constqrCodeawaitimage.createQRImage({content,// 扫码内容size,// 二维码尺寸pxmargin:10,// 白边宽度pxforeground:#000000,// 前景色默认黑色background:#FFFFFF// 背景色默认白色})returnqrCode}4.2 参数详解参数类型默认值说明建议值contentstring—必填。二维码内容URL 或文本lulu://share?eidxxxsizenumber200生成图片的宽高正方形海报用 200屏幕显示用 100marginnumber10四边留白QR 标准要求10-20foregroundstring#000000二维码模块颜色黑色最稳定深色也可backgroundstring#FFFFFF背景色白色最稳定浅色也可4.3 在海报中的应用// SharePage.ets - 生成带分享内容的 QR 码privateasyncgenerateShareQR():Promisevoid{// 1. 构建分享协议constshareContentthis.buildShareLink()// 输出: lulu://share?name小李type温和理性型energy62// 2. 生成 QR 码200px 适合海报打印this.qrCodeawaitimage.createQRImage({content:shareContent,size:200,margin:10,foreground:#A88868,// 匹配海报暖色主题background:#FBF7F0// 匹配海报浅色背景})// 3. 设置到海报组件this.posterQRCodethis.qrCode}五、Scan Kit 扫码解析链路5.1 Scan Kit APIimport{scanCore}fromkit.ScanKit/** * 初始化扫码引擎并开始识别 */asyncfunctionstartScan():Promisestring{// 1. 创建扫码引擎constscanEnginescanCore.createScanEngine(getContext())// 2. 配置扫码参数constscanConfig{scanTypes:[scanCore.ScanType.QR_CODE],// 仅扫描二维码scanMode:scanCore.ScanMode.DEFAULT,isAutoZoomEnabled:true// 自动对焦}// 3. 注册扫码回调scanEngine.on(scanResult,(result:scanCore.ScanResult){constcontentresult.originalValue// 原始扫码内容console.log(扫码结果:,content)// 解析自定义协议if(content.startsWith(lulu://)){handleScanResult(content)}})// 4. 启动扫码awaitscanEngine.init(scanConfig)awaitscanEngine.start()returnscanEngine.release()}5.2 从相册图片中扫码/** * 从相册图片中识别 QR 码 * param imagePath 图片路径 */asyncfunctionscanFromImage(imagePath:string):Promisestring|null{try{// 初始化扫描引擎图片模式constscanEnginescanCore.createScanEngine(getContext())awaitscanEngine.init({scanTypes:[scanCore.ScanType.QR_CODE],scanMode:scanCore.ScanMode.IMAGE})// 从图片中识别 QR 码constresultawaitscanEngine.scanFromImage(imagePath)if(resultresult.originalValue){returnresult.originalValue}returnnull}catch(error){console.error(图片扫码失败:,JSON.stringify(error))returnnull}}5.3 协议解析与页面跳转/** * 处理扫码结果 * param content 扫码原始内容 */functionhandleScanResult(content:string):void{// 解析 lulu:// 协议if(content.startsWith(lulu://)){consturlnewURL(content)constpathurl.hostnameurl.pathname// share?name...switch(url.hostname){caseshare:// 跳转到报告查看页navigateToReport(url.searchParams)breakcasemeta:// 跳转到元服务卡片navigateToMetaService(url.searchParams)breakcasecouple:// 跳转到合盘页面navigateToCouple(url.searchParams)breakdefault:console.warn(未知协议路径:,path)}}else{// 非自定义协议按 URL 打开openInBrowser(content)}}/** * 跳转到报告页面 */functionnavigateToReport(params:URLSearchParams):void{constreportIdparseInt(params.get(id)??0)if(reportId0){AppStorage.setOrCreatenumber(current_report_id,reportId)router.pushUrl({url:pages/ReportDetailPage})}}六、完整分享链路流程分享者端 ┌──────────────────────────────────────────────┐ │ 1. 选择报告 │ │ 2. 点击分享 │ │ 3. 选择海报主题warm / quiet / rose │ │ 4. 生成 QR 码image.createQRImage │ │ 5. 保存海报 / 分享到社交平台 │ │ ╲ │ │ ╲ QR 码包含lulu://share?nametype... │ └──────────────────────────────────────────────┘ 接收者端 ┌──────────────────────────────────────────────┐ │ 1. 看到海报 QR 码 │ │ 2. 打开 Scan Kit 或系统相机扫码 │ │ 3. 扫码得到协议 URL │ │ 4. 协议解析 → 提取 reportId / archiveId │ │ 5. 跳转到报告详情页 / 元服务卡片 │ └──────────────────────────────────────────────┘七、QR 码与协议的安全设计安全维度实现方式数据量最小化QR 码仅含协议码 匿名 ID不含姓名/手机号时效性可附加时间戳服务端验证是否过期防篡改服务端参数校验非法 ID 返回错误HTTPS非自定义协议的 URL 分享使用 HTTPSQR 码内容对比❌ 不安全包含敏感信息 小李, 138xxxx1234, 温和理性型, energy62 ✅ 安全仅含匿名协议标识 lulu://share?eida1b2c3d4八、QR 码色适配不同海报主题下QR 码应使用主题色以保持视觉统一// 为不同主题设置 QR 码颜色functiongetQRColors(theme:PosterTemplateId):{foreground:string,background:string}{switch(theme){casewarm:return{foreground:#A88868,background:#FBF7F0}casequiet:return{foreground:#5B7FB6,background:#EBF0F8}caserose:return{foreground:#B88A8A,background:#F7E9E5}default:return{foreground:#000000,background:#FFFFFF}}}注意QR 码使用深色前景 浅色背景是标准做法。如果前景色过浅或背景色过深可能导致扫码失败。建议 foreground 颜色的亮度值 ≤ 50%background ≥ 80%。九、多通道分享策略汇总本项目实现的所有分享方式方式核心 API数据载体适合场景QR 码image.createQRImage图像打印/屏幕/社交平台剪贴板pasteboard.setData文本即时通讯NFC 碰一碰kit.ConnectedTagKitNDEF Tag / 手机面对面超级终端模拟实现系统推送同华为账号十、FAQ 常见问题Q1image.createQRImage 支持中文内容吗支持。content参数为 UTF-8 编码的字符串中文、英文、特殊符号均可编码。Q2生成的 QR 码如何保存为图片文件asyncfunctionsaveQRToFile(qrCode:image.PixelMap,path:string):Promisevoid{constpackerimage.createImagePacker()constpackedImageawaitpacker.packing(qrCode,{format:image/png,quality:100})// 写入文件constfilefileIo.openSync(path,fileIo.OpenMode.CREATE|fileIo.OpenMode.WRITE_ONLY)file.writeSync(packedImage.buffer)fileIo.closeSync(file)}Q3QR 码在海报上的最小建议尺寸打印场景建议 ≥ 2cm约 80px屏幕显示建议 ≥ 100px。PosterTemplate 中使用 54px 是原型阶段的占位尺寸生产环境应增大到 80-100px。Q4Scan Kit 需要额外权限吗扫码需要相机权限ohos.permission.CAMERA。如果仅从相册图片扫码scanFromImage需要ohos.permission.READ_MEDIA。十一、注意事项与常见问题11.1 开发注意事项在正式开发前建议按以下步骤完成环境准备与前置检查版本确认检查 DevEco Studio 与 SDK 版本确保满足目标 API Level 要求权限声明在module.json5的requestPermissions字段中提前声明所有需要的系统权限设备能力检查调用前验证设备是否支持目标能力相机、NFC、传感器等异步封装所有耗时操作数据库、文件 I/O、网络请求统一使用async/await处理资源释放在组件aboutToDisappear()生命周期钩子中及时释放系统资源防止内存泄漏11.2 常见错误与解决方案常见问题快速排查表问题类型排查方向参考方法应用崩溃查看 hilog 错误日志hilog.error(TAG, ..., e.message)状态丢失检查 AppStorage 键名拼写统一使用常量管理键名动画不流畅避免在 animateTo 回调中执行 I/O动画与数据操作分离总结本文完整讲解了二维码扫码分享链路的设计与实现✅PosterTemplate 三主题warm / quiet / rose 配色系统 海报布局✅QR 占位设计原型阶段的▦占位符到真实 QR 码的渐进式实现✅QR 码生成image.createQRImage的完整参数配置✅Scan Kit 扫码摄像头实时扫码 相册图片扫码双模式✅自定义协议lulu://share协议解析 页面路由跳转✅安全设计匿名协议码、时间戳、HTTPS、数据最小化✅色适配QR 前景/背景色匹配三套海报主题至此第十模块「NFC 与碰一碰分享」三篇文章全部完成从 NFC 碰一碰到剪贴板复制再到 QR 码分享——覆盖了项目中的所有短距分享能力。下一篇将进入第十一模块「主题系统与设计令牌」讲解 AppColors 颜色体系、AppFonts 字体与间距系统、以及设计令牌的工程化管理。 收藏提示如果您觉得本系列对您有帮助欢迎点赞 关注也欢迎在评论区交流鸿蒙 SDK 开发的问题相关资源Scan Kit 扫码二维码生成Camera Kit 拍照第64篇 NFC第65篇 剪贴板第78篇 CapturePage第96篇 SharePageScan Kit API 参考