1. 内容整体设计与思路拆解
1.1 这一课到底在解决什么问题
第9课的核心是“碰一碰配网”。我先说说为什么我对这节课这么看重。做智能硬件场景的开发者应该都遇到过这个尴尬:一个不带屏幕、没有键盘的IoT设备(智能灯、摄像头、插座、白电),要让它连上家里的Wi-Fi,最常见的方案是让手机开热点、设备搜热点、手机再切回路由器……这套流程在客户那边演示一次,基本能把耐心耗光。二维码配网虽然比热点好一些,但摄像头对准暗光环境下的屏幕经常对焦失败,而且二维码图片一旦被转发,配网信息就泄露了。
NFC解决的是“操作路径”问题。手机NFC功能区贴近设备标贴,读到一个几十字节的NDEF消息,应用解析出Wi-Fi账号密码或一次性token,自动发起连接。整个过程不需要输入、不需要扫码、不需要用户理解任何技术细节。在HarmonyOS Next里实现这件事,核心就两块:一是NFC标签的读写能力,二是Wi-Fi连接能力,把两者串起来,就是一套标准的智能配网链路。
我拿这套方案给智能家居项目做过原型,演示效果比蓝牙配网稳定得多,因为蓝牙配网要做广播扫描、GATT连接、服务发现,链路长,出问题的环节多;NFC是一次性接触,读取成功率极高,只要标签和天线没坏,基本不会出现“搜不到设备”这种问题。
1.2 方案选型:为什么是NFC而不是蓝牙或二维码
这可能是很多人纠结的地方。我的看法是:配网方案不能只看技术,要看用户的使用场景和设备的硬件成本。
蓝牙配网的缺点是,手机需要靠近设备做扫描,用户在App里点“添加设备”后,界面会一直停在“搜索中”,如果设备没有正确进入配网模式,搜索超时要等十几秒。NFC配网是“确定性”的:你贴上去,读到了就是读到了,没读到立刻报错,没有玄学。
二维码配网的问题是,依赖手机摄像头,光线不好、屏幕贴膜反光时容易失败;另外二维码是个“可复制资产”,别人拍一张照就能拿到Wi-Fi信息。NFC标签虽然也可以被读,但至少需要物理贴近,攻击面小很多;而且NFC标签支持改写,配网完成后应用可以把标签内容覆盖为空,相当于“使用一次后作废”。
从HarmonyOS Next的开发角度来说,NFC标签能力的调用链很短:注册标签发现回调、解析NDEF消息、拿到载荷数据。Wi-Fi连接能力在API里也有现成接口。两件事都不需要引入第三方SDK,这对我这种不喜欢给工程增加依赖的人非常友好。
1.3 这节课的学习路径
我把整个实现拆成四步:
- 理解NFC的底层原理,知道NFC设备“碰一下”之后系统层发生了什么。
- 准备开发环境,处理真机调试和权限问题。
- 实现NFC标签的读取和解析,把标签里的NDEF消息转成业务数据。
- 联动Wi-Fi管理能力,完成从“碰一下”到“连上网”的完整闭环,最后再给一套问题排查清单。
每一个环节我都会把“为什么”讲透,而不只是贴一段代码。因为NFC系统回调触发时机、标签格式兼容性、Wi-Fi连接状态的异步处理,这些才是真正会在项目里卡住你的地方。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. NFC技术原理与HarmonyOS Next的适配机制
2.1 NFC基本原理:13.56MHz的近距离通信
NFC本质上就是RFID技术的一种,工作在13.56MHz频率,通信距离通常在10厘米以内。这个“近”是它的核心优势:天然适合“贴一贴”这种语义。NFC有三种工作模式,配网方案里主要用到的是读写模式——手机作为读卡器(Reader/Writer),主动去读NFC标签里的数据。另外两种模式是卡模拟(手机当作一张卡去刷闸机)和点对点(两台设备直接传数据),后面用到再单独讲。
一个NFC标签内部其实就是一个存储芯片加一个天线线圈。芯片里的存储区按照不同协议有不同的组织结构。大家常听到的Mifare Classic 1K,里面有16个扇区,每个扇区4个块,每块16字节,总容量1024字节。但对于应用层开发来说,直接跟扇区和块打交道的时候很少,因为系统通常会把标签按NDEF格式解析。
NDEF是NFC Forum定义的标准数据格式。你可以把NDEF消息看作一个“信封”,信封里面装着一条或多条记录(Record),记录里有类型、ID、载荷。比如一条文本记录的载荷是纯字符串,一条URI记录的载荷是网址。this is what makes the tag readable across devices。
在HarmonyOS Next的开发中,系统把NDEF标签的解析封装得比较干净。你注册监听后,底层已经把标签识别成NDEF消息,不需要自己去访问扇区。只有遇到极其特殊的非NDEF标签才需要动用底层接口。说实话,我开发到现在,90%的智能配网场景都只需要NDEF,所以把NDEF吃透就够了。
2.2 HarmonyOS Next的NFC能力封装
HarmonyOS Next把NFC能力放在@kit.ConnectivityKit里。具体的使用套路是:import { nfcController, tagSession } from '@kit.ConnectivityKit';。
nfcController负责全局的NFC开关状态、标签发现事件的注册;tagSession里是标签对象相关的类型和方法,比如TagInfo、NdefTag这些。真机贴标签的时候,系统会识别出标签类型,然后回调给你一个TagInfo对象,从这个对象里可以拿到NDEF标签实例,再进一步读取消息、解析记录、甚至写入新消息。
这个设计思路是“统一发现、分类处理”:不管标签是NDEF还是Mifare,系统先给你一个统一的TagInfo,你再根据自己的需求去做类型判断。如果你的设备同时支持NFC、蓝牙、UWB,你甚至可以在同一个回调里根据技术类型分发到不同的处理逻辑,这个我在多模设备联调时用过,非常顺手。
需要注意的是,HarmonyOS是“
