更新记录

1.0.5（2026-06-10） 下载此版本

• 统一返回数据格式
• type字段统一为 type1~type5 或 unknown
• results.type统一为 text/uri/mime/mifare_classic 等标准值
• data字段去除额外描述，只返回原始数据
• 更新文档说明

1.0.4（2026-05-27） 下载此版本

修复文档

1.0.3（2026-05-27） 下载此版本

修改api ,增加results,error, 删除 content

平台兼容性

uni-app(5.08)

uni-app x(5.08)

注意：iOS平台的NFC功能暂无支持计划，当前版本仅支持Android平台。

ohyes-nfc v1.0.5

一个用于uni-app的NFC读取插件，支持Android的NFC标签读取功能。

免责声明

• 源码无后门代码。
• 由第三方SDK而导致的任何损失,与作者无关。
• 使用本插件而导致的任何损失,与作者无关。
• 使用该插件即代表同意免责声明。

是否使用第三方SDK?

• 无

我有需求怎么办?

发送邮件到 sunic4@qq.com 感谢支持

功能特性

• NFC标签读取 - 支持多种NFC标签类型的读取
• 多种标签格式 - 支持NDEF、Mifare Classic、Mifare Ultralight、ISO-DEP等
• 详细信息获取 - 获取标签ID、技术列表、容量、内容等
• 空间统计 - 获取标签已用空间和剩余空间
• 只读检测 - 检测标签是否可以设为永久只读
• 多技术标准参数 - 支持NFC-A/B/F/V技术参数提取
• Smart Poster 解析 - 支持Smart Poster类型记录解析

支持的标签类型

• NDEF标签 - NFC Forum Type 1-5
• Mifare Classic - 1K/4K标签
• Mifare Ultralight - 轻量级标签
• ISO-DEP - ISO14443-4标准标签
• NFC-A/B/F/V - 各种NFC技术标准

安装

将插件导入到你的uni-app项目中：

1. 下载插件包
2. 将插件放入项目的uni_modules目录
3. 重新编译项目

权限配置

Android权限

插件会自动添加以下权限到AndroidManifest.xml：

<uses-feature android:name="android.hardware.nfc" android:required="false" />
<uses-permission android:name="android.permission.NFC" />
<uses-permission android:name="android.permission.VIBRATE" />

注意：uses-feature 的 required 属性为 false，允许无NFC硬件的设备安装应用。

使用方法

基本用法

参考示例工程：

<script setup>
import { onShow, onHide } from '@dcloudio/uni-app';
import { enableNFCRead, disableNFCRead, isNFCSupported, isNFCEnabled, onNFCListener } from '@/uni_modules/ohyes-nfc';

onHide(() => {
    disableNFCRead();
});

onShow(() => {
    if (isNFCSupported() && isNFCEnabled()) {
        enableNFCRead();
    }
});

onNFCListener((res) => {
    console.log('NFC标签信息:', res);
});
</script>

API文档

enableNFCRead()

启用NFC读取模式。启用前会自动检查NFC是否已开启，如果NFC未开启则返回false。

disableNFCRead()

停用NFC读取模式。

isNFCSupported()

检查当前设备是否支持NFC功能。

返回值：

• boolean - true表示设备支持NFC，false表示不支持

isNFCEnabled()

检查当前设备NFC功能是否已打开。

返回值：

• boolean - true表示NFC已启用，false表示NFC未启用

openNFCSettings()

跳转到系统NFC设置页面，用户可以手动打开NFC开关。

onNFCListener(callback:(res:NFCInfo)=>void)

监听NFC返回数据，全局唯一，重复调用会覆盖。

NFCInfo数据结构

读取成功后返回的NFC信息对象包含以下字段：

