@ohos.nfc.tag (Standard NFC Tags)

The nfcTag module provides APIs for managing Near-Field Communication (NFC) tags.

NOTE

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Declaration

Before developing applications related to tag read and write, you must declare NFC-related attributes in the attribute configuration file of the applications. For example, declare the following attributes in the module.json5 file:

{
    "module": {
        // Attributes to declare.

        "abilities": [
            {
                "skills": [
                    {
                        "actions": [
                            // Actions to declare.

                            // Add the nfc tag action.
                            "ohos.nfc.tag.action.TAG_FOUND"
                        ]
                    }
                ],
                "metadata": [
                    {
                        "name": "tag-tech",
                        "value": "NfcA"
                    },
                    {
                        "name": "tag-tech",
                        "value": "IsoDep"
                    },
                    // Add other technologies,
                    // such as NfcB, NfcF, NfcV, Ndef, MifareClassic, MifareUL, and NdefFormatable.
                ]
            }
        ],
        "requestPermissions": [
            "name": "ohos.permission.NFC_TAG",
            "reason": "tag",
        ]
    }
}

CAUTION

1. The actions field is mandatory. It must be ohos.nfc.tag.action.TAG_FOUND and cannot be changed.
2. The name field under metadata is mandatory. It must be tag-tech and cannot be changed.
3. The value field under metadata is mandatory. It can be NfcA, NfcB, NfcF, NfcV, IsoDep, Ndef, MifareClassic, MifareUL, NdefFormatable or any of their combinations. Incorrect settings of this field will cause a parsing failure.
4. The name field under requestPermissions is mandatory. It must be ohos.permission.NFC_TAG and cannot be changed.

Modules to Import

import tag from '@ohos.nfc.tag';

tag.TagInfo

Before a card with tags is read or written, TagInfo must be obtained to determine the tag technologies supported by the card. In this way, the application can invoke the correct API to communicate with the card.

import tag from '@ohos.nfc.tag';

onCreate(want, launchParam) {
    // Add other code here.

    // want is initialized by the NFC service and contains tagInfo.
    var tagInfo;
    try {
        tagInfo = tag.getTagInfo(want);
    } catch (error) {
        console.log("tag.getTagInfo caught error: " + error);
    }
    if (tagInfo == null || tagInfo == undefined) {
        console.log("no TagInfo to be created, ignore it.");
        return;
    }

    // get the supported technologies for this found tag.
    var isNfcATag =  false;
    var isIsoDepTag =  false;
    for (var i = 0; i < tagInfo.technology.length; i++) {
        if (tagInfo.technology[i] == tag.NFC_A) {
            isNfcATag = true;
        }

        if (tagInfo.technology[i] == tag.ISO_DEP) {
            isIsoDepTag = true;
        }
        // Also check for technology tag.NFC_B, NFC_F, NFC_V, ISO_DEP, NDEF, MIFARE_CLASSIC, MIFARE_ULTRALIGHT, and NDEF_FORMATABLE.
    }

    // use NfcA APIs to access the found tag.
    if (isNfcATag) {
        var nfcA;
        try {
            nfcA = tag.getNfcATag(taginfo);
        } catch (error) {
            console.log("tag.getNfcATag caught error: " + error);
        }
        // Other code to read or write this tag.
    }

    // use getIsoDep APIs to access the found tag.
    if (isIsoDepTag) {
        var isoDep;
        try {
            isoDep = tag.getIsoDep(taginfo);
        } catch (error) {
            console.log("tag.getIsoDep caught error: " + error);
        }
        // Other code to read or write this tag.
    }

    // Use the same code to handle "NfcA/NfcB/NfcF/NfcV/Ndef/MifareClassic/MifareUL/NdefFormatable".
}

tag.getNfcATag

getNfcATag(tagInfo: TagInfo): NfcATag

Obtains an NfcATag object, which allows access to the tags that use the NFC-A technology.

NOTE This API is supported since API version 7 and deprecated since API version 9. You are advised to use tag.getNfcA.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

tag.getNfcA⁹⁺

getNfcA(tagInfo: TagInfo): NfcATag

Obtains an NfcATag object, which allows access to the tags that use the NFC-A technology.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getNfcBTag

getNfcBTag(tagInfo: TagInfo): NfcBTag

Obtains an NfcBTag object, which allows access to the tags that use the NFC-B technology.

NOTE This API is supported since API version 7 and deprecated since API version 9. You are advised to use tag.getNfcB.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

tag.getNfcB⁹⁺

getNfcB(tagInfo: TagInfo): NfcBTag

Obtains an NfcBTag object, which allows access to the tags that use the NFC-B technology.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getNfcFTag

