更新记录

1.0.0（2026-03-20） 下载此版本

【v1.0.0】初始版本

  • 基于UTS原生实现，直接访问Android NFC API
  • 支持NFC标签的读取和写入操作
  • 支持NDEF格式数据处理
  • 内置超时检测和错误处理
  • 提供完整的API接口和示例代码

平台兼容性

Android NFC Plugin for uni-app

这是一个基于Android原生UTS的uni-app NFC插件，直接访问Android的NFC API，解决JavaScript层无法获取NFC事件的问题。

功能特性

  • ✅ 基于原生UTS实现
  • ✅ 直接访问Android NFC API
  • ✅ NFC标签写入
  • ✅ NFC标签读取
  • ✅ Toast提示
  • ✅ 完善的错误处理
  • ✅ 日志输出
  • ✅ 超时检测

项目结构

androidnfs/
├── utssdk/
│   ├── app-android/
│   │   ├── index.uts           # UTS实现文件
│   │   ├── manifest.json       # Android原生配置
│   │   └── res/
│   │       └── values/
│   │           └── strings.xml
├── js_sdk/
│   └── index.js              # JavaScript接口
├── package.json                # 插件配置
└── README.md                  # 使用说明

安装方法

1. 复制插件文件

将androidnfs目录复制到项目根目录下：

ShopUniapp/
├── androidnfs/
│   ├── utssdk/
│   ├── js_sdk/
│   ├── package.json
│   └── README.md

2. 配置manifest.json

在项目的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\"/>"
        ]
      }
    }
  }
}

3. 在页面中引用

// 在需要使用NFC的页面中引入
import NFCHelper from '@/androidnfs/js_sdk/index.js'

API文档

NFCHelper.initialize(options)

初始化NFC功能。

参数：

  • options.alwaysRead (Boolean): 是否始终读取，默认false
  • options.isShowToast (Boolean): 是否显示Toast提示，默认true

返回：

  • Promise: 初始化是否成功

示例：

const success = await NFCHelper.initialize({
  alwaysRead: false,
  isShowToast: true
});

if (success) {
  console.log('NFC初始化成功');
  uni.showToast({
    title: 'NFC初始化成功',
    icon: 'success'
  });
}

NFCHelper.writeData(url)

写入NFC标签。

参数：

  • url (String): 要写入的URL数据

返回：

  • Promise: 写入是否成功

示例：

const success = await NFCHelper.writeData('http://example.com');

if (success) {
  console.log('写入成功');
  uni.showToast({
    title: 'NFC标签写入成功',
    icon: 'success'
  });
}

说明：

  • 调用后会显示Toast提示"请将NFC标签靠近手机背面！"
  • 30秒后如果没有检测到NFC标签，会返回超时错误
  • 需要确保NFC标签靠近手机NFC感应区域

NFCHelper.readData()

读取NFC标签。

返回：

  • Promise: 读取是否成功

示例：

const success = await NFCHelper.readData();

if (success) {
  console.log('读取成功');
  uni.showToast({
    title: 'NFC标签读取成功',
    icon: 'success'
  });
}

说明：

  • 调用后会显示Toast提示"请将NFC标签靠近手机背面！"
  • 5秒后如果没有检测到NFC标签，会返回超时错误
  • 需要确保NFC标签靠近手机NFC感应区域
  • 注意：当前版本只支持读取，不支持返回读取到的数据

NFCHelper.destroy()

销毁NFC功能，释放资源。

示例：

NFCHelper.destroy();

使用示例

完整的NFC写入示例

export default {
  data() {
    return {
      nfcInitialized: false,
      writeUrl: ''
    }
  },

  methods: {
    // 初始化NFC
    async initNFC() {
      try {
        const success = await NFCHelper.initialize({
          alwaysRead: false,
          isShowToast: true
        });

        if (success) {
          this.nfcInitialized = true;
          uni.showToast({
            title: 'NFC初始化成功',
            icon: 'success'
          });
        } else {
          uni.showToast({
            title: 'NFC初始化失败',
            icon: 'none'
          });
        }
      } catch (error) {
        console.error('NFC初始化错误:', error);
        uni.showToast({
          title: 'NFC初始化错误',
          icon: 'none'
        });
      }
    },

    // 写入NFC标签
    async writeNFC(url) {
      try {
        if (!this.nfcInitialized) {
          uni.showToast({
            title: '请先初始化NFC',
            icon: 'none'
          });
          return;
        }

        this.writeUrl = url;

        const success = await NFCHelper.writeData(url);

        if (success) {
          uni.showToast({
            title: 'NFC标签写入成功',
            icon: 'success'
          });
        } else {
          uni.showToast({
            title: '写入失败，请重试',
            icon: 'none'
          });
        }
      } catch (error) {
        console.error('NFC写入操作异常:', error);
        uni.showToast({
          title: 'NFC操作失败',
          icon: 'none'
        });
      }
    },

    // 读取NFC标签
    async readNFC() {
      try {
        if (!this.nfcInitialized) {
          uni.showToast({
            title: '请先初始化NFC',
            icon: 'none'
          });
          return;
        }

        const success = await NFCHelper.readData();

        if (success) {
          uni.showToast({
            title: 'NFC标签读取成功',
            icon: 'success'
          });
        } else {
          uni.showToast({
            title: '读取失败，请重试',
            icon: 'none'
          });
        }
      } catch (error) {
        console.error('NFC读取操作异常:', error);
        uni.showToast({
          title: 'NFC操作失败',
          icon: 'none'
        });
      }
    },

    // 销毁NFC
    destroyNFC() {
      try {
        NFCHelper.destroy();
        this.nfcInitialized = false;

        uni.showToast({
          title: 'NFC已关闭',
          icon: 'success'
        });
      } catch (error) {
        console.error('NFC销毁错误:', error);
      }
    },

    // 页面卸载时销毁NFC
    onUnload() {
      if (this.nfcInitialized) {
        this.destroyNFC();
      }
    }
  },

  onUnload() {
    // 页面卸载时销毁NFC
    if (this.nfcInitialized) {
      this.destroyNFC();
    }
  }
}

