更新记录

1.3.4（2026-11-03）

• 新增按“读卡、NDEF、指令、标签、管理”组织的双宿主示例页签，常用功能直接展示，操作结果支持随页查看与完整、分段复制。
• 优化 NDEF 读取、写入、构造解析和标签操作的界面分组，切换页签保留输入与原有调用，保留写卡风险说明、密码遮蔽及日志脱敏。
• 统一发布版本、示例版本和诊断构建标记；公开 API 及原生 NFC 读写流程保持不变。

1.3.3（2026-10-30）

• 修复 Android 已发现 NDEF 内容、主动读取暂时返回空值时直接提示没有内容的问题，增加同一标签内最多两次读取复核；无法确认时返回读取失败，保留真实空 NDEF 的成功结果。
• 修复读取复核期间停止会话、标签失效或重新发现标签时可能继续使用旧请求的问题；保留原有失败码和一次回调结算。
• 优化 Android NDEF 读取诊断，记录连接、读取、关闭阶段及尝试次数和耗时，便于区分通信失败与空内容。
• 本版更新 Android 原生实现，需重新原生联编或安装匹配的新 Android 自定义基座；公开 API 调用方式不变。

1.3.2（2026-10-27）

• 修复示例页面和辅助模块使用相对引入路径的问题，统一通过 @/uni_modules/ 引用插件内文件，复制页面到其他目录时无需另行复制辅助代码。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

NFC 标签读写

介绍

为 uni-app、uni-app x 提供 Android、iOS、HarmonyOS NFC 识别、NDEF 读写和卡片协议交互。

插件市场：下载与查看支持平台

功能特色

适合哪些场景

普通文本、链接和资产编号业务可先使用 NDEF；高级协议需要卡片厂商协议。本插件不提供支付、交通卡充值、门禁卡破解或密钥提取。

下载与导入

1. 在插件市场选择“使用 HBuilderX 导入插件”，导入自己的 uni-app 或 uni-app x 项目。
2. 保留完整的 uni_modules/lizhao-nfc-pro 目录和插件名称。
3. 页面脚本从插件根目录导入需要的方法：

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

uni-app 使用普通页面脚本；uni-app x 使用 <script setup lang="uts">。不要直接导入 uni_modules/lizhao-nfc-pro/utssdk 或平台内部文件，也不要通过 uni.requireNativePlugin 调用。

完整示例位于项目的 uni_modules/lizhao-nfc-pro/example/ 目录下，按项目类型选择对应文件。以下路径均从项目根目录开始，可直接在 HBuilderX 项目目录中查找：

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

下面的示例需要在具备 NFC 能力的 App 真机上运行。首次接入的原生配置条件见后文“支持平台”。

复制完整示例到页面目录后，在 pages.json 注册对应页面。业务模块中的 UTS 类型写法用于 uni-app x；普通 uni-app 可直接参照同目录 JS 示例。

基础示例：识别一张标签

在页面按钮事件中调用。UID 是标签标识，NDEF 是标签存放文本、链接等内容的格式；取得 UID 不表示标签已有 NDEF 或允许写入。

uni-app 普通页面脚本：

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

scanTagOnce({
  timeoutMs: 15000,
  success: (tag) => { console.log('标签 UID：', tag.uidHex) },
  fail: (err) => { console.error('识别失败：', err.errCode, err.errMsg) }
})

uni-app x 在 <script setup lang="uts"> 中使用强类型参数：

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

const options: NfcScanTagOnceOptions = {
  timeoutMs: 15000,
  success: (tag) => { console.log('标签 UID：', tag.uidHex) },
  fail: (err) => { console.error('识别失败：', err.errCode, err.errMsg) }
}
scanTagOnce(options)

完整 uni-app x 页面见 uni_modules/lizhao-nfc-pro/example/uniappx/index.uvue。一次性 API 在成功、失败或超时后清理自己创建的会话；已有会话处于 starting / active / stopping 时返回 9060015，请等待当前操作结束。

按业务使用

以下片段从插件根目录调用真实 API。一次性 API 可放在按钮事件中；标注“会话内使用”的 API，需要先启动会话并发现标签。除专门展示生命周期的片段外，页面卸载时沿用基础示例的 stopNfcSession 清理。

模块一：读取标签里的文本或链接

适合资产编号、点位说明、设备链接等标准 NDEF 标签。不需要先调用 startNfcSession，点击后等待贴卡即可。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

readNdefOnce({
  timeoutMs: 15000,
  alertMessage: '请靠近需要读取的标签',
  success: (res) => {
    // 从本次真实读取的记录中提取首个文本和链接。
    const content = parseNdefMessage({ records: res.records })
    console.log('标签 UID：', res.tag.uidHex)
    console.log('文本内容：', content.firstText)
    console.log('链接内容：', content.firstUri)
  },
  fail: (err) => {
    console.error('读取标签内容失败：', err.errCode, err.errMsg)
  }
})

firstText / firstUri 只取首个对应记录；业务需要全部记录时读取 res.records。只有 UID、没有 NDEF 的卡片，应使用 scanTagOnce 识别，或按卡片的技术协议处理。

模块二：写入文本或链接，并确认内容

适合给可写的 NDEF 标签设置资产编号、说明文字或访问链接。使用测试标签，点击写入后保持标签贴近，直到收到回调。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

writeNdefOnce({
  records: [buildTextRecord({ text: '资产编号 A-1001', lang: 'zh-CN' })],
  verifyAfterWrite: true,
  timeoutMs: 15000,
  success: (res) => {
    // 写入已完成，只有 matched 才表示回读内容也一致。
    if (res.verificationStatus == 'matched') {
      console.log('写入成功，回读内容一致')
    } else {
      console.log('写入已完成，回读状态：', res.verificationStatus)
      console.log('回读说明：', res.mismatchReason, res.verificationErrorMessage)
    }
  },
  fail: (err) => {
    console.error('写入未确认完成：', err.errCode, err.errMsg)
  }
})

