更新记录

0.1.0（2026-03-25） 下载此版本

初版版，实现读卡功能

平台兼容性

uni-app(3.7.9)

nfc-card-reader 插件

Android 真机专用的 NFC 读 UID 页面型插件，提供一个可直接 navigateTo 的页面 /uni_modules/nfc-card-reader/pages/read-card/index。页面会检测 NFC 支持、自动开启监听，读取到卡片 UID 后通过 eventChannel 返回并自动关闭。

接入步骤

1. 将本插件拷贝或通过 DCloud 插件市场安装到宿主项目的 uni_modules/ 目录下。
2. 在宿主项目 pages.json 中注册页面 /uni_modules/nfc-card-reader/pages/read-card/index。
3. 宿主页面通过 uni.navigateTo 打开该页面，读取成功后会自动 navigateBack。
4. 调用方通过 eventChannel 监听 success 事件，收到数据 { cardNo, rawId, timestamp }。

仅支持 Android 原生 App 真机调试/打包，不支持 iOS、H5、小程序。建议使用最新 HBuilderX 打开项目并使用 UTS 原生插件编译链路构建。

调试提示：当检测到设备/构建环境不支持 NFC 并且处于开发调试模式（process.env.NODE_ENV !== 'production'）时，插件会返回一个 mock UID，帮助在无硬件环境下联调；正式包中会直接提示错误，不再返回模拟数据。

Android 权限与真机调试

• Manifest 配置：确保宿主 manifest.json 或 AndroidManifest.xml 含有 android.permission.NFC 与 <uses-feature android:name="android.hardware.nfc" android:required="true" />；同时在 MainActivity 上配置 intent-filter + tech-list（详见下方示例）。
• 真机步骤：使用 HBuilderX 自定义基座或真机打包运行 APP-PLUS，首次安装后在系统设置中手动开启 NFC，再运行首页 navigateTo 插件页面进行读卡测试。
• 打开手机 NFC：大部分机型需要到 “设置 -> 更多连接方式/连接与共享 -> NFC” 打开，也可在下拉快捷开关中开启，读取时请保持屏幕亮起并让卡片贴近手机背部 NFC 区域。

本仓库根目录已经是一个完整的 uni-app 示例工程（pages/index/index.vue 为入口），可直接在 HBuilderX 中运行到 Android 真机验证插件页面 /uni_modules/nfc-card-reader/pages/read-card/index。

pages.json 示例

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {}
    },
    {
      "path": "uni_modules/nfc-card-reader/pages/read-card/index",
      "style": {
        "navigationBarTitleText": "NFC 读卡"
      }
    }
  ]
}

调用示例

uni.navigateTo({
  url: '/uni_modules/nfc-card-reader/pages/read-card/index',
  success(res) {
    const eventChannel = res.eventChannel;
    eventChannel.once('success', (data) => {
      console.log('NFC UID:', data.cardNo, data);
    });
    eventChannel.once('error', (err) => {
      console.warn('NFC 读取失败', err);
    });
  }
});

宿主项目需要注意的 Android 配置

• AndroidManifest.xml 权限/能力：

  <uses-permission android:name="android.permission.NFC" />
  <uses-feature android:name="android.hardware.nfc" android:required="true" />

• MainActivity（或对应壳 Activity）需要声明 NFC 前台分发的 intent-filter，示例：

  <activity android:name=".MainActivity" ...>
  <intent-filter>
    <action android:name="android.nfc.action.TECH_DISCOVERED" />
    <action android:name="android.nfc.action.TAG_DISCOVERED" />
    <category android:name="android.intent.category.DEFAULT" />
  </intent-filter>
  <intent-filter>
    <action android:name="android.nfc.action.NDEF_DISCOVERED" />
    <category android:name="android.intent.category.DEFAULT" />
    <!-- 根据业务配置 data scheme/type -->
    <!-- <data android:mimeType="text/plain" /> -->
  </intent-filter>
  <meta-data
    android:name="nfc-tech-list"
    android:resource="@xml/nfc_tech_filter" />
  </activity>

