更新记录

1.1.3（2026-07-22）

• 修复 HBuilderX 5.15 / 新版 Android SDK 对 Android 12 及以下 Intent.getParcelableExtra(String) 兼容分支产生的 deprecated 诊断；Android 13+ 继续使用类型安全重载，两条标签解析路径及 Foreground Dispatch 行为保持不变。
• 已通过 uni-app x Android appResource 与生成 Kotlin 检查；公开 API 和调用方式保持不变。升级后需重新原生联编或重打 Android 自定义基座。

1.1.2（2026-07-15）

• 修复 iOS 云打包时 UInt8.toString(16)、stopNfcSession() 缺少可选参数以及 NSNumber 直接传入 setTimeout 导致的三项 SwiftCompile 错误。
• 增加 iOS Swift 云编译兼容守卫，并完成 uni-app、uni-app x 双项目 appResource、生成 Swift 与实际云打包复验；公开 API 和调用方式保持不变。升级后需重新原生联编或重打 iOS 自定义基座。

1.1.1（2026-07-15）

• 修复 Android 云打包时 scanTagOnce 清理会话未显式传入可选参数，导致生成 Kotlin 报 No value passed for parameter 'options' 的问题。
• 修复 Android 一次性扫描直接注册可变可空监听器，导致生成 Kotlin 报 Smart cast ... is impossible 的问题；改用不可变非空监听器完成注册，并在终态安全清理。
• 增加 Android 云编译 Kotlin 兼容守卫，并完成 uni-app、uni-app x 双项目 appResource 与生成 Kotlin 复验；公开 API 和调用方式保持不变。升级后需重新原生联编或重打 Android 自定义基座。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-nfc-pro

lizhao-nfc-pro 是面向 uni-app 与 uni-app x 的三端 NFC 标签读写 UTS 插件。它把 Android、iOS、HarmonyOS 的标签发现、NDEF 读写和底层技术协议统一为 32 个 API，适合设备配网、资产巡检、电子标签、卡片识别、文本/链接交换及 ISO-DEP、NfcF、NfcV、Mifare 等业务。

当前文档对应插件版本：1.1.3。

如果你是第一次接入，请按“第 1 步”到“第 8 步”依次阅读；如果已经跑通读卡，可直接跳到“第 9 步：按需查询 32 个 API”。

阅读路线

第 1 步：先判断插件是否适合你的业务

适合的场景

• Android、iOS、HarmonyOS 使用平台原生 NFC 能力，不伪造成功结果。
• 统一 32 个公开 API、统一 success / fail / complete 回调与 906xxxx 错误码。
• 支持标签发现、活动标签缓存与 TTL、NDEF 读写/格式化、原始指令和 Mifare 操作。
• Android 支持 ReaderMode 与前台分发；iOS 使用 Core NFC；HarmonyOS 使用 ReaderMode 与原生技术对象。
• 支持先发起操作、后贴标签的排队流程；会话终止、标签丢失或超时会返回明确错误。
• 同时提供 uni-app 和 uni-app x 示例，业务代码只从插件根目录导入。

不适合或不能直接承诺的场景

• Web、小程序、模拟器没有本插件所需的 App 原生 NFC 技术对象，不会返回伪造成功。
• 插件用于 NFC 标签读写，不提供银行卡支付、交通卡充值、门禁卡破解或安全芯片密钥提取能力。
• UID 只能作为标签标识之一，不能单独作为门禁授权、支付或防伪凭证。
• 不同手机和标签支持的技术类型不同；购买前应先确认目标设备、目标卡片与下方能力矩阵。

第 2 步：选择接入路线

大多数项目建议先完成“标准 NDEF 读取”，确认会话、权限和标签发现链路正常，再逐步增加写入或底层协议。不要一开始就用生产卡片测试写块、格式化或未知 APDU。

第 3 步：完成接入前准备

3.1 安装与导入

1. 将完整 lizhao-nfc-pro 目录放入项目 uni_modules。
2. 使用 HBuilderX 管理和编译项目；UTS 插件不能通过 uni.requireNativePlugin 或 uni.xxx 调用。
3. 页面只能从插件根目录导入：

// 正确：从插件根目录导入公开 API。
import { getNfcStatus } from '@/uni_modules/lizhao-nfc-pro'

不要直接引用 utssdk/index.uts 或某个平台的内部文件。

3.2 准备真机与自定义基座

新增插件或更新原生实现后必须重新原生联编。仅更新 wgt、appResource 或页面资源，不能把 NFC 原生代码更新进旧基座。

3.3 先做状态检查

在显示“开始读卡”按钮前，先查询设备能力与系统状态：

import { getNfcCapabilities, getNfcStatus } from '@/uni_modules/lizhao-nfc-pro'

// 能力矩阵用于控制不同平台的业务按钮是否显示。
getNfcCapabilities({
  success: (capability: any): void => {
    console.log('是否支持 NDEF 读取：', capability.ndefRead)
  }
})