写入链接时，将上面的记录换成 buildUriRecord({ uri: 'https://example.com/device/A-1001' })，并从插件根目录导入 buildUriRecord。records 可以包含多条记录，但不能是空数组。

verifyAfterWrite 默认开启。进入 success 不一定表示回读一致，应检查 verificationStatus。该方法不会自动格式化、锁定标签或重新写入；失败信息中的 details.reason 可帮助判断写入未开始还是结果不确定。

模块三：连续读取多张标签

适合 Android / iOS / HarmonyOS 批量登记、盘点或连续采集。每次只放一张标签，读取后移开，再贴下一张。

下面采用 UTS 写法，uni-app 普通脚本去掉类型标注即可。监听器在页面进入时注册一次；“开始”按钮只调用 startContinuousScan，“停止”按钮调用 stopContinuousScan。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

import {
  onTagDiscovered, offTagDiscovered,
  startNfcSession, stopNfcSession, NfcTagInfo
} from '@/uni_modules/lizhao-nfc-pro'

// 每张标签的结果从这个监听器返回。
const handleTag = (tag: NfcTagInfo): void => {
  console.log('标签 UID：', tag.uidHex)
  console.log('可取得的文本和链接：', tag.ndefText, tag.ndefUri)
}
onTagDiscovered(handleTag)

function startContinuousScan(): void {
  startNfcSession({
    continuousScan: true,
    alertMessage: '读取后移开标签，再贴下一张',
    fail: (err) => {
      console.error('连续扫描启动失败：', err.errCode, err.errMsg)
    }
  })
}

function stopContinuousScan(): void {
  // 停止本次会话，保留页面监听以便再次开始。
  stopNfcSession({})
}

function disposeContinuousScan(): void {
  // 页面退出时，用注册时的同一函数引用退订。
  offTagDiscovered(handleTag)
  stopNfcSession({})
}

uni-app x 在 onUnload 中调用 disposeContinuousScan()；uni-app 在页面 onUnload 中做相同清理。监听只需注册一次。Android 新订阅会向该监听回放仍有效的缓存标签；同一函数重复注册不再回放，其他监听不会因此重复收到结果。iOS 标签订阅等待后续发现事件，不回放历史标签。

• 每张标签通过 onTagDiscovered 返回；startNfcSession.success/complete 只返回启动结果。
• continuousScan 默认关闭；显式设为 true 时优先保持会话，即使同时传入 keepSessionAlive: false。iosContinuousScan 保留为兼容别名，新代码使用统一参数。
• App 三端都需要保持前台。iOS 使用系统读卡弹窗，受取消和会话时限约束；结束后需要再次启动，不支持后台无限扫描。
• Android 同一标签短时间内会去重；使用前台分发方式时，同一来源和 UID 至少去重 2 秒。是否再次报告未移开的同一张卡，还取决于设备回调，业务仍应按自己的规则去重。
• ndefText / ndefUri 可能为空；需要完整 NDEF 内容时，在当前标签仍贴近的回调中调用 readNdef。完成本张卡读写后再换卡。
• Android 的 readNdef / readNdefOnce 遇到暂时空返回或可恢复的读取通信错误时，在同一次标签发现内最多读取两次。发现时已有内容但复核仍为空，或通信错误后未取得消息，会返回 9060014；请提示“读取未完成，请保持贴近后重试”，不要显示为空卡。成功时以 res.records 为本次读取结果，res.tag 保留发现时快照。
• scanTagOnce、readNdefOnce、writeNdefOnce 始终用于一次操作，不会变成连续扫描。continuousScan 在 App 三端均保持会话；HarmonyOS 使用持续 ReaderMode 接收发现事件，Android / iOS 按各自原生方式等待移卡及下一张标签。

模块四：写入前检查标签，按需格式化

适合标签来源不统一、需要先判断是否可写的业务。会话内使用：先启动会话，发现标签后查询状态。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

getNdefStatus({
  success: (status) => {
    console.log('已格式化为 NDEF：', status.formatted)
    console.log('可读取 / 可写入：', status.readable, status.writable)
    // -1 表示无法取得容量，不能按 0 容量处理。
    if (status.capacity >= 0) console.log('标签容量（字节）：', status.capacity)
  },
  fail: (err) => {
    console.error('查询标签状态失败：', err.errCode, err.errMsg)
  }
})

HarmonyOS 的 capacity 当前为 -1；iOS 此查询不额外读取内容，messageSize 为 -1。状态检查不能代替写入回调，查询后移卡或标签改变仍可能导致写入失败。

如果确认是自己的空白测试标签、canFormat 为 true，可在明确的“格式化写入”按钮中使用下面片段；不要在发现未知卡片后自动格式化。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

// 已有活动标签时调用；先备份测试标签原内容。
formatAndWriteNdef({
  records: [buildTextRecord({ text: '测试标签 A-1001' })],
  success: (res) => { console.log('格式化写入完成：', res.message) },
  fail: (err) => { console.error('格式化写入失败：', err.errCode, err.errMsg) }
})

模块五：在自己的页面中管理读卡会话

适合要保留“开始 / 停止”按钮、持续显示读卡结果，或在同一张标签上执行多次操作的页面。先注册标签监听，再启动会话；在标签回调中执行 readNdef、writeNdef 或技术指令。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

// 页面进入时注册一次，当前标签仍贴近时读取内容。
const handleTag = (tag: NfcTagInfo): void => {
  console.log('发现标签：', tag.uidHex)
  readNdef({
    success: (res) => { console.log('读取到的 NDEF 记录：', res.records) },
    fail: (err) => { console.error('读取失败：', err.errCode, err.errMsg) }
  })
}
onTagDiscovered(handleTag)

