近场通信

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

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

npm run tauri add nfc

yarn run tauri add nfc

pnpm tauri add nfc

bun tauri add nfc

cargo tauri add nfc

在 src-tauri 文件夹中运行以下命令，将插件添加到 Cargo.toml 中的项目依赖：
```
cargo add tauri-plugin-nfc --target 'cfg(any(target_os = "android", target_os = "ios"))'
```

修改 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");
}

使用你偏好的 JavaScript 包管理器安装 JavaScript Guest 绑定：

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，你必须调整目标 iOS 版本，在 Info.plist 文件中配置使用说明，并将 NFC 功能添加到你的应用中。

🌐 To access the NFC APIs on iOS you must adjust the target iOS version, configure a usage description on the Info.plist file and add the NFC capability to your application.

目标 iOS 版本

🌐 Target IOS version

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

🌐 The NFC plugin requires iOS 14+. This is the default for Tauri applications created with Tauri CLI v2.8 and above, but you can edit your Xcode project to configure it.

在 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 配置中设置部署目标。

🌐 Alternatively you can set the deployment target from Xcode in the General > Minimum Deployments > iOS configuration.

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 的项目配置的“Signing & Capabilities”选项卡中通过点击“+ Capability”按钮并选择“近场通信标签读取”功能来添加此功能（有关更多信息，请参阅[向目标添加功能]），或者通过将以下配置添加到 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>

使用

🌐 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 标签，NDEF 是一种在 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(())
  })

过滤器

🌐 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.

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

:::注意 Rust API 目前仅提供用于写入 NFC 有效载荷的低级接口。

该 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.

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.