更新记录

1.0.0（2025-12-16）

新增功能

• ✅ 支持检查设备 NFC 是否可用
• ✅ 支持检查 NFC 是否已开启
• ✅ 支持打开系统 NFC 设置页面
• ✅ 支持监听和读取 NFC 标签
• ✅ 支持写入 NDEF 消息到 NFC 标签
• ✅ 支持 Android、iOS、HarmonyOS 三大平台
• ✅ 支持 uni-app 和 uni-app x 项目
• ✅ 兼容 vue2 和 vue3
• ✅ 使用 UTS 原生开发，性能优异
• ✅ 完整的错误处理和错误码定义
• ✅ 详细的 API 文档和使用示例

平台兼容性

uni-app(3.6.15)

uni-app x(3.6.15)

belay-nfc

一个功能完善的 NFC（近场通信）插件，支持 Android、iOS 和 HarmonyOS 平台。使用 UTS 原生开发，性能优异，提供完整的 NFC 标签读取、写入、监听等功能。

✨ 特性

• 🚀 原生性能：使用 UTS 语言原生开发，性能优异
• 📱 多平台支持：支持 Android、iOS、HarmonyOS 三大平台
• 🔧 功能完整：提供 NFC 检测、监听、读取、写入等完整功能
• 📚 文档完善：提供详细的 API 文档和使用示例
• 💪 类型安全：支持 TypeScript 类型定义（uni-app x）
• 🎯 易于使用：简洁的 API 设计，快速上手

功能特性

• ✅ 检查 NFC 是否可用
• ✅ 检查 NFC 是否开启
• ✅ 打开 NFC 设置
• ✅ 监听 NFC 标签
• ✅ 读取 NFC 标签数据
• ✅ 写入 NFC 标签数据

平台支持

• Android（最低 SDK 21）
• iOS（最低 iOS 12，需要 iPhone 7 及以上设备）
• HarmonyOS

📦 安装

方式一：通过插件市场安装（推荐）

1. 在 DCloud 插件市场 搜索 belay-nfc
2. 点击"使用 HBuilderX 导入插件"
3. 在 HBuilderX 中重新编译项目

方式二：手动安装

1. 下载插件包，将 belay-nfc 目录放置在项目的 uni_modules 目录下
2. 在 HBuilderX 中重新编译项目

版本要求

• HBuilderX 3.6.8 或更高版本
• uni-app 3.6.15 或更高版本
• uni-app x 3.6.15 或更高版本

权限配置

重要提示： 以下权限需要在使用该插件的项目的 manifest.json 文件中进行配置，插件本身不会自动申请这些权限。

Android 平台权限配置

在使用插件的项目的 manifest.json 文件中，添加以下权限配置：

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

说明：

• android.permission.NFC：允许应用使用 NFC 功能
• android.hardware.nfc：声明设备需要 NFC 硬件支持（required="false" 表示非必需，如果设备没有 NFC 硬件，应用仍可安装）

iOS 平台权限配置

在使用插件的项目的 manifest.json 文件中，iOS 平台需要配置 NFC 能力：

1. 在 HBuilderX 中打开项目的 manifest.json
2. 切换到"App模块配置"标签
3. 勾选"NFC（标签读取）"能力
4. 或者在 manifest.json 的源码视图中，确保包含 NFC 相关配置

注意： iOS 的 NFC 功能需要在 Xcode 中配置 Info.plist 的 NFCReaderUsageDescription，说明使用 NFC 的原因。插件已在其配置文件中包含此说明，但您可能需要根据实际使用场景调整描述文本。

HarmonyOS 平台权限配置

HarmonyOS 平台的权限配置需要根据实际使用的 HarmonyOS SDK 版本进行配置。由于 HarmonyOS 与 Android 在权限配置上类似，可以参考 Android 平台的配置方式。

配置说明：

• HarmonyOS 的权限配置方式与 Android 类似
• 需要在项目的 manifest.json 中声明 NFC 相关权限
• 具体配置方式请参考 HarmonyOS 官方文档和您使用的 SDK 版本

参考配置（具体以 HarmonyOS SDK 文档为准）：

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

使用方法

