# @capgo/capacitor-nfc 中文文档

规范地址：https://npmcn.com/package/%40capgo/capacitor-nfc/

版本：8\.3\.7
npm 元数据更新时间：2026-11-09T07:24:10.512Z
中文译文更新时间：2026-11-09T02:28:39.317Z
软件包许可：MPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/capacitor-nfc
原文对照：https://npmcn.com/package/%40capgo/capacitor-nfc/?lang=original
项目主页：https://capgo.app/docs/plugins/nfc/
源码仓库：https://github.com/Cap-go/capacitor-nfc

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：185 kB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-10-27T03:48:36.160Z
- 最新版本发布：2026-11-09T07:24:10.232Z
- 近 30 天下载量：117863（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：64（近 12 个月 56 个）

## 中文简介

在iOS和Android上为 Capacitor apps 原生的 NFC 标签发现,读取和写作.

## 安装

```sh
npm install @capgo/capacitor-nfc
```

也可以使用：`pnpm add @capgo/capacitor-nfc`、`yarn add @capgo/capacitor-nfc`、`bun add @capgo/capacitor-nfc`

## README

# @ capgo/ 电容器- nfc

在iOS和Android上从你的Capacitor app读取并写入NFC标签. 战斗测试电话gap-nfc插件的现代Capacitor移植.