interface NFCInfo {
  id: string              // 标签唯一ID（十六进制）
  techList: string[]      // 支持的技术列表，如["NfcA", "Ndef", "MifareUltralight"]
  type: string            // NFC Forum标签类型：type1 | type2 | type3 | type4 | type5 | unknown（非NDEF标签为unknown）
  size: number            // 标签总容量（字节）
  usedBytes: number       // 已用空间（字节）
  freeBytes: number       // 剩余空间（字节）
  isWritable: boolean     // 是否可写
  canMakeReadOnly: boolean // 是否可以设为永久只读
  atqa: string            // ATQA值（NFC-A技术）
  sak: string             // SAK值（NFC-A技术）
  nfcBAppData: string     // NFC-B Application Data
  nfcBProtocolInfo: string // NFC-B Protocol Info
  nfcFManufacturer: string // NFC-F Manufacturer
  nfcFSystemCode: string  // NFC-F System Code
  nfcVDsfId: string       // NFC-V DsfId
  signature: string       // 签名状态（预留字段，当前返回空字符串）
  passwordProtected: boolean // 是否密码保护（预留字段，当前固定返回false）
  dataFormat: string      // 底层硬件技术格式：nfc_a | nfc_b | nfc_f | nfc_v | mifare_classic | mifare_ultralight | iso_dep | unknown
  recordCount: number     // NDEF记录数量
  results: Array<{type: string, data: string}>  // 解析后的记录列表
  error: string           // 错误信息，无错误时为空字符串
}

字段说明

• id: 标签的唯一标识符，十六进制字符串
• techList: 标签支持的NFC技术列表
• type: NFC Forum标签类型，值为 type1 ~ type5 或 unknown。仅当标签为NDEF格式时有具体类型值，非NDEF标签返回 unknown
• size: 标签总容量，单位为字节
• usedBytes: NDEF消息已占用的字节数
• freeBytes: 标签剩余可用字节数
• isWritable: 标签是否支持写入操作
• canMakeReadOnly: 标签是否可以被永久设为只读
• atqa/sak: NFC-A技术的技术参数
• nfcBAppData/nfcBProtocolInfo: NFC-B技术参数（仅NFC-B标签有值）
• nfcFManufacturer/nfcFSystemCode: NFC-F技术参数（仅NFC-F标签有值）
• nfcVDsfId: NFC-V DsfId参数（仅NFC-V标签有值）
• signature: 标签签名验证状态（预留字段，当前返回空字符串）
• passwordProtected: 是否密码保护（预留字段，当前固定返回false）
• dataFormat: 底层硬件技术格式，与 NDEF 类型无关。可选值：nfc_a、nfc_b、nfc_f、nfc_v、mifare_classic、mifare_ultralight、iso_dep、unknown。用于区分标签使用的物理层技术
• recordCount: NDEF消息中的记录数量
• results: 解析后的记录数组，每条记录包含 type 和 data 字段
• error: 读取过程中的错误信息

results 记录类型说明

NDEF标签的记录 type 字段取值：

非NDEF标签的记录 type 字段取值：

data 字段说明

• text 类型: 返回纯文本字符串
• uri 类型: 返回完整URI字符串，如 https://www.example.com
• smart_poster 类型: 返回JSON字符串，包含子记录的type和data
• mime 类型: 返回payload的十六进制字符串
• 其他NDEF类型: 返回payload的十六进制字符串或解析后的文本
• mifare_classic: 返回Block 0的十六进制数据
• mifare_ultralight: 返回Page 0的十六进制数据
• iso_dep: 返回Historical Bytes的十六进制数据

支持的内容类型

插件能够解析以下类型的NFC内容：

NDEF记录类型

• 文本记录 - 纯文本内容，支持UTF-8/UTF-16编码
• URI记录 - 网址、电话、邮箱等链接，支持36种标准URI前缀
• Smart Poster - 智能海报，包含标题、URI、动作等子记录
• MIME记录 - 多媒体内容，返回原始十六进制数据
• 外部类型 - 自定义格式，返回原始十六进制数据

非NDEF标签

• Mifare Classic - 读取Block 0数据
• Mifare Ultralight - 读取Page 0数据
• ISO-DEP - 读取Historical Bytes数据

