NFC

GitHub npm crates.io

API Reference

在 Android 和 iOS 上读写 NFC 标签。

支持平台

此插件至少需要 1.77.2 版本的 Rust

平台	级别	备注
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 客户端绑定

   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

配置

iOS 上 NFC 插件需要本地配置。

iOS

要访问 iOS 上的 NFC API，您必须在 Info.plist 文件中配置用法描述并将其 NFC 功能添加到您应用中。

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>Read and write various NFC tags</string>
  </dict>
</plist>

NFC 功能

此外，iOS 要求将 NFC 功能与您的应用相关联。

功能可以通过在Xcode项目配置中的“签名和功能”选项卡中点击“+功能”按钮并选择“近场通信标签读取”功能添加（更多信息请参见将功能添加到目标）或通过将以下配置添加到代码目录 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数据交换格式）消息的NFC标签，这是封装NFC标签中类型数据的标准格式。

JavaScript

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

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

const options = {
  keepSessionAlive: false,
  // configure the messages displayed in the "Scan NFC" dialog on iOS
  message: 'Scan a NFC tag',
  successMessage: 'NFC tag successfully scanned',
};

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 = [
  // capture anything using NfcF
  [TechKind.NfcF],
  // capture all MIFARE Classics with NDEF payloads
  [TechKind.NfcA, TechKind.MifareClassic, TechKind.Ndef],
];

const tag = await scan({
  type: 'ndef', // or '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.org.cn'), textRecord('some payload')];

const options = {
  // the kind is only required if you do not have a scanned tag session alive
  // its format is the same as the argument provided to scan()
  kind: {
    type: 'ndef',
  },
  // configure the messages displayed in the "Scan NFC" dialog on iOS
  message: 'Scan a NFC tag',
  successfulReadMessage: 'NFC tag successfully scanned',
  successMessage: 'NFC tag successfully written',
};

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![], // insert payload here
          }
        ])?;
    }
    Ok(())
  })

权限

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

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

src-tauri/capabilities/default.json

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

默认权限

此权限集配置了从NFC插件可执行的类型操作。

已授予的权限

检查NFC功能是否可用，并且允许扫描附近的标签。向标签写入需要手动启用。

• allow-is-available
• allow-scan

权限表

标识符	描述
nfc:allow-is-available	启用无需预先配置作用域的is_available命令。
nfc:deny-is-available	拒绝无需预先配置作用域的is_available命令。
nfc:allow-scan	启用无需预先配置作用域的scan命令。
nfc:deny-scan	拒绝无需预先配置作用域的scan命令。
nfc:allow-write	启用无需预先配置作用域的write命令。
nfc:deny-write	拒绝无需预先配置作用域的write命令。