function startReadSession(): void {
  startNfcSession({
    keepSessionAlive: true,
    alertMessage: '请将标签靠近手机',
    success: () => { console.log('会话已启动，等待标签') },
    fail: (err) => { console.error('启动失败：', err.errCode, err.errMsg) }
  })
}

function disposeReadSession(): void {
  // 页面卸载时精确退订，并停止会话。
  offTagDiscovered(handleTag)
  stopNfcSession({})
}

“开始”按钮调用 startReadSession()，页面卸载时调用 disposeReadSession()。iOS 自动移卡换卡应使用模块三的 continuousScan。

startNfcSession.success 表示会话启动，标签结果来自监听器。活动标签有有效时间窗，默认 activeTagTtlMs 为 30 秒；读写时还必须保持标签贴近。页面退出、会话终止或标签过期后，不能继续使用旧标签。

需要记录会话关闭、取消、超时时，可注册状态监听：

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

import {
  onNfcSessionStateChange, offNfcSessionStateChange, NfcSessionStateEvent
} from '@/uni_modules/lizhao-nfc-pro'

// 注册后先收到当前状态快照，后续收到状态变化。
const handleState = (event: NfcSessionStateEvent): void => {
  console.log('会话状态：', event.state, event.reason)
}
onNfcSessionStateChange(handleState)

function disposeStateListener(): void {
  // 与标签监听一样，页面卸载时使用原函数引用退订。
  offNfcSessionStateChange(handleState)
}

模块六：保存自定义内容、解析多条记录

适合需要保存 JSON 数据、自定义设备标识或处理完整 NDEF 消息的业务。构造与解析函数同步返回结果，本身不启动读卡会话。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

// 载荷是 UTF-8 字节的十六进制；这里的内容为 {"ok":true}。
const jsonRecord = buildMimeRecord({
  mimeType: 'application/json',
  payloadHex: '7B226F6B223A747275657D'
})
const deviceRecord = buildExternalRecord({
  domain: 'example.com',
  type: 'device',
  payloadHex: '4131303031'
})

// 保存这些记录需要再交给 writeNdef 或 writeNdefOnce。
console.log('待写入记录：', jsonRecord, deviceRecord)
const parsed = parseNdefMessage({ rawMessageHex: 'D101085402656E48656C6C6F' })
console.log('解析后的文本：', parsed.firstText) // Hello

payloadHex 是字节的十六进制表达，不能直接填 JSON 文本。parseNdefMessage 可接收 records 或 rawMessageHex；非法原始消息可能返回公共结构化结果，不能只凭没有抛错就判断字节消息合法。

Android / iOS 写入前会检查整组记录。空数组、非法或奇数位 payloadHex / id、超过 63 字节的 Text 语言标记、矛盾的 TNF，以及独立使用 unchanged / reserved，会返回 9060013。合法的空载荷和空 ID 可以使用；ID 和实际 type 最多各 255 字节。hex 字段允许空格、换行、冒号、短横线、逗号和 0x 前缀。

手工构造 raw / External / absolute-uri 记录时，iOS 的 type 保留既有 hex 优先解码规则，Android 按文本字节处理；MIME type 两端均为文本。需要跨端相同的常见记录时优先使用上面的记录构造器，专业原始记录应按卡片协议分别确认字节。

文本默认使用 utf-8，需要 UTF-16 时显式传 encoding: 'utf-16'。记录 ID 使用偶数位十六进制；MIME / External 构造器可直接传 id，空 ID 和空 MIME 载荷保留为空。HarmonyOS 也保留自定义 Text / URI 记录的 ID，并按 UTF-8 字节检查语言字段最多 63 字节、type 最多 255 字节；各端已有原始 type 编码约定保持。

模块七：发送 APDU 或其他卡片指令

适合已经掌握卡片协议的专业业务。会话内使用：先检查标签 techs 和 getNfcCapabilities，确认设备和卡片支持对应技术，再发送指令。

下面只演示选择 NFC Forum NDEF 应用；它不是适用于所有卡片的通用读卡命令。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

isoDepTransceive({
  hex: '00A4040007D276000085010100',
  success: (res) => {
    // 响应内容和状态字仍需按卡片协议判断。
    console.log('APDU 响应：', res.bytesHex)
  },
  fail: (err) => {
    console.error('APDU 交互失败：', err.errCode, err.errMsg)
  }
})

ISO15693 在 Android 使用原始指令帧。iOS 会把支持的标准命令映射到 Core NFC 方法；两端的帧约定通过 nfcVFrameFormat 明确选择：默认 platform 保留各端已有调用，跨端发送 Android 格式时显式设为 android。这不会让 iOS 支持任意原始命令。

标准命令可验证寻址帧的 UID，UID 必须匹配当前标签的 ISO15693 线序（小端）；iOS 自定义指令的 android 寻址帧本版不支持。标准命令成功的 bytesHex 为 00 加实际数据，写单块成功为 00；厂商自定义仍返回原有 Core NFC 业务数据，不额外补 00。卡片错误通过 fail 返回，不返回伪造的原始错误帧。

例如，在已发现 ISO15693 标签的会话内读取第 0 块：

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

nfcVTransceive({
  hex: '022000',
  nfcVFrameFormat: 'android',
  success: (res) => { console.log('第 0 块响应：', res.bytesHex) },
  fail: (err) => { console.error('读取失败：', err.errCode, err.errMsg) }
})

通信成功只代表取得响应；卡片是否接受命令、返回何种业务数据，需要自己的协议解析。不要向未知卡片发送修改、锁定或擦除命令。

