更新记录

1.0.0（2026-03-13）

• iOS 扫描主路径切到 CoreNFC NFCTagReaderSession，补齐 transceive(options) 的部分能力对齐，支持 iso_dep / mifare_ultralight / nfc_f，nfc_v 需 iOS 14+
• iOS 扫描结果开始回传 platformExtras.techDetails / platformExtras.transceiveTechnologies，并补齐会话关闭原因映射
• iOS 编译链已在 HBuilderX 4.87 + iOS Simulator 跑通，真实 NFC 验收仍需真机
• Android 新增 transceive(options)，支持 iso_dep / nfc_a / nfc_b / nfc_f / nfc_v / mifare_ultralight
• Android 扫描结果补充 platformExtras.techDetails，暴露各 technology 的基础能力信息
• Android ReaderMode 会在系统 NFC 被关闭或宿主 Activity 销毁时补发 onSessionClosed(system_interrupted)
• Android 扫描结果补充 NdefFormatable 标签的可格式化写入提示
• Android 原生回调统一切回主线程分发，减少 UTS 监听器线程不一致
• 抽出 utssdk/runtime.uts，统一 listener、session state 与 log state 管理
• 抽出 utssdk/platform-stub.uts，收敛 iOS / Harmony stub 重复代码
• Android 入口新增宿主销毁清理，避免静态 session 状态和 native callback 残留
• README 补齐导入方式、最小接入示例、iOS 进阶配置说明、完整错误码说明
• package.json 版本与权限声明同步到 Android + iOS 当前事实
• 重构公共 UTS 接口为 NFC 会话模型
• 新增统一错误码与错误对象实现
• Android 接入 ReaderMode 扫描与 NDEF text/uri 写入主路径
• iOS 接入 CoreNFC 配置文件与 Swift service 骨架
• Harmony 保持 stub only
• playground 首页改为 NFC 调试台

平台兼容性

uni-app(4.87)

uni-app x(4.87)

hans-nfc

uni-app / uni-app x NFC 插件，提供扫描、NDEF 写入和 raw transceive 能力。

平台支持

版本要求

• HBuilderX: ^4.87.0
• uni-app: ^3.0.0
• uni-app x: ^3.0.0
• Android: minSdkVersion 21
• iOS: deploymentTarget 13.0

导入

import {
  getNfcAvailability,
  onDiscovered,
  offDiscovered,
  onSessionClosed,
  offSessionClosed,
  startScan,
  stopScan,
  writeNdef,
  transceive,
  setLogEnabled
} from '@/uni_modules/hans-nfc'

快速开始

<script setup lang="uts">
import {
  NfcSessionClosedEvent,
  OnDiscoveredCallback,
  OnSessionClosedCallback,
  ScanResult,
  getNfcAvailability,
  offDiscovered,
  offSessionClosed,
  onDiscovered,
  onSessionClosed,
  setLogEnabled,
  startScan,
  stopScan,
  writeNdef
} from '@/uni_modules/hans-nfc'

const lastTag = ref<ScanResult | null>(null)

const discoveredHandler : OnDiscoveredCallback = (result : ScanResult) => {
  lastTag.value = result
  console.log('onDiscovered', JSON.stringify(result))
}

const closedHandler : OnSessionClosedCallback = (event : NfcSessionClosedEvent) => {
  console.log('onSessionClosed', JSON.stringify(event))
}

function queryAvailability() {
  getNfcAvailability({
    success: (result) => {
      console.log('availability', JSON.stringify(result))
    },
    fail: (err) => {
      console.error('availability failed', err.errCode, err.errMsg)
    }
  })
}

function beginScan() {
  startScan({
    alertMessage: '请将设备靠近 NFC 标签',
    success: () => {
      console.log('startScan success')
    },
    fail: (err) => {
      console.error('startScan failed', err.errCode, err.errMsg)
    }
  })
}

function writeText() {
  writeNdef({
    type: 'text',
    text: 'Hello NFC',
    languageCode: 'en',
    success: () => {
      console.log('writeNdef success')
    },
    fail: (err) => {
      console.error('writeNdef failed', err.errCode, err.errMsg)
    }
  })
}

onMounted(() => {
  setLogEnabled({ enabled: true })
  onDiscovered(discoveredHandler)
  onSessionClosed(closedHandler)
  queryAvailability()
})

onUnmounted(() => {
  offDiscovered(discoveredHandler)
  offSessionClosed(closedHandler)
  stopScan({})
})
</script>

推荐流程：

1. 调用 getNfcAvailability 检查设备状态。
2. 注册 onDiscovered 和 onSessionClosed。
3. 调用 startScan 开始扫描。
4. 收到标签后调用 writeNdef 或 transceive。
5. 页面销毁或业务结束时调用 stopScan 并移除监听器。

API

写入

writeNdef 当前仅支持：

• type: 'text'
• type: 'uri'

Raw Transceive

transceive(options) 只能对当前扫描会话里最近一次发现的标签调用。

支持的 technology：

说明：

• iOS 的实际可用 technology 取决于当前标签、系统版本和宿主配置。
• Android 的 timeoutMs 只对部分 technology 生效。
• iOS 保留 timeoutMs 参数，但是否生效取决于系统实现。

权限与配置

Android

插件已包含 NFC 权限和 feature 声明：

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
  <uses-permission android:name="android.permission.NFC" />
  <uses-feature
    android:name="android.hardware.nfc"
    android:required="false" />
</manifest>

iOS

最小配置：

info.plist

<key>NFCReaderUsageDescription</key>
<string>需要使用 NFC 读取和写入 NDEF 标签。</string>

UTS.entitlements

<key>com.apple.developer.nfc.readersession.formats</key>
<array>
  <string>NDEF</string>
  <string>TAG</string>
</array>

如果业务要访问 ISO7816 或 FeliCa 标签，宿主还需要补充：

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>YOUR_ISO7816_AID</string>
</array>
<key>com.apple.developer.nfc.readersession.felica.systemcodes</key>
<array>
  <string>YOUR_FELICA_SYSTEM_CODE</string>
</array>

使用限制

• iOS 写入应在发现标签后尽快调用，不要等会话结束。
• iOS 模拟器只能验证编译和页面启动，不能作为 NFC 功能验收环境。
• 使用标准基座只能验证页面和编译链；实际 NFC 联调仍需自定义基座和真机。

常见错误码

调试

• 调用 setLogEnabled({ enabled: true }) 可打开插件日志。
• 真机联调时建议同时观察原生日志。

更多说明

• 实现与设计说明见 ../../../docs/hans-nfc-implementation.md
• 历史设计与排期记录见 ../../../docs/uniappx-nfc-plugin-plan.md