openharmony 鸿蒙 js-apis-nfcTag

2025-06-12 浏览 (1)

@ohos.nfc.tag (Standard NFC Tags)

The tag module provides APIs for operating and managing NFC tags. The following tag read modes are available:
Background mode: The device reads the tag by using NFC without starting any application, and then searches for applications based on the tag type. If only one application is matched, the card reading page of that application will be started. If multiple applications are matched, an application selector will be started, asking the user to select an application.
Foreground mode: A foreground application has priority to read the NFC tag discovered.

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.

Declaring the NFC Tag Background Mode

To enable NFC tags to be read without starting an application, declare NFC-related attributes in the module.json5 file.

{
    "module": {
        // Other declared attributes

        "abilities": [
            {
                "skills": [
                    {
                        "actions": [
                            // Other declared actions

                            // Add the action of the NFC tag.
                            "ohos.nfc.tag.action.TAG_FOUND"
                        ],
                        "uris": [
                            {
                                "type":"tag-tech/NfcA"
                            },
                            {
                                "type":"tag-tech/IsoDep"
                            }
                            // Add other technologies if necessary.
                            // Example: NfcB, NfcF, NfcV, Ndef, MifareClassic, MifareUL, and NdefFormatable
                        ]
                    }
                ]
            }
        ],
        "requestPermissions": [
            {
                "name": "ohos.permission.NFC_TAG",
                "reason": "$string:app_name",
            }
        ]
    }
}

NOTE

  1. The actions field must contain ohos.nfc.tag.action.TAG_FOUND and cannot be changed.
  2. 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.
  3. The name field under requestPermissions is mandatory. It must be ohos.permission.NFC_TAG and cannot be changed.
  4. When calling the APIs and constants of this module, use canIUse("SystemCapability.Communication.NFC.Tag") to check whether the device supports NFC. If the device does not support NFC, the application stability may be affected. For details, see NFC Tag Read/Write Development.
  5. If an error is reported while importing the tag module editor, the capabilities of a specific device model may exceed the capability set defined for the default device. To use these capabilities, configure a custom SysCap by following instructions in SystemCapability Development.

Modules to Import

import { tag } from '@kit.ConnectivityKit';

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 '@kit.ConnectivityKit';
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';

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

        // Initialize the want that contains the found tag by using the NFC service.
        let tagInfo : tag.TagInfo|null = null;
        try {
            tagInfo = tag.getTagInfo(want);
        } catch (error) {
            console.error("tag.getTagInfo catch error: " + error);
        }
        if (tagInfo == null||tagInfo == undefined) {
            console.log("no TagInfo to be created, ignore it.");
            return;
        }

        // Obtain the list of technologies that can be used for discovering tags.
        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;
            }
        // Check for other technologies, for example, NFC_B, NFC_F, NFC_V, NDEF, MIFARE_CLASSIC, MIFARE_ULTRALIGHT, and NDEF_FORMATABLE.
        }

        // Use NFC-A APIs to access the discovered tags.
        if (isNfcATag) {
            let nfcA : tag.NfcATag|null = null;
            try {
                nfcA = tag.getNfcA(tagInfo);
            } catch (error) {
                console.error("tag.getNfcA catch error: " + error);
            }
            // Code for reading or writing the discovered tag.
        }

        // Use IsoDep APIs to access the discovered tags.
        if (isIsoDepTag) {
            let isoDep : tag.IsoDepTag|null = null;
            try {
                isoDep = tag.getIsoDep(tagInfo);
            } catch (error) {
                console.error("tag.getIsoDep catch error: " + error);
            }
            // Code for reading or writing the discovered tag.
        }
        // Use the same code to process other NFC tags, including NfcA, NfcB, NfcF, NfcV, Ndef, MifareClassic, MifareUL, and NdefFormatable.
    }
}

tag.getNfcATag(deprecated)

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. Use tag.getNfcA instead.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
NfcATagNfcATag object obtained.

tag.getNfcA9+

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

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
NfcATagNfcATag object obtained.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.

tag.getNfcBTag(deprecated)

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. Use tag.getNfcB instead.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
NfcBTagNfcBTag object obtained.