// supported 表示平台能力，nfcEnabled 表示当前系统开关状态。
getNfcStatus({
  success: (status: any): void => {
    console.log('NFC 状态：', status)
  }
})

第 4 步：5 分钟跑通第一次读卡

第一次测试建议使用普通、可重复读取的 NDEF 标签。如果页面只需要“点击一次、读取一张标签”，优先用 scanTagOnce；需要连续读卡、监听多张标签时，再使用后面的会话模式。

4.0 最短路径：一次性扫描

import { scanTagOnce } from '@/uni_modules/lizhao-nfc-pro'

// 插件只在当前没有业务会话时启动内部会话；成功、失败或超时后都会清理资源。
scanTagOnce({
  timeoutMs: 15000,
  alertMessage: '请将 NFC 标签靠近设备',
  success: (tag: any): void => {
    console.log('标签 UID：', tag.uidHex)
  },
  fail: (err: any): void => {
    console.error('一次扫描失败：', err)
  }
})

如果当前已经存在 starting / active / stopping 会话，scanTagOnce 会返回 9060015，不会停止或覆盖客户自己的业务会话。

下面的连续会话示例只做三件事：注册标签监听、启动会话、页面退出时释放会话。

4.1 uni-app 最小示例

<template>
  <view>
    <button @click="startRead">开始读卡</button>
    <button @click="stopRead">停止读卡</button>
  </view>
</template>

<script>
import {
  startNfcSession,
  stopNfcSession,
  onTagDiscovered,
  offTagDiscovered,
  readNdef
} from '@/uni_modules/lizhao-nfc-pro'

const tagListener = (tag) => {
  console.log('发现 NFC 标签', tag)
  // 标签进入活动时间窗后读取 NDEF；失败时保留标准错误对象。
  readNdef({
    success(res) {
      console.log('NDEF 读取成功', res)
    },
    fail(err) {
      console.error('NDEF 读取失败', err)
    }
  })
}

export default {
  onLoad() {
    onTagDiscovered(tagListener)
  },
  onUnload() {
    // 必须使用注册时的同一函数引用精确退订。
    offTagDiscovered(tagListener)
    stopNfcSession()
  },
  methods: {
    startRead() {
      // success 只表示会话启动，发现标签要等待 tagListener。
      startNfcSession({
        alertMessage: '请将设备靠近 NFC 标签',
        success(res) {
          console.log('NFC 会话已启动', res)
        },
        fail(err) {
          console.error('NFC 会话启动失败', err)
        },
        complete() {
          console.log('启动调用已结束')
        }
      })
    },
    stopRead() {
      stopNfcSession()
    }
  }
}
</script>

4.2 uni-app x 最小示例

<template>
  <view>
    <button @tap="startRead">开始读卡</button>
    <button @tap="stopRead">停止读卡</button>
  </view>
</template>

<script setup lang="uts">
import {
  startNfcSession,
  stopNfcSession,
  onTagDiscovered,
  offTagDiscovered,
  readNdef,
  type NfcTagInfo,
  type NfcTagListener
} from '@/uni_modules/lizhao-nfc-pro'

// 保存同一监听函数引用，页面卸载时才能精确退订。
const tagListener: NfcTagListener = (tag: NfcTagInfo): void => {
  console.log('发现 NFC 标签：' + tag.uidHex)
  readNdef({
    success: (res: any): void => {
      console.log('NDEF 读取成功', res)
    },
    fail: (err: any): void => {
      console.error('NDEF 读取失败', err)
    },
    complete: (_res: any): void => {
      console.log('NDEF 读取调用已结束')
    }
  })
}

function startRead(): void {
  startNfcSession({
    alertMessage: '请将设备靠近 NFC 标签',
    fail: (err: any): void => {
      console.error('NFC 会话启动失败', err)
    }
  })
}

function stopRead(): void {
  stopNfcSession()
}

onLoad(() => {
  onTagDiscovered(tagListener)
})

onUnload(() => {
  offTagDiscovered(tagListener)
  stopNfcSession()
})
</script>

完整示例位于：

• uni-app：uni_modules/lizhao-nfc-pro/example/uniapp/nfc.vue
• uni-app x：uni_modules/lizhao-nfc-pro/example/uniappx/index.uvue

4.3 第一次运行时应看到什么

1. startNfcSession.success 触发：表示原生会话已启动，不表示已经读到卡。
2. 标签靠近设备后，tagListener 收到 NfcTagInfo，其中 uidHex 是标签 UID，techs 是真实技术类型。
3. 标签仍在活动时间窗内时，readNdef.success 返回 records、bytesHex 等读取结果。
4. 页面退出或业务完成后，监听器和会话被释放。

第 5 步：理解会话与标签生命周期

推荐调用顺序：

