更新记录

1.0.0（2026-08-13）

• 首版：Android / iOS / 鸿蒙轻量 NDEF（微信小程序不支持）
• 能力检测与系统开关：getNfcCapabilities / getNfcStatus
• 前台会话：startNfcSession / stopNfcSession；标签发现含 UID 与 tech 列表
• NDEF 读：Text / URI / MIME；Smart Poster 展平为 text+uri
• NDEF 写：buildTextRecord / buildUriRecord / writeNdef
• Android / 鸿蒙：空白格式化写入、Ultralight/NTAG 页读；iOS 对应能力返回明确错误码
• getNdefStatus 可写性与最大长度；scanTagOnce 一次性扫描
• makeNdefReadOnly 须显式确认（不可逆）；统一错误码 910xxxxx
• 支持 App-nvue / uni-app x（x 下鸿蒙不支持）

平台兼容性

uni-app(4.11)

uni-app x(4.11)

breao-nfcndef 使用说明

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

当前版本：1.0.0

• Android / iOS / 鸿蒙：能力检测、前台会话、UID、Text / URI 读写
• Android / 鸿蒙：空白标签格式化写入、Ultralight / NTAG 页读
• 不做微信小程序、不做 HCE 卡模拟、不做完整 ISO-DEP 透传工具

建议调用顺序：getNfcCapabilities / getNfcStatus → startNfcSession → 贴靠标签 → 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-Android、App-iOS、App-鸿蒙（仅 uni-app）
• 不支持：H5、微信及其它小程序；uni-app x 下鸿蒙不支持
• 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,
  writeNdef,
  formatAndWriteNdef,
  getNdefStatus,
  scanTagOnce,
  makeNdefReadOnly,
  readUltralightPages,
} 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: '请将标签贴近手机',
  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
  },
})

buildTextRecord({ text: 'hello', language: 'zh', success(res) { /* res.record */ } })
buildUriRecord({ uri: 'https://example.com', success(res) { /* res.record */ } })

writeNdef({ records: [/* build* 返回的 record */], success() {} })

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

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

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. 可配置项

不传参即用默认值。

5. 完整示例

import {
  getNfcStatus,
  startNfcSession,
  readNdef,
  buildTextRecord,
  writeNdef,
  stopNfcSession,
} from '@/uni_modules/breao-nfcndef'

getNfcStatus({
  success(st) {
    if (!st.enabled) {
      console.warn('请开启系统 NFC')
      return
    }
    startNfcSession({
      alertMessage: '请将标签贴近手机',
      invalidateAfterFirstRead: false,
      onTagDiscovered() {
        readNdef({
          success(msg) {
            console.log(msg)
            buildTextRecord({
              text: 'hello-nfc',
              success(built) {
                writeNdef({
                  records: [built.record],
                  success() { stopNfcSession({}) },
                })
              },
            })
          },
        })
      },
      fail(err) { console.error(err.errCode, err.errMsg) },
    })
  },
})

6. 权限

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

7. 错误码（910）

8. 平台注意

• 真机须具备 NFC 并开启；模拟器通常不可用
• iOS 依赖系统 NFC 弹层；空白格式化与 Ultralight 页读可能返回明确不支持码
• Android / 鸿蒙支持空白格式化写入与部分 Ultralight / NTAG 页读
• makeNdefReadOnly 不可逆，标签写入后将无法再次修改，调用前须 confirm: true 并提示用户
• 读写交替场景建议 invalidateAfterFirstRead: false，避免首次读后会话被系统关闭