解锁微信小程序NFC能力：从零实现标签读取与数据写入
1. 微信小程序NFC功能入门指南
第一次接触微信小程序的NFC功能时，我也是一头雾水。记得当时为了做一个会议签到系统，折腾了好几天才搞明白整个流程。现在回头看，其实只要掌握几个关键点，就能轻松实现NFC标签的读取和写入。
NFC（近场通信）技术在我们生活中已经很常见了，比如门禁卡、公交卡都在使用。微信小程序从基础库2.11.0版本开始支持NFC功能，这让开发者可以在小程序中实现各种有趣的近场交互场景。不过要注意的是，目前仅支持Android手机，iOS系统由于限制暂时无法使用。
要使用NFC功能，首先得确认两件事：一是用户手机是否支持NFC，二是用户是否已经开启了NFC功能。在实际开发中，我建议先做好这两项检测，否则用户遇到问题时可能会一头雾水。下面这段代码可以帮你检测设备支持情况：
// 检测设备是否支持NFC const nfc = wx.getNFCAdapter(); nfc.startDiscovery({ success(res) { console.log('NFC功能可用'); }, fail(err) { console.log('不支持NFC或未开启:', err); wx.showToast({ title: '请确认已开启NFC功能', icon: 'none' }); } });2. 实现NFC标签读取功能
2.1 初始化NFC适配器
读取NFC标签是小程序NFC功能中最基础的应用。我建议把初始化代码放在页面的onLoad生命周期里，这样页面一加载就能准备就绪。初始化过程很简单，只需要调用wx.getNFCAdapter()就能获取NFC适配器实例。
在实际项目中，我发现很多开发者容易忽略错误处理。NFC操作可能会因为各种原因失败，比如用户手机不支持、权限未开启等。好的错误处理能让你的应用更健壮，也能给用户更明确的指引。下面是我常用的初始化代码：
Page({ onLoad() { try { this.nfcAdapter = wx.getNFCAdapter(); this.startNFCListening(); } catch (error) { console.error('初始化NFC失败:', error); wx.showModal({ title: '提示', content: '您的设备不支持NFC功能', showCancel: false }); } }, startNFCListening() { this.nfcAdapter.onDiscovered(res => { console.log('发现NFC标签:', res); this.processNFCTag(res); }); this.nfcAdapter.startDiscovery({ success(res) { console.log('NFC监听已启动'); }, fail(err) { console.error('启动NFC监听失败:', err); } }); }, processNFCTag(tagData) { // 这里处理读取到的NFC标签数据 } })2.2 处理读取到的标签数据
当NFC标签靠近手机时，onDiscovered回调会被触发。这个回调返回的数据结构很重要，我刚开始时就因为不了解数据结构而踩了不少坑。返回的res对象中，messages字段包含了NDEF格式的数据，这是NFC论坛定义的标准数据格式。
在实际应用中，我们最常处理的是文本和URI类型的数据。比如会议签到系统中，可以把参会人员的ID编码到NFC标签中。下面这段代码展示了如何解析不同类型的NDEF消息：
processNFCTag(tagData) { if (!tagData.messages || tagData.messages.length === 0) { console.log('空标签或无法识别的数据格式'); return; } tagData.messages.forEach(message => { // 检查第一条记录的类型 const record = message.records[0]; if (!record) return; if (record.tnf === 1) { // TNF_WELL_KNOWN if (record.type === 'T') { // 文本类型 const text = this.decodeTextRecord(record); console.log('读取到文本:', text); } else if (record.type === 'U') { // URI类型 const uri = this.decodeURIRecord(record); console.log('读取到URI:', uri); } } }); }, decodeTextRecord(record) { // 文本记录的第一个字节包含语言编码和文本编码信息 const payload = new Uint8Array(record.payload); const textDecoder = new TextDecoder('utf-8'); return textDecoder.decode(payload.slice(3)); }, decodeURIRecord(record) { const payload = new Uint8Array(record.payload); const prefixMap = { 0x00: 'http://www.', 0x01: 'https://www.', 0x02: 'http://', 0x03: 'https://', // 其他前缀省略... }; const prefix = prefixMap[payload[0]] || ''; const rest = String.fromCharCode.apply(null, payload.slice(1)); return prefix + rest; }3. 实现NFC标签写入功能
3.1 准备要写入的数据
写入NFC标签比读取稍微复杂一些，需要先了解NDEF消息的结构。NDEF消息可以包含多条记录，每条记录都有类型、标识符、载荷等字段。微信小程序提供了writeNdefMessage方法来写入NDEF格式的数据。
在我的项目中，最常写入的是URI和文本类型的数据。比如在智能家居场景中，可以把设备控制URL写入NFC标签，用户只需用手机碰一下标签就能快速控制设备。下面是如何构造NDEF消息的示例：
createTextRecord(text) { // 文本记录需要包含语言编码和实际文本 const encoder = new TextEncoder(); const languageCode = 'en'; // 语言代码 const encodedText = encoder.encode(text); const payload = new Uint8Array(1 + languageCode.length + encodedText.length); payload[0] = languageCode.length; // 第一个字节是语言代码长度 payload.set(encoder.encode(languageCode), 1); payload.set(encodedText, 1 + languageCode.length); return { tnf: 1, // TNF_WELL_KNOWN type: 'T', // 文本类型 id: new Uint8Array(0), payload: payload.buffer }; }, createURIRecord(url) { // 识别URL前缀 let prefixCode; if (url.startsWith('https://www.')) { prefixCode = 0x01; url = url.substring(12); } else if (url.startsWith('http://www.')) { prefixCode = 0x00; url = url.substring(11); } // 其他前缀处理省略... const encoder = new TextEncoder(); const encodedURL = encoder.encode(url); const payload = new Uint8Array(1 + encodedURL.length); payload[0] = prefixCode; payload.set(encodedURL, 1); return { tnf: 1, // TNF_WELL_KNOWN type: 'U', // URI类型 id: new Uint8Array(0), payload: payload.buffer }; }3.2 执行写入操作
写入NFC标签需要几个步骤：首先监听标签发现，然后连接到标签，最后写入数据。这个过程可能会因为各种原因失败，比如标签移开太快、标签不支持写入等。在实际应用中，我建议给用户明确的反馈，告诉他们什么时候该把手机靠近标签，什么时候可以移开。
下面是一个完整的写入示例，包含了必要的错误处理和用户引导：
writeToNFCTag(content, isURL = false) { return new Promise((resolve, reject) => { this.nfcAdapter.onDiscovered(async (res) => { try { wx.showLoading({ title: '正在写入，请保持标签靠近手机', mask: true }); const ndef = this.nfcAdapter.getNdef(); await this.connectToTag(ndef); const record = isURL ? this.createURIRecord(content) : this.createTextRecord(content); const message = { records: [record] }; await this.writeTag(ndef, message); wx.hideLoading(); wx.showToast({ title: '写入成功', icon: 'success' }); resolve(); } catch (error) { wx.hideLoading(); console.error('写入失败:', error); wx.showToast({ title: '写入失败', icon: 'none' }); reject(error); } }); this.nfcAdapter.startDiscovery({ success() { wx.showToast({ title: '请将NFC标签靠近手机背面', icon: 'none', duration: 2000 }); }, fail(err) { reject(err); } }); }); }, connectToTag(ndef) { return new Promise((resolve, reject) => { ndef.connect({ success: resolve, fail: reject }); }); }, writeTag(ndef, message) { return new Promise((resolve, reject) => { ndef.writeNdefMessage({ message, success: resolve, fail: reject }); }); }4. 实战案例：会议签到系统
4.1 系统设计思路
现在让我们把这些知识应用到一个实际场景中——会议签到系统。这个系统的工作原理很简单：每个参会人员会得到一个NFC胸卡，胸卡中写入唯一的用户ID。参会者只需用手机打开小程序，靠近胸卡就能完成签到。
我在实现这个系统时，主要考虑了以下几个关键点：
- 数据安全性：NFC标签中的数据应该加密，防止伪造
- 用户体验：签到过程应该简单快速，有明确的反馈
- 错误处理：处理各种可能的异常情况，如网络问题、NFC功能不可用等
4.2 完整实现代码
下面是会议签到系统的主要代码实现。为了简洁，我省略了一些辅助函数和UI代码，专注于NFC相关的核心逻辑：
// pages/checkin/checkin.js Page({ data: { status: 'waiting', // waiting, reading, success, error userInfo: null, checkinTime: null }, onLoad() { this.initNFC(); this.checkNFCSupport(); }, initNFC() { try { this.nfcAdapter = wx.getNFCAdapter(); this.ndef = this.nfcAdapter.getNdef(); } catch (error) { this.handleError('初始化NFC失败'); } }, checkNFCSupport() { this.nfcAdapter.startDiscovery({ success: () => { this.setupNFCListeners(); }, fail: (err) => { this.handleError('NFC不可用，请确认已开启NFC功能'); } }); }, setupNFCListeners() { this.nfcAdapter.onDiscovered(async (res) => { if (this.data.status === 'reading') return; this.setData({ status: 'reading' }); try { const userId = await this.readUserIdFromTag(res); await this.reportCheckin(userId); this.setData({ status: 'success', userInfo: { name: `用户 ${userId}` }, checkinTime: new Date().toLocaleString() }); } catch (error) { this.handleError('签到失败，请重试'); } }); }, async readUserIdFromTag(tagData) { if (!tagData.messages || tagData.messages.length === 0) { throw new Error('无效的NFC标签'); } // 假设第一条记录是加密的用户ID const record = tagData.messages[0].records[0]; if (!record || record.tnf !== 1 || record.type !== 'T') { throw new Error('不支持的标签格式'); } const encryptedId = this.decodeTextRecord(record); const userId = this.decryptUserId(encryptedId); // 解密逻辑省略 return userId; }, async reportCheckin(userId) { // 调用云函数上报签到记录 return new Promise((resolve, reject) => { wx.cloud.callFunction({ name: 'checkin', data: { userId }, success: resolve, fail: reject }); }); }, handleError(message) { this.setData({ status: 'error' }); wx.showToast({ title: message, icon: 'none', duration: 2000 }); setTimeout(() => { this.setData({ status: 'waiting' }); }, 2000); } });5. 常见问题与调试技巧
5.1 常见错误排查
在实际开发中，你可能会遇到各种问题。根据我的经验，以下是一些最常见的问题和解决方法：
NFC功能不可用：首先确认手机是否支持NFC，并且已经在系统设置中开启。有些手机需要在设置中单独开启NFC功能。
无法读取标签：确保标签是可读的NDEF格式。有些标签可能是厂商锁定或特殊格式的，需要用专门的APP格式化。
写入失败：检查标签是否可写。有些标签是只读的，或者已经写保护。另外，确保标签足够靠近手机NFC天线（通常在手机背面顶部或中部）。
数据解析错误：仔细检查NDEF记录的格式。文本记录的第一个字节是语言编码长度，URI记录的第一个字节是前缀代码。
5.2 调试技巧
调试NFC功能可能会比较麻烦，因为涉及到硬件交互。以下是我总结的一些调试技巧：
使用NFC Tools等APP：在开发前，先用专业的NFC工具APP检查标签内容和格式，确保标签本身没有问题。
详细日志记录：在onDiscovered回调中打印完整的res对象，了解返回的数据结构。
模拟数据测试：先使用硬编码的模拟数据测试业务逻辑，确认非NFC部分的功能正常。
多设备测试：不同手机的NFC天线位置和性能可能不同，建议在多种设备上测试。
// 详细的日志记录示例 nfcAdapter.onDiscovered(res => { console.log('完整的NFC标签数据:', JSON.stringify(res, null, 2)); if (res.messages) { res.messages.forEach((message, i) => { console.log(`消息 ${i}:`, message); if (message.records) { message.records.forEach((record, j) => { console.log(`记录 ${j}:`, { tnf: record.tnf, type: String.fromCharCode.apply(null, record.type), id: record.id, payload: record.payload }); }); } }); } });掌握了这些技巧后，你会发现NFC开发其实并不复杂。关键是要理解NDEF数据格式，并做好错误处理。在实际项目中，我建议先实现一个简单的原型，验证核心功能后再逐步完善业务逻辑和用户体验。