@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"
                        ],
                        "uris": [
                            {
                                "type":"tag-tech/NfcA"
                            },
                            {
                                "type":"tag-tech/IsoDep"
                            }
                            // Add other technology if neccessary,
                            // such as NfcB, NfcF, NfcV, Ndef, MifareClassic, MifareUL, and NdefFormatable.
                        ]
                    }
                ]
            }
        ],
        "requestPermissions": [
            {
                "name": "ohos.permission.NFC_TAG",
                "reason": "tag",
            }
        ]
    }
}

CAUTION

• The actions field is mandatory. It must be ohos.nfc.tag.action.TAG_FOUND and cannot be changed.

• The type field under uris must start with tag-tech/, followed by NfcA, NfcB, NfcF, NfcV, IsoDep, Ndef, MifareClassic, MifareUL, or NdefFormatable. If there are multiple types, enter them in different lines. Incorrect settings of this field will cause a parsing failure.

• 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';
import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import Want from '@ohos.app.ability.Want'

export default class EntryAbility extends UIAbility {
    onCreate(want : Want, launchParam: AbilityConstant.LaunchParam) {
    // Add other code here.

    // want is initialized by the NFC service and contains tagInfo.
    let tagInfo : tag.TagInfo|null = null;
    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.
    let isNfcATag =  false;
    let isIsoDepTag =  false;
    for (let 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) {
      let nfcA : tag.NfcATag|null = null;
      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) {
      let isoDep : tag.IsoDepTag|null = null;
      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 |Name|Type |Mandatory|Description | |——-|——————-|—-|————————————————————-| |taginfo|TagInfo|Yes|Tag information including the technology type and related parameters, which are obtained from tag.getTagInfo(want: Want).|

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.registerForegroundDispatch¹⁰⁺

registerForegroundDispatch(elementName: ElementName, discTech: number[], callback: AsyncCallback<TagInfo>): void;

Registers listening for the card reading events of an NFC tag foreground application. You can set the supported tag technologies in discTech, and obtain the TagInfo read in a callback.
This API must be used with tag.unregisterForegroundDispatch in pairs. The registered event listening must be unregistered before the page exits the foreground or the page is destroyed.

Required permissions: ohos.permission.NFC_TAG

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Example

See the example of tag.unregisterForegroundDispatch.

tag.unregisterForegroundDispatch¹⁰⁺

unregisterForegroundDispatch(elementName: ElementName): void;

Unregisters the listening for card reading events of an NFC tag foreground application. The registered event listening must be unregistered before the page exits the foreground or the page is destroyed.

Required permissions: ohos.permission.NFC_TAG

System capability: SystemCapability.Communication.NFC.Tag

Parameters

Example

import Want from '@ohos.app.ability.Want'
import UIAbility from '@ohos.app.ability.UIAbility'
import tag from '@ohos.nfc.tag';
import { BusinessError } from '@ohos.base';
import bundleManager from '@ohos.bundle.bundleManager';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';

let discTech : number[] = [tag.NFC_A, tag.NFC_B]; // replace with the tech(s) that is needed by foreground ability
let elementName : bundleManager.ElementName;
function foregroundCb(err : BusinessError, tagInfo : tag.TagInfo) {
    if (err as BusinessError) {
        if (!err) {
            console.log("foreground callback: tag found tagInfo = ", JSON.stringify(tagInfo));
        } else {
            console.log("foreground callback err: " + (err as BusinessError).message);
            return;
        }
    }
  // Other operations of taginfo.
}

export default class MainAbility extends UIAbility {
    OnCreate(want : Want, launchParam : AbilityConstant.LaunchParam) {
        console.log("OnCreate");
        elementName = {
            bundleName: want.bundleName as string,
            abilityName: want.abilityName as string,
            moduleName: want.moduleName as string
        }
    }

    onForeground() {
        console.log("onForeground");
        try {
            tag.registerForegroundDispatch(elementName, discTech, foregroundCb);
        } catch (e) {
            console.log("registerForegroundDispatch error: " + (e as BusinessError).message);
        }
    }

    onBackground() {
        console.log("onBackground");
        try {
            tag.unregisterForegroundDispatch(elementName);
        } catch (e) {
            console.log("registerForegroundDispatch error: " + (e as BusinessError).message);
        }
    }

    onWindowStageDestroy() {
        console.log("onWindowStageDestroy");
        try {
            tag.unregisterForegroundDispatch(elementName);
        } catch (e) {
            console.log("registerForegroundDispatch error: " + (e as BusinessError).message);
        }
    }

  // Override other lifecycle functions.
}

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.
try {
    let ndefMessage = tag.ndef.createNdefMessage(rawData);
    console.log("ndef createNdefMessage, ndefMessage: " + ndefMessage);
    let rawData2 = tag.ndef.messageToBytes(ndefMessage);
    console.log("ndefMessage messageToBytes rawData2: " + rawData2);
} catch (busiError) {
    console.log("ndef createNdefMessage 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.
try {
    let 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];
try {
    let 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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙APIs

harmony 鸿蒙System Common Events (To Be Deprecated Soon)

harmony 鸿蒙System Common Events

harmony 鸿蒙API Reference Document Description

harmony 鸿蒙Enterprise Device Management Overview (for System Applications Only)

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager)

harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)

harmony 鸿蒙@ohos.bundle (Bundle)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)