页面进入
  -> configureNfc（可选）
  -> onTagDiscovered（先注册监听）
  -> startNfcSession（启动会话）
  -> 用户贴卡
  -> 标签回调内执行 NDEF 或技术指令
  -> offTagDiscovered + stopNfcSession（页面退出或业务结束）

关键规则：

1. startNfcSession.success 只代表会话启动，不代表标签已经出现。
2. 标签操作依赖当前会话和活动标签；会话已结束会返回 9060005，没有可用标签会返回 9060006。
3. 同一标签对象只在 activeTagTtlMs 时间窗内有效；超时后应重新贴卡。
4. success 与 fail 只会进入一个，complete 无论成功失败都会触发，不能把 complete 当成成功。
5. 页面卸载时必须停止会话并注销监听，避免原生会话和业务回调残留。

5.1 增强会话流程

1. 调用 configureNfc 设置 ReaderMode、去重窗口、活动标签 TTL 和等待队列上限。
2. 先注册 onTagDiscovered，再调用 startNfcSession，避免漏掉首个标签事件。
3. 标签发现回调触发后，在 activeTagTtlMs 时间窗内调用 readNdef、writeNdef 或技术指令。
4. 业务可在标签尚未贴近时先调用标签操作；Android 与 HarmonyOS 会按会话顺序等待标签，队列超过 pendingMax 返回 9060015。
5. keepSessionAlive 为 false 时只处理一次标签；插件会保留该标签到首个操作完成或 TTL 到期，随后关闭会话。
6. 页面退出时先 offTagDiscovered，再 stopNfcSession；会话关闭会取消尚未执行的操作。

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

// 配置一次读写会话：同一卡片 800ms 内去重，标签保持 30 秒。
configureNfc({
  useReaderMode: true,
  keepSessionAlive: true,
  activeTagTtlMs: 30000,
  dedupeMs: 800,
  pendingMax: 16
})

const textRecord = buildTextRecord({
  text: '设备编号：A-1001',
  lang: 'zh-CN'
})

startNfcSession({
  success: (): void => {
    // 可以等待贴卡后再执行，也可以由业务按钮提前提交到等待队列。
    writeNdef({
      records: [textRecord],
      fail: (err: any): void => {
        console.error('写入失败', err)
      }
    })
  }
})

5.2 取消还在等标签的操作

Android 与 HarmonyOS 支持“先调用、后贴卡”的等待队列。给标签操作传入稳定的 operationId 后，可在原生 I/O 开始前精确取消：

import { cancelNfcOperation, readNdef } from '@/uni_modules/lizhao-nfc-pro'

const operationId = 'asset-read-1001'

readNdef({
  operationId,
  fail: (err: any): void => console.log('读取被取消或失败', err)
})

// 只取消仍在等待队列中的同名操作；已经开始的原生读写不会被强制中断。
cancelNfcOperation({
  operationId,
  success: (result: any): void => console.log('是否取消成功', result.cancelled)
})

iOS 不维护预贴卡等待队列，因此返回 cancelled: false；这不是异常，也不会停止当前 Core NFC 会话。

第 6 步：从读取升级到 NDEF 写入

6.1 写入前先查询 NDEF 状态

import { getNdefStatus } from '@/uni_modules/lizhao-nfc-pro'

// 先确认标签已格式化且可写，再由客户主动触发 writeNdef。
getNdefStatus({
  operationId: 'check-before-write',
  success: (status: any): void => {
    console.log('是否可写：', status.writable)
    console.log('容量与当前消息：', status.capacity, status.messageSize)
  }
})

HarmonyOS 当前没有公开等价的 NDEF 容量接口，因此 capacity 返回 -1；业务只在 capacity >= 0 时做容量比较。iOS 状态查询不额外读取消息，messageSize 返回 -1。

6.2 优先使用文本和 URI 记录

普通跨平台业务优先使用 buildTextRecord、buildUriRecord 和 writeNdef，不需要自行拼接 NDEF 字节：

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

const record = buildTextRecord({
  text: '资产编号 A-1001',
  lang: 'zh-CN',
  encoding: 'utf-8'
})

// 请在标签发现后、活动标签 TTL 内写入。
writeNdef({
  records: [record],
  success: (res: any): void => {
    console.log('写入成功', res)
  },
  fail: (err: any): void => {
    console.error('写入失败', err.errCode, err.errMsg)
  }
})

6.3 writeNdef 与 formatAndWriteNdef 的区别

首次写入请使用可恢复的测试标签，并先备份原内容。不要对门禁卡、交通卡、银行卡、生产资产卡或未知标签直接执行格式化和写入。

6.4 构造 MIME 与 External 记录

import { buildExternalRecord, buildMimeRecord } from '@/uni_modules/lizhao-nfc-pro'

// application/json 载荷为 UTF-8 十六进制；构造器本身不访问 NFC 硬件。
const mimeRecord = buildMimeRecord({
  mimeType: 'application/json',
  payloadHex: '7B226F6B223A747275657D'
})

