当前位置：首页 > news >正文

鸿蒙Next NFC标签读写开发指南：从基础到实战

news 2025/9/29 13:32:08

在物联网时代，NFC技术正成为鸿蒙生态中连接物理与数字世界的重要桥梁。

近场通信（NFC）技术作为一种短距离无线通信技术，在鸿蒙生态中扮演着至关重要的角色。从移动支付到智能家居控制，从门禁系统到设备配对，NFC凭借其便捷性和安全性成为鸿蒙设备互联的核心技术之一。

本文将全面介绍鸿蒙Next中NFC标签读写的开发方法，帮助开发者快速掌握这一关键技术。

NFC技术概述

NFC是一种基于RFID（射频识别）的短距离无线通信技术，工作频率为13.56MHz，通信距离一般在10cm以内。在鸿蒙系统中，NFC主要支持三种工作模式：

读卡器模式：设备作为NFC读取器，主动读写NFC标签或卡片
点对点模式：两个NFC设备之间互相交换数据
卡模拟模式：设备模拟成NFC卡片（本文重点关注读卡器模式）

开发环境配置

权限配置

在鸿蒙应用中使用NFC功能，首先需要在应用的配置文件中声明相关权限。

在module.json5中添加以下内容：

json

"module": {"reqPermissions": [{"name": "ohos.permission.NFC_TAG"}],"deviceConfig": {"reqFeatures": [{ "name": "ohos.hardware.nfc", "version": "1.0" }]}
}

设备能力检查

在代码中，需要先检查设备是否支持NFC功能，并确保NFC已开启：

javascript

import nfc from '@ohos.nfc';let nfcController = nfc.getNfcController();
let isNfcSupported = nfcController.isNfcSupported();
let isNfcEnabled = nfcController.isNfcEnabled();if (!isNfcSupported) {console.error("This device does not support NFC");return;
}if (!isNfcEnabled) {// 可以提示用户开启NFCconsole.error("NFC is not enabled");return;
}

NFC标签读取

基本读取流程

在鸿蒙系统中，读取NFC标签主要通过监听NFC事件来实现：

javascript

