更新记录

1.2.8（2026-09-07）

• 修复 Android：success/fail 回调 ClassCast（扁平 Option 不可强转为 BaseOption；入口去掉 coerce 重建）
• .vue 直接传对象；.uvue 须 as XxxOption；须重打自定义基座并云端传统打包
• 不传参行为与上一版兼容

1.2.7（2026-09-07）

• 优化 uni-app x：入口将对象字面量归一化为 Option，业务页可直接传对象调用 API，无需再写 as XxxOption
• 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
• 不传参行为与上一版兼容

1.2.6（2026-09-06）

• 修复 App 端成功回调与驱动稳定性：去掉 undefined、可变属性强制解包改为局部拷贝；iOS BLE 状态/特性用 Number.from
• 修复 Android 运行时 ClassCastException：成功回调与 onTagDiscovered 结果改为 UTSJSONObject 别名，避免强转为独立 Result 类型
• 修复标签发现回调字段读写：uid/techList 用会话局部变量，避免 UTSJSONObject 动态属性依赖
• 修复 invoke 回调判空调用；可选 number 去掉 undefined 联合；部分 Android 原生返回值改 Number.from、可变属性局部拷贝
• 使用须制作自定义基座，并走云端传统打包（不支持离线打包、安心打包）
• 【务必使用此版本及以上版本打包使用，低版本存在缺陷】

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-nfcndef 使用说明

轻量 NFC NDEF 读写插件，适用于门禁、资产标签、点检等贴靠读写场景。

当前版本：1.2.8

• Android / iOS / 鸿蒙（含 uni-app x 鸿蒙）：能力检测、前台会话、UID、Text / URI / MIME / Smart Poster / Empty 读写辅助
• Android / 鸿蒙：空白标签格式化写入、Ultralight / NTAG 页读（iOS 见能力矩阵）
• 不做微信小程序、不做 HCE 卡模拟、不做完整 ISO-DEP 透传工具

建议调用顺序：getNfcCapabilities / getNfcStatus → startNfcSession → 贴靠标签 → getNdefStatus（写入前可选）→ readNdef / writeNdef → stopNfcSession。各异步方法均支持 success / fail / complete；fail 含 errCode / errMsg。

1. 环境要求

• HBuilderX 4.11 及以上
• uni-app Vue3（App-vue / App-nvue）或 uni-app x（App-Android / App-iOS / App-鸿蒙）
• 支持：App-Android、App-iOS、App-鸿蒙（uni-app 与 uni-app x）
• 不支持：H5、微信及其它小程序
• Android 最低 API：21；iOS 最低 12；鸿蒙最低 API：12
• App 真机调试须制作自定义基座；正式发版须购买授权后走云端传统打包
• 授权绑定唯一 appid + 包名
• 真机须具备 NFC 硬件并开启系统 NFC

2. 安装与引入

将插件目录放入工程的 uni_modules/breao-nfcndef，或从插件市场导入后同步。

import {
  getNfcCapabilities,
  getNfcStatus,
  startNfcSession,
  stopNfcSession,
  onTagDiscovered,
  offTagDiscovered,
  readNdef,
  buildTextRecord,
  buildUriRecord,
  buildMimeRecord,
  buildSmartPosterRecord,
  buildEmptyRecord,
  writeNdef,
  formatAndWriteNdef,
  getNdefStatus,
  scanTagOnce,
  makeNdefReadOnly,
  readUltralightPages,
  // 同步协议辅助（可选）
  bytesToHex,
  hexToBytes,
  createTextRecord,
  createUriRecord,
  createMimeRecord,
  createSmartPosterRecord,
  createEmptyRecord,
  parseTextPayload,
  parseUriPayload,
  flattenSmartPoster,
  buildNdefMessage,
} from '@/uni_modules/breao-nfcndef'

3. API

3.1 能力与状态

getNfcCapabilities({
  success(res) {
    // hasHardware / canRead / canWrite / canFormat / canReadUltralightPages / platform
  },
})

getNfcStatus({
  success(res) {
    // enabled / hasHardware / sessionActive
  },
})

3.2 会话与标签发现

startNfcSession({
  alertMessage: '请将标签贴近手机',
  invalidateAfterFirstRead: false,
  onTagDiscovered(tag) {
    // tag.uid / techList / atqa? / sak?
  },
  success() {},
  fail(err) { console.error(err.errCode, err.errMsg) },
})

onTagDiscovered({ callback(tag) { console.log(tag.uid) } })
offTagDiscovered()
stopNfcSession({ success() {} })

会话参数见 §4。

3.3 NDEF 读 / 写

readNdef({
  success(res) {
    // res.message.records；Smart Poster 可展平为 text / uri
  },
})