const externalRecord = buildExternalRecord({
  domain: 'example.com',
  type: 'device',
  payloadHex: '6C697A68616F'
})

6.5 验证 NDEF 解析器

以下十六进制是一个合法的 Hello 英文文本记录，可用于验证 Android / iOS / HarmonyOS 的原始 NDEF 解析：

import { parseNdefMessage } from '@/uni_modules/lizhao-nfc-pro'

const parsed = parseNdefMessage({
  rawMessageHex: 'D101085402656E48656C6C6F'
})
console.log(parsed.firstText) // Hello

Android、iOS、HarmonyOS 都会尝试使用平台 NDEF 解析器处理 rawMessageHex；非法输入会回退为公共结构化结果。

第 7 步：按标签技术类型使用高级能力

高级指令不是通用读卡接口。先从 NfcTagInfo.techs 和 getNfcCapabilities 确认技术类型，再根据卡片厂商协议生成命令。

生产密钥、AID、卡片个人数据和完整 APDU 不应写入页面、README 或日志。插件只负责传输与结构化错误，不替代业务协议和安全设计。

第 8 步：按顺序排查常见问题

排查时先记录 getNfcCapabilities、getNfcStatus、标签 techs 和完整 NfcFail，但不要把真实密钥、个人数据或生产 APDU 打进日志。

第 9 步：按需查询 32 个 API

API 详细说明（参考手册）

configureNfc(options)

说明 配置会话保持、标签 TTL、去重、等待队列和 Android ReaderMode 策略。

支持平台 Android / iOS / HarmonyOS；部分字段只在对应平台生效。

参数

返回值 void；成功回调返回当前平台和生效配置。

错误码 Android / iOS / HarmonyOS 当前直接通过 success 返回生效配置；Web / 小程序降级入口返回 9060001。

示例

import { configureNfc } from '@/uni_modules/lizhao-nfc-pro'

// 更新后续会话使用的运行策略。
configureNfc({ keepSessionAlive: true, activeTagTtlMs: 30000 })

getNfcCapabilities(options)

说明 查询当前平台真实 NFC 技术能力矩阵。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；success 返回 NfcCapability。

错误码 当前各平台均通过 success 返回能力对象，不进入 fail。

示例

import { getNfcCapabilities } from '@/uni_modules/lizhao-nfc-pro'

// 启用业务按钮前先读取真实平台能力。
getNfcCapabilities({ success: (res: any): void => console.log(res) })

getNfcStatus(options)

说明 查询 NFC 支持状态、系统开关、权限、会话和活动标签状态。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；success 返回 NfcStatus。

错误码 当前各平台均通过 success 返回状态对象；不支持平台会在状态对象中明确 supported: false，不进入 fail。

示例

import { getNfcStatus } from '@/uni_modules/lizhao-nfc-pro'

// 检查开关与权限后再启动读卡会话。
getNfcStatus({ success: (status: any): void => console.log(status) })

openNfcSettings(options)

说明 打开 Android 系统 NFC 设置页。iOS 和 HarmonyOS 没有插件可直接打开的等价设置入口，会明确失败。

支持平台 Android；iOS / HarmonyOS 返回不支持。

参数

返回值 void；Android 成功回调表示已发起系统页面跳转。

错误码 可能返回 9060001、9060002 或 9060015。iOS / HarmonyOS 因没有可直接打开的等价设置入口返回 9060001；Android 上下文不可用返回 9060002，系统页面跳转失败返回 9060015。

示例

import { openNfcSettings } from '@/uni_modules/lizhao-nfc-pro'

// 仅 Android 提供可直接打开的 NFC 设置页。
openNfcSettings({ fail: (err): void => console.error(err) })

startNfcSession(options)

说明 启动原生 NFC 标签发现会话。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；success 只表示会话启动，不表示已经发现标签。

错误码 可能返回 9060001、9060002、9060003、9060004、9060015 或 9060016。

示例

import { startNfcSession } from '@/uni_modules/lizhao-nfc-pro'

// 先注册标签监听，再启动会话。
startNfcSession({ alertMessage: '请靠近 NFC 标签' })

stopNfcSession(options)

说明 停止当前会话并取消该会话尚未执行的等待操作。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；success 返回停止结果。

错误码 可能返回 9060002；被取消的等待操作返回 9060005。

示例

import { stopNfcSession } from '@/uni_modules/lizhao-nfc-pro'

// 页面退出时主动释放原生会话。
stopNfcSession()

scanTagOnce(options)

说明 在当前没有业务会话时启动一次性标签扫描，首张标签成功、启动失败或超时后自动清理内部监听、计时器和会话。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；success 返回 NfcTagInfo。

错误码 已有会话返回 9060015；等待超时返回 9060016；能力、权限或系统开关异常沿用会话错误码。

示例

import { scanTagOnce } from '@/uni_modules/lizhao-nfc-pro'

