Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

bun add @capgo/capacitor-nfc
bunx cap sync

Importieren

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

Quickstart

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

await CapacitorNfc.startScanning();

Beispiel: stopScanning

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

await CapacitorNfc.stopScanning();

Beispiel: write

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

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

Häufige Stolperfallen

• Listener: Handles beim Unmounten von Screens entfernen.
• Nativer Sync: ausführen bunx cap sync nach Plugin-Upgrades.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

API Übersicht

startScanning

Beginnt, auf NFC-Tags zu lauschen.

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

await CapacitorNfc.startScanning();

stopScanning

Beendet die laufende NFC-Scan-Session.

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

await CapacitorNfc.stopScanning();

write

Schreibt die bereitgestellten NDEF-Records auf den zuletzt erkannten Tag.

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

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

erase

Versucht, den zuletzt erkannten Tag durch Schreiben einer leeren NDEF-Message zu löschen.

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

await CapacitorNfc.erase();

makeReadOnly

Versucht, den zuletzt erkannten Tag schreibgeschützt zu machen.

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

await CapacitorNfc.makeReadOnly();

share

Teilt eine NDEF-Nachricht via Peer-to-Peer mit einem anderen Gerät (nur Android).

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

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

unshare

Beendet das Teilen der zuvor bereitgestellten NDEF-Nachricht (nur Android).

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

await CapacitorNfc.unshare();

getStatus

Gibt den aktuellen Status des NFC-Adapters zurück.

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

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

showSettings

Öffnet die Systemeinstellungen, damit der Nutzer NFC aktivieren kann.

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

await CapacitorNfc.showSettings();

isSupported

Prüft, ob das Gerät über NFC-Hardware verfügt.

Gibt zurück, true ob das Gerät über NFC-Hardware verfügt, unabhängig davon, ob NFC gerade aktiviert oder deaktiviert ist. Gibt zurück, false wenn das Gerät über keine NFC-Hardware verfügt.

Nutze diese Methode, um zu prüfen, ob NFC-Funktionen in der UI deiner App angezeigt werden sollen. Um zu prüfen, ob NFC aktuell aktiviert ist, nutze getStatus().

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

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

Typreferenz

StartScanningOptions

Optionen zur Steuerung des Verhaltens von .

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

Optionen zum Schreiben einer NDEF-Nachricht auf den aktuellen Tag.

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

Optionen zum Teilen einer NDEF-Nachricht mit einem anderen Gerät via Android Beam / P2P-Modus.

export interface ShareTagOptions {
  records: NdefRecord[];
}

NfcStatus

Mögliche NFC-Adapterzustände, die von . zurückgegeben werden.

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

NfcEvent

Allgemeines NFC-Discovery-Event, das vom Plugin ausgelöst wird.

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

NfcStateChangeEvent

Event, das ausgelöst wird, wenn sich die Verfügbarkeit des NFC-Adapters ändert.

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

NdefRecord

JSON-Struktur, die einen einzelnen NDEF-Record repräsentiert.

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

Event-Typ, der die Art der durchgeführten NFC-Discovery beschreibt.

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

NfcTag

Darstellung der vollständigen Tag-Informationen, die von den Native Layers zurückgegeben werden.

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 of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte um Dashboard- und API-Operationen zu planen, verbinde es mit Nutzung von @capgo/capacitor-nfc für die native Funktion in der Nutzung von @capgo/capacitor-nfc, API Übersicht für Details zur Implementierung im API Overview, Einführung für die Implementierungsdetails in der Einleitung, API Schlüssel für das Implementierungsdetail in API Keys und Geräte für das Implementierungsdetail in Devices.