平台支持

注意事项

1. 设备要求: 设备必须支持NFC功能
2. 权限: Android需要NFC权限
3. 距离: NFC读取需要设备与标签距离很近（通常<4cm）
4. 兼容性: 不同厂商的NFC标签可能有细微差异
5. Mifare Classic: 部分设备（如Google Pixel）不支持Mifare Classic标签

错误处理

常见错误及处理方法：

• "NFC不可用" - 检查设备是否支持NFC并已启用
• "读取超时" - 确保标签与设备距离足够近
• "标签格式不支持" - 标签可能损坏或使用了不支持的格式
• "权限被拒绝" - 检查应用是否有NFC权限

返回示例

NDEF标签示例

{
    "id": "045A5922C17480",
    "techList": ["NfcA", "MifareUltralight", "Ndef"],
    "type": "type2",
    "size": 137,
    "usedBytes": 18,
    "freeBytes": 119,
    "isWritable": true,
    "canMakeReadOnly": true,
    "atqa": "0x4400",
    "sak": "0x00",
    "nfcBAppData": "",
    "nfcBProtocolInfo": "",
    "nfcFManufacturer": "",
    "nfcFSystemCode": "",
    "nfcVDsfId": "",
    "signature": "",
    "passwordProtected": false,
    "dataFormat": "mifare_ultralight",
    "recordCount": 1,
    "results": [
        {
            "type": "text",
            "data": "Hello World"
        }
    ],
    "error": ""
}

URI记录示例

{
    "results": [
        {
            "type": "uri",
            "data": "https://www.example.com"
        }
    ],
    "type": "type2",
    "dataFormat": "mifare_ultralight",
    "recordCount": 1
}

Smart Poster记录示例

{
    "results": [
        {
            "type": "smart_poster",
            "data": "{\"uri\":\"https://www.example.com\",\"text\":\"Example Site\"}"
        }
    ],
    "type": "type2",
    "dataFormat": "mifare_ultralight",
    "recordCount": 1
}

非NDEF标签示例

{
    "id": "A1B2C3D4",
    "techList": ["NfcA", "MifareClassic"],
    "type": "unknown",
    "size": 0,
    "usedBytes": 0,
    "freeBytes": 0,
    "isWritable": false,
    "canMakeReadOnly": false,
    "atqa": "0x0400",
    "sak": "0x08",
    "nfcBAppData": "",
    "nfcBProtocolInfo": "",
    "nfcFManufacturer": "",
    "nfcFSystemCode": "",
    "nfcVDsfId": "",
    "signature": "",
    "passwordProtected": false,
    "dataFormat": "mifare_classic",
    "recordCount": 1,
    "results": [
        {
            "type": "mifare_classic",
            "data": "A1B2C3D4E5F6..."
        }
    ],
    "error": ""
}

更新日志

v1.0.5

• 优化：NFC连接资源管理，所有连接操作添加try-finally确保正确关闭
• 优化：使用AtomicBoolean替代普通布尔值，消除多线程状态竞争
• 优化：enableReaderMode添加EXTRA_READER_PRESENCE_CHECK_DELAY参数
• 优化：dataFormat字段改为返回底层硬件技术格式（nfc_a/nfc_b/nfc_f/nfc_v等），与type字段职责分离
• 新增：NDEF标签已用空间(usedBytes)和剩余空间(freeBytes)统计
• 新增：标签可永久只读检测(canMakeReadOnly)
• 新增：NFC-B技术参数提取(AppData/ProtocolInfo)
• 新增：NFC-F技术参数提取(Manufacturer/SystemCode)
• 新增：NFC-V技术参数提取(DsfId)
• 新增：Smart Poster记录类型解析
• 新增：完整URI前缀码支持（36种标准前缀）
• 修复：AndroidManifest.xml uses-feature required改为false，允许无NFC设备安装
• 修复：enableReadMode前检查NFC是否已启用

v1.0.4

• 初始版本发布