// 适合“点一下读一张卡”的页面。
scanTagOnce({ success: (tag: any): void => console.log(tag.uidHex) })

onTagDiscovered(listener)

说明 注册持续标签发现监听；同一函数可以在 offTagDiscovered 中精确退订。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；标签通过 listener 持续返回。

错误码 该方法不使用 fail 回调；平台会话错误由 startNfcSession 返回。

示例

import { onTagDiscovered } from '@/uni_modules/lizhao-nfc-pro'

// 保存监听引用，便于页面卸载时精确退订。
const listener = (tag): void => console.log(tag.uidHex)
onTagDiscovered(listener)

offTagDiscovered(listener)

说明 注销指定监听；不传 listener 或传 null 时清空全部标签监听。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void。

错误码 该方法不使用错误回调。

示例

import { offTagDiscovered } from '@/uni_modules/lizhao-nfc-pro'

// 不传参数会清空当前模块注册的全部标签监听。
offTagDiscovered()

getLastTag(options)

说明 读取 TTL 内缓存的最近活动标签。includeNdef 是为兼容既有调用保留的字段，当前 Android、iOS、HarmonyOS 实现均忽略该字段，返回内容只取决于当前标签缓存。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；存在有效缓存时 success 返回 NfcTagInfo。没有缓存标签时，Android / iOS 通过 success 返回空标签对象；HarmonyOS 通过 fail 返回 9060006，缓存过期返回 9060007。

错误码 HarmonyOS 可能返回 9060006 或 9060007；Android / iOS 无缓存时返回空标签对象，不进入 fail。

示例

import { getLastTag } from '@/uni_modules/lizhao-nfc-pro'

// 读取当前缓存标签；需要 NDEF 内容时请再调用 readNdef。
getLastTag({ success: (tag: any): void => console.log(tag) })

clearLastTag(options)

说明 清除缓存标签和原生技术对象，后续标签操作需重新贴卡。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；success 返回清理结果。

错误码 当前各平台均直接清理缓存并通过 success 返回结果，不进入 fail。

示例

import { clearLastTag } from '@/uni_modules/lizhao-nfc-pro'

// 敏感操作完成后清除活动标签引用。
clearLastTag()

cancelNfcOperation(options)

说明 按 operationId 精确取消 Android / HarmonyOS 尚在等待标签的队列项；不会中断已经开始的原生 I/O。

支持平台 Android / HarmonyOS 支持等待队列取消；iOS 返回结构化 cancelled: false。

参数

返回值 void；success 返回 NfcCancelOperationResult，其中 cancelled 表示是否找到仍在等待的操作。

错误码 空 operationId 返回 9060013；被取消的原调用返回 9060005。

示例

import { cancelNfcOperation } from '@/uni_modules/lizhao-nfc-pro'

cancelNfcOperation({ operationId: 'asset-read-1001' })

readNdef(options)

说明 读取活动标签的 NDEF 记录并解析首个文本和 URI。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；success 返回 NfcOperationResult，records 为 NDEF 记录数组。

错误码 可能返回 9060005、9060006、9060007、9060008、9060010、9060014 或 9060015。

示例

import { readNdef } from '@/uni_modules/lizhao-nfc-pro'

// 在标签发现回调内读取，避免超过活动标签 TTL。
readNdef({ success: (res: any): void => console.log(res.records) })

getNdefStatus(options)

说明 查询活动标签的 NDEF 格式、可读写、容量、当前消息大小、标签类型、可格式化和可转只读能力；本接口不会执行不可逆的只读转换。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；success 返回 NfcNdefStatusResult。HarmonyOS capacity=-1，iOS messageSize=-1 表示平台未提供或本次不额外读取。

错误码 可能返回 9060005、9060006、9060007、9060010、9060014 或 9060015。

示例

import { getNdefStatus } from '@/uni_modules/lizhao-nfc-pro'

// 写入前先检查 writable，并仅在 capacity >= 0 时比较容量。
getNdefStatus({ success: (status: any): void => console.log(status.writable) })

writeNdef(options)

说明 把 NfcNdefRecord 数组写入已格式化且可写的 NDEF 标签。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；success 返回 NfcOperationResult。

错误码 可能返回 9060002、9060005、9060006、9060007、9060008、9060010、9060011、9060013 或 9060015；iOS 在 records 为空时返回 9060002。

示例

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

// 先构造标准文本记录，再写入活动标签。
writeNdef({ records: [buildTextRecord({ text: '巡检完成' })] })

formatAndWriteNdef(options)

说明 格式化 NdefFormatable 标签并写入记录。iOS Core NFC 不提供通用格式化能力。

支持平台 Android / HarmonyOS；iOS 返回不支持。

参数

返回值 void；success 返回 NfcOperationResult。

错误码 可能返回 9060001、9060005、9060006、9060007、9060008、9060010、9060012、9060013 或 9060015。iOS 因不提供通用 NDEF 格式化能力返回 9060001。

