更新记录

1.0.0（2026-04-13） 下载此版本

初次提交

平台兼容性

uni-app x(4.72)

laoqianjunzi-nfc

laoqianjunzi-nfc 是一个面向 uni-app / uni-app x 的多端 NFC 插件，统一提供设备能力检测、标签监听、NDEF 读写、Mifare Classic/Ultralight 读写、IsoDep APDU、NFC-V 原始指令等接口。

✨ 特性

• 🚀 统一接口：一套 API 覆盖 Android/iOS/HarmonyOS/Web/微信小程序多端
• 📱 完整能力：支持标签监听、NDEF 读写、Mifare Classic/Ultralight 操作、ISO-DEP APDU、NFC-V 原始指令
• 🔧 多端兼容：Android 端完整实现，其他平台占位兼容，保证编译通过
• 📚 异步同步并存：支持回调监听、轮询缓冲、批量读取多种使用模式
• ⚡ 性能优化：内置去重机制、标签缓存、会话管理
• 🛡️ 类型安全：完整 TypeScript 类型定义（uni-app x）

插件简介

• 统一输出一组新命名 API：便于在页面侧按同一模型调用
• Android 完整实现：提供完整的原生 UTS 实现，覆盖监听、缓存、NDEF 读写和高级卡操作
• 多端占位兼容：iOS、HarmonyOS、Web、微信小程序目录保留同名接口，避免项目编译时报错
• 灵活监听模式：页面侧既可通过回调实时接收标签，也可从缓冲区拉取最近一次或最近一批记录

📦 安装方法

方式一：通过插件市场安装（推荐）

1. 在 DCloud 插件市场 搜索 laoqianjunzi-nfc
2. 点击"使用 HBuilderX 导入插件"
3. 在 HBuilderX 中重新编译项目

方式二：手动安装

1. 下载插件包，将 laoqianjunzi-nfc 目录放置在项目的 uni_modules 目录下
2. 在 HBuilderX 中重新编译项目

版本要求

• HBuilderX 4.25.0 或更高版本
• uni-app 4.0.0 或更高版本
• uni-app x 4.0.0 或更高版本

⚙️ 权限配置

重要提示：以下权限需要在使用该插件的项目的 manifest.json 文件中进行配置，插件本身不会自动申请这些权限。

Android 平台权限配置

在使用插件的项目的 manifest.json 文件中，添加以下权限配置：

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.NFC\"/>",
          "<uses-feature android:name=\"android.hardware.nfc\" android:required=\"false\"/>"
        ]
      }
    }
  }
}

说明：

• android.permission.NFC：允许应用使用 NFC 功能
• android.hardware.nfc：声明设备需要 NFC 硬件支持（required="false" 表示非必需，如果设备没有 NFC 硬件，应用仍可安装）

iOS 平台权限配置

在使用插件的项目的 manifest.json 文件中，iOS 平台需要配置 NFC 能力：

1. 在 HBuilderX 中打开项目的 manifest.json
2. 切换到"App模块配置"标签
3. 勾选"NFC（标签读取）"能力
4. 或者在 manifest.json 的源码视图中，确保包含 NFC 相关配置

注意：iOS 的 NFC 功能需要在 Xcode 中配置 Info.plist 的 NFCReaderUsageDescription，说明使用 NFC 的原因。

HarmonyOS 平台权限配置

HarmonyOS 平台权限配置需要根据实际使用的 HarmonyOS SDK 版本进行配置。

参考配置（具体以 HarmonyOS SDK 文档为准）：

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.NFC\"/>",
          "<uses-feature android:name=\"android.hardware.nfc\" android:required=\"false\"/>"
        ]
      }
    }
  }
}

Web 和微信小程序平台

• Web 平台：浏览器 Web NFC API 尚在发展中，当前插件提供占位接口
• 微信小程序：需等待微信开放 NFC 相关能力，当前提供占位接口

快速开始示例

import {
  attachTagListener,
  beginInteractiveSession,
  checkHardwareReady,
  checkRadioReady,
  finishInteractiveSession,
  openSystemNfcPanel,
  watchTagArrival,
  writeTextPayload
} from '@/uni_modules/laoqianjunzi-nfc'

if (!checkHardwareReady()) {
  console.log('当前设备不支持 NFC')
}

attachTagListener((snapshot) => {
  console.log('标签到达', snapshot.serialHex, snapshot.ndefLines)
})

watchTagArrival({
  success: (snapshot) => {
    console.log('一次监听结果', snapshot)
  }
})

beginInteractiveSession()

writeTextPayload({
  content: 'Hello NFC'
})

finishInteractiveSession()

📱 平台支持

说明：

• ✅：已完整实现
• ✅ (占位)：接口已存在，返回占位结果
• ❌：当前平台不支持
• ❌ (待实现)：接口已预留，待后续实现

🎯 高级使用示例

1. 监听标签并读取 Mifare Classic

import {
  attachTagListener,
  readClassicZone,
  beginInteractiveSession,
  finishInteractiveSession
} from '@/uni_modules/laoqianjunzi-nfc'

// 注册标签监听器
attachTagListener((snapshot) => {
  console.log('标签到达:', snapshot.serialHex)
  console.log('支持的技术:', snapshot.techNames)

  // 如果是 Mifare Classic 标签，尝试读取扇区 0
  if (snapshot.techNames.includes('android.nfc.tech.MifareClassic')) {
    const result = readClassicZone(0, 'A', 'FFFFFFFFFFFF')
    if (result.ok) {
      console.log('扇区 0 数据:', result.payload?.blocks)
    } else {
      console.error('读取失败:', result.message)
    }
  }
})