• res/xml/nfc_tech_filter.xml（或 HBuilderX nativePackages/res/xml/）示例：

  <?xml version="1.0" encoding="utf-8"?>
  <resources xmlns:android="http://schemas.android.com/apk/res/android">
  <tech-list>
    <tech>android.nfc.tech.NfcA</tech>
  </tech-list>
  <tech-list>
    <tech>android.nfc.tech.NfcB</tech>
  </tech-list>
  <tech-list>
    <tech>android.nfc.tech.IsoDep</tech>
  </tech-list>
  <tech-list>
    <tech>android.nfc.tech.MifareClassic</tech>
  </tech-list>
  <tech-list>
    <tech>android.nfc.tech.MifareUltralight</tech>
  </tech-list>
  <tech-list>
    <tech>android.nfc.tech.NfcV</tech>
  </tech-list>
  </resources>

需要在 HBuilderX 中确认/补充的点：

1. TODO: 确认 UTSAndroid.getAppActivity()、UTSAndroid.onAppActivityNewIntent 等 Hook 名称及可用性（不同 HBuilderX 版本可能差异）。
2. TODO: PendingIntent Flag (FLAG_MUTABLE) 与 targetSdk 版本关系，如不支持需替换。
3. TODO: 如果宿主使用 manifest.json 的 app-plus.distribute.android.features.nfc 开关，请确保开启。

Android 真机调试提示

1. 开启 NFC：进入手机“设置 -> 连接与共享（或更多连接方式） -> NFC”并打开；部分品牌在系统下拉快捷开关中提供 NFC 图标，也需置为开启状态。
2. 确认权限/硬件声明：确保 manifest.json 中包含 android.permission.NFC 与 <uses-feature android:name="android.hardware.nfc" android:required="true" />，否则真机调试时系统可能直接禁用或在安装阶段提示不兼容。
3. 真机运行注意事项：使用 HBuilderX 打包/运行到 Android 真机的 APP-PLUS 环境，基座需支持 plus.android 原生能力（推荐使用自定义基座）；若控制台提示“当前运行基座不支持原生能力”，请重新生成包含插件代码的调试基座。
4. 读卡姿势：读取前保持屏幕亮起，将卡片靠近手机背部的 NFC 区域，必要时关闭其他默认支付/门禁应用以避免 NFC Intent 被抢占。

详见 example-host-usage.md 获取更多示例。

发布与示例工程说明

1. 将 uni_modules/nfc-card-reader 发布到插件市场

1. 确认 uni_modules/nfc-card-reader/package.json 中的 id、version、dcloudext 信息与插件市场要求一致。
2. 打开 HBuilderX -> 工具 -> 发布 -> 原生插件，选择 uni_modules/nfc-card-reader 目录，按照向导上传（若使用命令行，可打包该目录为 zip 上传）。
3. 发布前请再次检查 readme.md 中的 TODO，注明宿主需补充的 AndroidManifest 配置，并用真机测试页面 /uni_modules/nfc-card-reader/pages/read-card/index 的跳转行为。
4. 插件市场上线后，其他项目只需安装到 uni_modules/，在 pages.json 注册并 navigateTo 即可使用。

2. 运行当前示例工程

1. 将整个项目目录导入/打开到 HBuilderX，确保根目录包含 pages.json、manifest.json、package.json。
2. 使用 HBuilderX 选择运行 -> 运行到 Android App 真机，首页 pages/index/index 会展示“打开读卡器”按钮并跳转到插件页面。
3. 读取成功后，首页通过 eventChannel 接收 success 事件并展示 cardNo；读取失败或 mock 时会提示错误信息。

3. 发布为项目模板

• 如果需要把当前完整工程发布为模板，保留根目录 package.json（已提供项目名称/描述），在 HBuilderX 中选择 工具 -> 发布 -> 项目模板，按提示上传即可。模板使用者将自动获得插件源码及示例页面。
• 发布模板后，如需同步更新插件市场版本，记得同步更新 uni_modules/nfc-card-reader 目录并重新发布，以保证插件与示例项目一致。