CPU 卡与实体公交卡补登对接

ISO14443 描述底层通信。支持 ISO-DEP 的 CPU 卡应用通常通过 APDU 交互；Classic 的扇区 Key A/B 鉴权不能代替 CPU 卡应用认证。技术列表同时出现 isoDep 和 mifareClassic 时，按目标应用协议选择接口，不根据列表推断厂商或充值权限。

Android 的标签回调和 getLastTag 返回可选的 androidTechnology：包含 atqaHex、sakHex、isoDepAvailable、historicalBytesHex、hiLayerResponseHex、maxTransceiveLength 和 extendedLengthApduSupported。这些值来自 SDK 缓存，查询不会发送探测指令。atqaHex 保留 SDK 字节顺序；historicalBytesHex 只是历史字节，不是完整 ATS。UID 和这些参数都不能用于确认充值订单对应的真实卡账户。

对接分多步的卡片业务时，可保留首次确认卡片的 tagToken，随后将它传入 isoDepTransceive.expectedTagToken。以下函数只发送一条已取得协议的指令；调用前必须已启动会话并取得标签，commandHex 由业务协议提供：

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

function sendBoundCommand(tagToken: string, commandHex: string) {
  isoDepTransceive({
    expectedTagToken: tagToken,
    hex: commandHex,
    timeoutMs: 1500,
    success: (res) => {
      // success 只表示通信完成；将真实响应交给已接入的卡应用协议处理。
      console.log('状态字：', res.apduResponse?.statusWord)
    },
    fail: (err) => { console.error('交互已停止：', err.errCode, err.errMsg) }
  })
}

绑定参数错误返回 9060013，标签不匹配或不可用返回 9060006，仍可识别的过期标签返回 9060007；通信错误保留既有错误分类。绑定流程发生通信异常后，旧标签不能继续使用，应重新发现并按业务平台要求恢复。手机未即时报告离场时，令牌仍可能存在；最终以原生通信结果为准。

两份示例均位于插件的 uni_modules/lizhao-nfc-pro/example/ 目录：uni-app 为 uni_modules/lizhao-nfc-pro/example/uniapp/nfc.vue，uni-app x 为 uni_modules/lizhao-nfc-pro/example/uniappx/index.uvue。两份示例提供相同的功能分组、默认输入、按钮、CPU 绑定发送和分段日志；空块号不会被当成块 0。

三端普通 APDU 的 success 均表示取得真实响应，返回完整 bytesHex 和结构化 apduResponse，不把非 9000 的卡片响应冒充通信异常。iOS 同时支持系统识别为 ISO7816 的标签及 MiFare Plus / DESFire 的 ISO7816 通道；实际卡应用仍受 Core NFC 和发行方协议限制。HarmonyOS 在同次发现的标签上复用 ISO-DEP 连接并串行发送；换卡、清空缓存、停止或切换其他技术时释放。三端均不自动重试或追加指令。

timeoutMs 传入时应为有限正整数。Android / HarmonyOS 设置原生收发超时；iOS 使用插件超时门禁，超时终结本次请求并释放对应会话，不能证明卡片没有执行命令。省略时沿用平台默认处理。收到失败后先核对业务结果，不要直接重复发送写卡命令。

连接恢复的共同操作为“停止会话 → 开始会话 → 移开后重新贴卡 → 等待新标签令牌”。正常连续发送不必重开会话。已有活动会话时重复 startNfcSession 的原行为保留：Android 重建，iOS 返回忙，HarmonyOS 返回已启动；因此不要将重复开始当成三端通用的重置操作。iOS 仍有系统读卡窗口与签名/AID 配置要求，也不支持 Classic。

实体公交卡的“已付款补登”还需要发卡方、运营方或授权服务商提供订单查询、认证交易、写卡结果确认及中断恢复接口或 SDK，以及测试卡和测试订单。本插件目前提供通信与诊断基础，不含这些服务，不提供通用充值函数。取得资料后按其流程完成“确认卡账户和待补登订单 → 认证与写卡 → 卡片结果及平台确认”；若 SDK 已管理 NFC，应按其接入方式避免抢占连接。

没有协议资料时，可先在 uni_modules/lizhao-nfc-pro/example/uniappx/index.uvue 或 uni_modules/lizhao-nfc-pro/example/uniapp/nfc.vue 的“CPU 卡 / ISO-DEP 对接”区域点击“卡片 / APDU 诊断”，再点“复制日志”；无需填写或发送指令。新增诊断的 androidIsoDep 保留最近 24 条事件和最后失败，记录阶段、长度、状态字、耗时及是否已尝试发送，不保存 APDU 或响应数据。旧示例的原始收发日志仍会显示响应内容，转发前按业务要求检查。

模块八：读取 Mifare 标签的块或页

适合明确使用 Mifare 标签的业务。下面为 MifareUltralight 读取示例，在已经发现该技术标签的会话中调用。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

// 示例从第 4 页读取；实际可访问范围按标签规格确认。
mifareUltralightReadPages({
  pageIndex: 4,
  success: (res) => { console.log('页数据：', res.bytesHex) },
  fail: (err) => { console.error('读取页失败：', err.errCode, err.errMsg) }
})

MifareClassic 只在 Android / HarmonyOS 支持：先用合法业务密钥调用 mifareClassicAuthenticate，鉴权成功后再调用 mifareClassicReadBlock 或 mifareClassicReadSector。写块使用 mifareClassicWriteBlock，写页使用 mifareUltralightWritePage。

Classic 写块必须提供 16 字节，Ultralight 写页必须提供 4 字节；卡片锁定位、厂商区、配置页和扇区尾块不能按普通业务数据随意写入。密钥由自己的受控业务提供，不要写进示例或日志。