// build* 成功回调同时含 record 与 records: [record]，单条写入可任选其一
buildTextRecord({ text: 'hello', language: 'zh', success(res) { /* res.record / res.records */ } })
buildUriRecord({ uri: 'https://example.com', success(res) { /* res.record / res.records */ } })
buildMimeRecord({ mimeType: 'application/json', text: '{"id":1}', success(res) { /* res.record / res.records */ } })
buildSmartPosterRecord({ uri: 'https://example.com', text: '标题', language: 'zh', success(res) { /* res.record / res.records */ } })

// 多 record：Text + URI 同条消息写入
buildTextRecord({
  text: '资产A',
  language: 'zh',
  success(t) {
    buildUriRecord({
      uri: 'https://example.com/a',
      success(u) {
        writeNdef({ records: [t.record, u.record], success() {} })
      },
    })
  },
})

// 显式擦写：写入 Empty 记录；禁止 writeNdef({ records: [] })（会 9100006，无隐式擦除）
buildEmptyRecord({
  success(built) {
    writeNdef({ records: built.records, success() {} })
  },
})

formatAndWriteNdef({
  records: [/* … */],
  success() {}, // 空白格式化写入；iOS 可能返回明确不支持码
})

3.4 标签 NDEF 状态

在会话内、标签已贴靠后调用；写入前可查询容量与可写性，避免载荷超限或只读标签写入失败。

getNdefStatus({
  success(res) {
    // res.isFormatted：是否已格式化为 NDEF
    // res.canWrite：当前是否可写
    // res.maxSize：可写最大字节数（未格式化时可能为 0）
    // res.isReadOnly：是否只读（与 canWrite 互斥语义）
  },
  fail(err) { console.error(err.errCode, err.errMsg) },
})

3.5 协议辅助（同步）

不依赖 NFC 会话，可在业务侧自组 NfcNdefRecord / NfcNdefMessage 后再 writeNdef：

3.6 一次性扫描 / 只读 / 页读

scanTagOnce({
  timeoutMs: 15000,
  autoReadNdef: true,
  success(res) {
    // 含 tag 信息；autoReadNdef 时含 message
  },
})

makeNdefReadOnly({
  confirm: true, // 必须为 true，否则 9100012；操作不可逆
  success() {},
})

readUltralightPages({
  pageOffset: 0,
  pageCount: 4,
  success(res) {
    // 页数据；仅 Android / 鸿蒙部分标签
  },
})

4. 可配置项

不传参即用默认值。buildEmptyRecord 无额外字段。

5. 完整示例

import {
  getNfcStatus,
  startNfcSession,
  getNdefStatus,
  createTextRecord,
  createUriRecord,
  buildNdefMessage,
  writeNdef,
  stopNfcSession,
} from '@/uni_modules/breao-nfcndef'

getNfcStatus({
  success(st) {
    if (!st.enabled) {
      console.warn('请开启系统 NFC')
      return
    }
    startNfcSession({
      alertMessage: '请将标签贴近手机',
      invalidateAfterFirstRead: false,
      onTagDiscovered() {
        getNdefStatus({
          success(nd) {
            if (!nd.canWrite) {
              console.warn('标签不可写')
              return
            }
            const textRec = createTextRecord('资产A', 'zh')
            const uriRec = createUriRecord('https://example.com/asset/a')
            const msg = buildNdefMessage([textRec, uriRec])
            writeNdef({
              records: msg.records,
              success() { stopNfcSession({}) },
              fail(err) { console.error(err.errCode, err.errMsg) },
            })
          },
        })
      },
      fail(err) { console.error(err.errCode, err.errMsg) },
    })
  },
})

6. 权限

请在应用 manifest / 隐私弹窗中按需声明，并说明用于本机与用户贴靠的 NFC 标签之间进行 NDEF 读写。

7. 错误码（910）

8. 平台注意

• uni-app x（.uvue）：须对入参使用 as XxxOption（见官方 error17）；.vue 可直接传对象。须使用 1.2.8+ 并重打自定义基座
• 真机须具备 NFC 并开启；模拟器通常不可用
• iOS 依赖系统 NFC 弹层；详见下方能力矩阵
• Android / 鸿蒙支持空白格式化写入与部分 Ultralight / NTAG 页读
• makeNdefReadOnly 不可逆，标签写入后将无法再次修改，调用前须 confirm: true 并提示用户
• 读写交替场景建议 invalidateAfterFirstRead: false，避免首次读后会话被系统关闭
• 擦写语义：writeNdef({ records: [] }) / formatAndWriteNdef({ records: [] }) 一律参数非法（9100006），不会依赖厂商「空数组即擦除」；须 buildEmptyRecord 得到 Empty 记录后再写入

8.1 能力矩阵