NFC读卡能力 支持安卓/iOS/鸿蒙 UTS插件介绍支持Android、iOS、HarmonyOS的 NFC 读卡能力封装可用于读取卡片基础信息、NDEF 记录、透传 APDU 以及部分 Mifare 操作。适用于uni-app与uni-app xApp 平台不支持 Web 和各类小程序平台。读卡流程统一为先initNFC初始化再readCard建立卡片会话之后调用transceive、readNDEFRecords、readBlock等方法结束后调用closeNFC关闭会话。猛戳这里去插件市场看看平台支持平台支持情况Android支持iOS支持HarmonyOS支持Web不支持小程序不支持API说明方法名称参数返回说明initNFCInitNFCParams回调ResponseEntity初始化 NFC 读卡配置检查权限和设备能力readCardReadCardParams回调ResponseEntitydata为NfcTag开始轮询卡片并返回卡片信息transceiveTransceiveParams回调ResponseEntitydata为十六进制字符串与卡片进行 APDU 或原始指令透传readNDEFRecordsReadNDEFParams回调ResponseEntitydata为NdefInfo[]JSON数据读取当前卡片上的 NDEF 记录writeNDEFRecordsWriteNDEFParams回调ResponseEntity写入 NDEF 记录makeNdefReadOnlyMakeNDEFReadOnlyParams回调ResponseEntity将当前 NDEF 标签设置为只读操作不可逆authenticateSectorAuthenticateSectorParams回调ResponseEntitydata为boolean对 Mifare Classic 扇区进行 KeyA 或 KeyB 认证readSectorReadSectorParams回调ResponseEntitydata为十六进制字符串或false读取 Mifare Classic 整个扇区readBlockReadBlockParams回调ResponseEntitydata为十六进制字符串或false读取 Mifare Classic 块或 Mifare Ultralight 页writeBlockWriteBlockParams回调ResponseEntitydata为boolean写入 Mifare Classic 块或 Mifare Ultralight 页closeNFCCloseNFCParams回调ResponseEntity关闭当前 NFC 会话平台差异说明不同平台底层 NFC 能力不同部分 API 在三端的支持范围并不完全一致接入前建议先阅读本节。APIAndroidiOSHarmonyOS说明initNFC支持支持支持三端都支持初始化但底层参数映射不完全一致readCard支持支持支持三端都支持读卡与返回基础卡信息transceive支持支持支持三端都支持但不同卡型支持范围取决于系统底层能力readNDEFRecords支持支持支持当前三端实际返回的data为 JSON 字符串格式的记录列表writeNDEFRecords支持支持支持三端都支持 NDEF 写入但实际可写能力取决于卡片类型与系统支持makeNdefReadOnly支持支持支持三端都支持但是否允许设只读取决于标签本身authenticateSector支持不支持固定返回true支持iOS 无 Mifare Classic 扇区认证能力为兼容前置调用链默认返回成功readSector支持不支持支持iOS 当前未实现整扇区读取readBlock支持部分支持部分支持iOS 主要支持MiFare/ISO15693鸿蒙当前ISO15693需走transceive兜底writeBlock支持部分支持部分支持iOS 主要支持MiFare/ISO15693鸿蒙当前ISO15693需走transceive兜底closeNFC支持支持支持三端都支持关闭当前会话iOS 特别说明authenticateSector在 iOS 中不支持真实的 Mifare Classic 扇区认证。由于很多业务会把authenticateSector作为后续读写流程的前置 API为避免直接中断调用链iOS 侧当前默认返回true。readSector在 iOS 中不支持当前会直接返回失败。readBlock/writeBlock在 iOS 中并不是完整对齐 Android 的 Mifare Classic 语义主要依赖 CoreNFC 对MiFare与ISO15693的能力支持。HarmonyOS 特别说明readBlock/writeBlock当前对ISO15693没有直接暴露独立块读写封装建议通过transceive作为兜底方案。HarmonyOS 当前实现中卡片技术类型筛选依赖readIso14443A、readIso14443B、readIso18092、readIso15693的组合如果全部关闭不会自动回退为全卡型扫描。Android 特别说明androidSound、androidCheckNDEF、androidReaderModeFlags、extraReaderPresenceCheckDelay仅 Android 平台生效。readBlock/writeBlock在 Android 侧对Mifare Classic、Mifare Ultralight、ISO15693的支持相对更完整。数据结构说明ResponseEntitytypeResponseEntity{success:booleandata?:any|nullmessage?:string|null}NfcTagreadCard成功后返回的卡片信息对象常用字段如下id卡片 ID十六进制字符串type卡片类型如iso7816、mifare_classic、mifare_ultralight、iso15693、iso18092standard卡片协议标准ndefAvailable是否支持 NDEFndefTypeNDEF 标签类型ndefWritableNDEF 是否可写ndefCanMakeReadOnly是否可设置为只读mifareInfoMifare 相关信息包含容量、块大小、块数量、扇区数量等NdefInfotypeNdefInfo{identifier:stringpayload:stringtype:stringtypeNameFormat:string}字段均为十六进制字符串业务层可按需自行转为文本。快速开始1. 引入插件import*asreaderfrom/uni_modules/cz-nfc-reader2. 初始化 NFCreader.initNFC({readIso14443A:true,readIso14443B:true,readIso15693:true,readIso18092:true,completeListener(res){if(res.success){console.log(NFC 初始化成功)}else{console.log(NFC 初始化失败:${res.message})}}})3. 读卡并获取卡片信息reader.readCard({completeListener(res){if(!res.success||res.datanull){console.log(读卡失败:${res.message})return}consttagres.dataasreader.NfcTagconsole.log(卡号:${tag.id})console.log(标准:${tag.standard})console.log(类型:${tag.type})console.log(支持NDEF:${tag.ndefAvailable})}})4. 读取 NDEFreader.readCard({completeListener(card){if(!card.success||card.datanull){return}consttagcard.dataasreader.NfcTagif(tag.ndefAvailable!true){console.log(当前卡片不支持 NDEF)reader.closeNFC({})return}reader.readNDEFRecords({cached:true,completeListener(res){console.log(NDEF 结果:${res.data})reader.closeNFC({})}})}})5. APDU透传示例reader.readCard({completeListener(card){if(!card.success||card.datanull){return}reader.transceive({capdu:00A4040009A00000000386980701,completeListener(res){console.log(透传结果:${res.success}${res.data})reader.closeNFC({})}})}})常用方法说明initNFC用于初始化 NFC 能力和读卡配置。常用参数参数类型默认值说明timeoutnumber30000读卡超时时间单位毫秒iOS 无效readIso14443Abooleantrue是否启用 ISO14443AreadIso14443Bbooleantrue是否启用 ISO14443BreadIso18092booleanfalse是否启用 ISO18092/FeliCareadIso15693booleantrue是否启用 ISO15693androidSoundbooleantrueAndroid 发现标签时是否播放系统音效androidCheckNDEFbooleantrueAndroid 是否自动检查 NDEFandroidReaderModeFlags0x80 | 0x100无Android ReaderMode 附加标志extraReaderPresenceCheckDelaynumber无Android Presence Check 额外延迟iosAlertMessagestring无iOS 会话开始提示语iosMultipleTagMessagestring无iOS 多标签提示语readCard启动一次读卡轮询成功后返回NfcTag。后续如果要继续调用transceive、readNDEFRecords、writeNDEFRecords、readBlock等方法应保持当前会话不要提前关闭。transceive向当前卡片发送十六进制指令字符串并接收十六进制字符串响应。调用前必须先成功执行readCard。readNDEFRecords / writeNDEFRecords用于读取或写入 NDEF 记录参数和返回值中的identifier、payload、type均为十六进制字符串。makeNdefReadOnly将标签设置为只读该操作不可恢复调用前请确认卡片支持且业务允许。authenticateSector / readSector / readBlock / writeBlock主要用于 Mifare Classic 与部分 Mifare Ultralight 场景。authenticateSector对指定扇区认证readSector读取整个扇区readBlock读取一个块或页writeBlock写入一个块或页注意事项keyA、keyB必须是 6 字节十六进制字符串例如FFFFFFFFFFFF。Mifare Classic 单块写入数据长度必须为 16 字节。Mifare Ultralight 单页写入数据长度必须为 4 字节。closeNFC结束当前 NFC 会话。建议每次读卡、透传、读写 NDEF 或块操作完成后都调用一次避免会话残留。完整示例import*asreaderfrom/uni_modules/cz-nfc-readerexportdefault{methods:{startRead(){reader.initNFC({readIso14443A:true,readIso14443B:true,readIso15693:true,readIso18092:true,completeListener:(initRes){if(!initRes.success){uni.showModal({content:initRes.message??初始化失败,showCancel:false})return}reader.readCard({completeListener:(cardRes){if(!cardRes.success||cardRes.datanull){uni.showModal({content:cardRes.message??读卡失败,showCancel:false})return}consttagcardRes.dataasreader.NfcTagconsole.log(卡片信息:${JSON.stringify(tag)})if(tag.ndefAvailabletrue){reader.readNDEFRecords({cached:true,completeListener:(ndefRes){console.log(NDEF:${JSON.stringify(ndefRes.data)})reader.closeNFC({})}})}else{reader.closeNFC({})}}})}})}}}权限说明Android插件已包含 NFC 权限声明uses-permissionandroid:nameandroid.permission.NFC/iOS插件已包含以下配置/// Info.plist 参考配置?xml version1.0 encodingUTF-8?!DOCTYPEplistPUBLIC-//Apple//DTD PLIST 1.0//ENhttp://www.apple.com/DTDs/PropertyList-1.0.dtdplistversion1.0dictkeyNFCReaderUsageDescription/keystring需要使用NFC读取卡片信息/stringkeyUIRequiredDeviceCapabilities/keyarraystringnfc/string/arraykeycom.apple.developer.nfc.readersession.felica.systemcodes/keyarraystring88B4/string/arraykeycom.apple.developer.nfc.readersession.iso7816.select-identifiers/keyarraystringA00000000386980701/string/array/dict/plist/// UTS.entitlements 参考配置?xml version1.0 encodingUTF-8?!DOCTYPEplistPUBLIC-//Apple//DTD PLIST 1.0//ENhttp://www.apple.com/DTDs/PropertyList-1.0.dtdplistversion1.0dictkeycom.apple.developer.nfc.readersession.formats/keyarraystringTAG/stringstringNDEF/string/array/dict/plist同时已预置 FeliCa 与 ISO7816 相关会话配置。iOS 侧还需要注意以下事项插件要求iOS 13。需要在项目的UTS.entitlements中添加Near Field Communication Tag Reader Session Formats能力。需要在Info.plist中添加NFCReaderUsageDescription。根据业务需要在Info.plist中添加com.apple.developer.nfc.readersession.felica.systemcodescom.apple.developer.nfc.readersession.iso7816.select-identifiers特别注意在iOS 14.5及更早版本上如果调用轮询前启用了readIso18092或readIso15693那么必须先正确配置上面的 FeliCa / ISO7816 相关项。否则受CoreNFC已知问题影响设备 NFC 可能在重启前都不可用。如果是原生工程联调打开Runner.xcworkspace进入 Xcode 的项目设置页面在Signing Capabilities中为目标应用添加Near Field Communication Tag Reading能力。HarmonyOS插件已声明{requestPermissions:[{name:ohos.permission.NFC_TAG}]}注意事项仅支持手机真机调试不支持模拟器。使用transceive、readNDEFRecords、writeNDEFRecords、readBlock、writeBlock前必须先成功调用readCard。调用完成后建议执行closeNFC关闭会话避免影响下次读卡。makeNdefReadOnly为不可逆操作请谨慎使用。不同平台、不同卡型支持能力不同业务接入前建议先通过readCard返回的type、standard、ndefAvailable等字段进行判断。
NFC读卡能力 支持安卓/iOS/鸿蒙 UTS插件
发布时间:2026/5/19 22:53:13
NFC读卡能力 支持安卓/iOS/鸿蒙 UTS插件介绍支持Android、iOS、HarmonyOS的 NFC 读卡能力封装可用于读取卡片基础信息、NDEF 记录、透传 APDU 以及部分 Mifare 操作。适用于uni-app与uni-app xApp 平台不支持 Web 和各类小程序平台。读卡流程统一为先initNFC初始化再readCard建立卡片会话之后调用transceive、readNDEFRecords、readBlock等方法结束后调用closeNFC关闭会话。猛戳这里去插件市场看看平台支持平台支持情况Android支持iOS支持HarmonyOS支持Web不支持小程序不支持API说明方法名称参数返回说明initNFCInitNFCParams回调ResponseEntity初始化 NFC 读卡配置检查权限和设备能力readCardReadCardParams回调ResponseEntitydata为NfcTag开始轮询卡片并返回卡片信息transceiveTransceiveParams回调ResponseEntitydata为十六进制字符串与卡片进行 APDU 或原始指令透传readNDEFRecordsReadNDEFParams回调ResponseEntitydata为NdefInfo[]JSON数据读取当前卡片上的 NDEF 记录writeNDEFRecordsWriteNDEFParams回调ResponseEntity写入 NDEF 记录makeNdefReadOnlyMakeNDEFReadOnlyParams回调ResponseEntity将当前 NDEF 标签设置为只读操作不可逆authenticateSectorAuthenticateSectorParams回调ResponseEntitydata为boolean对 Mifare Classic 扇区进行 KeyA 或 KeyB 认证readSectorReadSectorParams回调ResponseEntitydata为十六进制字符串或false读取 Mifare Classic 整个扇区readBlockReadBlockParams回调ResponseEntitydata为十六进制字符串或false读取 Mifare Classic 块或 Mifare Ultralight 页writeBlockWriteBlockParams回调ResponseEntitydata为boolean写入 Mifare Classic 块或 Mifare Ultralight 页closeNFCCloseNFCParams回调ResponseEntity关闭当前 NFC 会话平台差异说明不同平台底层 NFC 能力不同部分 API 在三端的支持范围并不完全一致接入前建议先阅读本节。APIAndroidiOSHarmonyOS说明initNFC支持支持支持三端都支持初始化但底层参数映射不完全一致readCard支持支持支持三端都支持读卡与返回基础卡信息transceive支持支持支持三端都支持但不同卡型支持范围取决于系统底层能力readNDEFRecords支持支持支持当前三端实际返回的data为 JSON 字符串格式的记录列表writeNDEFRecords支持支持支持三端都支持 NDEF 写入但实际可写能力取决于卡片类型与系统支持makeNdefReadOnly支持支持支持三端都支持但是否允许设只读取决于标签本身authenticateSector支持不支持固定返回true支持iOS 无 Mifare Classic 扇区认证能力为兼容前置调用链默认返回成功readSector支持不支持支持iOS 当前未实现整扇区读取readBlock支持部分支持部分支持iOS 主要支持MiFare/ISO15693鸿蒙当前ISO15693需走transceive兜底writeBlock支持部分支持部分支持iOS 主要支持MiFare/ISO15693鸿蒙当前ISO15693需走transceive兜底closeNFC支持支持支持三端都支持关闭当前会话iOS 特别说明authenticateSector在 iOS 中不支持真实的 Mifare Classic 扇区认证。由于很多业务会把authenticateSector作为后续读写流程的前置 API为避免直接中断调用链iOS 侧当前默认返回true。readSector在 iOS 中不支持当前会直接返回失败。readBlock/writeBlock在 iOS 中并不是完整对齐 Android 的 Mifare Classic 语义主要依赖 CoreNFC 对MiFare与ISO15693的能力支持。HarmonyOS 特别说明readBlock/writeBlock当前对ISO15693没有直接暴露独立块读写封装建议通过transceive作为兜底方案。HarmonyOS 当前实现中卡片技术类型筛选依赖readIso14443A、readIso14443B、readIso18092、readIso15693的组合如果全部关闭不会自动回退为全卡型扫描。Android 特别说明androidSound、androidCheckNDEF、androidReaderModeFlags、extraReaderPresenceCheckDelay仅 Android 平台生效。readBlock/writeBlock在 Android 侧对Mifare Classic、Mifare Ultralight、ISO15693的支持相对更完整。数据结构说明ResponseEntitytypeResponseEntity{success:booleandata?:any|nullmessage?:string|null}NfcTagreadCard成功后返回的卡片信息对象常用字段如下id卡片 ID十六进制字符串type卡片类型如iso7816、mifare_classic、mifare_ultralight、iso15693、iso18092standard卡片协议标准ndefAvailable是否支持 NDEFndefTypeNDEF 标签类型ndefWritableNDEF 是否可写ndefCanMakeReadOnly是否可设置为只读mifareInfoMifare 相关信息包含容量、块大小、块数量、扇区数量等NdefInfotypeNdefInfo{identifier:stringpayload:stringtype:stringtypeNameFormat:string}字段均为十六进制字符串业务层可按需自行转为文本。快速开始1. 引入插件import*asreaderfrom/uni_modules/cz-nfc-reader2. 初始化 NFCreader.initNFC({readIso14443A:true,readIso14443B:true,readIso15693:true,readIso18092:true,completeListener(res){if(res.success){console.log(NFC 初始化成功)}else{console.log(NFC 初始化失败:${res.message})}}})3. 读卡并获取卡片信息reader.readCard({completeListener(res){if(!res.success||res.datanull){console.log(读卡失败:${res.message})return}consttagres.dataasreader.NfcTagconsole.log(卡号:${tag.id})console.log(标准:${tag.standard})console.log(类型:${tag.type})console.log(支持NDEF:${tag.ndefAvailable})}})4. 读取 NDEFreader.readCard({completeListener(card){if(!card.success||card.datanull){return}consttagcard.dataasreader.NfcTagif(tag.ndefAvailable!true){console.log(当前卡片不支持 NDEF)reader.closeNFC({})return}reader.readNDEFRecords({cached:true,completeListener(res){console.log(NDEF 结果:${res.data})reader.closeNFC({})}})}})5. APDU透传示例reader.readCard({completeListener(card){if(!card.success||card.datanull){return}reader.transceive({capdu:00A4040009A00000000386980701,completeListener(res){console.log(透传结果:${res.success}${res.data})reader.closeNFC({})}})}})常用方法说明initNFC用于初始化 NFC 能力和读卡配置。常用参数参数类型默认值说明timeoutnumber30000读卡超时时间单位毫秒iOS 无效readIso14443Abooleantrue是否启用 ISO14443AreadIso14443Bbooleantrue是否启用 ISO14443BreadIso18092booleanfalse是否启用 ISO18092/FeliCareadIso15693booleantrue是否启用 ISO15693androidSoundbooleantrueAndroid 发现标签时是否播放系统音效androidCheckNDEFbooleantrueAndroid 是否自动检查 NDEFandroidReaderModeFlags0x80 | 0x100无Android ReaderMode 附加标志extraReaderPresenceCheckDelaynumber无Android Presence Check 额外延迟iosAlertMessagestring无iOS 会话开始提示语iosMultipleTagMessagestring无iOS 多标签提示语readCard启动一次读卡轮询成功后返回NfcTag。后续如果要继续调用transceive、readNDEFRecords、writeNDEFRecords、readBlock等方法应保持当前会话不要提前关闭。transceive向当前卡片发送十六进制指令字符串并接收十六进制字符串响应。调用前必须先成功执行readCard。readNDEFRecords / writeNDEFRecords用于读取或写入 NDEF 记录参数和返回值中的identifier、payload、type均为十六进制字符串。makeNdefReadOnly将标签设置为只读该操作不可恢复调用前请确认卡片支持且业务允许。authenticateSector / readSector / readBlock / writeBlock主要用于 Mifare Classic 与部分 Mifare Ultralight 场景。authenticateSector对指定扇区认证readSector读取整个扇区readBlock读取一个块或页writeBlock写入一个块或页注意事项keyA、keyB必须是 6 字节十六进制字符串例如FFFFFFFFFFFF。Mifare Classic 单块写入数据长度必须为 16 字节。Mifare Ultralight 单页写入数据长度必须为 4 字节。closeNFC结束当前 NFC 会话。建议每次读卡、透传、读写 NDEF 或块操作完成后都调用一次避免会话残留。完整示例import*asreaderfrom/uni_modules/cz-nfc-readerexportdefault{methods:{startRead(){reader.initNFC({readIso14443A:true,readIso14443B:true,readIso15693:true,readIso18092:true,completeListener:(initRes){if(!initRes.success){uni.showModal({content:initRes.message??初始化失败,showCancel:false})return}reader.readCard({completeListener:(cardRes){if(!cardRes.success||cardRes.datanull){uni.showModal({content:cardRes.message??读卡失败,showCancel:false})return}consttagcardRes.dataasreader.NfcTagconsole.log(卡片信息:${JSON.stringify(tag)})if(tag.ndefAvailabletrue){reader.readNDEFRecords({cached:true,completeListener:(ndefRes){console.log(NDEF:${JSON.stringify(ndefRes.data)})reader.closeNFC({})}})}else{reader.closeNFC({})}}})}})}}}权限说明Android插件已包含 NFC 权限声明uses-permissionandroid:nameandroid.permission.NFC/iOS插件已包含以下配置/// Info.plist 参考配置?xml version1.0 encodingUTF-8?!DOCTYPEplistPUBLIC-//Apple//DTD PLIST 1.0//ENhttp://www.apple.com/DTDs/PropertyList-1.0.dtdplistversion1.0dictkeyNFCReaderUsageDescription/keystring需要使用NFC读取卡片信息/stringkeyUIRequiredDeviceCapabilities/keyarraystringnfc/string/arraykeycom.apple.developer.nfc.readersession.felica.systemcodes/keyarraystring88B4/string/arraykeycom.apple.developer.nfc.readersession.iso7816.select-identifiers/keyarraystringA00000000386980701/string/array/dict/plist/// UTS.entitlements 参考配置?xml version1.0 encodingUTF-8?!DOCTYPEplistPUBLIC-//Apple//DTD PLIST 1.0//ENhttp://www.apple.com/DTDs/PropertyList-1.0.dtdplistversion1.0dictkeycom.apple.developer.nfc.readersession.formats/keyarraystringTAG/stringstringNDEF/string/array/dict/plist同时已预置 FeliCa 与 ISO7816 相关会话配置。iOS 侧还需要注意以下事项插件要求iOS 13。需要在项目的UTS.entitlements中添加Near Field Communication Tag Reader Session Formats能力。需要在Info.plist中添加NFCReaderUsageDescription。根据业务需要在Info.plist中添加com.apple.developer.nfc.readersession.felica.systemcodescom.apple.developer.nfc.readersession.iso7816.select-identifiers特别注意在iOS 14.5及更早版本上如果调用轮询前启用了readIso18092或readIso15693那么必须先正确配置上面的 FeliCa / ISO7816 相关项。否则受CoreNFC已知问题影响设备 NFC 可能在重启前都不可用。如果是原生工程联调打开Runner.xcworkspace进入 Xcode 的项目设置页面在Signing Capabilities中为目标应用添加Near Field Communication Tag Reading能力。HarmonyOS插件已声明{requestPermissions:[{name:ohos.permission.NFC_TAG}]}注意事项仅支持手机真机调试不支持模拟器。使用transceive、readNDEFRecords、writeNDEFRecords、readBlock、writeBlock前必须先成功调用readCard。调用完成后建议执行closeNFC关闭会话避免影响下次读卡。makeNdefReadOnly为不可逆操作请谨慎使用。不同平台、不同卡型支持能力不同业务接入前建议先通过readCard返回的type、standard、ndefAvailable等字段进行判断。