更新记录

1.0.0（2026-06-22）

• 新增 NFC 标签读写 UTS 插件，提供统一会话、标签发现、NDEF、技术指令、能力矩阵和错误码契约。
• Android 接入系统 NFC 原生能力，覆盖 ReaderMode、NDEF 读写、格式化写入、NfcA/B/F/V、IsoDep、MifareClassic、MifareUltralight。
• iOS 接入 Core NFC 基础能力，覆盖标签会话、NDEF 读写、活动标签缓存、ISO7816 APDU，并对系统限制能力返回明确失败。
• HarmonyOS 增加 ohos.permission.NFC_TAG 权限声明、统一 API 入口和结构化待适配错误，不伪造成功结果。
• 新增 uni-app、uni-app x 示例和当前项目 NFC 调试页，便于打自定义基座后做真机验证。
• 新增发布守卫脚本，校验命名、接口、平台配置、示例入口、禁用词和关键原生实现文件。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-nfc-pro

lizhao-nfc-pro 是面向 uni-app / uni-app x 的 NFC 标签读写 UTS 插件，用于业务 App 读取、写入和诊断用户主动靠近设备的 NFC 标签。

功能特色

• Android 已接入系统 NFC ReaderMode、NDEF 读写、格式化写入、IsoDep、NfcA/B/F/V、Mifare Classic 和 Mifare Ultralight。
• iOS 已接入 Core NFC 会话、标签发现、NDEF 读写、ISO7816 APDU 和能力边界诊断。
• HarmonyOS 已提供权限声明、统一 API 入口和结构化能力边界，真实标签读写需在 Harmony 自定义基座和目标 SDK 环境下继续联调。
• 提供统一会话控制、标签发现监听、活动标签缓存和能力矩阵。
• 支持 NDEF 文本、URI、MIME、自定义 external、raw payload 的统一建模。
• 预留 Mifare Classic、Mifare Ultralight、IsoDep、NfcA/B/F/V 等技术类型接口。
• 所有不支持或不可用能力均返回结构化错误，不伪造成功。
• 文档和示例面向客户接入，先给最小调用，再给增强场景。

接入方式选择

支持平台

最小示例

import { getNfcStatus, startNfcSession, onTagDiscovered, readNdef } from '@/uni_modules/lizhao-nfc-pro'

// 先检查当前平台 NFC 状态，避免直接进入读写流程。
getNfcStatus({
  success(res) {
    console.log('NFC 状态', res)
  },
  fail(err) {
    console.log('NFC 状态检查失败', err)
  }
})

// iOS / HarmonyOS 需要主动开始会话；Android 可用于启用前台 reader mode。
startNfcSession({
  alertMessage: '请将 NFC 标签靠近设备感应区',
  keepSessionAlive: true,
  success(res) {
    console.log('NFC 会话已开始', res)
  }
})

// 标签事件是持续回调，页面卸载时应调用 offTagDiscovered。
onTagDiscovered((tag) => {
  console.log('发现 NFC 标签', tag.uidHex, tag.techs)

  // 读取当前活动标签的 NDEF 数据。
  readNdef({
    success(res) {
      console.log('NDEF 内容', res.records)
    }
  })
})

写入 NDEF 示例

import { buildTextRecord, buildUriRecord, writeNdef } from '@/uni_modules/lizhao-nfc-pro'

// 构造文本和 URI 记录，统一交给 writeNdef 写入当前活动标签。
const textRecord = buildTextRecord({ text: '欢迎使用 lizhao-nfc-pro', lang: 'zh-CN' })
const uriRecord = buildUriRecord({ uri: 'https://example.com' })

writeNdef({
  records: [textRecord, uriRecord],
  success(res) {
    console.log('NDEF 写入成功', res)
  },
  fail(err) {
    console.log('NDEF 写入失败', err)
  }
})

参数说明

startNfcSession(options)

说明
开始 NFC 会话或启用前台读卡模式。

支持平台
Android / iOS / HarmonyOS（HarmonyOS 基础版返回结构化待适配错误）

writeNdef(options)

说明
向当前活动标签写入 NDEF 消息。

支持平台
Android / iOS / HarmonyOS（HarmonyOS 基础版返回结构化待适配错误）

错误码

完整示例源码

自定义基座说明

本插件已经修改 Android Manifest、iOS NFC Capability / Entitlements、HarmonyOS NFC 权限声明和 App 端平台 UTS/Swift 原生能力。真机使用最新能力前，需要重新运行对应平台原生联编或重新打对应平台自定义基座；仅更新 wgt/appResource 不能替换旧基座中已编译的 App 原生部分。