uni-app 项目（vue/nvue）

// 引入插件
import { 
  isNFCAvailable, 
  isNFCEnabled, 
  openNFCSettings,
  startNFCDiscovery,
  stopNFCDiscovery,
  writeNdef
} from "@/uni_modules/belay-nfc"

// 检查 NFC 是否可用
const available = isNFCAvailable()
console.log('NFC 可用:', available)

// 检查 NFC 是否开启
const enabled = isNFCEnabled()
console.log('NFC 已开启:', enabled)

// 打开 NFC 设置
openNFCSettings({
  success: () => {
    console.log('打开设置成功')
  },
  fail: (err) => {
    console.error('打开设置失败:', err)
  }
})

// 开始监听 NFC 标签
startNFCDiscovery({
  success: (res) => {
    console.log('检测到 NFC 标签:', res)
    console.log('标签 ID:', res.id)
    console.log('技术列表:', res.techList)
    console.log('NDEF 消息:', res.ndefMessage)
  },
  fail: (err) => {
    console.error('监听失败:', err)
  }
})

// 停止监听 NFC 标签
stopNFCDiscovery({
  success: () => {
    console.log('停止监听成功')
  }
})

// 写入 NFC 标签
writeNdef({
  message: 'Hello NFC',
  success: () => {
    console.log('写入成功')
  },
  fail: (err) => {
    console.error('写入失败:', err)
  }
})

uni-app x 项目（uvue）

// 引入插件和类型定义
import { 
  isNFCAvailable, 
  isNFCEnabled, 
  openNFCSettings,
  OpenNFCSettingsOptions,
  startNFCDiscovery,
  StartNFCDiscoveryOptions,
  stopNFCDiscovery,
  StopNFCDiscoveryOptions,
  writeNdef,
  WriteNdefOptions,
  NFCTagData
} from "@/uni_modules/belay-nfc"

// 检查 NFC 是否可用
const available: boolean = isNFCAvailable()
console.log('NFC 可用:', available)

// 检查 NFC 是否开启
const enabled: boolean = isNFCEnabled()
console.log('NFC 已开启:', enabled)

// 打开 NFC 设置
let settingsOptions = {
  success: () => {
    console.log('打开设置成功')
  },
  fail: (err: any) => {
    console.error('打开设置失败:', err)
  }
} as OpenNFCSettingsOptions
openNFCSettings(settingsOptions)

// 开始监听 NFC 标签
let discoveryOptions = {
  success: (res: NFCTagData) => {
    console.log('检测到 NFC 标签:', res)
    console.log('标签 ID:', res.id)
    console.log('技术列表:', res.techList)
    if (res.ndefMessage != null) {
      console.log('NDEF 消息:', res.ndefMessage)
    }
  },
  fail: (err: any) => {
    console.error('监听失败:', err)
  }
} as StartNFCDiscoveryOptions
startNFCDiscovery(discoveryOptions)

// 停止监听 NFC 标签
let stopOptions = {
  success: () => {
    console.log('停止监听成功')
  }
} as StopNFCDiscoveryOptions
stopNFCDiscovery(stopOptions)

// 写入 NFC 标签
let writeOptions = {
  message: 'Hello NFC',
  success: () => {
    console.log('写入成功')
  },
  fail: (err: any) => {
    console.error('写入失败:', err)
  }
} as WriteNdefOptions
writeNdef(writeOptions)

API 说明

isNFCAvailable()

检查设备是否支持 NFC 功能。

返回值： boolean - true 表示设备支持 NFC，false 表示不支持

isNFCEnabled()

检查 NFC 是否已开启。

返回值： boolean - true 表示 NFC 已开启，false 表示未开启

openNFCSettings(options)

打开系统的 NFC 设置页面。

参数：

• options.success - 成功回调
• options.fail - 失败回调
• options.complete - 完成回调（无论成功或失败都会调用）

startNFCDiscovery(options)

开始监听 NFC 标签。当检测到 NFC 标签时，会触发 success 回调。

参数：

• options.success - 检测到标签时的回调，参数为 NFCTagData 对象
• options.fail - 失败回调
• options.complete - 完成回调

