扫一扫功能在HarmonyOS里到底怎么做从Scan Kit开发准备说起很多刚接触HarmonyOS NEXT开发的人第一个想到要做的功能就是“扫一扫”。扫码支付、扫码登录、扫码加好友——这些场景在移动端太常见了。但问题是官方文档虽然给了API介绍但真正从零开始把开发环境搭好、权限配对、集成不出错中间有不少细节容易被忽略。特别是如果你之前做过Android或者iOS的扫码开发会发现HarmonyOS的Scan Kit在设计思路上有自己的特点直接拿跨平台的思路来套容易翻车。这篇文章不会去复述文档而是聚焦一个最务实的问题Scan Kit到底是什么、能做什么、怎么把它接入到项目里。Scan Kit是什么先搞清楚它解决什么问题Scan Kit在HarmonyOS里的定位是“统一扫码服务”。它的核心能力分为四块能力说明适用场景默认界面扫码调用系统预置的扫码界面配置参数后直接使用快速集成对扫码界面没有定制要求自定义界面扫码完全自绘扫码界面控制扫描框、提示文案、闪光灯等品牌应用、定制化需求高的场景图像识码从本地图片或网络图片中识别二维码/条形码相册选图识别、截图识别码图生成生成指定内容的二维码/条形码图片分享、支付码展示它不是一个单纯的“打开相机扫一扫”的封装而是一套完整的扫码解决方案。统一体现在哪里在HarmonyOS生态里不同设备手机、平板、智慧屏、手表的相机能力和屏幕尺寸差异很大。Scan Kit把这些差异屏蔽掉了开发者只需要调用统一接口。这一点做得比较到位实际测试下来在折叠屏和普通直板机上的表现基本一致。适合的场景任何需要识别码图或者生成码图的功能。支付、登录、信息录入、分享、设备绑定。不适合的场景如果只是需要调用相机预览不需要扫码功能直接用Camera Kit更合适。Scan Kit的相机调用是内部封装的无法直接暴露预览流做二次处理。开发前准备环境说明本文基于以下环境验证DevEco Studio 版本DevEco Studio 6.1.0 及以上 HarmonyOS SDK 版本HarmonyOS 6.1.0(23) 及以上 目标设备手机HarmonyOS NEXT 真机建议直接在真机上测试。模拟器对相机的支持有限扫码功能在模拟器上容易出现预览黑屏或者无法对焦的问题。第一步AGC平台配置——这个环节容易漏Scan Kit是系统服务但开通权限需要在AppGallery ConnectAGC上操作。这一步很多人会忘记导致代码跑了半天结果返回的扫码结果全是空。操作流程登录 AppGallery Connect创建项目如果已有项目可以直接使用在项目下创建应用包名必须与你项目中的app.json5里的bundleName一致进入“API管理” - 找到“Scan Kit” - 点击“开通”开通后需要下载agconnect-services.json文件。这是AGC服务的配置标识里面包含App ID、Client ID等信息。注意这个文件必须放在AppScope/resources/rawfile目录下。放在其他地方会导致运行时SDK初始化失败。第二步配置依赖打开oh-package.json5添加Scan Kit的依赖{dependencies:{kit.ScanKit:13.0.0-rc1}}版本号请以官方最新版本为准。这里是API 13的示例。如果是API 12对应的版本需要调整。添加后执行ohpm install安装依赖。这里有个坑如果项目同时使用了其他Kit比如Camera Kit可能会出现依赖版本冲突的情况。解决方案是统一所有Kit的版本号都使用同一个API版本对应的依赖。不要混用API 12和API 13的Kit。第三步权限声明——不配上这步毫无意义扫码需要相机权限。如果是从相册选图识码还需要读存储权限。在entry/src/main/module.json5中声明{module:{requestPermissions:[{name:ohos.permission.CAMERA,reason:用于扫码识别,usedScene:{abilities:[EntryAbility],when:inuse}},{name:ohos.permission.READ_MEDIA,reason:用于从相册选择图片识码,usedScene:{abilities:[EntryAbility],when:inuse}}]}}细节说明reason字段不能随便写系统会把这个文本展示给用户看。建议写一句通顺的描述比如“扫码识别需要相机权限”会比“用于扫码”更清晰。when字段建议用inuse即应用在前台使用时才申请权限。如果设为always用户可能会更警惕影响授权通过率。相机权限是must不声明的话调用扫码接口会直接报error code: 201权限拒绝。权限的动态请求在代码里单独写一个权限请求函数不要在扫码页面里才突然弹窗。推荐在应用启动时或进入扫码页面前预先申请。第四步运行时权限申请代码示例在EntryAbility.ets的onWindowStageCreate中添加权限申请// EntryAbility.etsimport{abilityAccessCtrl,Permissions}fromkit.AbilityKit;import{BusinessError}fromkit.BasicServicesKit;asyncfunctionrequestCameraPermission():Promisevoid{constpermissions:ArrayPermissions[ohos.permission.CAMERA];constatManagerabilityAccessCtrl.createAtManager();try{// 先检查状态constgrantStatusawaitatManager.checkAccessToken({tokenId:0,permissionName:ohos.permission.CAMERA});if(grantStatusabilityAccessCtrl.GrantStatus.PERMISSION_GRANTED){// 已授权return;}// 请求授权constresultawaitatManager.requestPermissionsFromUser(permissions);if(result.authResults[0]!abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED){console.error(Camera permission denied);// 可以在这里引导用户去设置中开启}}catch(error){leterr:BusinessErrorerrorasBusinessError;console.error(Request camera permission failed:${err.message});}}这里有个设计细节checkAccessToken的tokenId参数传入0表示查询当前应用自己的权限状态。如果换成其他值可以查询其他应用的权限但实际开发中很少用到。常见问题开发准备阶段的坑问题1ohpm install 报版本冲突现象执行ohpm install时提示依赖版本不兼容。原因oh-package.json5中多个Kit引用了不同版本的公共依赖如kit.AbilityKit、ohos.graphics等。解决方案使用ohpm install --force强制安装或者手动统一各Kit的版本号。建议优先手动统一版本。问题2配置完AGC后扫码服务依然返回空结果现象调用scan方法后回调正常但返回的码内容为空。原因大概率是agconnect-services.json文件没有放到rawfile目录下或者包名不匹配。解决方案检查文件路径AppScope/resources/rawfile/agconnect-services.json。再核对AGC平台上的包名与app.json5中的bundleName是否完全一致。问题3权限弹窗不显示现象调用requestPermissionsFromUser后没有弹窗但方法直接返回授权失败。原因在module.json5中没有声明ohos.permission.CAMERA或者声明的reason字段为空。解决方案重新检查module.json5的requestPermissions配置确保name、reason、usedScene都正确填写。最佳实践权限申请放在应用启动阶段不要在扫码页面中临时申请。用户正在准备扫码时突然出现权限弹窗体验很糟糕而且一旦用户拒绝后续就没法正常扫码了。使用when: inuse而不是always降低用户对隐私权限的敏感度。扫码功能只在页面可见时使用相机inuse模式完全满足需求。从AGC下载agconnect-services.json后建议用版本控制工具检查文件内容。有些开发者会不小心把不同项目的配置文件混在一起排查起来很头疼。下一步开发准备完成后就可以开始写具体的扫码页面了。下一篇文章会详细讲默认界面扫码的实际用法包括参数配置、结果回调处理、以及常见的性能优化点。FAQQ开启扫码功能后后台被杀再次进入时会出问题吗A不会。Scan Kit 的初始化不依赖持久化状态每次调用都会重新初始化。但需要注意如果应用被杀相机资源会被系统释放重新进入时扫码页面需要重新绑定相机。Q在API 12和API 13之间配置方式有变化吗A主要变化在权限声明格式上。API 13要求reason字段必须填写有效字符串否则编译时会报 warning但不影响运行。另外AGC配置在API 13下更为严格agconnect-services.json不能缺失任何字段。Q配置完成后编译报错提示“找不到kit.ScanKit”A检查oh-package.json5中的依赖是否写对了。常见错误是写成了kit/ScanKit用斜杠代替了点。正确写法是kit.ScanKit点号。另外确认ohpm版本是否支持该依赖格式建议升级到最新版。