tag.getNfcB9+

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

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
NfcBTagNfcBTag object obtained.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.

tag.getNfcFTag(deprecated)

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. Use tag.getNfcF instead.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
NfcFTagNfcFTag object obtained.

tag.getNfcF9+

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

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
NfcFTagNfcFTag object obtained.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.

tag.getNfcVTag(deprecated)

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. Use tag.getNfcV instead.

System capability: SystemCapability.Communication.NFC.Tag

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
NfcVTagNfcVTag object obtained.

tag.getNfcV9+

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

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
NfcVTagNfcVTag object obtained.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.

tag.getIsoDep9+

getIsoDep(tagInfo: TagInfo): IsoDepTag

Obtains an IsoDepTag object, which allows access to the tags that use the IsoDep technology.

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
IsoDepTagIsoDepTag object obtained.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.

tag.getNdef9+

getNdef(tagInfo: TagInfo): NdefTag

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

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
NdefTagNdefTag object obtained.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.

tag.getMifareClassic9+

getMifareClassic(tagInfo: TagInfo): MifareClassicTag

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

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
MifareClassicTagMifareClassicTag object obtained.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.

tag.getMifareUltralight9+

getMifareUltralight(tagInfo: TagInfo): MifareUltralightTag

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

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
MifareUltralightTagMifareUltralightTag object obtained.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.

tag.getNdefFormatable9+

getNdefFormatable(tagInfo: TagInfo): NdefFormatableTag

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

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
NdefFormatableTagNdefFormatableTag object obtained.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.

tag.getBarcodeTag18+

getBarcodeTag(tagInfo: TagInfo): BarcodeTag

Obtains a BarcodeTag object, which allows access to the tags in the BarcodeTag format.

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 18.

Parameters

NameTypeMandatoryDescription
tagInfoTagInfoYesTag information, including the tag technology type and related parameters, obtained from tag.getTagInfo(want: Want).

Return value

TypeDescription
BartcodeTagBarcodeTag object obtained.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.

tag.getTagInfo9+

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

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
wantWantYesData obtained from the parameters of the onCreate entry function when an ability is dispatched.

Return value

TypeDescription
TagInfoTagInfo object obtained.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.

tag.registerForegroundDispatch10+

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

Registers a listener for the NFC tag read event so that the tag can be preferentially dispatched to a foreground application. You can set the supported NFC tag technologies in discTech. The callback returns TagInfo read. This API can be called only by an application running in the foreground. It must be used with tag.unregisterForegroundDispatch in pairs. The registered callback must be unregistered before the tag reading page exits the foreground or is destroyed.

Required permissions: ohos.permission.NFC_TAG

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
elementNameElementNameYesInformation about the tag reading page of the application. It cannot be empty and must contain at least bundleName and abilityName.
discTechnumber[]YesNFC tag technologies supported by the foreground application. It cannot be empty. At least one NFC tag technology must be specified. Each number indicates the constant value of an NFC tag technology. The tag technologies are polled based on the specified value, which contains one or more of NFC_A, NFC_B, NFC_F, and NFC_V only.
callbackAsyncCallback<TagInfo>YesCallback used to return the tag information read. It cannot be empty.

Error codes

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

IDError Message
201Permission denied.
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.
3100202The element state is invalid.

Example

See the example of tag.unregisterForegroundDispatch.

tag.unregisterForegroundDispatch10+

unregisterForegroundDispatch(elementName: ElementName): void

Unregisters the listener for the NFC tag read event. If the listener is unregistered, the NFC tag discovered will not be dispatched to foreground applications. The registered callback must be unregistered before the tag reading page exits the foreground or is destroyed.

Required permissions: ohos.permission.NFC_TAG

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
elementNameElementNameYesInformation about the tag reading page of the application. It cannot be empty and must contain at least bundleName and abilityName.

Error codes

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

IDError Message
201Permission denied.
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.

Example


import { tag } from '@kit.ConnectivityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant, UIAbility, Want, bundleManager } from '@kit.AbilityKit';

