Guida rapida

Installazione

Puoi usare il nostro Setup assistito dall'AI per installare il plugin. Aggiungi le skill Capgo al tuo tool AI con il comando seguente:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Poi usa questo prompt:

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

Se preferisci il Setup manuale, installa il plugin eseguendo i comandi seguenti e segui le istruzioni specifiche per piattaforma qui sotto:

bun add @capgo/capacitor-nfc
bunx cap sync

Importa

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

Avvio rapido

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

await CapacitorNfc.startScanning();

Esempio: stopScanning

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

await CapacitorNfc.stopScanning();

Esempio: write

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

await CapacitorNfc.write({
  records: [
    {
      tnf: 1,
      type: [1],
      id: [1],
      payload: [1],
    },
  ],
});

Errori comuni

• Listener: rimuove gli handle quando gli schermi vengono smontati.
• Sync nativo: esegui bunx cap sync dopo gli aggiornamenti dei plugin.
• Fonte di verità: fidati src/definitions.ts nel repo GitHub.

API Panoramica

startScanning

Inizia l'ascolto dei tag NFC.

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

await CapacitorNfc.startScanning();

stopScanning

Interrompe la sessione di scansione NFC in corso.

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

await CapacitorNfc.stopScanning();

write

Scrive i record NDEF forniti nell'ultimo tag rilevato.

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

await CapacitorNfc.write({
  records: [
    {
      tnf: 1,
      type: [1],
      id: [1],
      payload: [1],
    },
  ],
});

erase

Tenta di cancellare l'ultimo tag rilevato scrivendo un messaggio NDEF vuoto.

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

await CapacitorNfc.erase();

makeReadOnly

Tenta di rendere di sola lettura l'ultimo tag rilevato.

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

await CapacitorNfc.makeReadOnly();

share

Condivide un messaggio NDEF con un altro dispositivo tramite peer-to-peer (solo Android).

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

await CapacitorNfc.share({
  records: [
    {
      tnf: 1,
      type: [1],
      id: [1],
      payload: [1],
    },
  ],
});

unshare

Interrompe la condivisione del messaggio NDEF precedentemente fornito (solo Android).

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

await CapacitorNfc.unshare();

getStatus

Restituisce lo stato attuale dell'adapter NFC.

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

const result = await CapacitorNfc.getStatus();
console.log(result);

showSettings

Apre la pagina delle impostazioni di sistema dove l'utente può abilitare l'NFC.

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

await CapacitorNfc.showSettings();

isSupported

Verifica se il dispositivo supporta l'hardware NFC.

Restituisce true se l'hardware NFC è presente sul dispositivo, indipendentemente dal fatto che l'NFC sia attualmente abilitato o disabilitato. Restituisce false se il dispositivo non dispone di hardware NFC.

Usa questo metodo per determinare se le funzionalità NFC debbano essere mostrate nella UI della tua app. Per verificare se l'NFC è attualmente abilitato, usa getStatus().

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

const result = await CapacitorNfc.isSupported();
console.log(result);

Riferimento ai tipi

StartScanningOptions

Opzioni per controllare il comportamento di .

export interface StartScanningOptions {
  /**
   * iOS-only: closes the NFC session automatically after the first successful tag read.
   * Defaults to `true`.
   */
  invalidateAfterFirstRead?: boolean;
  /**
   * iOS-only: custom message displayed in the NFC system sheet while scanning.
   */
  alertMessage?: string;
  /**
   * iOS-only: session type to use for NFC scanning.
   * - `'ndef'`: Uses NFCNDEFReaderSession (default). Only detects NDEF-formatted tags.
   * - `'tag'`: Uses NFCTagReaderSession. Detects both NDEF and non-NDEF tags (e.g., raw MIFARE tags).
   *            Allows reading UID from unformatted tags.
   *            **Requires** the `Near Field Communication Tag Reader Session Formats` entitlement
   *            in your app with the `TAG` format included. Without it the session will fail to
   *            start and the promise will reject with a `NO_NFC` error code.
   * Defaults to `'ndef'` for backward compatibility.
   */
  iosSessionType?: 'ndef' | 'tag';
  /**
   * Android-only: raw flags passed to `NfcAdapter.enableReaderMode`.
   * Defaults to enabling all tag types with skipping NDEF checks.
   */
  androidReaderModeFlags?: number;
}

WriteTagOptions

Opzioni utilizzate per scrivere un messaggio NDEF sul tag corrente.

export interface WriteTagOptions {
  /**
   * Array of records that compose the NDEF message to be written.
   */
  records: NdefRecord[];
  /**
   * When `true`, the plugin attempts to format NDEF-formattable tags before writing.
   * Defaults to `true`.
   */
  allowFormat?: boolean;
}

ShareTagOptions

Opzioni per condividere un messaggio NDEF con un altro dispositivo tramite Android Beam / modalità P2P.

export interface ShareTagOptions {
  records: NdefRecord[];
}

NfcStatus

Possibili stati dell'adapter NFC restituiti da .

export type NfcStatus = 'NFC_OK' | 'NO_NFC' | 'NFC_DISABLED' | 'NDEF_PUSH_DISABLED';

NfcEvent

Evento generico di scoperta NFC inviato dal plugin.

export interface NfcEvent {
  type: NfcEventType;
  tag: NfcTag;
}

NfcStateChangeEvent

Evento emesso quando cambia la disponibilità dell'adapter NFC.

export interface NfcStateChangeEvent {
  status: NfcStatus;
  enabled: boolean;
}

NdefRecord

Struttura JSON che rappresenta un singolo record NDEF.

export interface NdefRecord {
  /**
   * Type Name Format identifier.
   */
  tnf: number;
  /**
   * Type field expressed as an array of byte values.
   */
  type: number[];
  /**
   * Record identifier expressed as an array of byte values.
   */
  id: number[];
  /**
   * Raw payload expressed as an array of byte values.
   */
  payload: number[];
}

NfcEventType

Tipo di evento che descrive la scoperta NFC avvenuta.

export type NfcEventType = 'tag' | 'ndef' | 'ndef-mime' | 'ndef-formatable';

NfcTag

Rappresentazione delle informazioni complete del tag restituite dai layer nativi.

export interface NfcTag {
  /**
   * Raw identifier bytes for the tag.
   */
  id?: number[];
  /**
   * List of Android tech strings (e.g. `android.nfc.tech.Ndef`).
   */
  techTypes?: string[];
  /**
   * Human readable tag type when available (e.g. `NFC Forum Type 2`, `MIFARE Ultralight`).
   */
  type?: string | null;
  /**
   * Maximum writable size in bytes for tags that expose NDEF information.
   */
  maxSize?: number | null;
  /**
   * Indicates whether the tag can be written to.
   */
  isWritable?: boolean | null;
  /**
   * Indicates whether the tag can be permanently locked.
   */
  canMakeReadOnly?: boolean | null;
  /**
   * Array of NDEF records discovered on the tag.
   */
  ndefMessage?: NdefRecord[] | null;
}

Fonte di verità

Questa pagina è generata dal src/definitions.ts. Riesegui la sync quando il API pubblico cambia upstream.

Continua da Getting Started

Se stai usando Guida rapida per pianificare dashboard e operazioni API, collegalo a Utilizzo di @capgo/capacitor-nfc per la funzionalità nativa in Utilizzo di @capgo/capacitor-nfc, API Panoramica per i dettagli di implementazione in Panoramica di API, Introduzione per i dettagli implementativi nell'Introduzione, Chiavi API per i dettagli implementativi in API Keys, e Dispositivi per i dettagli implementativi in Dispositivi.