@ capgo/ 电容器- nfc

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

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

主要特点

• 扫描标签数字 : 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 插件,与 Capgo 常规和工具一致 .

支持的标签类型

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

文档

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

兼容性

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

安装

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

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

然后使用下列提示:

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

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

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硬件:

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 标签( 默认行为)

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

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会话. 正常的首读完成不会发出此事件.

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(...)
• stopScanning()
• write(...)
• erase()
• makeReadOnly()
• transceive(...)
• share(...)
• unshare()
• getStatus()
• showSettings()
• getPluginVersion()
• isSupported()
• addListener('nfcEvent', ...)
• addListener('tagDiscovered' | 'ndefDiscovered' | 'ndefMimeDiscovered' | 'ndefFormatableDiscovered', ...)
• addListener('nfcStateChange', ...)
• addListener('nfcSessionEnd', ...)
• 接口
• 类型异名

Capacitor NFC插件的公用API表面.

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

开始扫描(...)

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

开始监听 NFC 标签 .

停止扫描( )

stopScanning() => Promise<void>

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

写入(...)

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

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

删除( c)

erase() => Promise<void>

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

仅读( )

makeReadOnly() => Promise<void>

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

转录(...)

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

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

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

回返情况: Promise<TransceiveResult>

共享(...)

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

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

未共享 ()

unshare() => Promise<void>

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

获取状态( C)

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

返回当前 NFC 适配器状态 .

回返情况: Promise<{ status: NfcStatus; }>

显示设置( C)

showSettings() => Promise<void>

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

获取 PluginVersion ()

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

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

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

已支持 ()

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

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

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

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

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

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

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

回返情况: Promise<PluginListenerHandle>

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

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

回返情况: Promise<PluginListenerHandle>

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

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

回返情况: Promise<PluginListenerHandle>

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

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

回返情况: Promise<PluginListenerHandle>

接口

开始扫描选项

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

写入标签选项

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

无标记

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

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

转接结果

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

转换选项

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

共享标签选项

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

插件听筒

无活动

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

Nfc 标签

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

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

Nfc State 变换事件

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

会议结束

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

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

类型异名

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'