更新记录

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 标签） 上可用。调用后请将卡片或标签贴紧手机背面（一般靠近摄像头区域），默认等待 30 秒。iOS 会弹出系统 NFC 扫描页，身份证和银行卡请使用 Android 或 HarmonyOS。

权限配置

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

按 uni-app x 鸿蒙权限配置指南，在工程根目录 harmony-configs/entry/src/main/module.json5 声明。该文件会整文件覆盖编译产物，需保留 module.type 等完整模块字段。

读卡需要 ohos.permission.NFC_TAG（system_grant）。openNfc 仅跳转系统 NFC 设置，无需该权限。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

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 实现

错误码