示例

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

// 仅 Android/HarmonyOS 对可格式化标签执行。
formatAndWriteNdef({ records: [buildUriRecord({ uri: 'https://example.com' })] })

buildTextRecord(options)

说明 同步构造标准 NDEF 文本记录。

支持平台 Android / iOS / HarmonyOS，以及不依赖原生会话的公共逻辑。

参数

返回值 NfcNdefRecord。

错误码 同步构造不使用 fail 回调；非法业务内容应在调用前校验。

示例

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

// 构造可直接交给 writeNdef 的文本记录。
const record = buildTextRecord({ text: '资产编号 A-1001', lang: 'zh-CN' })

buildUriRecord(options)

说明 同步构造标准 NDEF URI 记录。

支持平台 Android / iOS / HarmonyOS，以及不依赖原生会话的公共逻辑。

参数

返回值 NfcNdefRecord。

错误码 同步构造不使用 fail 回调；调用前应校验 URI。

示例

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

// 构造一个 HTTPS 链接记录。
const record = buildUriRecord({ uri: 'https://example.com/device/A-1001' })

buildMimeRecord(options)

说明 同步构造 MIME NDEF 记录，适合 JSON、图片描述或业务自定义二进制载荷。

支持平台 全部平台；纯函数不访问 NFC 硬件。

参数

返回值 NfcNdefRecord。

错误码 同步构造不使用 fail 回调；调用前应校验 MIME 类型和十六进制载荷。

示例

import { buildMimeRecord } from '@/uni_modules/lizhao-nfc-pro'

const record = buildMimeRecord({ mimeType: 'application/json', payloadHex: '7B226F6B223A747275657D' })

buildExternalRecord(options)

说明 同步构造 NFC Forum External Type 记录，最终类型为 domain:type。

支持平台 全部平台；纯函数不访问 NFC 硬件。

参数

返回值 NfcNdefRecord。

错误码 同步构造不使用 fail 回调；调用前应校验域名、类型和十六进制载荷。

示例

import { buildExternalRecord } from '@/uni_modules/lizhao-nfc-pro'

const record = buildExternalRecord({ domain: 'example.com', type: 'device', payloadHex: '6C697A68616F' })

parseNdefMessage(options)

说明 同步解析 NDEF 记录并返回首个文本和 URI。Android、iOS、HarmonyOS 都会优先使用平台 NDEF 消息解析能力处理 rawMessageHex；非法输入回退为公共结构化结果，不抛出未捕获异常。

支持平台 Android / iOS / HarmonyOS，以及不依赖原生会话的公共逻辑。

参数

返回值 NfcParseNdefResult。

错误码 同步解析不使用 fail 回调；无法识别的数据保留为 raw 结果。

示例

import { parseNdefMessage } from '@/uni_modules/lizhao-nfc-pro'

// 使用合法的 NDEF 文本消息验证原始十六进制解析。
const parsed = parseNdefMessage({ rawMessageHex: 'D101085402656E48656C6C6F' })
console.log(parsed.firstText)

nfcATransceive(options)

说明 向活动 NfcA 标签发送原始十六进制指令。

支持平台 Android / HarmonyOS；iOS 不开放通用 NfcA raw transceive。

参数

返回值 void；success 的 bytesHex 为响应字节。

错误码 可能返回 9060005、9060006、9060007、9060008、9060010、9060013、9060014 或 9060015。

示例

import { nfcATransceive } from '@/uni_modules/lizhao-nfc-pro'

// 示例指令仅用于展示格式，真实命令必须遵循目标标签协议。
nfcATransceive({ hex: '3004', timeoutMs: 1000 })

nfcBTransceive(options)

说明 向活动 NfcB 标签发送原始十六进制指令。

支持平台 Android / HarmonyOS；iOS 不开放通用 NfcB raw transceive。

参数

返回值 void；success 的 bytesHex 为响应字节。

错误码 可能返回 9060005、9060006、9060007、9060008、9060010、9060013、9060014 或 9060015。

示例

import { nfcBTransceive } from '@/uni_modules/lizhao-nfc-pro'

// 发送前按卡片厂商协议生成完整命令。
nfcBTransceive({ hex: '0500', fail: (err): void => console.error(err) })

nfcFTransceive(options)

说明 向活动 NfcF / FeliCa 标签发送原始十六进制指令。

支持平台 Android / iOS / HarmonyOS；iOS 需配置业务 System Code。

参数

返回值 void；success 的 bytesHex 为响应字节。

错误码 可能返回 9060005、9060006、9060007、9060008、9060010、9060013、9060014 或 9060015。

示例

import { nfcFTransceive } from '@/uni_modules/lizhao-nfc-pro'

// 命令内容必须与业务 FeliCa System Code 和服务定义匹配。
nfcFTransceive({ hex: '0600', fail: (err): void => console.error(err) })

nfcVTransceive(options)

