更新记录

1.2.0（2026-01-30）

新增 HarmonyOS 平台支持

1.0.0（2026-01-30）

• 新增 Android
• 新增 UTS API：
  • onTagDiscovered：前台碰卡持续回调
  • getPendingTagSync：读取后台缓存事件（可读取后清空）
  • clearPendingTag：清空缓存
  • isNfcSupported / isNfcEnabled：能力与开关判断
• 支持识别技术类型：NDEF、Mifare Classic/Ultralight、IsoDep、NfcA/B/F/V

平台兼容性

uni-app(4.66)

uni-app x(4.66)

UTS环境兼容性

hl-nfccase-uts

使用说明

本插件用于 NFC 读卡，支持 Android、iOS 和 HarmonyOS 平台。

Android 平台

• App 在前台时，通过回调实时拿到 NFC 数据
• 支持多种 NFC 技术类型（NDEF、Mifare、ISO-DEP、NFC-A/B/F/V 等）
• 支持高级操作（读块、transceive 等）

iOS 平台

• 使用 CoreNFC 框架实现多格式 NFC 标签读取
• 支持 ISO14443（MiFare、ISO7816 智能卡）和 ISO15693（NFC-V）
• 需要用户主动触发（点击按钮），不支持后台/冷启动唤醒
• 系统要求：iOS 13.0+，iPhone 7 及以上设备

HarmonyOS 平台

• 使用 @ohos.nfc.tag 和 @ohos.nfc.controller 实现 NFC 标签读取
• 支持多种 NFC 技术类型（NDEF、MiFare Classic/Ultralight、IsoDep、NFC-A/B/F/V）
• 需要调用 startNFCSession() 启动前台调度
• 系统要求：HarmonyOS 3.0+

支持的标签/技术类型

Android 平台

iOS 平台

注意：iOS 不支持 FeliCa (ISO18092)，该协议主要用于日本市场。

HarmonyOS 平台

平台差异对比

说明：默认返回“识别信息 + NDEF 文本/URI（如有）”。不默认读取 Mifare 块数据（需要密钥/认证策略，且容易因卡不同而失败）。

示例

uni-app x 调用示例（Vue 3 Composition API）

<template>
  <view class="container">
    <button @click="startScan">开始扫描 NFC</button>
    <button @click="stopScan">停止扫描</button>
    <view v-if="tagData">
      <text>UID: {{ tagData.uidHex }}</text>
      <text>NDEF: {{ tagData.ndefText || tagData.ndefUri }}</text>
    </view>
  </view>
</template>

<script setup>
import { ref } from 'vue'
import { onShow, onHide } from '@dcloudio/uni-app'
import {
  onTagDiscovered,
  startNFCSession,
  stopNFCSession,
  isNfcSupported,
  configure
} from '@/uni_modules/hl-nfccase-uts'

const tagData = ref(null)

// 启动扫描
const startScan = () => {
  // 注册回调
  onTagDiscovered((event) => {
    console.log('NFC 标签:', event)
    tagData.value = event
  })

  // iOS/HarmonyOS 需要手动启动
  // #ifdef APP-IOS || APP-HARMONY
  startNFCSession()
  // #endif
}

// 停止扫描
const stopScan = () => {
  // #ifdef APP-IOS || APP-HARMONY
  stopNFCSession()
  // #endif
}

onShow(() => {
  configure({ pendingMax: 10, dedupeMs: 600 })
})

onHide(() => {
  stopScan()
})
</script>

uni-app 调用示例（Options API）

<template>
  <view class="container">
    <button @click="startScan">开始扫描 NFC</button>
    <button @click="stopScan">停止扫描</button>
    <view v-if="tagData">
      <text>UID: {{ tagData.uidHex }}</text>
    </view>
  </view>
</template>

<script>
import {
  onTagDiscovered,
  startNFCSession,
  stopNFCSession,
  isNfcSupported,
  configure
} from '@/uni_modules/hl-nfccase-uts'

export default {
  data() {
    return {
      tagData: null
    }
  },
  onShow() {
    configure({ pendingMax: 10, dedupeMs: 600 })
  },
  onHide() {
    this.stopScan()
  },
  methods: {
    startScan() {
      // 注册回调
      onTagDiscovered((event) => {
        console.log('NFC 标签:', event)
        this.tagData = event
      })

      // iOS/HarmonyOS 需要手动启动
      // #ifdef APP-IOS || APP-HARMONY
      startNFCSession()
      // #endif
    },
    stopScan() {
      // #ifdef APP-IOS || APP-HARMONY
      stopNFCSession()
      // #endif
    }
  }
}
</script>

平台特定调用示例

1) Android 前台监听（自动）

import { onTagDiscovered } from '@/uni_modules/hl-nfccase-uts'

// Android 无需调用 startNFCSession，注册回调后自动监听
onTagDiscovered((event) => {
  console.log('NFC event:', event)
  // event.uidHex / event.techs / event.ndefText / event.ndefUri / event.extras ...
})

2) iOS/HarmonyOS 手动启动扫描

import { startNFCSession, stopNFCSession, onTagDiscovered } from '@/uni_modules/hl-nfccase-uts'

// 先注册回调
onTagDiscovered((event) => {
  console.log('NFC 标签:', event)
})

// 再启动扫描
startNFCSession()

// 页面隐藏时停止
stopNFCSession()

4) 判断 NFC 状态

import { isNfcSupported, isNfcEnabled } from '@/uni_modules/hl-nfccase-uts'

console.log('supported:', isNfcSupported())
console.log('enabled:', isNfcEnabled())