let discTech: number[] = [tag.NFC_A, tag.NFC_B]; // Specify the technology required for foreground ability.
let elementName : bundleManager.ElementName;
function foregroundCb(err : BusinessError, tagInfo : tag.TagInfo) {
    if (!err) {
        console.log("foreground callback: tag found tagInfo = ", JSON.stringify(tagInfo));
    } else {
        console.log("foreground callback err: " + err.message);
        return;
    }
  // Other operations on 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.error("registerForegroundDispatch error: " + (e as BusinessError).message);
        }
    }

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

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

  // Other functions in the ability lifecycle
}

tag.on11+

on(type: 'readerMode', elementName: ElementName, discTech: number[], callback: AsyncCallback<TagInfo>): void

Subscribes to the NFC tag read event to implement dispatch of the tag to a foreground application preferentially. The device enters the reader mode and disables card simulation. You can set the supported NFC tag technologies in discTech. The callback returns TagInfo read. This API must be used with tag.off in pairs. If the NFC reader mode is enabled by tag.on, tag.off must be called when the application page exits the foreground or is destroyed.

Required permissions: ohos.permission.NFC_TAG

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
typestringYesEvent type, which has a fixed value of readerMode.
elementNameElementNameYesInformation about the tag reading page of the application. It cannot be empty and must contain at least bundleName and abilityName.
discTechnumber[]YesNFC tag technologies supported by the foreground application. It cannot be empty. At least one NFC tag technology must be specified. Each number indicates the constant value of an NFC tag technology. The tag technologies are polled based on the specified value, which contains one or more of NFC_A, NFC_B, NFC_F, and NFC_V only.
callbackAsyncCallback<TagInfo>YesCallback used to return the tag information read. It cannot be empty.

Error codes

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

IDError Message
201Permission denied.
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.
3100202The element state is invalid.

Example

See the example of tag.off.

tag.off11+

off(type: 'readerMode', elementName: ElementName, callback?: AsyncCallback<TagInfo>): void

Unsubscribes from the NFC tag card read event. The device exits the reader mode and resumes card simulation. If the NFC reader mode is enabled by tag.on, this API must be used when the application page exits the foreground or is destroyed.

Required permissions: ohos.permission.NFC_TAG

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
typestringYesEvent type, which has a fixed value of readerMode.
elementNameElementNameYesInformation about the tag reading page of the application. It cannot be empty and must contain at least bundleName and abilityName.
callbackAsyncCallback<TagInfo>NoCallback to unregister.

Error codes

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

IDError Message
201Permission denied.
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.
801Capability not supported.
3100201The tag running state is abnormal in the service.
3100203The off() API can be called only when the on() has been called.

Example

import { tag } from '@kit.ConnectivityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { AbilityConstant, UIAbility, Want, bundleManager } from '@kit.AbilityKit';

let discTech: number[] = [tag.NFC_A, tag.NFC_B]; // Specify the technology required for foreground ability.
let elementName : bundleManager.ElementName;

function readerModeCb(err : BusinessError, tagInfo : tag.TagInfo) {
    if (!err) {
        console.log("offCallback: tag found tagInfo = ", JSON.stringify(tagInfo));
    } else {
        console.error("offCallback err: " + err.message);
        return;
    }
  // Other operations on 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("on start");
        try {
            tag.on('readerMode', elementName, discTech, readerModeCb);
        } catch (e) {
            console.error("tag.on error: " + (e as BusinessError).message);
        }
    }

    onBackground() {
        console.log("onBackground");
        try {
            tag.off('readerMode', elementName, readerModeCb);
        } catch (e) {
            console.error("tag.off error: " + (e as BusinessError).message);
        }
    }

    onWindowStageDestroy() {
        console.log("onWindowStageDestroy");
        try {
            tag.off('readerMode', elementName, readerModeCb);
        } catch (e) {
            console.error("tag.off error: " + (e as BusinessError).message);
        }
    }

  // Other functions in the ability lifecycle
}

tag.ndef.makeUriRecord9+

makeUriRecord(uri: string): NdefRecord

Creates an NDEF record based on the specified URI.

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
uristringYesData to write to the NDEF record.

Return value

