更新记录

1.1.1（2026-10-12）

• 修复已知问题。

1.1.0（2026-09-15）

• 新增微信小程序 Android 5.0+ NFC：状态探测、UID、技术类型、NDEF 和身份证芯片类型识别
• 微信小程序暂不支持打开系统 NFC 开关和银行卡 EMV 解析
• 修复蒸汽模式编译警告

1.0.0（2026-08-29）

• 支持 Android / iOS / HarmonyOS App：getNfcState、getNfcStateSync、isNfcSupported、isNfcSupportedSync、openNfc
• 支持 readNfcCard / readIdCard / readBankCard / cancelNfcRead；readBankCard 返回品牌、明文卡号、脱敏卡号和有效期
• Android、HarmonyOS 读取 NDEF、身份证芯片和闪付卡；iOS 通过 CoreNFC 读取 NDEF 标签

平台兼容性

uni-app(4.83)

uni-app x(4.83)

其他

支持平台

读卡目前在 Android App、HarmonyOS App、iOS App（NDEF 标签） 和 微信小程序 Android 端上可用。调用后请将卡片或标签贴紧手机背面（一般靠近摄像头区域），默认等待 30 秒。iOS 会弹出系统 NFC 扫描页，身份证和银行卡请使用 Android 或 HarmonyOS App。

微信小程序限制

根据微信 NFC 官方文档，小程序 NFC：

• 仅支持 Android 系统，适用系统版本为 Android 5.0 及以上。
• 需要微信基础库 2.11.2 及以上，低版本需自行兼容。
• 支持 NFC-A、NFC-B、NFC-F、NFC-V、ISO-DEP 和 NDEF；部分 Android 手机支持 MIFARE Classic / Ultralight。
• openNfc() 不能替用户打开系统 NFC 开关。检测到错误码 13001 时会提示用户前往系统设置手动开启。
• getNfcStateSync() 返回最近一次异步探测缓存；首次调用可能为 unknown。
• 当前微信实现支持普通标签和身份证芯片类型识别，暂未实现银行卡 EMV APDU 解析。

权限配置

openNfc、readNfcCard、readIdCard、readBankCard 需要在宿主工程声明权限。Android / HarmonyOS 为系统授权，安装后生效，无运行时弹窗。iOS 读取 NDEF 标签需 NFC 能力与用途说明，系统会弹出扫描页。

Android

在项目根目录 manifest.json 的 app-android.distribute.permissions 中声明。android.hardware.nfc 设为 required=false，无 NFC 硬件的设备仍可安装。

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

• openNfc：需要 android.permission.NFC
• 读卡三个接口：额外需要 android.permission.VIBRATE（贴卡成功短震动）

HarmonyOS

插件已按 UTS 鸿蒙模块配置规范，在 utssdk/app-harmony/module.json5 中声明 ohos.permission.NFC_TAG，模块类型为 har。对应的权限用途字符串包含在插件的 utssdk/app-harmony/resources/base/element/string.json 中，随插件一起编译。

读卡需要 ohos.permission.NFC_TAG（system_grant）。openNfc 仅跳转系统 NFC 设置，无需该权限。下方为宿主工程手动配置示例；若使用 harmony-configs/entry/src/main/module.json5，该文件会整文件覆盖编译产物，需保留 module.type 等完整模块字段，示例中的 reason 文案放在 harmony-configs/entry/src/main/resources/base/element/string.json。