注意事项

Android 平台

• 必须制作自定义基座/重新打包：因为本插件新增了 AndroidManifest（NFC intent-filter）用于后台唤起。
• Android 12+ 要求：带 intent-filter 的 Activity 必须设置 android:exported="true"（插件已处理）。
• 后台碰卡时，系统会先启动插件内置的 NfcDispatchActivity 缓存数据，再拉起主界面；页面跳转逻辑放在前端实现（例如在 onShow 里读取 getPendingTagSync(true) 后跳转）。

iOS 平台

• 必须配置 Info.plist 权限：添加 NFCReaderUsageDescription 权限说明。
• 必须启用 NFC Capability：在 Xcode 中添加 Near Field Communication Tag Reading capability。
• 必须配置 Entitlements：添加 com.apple.developer.nfc.readersession.formats 包含 NDEF 和 TAG。
• 系统要求：iOS 13.0+ 和支持 NFC 的设备（iPhone 7+）。
• 不支持后台唤醒：必须由用户主动点击按钮启动 NFC 扫描。
• 支持多种标签：MiFare、ISO7816、ISO15693 (NFC-V)，不支持 FeliCa。
• Mifare 读写限制：不支持 Mifare Classic 直接读块/扫区（需通过 ISO7816 APDU）。

HarmonyOS 平台

• 必须配置权限：在 module.json5 中添加 ohos.permission.NFC_TAG 权限。
• 系统要求：HarmonyOS 3.0+ 和支持 NFC 的设备。
• 需要手动启动：调用 startNFCSession() 启动前台调度。
• 支持 Mifare 读写：支持 MiFare Classic/Ultralight 的读写操作。

API 参考

写入操作示例（HarmonyOS）

1) 写入 NDEF 消息

import { ndefWrite, startNFCSession, onTagDiscovered } from '@/uni_modules/hl-nfccase-uts'

// 先扫描标签
onTagDiscovered((event) => {
  console.log('标签已扫描:', event.uidHex)

  // 写入 NDEF 数据
  const res = ndefWrite([
    { type: 'text', data: 'Hello NFC' },
    { type: 'uri', data: 'https://example.com' }
  ])

  if (res.code === 0) {
    console.log('NDEF 写入成功')
  } else {
    console.error('写入失败:', res.data.error)
  }
})

startNFCSession()

2) 写入 MiFare Classic 块

import { mifareClassicWriteBlock } from '@/uni_modules/hl-nfccase-uts'

// 写入块 4（需要密钥认证）
const res = mifareClassicWriteBlock(
  4,                    // 块号
  'A',                  // 密钥类型
  'FFFFFFFFFFFF',       // 6字节密钥
  '00112233445566778899AABBCCDDEEFF'  // 16字节数据
)

if (res.code === 0) {
  console.log('写入成功')
}

3) 写入 MiFare Ultralight 页

import { mifareUltralightWritePage } from '@/uni_modules/hl-nfccase-uts'

// 写入页 4
const res = mifareUltralightWritePage(
  4,          // 页号
  '00112233'  // 4字节数据
)

if (res.code === 0) {
  console.log('写入成功')
}

返回数据结构

Android 平台

{
  "timestamp": 1769741815417,      // 时间戳
  "action": "TECH_DISCOVERED",     // 动作类型
  "uidHex": "04A1B2C3D4E5F6",      // 标签 UID
  "techs": ["NfcA", "MifareClassic", "NdefFormatable"], // 支持的技术
  "atqa": "0400",                  // ATQA（NfcA）
  "sak": "08",                     // SAK（NfcA）
  "ndef": {                        // NDEF 数据（如有）
    "records": [...],
    "text": "文本内容",
    "uri": "https://example.com"
  },
  "ndefText": "文本内容",
  "ndefUri": "https://example.com",
  "extras": {                      // 额外信息
    "mifareType": "Classic1K",
    "mifareSize": 1024
  }
}

iOS 平台

{
  "timestamp": 1769741815417,      // 时间戳
  "action": "iOS_CoreNFC_MiFare",  // 标签类型标识
  "uidHex": "53318EF7210001",      // 标签 UID
  "techs": ["MiFare", "MiFareUnknown"], // 支持的技术
  "tagType": "MiFare",             // 标签类型
  "mifareFamily": "MiFare Unknown", // MiFare 家族（仅 MiFare）
  "ndef": {                        // NDEF 数据（如有）
    "records": [...],
    "text": null,
    "uri": "https://example.com"
  },
  "ndefText": null,
  "ndefUri": "https://example.com"
}

HarmonyOS 平台

{
  "timestamp": 1769741815417,      // 时间戳
  "action": "Harmony_NFC_TAG",     // 动作类型
  "uidHex": "04A1B2C3D4E5F6",      // 标签 UID
  "techs": ["NfcA", "MifareClassic", "Ndef"], // 支持的技术
  "atqa": "0400",                  // ATQA（NfcA）
  "sak": "08",                     // SAK（NfcA）
  "tagType": "MifareClassic",      // 标签类型
  "mifareType": "Classic",         // MiFare 类型
  "ndef": {                        // NDEF 数据（如有）
    "records": [...],
    "text": "文本内容",
    "uri": "https://example.com"
  },
  "ndefText": "文本内容",
  "ndefUri": "https://example.com",
  "extras": {                      // 额外信息
    "nfcA": { "atqa": "0400", "sak": 8 },
    "mifareClassic": { "type": "Classic", "size": 1024, "sectorCount": 16, "blockCount": 64 }
  }
}