import nfc from '@ohos.nfc';
import tag from '@ohos.nfc.tag';export default {onInit() {this.initNfcListener();},initNfcListener() {nfc.on("tagDiscovered", (tagInfo) => {console.info('NFC Tag Discovered: ', JSON.stringify(tagInfo));this.processTag(tagInfo);});},processTag(tagInfo) {// 解析标签技术类型let techs = tagInfo.technology;for (let i = 0; i < techs.length; i++) {switch(techs[i]) {case tag.NFC_A:this.handleNfcATag(tagInfo);break;case tag.NFC_B:this.handleNfcBTag(tagInfo);break;case tag.NFC_F:this.handleNfcFTag(tagInfo);break;case tag.NFC_V:this.handleNfcVTag(tagInfo);break;default:console.warn("Unsupported NFC technology: " + techs[i]);}}},handleNfcATag(tagInfo) {let nfcA = tag.getNfcATag(tagInfo);console.info("NFC-A Tag: " + nfcA.toString());}
};

前台优先处理

如果希望应用在前台时优先处理NFC标签，可以使用前台优先模式：

javascript

import { tag } from '@kit.ConnectivityKit';
import { BusinessError } from '@kit.BasicServicesKit';async function registerForegroundDispatch() {try {await tag.registerForegroundDispatch((error: BusinessError, tagInfo: tag.TagInfo) => {if (!error) {// 处理标签console.info("Tag discovered in foreground: " + JSON.stringify(tagInfo));}},["nfcA"]  // 指定支持的技术类型);} catch (error) {console.error("Failed to register foreground dispatch: " + error);}
}// 页面不可见时取消注册
async function unregisterForegroundDispatch() {try {await tag.unregisterForegroundDispatch();} catch (error) {console.error("Failed to unregister foreground dispatch: " + error);}
}

NFC标签写入

基本写入流程

向NFC标签写入数据需要先获取标签对象，然后执行写入操作：

javascript

import nfc from '@ohos.nfc';
import tag from '@ohos.nfc.tag';async function writeNfcTag(ndefMessage) {try {let nfcController = nfc.getNfcController();// 监听标签发现nfcController.on("tagDiscovered", async (tagInfo) => {try {// 获取NDEF标签let ndefTag = tag.getNdefTag(tagInfo);// 检查标签是否可写if (!ndefTag.isNdefWritable()) {console.error("Tag is not writable");return;}// 连接标签await ndefTag.connect();// 写入数据await ndefTag.writeNdefMessage(ndefMessage);console.info("NFC Tag write success");// 断开连接await ndefTag.close();} catch (error) {console.error("Write NFC Tag Error: ", error);}});} catch (error) {console.error("NFC write setup error: ", error);}
}

NDEF消息格式

NDEF（NFC Data Exchange Format）是NFC论坛定义的标准数据格式，下面是创建NDEF消息的示例：

javascript

function createTextNdefMessage(text, locale) {// 创建文本类型的NDEF记录let textRecord = {tnf: tag.TNF_WELL_KNOWN,           // 类型名称格式rtdType: "T",                      // 记录类型定义id: new Uint8Array(0),payload: encodeTextRecord(text, locale)};return [textRecord];
}function encodeTextRecord(text, locale) {// 编码文本记录let encoder = new TextEncoder();let textBytes = encoder.encode(text);let localeBytes = encoder.encode(locale);let payload = new Uint8Array(1 + localeBytes.length + textBytes.length);payload[0] = localeBytes.length;  // 状态字节，包含语言编码长度payload.set(localeBytes, 1);payload.set(textBytes, 1 + localeBytes.length);return payload;
}// 创建URI类型的NDEF记录
function createUriNdefMessage(uri) {let uriRecord = {tnf: tag.TNF_WELL_KNOWN,rtdType: "U",id: new Uint8Array(0),payload: encodeUriRecord(uri)};return [uriRecord];
}function encodeUriRecord(uri) {let prefixMap = {"http://www.": 0x01,"https://www.": 0x02,"http://": 0x03,"https://": 0x04};let prefixCode = 0x00;let remainingUri = uri;// 检查URI前缀for (let prefix in prefixMap) {if (uri.startsWith(prefix)) {prefixCode = prefixMap[prefix];remainingUri = uri.substring(prefix.length);break;}}let encoder = new TextEncoder();let uriBytes = encoder.encode(remainingUri);let payload = new Uint8Array(1 + uriBytes.length);payload[0] = prefixCode;payload.set(uriBytes, 1);return payload;
}

高级功能与技巧

处理不同标签类型

鸿蒙系统支持多种NFC标签类型，需要针对不同类型进行处理：

javascript

import tag from '@ohos.nfc.tag';function handleNfcATag(tagInfo) {let nfcA = tag.getNfcATag(tagInfo);let atqa = nfcA.atqa;let sak = nfcA.sak;console.info(`NFC-A Tag - ATQA: ${atqa}, SAK: ${sak}`);
}function handleNfcBTag(tagInfo) {let nfcB = tag.getNfcBTag(tagInfo);let appData = nfcB.applicationData;let protInfo = nfcB.protocolInfo;console.info(`NFC-B Tag - AppData: ${appData}, ProtInfo: ${protInfo}`);
}function handleNdefTag(tagInfo) {let ndefTag = tag.getNdefTag(tagInfo);let type = ndefTag.type;let maxSize = ndefTag.maxSize;console.info(`NDEF Tag - Type: ${type}, MaxSize: ${maxSize}`);
}

错误处理与超时机制

在实际开发中，完善的错误处理和超时机制至关重要：

javascript

async function readTagWithTimeout(timeoutMs = 5000) {return new Promise((resolve, reject) => {const timeoutId = setTimeout(() => {reject(new Error("NFC read timeout"));}, timeoutMs);try {nfc.on("tagDiscovered", (tagInfo) => {clearTimeout(timeoutId);resolve(tagInfo);});} catch (error) {clearTimeout(timeoutId);reject(error);}});
}// 使用示例
async function readTagSafely() {try {let tagInfo = await readTagWithTimeout(3000);console.info("Tag read successfully: " + JSON.stringify(tagInfo));} catch (error) {console.error("Failed to read tag: " + error.message);}
}

调试与测试

常见问题排查

NFC无响应：检查设备NFC硬件是否正常，确认NFC开关已开启
权限错误：确认已在配置文件中声明所有必要权限
标签无法识别：确认标签类型是否受支持，标签是否完好
写入失败：检查标签是否可写，存储空间是否充足

日志记录

在开发过程中，详细记录日志有助于排查问题：

javascript

class NfcLogger {static logTagInfo(tagInfo) {console.info(`Tag Technology: ${tagInfo.technology}`);console.info(`Tag UID: ${this.bytesToHex(tagInfo.uid)}`);console.info(`Tag Extras: ${JSON.stringify(tagInfo.extras)}`);}static bytesToHex(bytes) {return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join(':');}static logNdefMessage(ndefMessage) {console.info(`NDEF Record Count: ${ndefMessage.length}`);ndefMessage.forEach((record, index) => {console.info(`Record ${index}: TNF=${record.tnf}, Type=${record.rtdType}`);});}
}