NFCTagData 对象：

• id: string - 标签的唯一标识符
• techList: string[] - 标签支持的技术列表
• ndefMessage?: string - NDEF 消息内容（如果标签包含 NDEF 数据）

stopNFCDiscovery(options)

停止监听 NFC 标签。

参数：

• options.success - 成功回调
• options.fail - 失败回调
• options.complete - 完成回调

writeNdef(options)

写入 NDEF 消息到 NFC 标签。

参数：

• options.message: string - 要写入的文本消息
• options.success - 成功回调
• options.fail - 失败回调
• options.complete - 完成回调

错误码

注意事项

⚠️ 重要：权限配置

所有 NFC 相关权限必须在使用该插件的项目的 manifest.json 文件中进行配置，插件本身不会自动申请这些权限。 请参考上方的"权限配置"章节进行配置，否则插件功能将无法正常使用。

1. Android 平台：

   • 需要 Android 5.0（API 21）及以上版本
   • 必须在项目的 manifest.json 中配置 NFC 权限（详见"权限配置"章节）
   • 监听 NFC 标签需要在 Activity 前台时进行

2. iOS 平台：

   • 需要 iOS 12 及以上版本
   • 仅支持 iPhone 7 及更新设备
   • 需要在项目的 manifest.json 中配置 NFC 能力（详见"权限配置"章节）
   • iOS 的 NFC 读取需要用户交互，会自动显示读取界面
   • iOS 的 NFC 写入功能有限

3. HarmonyOS 平台：

   • 需要根据实际 HarmonyOS SDK 版本进行调整
   • 需要在项目的 manifest.json 中配置 NFC 权限（详见"权限配置"章节）
   • 部分功能可能需要进一步实现

开发文档

• UTS 语法
• UTS API插件
• UTS uni-app兼容模式组件
• UTS 标准模式组件
• Hello UTS

🎯 使用场景

• 📇 智能门禁：读取 NFC 门禁卡信息
• 🎫 票务系统：读取和验证 NFC 门票
• 🏷️ 商品标签：读取商品 NFC 标签信息
• 📱 设备配对：通过 NFC 快速配对设备
• 🔐 身份验证：NFC 卡片身份验证
• 📖 信息读取：读取 NFC 标签中的文本、URL 等信息

❓ 常见问题

Q: 为什么调用 API 后没有反应？

A: 请检查以下几点：

1. 确认已在 manifest.json 中配置了 NFC 权限（详见"权限配置"章节）
2. 确认设备支持 NFC 功能（Android 5.0+，iOS 12+，iPhone 7+）
3. 确认设备的 NFC 功能已开启
4. 查看控制台是否有错误信息

Q: iOS 平台无法使用 NFC？

A: iOS 平台需要满足以下条件：

1. 设备型号：iPhone 7 及以上
2. iOS 版本：12.0 及以上
3. 已在 HBuilderX 中勾选"NFC（标签读取）"能力
4. 已配置 NFCReaderUsageDescription 隐私描述

Q: Android 平台监听 NFC 标签没有响应？

A: 请检查：

1. 确认应用在前台运行（Android 需要应用在前台才能监听）
2. 确认已调用 startNFCDiscovery 开始监听
3. 确认 NFC 标签格式正确（支持 NDEF 格式）
4. 尝试将 NFC 标签靠近设备 NFC 感应区域

Q: 可以同时监听多个 NFC 标签吗？

A: 不可以。插件采用单次监听模式，检测到一个标签后会自动停止监听。如需继续监听，需要重新调用 startNFCDiscovery。

Q: 支持哪些 NFC 标签格式？

A: 插件主要支持 NDEF（NFC Data Exchange Format）格式的标签，这是最常用的 NFC 标签格式。对于其他格式，可能需要根据具体标签类型进行适配。

📞 技术支持

如有问题或建议，请通过以下方式联系：

• 插件市场：DCloud 插件市场
• 问题反馈：在插件市场页面提交问题或建议

📄 许可证

MIT License

🙏 致谢

感谢使用 belay-nfc 插件！如果这个插件对您有帮助，欢迎在插件市场给予好评和反馈。