更新记录

1.4.7（2026-03-03）

• 修复ios端大小端问题

1.4.6（2026-03-03）

• 优化ios云打包问题

1.4.5（2026-03-02）

-ios 打开设置优化

平台兼容性

uni-app(4.87)

uni-app x(4.87)

ry-nfc

UniApp / UniApp X 通用 NFC 读写插件，支持 Android NDEF 协议和 iOS ISO14443 + ISO15693 双协议。

平台支持

安装

将 ry-nfc 目录复制到项目 uni_modules 目录下。

配置

Android

在 manifest.json 中添加 NFC 权限：

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<uses-permission android:name=\"android.permission.NFC\"/>",
          "<uses-feature android:name=\"android.hardware.nfc\" android:required=\"true\"/>"
        ]
      }
    }
  }
}

iOS

1. 在 HBuilderX 中勾选 NFC 模块
2. Apple Developer 后台开启 NFC Tag Reading 能力
3. Info.plist 添加：

<key>NFCReaderUsageDescription</key>
<string>需要NFC权限用于读写NFC标签</string>

使用示例

uni-app 模式 (.vue)

<script>
import {
  initNFC,
  readNDEF,
  writeText,
  closeNFC,
  openNFCSettings
} from '@/uni_modules/ry-nfc';

export default {
  async onLoad() {
    try {
      await initNFC();
      console.log('NFC 初始化成功');
    } catch (e) {
      console.error(e.errMsg);
    }
  },

  onUnload() {
    closeNFC();
  },

  methods: {
    async read() {
      try {
        const res = await readNDEF();
        console.log('类型:', res.type);
        console.log('内容:', res.content);
      } catch (e) {
        console.error(e.errMsg);
      }
    }
  }
};
</script>

uni-app x 模式 (.uvue)

<script lang="uts">
import {
  initNFC,
  readNDEF,
  writeText,
  closeNFC,
  NFCReadResult,
  NFCError,
  openNFCSettings,
} from '@/uni_modules/ry-nfc';

export default {
  async onLoad() {
    try {
      await initNFC();
      console.log('NFC 初始化成功');
    } catch (e) {
      const err = e as NFCError;
      console.error(err.errMsg);
    }
  },

  onUnload() {
    closeNFC();
  },

  methods: {
    async read() {
      try {
        const res = await readNDEF();
        console.log('类型:', res.type);
        console.log('内容:', res.content);
      } catch (e) {
        const err = e as NFCError;
        console.error(err.errMsg);
      }
    }
  }
};
</script>

API 文档

initNFC()

初始化 NFC 模块。

initNFC(): Promise<NFCResult>

type NFCResult = {
  code: number   // 0=成功
  msg: string
}

getNFCStatus()

获取 NFC 状态。

getNFCStatus(): NFCStatus

type NFCStatus = {
  isReady: boolean      // 已初始化
  isListening: boolean  // 监听中
  isSupported: boolean  // 设备支持
  isEnabled: boolean    // 已开启
}

readNDEF()

读取 NFC 标签。

readNDEF(): Promise<NFCReadResult>

type NFCReadResult = {
  type: string     // text | uri | unknown
  content: string  // 内容
  raw: string      // 原始数据(十六进制)
  tagId: string    // 标签ID
}

writeText(options)

写入文本。

writeText(options: WriteTextOptions): Promise<NFCResult>

type WriteTextOptions = {
  text: string       // 文本内容
  language?: string  // 语言代码，默认 "en"
}

writeUri(options)

写入 URI。

writeUri(options: WriteUriOptions): Promise<NFCResult>

type WriteUriOptions = {
  uri: string  // http/https/tel/mailto
}

startListenNFC(callback)

开始监听。

startListenNFC(callback: NFCListenCallback): void

type NFCListenCallback = (result: NFCReadResult | NFCError) => void

stopListenNFC()

停止监听。

stopListenNFC(): void

closeNFC()

关闭 NFC 模块。

closeNFC(): void

cancelOperation()

取消当前操作。

cancelOperation(): void

错误处理

type NFCError = {
  errCode?: number
  errMsg: string
}

目录结构

ry-nfc/
├── index.uts                       # 入口 + 类型声明
├── interface.uts                   # 内部类型
├── package.json                    # 配置
├── README.md                       # 文档
└── utssdk/
    ├── app-android/
    │   ├── index.uts              # Android 实现
    │   └── config.json            # Android 配置
    └── app-ios/
        ├── index.uts              # iOS 实现
        └── config.json            # iOS 配置
    └── app-harmony/
        ├── index.uts              # HarmonyOS 实现
        └── config.json            # HarmonyOS 配置

注意事项

1. 必须在真机上测试
2. 标签距离建议 1-2cm
3. 页面销毁时调用 closeNFC()
4. iOS 会话有超时限制（约60秒）
5. Android 仅支持 NDEF 协议标签

版本历史

• 1.3.0: 同时支持 uni-app 和 uni-app x
• 1.2.0: 重构，符合 UTS 插件规范
• 1.1.0: 添加类型定义
• 1.0.0: 初始版本