// 开始交互会话
beginInteractiveSession()

// 在页面隐藏时结束会话
// onHide() { finishInteractiveSession() }

2. 写入结构化 NDEF 数据

import { writeStructuredNdef } from '@/uni_modules/laoqianjunzi-nfc'

// 写入包含文本和 URI 的复合 NDEF 记录
const result = writeStructuredNdef([
  { kind: 'text', value: '欢迎使用 NFC 插件' },
  { kind: 'uri', value: 'https://example.com/product' }
])

if (result.ok) {
  console.log('NDEF 写入成功，写入记录数:', result.payload?.recordCount)
} else {
  console.error('写入失败:', result.message, '错误码:', result.code)
}

3. 批量处理缓冲标签

import { 
  fetchBufferedTagBatch,
  dropBufferedTag,
  inspectLaunchRecord 
} from '@/uni_modules/laoqianjunzi-nfc'

// 获取最近 5 个标签记录（不清除缓冲）
const recentTags = fetchBufferedTagBatch(false, 5)
console.log(`最近 ${recentTags.length} 个标签:`)
recentTags.forEach((tag, index) => {
  console.log(`${index + 1}. UID: ${tag.serialHex}, 时间: ${new Date(tag.detectedAt).toLocaleString()}`)
})

// 获取最近一次标签到达时间
const lastTapTime = inspectLaunchRecord()
if (lastTapTime > 0) {
  console.log('上次标签到达:', new Date(lastTapTime).toLocaleString())
}

// 清空缓冲区
dropBufferedTag()

4. ISO-DEP APDU 通信

import { exchangeIsoDep } from '@/uni_modules/laoqianjunzi-nfc'

// 发送 SELECT APDU 命令（示例）
const selectCommand = '00A404000E315041592E5359532E4444463031'
const result = exchangeIsoDep(selectCommand)

if (result.ok) {
  console.log('APDU 响应:', result.payload?.hex)
  // 解析响应数据...
} else {
  console.error('APDU 通信失败:', result.message)
}

完整 API 说明

设备与会话

标签监听与缓冲

标签写入

标签读取与透传

返回类型

TapSnapshot 主要字段：

• serialHex：标签 UID 十六进制文本
• techNames：系统识别到的技术栈列表
• textContent：第一条可解析文本内容
• linkContent：第一条可解析 URI
• ndefLines：所有可解析 NDEF 内容
• detectedAt：检测时间戳

EnginePacket 主要字段：

• ok：是否成功
• code：0 表示成功，非 0 表示失败
• message：结果说明
• payload：附带的结构化结果

📋 错误码说明

各端注意事项

app-android

• 当前版本的核心能力集中在 Android 目录实现。
• 建议在页面 onShow 后调用 renewWatcher()，在 onHide/onUnload 中调用 finishInteractiveSession()。
• Mifare Classic 相关接口依赖正确的 A/B 密钥。

app-ios

• 当前目录保留统一 API 与占位实现，便于项目编译通过。
• 若后续需要补齐 CoreNFC，会直接复用当前接口模型。

app-harmony

• 当前目录保留统一 API 与占位实现，便于项目编译通过。
• 若后续引入 ArkTS 混编，可直接替换函数体。

mp-weixin

• 当前目录保留占位接口，不在小程序编译阶段报错。
• 若后续接入微信侧 NFC 能力，需要根据宿主实际开放情况扩展。

web

• 当前目录保留占位接口。
• 浏览器侧未接入原生 NFC 通道时，相关方法会返回不支持结果。

常见问题

1. 为什么监听没有回调？

• 先确认 checkHardwareReady() 和 checkRadioReady() 均返回 true。
• 确认 Android 工程已经声明 NFC 权限。
• 确认页面启动了 watchTagArrival() 或 beginInteractiveSession()。

2. 为什么高级读写接口提示没有活动标签？

• 高级接口依赖最近一次刚触达的标签对象。
• 标签离开感应区太久后，内部会释放活动对象，需要重新贴卡。

3. writeStructuredNdef 支持哪些记录？

• 当前实现支持 text 和 uri 两类记录。
• 其他记录类型可以在现有接口基础上继续扩展。

4. 其他平台为什么先返回占位结果？

• 本次重构首先完成统一接口与 Android 主链路，保证多端编译安全。
• iOS、HarmonyOS、Web、微信小程序目录已经保留同名函数，后续可以逐端补齐真实能力。

📖 开发文档

• UTS 语法
• UTS API插件
• UTS uni-app兼容模式组件
• UTS 标准模式组件
• Hello UTS

🎯 使用场景

• 📇 智能门禁：读取 NFC 门禁卡信息
• 🎫 票务系统：读取和验证 NFC 门票
• 🏷️ 商品标签：读取商品 NFC 标签信息
• 📱 设备配对：通过 NFC 快速配对设备
• 🔐 身份验证：NFC 卡片身份验证
• 📖 信息读取：读取 NFC 标签中的文本、URL 等信息

❓ 技术支持

如有问题或建议，请通过以下方式联系：

• 插件市场：DCloud 插件市场
• 问题反馈：在插件市场页面提交问题或建议

📄 许可证

MIT License

🙏 致谢

感谢使用 laoqianjunzi-nfc 插件！如果这个插件对您有帮助，欢迎在插件市场给予好评和反馈。