Panduan Memulai

Instal

Anda bisa menggunakan AI-Assisted Setup untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda menggunakan perintah berikut:

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

Lalu gunakan prompt berikut:

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

Jika Anda lebih suka Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti instruksi khusus platform di bawah ini:

bun add @capgo/capacitor-nfc
bunx cap sync

Impor

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

Mulai cepat

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

await CapacitorNfc.startScanning();

Contoh: stopScanning

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

await CapacitorNfc.stopScanning();

Contoh: write

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

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

Masalah umum

• Listeners: hapus handle saat screen unmount.
• Sinkronisasi native: jalankan bunx cap sync setelah upgrade plugin.
• Sumber kebenaran: percaya src/definitions.ts pada repo GitHub.

Ikhtisar API

startScanning

Mulai mendengarkan tag NFC.

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

await CapacitorNfc.startScanning();

stopScanning

Menghentikan sesi pemindaian NFC yang sedang berjalan.

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

await CapacitorNfc.stopScanning();

write

Menulis record NDEF yang diberikan ke tag terakhir yang ditemukan.

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

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

erase

Mencoba menghapus tag terakhir yang ditemukan dengan menulis pesan NDEF kosong.

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

await CapacitorNfc.erase();

makeReadOnly

Mencoba membuat tag terakhir yang terdeteksi menjadi read-only.

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

await CapacitorNfc.makeReadOnly();

share

Membagikan pesan NDEF ke perangkat lain via peer-to-peer (khusus Android).

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

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

unshare

Menghentikan pembagian pesan NDEF yang sebelumnya diberikan (khusus Android).

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

await CapacitorNfc.unshare();

getStatus

Mengembalikan status adapter NFC saat ini.

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

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

showSettings

Membuka halaman pengaturan sistem agar user bisa mengaktifkan NFC.

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

await CapacitorNfc.showSettings();

isSupported

Mengecek apakah perangkat memiliki dukungan hardware NFC.

Mengembalikan true jika hardware NFC tersedia di perangkat, terlepas dari apakah NFC sedang aktif atau nonaktif. Mengembalikan false jika perangkat tidak memiliki hardware NFC.

Gunakan method ini untuk menentukan apakah fitur NFC perlu ditampilkan di UI app Anda. Untuk mengecek apakah NFC sedang aktif, gunakan getStatus().

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

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

Referensi Tipe

StartScanningOptions

Opsi untuk mengatur perilaku .

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

Opsi saat menulis pesan NDEF ke tag yang aktif.

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

Opsi saat berbagi pesan NDEF ke perangkat lain via Android Beam / mode P2P.

export interface ShareTagOptions {
  records: NdefRecord[];
}

NfcStatus

Kemungkinan status adapter NFC yang dikembalikan oleh .

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

NfcEvent

Event discovery NFC umum yang dikirim oleh plugin.

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

NfcStateChangeEvent

Event yang dipicu setiap kali ketersediaan adapter NFC berubah.

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

NdefRecord

Struktur JSON yang merepresentasikan satu 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

Tipe event yang menjelaskan jenis discovery NFC yang terjadi.

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

NfcTag

Representasi informasi tag lengkap yang dikembalikan oleh native layer.

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

Sumber Kebenaran

Halaman ini dibuat dari plugin src/definitions.ts. Jalankan ulang sync saat API publik berubah di upstream.

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan operasi dashboard dan API, hubungkan dengan Menggunakan @capgo/capacitor-nfc untuk kapabilitas native di Menggunakan @capgo/capacitor-nfc, Ikhtisar API untuk detail implementasi di Ringkasan API, Pendahuluan untuk detail implementasi di Pendahuluan, Kunci API untuk detail implementasi di API Keys, dan Perangkat untuk detail implementasi di Perangkat.