说明 向活动 NfcV / ISO 15693 标签发送指令；首字节为 requestFlags，第二字节为 commandCode。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；success 的 bytesHex 为响应字节。

错误码 可能返回 9060005、9060006、9060007、9060008、9060010、9060013、9060014 或 9060015。

示例

import { nfcVTransceive } from '@/uni_modules/lizhao-nfc-pro'

// 02 为示例 requestFlags，20 为示例 commandCode。
nfcVTransceive({ hex: '0220', fail: (err): void => console.error(err) })

isoDepTransceive(options)

说明 通过 IsoDep 发送 APDU；iOS 对应 ISO7816 标签能力。

支持平台 Android / iOS / HarmonyOS；iOS 需把业务 AID 配入签名和 Info.plist。

参数

返回值 void；success 的 bytesHex 包含响应数据和状态字。

错误码 可能返回 9060005、9060006、9060007、9060008、9060010、9060013、9060014 或 9060015。

示例

import { isoDepTransceive } from '@/uni_modules/lizhao-nfc-pro'

// SELECT AID 仅为结构示例，请替换为已配置并获授权的业务 AID。
isoDepTransceive({ hex: '00A4040007D2760000850101' })

mifareClassicAuthenticate(options)

说明 使用 Key A 或 Key B 对 MifareClassic 扇区鉴权。

支持平台 Android / HarmonyOS；iOS Core NFC 不支持 MifareClassic。

参数

返回值 void；success 表示当前标签扇区鉴权成功。

错误码 可能返回 9060001、9060005、9060006、9060007、9060008、9060009、9060010、9060013 或 9060015。iOS 因不支持 MifareClassic 返回 9060001。

示例

import { mifareClassicAuthenticate } from '@/uni_modules/lizhao-nfc-pro'

// 密钥仅为常见示例，生产环境不得在页面明文硬编码真实密钥。
mifareClassicAuthenticate({ sectorIndex: 1, keyType: 'A', keyHex: 'FFFFFFFFFFFF' })

mifareClassicReadBlock(options)

说明 读取 MifareClassic 单个块；业务应先完成对应扇区鉴权。

支持平台 Android / HarmonyOS；iOS Core NFC 不支持 MifareClassic。

参数

返回值 void；success 的 bytesHex 为块数据。

错误码 可能返回 9060001、9060005、9060006、9060007、9060008、9060009、9060010、9060014 或 9060015。iOS 因不支持 MifareClassic 返回 9060001。

示例

import { mifareClassicReadBlock } from '@/uni_modules/lizhao-nfc-pro'

// 先鉴权对应扇区，再读取业务块。
mifareClassicReadBlock({ blockIndex: 4, success: (res: any): void => console.log(res.bytesHex) })

mifareClassicWriteBlock(options)

说明 向 MifareClassic 单个块写入恰好 16 字节数据；业务应先鉴权。

支持平台 Android / HarmonyOS；iOS Core NFC 不支持 MifareClassic。

参数

返回值 void；success 表示块写入完成。

错误码 可能返回 9060001、9060005、9060006、9060007、9060008、9060009、9060010、9060011、9060013 或 9060015。iOS 因不支持 MifareClassic 返回 9060001。

示例

import { mifareClassicWriteBlock } from '@/uni_modules/lizhao-nfc-pro'

// 禁止写入厂商块或扇区尾块，示例只展示 16 字节格式。
mifareClassicWriteBlock({ blockIndex: 4, dataHex: '00000000000000000000000000000000' })

mifareClassicReadSector(options)

说明 读取 MifareClassic 指定扇区的全部块；业务应先完成该扇区鉴权。

支持平台 Android / HarmonyOS；iOS Core NFC 不支持 MifareClassic。

参数

返回值 void；success 的 bytesHex 为按块拼接的数据。

错误码 可能返回 9060001、9060005、9060006、9060007、9060008、9060009、9060010、9060014 或 9060015。iOS 因不支持 MifareClassic 返回 9060001。

示例

import { mifareClassicReadSector } from '@/uni_modules/lizhao-nfc-pro'

// 先完成目标扇区鉴权，再读取该扇区。
mifareClassicReadSector({ sectorIndex: 1 })

mifareUltralightReadPages(options)

说明 从 MifareUltralight 指定页开始连续读取四页。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；success 的 bytesHex 为连续四页数据。

错误码 可能返回 9060005、9060006、9060007、9060008、9060010、9060013、9060014 或 9060015。

示例

import { mifareUltralightReadPages } from '@/uni_modules/lizhao-nfc-pro'

// 从第 4 页开始连续读取四页。
mifareUltralightReadPages({ pageIndex: 4 })

mifareUltralightWritePage(options)

说明 向 MifareUltralight 指定页写入恰好 4 字节。

支持平台 Android / iOS / HarmonyOS。

参数

返回值 void；success 表示单页写入完成。

