NFC

GitHub npm crates.io

API Reference

在 Android 和 iOS 上读取和写入 NFC 标签。

支持的平台

This plugin requires a Rust version of at least 1.77.2

Platform	Level	Notes
windows
linux
macos
android
ios

设置

安装 nfc 插件以开始使用。

自动

使用项目的包管理器添加依赖项：

npm

npm run tauri add nfc

yarn

yarn run tauri add nfc

pnpm

pnpm tauri add nfc

bun

bun tauri add nfc

cargo

cargo tauri add nfc

手动

1. 在 src-tauri 文件夹中运行以下命令，将插件添加到 Cargo.toml 中的项目依赖项中：

   cargo add tauri-plugin-nfc --target 'cfg(any(target_os = "android", target_os = "ios"))'

2. 修改 lib.rs 以初始化插件：

   src-tauri/src/lib.rs

   #[cfg_attr(mobile, tauri::mobile_entry_point)]
   pub fn run() {
       tauri::Builder::default()
           .setup(|app| {
               #[cfg(mobile)]
               app.handle().plugin(tauri_plugin_nfc::init());
               Ok(())
           })
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }

3. 使用你喜欢的 JavaScript 包管理器安装 JavaScript Guest 绑定：

   npm

   npm install @tauri-apps/plugin-nfc

   yarn

   yarn add @tauri-apps/plugin-nfc

   pnpm

   pnpm add @tauri-apps/plugin-nfc

   deno

   deno add npm:@tauri-apps/plugin-nfc

   bun

   bun add @tauri-apps/plugin-nfc

配置

NFC 插件需要 iOS 的本机配置。

iOS

要在 iOS 上访问 NFC API，你必须调整目标 iOS 版本，在 Info.plist 文件中配置使用描述并将 NFC 功能添加到你的应用程序。

目标 iOS 版本

NFC 插件需要 iOS 14+。这是使用 Tauri CLI v2.8 及更高版本创建的 Tauri 应用程序的默认设置，但你可以编辑 Xcode 项目进行配置。

在 src-tauri/gen/apple/<project-name>.xcodeproj/project.pbxproj 文件中，将所有 IPHONEOS_DEPLOYMENT_TARGET 属性设置为 14.0：

/* Begin XCBuildConfiguration section */
    <random-id> /* release */ = {
      isa = XCBuildConfiguration;
      buildSettings = {
        ...
        IPHONEOS_DEPLOYMENT_TARGET = 14.0;
      };
      name = release;
    };
    <random-id> /* debug */ = {
      isa = XCBuildConfiguration;
      buildSettings = {
        ...
        IPHONEOS_DEPLOYMENT_TARGET = 14.0;
      };
      name = debug;
    };

或者，你可以在 Xcode 的 General > Minimum Deployments > iOS 配置中设置部署目标。

Info.plist

在 iOS 上，NFC 插件需要 NFCReaderUsageDescription 信息属性列表值，该值应描述你的应用为何需要扫描或写入 NFC 标签。

在 src-tauri/Info.ios.plist 文件中，添加以下代码段：

src-tauri/Info.ios.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NFCReaderUsageDescription</key>
    <string>读取和写入各种 NFC 标签</string>
  </dict>
</plist>

NFC 功能

此外，iOS 要求 NFC 功能与你的应用程序相关联。

可以在 Xcode 的项目配置的 “Signing & Capabilities” 选项卡中添加该功能，方法是单击 ”+ Capability” 按钮并选择 “Near Field Communication Tag Reading” 功能（有关更多信息，请参阅 向目标添加功能） 或者通过将以下配置添加到 gen/apple/<app-name>_iOS/<app-name>_iOS.entitlements 文件中：

gen/apple/<app-name>_iOS/<app-name>_iOS.entitlements

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.apple.developer.nfc.readersession.formats</key>
  <array>
    <string>TAG</string>
  </array>
</dict>
</plist>

用法

NFC 插件在 JavaScript 和 Rust 中均可用，允许你扫描和写入 NFC 标签。

检查是否支持 NFC

并非每台移动设备都有扫描 NFC 标签的功能，因此你应该在使用扫描和写入 API 之前检查可用性。

JavaScript

import { isAvailable } from '@tauri-apps/plugin-nfc';

const canScanNfc = await isAvailable();

Rust

tauri::Builder::default()
  .setup(|app| {
    #[cfg(mobile)]
    {
      use tauri_plugin_nfc::NfcExt;

      app.handle().plugin(tauri_plugin_nfc::init());

      let can_scan_nfc = app.nfc().is_available()?;
    }
    Ok(())
  })

扫描 NFC 标签

该插件可以扫描通用 NFC 标签或带有 NDEF (NFC Data Exchange Format) 消息的 NFC 标签， 这是在 NFC 标签中封装类型化数据的标准格式。

JavaScript

import { scan } from '@tauri-apps/plugin-nfc';

const scanType = {
  type: 'ndef', // 或 'tag',
};

const options = {
  keepSessionAlive: false,
  // 配置在 iOS 上 "扫描 NFC" 对话框中显示的消息
  message: '扫描 NFC 标签',
  successMessage: 'NFC 标签扫描成功',
};