模块九：根据手机能力显示业务入口

适合在页面进入时判断“是否支持 NFC”“是否需要打开系统 NFC”，并按技术能力显示操作按钮。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

getNfcCapabilities({
  success: (capability) => {
    console.log('支持 NFC：', capability.supported)
    console.log('支持读取 / 写入 NDEF：', capability.ndefRead, capability.ndefWrite)
  }
})
getNfcStatus({
  success: (status) => {
    console.log('系统 NFC 状态：', status.nfcEnabled)
    console.log('授权和会话状态：', status.permissionStatus, status.sessionState)
  }
})

Android 可用 openNfcSettings({}) 引导打开系统设置；iOS / HarmonyOS 不提供插件直达 NFC 开关设置入口。supported 表示能力，nfcEnabled 表示报告的可用状态，二者不能代替真正启动会话后的成功或失败结果。

模块十：取消还在等待贴卡的操作

适合 Android / HarmonyOS 已启动会话、先提交操作但标签还未靠近的业务。使用自己的操作编号，取消尚未开始的请求。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

// 同一个编号关联本次等待操作与取消按钮。
const operationId = 'asset-read-1001'
readNdef({
  operationId,
  success: (res) => { console.log('读取完成：', res.records) },
  fail: (err) => { console.log('读取被取消或失败：', err.errCode, err.errMsg) }
})

// 放到“取消等待”按钮中调用。
cancelNfcOperation({
  operationId,
  success: (res) => { console.log('是否取消了等待操作：', res.cancelled) },
  fail: (err) => { console.error('取消等待失败：', err.errCode, err.errMsg) }
})

cancelled: true 表示从等待队列中取消成功；已经开始的原生读写不会被强制中断。iOS 没有这种预贴卡等待队列，返回 cancelled: false，也不会因此停止读卡会话。该方法用于会话内等待操作，不能代替停止一次性 API 的会话。

模块十一：设置 NTAG215 密码保护

在已开始的会话中发现标签后，由用户明确点击按钮调用。调用方必须确认是真实 NTAG215 测试卡；技术列表包含 MifareUltralight / NfcA 不代表 SDK 能可靠识别 NTAG215 型号。先由业务安全保存密码，再执行写卡。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

// 仅在用户明确点击“设置密码并启用保护”后调用，示例值请替换为业务保管的密码。
ntag215SetPassword({
  passwordHex: '11223344',
  packHex: 'A1B2', // 可省略，默认 0000；不要记录到日志。
  success: (res) => {
    console.log('NTAG215 保护成功：', res.auth0, res.verificationStatus)
  },
  fail: (err) => {
    // 仅输出安全状态；不能因为失败就自动重新写卡。
    console.error('NTAG215 保护失败：', err.errCode,
      err.details?.stage, err.details?.writeAttempted, err.details?.mayBePartial)
  },
  complete: () => { console.log('NTAG215 密码保护回调完成') }
})

固定策略为 AUTH0=4、PROT=1、AUTHLIM=0：从第 4 页开始读取和写入均须认证，不限制认证失败次数。插件按 PWD → PACK → ACCESS → AUTH0 → PWD_AUTH 的顺序执行，最后核对返回的 PACK；写入保护后立即生效。密码保护不是数据加密，密码只能由业务安全保管，不应记录在日志、诊断或复制报告中。

CFGLCK=1 时预检返回 9060011、reason=configurationLocked，且零写入。四页写入不具备原子性，首次写请求失败也可能实际生效；根据失败详情人工确认，不要自动重试或回滚。本 API 不提供旧密码更改、解锁，也不承诺公共 raw API 在跨连接或重新贴卡后保留鉴权状态。

API 用途速查

不需要一次接入全部方法，按自己的业务选择。下表覆盖全部 38 个公开 API；具体平台支持见后文。

异步 API 的函数本身返回 void，结果从回调取得。记录构造器返回 NfcNdefRecord，parseNdefMessage 返回 NfcParseNdefResult；监听器通过传入函数订阅。

常用配置与参数

通用回调与操作编号

有回调的 API 采用 success / fail / complete。成功和失败只会进入其中一个，complete 在结束时触发，不能作为成功判断；持续标签结果和会话变化来自各自监听器。

cancelNfcOperation 的 operationId 是必填项。上述回调不适用于同步构造/解析函数；on* / off* 直接传监听函数。offTagDiscovered() / offNfcSessionStateChange() 不传函数会清除该类全部监听，多个页面或模块共用插件时应传入自己的函数。

configureNfc：配置后续会话

多数业务可使用默认值。修改配置影响后续会话，正在运行的会话仍使用启动时的配置。

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

// 为之后启动的会话设置去重与活动标签时间窗。
configureNfc({ dedupeMs: 800, activeTagTtlMs: 30000 })

App 三端的超范围有限数值收窄到上述范围；NaN / Infinity 保留此前有效默认。配置修改用于下一次启动，当前会话继续使用启动时的快照。成功回调中的 config 返回归一后的默认配置；iOS 的 Android 专用字段为 useReaderMode: false、skipNdefCheck: false，未提供等待队列，pendingMax 为 0；HarmonyOS 的 useReaderMode 为 false，其 ReaderMode 由平台实现管理。

startNfcSession：普通会话或连续扫描

continuousScan 不传或关闭时，继续沿用普通会话的保持策略；它不等于把 keepSessionAlive 改为 false。普通会话的 keepSessionAlive: false 用于处理首张标签，保留到首个操作完成或有效时间窗结束后关闭。

一次性识别、读取与写入

三种入口成功、失败或超时后仅清理自己创建的会话，不停止其他业务的已有会话。等待首张标签的超时不等于每条原生指令的超时。

会话内 NDEF 与标签缓存

