NFC

API Reference

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

¥Read and write NFC tags on Android and iOS.

支持的平台

¥Supported Platforms

This plugin requires a Rust version of at least 1.77.2

Platform	Level	Notes
windows
linux
macos
android
ios

设置

¥Setup

安装 nfc 插件即可开始使用。

¥Install the nfc plugin to get started.

Automatic
Manual

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

¥Use your project’s package manager to add the dependency:

npm run tauri add nfc

yarn run tauri add nfc

pnpm tauri add nfc

bun tauri add nfc

cargo tauri add nfc

Run the following command in the src-tauri folder to add the plugin to the project’s dependencies in Cargo.toml:
```
cargo add tauri-plugin-nfc --target 'cfg(any(target_os = "android", target_os = "ios"))'
```

Modify lib.rs to initialize the plugin:

#[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");
}

Install the JavaScript Guest bindings using your preferred JavaScript package manager:

npm install @tauri-apps/plugin-nfc

yarn add @tauri-apps/plugin-nfc

pnpm add @tauri-apps/plugin-nfc

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

bun add @tauri-apps/plugin-nfc

配置

¥Configuration

NFC 插件需要 iOS 的原生配置。

¥The NFC plugin requires native configuration for iOS.

iOS

要访问 iOS 上的 NFC API，你必须在 Info.plist 文件上配置使用说明，并将 NFC 功能添加到你的应用中。

¥To access the NFC APIs on iOS you must configure a usage description on the Info.plist file and add the NFC capability to your application.

Info.plist

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

¥On iOS the NFC plugin requires the NFCReaderUsageDescription information property list value, which should describe why your app needs to scan or write to NFC tags.

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

¥In the src-tauri/Info.ios.plist file, add the following snippet:

<?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 功能

¥NFC Capability

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

¥Additionally iOS requires the NFC capability to be associated with your application.

可以在 Xcode 的项目配置的 “签名和功能” 选项卡中通过单击 ”* 功能” 按钮并选择 “近场通信标签读取” 功能（有关更多信息，请参阅向目标添加功能）或通过将以下配置添加到 gen/apple/<app-name>_iOS/<app-name>_iOS.entitlements 文件来添加该功能：

¥The capability can be added in Xcode in the project configuration’s “Signing & Capabilities” tab by clicking the ”+ Capability” button and selecting the “Near Field Communication Tag Reading” capability (see Add a capability to a target for more information) or by adding the following configuration to the gen/apple/<app-name>_iOS/<app-name>_iOS.entitlements file:

<?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>

使用

¥Usage

NFC 插件有 JavaScript 和 Rust 两种版本，允许你扫描和写入 NFC 标签。

¥The NFC plugin is available in both JavaScript and Rust, allowing you to scan and write to NFC tags.

检查是否支持 NFC

¥Checking if NFC is supported

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

¥Not every mobile device has the capability to scan NFC tags, so you should check for availability before using the scan and write APIs.

JavaScript
Rust

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

const canScanNfc = await isAvailable();

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 标签

¥Scanning NFC tags

插件可以扫描通用 NFC 标签或带有 NDEF（NFC 数据交换格式）消息的 NFC 标签，这是一种在 NFC 标签中封装类型数据的标准格式。

¥The plugin can scan either generic NFC tags or NFC tags with a NDEF (NFC Data Exchange Format) message, which is a standard format to encapsulate typed data in an NFC tag.

JavaScript
Rust

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);

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(())
  })

:::note 注意

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

¥The keepSessionAlive option can be used to directly write to the scanned NFC tag later.

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

¥If you do not provide that option, the session is recreated on the next write() call, which means the app will try to rescan the tag.

:::

过滤器

¥Filters

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

¥The NFC scanner can also filter tags with a specific URI format, mime type or NFC tag technologies. In this case, the scan will only detect tags that matches the provided filters.

:::note 注意

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

¥Filtering is only available on Android, so you should always check the scanned NFC tag contents.

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

¥The mime type is case sensitive and must be provided with lower case letters.

:::

JavaScript
Rust

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,
});

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 标签

¥Writing to NFC tags

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

¥The write API can be used to write a payload to a NFC tag. If there’s no scanned tag with keepSessionAlive: true, the application will first scan an NFC tag.

JavaScript
Rust

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

const payload = [uriRecord('https://tauri.nodejs.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);

:::caution 提醒

Rust API 目前仅提供用于编写 NFC 有效负载的底层接口。

¥The Rust API currently only provides a low level interface for writing NFC payloads.

API 将很快得到增强。

¥The API will be enhanced soon.

:::

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(())
  })

权限

¥Permissions

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

¥By default all potentially dangerous plugin commands and scopes are blocked and cannot be accessed. You must modify the permissions in your capabilities configuration to enable these.

有关更详细的说明，请参阅功能概述。

¥See the Capabilities Overview for more information and the step by step guide to use plugin permissions.

{
  "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.

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.