getNfcFTag(tagInfo: TagInfo): NfcFTag

Obtains an NfcFTag object, which allows access to the tags that use the NFC-F technology.

NOTE This API is supported since API version 7 and deprecated since API version 9. You are advised to use tag.getNfcF.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

tag.getNfcF⁹⁺

getNfcF(tagInfo: TagInfo): NfcFTag

Obtains an NfcFTag object, which allows access to the tags that use the NFC-F technology.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getNfcVTag

getNfcVTag(tagInfo: TagInfo): NfcVTag

Obtains an NfcVTag object, which allows access to the tags that use the NFC-V technology.

NOTE This API is supported since API version 7 and deprecated since API version 9. You are advised to use tag.getNfcV.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

tag.getNfcV⁹⁺

getNfcV(tagInfo: TagInfo): NfcVTag

Obtains an NfcVTag object, which allows access to the tags that use the NFC-V technology.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getIsoDep⁹⁺

getIsoDep(tagInfo: TagInfo): IsoDepTag

Obtains an IsoDepTag object, which allows access to the tags that use the ISO-DEP technology.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getNdef⁹⁺

getNdef(tagInfo: TagInfo): NdefTag

Obtains an NdefTag object, which allows access to the tags in the NFC Data Exchange Format (NDEF).

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getMifareClassic⁹⁺

getMifareClassic(tagInfo: TagInfo): MifareClassicTag

Obtains a MifareClassicTag object, which allows access to the tags that use MIFARE Classic.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getMifareUltralight⁹⁺

getMifareUltralight(tagInfo: TagInfo): MifareUltralightTag

Obtains a MifareUltralightTag object, which allows access to the tags that use MIFARE Ultralight.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getNdefFormatable⁹⁺

getNdefFormatable(tagInfo: TagInfo): NdefFormatableTag

Obtains an NdefFormatableTag object, which allows access to the tags that are NDEF formattable.

System capability: SystemCapability.Communication.NFC.Tag

Return value

Error codes

For details about the error codes, see NFC Error Codes.

tag.getTagInfo⁹⁺

getTagInfo(want: Want): TagInfo

Obtains TagInfo from Want, which is initialized by the NFC service and contains the attributes required by TagInfo.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

tag.ndef.makeUriRecord⁹⁺

makeUriRecord(uri: string): NdefRecord;

Creates an NDEF record based on the specified URI.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

try {
    let uri = "https://gitee.com/openharmony"; // change it to be correct.
    let ndefRecord = tag.ndef.makeUriRecord(uri);
    if (ndefRecord != undefined) {
        console.log("ndefMessage makeUriRecord rtdType: " + ndefRecord.rtdType);
        console.log("ndefMessage makeUriRecord payload: " + ndefRecord.payload);
    } else {
        console.log("ndefMessage makeUriRecord ndefRecord: " + ndefRecord);
    }
} catch (busiError) {
    console.log("ndefMessage makeUriRecord caught busiError: " + busiError);
}

tag.ndef.makeTextRecord⁹⁺

makeTextRecord(text: string, locale: string): NdefRecord;

Creates an NDEF record based on the specified text data and encoding type.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

try {
    let text = "Hello World";   // change it to be correct.
    let locale = "en"; // change it to be correct.
    let ndefRecord = tag.ndef.makeTextRecord(text, locale);
    if (ndefRecord != undefined) {
        console.log("ndefMessage makeTextRecord rtdType: " + ndefRecord.rtdType);
        console.log("ndefMessage makeTextRecord payload: " + ndefRecord.payload);
    } else {
        console.log("ndefMessage makeTextRecord ndefRecord: " + ndefRecord);
    }
} catch (busiError) {
    console.log("ndefMessage makeTextRecord caught busiError: " + busiError);
}

tag.ndef.makeMimeRecord⁹⁺

makeMimeRecord(mimeType: string, mimeData: number[]): NdefRecord;

Creates an NDEF record based on the specified MIME data and type.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

try {
    let mimeType = "text/plain";   // change it to be correct.
    let mimeData = [0x01, 0x02, 0x03, 0x04]; // change it to be correct.
    let ndefRecord = tag.ndef.makeMimeRecord(mimeType, mimeData);
    if (ndefRecord != undefined) {
        console.log("ndefMessage makeMimeRecord rtdType: " + ndefRecord.rtdType);
        console.log("ndefMessage makeMimeRecord payload: " + ndefRecord.payload);
    } else {
        console.log("ndefMessage makeMimeRecord ndefRecord: " + ndefRecord);
    }
} catch (busiError) {
    console.log("ndefMessage makeMimeRecord caught busiError: " + busiError);
}