在 EntryAbility.skills 中声明 ohos.nfc.tag.action.TAG_FOUND 和 tag-tech/*，系统才能把 NFC 标签分发给应用。

"requestPermissions": [
  {
    "name": "ohos.permission.NFC_TAG",
    "reason": "$string:nfc_tag_permission_reason",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  }
]

{
  "actions": ["ohos.nfc.tag.action.TAG_FOUND"],
  "uris": [
    { "type": "tag-tech/NfcA" },
    { "type": "tag-tech/NfcB" },
    { "type": "tag-tech/IsoDep" },
    { "type": "tag-tech/Ndef" }
  ]
}

{
  "name": "nfc_tag_permission_reason",
  "value": "用于读取NFC标签、身份证芯片和银行卡信息"
}

iOS

getNfcState() / getNfcStateSync() 使用 CoreNFC 的 readingAvailable 判断是否支持标签读取，不能查询系统 NFC 开关。支持读取时返回 available: true, enabled: false, state: 'unknown'；不支持时返回 available: false, enabled: false, state: 'unsupported'。unknown 下的 enabled: false 不代表 NFC 已关闭。openNfc() 不会打开开关，返回 enabled: false, triggered: false。读卡请直接调用 readNfcCard()，由系统扫描会话反馈实际结果。

readNfcCard 通过 CoreNFC 读取 NDEF 文本 / 链接。插件已包含 Info.plist（NFCReaderUsageDescription）和 UTS.entitlements（NDEF / TAG）。Apple Developer 后台需为 App ID 开启 Near Field Communication Tag Reading。readIdCard / readBankCard 在 iOS 上不支持。

<key>NFCReaderUsageDescription</key>
<string>用于读取NFC标签中的文本和链接</string>

使用方法

导入

import {
  getNfcState,
  getNfcStateSync,
  isNfcSupported,
  isNfcSupportedSync,
  openNfc,
  readNfcCard,
  readIdCard,
  readBankCard,
  cancelNfcRead
} from '@/uni_modules/umi-nfc-kit'

获取 NFC 状态

同步

const nfcState = getNfcStateSync()

console.log(nfcState.available)  // 设备是否支持 NFC
console.log(nfcState.enabled)    // NFC 是否已开启
console.log(nfcState.state)      // off | on | unknown | unsupported

异步

getNfcState({
  success(res) {
    console.log(res.errMsg)   // getNfcState:ok
    console.log(res.nfcState)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)  // 9020001
  }
})

检查是否支持 NFC

同步

const supported = isNfcSupportedSync()
console.log(supported)

异步

isNfcSupported({
  success(res) {
    console.log(res.supported)
  }
})

打开 NFC

第三方应用通常不能静默强制打开 NFC。已开启则直接返回；否则 Android 10+ 会拉起系统 NFC 开关面板，更早系统跳转 NFC 设置页。HarmonyOS 三方应用无法调用 enableNfc，改为跳转系统 NFC 设置页。Android 需在 manifest.json 声明 android.permission.NFC，详见 权限配置。

openNfc({
  success(res) {
    console.log(res.actionResult.enabled)
    console.log(res.actionResult.triggered)
    console.log(res.actionResult.message)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)  // 9020007
  }
})

读取普通 NFC 卡片

返回 UID、技术列表、NDEF 文本 / 链接（若有）。适用于门禁卡、标签、NDEF 贴纸等。iOS 通过系统扫描页读取 NDEF，UID 可能为空。Android 需声明 NFC、VIBRATE；HarmonyOS 需声明 NFC_TAG；iOS 需 NFC Tag Reading 能力，详见 权限配置。

readNfcCard({
  timeout: 30000,
  success(res) {
    console.log(res.card.uid)
    console.log(res.card.kind)      // ndef | iso-dep | mifare | nfc-a ...
    console.log(res.card.techs)
    console.log(res.card.ndefText)
    console.log(res.card.ndefUri)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)  // 9020003
  }
})

识别居民身份证芯片

第二代居民身份证为 ISO 14443 Type B。本接口只识别芯片并返回 UID，不读取姓名、身份证号、照片等身份明文。明文需公安机关授权的 SAM 安全模块，普通手机 NFC 无法解密。权限要求同 readNfcCard。

readIdCard({
  timeout: 30000,
  success(res) {
    console.log(res.idCard.uid)
    console.log(res.idCard.protocol)  // iso14443-b
    console.log(res.idCard.message)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)  // 9020004
  }
})

读取闪付银行卡

通过 EMV 非接协议读取公开应用数据：品牌、AID、应用标签、明文卡号、脱敏卡号、有效期。请贴带「闪付 / QuickPass / PayWave / PayPass」标识的银行卡。权限要求同 readNfcCard。

readBankCard({
  timeout: 30000,
  success(res) {
    console.log(res.bankCard.brand)              // unionpay | visa | mastercard ...
    console.log(res.bankCard.pan)                // 明文卡号
    console.log(res.bankCard.panMasked)          // 622202******1234
    console.log(res.bankCard.expiry)             // YYMM
    console.log(res.bankCard.applicationLabel)
  },
  fail(err) {
    console.error(err.errCode, err.errMsg)  // 9020005
  }
})

取消读卡

cancelNfcRead()

页面隐藏时建议调用，避免 Reader Mode 残留。

目录结构

uni_modules/umi-nfc-kit/
├── package.json          # 插件清单
├── readme.md
├── changelog.md
└── utssdk/
    ├── interface.uts     # 对外 API 类型声明
    ├── index.d.ts        # TS 语法提示
    ├── protocol.uts      # API 名称常量
    ├── unierror.uts      # 错误码导出
    ├── common/           # 跨平台公共逻辑
    ├── app-android/      # Android 实现
    ├── app-ios/          # iOS 实现
    ├── app-harmony/      # HarmonyOS 实现
    └── mp-weixin/        # 微信小程序 Android 实现

错误码