更新记录

1.0.0（2026-04-07）

支持检查设备 NFC 是否可用 支持检查 NFC 是否已开启 支持打开系统 NFC 设置页面 支持监听和读取 NFC 标签 支持写入 NDEF 消息到 NFC 标签

平台兼容性

uni-app(4.0)

# sp-nfc-kit

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

功能特性

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

平台支持

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

📦 安装

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

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

方式二：手动安装

1. 下载插件包，将 sp-nfc-kit 目录放置在项目的 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 的原因。插件已在其配置文件中包含此说明，但您可能需要根据实际使用场景调整描述文本。

{
  "app-plus": {
    "distribute": {
         "ios" : {
          "plist" : {
              // NFC权限描述（必填，说明使用NFC的目的）
              "NFCReaderUsageDescription" : "为了读取NFC标签信息，完成设备绑定",
              // NFC支持的协议格式（按需配置）
              "com.apple.developer.nfc.readersession.formats" : [
                  "TAG" // 支持NDEF格式的NFC标签
              ]
          },
          "capabilities" : {
              // 开启NFC硬件权限（部分uniapp版本需配置）
              "nfc" : true
          },
          "dSYMs" : false,
          "privacyDescription" : {
              "NFCReaderUsageDescription" : "APP将会使用NFC功能，获取xxx信息"
          },
          "idfa" : false
      },
    }
  }
}

## 使用方法

### uni-app 项目（vue/nvue）

```javascript
// 引入插件
import { 
  spNfcIsAvailable, 
  spNfcIsEnabled, 
  spNfcOpenSettings,
  spNfcStartScan,
  spNfcStopScan,
  spNfcWriteMessage
} from "@/uni_modules/sp-nfc-kit"

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

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

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

// 开始监听 NFC 标签
spNfcStartScan({
  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 标签
spNfcStopScan({
  success: () => {
    console.log('停止监听成功')
  }
})

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

uni-app x 项目（uvue）

// 引入插件和类型定义
import { 
  spNfcIsAvailable, 
  spNfcIsEnabled, 
  spNfcOpenSettings,
  SpOpenNfcPanelOptions,
  spNfcStartScan,
  SpStartNfcScanOptions,
  spNfcStopScan,
  SpStopNfcScanOptions,
  spNfcWriteMessage,
  SpWriteNfcMessageOptions,
  SpNfcTagPayload
} from "@/uni_modules/sp-nfc-kit"

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

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

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

// 开始监听 NFC 标签
let discoveryOptions = {
  success: (res: SpNfcTagPayload) => {
    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 SpStartNfcScanOptions
spNfcStartScan(discoveryOptions)

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

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

API 说明

spNfcIsAvailable()

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

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

spNfcIsEnabled()

检查 NFC 是否已开启。

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

spNfcOpenSettings(options)

打开系统的 NFC 设置页面。

参数：

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

spNfcStartScan(options)

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

参数：

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

SpNfcTagPayload 对象：

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

spNfcStopScan(options)

停止监听 NFC 标签。

参数：

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

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

🙏 致谢

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