getLastTag 返回最近一次发现的标签摘要，不代表标签仍贴近手机；缓存也不能替代 readNdef 的真实读取。clearLastTag 清除缓存，不等于停止会话。

NDEF 构造与解析

技术指令与 Mifare 参数

这些参数只用于对应的技术 API，不能混入一次性扫描参数。

ntag215SetPassword：NTAG215 密码保护参数

返回结果怎么读

NTAG215 密码保护结果 NfcNtag215SetPasswordResult

标签结果 NfcTagInfo

scanTagOnce.success、onTagDiscovered 和 getLastTag.success 返回标签对象。

NDEF 记录 NfcNdefRecord

读写与技术操作结果

设备、会话与诊断结果

会话状态为 idle / starting / active / stopping / closed。权限状态为 notRequired / granted / denied / notDetermined / missingCapability / unsupported；iOS 的 notDetermined 不代表已被拒绝，也不代表已经授权。

支持平台

以下能力用于 App 真机；Web 和小程序不提供本插件的原生 NFC 标签读写。

平台支持不等于每部手机支持所有卡片。接入前查询 getNfcCapabilities，发现标签后再检查 techs。iOS 的 rawTransceive: false 只表示没有通用原始指令能力，不能据此隐藏 NfcF、NfcV、ISO7816 或 MifareUltralight 的专用操作。

• Android：需要具有 NFC 的手机，开启系统 NFC，并在原生包中包含 NFC 权限与能力声明。
• iOS：使用支持 Core NFC 的 iPhone；最终应用的 NFC 使用说明、NFC Tag Reading 能力和签名描述文件必须一致。ISO7816 使用对应业务 AID，FeliCa 使用合法的四位十六进制 System Code；FFFF / FFxx / xxFF 不能作为通配配置。
• HarmonyOS：需要设备提供相应 NFC 能力，并在应用中声明 ohos.permission.NFC_TAG。

iOS 未配置有效 FeliCa System Code 时，NfcF / Type 3 标签不可发现；普通 ISO14443 / ISO15693 路径不因此关闭。普通读卡流程不支持支付应用选择，应使用自己业务合法的 AID。

FeliCa System Code 使用四位十六进制离散值，不使用 FFxx / xxFF 字节通配值；0FF0 是合法的离散值，仍需与业务卡片匹配。

iOS 宿主需启用 NFC Tag Reading 能力，并确认描述文件与最终签名中的 com.apple.developer.nfc.readersession.formats 包含 TAG。UTS.entitlements 是插件参与原生合并的配置文件，最终授权以应用签名和描述文件为准。

ntag215SetPassword 在 Web、微信小程序、支付宝小程序同样返回 9060001，不会模拟写卡成功。

错误码说明

失败对象包含 errSubject、errCode、errMsg 和 details。业务按 errCode 分支处理，details 中的 platform / apiName / nativeCode / nativeMessage / tech / reason 用于辅助排查。

NTAG215 失败详情

ntag215SetPassword 的 error.details 提供以下安全状态。字段尚未产生时可能省略，不能把字段缺失解释为写卡成功。

参数不合法返回 9060013，配置读取或保护配置写入失败返回 9060011，标签离场返回 9060010，认证交互异常或 PACK 不匹配可能返回 9060014 / 9060011。会话、超时和取消仍使用既有错误码。失败并不等于卡片未改变，尤其首次写入请求送出后无法单凭异常确认芯片状态。

errSubject 为 lizhao-nfc-pro。

注意事项

• Android UTS 原生代码更新后，请重新原生联编或安装与当前源码匹配的自定义基座；页面热更新不能更新原生代码。

• 首次接入或更新原生 NFC 能力、权限、签名配置时，需要重新原生联编或制作并安装对应平台自定义基座；页面热更新不能更新已编入原生包的 NFC 能力。

• Classic 普通数据块自动回读校验仍为 Android 能力；HarmonyOS 写入指令完成后应显式读回核验，iOS 不支持 Classic。

• 页面退出时停止自己管理的会话，并用原监听函数精确退订。应用中同时存在多个 NFC 页面时，应集中管理会话，避免互相停止。

• 每次只放一张标签，读写完成前保持贴近感应区。标签离场后先确认上次写入结果，不自动重复写入或对旧标签持续重试。

• UID 不能单独作为门禁授权、支付或防伪凭证。写入前备份原内容，确认容量、锁定位与访问条件，只在合法可操作的标签上使用。

• 正式使用前，按目标手机和实际标签验证读取、写入、取消与恢复流程；模拟器不能证明真实 NFC 通信可用。

常见问题

需要定位问题时，在失败后查询诊断：

以下代码若含 UTS 类型标注，适用于 uni-app x；普通 uni-app 请使用本插件对应 JS 示例。

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

getNfcDiagnostics({
  success: (res) => {
    console.log('当前会话状态：', res.sessionState)
    console.log('最近错误：', res.lastError)
    console.log('处理建议：', res.recommendation)
  }
})

诊断不包含标签内容、APDU 或密钥，自己的业务日志也应避免记录这些敏感信息。

Android 升级后进入页面报 NfcTagInfo / NoSuchMethodError

这类错误发生在页面创建标签对象时，表示页面调用的原生构造方法与 APK 中实际的类不一致。它发生在读卡之前，与扇区、密钥、卡片协议无关。标签包含可选的 tagToken、androidTechnology；页面仍可只填写原有字段，但页面代码与原生插件需要一起重新编译。仅凭错误截图不能确定是哪一份缓存或打包输入不一致。