重要说明

1. UTS插件 vs JavaScript插件

UTS插件（当前实现）：

  • ✅ 直接访问Android原生NFC API
  • ✅ 可以正确处理NFC事件
  • ✅ 可以实现完整的NFC标签读写逻辑
  • ✅ 性能更好，执行效率更高
  • ❌ 需要打包和发布流程

JavaScript插件（之前的实现）：

  • ✅ 简单快速，不需要等待审核
  • ❌ JavaScript层无法直接获取NFC事件
  • ❌ 无法实现完整的NFC标签检测逻辑

2. 当前实现状态

已实现：

  • ✅ UTS原生NFC API访问
  • ✅ NFC初始化和检测
  • ✅ Toast提示
  • ✅ 超时检测
  • ✅ 错误处理
  • ✅ 日志输出

待完善：

  • ⚠️ JavaScript层与UTS层的通信机制
  • ⚠️ NFC标签检测和写入逻辑的测试
  • ⚠️ 读取功能的完善（返回读取到的数据）

3. 发布到插件市场

如果要发布到uni-app插件市场，需要：

  1. 打包插件：使用HBuilderX打包插件
  2. 上传到插件市场：登录DCloud开发者中心
  3. 审核通过：等待DCloud审核
  4. 发布：插件发布后，其他开发者可以搜索和使用

4. 本地测试

在发布前，建议先进行本地测试：

  1. 测试NFC初始化
  2. 测试NFC标签写入
  3. 测试NFC标签读取
  4. 测试错误处理
  5. 测试超时检测

注意事项

1. 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\"/>"
        ]
      }
    }
  }
}

2. NFC标签要求

  • 确保NFC标签已格式化
  • 确保NFC标签支持NDEF格式
  • 建议使用NFC Type 2或Type 4标签
  • 确保NFC标签靠近手机NFC感应区域

3. 错误处理

所有NFC操作都可能失败，需要完善的错误处理：

try {
  await NFCHelper.writeData(url);
} catch (error) {
  console.error('NFC操作失败:', error);
  uni.showToast({
    title: '操作失败',
    icon: 'none'
  });
}

4. 性能优化

  • 避免频繁初始化和销毁NFC
  • 在页面卸载时及时销毁NFC
  • 合理设置超时时间
  • 避免在不需要NFC的页面初始化NFC

5. 调试

使用adb logcat查看Android原生日志：

adb logcat -s NFCHelper

故障排除

问题1: NFC未初始化

症状： 提示"NFC未初始化"

解决方案：

  1. 检查设备是否支持NFC
  2. 检查NFC是否已启用
  3. 检查Android权限是否已授予

问题2: 写入/读取超时

症状： 提示"写入超时"或"读取超时"

解决方案：

  1. 确保NFC标签靠近手机NFC感应区域
  2. 检查NFC标签是否正常工作
  3. 增加超时时间
  4. 检查NFC标签是否支持NDEF格式

问题3: 权限被拒绝

症状： 提示"权限被拒绝"

解决方案：

  1. 检查manifest.json中的权限配置
  2. 引导用户手动授予权限
  3. 重启应用

版本历史

v1.0.0 (2024-03-19)

  • ✅ 初始版本发布
  • ✅ 基于UTS原生实现
  • ✅ 支持NFC初始化
  • ✅ 支持NFC标签写入
  • ✅ 支持NFC标签读取
  • ✅ Toast提示
  • ✅ 错误处理
  • ✅ 日志输出
  • ✅ 超时检测

许可证

MIT License

联系方式

如有问题或建议，请联系开发团队。

致谢

感谢使用本NFC插件！

隐私、权限声明

1. 本插件需要申请的系统权限列表：

1. android.permission.NFC - 访问NFC硬件权限，用于NFC标签的读取、写入和检测 2. android.hardware.nfc - NFC硬件特性声明，标识应用需要NFC功能支持

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

本插件不采集任何用户数据，不发送数据到任何服务器。 本插件仅在本地设备上操作NFC硬件，所有NFC标签的读取和写入操作均在设备本地完成，不涉及网络通信，不收集、不传输、不存储任何用户个人信息或敏感数据。

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

许可协议

MIT协议
评论列表 撰写评论 向官方投诉

暂无用户评论。