const tag = await scan(scanType, options);

Rust

tauri::Builder::default()
  .setup(|app| {
    #[cfg(mobile)]
    {
      use tauri_plugin_nfc::NfcExt;

      app.handle().plugin(tauri_plugin_nfc::init());

      let tag = app
        .nfc()
        .scan(tauri_plugin_nfc::ScanRequest {
            kind: tauri_plugin_nfc::ScanKind::Ndef {
                mime_type: None,
                uri: None,
                tech_list: None,
            },
            keep_session_alive: false,
        })?
        .tag;
    }
    Ok(())
  })

注意

keepSessionAlive 选项可用于稍后直接写入扫描的 NFC 标签。

如果你不提供该选项，则会在下一次 write() 调用时重新创建会话， 这意味着应用程序将尝试重新扫描标签。

过滤器

NFC 扫描器还可以使用特定的 URI 格式、MIME 类型或 NFC 标签技术过滤标签。 在这种情况下，扫描将仅检测与提供的过滤器匹配的标签。

注意

过滤仅在 Android 上可用，因此你应该始终检查扫描的 NFC 标签内容。

MIME 类型区分大小写，必须使用小写字母提供。

JavaScript

import { scan, TechKind } from '@tauri-apps/plugin-nfc';

const techLists = [
  // 捕获任何使用 NfcF 的内容
  [TechKind.NfcF],
  // 捕获所有带有 NDEF 负载的 MIFARE Classics
  [TechKind.NfcA, TechKind.MifareClassic, TechKind.Ndef],
];

const tag = await scan({
  type: 'ndef', // 或 'tag'
  mimeType: 'text/plain',
  uri: {
    scheme: 'https',
    host: 'my.domain.com',
    pathPrefix: '/app',
  },
  techLists,
});

Rust

tauri::Builder::default()
  .setup(|app| {
    #[cfg(mobile)]
    {
      use tauri_plugin_nfc::NfcExt;

      app.handle().plugin(tauri_plugin_nfc::init());

      let tag = app
        .nfc()
        .scan(tauri_plugin_nfc::ScanRequest {
            kind: tauri_plugin_nfc::ScanKind::Ndef {
                mime_type: Some("text/plain".to_string()),
                uri: Some(tauri_plugin_nfc::UriFilter {
                  scheme: Some("https".to_string()),
                  host: Some("my.domain.com".to_string()),
                  path_prefix: Some("/app".to_string()),
                }),
                tech_list: Some(vec![
                  vec![tauri_plugin_nfc::TechKind::Ndef],
                ]),
            },
        })?
        .tag;
    }
    Ok(())
  })

写入 NFC 标签

write API 可用于向 NFC 标签写入负载。 如果使用 keepSessionAlive: true 没有扫描的标签，应用程序将首先扫描 NFC 标签。

JavaScript

import { write, textRecord, uriRecord } from '@tauri-apps/plugin-nfc';

const payload = [uriRecord('https://tauri.app'), textRecord('一些负载')];

const options = {
  // kind 仅在你没有保持活动的扫描标签会话时才需要
  // 其格式与提供给 scan() 的参数相同
  kind: {
    type: 'ndef',
  },
  // 配置在 iOS 上 "扫描 NFC" 对话框中显示的消息
  message: '扫描 NFC 标签',
  successfulReadMessage: 'NFC 标签扫描成功',
  successMessage: 'NFC 标签写入成功',
};

await write(payload, options);

Rust

警告

Rust API 目前仅提供用于写入 NFC 负载的低级接口。

该 API 将很快得到增强。

tauri::Builder::default()
  .setup(|app| {
    #[cfg(mobile)]
    {
      use tauri_plugin_nfc::NfcExt;

      app.handle().plugin(tauri_plugin_nfc::init());

      app
        .nfc()
        .write(vec![
          tauri_plugin_nfc::NfcRecord {
            format: tauri_plugin_nfc::NFCTypeNameFormat::NfcWellKnown,
            kind: vec![0x55], // URI record
            id: vec![],
            payload: vec![], //在此插入负载
          }
        ])?;
    }
    Ok(())
  })

权限

默认情况下，所有潜在危险的插件命令和范围都被阻止，无法访问。你必须修改 capabilities 配置中的权限以启用这些功能。

有关更多信息，请参阅 功能概述 和 使用插件权限的步骤指南。

src-tauri/capabilities/default.json

{
  "permissions": [
    ...,
    "nfc:default",
  ]
}

Default Permission

This permission set configures what kind of operations are available from the nfc plugin.

Granted Permissions

Checking if the NFC functionality is available and scanning nearby tags is allowed. Writing to tags needs to be manually enabled.

This default permission set includes the following:

• allow-is-available
• allow-scan

Permission Table

Identifier	Description
nfc:allow-is-available	Enables the is_available command without any pre-configured scope.
nfc:deny-is-available	Denies the is_available command without any pre-configured scope.
nfc:allow-scan	Enables the scan command without any pre-configured scope.
nfc:deny-scan	Denies the scan command without any pre-configured scope.
nfc:allow-write	Enables the write command without any pre-configured scope.
nfc:deny-write	Denies the write command without any pre-configured scope.