1. 确认项目的完整 uni_modules/lizhao-nfc-pro/ 已更新到同一版本，不混用不同版本的接口文件和平台文件；保留业务页面原有初始化写法。
2. 在 HBuilderX 的 Android 运行窗口勾选“清理构建缓存”，并执行一次完整运行，等待控制台显示编译完成后再停止运行，让页面与插件重新生成。仅勾选复选框而不执行运行不会完成清理。请使用同一 HBuilderX 版本完成后续构建。
3. 正式 APK 出错：清理后重新执行“发行 → 原生 App－云打包”，安装新生成的正式 APK 再进入 NFC 页面。只更新页面资源、WGT 或重启旧 APK 不能替换其中的原生类。
4. 自定义基座调试出错：重新制作并安装本项目的 Android 自定义基座，运行时选择“自定义基座 → 本地基座”，并完成页面资源的重新编译与同步。普通模式和蒸汽模式需使用各自对应的基座。
5. 若全量重新打包后仍出错，请保留第一条完整异常、HBuilderX 版本、插件版本、普通/蒸汽模式以及该次 APK 的生成时间。页面可以打开后，点击“接入诊断”，buildMarker 应与当前插件构建标记一致。

无需为消除这个错误，把 ref<NfcTagInfo>({...}) 改成其他类型或补写可选字段。插件版本号更新本身也不会修复已经安装的旧 APK。

CPU 卡为什么提示 Classic 鉴权失败？诊断会执行鉴权吗？

先看实际 API 和错误码。若标签技术只有 isoDep,nfcA，调用 mifareClassicAuthenticate 返回 9060008，表示标签未提供 Classic 技术，尚未执行扇区密钥鉴权。9060009 才是 Classic 鉴权被拒绝。ISO14443-4 / ISO-DEP 使用 APDU 交互，CPU 卡应用认证需按发行方协议完成；更换 Classic Key 或延长会话不能把这两个流程转换为同一种认证。技术列表同时包含 isoDep 和 mifareClassic 时，按实际应用协议选择，不能直接禁用 Classic。

两套示例的“CPU 卡 / ISO-DEP 对接”区域都提供以下入口：

1. 没有发行方协议：开始会话 → 贴卡 → 卡片 / APDU 诊断 → 复制日志。诊断仅读取缓存技术参数，不发送探测 APDU，也不会执行 CPU 卡应用鉴权。
2. 已有发行方协议：填写协议规定的 APDU，再点“绑定当前卡发送”。通信结果、状态字、应用鉴权与充值结果应按业务协议分别判断；示例不会自动执行一套通用认证或补登充值流程。

示例中，“当前状态”会显示最后发现标签的协议提示，“Classic 扇区鉴权”按钮仍调用原插件 API，便于验证真实失败回调。日志开头包含示例版本、本页诊断次数及 APDU 请求数；计数只记录本页操作，不是鉴权或充值成功次数。短摘要不重复展开 lastError.reason 中的长原生事件，ISO-DEP 日志置于完整 Classic 日志之前。

请使用示例“复制日志”按钮的完整输出，保留开头的示例版本和诊断获取状态。若只复制一条“接入诊断”控制台输出，或文件在 JSON 字符串中间结束，不能把后半段缺失当作没有 APDU 记录。

客户遇到问题，怎样一次提供完整日志？

uni-app x 使用 uni_modules/lizhao-nfc-pro/example/uniappx/index.uvue；uni-app 使用 uni_modules/lizhao-nfc-pro/example/uniapp/nfc.vue。示例的完整报告格式为 nfc-example-report-v3，页面版本与原生 buildMarker 会分别记录，便于检查页面、插件和基座是否匹配。

1. 开始会话、贴卡，按实际业务步骤复现一次问题；保留页面，不用先清屏。
2. 点击“复制日志”，把完整文本粘贴发送。报告应同时有同一编号的 NFC报告开始 和 NFC报告结束；即使清屏过，仍可复制当前原生诊断与本页保留的 APDU 流水。
3. 如聊天软件截断长文本，可粘贴到 TXT 文件后发送文件，或点击“复制下一段”，每次粘贴发送一段，直到 N/N。每段正文最多 6000 个 UTF-16 字符，带报告编号、序号、总段数及结束标记；复制失败或 3 秒未回调不会跳过该段，可重试。
4. 分段发送期间不要再次点击“复制日志”，否则会生成新快照并从第 1 段重新开始。已有分段不会随新读卡操作变化；全部复制后再点“复制下一段”会从第 1 段重发。

报告包括设备/系统与编译运行环境、页面/原生版本、缓存标签协议/会话/令牌、非敏感表单参数、原生异常、Classic 与 ISO-DEP 原生诊断、页面事件，以及每次 APDU 的入口、operationId、头部/长度、超时、总耗时、响应长度/状态字和成功/失败/complete 回调次数。页面事件和 APDU 时间使用带毫秒的 UTC 时间；APDU 总耗时含等待标签和排队，原生 I/O 耗时单独见原生诊断。表单快照不代表实际已发请求，以流水为准。

APDU 流水在本页保留最近 120 条并标明省略数，“清屏”只清除页面显示；退出重进页面会重新计数。新增流水不记录 APDU 数据区、响应载荷或 Classic 密钥；异常自由文本中连续 8 位以上的十六进制、4 字节以上的分隔十六进制及以 PIN / password / key 等标注的值会脱敏，摘要与完整错误使用同一规则。单条 APDU 错误详情超过 8000 字符会明确标记截短，原生缓存报告继续单独保留。没有回调、回调重复、只有 complete 或原生诊断查询失败/超时都会留下可识别的状态；复制诊断不会额外发送卡片指令。

Classic 鉴权成功但读块失败：复制完整诊断日志