[![Capgo - Build Capacitor apps with AI, ship updates instantly](https://capgo.app/readme-banner.svg?repo=Cap-go/capacitor-nfc)](https://capgo.app/?ref=plugin_nfc)

**队长**:在几分钟内将修正推给您的 Capacitor 用户,在没有Mac的情况下构建已签名的iOS和Android apps,并在一击中回滚.

## [\*免费开始\*](https://capgo.app/register/?ref=plugin_nfc)

14天无限自由审判. 不需要信用卡

> 🤖 **建筑与AI编码代理?** 安装 [Capgo 技能](https://capgo.app/skills/?ref=plugin_nfc) 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 `@capgo/capacitor-nfc` 在您的电容应用程序中: `npx skills add Cap-go/capgo-skills`。然后问你的经纪人: _将@capgo/capor-nfc 添加到我的Capacitor app上,并把它连接起来_ [代理设置指南](https://capgo.app/agents/?ref=plugin_nfc) • 妇女 [主机磁共振](https://capgo.app/docs/ai/mcp/?ref=plugin_nfc)

![@capgo/capacitor-nfc for Capacitor apps](https://raw.githubusercontent.com/Cap-go/capacitor-nfc/main/assets/github-social-preview.png)

## 主要特点

-   **扫描标签**数字 : `startScanning()` 财务报告和审定财务报表 `stopScanning()`,与 `tagDiscovered` 财务报告和审定财务报表 `nfcEvent` 听众.
-   **写入 NDEF**数字 : `write()` 将 NDEF 记录发送到最后一个发现的标记 。 在iOS上,保持会话的开放性 `invalidateAfterFirstRead: false`。 。 。 .
-   **标签管理**数字 : `erase()`附加时 `makeReadOnly()` 安卓号.
-   **适配器状态**数字 : `isSupported()`, (中文(简体) ), `getStatus()`, (中文(简体) ), `showSettings()` 编辑 `nfcStateChange` 活动.
-   **iOS 会话选项**: NDEF或标记会话,投票选项和自定义提醒信息.
-   **机器人 P2P**数字 : `share()` 财务报告和审定财务报表 `unshare()` 在Android 10之前.
-   **平台**: iOS和Android. 互联网档案馆的存檔,存档日期2013-12-22. iOS 使用 Core NFC, Android 使用 `NfcAdapter`。在网上不可用.

在iOS和Android上为 Capacitor apps 原生的 NFC 标记检测,读取和写作.

战事试验的现代辅助港口 [电话gap-nfc](https://github.com/chariotsolutions/phonegap-nfc) 插件,与 Capgo 常规和工具一致 .

## 支持的标签类型

-   **标准 NFC 论坛标签** (第1-4款)
-   **MIFARE 超光线** - 全力支持从MIFARE Ultralight标记,包括EV1和NTAG变体读取NDEF数据。 该插件除了标准NFC标记外,还自动检测出MIFARE Ultralight卡并提取NDEF消息.

## 文档

最完整的文档将在 Capgo Docs 门户网站上直播. 在此之前,探索TypeScript定义(`src/definitions.ts`),并运行包含的示例应用程序来进行API的巡演.

## 兼容性

| 插件版本 | 电容兼容性 | 维护 |
| --- | --- | --- |
| 联合国 | 联合国 | ✅ |
| 页:1 | 页:1 | 应要求 |
| 页:1 | 页:1 | ❌ |
| 页:1 | 页:1 | ❌ |

> **说明:** 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

## 安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

```bash
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
```

然后使用下列提示:

```text
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-nfc` plugin in my project.
```

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capgo/capacitor-nfc
npx cap sync
```

记住要添加所需的平台配置 :

-   **机器人:** 保证您 `AndroidManifest.xml` 声明 `android.permission.NFC` 允许.
-   **iOS: (英语)** 添加 `NFCReaderUsageDescription` 给您的应用程序 `Info.plist` 解释为什么需要NFC进入.
-   **iOS (英语:`iosSessionType: 'tag'`:** 要使用标签会话类型,您还必须添加 `Near Field Communication Tag Reader Session Formats` 应享权利`com.apple.developer.nfc.readersession.formats`)到你的应用程序的应享权利文件,包括 `TAG` 格式(可选) `NDEF`) (中文(简体) ). 如果没有这一资格,届会将无法开始.

## 使用量

### 正在检查 NFC 硬件支持

在尝试使用NFC特性之前,您可以检查设备是否有NFC硬件:

```ts
import { CapacitorNfc } from '@capgo/capacitor-nfc';

const { supported } = await CapacitorNfc.isSupported();
if (!supported) {
  console.warn('This device does not have NFC hardware');
  // Hide NFC features in your UI
} else {
  // Check if NFC is currently enabled
  const { status } = await CapacitorNfc.getStatus();
  if (status === 'NFC_DISABLED') {
    console.warn('NFC is disabled. Prompt user to enable it.');
    // Optionally show settings button
  }
}
```

### 正在读取 NDEF 标签( 默认行为)

```ts
import { CapacitorNfc } from '@capgo/capacitor-nfc';

await CapacitorNfc.startScanning({
  invalidateAfterFirstRead: false, // keep the session open so we can write later
  alertMessage: 'Hold a tag near the top of your device.',
});

const listener = await CapacitorNfc.addListener('nfcEvent', (event) => {
  console.info('Tag type:', event.type);
  console.info('First record:', event.tag?.ndefMessage?.[0]);
});

// Later, write a simple text record back to the tag
const encoder = new TextEncoder();
const langBytes = Array.from(encoder.encode('en'));
const textBytes = Array.from(encoder.encode('Hello Capgo'));
const payload = [langBytes.length & 0x3f, ...langBytes, ...textBytes];

await CapacitorNfc.write({
  allowFormat: true,
  records: [
    {
      tnf: 0x01,
      type: [0x54], // 'T'
      id: [],
      payload,
    },
  ],
});

await listener.remove();
await CapacitorNfc.stopScanning();
```

### 读取原始标签( iOS) - 从未格式化的标签获取 UID

```ts
import { CapacitorNfc } from '@capgo/capacitor-nfc';

// Use 'tag' session type to read raw (non-NDEF) tags
await CapacitorNfc.startScanning({
  iosSessionType: 'tag', // Enable raw tag reading on iOS
  alertMessage: 'Hold your card near the device',
});

const listener = await CapacitorNfc.addListener('nfcEvent', (event) => {
  console.info('Tag detected:', event.type); // 'tag' or 'ndef'
  
  // Read the UID (identifier) - works for both NDEF and raw tags
  if (event.tag?.id) {
    const uid = event.tag.id.map(byte => byte.toString(16).padStart(2, '0').toUpperCase()).join(':');
    console.info('Tag UID:', uid); // e.g., "04:A1:B2:C3:D4:E5:F6"
  }
  
  // If the tag has NDEF data, it will also be available
  if (event.tag?.ndefMessage) {
    console.info('NDEF records:', event.tag.ndefMessage);
  }
});

await listener.remove();
await CapacitorNfc.stopScanning();
```

### 处理 iOS 会话结束

听着 `nfcSessionEnd` 以区分会议暂停或另一个核心 NFC 错误。 双方均可参加这项活动 `ndef` 财务报告和审定财务报表 `tag` iOS会话. 正常的首读完成不会发出此事件.

```ts
const sessionEndListener = await CapacitorNfc.addListener('nfcSessionEnd', ({ reason }) => {
  if (reason === 'userCancelled') {
    return;
  }

  console.warn(reason === 'sessionTimeout' ? 'No tag detected. Try again.' : 'The NFC session failed.');
});

// Later, when the listener is no longer needed
await sessionEndListener.remove();
```

## API 密码

-   [`startScanning(...)`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-startscanning)
-   [`stopScanning()`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-stopscanning)
-   [`write(...)`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-write)
-   [`erase()`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-erase)
-   [`makeReadOnly()`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-makereadonly)
-   [`transceive(...)`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-transceive)
-   [`share(...)`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-share)
-   [`unshare()`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-unshare)
-   [`getStatus()`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-getstatus)
-   [`showSettings()`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-showsettings)
-   [`getPluginVersion()`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-getpluginversion)
-   [`isSupported()`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-issupported)
-   [`addListener('nfcEvent', ...)`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-addlistenernfcevent-)
-   [`addListener('tagDiscovered' | 'ndefDiscovered' | 'ndefMimeDiscovered' | 'ndefFormatableDiscovered', ...)`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-addlistenertagdiscovered--ndefdiscovered--ndefmimediscovered--ndefformatablediscovered-)
-   [`addListener('nfcStateChange', ...)`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-addlistenernfcstatechange-)
-   [`addListener('nfcSessionEnd', ...)`](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-addlistenernfcsessionend-)
-   [接口](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-type-aliases)

Capacitor NFC插件的公用API表面.

界面有意映射参考 PhoneGap 的行为 执行以缓解移徙,同时接受平庸的电容API.

### 开始扫描(...)

```typescript
startScanning(options?: StartScanningOptions | undefined) => Promise<void>
```

开始监听 NFC 标签 .

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[StartScanningOptions](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-startscanningoptions)` |

* * *

### 停止扫描( )

```typescript
stopScanning() => Promise<void>
```

停止正在进行的 NFC 扫描会话 .

* * *

### 写入(...)

```typescript
write(options: WriteTagOptions) => Promise<void>
```

将所提供的NDEF记录写入上一个已发现的标签.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[WriteTagOptions](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-writetagoptions)` |

* * *

### 删除( c)

```typescript
erase() => Promise<void>
```

试图通过写入空的 NDEF 信件来删除最后一个已发现的标签 .

* * *

### 仅读( )

```typescript
makeReadOnly() => Promise<void>
```

尝试使最后发现的标记只读取 .

* * *

### 转录(...)

```typescript
transceive(options: TransceiveOptions) => Promise<TransceiveResult>
```

将原始命令发送到最后一个已发现的标记,同时它仍然留在域中.

在Android上,使用 `NfcV` 或者说 `NfcA` 与QQlink CapacitorNfcPlugin.write}相同的标签上. 在iOS上,需要一个活跃的标签阅读器会话(`iosSessionType: 'tag'`与 `invalidateAfterFirstRead: false`,并在相接标签上使用ISO 15693或MIFARE命令.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[TransceiveOptions](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-transceiveoptions)` |

**回返情况:** `Promise<[TransceiveResult](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-transceiveresult)>`

* * *

### 共享(...)

```typescript
share(options: ShareTagOptions) => Promise<void>
```

通过对等器(仅限Android)与另一个设备共享NDEF消息.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[ShareTagOptions](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-sharetagoptions)` |

* * *

### 未共享 ()

```typescript
unshare() => Promise<void>
```

停止共享先前提供的 NDEF 消息( 只有Android) .

* * *

### 获取状态( C)

```typescript
getStatus() => Promise<{ status: NfcStatus; }>
```

返回当前 NFC 适配器状态 .

**回返情况:** `Promise<{ status: [NfcStatus](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-nfcstatus); }>`

* * *

### 显示设置( C)

```typescript
showSettings() => Promise<void>
```

打开用户可以启用 NFC 的系统设置页面.

* * *

### 获取 PluginVersion ()

```typescript
getPluginVersion() => Promise<{ version: string; }>
```

返回已烤入本地插件的版本字符串 .

**回返情况:** `Promise<{ version: string; }>`

* * *

### 已支持 ()

```typescript
isSupported() => Promise<{ supported: boolean; }>
```

检查设备是否有 NFC 硬件支持 .

回返 `true` 如果设备上存在 NFC 硬件,无论 是否当前启用或禁用 NFC 。 回返 `false` 若为 设备没有NFC硬件.

使用此方法来确定NFC 特性是否应在您 应用的UI。 要检查当前是否启用 NFC, 请使用 `getStatus()`。 。 。 .

**回返情况:** `Promise<{ supported: boolean; }>`

* * *

### 添加倾听器( nfcEvent,...)

```typescript
addListener(eventName: 'nfcEvent', listenerFunc: (event: NfcEvent) => void) => Promise<PluginListenerHandle>
```

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'nfcEvent'` |
| **`listenerFunc`** | `(event: [NfcEvent](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-nfcevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-pluginlistenerhandle)>`

* * *

### 添加 listener( “ tag Discovered ” + “ ndef Discovered ” + “ ndefMime Discovered ” + “ ndef Formatable Discovered ” , ) , )

```typescript
addListener(eventName: 'tagDiscovered' | 'ndefDiscovered' | 'ndefMimeDiscovered' | 'ndefFormatableDiscovered', listenerFunc: (event: NfcEvent) => void) => Promise<PluginListenerHandle>
```

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'tagDiscovered' | 'ndefDiscovered' | 'ndefMimeDiscovered' | 'ndefFormatableDiscovered'` |
| **`listenerFunc`** | `(event: [NfcEvent](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-nfcevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-pluginlistenerhandle)>`

* * *

### 添加 listener ('nfc StateChange',...)

```typescript
addListener(eventName: 'nfcStateChange', listenerFunc: (event: NfcStateChangeEvent) => void) => Promise<PluginListenerHandle>
```

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'nfcStateChange'` |
| **`listenerFunc`** | `(event: [NfcStateChangeEvent](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-nfcstatechangeevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-pluginlistenerhandle)>`

* * *

### 添加收听器( 'nfcSession End', ...)

```typescript
addListener(eventName: 'nfcSessionEnd', listenerFunc: (event: NfcSessionEndEvent) => void) => Promise<PluginListenerHandle>
```

| 参数 | 类型 |
| --- | --- |
| **`eventName`** | `'nfcSessionEnd'` |
| **`listenerFunc`** | `(event: [NfcSessionEndEvent](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-nfcsessionendevent)) => void` |

**回返情况:** `Promise<[PluginListenerHandle](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-pluginlistenerhandle)>`

* * *

### 接口

#### 开始扫描选项

控制 QQlink CapacitorNfcPlugin. startScanning 行为的选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`invalidateAfterFirstRead`** | `boolean` | iOS-只:在第一个成功标记读取后自动关闭NFC会话. 默认为 `true`。 。 。 . |
| **`alertMessage`** | `string` | iOS-只:扫描时显示在NFC系统工作表中的自定义消息. |
| **`iosSessionType`** | `'tag' | 'ndef'` | iOS:用于NFC扫描的会话类型。 - `'ndef'`: 使用 NFCNDEF Reader session(默认). 只有探测到NDEF格式标记。 - `'tag'`使用NFCTagReader会议。 探测到NDEF和非NDEF标记(例如原始MIFARE标记). 允许从未格式化的标记读取 UID . **要求数** 页:1 `Near Field Communication Tag Reader Session Formats` 在您的应用程序中 `TAG` 包含格式。 如果没有它,会议将无法开始,承诺将以 `NO_NFC` 错误代码 。 默认为 `'ndef'` 用于向后兼容. |
| **`iosPollingOptions`** | `NfcIosPollingOption[]` | 只使用iOS:用于NFC扫描的投票选项. 默认为 `['iso14443', 'iso15693']`。扫描 FeliCa 标签的应用程序可以选择使用 `'iso18092'` 在配置所需的 FeliCa 权利和系统代码后. |
| **`androidReaderModeFlags`** | `number` | 仅使用Android: 传递给原始旗帜 `NfcAdapter.enableReaderMode`。默认允许所有标记类型和Android的NDEF发现,以便仍可使用被检测的标记进行书写和格式化. |

#### 写入标签选项

在当前标签上写入 NDEF 信件时使用的选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`records`** | `NdefRecord[]` | 编成NDEF消息的一组记录. |
| **`allowFormat`** | `boolean` | 何时 `true`,插件试图在写入前格式化 NDEF-格式标记。 默认为 `true`。 。 。 . |

#### 无标记

JSON结构代表单一的NDEF记录.

镜像遗留的 Cordova 执行和 使用整数阵列而不是字符串来保存原有效载荷 字节.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`tnf`** | `number` | 键入名称格式标识符 . |
| **`type`** | `number[]` | 类型字段表示为字节值的数组. |
| **`id`** | `number[]` | 以字节值数组表示的记录标识符 . |
| **`payload`** | `number[]` | 原始有效载荷表示为数组字节值. |

#### 转接结果

(原始内容存档于2017-10-21) (英语). Results of a supposed QQlink CapacitorNfcPlugin.transceive} call.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`response`** | `number[]` | 从标签(ISO 15693回應中包括了响应旗为第一字节)的原始响应框架. |

#### 转换选项

向当前标签发送原始命令的选项 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`data`** | `number[]` | 没有 CRC 的原始请求框架 。 ISO 15693号标准`nfcV`),第一个字节是请求旗,第二个字节是命令代码,后面是任何命令参数. 反应包括了响应旗作为第一个字节. |
| **`tech`** | `[TransceiveTech](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-transceivetech)` | 要用哪种技术? 默认为当前标记检测到的技术 . |
| **`timeout`** | `number` | 仅限Android:以毫秒计的转录超时为NFC-A(`nfcA`。忽略了ISO 15693`nfcV`) (中文(简体) ). |

#### 共享标签选项

使用 Android Beam / P2P 模式与另一个设备共享 NDEF 消息时使用的选项 .

| Prop | 类型 |
| --- | --- |
| **`records`** | `NdefRecord[]` |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### 无活动

由插件发送的通用 NFC 发现事件 .

| Prop | 类型 |
| --- | --- |
| **`type`** | `[NfcEventType](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-nfceventtype)` |
| **`tag`** | `[NfcTag](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-nfctag)` |

#### Nfc 标签

代表原地层返回的全部标签信息.

支持标准的NFC论坛标签以及MIFARE Ultralight卡(包括 EV1和NTAG变种. NDEF数据自动取自MIFARE Ultralight 可用时标记.

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`id`** | `number[]` | 标记的原始标识符字节 . |
| **`techTypes`** | `string[]` | Android技术字符串列表(例如:. `android.nfc.tech.Ndef`) (中文(简体) ). |
| **`type`** | `string | null` | 人类可读标记类型(如:. `NFC Forum Type 2`, (中文(简体) ), `MIFARE Ultralight`) (中文(简体) ). |
| **`maxSize`** | `number | null` | 显示 NDEF 信息的标签的最大字节大小 . |
| **`isWritable`** | `boolean | null` | 指示标记是否可以写入 . |
| **`canMakeReadOnly`** | `boolean | null` | 显示标记是否可永久锁定 . |
| **`ndefMessage`** | `NdefRecord[] | null` | 标记上发现的NDEF记录的阵列. |

#### Nfc State 变换事件

当NFC适配器的可用性发生变化时,事件即会释放出.

| Prop | 类型 |
| --- | --- |
| **`status`** | `[NfcStatus](https://npmcn.com/package/%40capgo/capacitor-nfc/#readme-nfcstatus)` |
| **`enabled`** | `boolean` |

#### 会议结束

当iOS NFC 阅读器会话结束时, 事件会释放出 .

当会话在第一次成功读取后正常关闭时,此事件不会被释放 .

| Prop | 类型 |
| --- | --- |
| **`reason`** | `'userCancelled' | 'sessionTimeout' | 'invalidated'` |

### 类型异名

#### NfcIos 弹出选项

nFC扫描会话的iOS专用投票选项. 这些选项决定了读者会话的标签类型 应在投票过程中发现.

-   'iso14443': ISO 14443标签的投放
-   'iso15693': ISO 15693标签的投影
-   'iso18092': ISO 18092标签的投影
-   “ 速度 ” : PACE 标签的 Polls( 可在 iOS 16 上查阅, 也可在 iOS 16 上查阅)

`'iso14443' | 'iso15693' | 'iso18092' | 'pace'`

#### 传输技术

用于QQLink CapacitorNfcPlugin.transceive的NFC技术.

-   `nfcV`: ISO 15693(例如ST25DV).
-   `nfcA`: NFC-A /MIFARE(例如NTAG I2C外加).

`'nfcV' | 'nfcA'`

#### 情况

可能的NFC适配器状态由QQlink CapacitorNfcPlugin.getStatus}返回.

匹配原始 PhoneGap NFC 插件提供的常数 与现有应用程序兼容.

`'NFC_OK' | 'NO_NFC' | 'NFC_DISABLED' | 'NDEF_PUSH_DISABLED'`

#### NfcEvent 主题

事件类型描述NFC的发现类型.

-   `tag`:通用NFC标记(无NDEF有效载荷).
-   `ndef`显示NDEF载荷的标签.
-   `ndef-mime`: 匹配 MIME 类型过滤器之一的 NDEF 标记 .
-   `ndef-formatable`:可以格式化为NDEF的标签.

`'tag' | 'ndef' | 'ndef-mime' | 'ndef-formatable'`

## 常见问题

### @capgo/capacitor-nfc 是什么？

在iOS和Android上为 Capacitor apps 原生的 NFC 标签发现,读取和写作\.

### 如何安装 @capgo/capacitor-nfc？

在项目目录运行 npm install @capgo/capacitor-nfc，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capgo/capacitor-nfc 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/capacitor-nfc 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capgo/capacitor-nfc 可以商用吗？

@capgo/capacitor-nfc 使用 MPL-2\.0 许可。弱 Copyleft：可以商用，也可以和闭源代码一起使用；但如果分发时修改了 MPL 授权的文件，这些文件的修改需以 MPL 开源。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/capacitor-nfc 的下载量有多少？

根据 npm 官方下载统计，@capgo/capacitor-nfc 在 2026/10/09 – 2026/11/07 这 30 天内被下载 117,863 次，日均约 3,929 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/capacitor-nfc 还在维护吗？

最新版本 8\.3\.7 发布于 2026/11/09（今天）；至今共发布 64 个版本，其中过去 12 个月发布了 56 个；首次发布于 2025/10/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。