错误码 可能返回 9060005、9060006、9060007、9060008、9060010、9060011、9060013 或 9060015。

示例

import { mifareUltralightWritePage } from '@/uni_modules/lizhao-nfc-pro'

// 写入前确认目标页可写且不是锁定位、配置页或厂商保留页。
mifareUltralightWritePage({ pageIndex: 4, dataHex: '01020304' })

技术能力矩阵

本矩阵描述 App 原生能力；Web 与小程序不提供这些原生技术对象。

iOS 八项系统与技术边界

以下八个公开 API 在 iOS 会明确失败，不会伪造成功：

1. openNfcSettings：iOS 没有应用可直接打开的 NFC 开关设置页。
2. formatAndWriteNdef：Core NFC 不提供通用 NDEF 格式化。
3. nfcATransceive：Core NFC 不开放通用 NfcA raw transceive。
4. nfcBTransceive：Core NFC 不开放通用 NfcB raw transceive。
5. mifareClassicAuthenticate：不支持 MifareClassic 扇区密钥鉴权。
6. mifareClassicReadBlock：不支持 MifareClassic 块读取。
7. mifareClassicWriteBlock：不支持 MifareClassic 块写入。
8. mifareClassicReadSector：不支持 MifareClassic 扇区读取。

iOS 的 NfcF、NfcV、IsoDep/ISO7816、MifareUltralight 是专用原生路径，不能因 rawTransceive 为 false 而误判为全部不可用。

权限、Capability、AID、System Code 与自定义基座

Android

• AndroidManifest.xml 需要 android.permission.NFC 和 android.hardware.nfc。
• NFC 不是运行时危险权限，但设备必须具备 NFC 芯片且系统开关已开启。
• 插件包含 Android 原生 UTS 逻辑，修改后必须重新原生联编或重新打 Android 自定义基座。

iOS

• Info.plist 必须包含 NFCReaderUsageDescription。
• Apple Developer App ID、证书与描述文件必须启用 NFC Tag Reading capability。
• 签名产物需要 com.apple.developer.nfc.readersession.formats；仓库中的 UTS.entitlements 默认不写死该键，最终值必须由实际 App 能力、证书和描述文件一致生成。
• ISO7816 业务需要把真实 AID 配置到 com.apple.developer.nfc.readersession.iso7816.select-identifiers。示例 D2760000850101 不能替代你的业务 AID。
• FeliCa/NfcF 业务需要把真实 System Code 配置到 com.apple.developer.nfc.readersession.felica.systemcodes。FFFF 只用于通用轮询，发布前应按业务签名配置核对。
• 仅修改 UTS.entitlements 文本不能补齐 Apple Developer 后台能力或描述文件；签名不一致会导致会话不可用。
• 插件包含 Swift 与 iOS UTS 原生逻辑，修改后必须重新原生联编或重新打 iOS 自定义基座。

HarmonyOS

• module.json5 需要 ohos.permission.NFC_TAG。
• 设备必须公开对应 NFC Kit 能力；权限或能力缺失会返回明确错误。
• 插件包含 HarmonyOS 原生 UTS 逻辑，修改后必须重新原生联编或重新打 HarmonyOS 自定义基座。

为什么 appResource / wgt 不够

Android、iOS、HarmonyOS 的 NFC 能力都包含编译进安装包的原生实现、权限或 Capability。appResource / wgt 只能更新页面与普通资源，不能替换旧基座里的 UTS 原生代码、Swift、系统权限、entitlements、AID 或 System Code 配置。本次原生能力更新后，三个 App 平台都需要重新联编或重新制作对应自定义基座。

统一错误码

NfcFail.details 会携带 platform、apiName、nativeCode、nativeMessage、tech 和 reason 等诊断字段。业务应以 errCode 做稳定分支，以 details 辅助日志定位。

返回结构

NfcTagInfo

NfcOperationResult

实体标签与安全注意

• 发布前必须用目标 Android、iPhone 和 HarmonyOS 真机以及目标标签类型验证；模拟器和静态编译不能证明射频链路可用。
• 标签必须保持在感应区内，TagLost 后应重新贴卡，不要对旧标签对象无限重试。
• UID 不是安全身份凭证，不能单独用于门禁授权、支付或防伪判断。
• MifareClassic 密钥、APDU 密钥材料和生产 AID 不要明文写入页面、README、日志或仓库，应使用受控后端、设备安全区或业务密钥体系。
• 写入前确认标签容量、只读位、锁定位、厂商块、扇区尾块和访问控制；错误写入可能永久锁卡。
• 日志应避免输出完整卡片个人数据、密钥、令牌和生产配置。
• keepSessionAlive 为 false 适合一次性扫描；连续读写应设为 true，并在完成后主动 stopNfcSession 和 clearLastTag。
• Web 与小程序不伪装 App 原生 NFC 能力；业务应根据 getNfcCapabilities 结果提供明确降级提示。

作者系列UTS插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。