TypeDescription
NdefRecordNDEF record created. For details, see NFCForum-TS-NDEF_1.0.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.

Example

import { tag } from '@kit.ConnectivityKit';

try {
    let uri = "https://www.example.com"; // Set the correct URI.
    let ndefRecord : tag.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 (businessError) {
    console.error("ndefMessage makeUriRecord catch businessError: " + businessError);
}

tag.ndef.makeTextRecord9+

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

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
textstringYesText to write to the NDEF record.
localestringYesEncoding mode of the text.

Return value

TypeDescription
NdefRecordNDEF record created. For details, see NFCForum-TS-NDEF_1.0.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.

Example

import { tag } from '@kit.ConnectivityKit';

try {
    let text = "Hello World"; // Set the text as demanded.
    let locale = "en"; // Set the expected encoding format.
    let ndefRecord : tag.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 (businessError) {
    console.error("ndefMessage makeTextRecord catch businessError: " + businessError);
}

tag.ndef.makeApplicationRecord18+

makeApplicationRecord(bundleName: string): NdefRecord

Creates an NDEF record based on the specified application bundle name.

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 18.

Parameters

NameTypeMandatoryDescription
bundleNamestringYesApplication bundle name.

Return value

TypeDescription
NdefRecordNDEF record created. For details, see NFCForum-TS-NDEF_1.0.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.

Example

import { tag } from '@kit.ConnectivityKit';

try {
    let bundleName: string = 'com.demo.test';
    let ndefRecord : tag.NdefRecord = tag.ndef.makeApplicationRecord(bundleName);
    if (ndefRecord != undefined) {
        console.log("ndefMessage makeApplicationRecord rtdType: " + ndefRecord.rtdType);
        console.log("ndefMessage makeApplicationRecord payload: " + ndefRecord.payload);
    } else {
        console.log("ndefMessage makeApplicationRecord ndefRecord: " + ndefRecord);
    }
} catch (businessError) {
    console.error("ndefMessage makeApplicationRecord catch businessError: " + businessError);
}

tag.ndef.makeMimeRecord9+

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

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

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
mimeTypestringYesMIME type that complies with RFC rules, for example, text/plain or image/jpeg.
mimeDatanumber[]YesMIME data, which consists of hexadecimal numbers ranging from 0x00 to 0xFF.

Return value

TypeDescription
NdefRecordNDEF record created. For details, see NFCForum-TS-NDEF_1.0.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.

Example

import { tag } from '@kit.ConnectivityKit';

try {
    let mimeType = "text/plain"; // Set a correct MIME type.
    let mimeData = [0x01, 0x02, 0x03, 0x04]; // Set the correct MIME data.
    let ndefRecord : tag.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 (businessError) {
    console.error("ndefMessage makeMimeRecord catch businessError: " + businessError);
}

tag.ndef.makeExternalRecord9+

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

Creates an NDEF record based on application-specific data.

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
domainNamestringYesBundle name of the application or domain name of the organization that releases the applications.
typestringYesType of the application data.
externalDatanumber[]YesApplication data, which consists of hexadecimal numbers ranging from 0x00 to 0xFF.

Return value

TypeDescription
NdefRecordNDEF record created. For details, see NFCForum-TS-NDEF_1.0.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.

Example

import { tag } from '@kit.ConnectivityKit';

try {
    let domainName = "ohos.nfc.application"; // Set a correct bundle name.
    let type = "test"; // Set a correct data type.
    let externalData = [0x01, 0x02, 0x03, 0x04]; // Set the correct external data.
    let ndefRecord : tag.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 (businessError) {
    console.error("ndefMessage makeExternalRecord catch businessError: " + businessError);
}

tag.ndef.messageToBytes9+

messageToBytes(ndefMessage: NdefMessage): number[]

Converts an NDEF message to bytes.

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
ndefMessageNdefMessageYesNDEF message to convert.

Return value

TypeDescription
number[]NDEF message in bytes, which consists of hexadecimal numbers ranging from 0x00 to 0xFF.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.

Example

import { tag } from '@kit.ConnectivityKit';

let rawData = [0xD1, 0x01, 0x03, 0x54, 0x4E, 0x46, 0x43]; // Set the correct raw data, which is in the NDEF format.
try {
    let ndefMessage : tag.NdefMessage = tag.ndef.createNdefMessage(rawData);
    console.log("ndef createNdefMessage, ndefMessage: " + ndefMessage);
    let rawData2 = tag.ndef.messageToBytes(ndefMessage);
    console.log("ndefMessage messageToBytes rawData2: " + rawData2);
} catch (businessError) {
    console.error("ndef createNdefMessage businessError: " + businessError);
}

tag.ndef.createNdefMessage9+

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

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
datanumber[]YesRaw byte data, which consists of hexadecimal numbers ranging from 0x00 to 0xFF. The data must comply with the NDEF record format.

Return value

TypeDescription
NdefMessageNDEF message created. For details, see NFCForum-TS-NDEF_1.0.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.

Example

import { tag } from '@kit.ConnectivityKit';

let rawData = [0xD1, 0x01, 0x03, 0x54, 0x4E, 0x46, 0x43]; // The NDEF data must be resolvable.
try {
    let ndefMessage : tag.NdefMessage = tag.ndef.createNdefMessage(rawData);
    console.log("ndef createNdefMessage, ndefMessage: " + ndefMessage);
} catch (businessError) {
    console.error("ndef createNdefMessage businessError: " + businessError);
}

tag.ndef.createNdefMessage9+

createNdefMessage(ndefRecords: NdefRecord[]): NdefMessage

Creates an NDEF message from the NDEF records list.

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

Parameters

NameTypeMandatoryDescription
ndefRecordsNdefRecord[]YesNDEF record list used to create the NDEF message. For details, see NFCForum-TS-NDEF_1.0.

Return value

TypeDescription
NdefMessageNDEF message created. For details, see NFCForum-TS-NDEF_1.0.

Error codes

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

IDError Message
401The parameter check failed. Possible causes:
1. Mandatory parameters are left unspecified.
2. Incorrect parameters types.
3. Parameter verification failed.

Example

import { tag } from '@kit.ConnectivityKit';

let uriRecord : tag.NdefRecord = tag.ndef.makeUriRecord("https://www.example.com");
let textRecord : tag.NdefRecord = tag.ndef.makeTextRecord("Hello World", "en");
let ndefRecords : tag.NdefRecord[] = [uriRecord, textRecord];
try {
    let ndefMessage : tag.NdefMessage = tag.ndef.createNdefMessage(ndefRecords);
    console.log("ndef createNdefMessage ndefMessage: " + ndefMessage);
} catch (businessError) {
    console.error("ndef createNdefMessage businessError: " + businessError);
}

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

NameTypeReadableWritableDescription
uid9+number[]YesNoTag unique identifier (UID), which consists of hexadecimal numbers ranging from 0x00 to 0xFF.
Atomic service API: This API can be used in atomic services since API version 12.
technology9+number[]YesNoSupported tag technologies. Each number is a constant indicating the supported technology.
Atomic service API: This API can be used in atomic services since API version 12.
supportedProfilesnumber[]YesNoSupported profiles. This parameter is not supported since API version 9. Use tag.TagInfo#technology instead.

NdefRecord9+

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

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

NameTypeReadableWritableDescription
tnfnumberYesNoType name field (TNF) of the NDEF record.
rtdTypenumber[]YesNoRecord type definition (RTD) of the NDEF record. It consists of hexadecimal numbers ranging from 0x00 to 0xFF.
idnumber[]YesNoNDEF record ID, which consists of hexadecimal numbers ranging from 0x00 to 0xFF.
payloadnumber[]YesNoNDEF payload, which consists of hexadecimal numbers ranging from 0x00 to 0xFF.

Constants

Enumerates the tag technology types.

System capability: SystemCapability.Communication.NFC.Tag

NameTypeValueDescription
NFC_A12+number1NFC-A (ISO 14443-3A).
Atomic service API: This API can be used in atomic services since API version 12.
NFC_B12+number2NFC-B (ISO 14443-3B).
Atomic service API: This API can be used in atomic services since API version 12.
ISO_DEP12+number3ISO-DEP (ISO 14443-4).
Atomic service API: This API can be used in atomic services since API version 12.
NFC_F12+number4NFC-F (JIS 6319-4).
Atomic service API: This API can be used in atomic services since API version 12.
NFC_V12+number5NFC-V (ISO 15693).
Atomic service API: This API can be used in atomic services since API version 12.
NDEF12+number6NDEF.
Atomic service API: This API can be used in atomic services since API version 12.
NDEF_FORMATABLE9+number7NDEF formattable.
Atomic service API: This API can be used in atomic services since API version 12.
MIFARE_CLASSIC12+number8MIFARE Classic.
Atomic service API: This API can be used in atomic services since API version 12.
MIFARE_ULTRALIGHT12+number9MIFARE Ultralight.
Atomic service API: This API can be used in atomic services since API version 12.
NFC_BARCODE18+number10BARCODE technology.
Atomic service API: This API can be used in atomic services since API version 18.

TnfType9+

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

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

NameValueDescription
TNF_EMPTY0x0Empty.
TNF_WELL_KNOWN0x1NFC Forum Well Known Type [NFC RTD].
TNF_MEDIA0x2Media-type as defined in RFC 2046 [RFC 2046].
TNF_ABSOLUTE_URI0x3Absolute URI as defined in RFC 3986 [RFC 3986].
TNF_EXT_APP0x4NFC Forum external type [NFC RTD].
TNF_UNKNOWN0x5Unknown.
TNF_UNCHANGED0x6Unchanged (see section 2.3.3 in NFCForum-TS-NDEF_1.0).

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

Atomic service API: This API can be used in atomic services since API version 12.

NameTypeValueDescription
RTD_TEXT9+number[][0x54]NDEF record of the text type.
RTD_URI9+number[][0x55]NDEF record of the URI type.

NfcForumType9+

Enumerates the NFC Forum tag types.

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

NameValueDescription
NFC_FORUM_TYPE_11NFC Forum tag type 1.
NFC_FORUM_TYPE_22NFC Forum tag type 2.
NFC_FORUM_TYPE_33NFC Forum tag type 3.
NFC_FORUM_TYPE_44NFC Forum tag type 4.
MIFARE_CLASSIC101MIFARE Classic.

MifareClassicType9+

Enumerates the MIFARE Classic tag types.

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

NameValueDescription
TYPE_UNKNOWN0Unknown type.
TYPE_CLASSIC1MIFARE Classic.
TYPE_PLUS2MIFARE Plus.
TYPE_PRO3MIFARE Pro.

MifareClassicSize9+

Enumerates the sizes of a MIFARE Classic tag.

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

NameValueDescription
MC_SIZE_MINI320Each tag has 5 sectors, and each sector has 4 blocks.
MC_SIZE_1K1024Each tag has 16 sectors, and each sector has 4 blocks.
MC_SIZE_2K2048Each tag has 32 sectors, and each sector has 4 blocks.
MC_SIZE_4K4096Each tag has 40 sectors, and each sector has 4 blocks.

MifareUltralightType9+

Enumerates the MIFARE Ultralight tag types.

System capability: SystemCapability.Communication.NFC.Tag

Atomic service API: This API can be used in atomic services since API version 12.

NameValueDescription
TYPE_UNKNOWN0Unknown type.
TYPE_ULTRALIGHT1MIFARE Ultralight.
TYPE_ULTRALIGHT_C2MIFARE Ultralight C.

NfcATag7+

type NfcATag = _NfcATag

Defines an NfcATag object.

System capability: SystemCapability.Communication.NFC.Tag Atomic service API: This API can be used in atomic services since API version 12.

TypeDescription
_NfcATagObject that implements access to NFC-A (ISO 15693) properties and I/O operations on a tag.

NfcBTag7+

type NfcBTag = _NfcBTag

Obtains an NfcBTag object.

System capability: SystemCapability.Communication.NFC.Tag Atomic service API: This API can be used in atomic services since API version 12.

TypeDescription
_NfcBTagObject that implements access to NFC-B (ISO 14443-3B) properties and I/O operations on a tag.

NfcFTag7+

type NfcFTag = _NfcFTag

Obtains an NfcFTag object.

System capability: SystemCapability.Communication.NFC.Tag Atomic service API: This API can be used in atomic services since API version 12.

TypeDescription
_NfcFTagObject that implements access to NFC-F (ISO 6319-4) properties and I/O operations on a tag.

NfcVTag7+

type NfcVTag = _NfcVTag

Obtains an NfcVTag object.

System capability: SystemCapability.Communication.NFC.Tag Atomic service API: This API can be used in atomic services since API version 12.

TypeDescription
_NfcVTagObject that implements access to NFC-V (ISO 15693) properties and I/O operations on a tag.

IsoDepTag9+

type IsoDepTag = _IsoDepTag

Obtains an IsoDepTag object.

System capability: SystemCapability.Communication.NFC.Tag Atomic service API: This API can be used in atomic services since API version 12.

TypeDescription
_IsoDepTagObject that implements access to ISO-DEP (ISO 14443-4) properties and I/O operations on a tag.

NdefTag9+

type NdefTag = _NdefTag

Obtains an NdefTag object.

System capability: SystemCapability.Communication.NFC.Tag Atomic service API: This API can be used in atomic services since API version 12.

TypeDescription
_NdefTagObject that implements access to NDEF tags.

MifareClassicTag9+

type MifareClassicTag = _MifareClassicTag

Obtains a MifareClassicTag object.

System capability: SystemCapability.Communication.NFC.Tag Atomic service API: This API can be used in atomic services since API version 12.

TypeDescription
_MifareClassicTagObject that implements access to MIFARE Classic properties and I/O operations on a tag.

MifareUltralightTag9+

type MifareUltralightTag = _MifareUltralightTag;

Obtains a MifareUltralightTag object.

System capability: SystemCapability.Communication.NFC.Tag Atomic service API: This API can be used in atomic services since API version 12.

TypeDescription
_MifareUltralightTagObject that implements access to MIFARE Ultralight properties and I/O operations on a tag.

NdefFormatableTag9+

type NdefFormatableTag = _NdefFormatableTag

Obtains a NdefFormatableTag object.

System capability: SystemCapability.Communication.NFC.Tag Atomic service API: This API can be used in atomic services since API version 12.

TypeDescription
_NdefFormatableTagObject that implements formatting of NDEF formattable tags.

BarcodeTag18+

type BarcodeTag = _BarcodeTag

Obtains a BarcodeTag object.

System capability: SystemCapability.Communication.NFC.Tag Atomic service API: This API can be used in atomic services since API version 18.

TypeDescription
_BarcodeTagObject that implements access to the barcode tag properties and I/O operations on a tag.

NdefMessage9+

type NdefMessage = _NdefMessage

Obtains an NdefMessage object.

System capability: SystemCapability.Communication.NFC.Tag Atomic service API: This API can be used in atomic services since API version 12.

TypeDescription
_NdefMessageObtains all NDEF records.

TagSession7+

type TagSession = _TagSession

Obtains a TagSession object.

System capability: SystemCapability.Communication.NFC.Tag Atomic service API: This API can be used in atomic services since API version 12.

TypeDescription
_TagSessionBase class of all NFC tag technologies. It provides common APIs for establishing connections and transferring data.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Connectivity Kit (Short-Range Communication Service)

harmony 鸿蒙Bluetooth

harmony 鸿蒙Wifi

harmony 鸿蒙Bluetooth Error Codes

harmony 鸿蒙NFC Error Codes

harmony 鸿蒙SecureElement Error Codes

harmony 鸿蒙Wi-Fi Error Codes

harmony 鸿蒙@ohos.bluetooth.a2dp (Bluetooth A2DP Module) (System API)

harmony 鸿蒙@ohos.bluetooth.a2dp (Bluetooth A2DP Module)

harmony 鸿蒙@ohos.bluetooth.access (Bluetooth Access Module) (System API)

  • 所属分类: 后端技术
  • 本文标签: 鸿蒙 软件
  • 版权声明: 本文链接 https://seaxiang.com/blog/sTPY0a