更新记录

1.0.1（2026-08-28） 下载此版本

iOS和鸿蒙没经过测试

1.0.0（2026-08-28） 下载此版本

• 【新增】首版本发布
• 【新增】Android 端 NDEF 读取（基于 NfcAdapter.enableReaderMode + FLAG_READER_NFC_A/B/F/V）
• 【新增】iOS 端 NDEF 读取（基于 NFCNDEFReaderSession，自动配置 NFCReaderUsageDescription）
• 【新增】HarmonyOS 端 NFC 读取（基于 @kit.ConnectivityKit readerMode）
• 【新增】NDEF 解析：Well-Known Text / Well-Known URI（35 种前缀码）/ Absolute URI / MIME / External
• 【新增】Promise 风格 API：readNfc() / isSupported() / isEnabled() / cancelRead()
• 【新增】测试页 example/nfc-demo.uvue，含状态检查、读取按钮、日志区
• 【注意】NDEF tagId 在 iOS 端恒为空字符串（CoreNFC 限制）
• 【注意】HarmonyOS 端 readNdefFromTag 解析逻辑需按目标 SDK 版本补全

平台兼容性

uni-app x(5.0)

ff-uni-nfc

NFC 标签读取 UTS 插件，覆盖 Android / iOS / HarmonyOS 三端，基于 NDEF 协议解析文本与 URI。

平台支持

⚠️ uni-app x 内置 NFC API 仅在小程序端可用（uni.getNFCAdapter / startHCE 等），App 端需使用本插件。

安装

将 ff-uni-nfc 目录拷贝到项目 uni_modules/ 下即可，HBuilderX 会自动识别。

三端均为标准基座即可运行，无三方依赖、无需自定义基座。

基础用法

import { readNfc, isSupported, isEnabled, cancelRead, NFCError } from '@/uni_modules/ff-uni-nfc'

// 检查设备能力
if (!isSupported()) {
  uni.showToast({ title: '设备不支持 NFC' })
  return
}
if (!isEnabled()) {
  uni.showToast({ title: '请先在系统设置中开启 NFC' })
  return
}

// 读取一次
try {
  const result = await readNfc({
    timeout: 30000,
    alertMessage: '请将 NFC 标签靠近手机'
  })
  console.log('tagId:', result.tag.tagId)
  console.log('texts:', result.tag.ndefMessage?.texts)
  console.log('uris:', result.tag.ndefMessage?.uris)
  console.log('records:', result.tag.ndefMessage?.records)
} catch (e) {
  const err = e as NFCError
  console.error('读取失败', err.code, err.message)
}

API

readNfc(options?: NfcReadOptions): Promise<NfcReadResult>

启动一次 NFC 标签读取，返回 Promise。

返回值 NfcReadResult：

type NfcReadResult = {
  tag: NfcTag
  raw: UTSJSONObject  // 三端原始 JSON，用于调试或自定义解析
}

type NfcTag = {
  tagId: string                    // 标签唯一序列号（hex，大写）
  techList: string[]               // 标签支持的技术列表
  ndefMessage?: NdefMessage        // NDEF 消息（无 NDEF 的标签此字段为 undefined）
}

type NdefMessage = {
  records: NdefRecord[]            // 全部 record 的原始解析
  texts: string[]                  // 提取的纯文本（按出现顺序）
  uris: string[]                   // 提取的 URI（按出现顺序）
}

type NdefRecord = {
  tnf: number                      // Type Name Format（0..7）
  type: string                     // 类型字段（UTF-8 解码字符串）
  id: string                       // ID 字段
  payload: string                  // payload 的 UTF-8 解码字符串
  payloadType: 'text' | 'uri' | 'mime' | 'external' | 'unknown'
  rawPayloadBase64?: string        // payload 原始字节的 Base64
}

isSupported(): boolean

设备是否支持 NFC。无 NFC 硬件返回 false。

isEnabled(): boolean

NFC 是否已开启（用户在系统设置中关闭则返回 false）。

iOS / HarmonyOS 当前 API 不直接暴露 NFC 开关状态，恒等于 isSupported()。

cancelRead(): void

主动取消当前读取。建议在页面 onUnload 中调用，避免内存泄漏（特别是 iOS，必须主动 invalidate）。

错误码

所有错误以 NFCError 实例抛出，含 code 和 message 两个字段。

平台差异

Android

• 使用 NfcAdapter.enableReaderMode + 4 种 NFC flags（FLAG_READER_NFC_A/B/F/V），比 enableForegroundDispatch 更稳定。
• 支持的标签类型：NDEF 文本（RTD_TEXT）、NDEF URI（RTD_URI，含 35 种前缀码）、Absolute URI、MIME、External。
• 国产厂商（华为/小米/OPPO）的 NFC 兼容性需真机验证。
• 无系统弹窗，直接由硬件触发回调。

iOS

• 使用 NFCNDEFReaderSession，必须弹系统 UI，用户感知明显。
• 必须在 Info.plist 中声明 NFCReaderUsageDescription，否则调用即 crash（本插件已默认配置）。
• 单次 session 系统强制上限 60s；用户取消后必须重新 begin() 才能再次读取。
• CoreNFC didDetectNDEFs 回调不暴露 tag.id，tagId 字段恒为空字符串。
• 设备要求：iPhone 7+ 且 iOS 11+。

HarmonyOS

• 使用 @kit.ConnectivityKit 的 controller.on('readerMode', ...) 注册 readerMode 会话。
• NDEF API 在不同 SDK 版本差异较大（API 11 vs API 12+），真机调试时按目标 SDK 文档补全 NfcBridge.ets 中的 readNdefFromTag。
• 推荐最低支持版本：HarmonyOS 4.0+（API 11+）。

注意事项

1. 回调函数必须存为模块级变量（class 实例字段会被 JSCore / GC 释放），本插件已在 utssdk/app-*/index.uts 中严格遵守。
2. 导出给原生调用的函数必须 @UTSJS.keepAlive 标注，避免被 UTS GC 回收。
3. 页面销毁时务必调用 cancelRead()：iOS 必须主动 invalidate() 否则系统弹窗残留；Android enableReaderMode 跟随 Activity 生命周期。
4. 并发约束：同一时间只允许一个 NFC 会话；并发 readNfc 时第二个调用会自动 reject 第一个的 pending Promise（错误码 NFC_ERR_CANCELED）。
5. 超时上限：iOS 系统强制 60s；Android 推荐 ≤ 60s；HarmonyOS 无硬限制但建议 ≤ 60s。

版本历史

详见 changelog.md。