Classic 读写块的 blockIndex 是整张卡的绝对块号。鉴权扇区 1 后，读三个数据块分别传 4、5、6；7 是该扇区的尾块，保存访问条件和密钥区域，读取权限由卡片访问条件决定。传 1、2、3 会操作扇区 0，填写的鉴权扇区号不会自动转换读写块号。Classic 4K 的扇区 32 起每区 16 块，不能对所有扇区统一使用“扇区号乘 4”计算。

Android 的 mifareClassicWriteBlock 对可确认的普通数据块自动执行写前原 Key 鉴权、一次写入、写后原 Key 鉴权和同一绝对块的 16 字节回读比对；仅比对一致后进入 success，message 明确“回读校验一致”。bytesHex 仍为本次提交的数据。没有当前连接、会话、标签代次和扇区的匹配凭据时不猜测 Key，沿用原 SDK 鉴权状态执行一次写入与回读校验；失败进入 fail。回读不一致返回 9060011；写入已发送但掉场、鉴权或回读失败时，结果可能不确定，应查看完整诊断，不自动重复写入。

块 0、扇区尾块和无法确认元数据的目标保留原有写入指令语义，成功消息明确“未执行回读校验”，不能当成完整内容已校验。尾块密钥的读取值可能被屏蔽，不能直接与写入的 16 字节比较；此类操作及异常会清理原凭据。写入尾块后继续操作须用当前密钥重新鉴权。HarmonyOS 的写块结果保持原语义，需要业务自行回读；iOS 不支持 Classic。

复测写入时先记录原值，再写入另一组 16 字节数据；重复提交卡内已有内容无法证明写入过程实际生效。普通块的回读一致只说明当前回读内容匹配，长期保存仍可移卡后用独立读卡器确认。

Android Classic 失败会在已有 details.reason 中附带 Classic诊断= JSON，失败后查询 getNfcDiagnostics 可从 lastError.reason 取得失败快照，也可从可选的 androidClassic JSON 文本取得原生事件及独立保留的最后一次 Classic 失败。即使页面序列化的 UniError 只有 errCode、errMsg、errSubject，也能通过 androidClassic 导出原生详情。其他平台或旧基座可能没有此字段。

读块和读扇区在同一次原生任务中，会使用当前连接、会话及标签代次下该扇区之前鉴权成功的原 Key，再鉴权一次后立即读取；没有匹配记录时保留原读取路径。恢复鉴权失败则结束本次读取，不自动更换 Key，也不重试失败的 READ 或写入。原 errCode、errMsg、nativeCode、nativeMessage 保持原义，单独鉴权和读块的调用方式保持不变。

两套原示例的“复制日志”会先刷新原生诊断，再把设备/运行版本、原生诊断和按发生顺序排列的页面日志一起导出。刷新失败、异常或 2 秒未返回时仍复制已有日志，并明确标记缓存或缺失状态。页面只显示诊断摘要，完整原生内容保留在复制结果中。新增原生诊断不记录密钥、块内容、APDU 或设备唯一标识；原有业务成功日志仍可能包含读取结果，转发前按业务要求检查。complete 仅表示调用结束，不能代替成功回调。

客户复测时：

1. 更新插件后重新原生联编，或重新制作并安装匹配的 Android 自定义基座；只热更新示例页面无法增加原生日志。
2. 使用实体 Mifare Classic 卡，确认发现标签的技术列表包含 mifareClassic；鸿蒙 HceService 的 ISO-DEP/APDU 模拟不能替代 Classic 卡验收。
3. 点“清空”和“开始会话”；贴卡并保持不动，点击原“Classic 鉴权”，随后点击原“Classic 读块”。默认扇区 1 对应绝对块 4～7，示例默认读块 4。
4. 成功或失败后点击一次“复制日志”，回传整段文字即可，无需另外抓取控制台或先点“接入诊断”。不要退出 App 后再复制，以免进程结束导致内存诊断丢失。

如果此前把示例复制到了自己的业务页面，更新插件后也要同步业务页中的参数日志、诊断查询和复制处理，或直接运行 uni_modules/lizhao-nfc-pro/example/uniappx/index.uvue / uni_modules/lizhao-nfc-pro/example/uniapp/nfc.vue 核对。复制文本第一行的示例路径是固定文字，不表示 App 当前实际运行的页面路径或页面版本；只有倒序业务日志而没有下列诊断头时，需要核对实际使用的复制入口。

复制结果的示例标记为 classic-report-v2；androidClassic.nativeBuildMarker 应为 classic-report-v2+20261009，classicReadCompatibility 应为 same-key-before-read-v1。这三项分别核对页面、原生诊断和读前鉴权策略，不能只根据插件版本号判断基座已更新。单次请求的 Classic诊断= 保留原 classic-log-v1 字段，并增加以下信息：

Android 普通数据块的写前鉴权及写后校验，通过运行诊断返回的构建标记和 classicWriteCompatibility: same-key-write-verify-v1 同时核对；缺少对应标记时不能仅凭页面或插件版本判断能力已进入基座。

原生缓存最多保留 48 条事件，事件文字总量最多 65536 个 UTF-16 字符；单条事件上限 8192 字符。lastFailure 独立保留最后一次 Classic 失败，最多 16384 字符，后续 TTL、成功或会话停止不会覆盖它。droppedEvents、truncatedEvents、truncatedFailures 和事件自身的 truncated 明确说明是否有内容被挤出或截断。页面日志保留最近 80 条，复制结果同时报告省略条数；“清空”只清页面日志，核对失败时应使用请求编号和时间。

鉴权观察记录不能证明射频一直稳定，也不能保证该 Key 拥有块读权限；需要结合原生异常及实际卡的访问位分析。示例 lastDiscovered* 是最后发现记录，不能当作当前标签仍有效；以本次失败快照和接入诊断为准。

作者系列 UTS 插件

以下为作者已上架的 UTS 插件，详情见各市场页面或作者主页。