tag.ndef.makeExternalRecord⁹⁺

makeExternalRecord(domainName: string, type: string, externalData: number[]): NdefRecord;

Creates an NDEF record based on application-specific data.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

try {
    let domainName = "ohos.nfc.application"; // change it to be correct.
    let type = "test"; // change it to be correct.
    let externalData = [0x01, 0x02, 0x03, 0x04]; // change it to be correct.
    let ndefRecord = tag.ndef.makeExternalRecord(domainName, type, externalData);
    if (ndefRecord != undefined) {
        console.log("ndefMessage makeExternalRecord rtdType: " + ndefRecord.rtdType);
        console.log("ndefMessage makeExternalRecord payload: " + ndefRecord.payload);
    } else {
        console.log("ndefMessage makeExternalRecord ndefRecord: " + ndefRecord);
    }
} catch (busiError) {
    console.log("ndefMessage makeExternalRecord caught busiError: " + busiError);
}

tag.ndef.messageToBytes⁹⁺

messageToBytes(ndefMessage: NdefMessage): number[];

Converts an NDEF message to bytes.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

let rawData = [0xD1, 0x01, 0x03, 0x54, 0x4E, 0x46, 0x43]; // MUST can be parsed as NDEF Record.
let ndefMessage;
try {
    ndefMessage = tag.ndef.createNdefMessage(rawData);
    console.log("ndef createNdefMessage, ndefMessage: " + ndefMessage);
} catch (busiError) {
    console.log("ndef createNdefMessage busiError: " + busiError);
}

try {
    let rawData2 = tag.ndef.messageToBytes(ndefMessage);
    console.log("ndefMessage messageToBytes rawData2: " + rawData2);
} catch (busiError) {
    console.log("ndefMessage messageToBytes caught busiError: " + busiError);
}

tag.ndef.createNdefMessage⁹⁺

createNdefMessage(data: number[]): NdefMessage

Creates an NDEF message from raw byte data. The data must comply with the NDEF record format. Otherwise, the NDE record list contained in the NdefMessage object will be empty.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

let rawData = [0xD1, 0x01, 0x03, 0x54, 0x4E, 0x46, 0x43];  // MUST can be parsed as NDEF Record.
let ndefMessage;
try {
    ndefMessage = tag.ndef.createNdefMessage(rawData);
    console.log("ndef createNdefMessage, ndefMessage: " + ndefMessage);
} catch (busiError) {
    console.log("ndef createNdefMessage busiError: " + busiError);
}

tag.ndef.createNdefMessage⁹⁺

createNdefMessage(ndefRecords: NdefRecord[]): NdefMessage

Creates an NDEF message from the NDEF records list.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Return value

Example

import tag from '@ohos.nfc.tag';

let uriRecord = tag.ndef.makeUriRecord("https://gitee.com/openharmony");
let textRecord = tag.ndef.makeTextRecord("Hello World", "en");
let ndefRecords = [uriRecord, textRecord];
let ndefMessage;
try {
    ndefMessage = tag.ndef.createNdefMessage(ndefRecords);
    console.log("ndef createNdefMessage ndefMessage: " + ndefMessage);
} catch (busiError) {
    console.log("ndef createNdefMessage busiError: " + busiError);
}

TagInfo

Defines the TagInfo object, which provides information about the tag technologies supported by a card.

System capability: SystemCapability.Communication.NFC.Tag

Required permissions: ohos.permission.NFC_TAG

NdefRecord⁹⁺

Defines an NDEF record. For details, see NFCForum-TS-NDEF_1.0.

System capability: SystemCapability.Communication.NFC.Tag

Technology Type Definition

Enumerates the tag technology types.

System capability: SystemCapability.Communication.NFC.Tag

TnfType⁹⁺

Enumerates the TNF types. For details, see NFCForum-TS-NDEF_1.0.

System capability: SystemCapability.Communication.NFC.Tag

NDEF Record RTD

Enumerates the NDEF record types. For details about the RTD, see NFCForum-TS-NDEF_1.0.

System capability: SystemCapability.Communication.NFC.Tag

NfcForumType⁹⁺

Enumerates the NFC Forum tag types.

System capability: SystemCapability.Communication.NFC.Tag

MifareClassicType⁹⁺

Enumerates the MIFARE Classic tag types.

System capability: SystemCapability.Communication.NFC.Tag

MifareClassicSize⁹⁺

Enumerates the sizes of a MIFARE Classic tag.

System capability: SystemCapability.Communication.NFC.Tag

MifareUltralightType⁹⁺

Enumerates the MIFARE Ultralight tag types.

System capability: SystemCapability.Communication.NFC.Tag