Premiers pas

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez la configuration manuelle, installez le plugin avec les commandes suivantes, puis suivez les instructions spécifiques à chaque plateforme ci-dessous :

bun add @capgo/capacitor-nfc
bunx cap sync

Importer

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

Démarrage rapide

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

await CapacitorNfc.startScanning();

Exemple : stopScanning

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

await CapacitorNfc.stopScanning();

Exemple : write

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

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

Erreurs courantes

• Écouteurs : supprimez les handles lors du démontage des écrans.
• Sync native : exécutez bunx cap sync après la mise à jour des plugins.
• Source de vérité: confiance src/definitions.ts dans le repo GitHub.

Aperçu de API

startScanning

Lance l'écoute des tags NFC.

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

await CapacitorNfc.startScanning();

stopScanning

Arrête la session de scan NFC en cours.

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

await CapacitorNfc.stopScanning();

write

Écrit les enregistrements NDEF fournis sur le dernier tag détecté.

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

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

erase

Tente d'effacer le dernier tag détecté en écrivant un message NDEF vide.

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

await CapacitorNfc.erase();

makeReadOnly

Tente de rendre le dernier tag détecté en lecture seule.

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

await CapacitorNfc.makeReadOnly();

share

Partage un message NDEF avec un autre appareil via le peer-to-peer (Android uniquement).

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

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

unshare

Arrête le partage du message NDEF précédemment fourni (Android uniquement).

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

await CapacitorNfc.unshare();

getStatus

Renvoie le statut actuel de l'adaptateur NFC.

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

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

showSettings

Ouvre la page des paramètres système pour permettre à l'utilisateur d'activer le NFC.

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

await CapacitorNfc.showSettings();

isSupported

Vérifie si l'appareil dispose d'un support matériel NFC.

Retourne true si le matériel NFC est présent sur l'appareil, que le NFC soit activé ou désactivé. Retourne false si l'appareil ne possède pas de matériel NFC.

Utilisez cette méthode pour déterminer si les fonctionnalités NFC doivent être affichées dans l'interface de votre application. Pour vérifier si le NFC est activé, utilisez getStatus().

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

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

Référence de type

StartScanningOptions

Options qui contrôlent le comportement de .

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

Options utilisées lors de l'écriture d'un message NDEF sur le tag actuel.

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

Options utilisées lors du partage d'un message NDEF avec un autre appareil via Android Beam / le mode P2P.

export interface ShareTagOptions {
  records: NdefRecord[];
}

NfcStatus

États possibles de l'adaptateur NFC renvoyés par .

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

NfcEvent

Événement de découverte NFC générique émis par le plugin.

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

NfcStateChangeEvent

Événement émis dès que la disponibilité de l'adaptateur NFC change.

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

NdefRecord

Structure JSON représentant un seul enregistrement 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

Type d'événement décrivant le type de découverte NFC effectuée.

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

NfcTag

Représentation de l'intégralité des informations du tag renvoyées par les couches natives.

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

Source de vérité

Cette page est générée à partir du src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

Continuer depuis Getting Started

Si vous utilisez Premiers pas pour planifier les opérations du dashboard et de API, connectez-l’à Utiliser @capgo/capacitor-nfc pour la capacité native dans Utiliser @capgo/capacitor-nfc, Aperçu de API pour les détails d'implémentation dans l'aperçu de API, Introduction pour les détails d'implémentation dans l'Introduction, Clés API pour les détails d'implémentation dans les clés API, et Appareils pour le détail d’implémentation dans Devices.