1# @ohos.nfc.tag (Standard NFC Tags) 2 3The **nfcTag** module provides APIs for managing Near-Field Communication (NFC) tags. 4 5> **NOTE** 6> 7> 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. 8 9## **Declaration** 10 11Before 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: 12```json 13{ 14 "module": { 15 // Attributes to declare. 16 17 "abilities": [ 18 { 19 "skills": [ 20 { 21 "actions": [ 22 // Actions to declare. 23 24 // Add the nfc tag action. 25 "ohos.nfc.tag.action.TAG_FOUND" 26 ], 27 "uris": [ 28 { 29 "type":"tag-tech/NfcA" 30 }, 31 { 32 "type":"tag-tech/IsoDep" 33 } 34 // Add other technology if neccessary, 35 // such as NfcB, NfcF, NfcV, Ndef, MifareClassic, MifareUL, and NdefFormatable. 36 ] 37 } 38 ] 39 } 40 ], 41 "requestPermissions": [ 42 { 43 "name": "ohos.permission.NFC_TAG", 44 "reason": "tag", 45 } 46 ] 47 } 48} 49``` 50> **NOTE** 51> 52> - The **actions** field is mandatory. It must be **ohos.nfc.tag.action.TAG_FOUND** and cannot be changed. 53> - 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. 54> - The **name** field under **requestPermissions** is mandatory. It must be **ohos.permission.NFC_TAG** and cannot be changed. 55 56 57## **Modules to Import** 58 59```js 60import tag from '@ohos.nfc.tag'; 61``` 62 63## **tag.TagInfo** 64 65Before a card with tags is read or written, **[TagInfo](#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. 66```js 67import tag from '@ohos.nfc.tag'; 68import UIAbility from '@ohos.app.ability.UIAbility'; 69import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 70import Want from '@ohos.app.ability.Want' 71 72export default class EntryAbility extends UIAbility { 73 onCreate(want : Want, launchParam: AbilityConstant.LaunchParam) { 74 // Add other code here. 75 76 // want is initialized by the NFC service and contains tagInfo. 77 let tagInfo : tag.TagInfo | null = null; 78 try { 79 tagInfo = tag.getTagInfo(want); 80 } catch (error) { 81 console.error("tag.getTagInfo catched error: " + error); 82 } 83 if (tagInfo == null || tagInfo == undefined) { 84 console.log("no TagInfo to be created, ignore it."); 85 return; 86 } 87 88 // Obtain the supported technologies for this found tag. 89 let isNfcATag = false; 90 let isIsoDepTag = false; 91 for (let i = 0; i < tagInfo.technology.length; i++) { 92 if (tagInfo.technology[i] == tag.NFC_A) { 93 isNfcATag = true; 94 } 95 96 if (tagInfo.technology[i] == tag.ISO_DEP) { 97 isIsoDepTag = true; 98 } 99 // Also check for technology tag.NFC_B, NFC_F, NFC_V, ISO_DEP, NDEF, MIFARE_CLASSIC, MIFARE_ULTRALIGHT, and NDEF_FORMATABLE. 100 } 101 102 // Use NfcA APIs to access the found tag. 103 if (isNfcATag) { 104 let nfcA : tag.NfcATag | null = null; 105 try { 106 nfcA = tag.getNfcATag(tagInfo); 107 } catch (error) { 108 console.error("tag.getNfcATag catched error: " + error); 109 } 110 // Other code to read or write this tag. 111 } 112 113 // Use getIsoDep APIs to access the found tag. 114 if (isIsoDepTag) { 115 let isoDep : tag.IsoDepTag | null = null; 116 try { 117 isoDep = tag.getIsoDep(tagInfo); 118 } catch (error) { 119 console.error("tag.getIsoDep catched error: " + error); 120 } 121 // Other code to read or write this tag. 122 } 123 // Use the same code to handle "NfcA/NfcB/NfcF/NfcV/Ndef/MifareClassic/MifareUL/NdefFormatable". 124 } 125} 126``` 127 128## tag.getNfcATag<sup>(deprecated)</sup> 129 130getNfcATag(tagInfo: [TagInfo](#taginfo)): [NfcATag](js-apis-nfctech.md#nfcatag) 131 132Obtains an **NfcATag** object, which allows access to the tags that use the NFC-A technology. 133 134> **NOTE** 135> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [tag.getNfcA](#taggetnfca9). 136 137**System capability**: SystemCapability.Communication.NFC.Tag 138 139**Parameters** 140 141| Name | Type | Mandatory| Description | 142| ------- | ------------------- | ---- | ------------------------------------------------------------- | 143| tagInfo | [TagInfo](#taginfo) | Yes | Tag information including the technology type and related parameters, which are obtained from **tag.getTagInfo(want: Want)**.| 144 145**Return value** 146 147| **Type** | **Description** | 148| ------------------------------------- | ------------------ | 149| [NfcATag](js-apis-nfctech.md#nfcatag) | **NfcATag** object obtained.| 150 151## tag.getNfcA<sup>9+</sup> 152 153getNfcA(tagInfo: [TagInfo](#taginfo)): [NfcATag](js-apis-nfctech.md#nfcatag) 154 155Obtains an **NfcATag** object, which allows access to the tags that use the NFC-A technology. 156 157**System capability**: SystemCapability.Communication.NFC.Tag 158 159**Parameters** 160 161| Name | Type | Mandatory| Description | 162| ------- | ------------------- | ---- | ------------------------------------------------------------- | 163| tagInfo | [TagInfo](#taginfo) | Yes | Tag information including the technology type and related parameters, which are obtained from **tag.getTagInfo(want: Want)**.| 164 165**Return value** 166 167| **Type** | **Description** | 168| ------------------------------------- | ------------------ | 169| [NfcATag](js-apis-nfctech.md#nfcatag) | **NfcATag** object obtained.| 170 171**Error codes** 172 173For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md). 174 175| ID| Error Message | 176| -------- | ----------------------------------------- | 177| 3100201 | Tag running state is abnormal in service. | 178 179## tag.getNfcBTag<sup>(deprecated)</sup> 180 181getNfcBTag(tagInfo: [TagInfo](#taginfo)): [NfcBTag](js-apis-nfctech.md#nfcbtag) 182 183Obtains an **NfcBTag** object, which allows access to the tags that use the NFC-B technology. 184 185> **NOTE** 186> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [tag.getNfcB](#taggetnfcb9). 187 188**System capability**: SystemCapability.Communication.NFC.Tag 189 190**Parameters** 191 192| Name | Type | Mandatory| Description | 193| ------- | ------------------- | ---- | ------------------------------------------------------------- | 194| tagInfo | [TagInfo](#taginfo) | Yes | Tag information including the technology type and related parameters, which are obtained from **tag.getTagInfo(want: Want)**.| 195 196**Return value** 197 198| **Type** | **Description** | 199| ------------------------------------- | ------------------ | 200| [NfcBTag](js-apis-nfctech.md#nfcbtag) | **NfcBTag** object obtained.| 201 202## tag.getNfcB<sup>9+</sup> 203 204getNfcB(tagInfo: [TagInfo](#taginfo)): [NfcBTag](js-apis-nfctech.md#nfcbtag) 205 206Obtains an **NfcBTag** object, which allows access to the tags that use the NFC-B technology. 207 208**System capability**: SystemCapability.Communication.NFC.Tag 209 210**Parameters** 211 212| Name | Type | Mandatory| Description | 213| ------- | ------------------- | ---- | ------------------------------------------------------------- | 214| tagInfo | [TagInfo](#taginfo) | Yes | Tag information including the technology type and related parameters, which are obtained from **tag.getTagInfo(want: Want)**.| 215 216**Return value** 217 218| **Type** | **Description** | 219| ------------------------------------- | ------------------ | 220| [NfcBTag](js-apis-nfctech.md#nfcbtag) | **NfcBTag** object obtained.| 221 222**Error codes** 223 224For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md). 225 226| ID| Error Message | 227| -------- | ----------------------------------------- | 228| 3100201 | Tag running state is abnormal in service. | 229 230## tag.getNfcFTag<sup>(deprecated)</sup> 231 232getNfcFTag(tagInfo: [TagInfo](#taginfo)): [NfcFTag](js-apis-nfctech.md#nfcftag) 233 234Obtains an **NfcFTag** object, which allows access to the tags that use the NFC-F technology. 235 236> **NOTE** 237> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [tag.getNfcF](#taggetnfcf9). 238 239**System capability**: SystemCapability.Communication.NFC.Tag 240 241**Parameters** 242 243| Name | Type | Mandatory| Description | 244| ------- | ------------------- | ---- | ------------------------------------------------------------- | 245| tagInfo | [TagInfo](#taginfo) | Yes | Tag information including the technology type and related parameters, which are obtained from **tag.getTagInfo(want: Want)**.| 246 247**Return value** 248 249| **Type** | **Description** | 250| ------------------------------------- | ------------------ | 251| [NfcFTag](js-apis-nfctech.md#nfcftag) | **NfcFTag** object obtained.| 252 253## tag.getNfcF<sup>9+</sup> 254 255getNfcF(tagInfo: [TagInfo](#taginfo)): [NfcFTag](js-apis-nfctech.md#nfcftag) 256 257Obtains an **NfcFTag** object, which allows access to the tags that use the NFC-F technology. 258 259**System capability**: SystemCapability.Communication.NFC.Tag 260 261**Parameters** 262 263| Name | Type | Mandatory| Description | 264| ------- | ------------------- | ---- | ------------------------------------------------------------- | 265| tagInfo | [TagInfo](#taginfo) | Yes | Tag information including the technology type and related parameters, which are obtained from **tag.getTagInfo(want: Want)**.| 266 267**Return value** 268 269| **Type** | **Description** | 270| ------------------------------------- | ------------------ | 271| [NfcFTag](js-apis-nfctech.md#nfcftag) | **NfcFTag** object obtained.| 272 273**Error codes** 274 275For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md). 276 277| ID| Error Message | 278| -------- | ----------------------------------------- | 279| 3100201 | Tag running state is abnormal in service. | 280 281## tag.getNfcVTag<sup>(deprecated)</sup> 282 283getNfcVTag(tagInfo: [TagInfo](#taginfo)): [NfcVTag](js-apis-nfctech.md#nfcvtag) 284 285Obtains an **NfcVTag** object, which allows access to the tags that use the NFC-V technology. 286 287> **NOTE** 288> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [tag.getNfcV](#taggetnfcv9). 289 290**System capability**: SystemCapability.Communication.NFC.Tag 291 292**Parameters** 293 294| Name | Type | Mandatory| Description | 295| ------- | ------------------- | ---- | ------------------------------------------------------------- | 296| tagInfo | [TagInfo](#taginfo) | Yes | Tag information including the technology type and related parameters, which are obtained from **tag.getTagInfo(want: Want)**.| 297 298**Return value** 299 300| **Type** | **Description** | 301| ------------------------------------- | ------------------ | 302| [NfcVTag](js-apis-nfctech.md#nfcvtag) | **NfcVTag** object obtained.| 303 304## tag.getNfcV<sup>9+</sup> 305 306getNfcV(tagInfo: [TagInfo](#taginfo)): [NfcVTag](js-apis-nfctech.md#nfcvtag) 307 308Obtains an **NfcVTag** object, which allows access to the tags that use the NFC-V technology. 309 310**System capability**: SystemCapability.Communication.NFC.Tag 311 312**Parameters** 313 314| Name | Type | Mandatory| Description | 315| ------- | ------------------- | ---- | ------------------------------------------------------------- | 316| tagInfo | [TagInfo](#taginfo) | Yes | Tag information including the technology type and related parameters, which are obtained from **tag.getTagInfo(want: Want)**.| 317 318**Return value** 319 320| **Type** | **Description** | 321| ------------------------------------- | ------------------ | 322| [NfcVTag](js-apis-nfctech.md#nfcvtag) | **NfcVTag** object obtained.| 323 324**Error codes** 325 326For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md). 327 328| ID| Error Message | 329| -------- | ----------------------------------------- | 330| 3100201 | Tag running state is abnormal in service. | 331 332## tag.getIsoDep<sup>9+</sup> 333 334getIsoDep(tagInfo: [TagInfo](#taginfo)): [IsoDepTag](js-apis-nfctech.md#isoDepTag9 ) 335 336Obtains an **IsoDepTag** object, which allows access to the tags that use the ISO-DEP technology. 337 338**System capability**: SystemCapability.Communication.NFC.Tag 339 340**Parameters** 341 342| Name | Type | Mandatory| Description | 343| ------- | ------------------- | ---- | ------------------------------------------------------------- | 344| tagInfo | [TagInfo](#taginfo) | Yes | Tag information including the technology type and related parameters, which are obtained from **tag.getTagInfo(want: Want)**.| 345 346**Return value** 347 348| **Type** | **Description** | 349| ------------------------------------------ | ------------------------------------------------------- | 350| [IsoDepTag](js-apis-nfctech.md#isodeptag9) | **IsoDepTag** object obtained.| 351 352**Error codes** 353 354For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md). 355 356| ID| Error Message | 357| -------- | ----------------------------------------- | 358| 3100201 | Tag running state is abnormal in service. | 359 360## tag.getNdef<sup>9+</sup> 361 362getNdef(tagInfo: [TagInfo](#taginfo)): [NdefTag](js-apis-nfctech.md#ndeftag9) 363 364Obtains an **NdefTag** object, which allows access to the tags in the NFC Data Exchange Format (NDEF). 365 366**System capability**: SystemCapability.Communication.NFC.Tag 367 368**Parameters** 369 370| Name | Type | Mandatory| Description | 371| ------- | ------------------- | ---- | ------------------------------------------------------------- | 372| tagInfo | [TagInfo](#taginfo) | Yes | Tag information including the technology type and related parameters, which are obtained from **tag.getTagInfo(want: Want)**.| 373 374**Return value** 375 376| **Type** | **Description** | 377| -------------------------------------- | --------------------------------------------------- | 378| [NdefTag](js-apis-nfctech.md#ndeftag9) | **NdefTag** object obtained.| 379 380**Error codes** 381 382For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md). 383 384| ID| Error Message | 385| -------- | ----------------------------------------- | 386| 3100201 | Tag running state is abnormal in service. | 387 388## tag.getMifareClassic<sup>9+</sup> 389 390getMifareClassic(tagInfo: [TagInfo](#taginfo)): [MifareClassicTag](js-apis-nfctech.md#mifareclassictag9) 391 392Obtains a **MifareClassicTag** object, which allows access to the tags that use MIFARE Classic. 393 394**System capability**: SystemCapability.Communication.NFC.Tag 395 396**Parameters** 397 398| Name | Type | Mandatory| Description | 399| ------- | ------------------- | ---- | ------------------------------------------------------------- | 400| tagInfo | [TagInfo](#taginfo) | Yes | Tag information including the technology type and related parameters, which are obtained from **tag.getTagInfo(want: Want)**.| 401 402**Return value** 403 404| **Type** | **Description** | 405| --------------------------------------------------------- | ----------------------------------------------------------------------- | 406| [MifareClassicTag](js-apis-nfctech.md#mifareclassictag-9) | **MifareClassicTag** object obtained.| 407 408**Error codes** 409 410For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md). 411 412| ID| Error Message | 413| -------- | ----------------------------------------- | 414| 3100201 | Tag running state is abnormal in service. | 415 416## tag.getMifareUltralight<sup>9+</sup> 417 418getMifareUltralight(tagInfo: [TagInfo](#taginfo)): [MifareUltralightTag](js-apis-nfctech.md#mifareultralighttag9) 419 420Obtains a **MifareUltralightTag** object, which allows access to the tags that use MIFARE Ultralight. 421 422**System capability**: SystemCapability.Communication.NFC.Tag 423 424**Parameters** 425| Name | Type | Mandatory| Description | 426| ------- | ------------------- | ---- | ------------------------------------------------------------- | 427| tagInfo | [TagInfo](#taginfo) | Yes | Tag information including the technology type and related parameters, which are obtained from **tag.getTagInfo(want: Want)**.| 428 429**Return value** 430 431| **Type** | **Description** | 432| -------------------------------------------------------------- | ----------------------------------------------------------------------------- | 433| [MifareUltralightTag](js-apis-nfctech.md#mifareultralighttag9) | **MifareUltralightTag** object obtained.| 434 435**Error codes** 436 437For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md). 438 439| ID| Error Message | 440| -------- | ----------------------------------------- | 441| 3100201 | Tag running state is abnormal in service. | 442 443## tag.getNdefFormatable<sup>9+</sup> 444 445getNdefFormatable(tagInfo: [TagInfo](#taginfo)): [NdefFormatableTag](js-apis-nfctech.md#ndefformatabletag9) 446 447Obtains an **NdefFormatableTag** object, which allows access to the tags that are NDEF formattable. 448 449**System capability**: SystemCapability.Communication.NFC.Tag 450 451**Return value** 452 453| **Type** | **Description** | 454| --------------------------------------------------------- | ------------------------------------------------------------------------- | 455| [NdefFormatableTag](js-apis-nfctech.md#ndefformatabletag) | **NdefFormatableTag** object obtained.| 456 457**Error codes** 458 459For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md). 460 461| ID| Error Message | 462| -------- | ----------------------------------------- | 463| 3100201 | Tag running state is abnormal in service. | 464 465## tag.getTagInfo<sup>9+</sup> 466 467getTagInfo(want: [Want](js-apis-app-ability-want.md#Want)): [TagInfo](#taginfo) 468 469Obtains **TagInfo** from **Want**, which is initialized by the NFC service and contains the attributes required by **TagInfo**. 470 471**System capability**: SystemCapability.Communication.NFC.Tag 472 473**Parameters** 474 475| Name| Type | Mandatory| Description | 476| ------ | ---------------------------------------- | ---- | --------------------------------------------------- | 477| want | [Want](js-apis-app-ability-want.md#Want) | Yes | Data obtained from the parameters of the **onCreate** entry function when an ability is dispatched.| 478 479**Return value** 480 481| **Type** | **Description** | 482| ------------------- | -------------------------------------------- | 483| [TagInfo](#taginfo) | **TagInfo** object obtained.| 484 485## tag.registerForegroundDispatch<sup>10+</sup> 486 487registerForegroundDispatch(elementName: [ElementName](js-apis-bundleManager-elementName.md), discTech: number[], callback: AsyncCallback<[TagInfo](#taginfo)>): void 488 489Registers 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](#taginfo) read in a callback. <br>This API must be used with [tag.unregisterForegroundDispatch](#tagunregisterforegrounddispatch10) in pairs. The registered event listening must be unregistered before the page exits the foreground or the page is destroyed. 490 491**Required permissions**: ohos.permission.NFC_TAG 492 493**System capability**: SystemCapability.Communication.NFC.Tag 494 495**Parameters** 496 497| Name | Type | Mandatory| Description | 498| ------------ | -------- | ---- | ------------------------------------------------------- | 499| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes | Information about the application page, which must contain at least the bundle name and ability name. | 500| discTech | number[] | Yes | Technologies supported by the foreground dispatch system. Each number indicates the constant value of the supported technology. Based on the value of **number**, the system sets tag technologies ([NFC_A](#technology-type-definition), [NFC_B](#technology-type-definition), and [NFC_F](#technology-type-definition), and [NFC_V](#technology-type-definition)) for NFC card read polling and disable card emulation. If the **number** length is 0, both card read polling and card emulation will be disabled.| 501| callback | AsyncCallback<[TagInfo](#taginfo)> | Yes | Callback invoked to return the card read event in the foreground.| 502 503**Example** 504 505See the example of [tag.unregisterForegroundDispatch](#tagunregisterforegrounddispatch10). 506 507## tag.unregisterForegroundDispatch<sup>10+</sup> 508 509unregisterForegroundDispatch(elementName: [ElementName](js-apis-bundleManager-elementName.md)): void 510 511Unregisters 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. 512 513**Required permissions**: ohos.permission.NFC_TAG 514 515**System capability**: SystemCapability.Communication.NFC.Tag 516 517**Parameters** 518 519| Name | Type | Mandatory| Description | 520| ------------ | -------- | ---- | ------------------------------------------------------- | 521| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes | Information about the application page, which must contain at least the bundle name and ability name. | 522 523**Example** 524 525```js 526import Want from '@ohos.app.ability.Want'; 527import UIAbility from '@ohos.app.ability.UIAbility'; 528import tag from '@ohos.nfc.tag'; 529import { BusinessError } from '@ohos.base'; 530import bundleManager from '@ohos.bundle.bundleManager'; 531import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 532 533let discTech : number[] = [tag.NFC_A, tag.NFC_B]; // replace with the tech(s) that is needed by foreground ability 534let elementName : bundleManager.ElementName; 535function foregroundCb(err : BusinessError, tagInfo : tag.TagInfo) { 536 if (err as BusinessError) { 537 if (!err) { 538 console.log("foreground callback: tag found tagInfo = ", JSON.stringify(tagInfo)); 539 } else { 540 console.log("foreground callback err: " + (err as BusinessError).message); 541 return; 542 } 543 } 544 // Other operations of taginfo. 545} 546 547export default class MainAbility extends UIAbility { 548 OnCreate(want : Want, launchParam : AbilityConstant.LaunchParam) { 549 console.log("OnCreate"); 550 elementName = { 551 bundleName: want.bundleName as string, 552 abilityName: want.abilityName as string, 553 moduleName: want.moduleName as string 554 } 555 } 556 557 onForeground() { 558 console.log("onForeground"); 559 try { 560 tag.registerForegroundDispatch(elementName, discTech, foregroundCb); 561 } catch (e) { 562 console.error("registerForegroundDispatch error: " + (e as BusinessError).message); 563 } 564 } 565 566 onBackground() { 567 console.log("onBackground"); 568 try { 569 tag.unregisterForegroundDispatch(elementName); 570 } catch (e) { 571 console.error("registerForegroundDispatch error: " + (e as BusinessError).message); 572 } 573 } 574 575 onWindowStageDestroy() { 576 console.log("onWindowStageDestroy"); 577 try { 578 tag.unregisterForegroundDispatch(elementName); 579 } catch (e) { 580 console.error("registerForegroundDispatch error: " + (e as BusinessError).message); 581 } 582 } 583 584 // Override other lifecycle functions. 585} 586``` 587 588## tag.on<sup>11+</sup> 589 590on(type: 'readerMode', elementName: [ElementName](js-apis-bundleManager-elementName.md), discTech: number[], callback: AsyncCallback<[TagInfo](#taginfo)>): void 591 592Sets the NFC card reader mode and subscribes to card reading events when the application page is in the foreground. The **discTech** parameter specifies the supported tag technology types, and the callback returns the [TagInfo](#taginfo) obtained. This API must be used with [tag.off](#tagoff11) in pairs. If the NFC card reader mode is set by [tag.on](#tagon11), you must use call **tag.off** to exit the mode when the application page exits the foreground or the page is destroyed. 593 594**Required permissions**: ohos.permission.NFC_TAG 595 596**System capability**: SystemCapability.Communication.NFC.Tag 597 598**Parameters** 599 600| Name | Type | Mandatory| Description | 601| ------------ | -------- | ---- | ------------------------------------------------------- | 602| type | string | Yes | Type of the callback to register.| 603| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes | Element name of the application, which must contain at least the bundle name and ability name. | 604| discTech | number[] | Yes | Technologies supported by the card reader mode. Each number indicates the constant value of the supported technology. Based on the value of **number**, the system sets tag technologies ([NFC_A](#technology-type-definition), [NFC_B](#technology-type-definition), and [NFC_F](#technology-type-definition), and [NFC_V](#technology-type-definition)) for NFC card read polling and disable card emulation. If the **number** length is 0, both card read polling and card emulation will be disabled.| 605| callback | AsyncCallback<[TagInfo](#taginfo)> | Yes | Callback used to listen for the card reader mode, which returns the tag information read.| 606 607**Error codes** 608 609For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md). 610 611| ID| Error Message | 612| -------- | ----------------------------------------- | 613| 3100202 | Invalid element status.| 614 615**Example** 616 617See the example of [tag.off](#tagoff11). 618 619## tag.off<sup>11+</sup> 620 621off(type: 'readerMode', elementName: [ElementName](js-apis-bundleManager-elementName.md), callback?: AsyncCallback<[TagInfo](#taginfo)>): void 622 623Exits the NFC card reader mode and unsubscribes from the card reading events. If the NFC card reader mode is set by [tag.on](#tagon11), you must use this API to exit the mode when the application page exits the foreground or the page is destroyed. 624 625**Required permissions**: ohos.permission.NFC_TAG 626 627**System capability**: SystemCapability.Communication.NFC.Tag 628 629**Parameters** 630 631| Name | Type | Mandatory| Description | 632| ------------ | -------- | ---- | ------------------------------------------------------- | 633| type | string | Yes | Type of the callback to unregister.| 634| elementName | [ElementName](js-apis-bundleManager-elementName.md) | Yes | Element name of the application, which must contain at least the bundle name and ability name. | 635| callback | AsyncCallback<[TagInfo](#taginfo)> | No | Callback for listening for the card reading in the foreground.| 636 637**Error codes** 638 639For details about the error codes, see [NFC Error Codes](../errorcodes/errorcode-nfc.md). 640 641| ID| Error Message | 642| -------- | ----------------------------------------- | 643| 3100203 | off() must be used with on() in pairs.| 644 645**Example** 646 647```js 648import Want from '@ohos.app.ability.Want'; 649import UIAbility from '@ohos.app.ability.UIAbility'; 650import tag from '@ohos.nfc.tag'; 651import { BusinessError } from '@ohos.base'; 652import bundleManager from '@ohos.bundle.bundleManager'; 653import AbilityConstant from '@ohos.app.ability.AbilityConstant'; 654 655let discTech : number[] = [tag.NFC_A, tag.NFC_B]; // replace with the tech(s) that is needed by foreground ability 656let elementName : bundleManager.ElementName; 657 658function readerModeCb(err : BusinessError, tagInfo : tag.TagInfo) { 659 if (err as BusinessError) { 660 if (!err) { 661 console.log("offCallback: tag found tagInfo = ", JSON.stringify(tagInfo)); 662 } else { 663 console.error("offCallback err: " + (err as BusinessError).message); 664 return; 665 } 666 } 667 // other Operations of taginfo 668} 669 670export default class MainAbility extends UIAbility { 671 OnCreate(want : Want, launchParam : AbilityConstant.LaunchParam) { 672 console.log("OnCreate"); 673 elementName = { 674 bundleName: want.bundleName as string, 675 abilityName: want.abilityName as string, 676 moduleName: want.moduleName as string 677 } 678 } 679 680 onForeground() { 681 console.log("on start"); 682 try { 683 tag.on('readerMode', elementName, discTech, readerModeCb); 684 } catch (e) { 685 console.error("tag.on error: " + (e as BusinessError).message); 686 } 687 } 688 689 onBackground() { 690 console.log("onBackground"); 691 try { 692 tag.off('readerMode', elementName, readerModeCb); 693 } catch (e) { 694 console.error("tag.off error: " + (e as BusinessError).message); 695 } 696 } 697 698 onWindowStageDestroy() { 699 console.log("onWindowStageDestroy"); 700 try { 701 tag.off('readerMode', elementName, readerModeCb); 702 } catch (e) { 703 console.error("tag.off error: " + (e as BusinessError).message); 704 } 705 } 706 707 // override other lifecycle functions 708} 709``` 710 711## tag.ndef.makeUriRecord<sup>9+</sup> 712 713makeUriRecord(uri: string): [NdefRecord](#ndefrecord9) 714 715Creates an NDEF record based on the specified URI. 716 717**System capability**: SystemCapability.Communication.NFC.Tag 718 719**Parameters** 720 721| Name| Type | Mandatory| Description | 722| ------ | ------ | ---- | --------------------------------- | 723| uri | string | Yes | Data to write to the NDEF record.| 724 725**Return value** 726 727| **Type** | **Description** | 728| -------------------------- | ------------------------------------------------------------ | 729| [NdefRecord](#ndefrecord9) | NDEF record created. For details, see *NFCForum-TS-NDEF_1.0*.| 730 731**Example** 732 733```js 734import tag from '@ohos.nfc.tag'; 735 736try { 737 let uri = "https://gitee.com/openharmony"; // change it to be correct. 738 let ndefRecord = tag.ndef.makeUriRecord(uri); 739 if (ndefRecord != undefined) { 740 console.log("ndefMessage makeUriRecord rtdType: " + ndefRecord.rtdType); 741 console.log("ndefMessage makeUriRecord payload: " + ndefRecord.payload); 742 } else { 743 console.log("ndefMessage makeUriRecord ndefRecord: " + ndefRecord); 744 } 745} catch (busiError) { 746 console.error("ndefMessage makeUriRecord catched busiError: " + busiError); 747} 748``` 749 750## tag.ndef.makeTextRecord<sup>9+</sup> 751 752makeTextRecord(text: string, locale: string): [NdefRecord](#ndefrecord9) 753 754Creates an NDEF record based on the specified text data and encoding type. 755 756**System capability**: SystemCapability.Communication.NFC.Tag 757 758**Parameters** 759 760| Name| Type | Mandatory| Description | 761| ------ | ------ | ---- | ------------------------------------- | 762| text | string | Yes | Text to write to the NDEF record.| 763| locale | string | Yes | Encoding mode of the text. | 764 765**Return value** 766 767| **Type** | **Description** | 768| -------------------------- | ------------------------------------------------------------ | 769| [NdefRecord](#ndefrecord9) | NDEF record created. For details, see *NFCForum-TS-NDEF_1.0*.| 770 771**Example** 772 773```js 774import tag from '@ohos.nfc.tag'; 775 776try { 777 let text = "Hello World"; // change it to be correct. 778 let locale = "en"; // change it to be correct. 779 let ndefRecord = tag.ndef.makeTextRecord(text, locale); 780 if (ndefRecord != undefined) { 781 console.log("ndefMessage makeTextRecord rtdType: " + ndefRecord.rtdType); 782 console.log("ndefMessage makeTextRecord payload: " + ndefRecord.payload); 783 } else { 784 console.log("ndefMessage makeTextRecord ndefRecord: " + ndefRecord); 785 } 786} catch (busiError) { 787 console.error("ndefMessage makeTextRecord catched busiError: " + busiError); 788} 789``` 790 791 792## tag.ndef.makeMimeRecord<sup>9+</sup> 793 794makeMimeRecord(mimeType: string, mimeData: number[]): [NdefRecord](#ndefrecord9) 795 796Creates an NDEF record based on the specified MIME data and type. 797 798**System capability**: SystemCapability.Communication.NFC.Tag 799 800**Parameters** 801 802| Name | Type | Mandatory| Description | 803| -------- | -------- | ---- | ------------------------------------------------------- | 804| mimeType | string | Yes | MIME type that complies with RFC rules, for example, **text/plain** or **image/jpeg**.| 805| mimeData | number[] | Yes | MIME data, which consists of hexadecimal numbers ranging from **0x00** to **0xFF**.| 806 807**Return value** 808 809| **Type** | **Description** | 810| -------------------------- | ------------------------------------------------------------ | 811| [NdefRecord](#ndefrecord9) | NDEF record created. For details, see *NFCForum-TS-NDEF_1.0*.| 812 813**Example** 814 815```js 816import tag from '@ohos.nfc.tag'; 817 818try { 819 let mimeType = "text/plain"; // change it to be correct. 820 let mimeData = [0x01, 0x02, 0x03, 0x04]; // change it to be correct. 821 let ndefRecord = tag.ndef.makeMimeRecord(mimeType, mimeData); 822 if (ndefRecord != undefined) { 823 console.log("ndefMessage makeMimeRecord rtdType: " + ndefRecord.rtdType); 824 console.log("ndefMessage makeMimeRecord payload: " + ndefRecord.payload); 825 } else { 826 console.log("ndefMessage makeMimeRecord ndefRecord: " + ndefRecord); 827 } 828} catch (busiError) { 829 console.error("ndefMessage makeMimeRecord catched busiError: " + busiError); 830} 831``` 832## tag.ndef.makeExternalRecord<sup>9+</sup> 833 834makeExternalRecord(domainName: string, type: string, externalData: number[]): [NdefRecord](#ndefrecord9) 835 836Creates an NDEF record based on application-specific data. 837 838**System capability**: SystemCapability.Communication.NFC.Tag 839 840**Parameters** 841 842| Name | Type | Mandatory| Description | 843| ------------ | -------- | ---- | ------------------------------------------------------- | 844| domainName | string | Yes | Bundle name of the application or domain name of the organization that releases the applications. | 845| type | string | Yes | Type of the application data. | 846| externalData | number[] | Yes | Application data, which consists of hexadecimal numbers ranging from **0x00** to **0xFF**.| 847 848**Return value** 849 850| **Type** | **Description** | 851| -------------------------- | ------------------------------------------------------------ | 852| [NdefRecord](#ndefrecord9) | NDEF record created. For details, see *NFCForum-TS-NDEF_1.0*.| 853 854**Example** 855 856```js 857import tag from '@ohos.nfc.tag'; 858 859try { 860 let domainName = "ohos.nfc.application"; // change it to be correct. 861 let type = "test"; // change it to be correct. 862 let externalData = [0x01, 0x02, 0x03, 0x04]; // change it to be correct. 863 let ndefRecord = tag.ndef.makeExternalRecord(domainName, type, externalData); 864 if (ndefRecord != undefined) { 865 console.log("ndefMessage makeExternalRecord rtdType: " + ndefRecord.rtdType); 866 console.log("ndefMessage makeExternalRecord payload: " + ndefRecord.payload); 867 } else { 868 console.log("ndefMessage makeExternalRecord ndefRecord: " + ndefRecord); 869 } 870} catch (busiError) { 871 console.error("ndefMessage makeExternalRecord catched busiError: " + busiError); 872} 873``` 874 875## tag.ndef.messageToBytes<sup>9+</sup> 876 877messageToBytes(ndefMessage: [NdefMessage](js-apis-nfctech.md#ndefmessage9)): number[] 878 879Converts an NDEF message to bytes. 880 881**System capability**: SystemCapability.Communication.NFC.Tag 882 883**Parameters** 884 885| Name | Type | Mandatory| Description | 886| ----------- | ---------------------------------------------- | ---- | ------------------ | 887| ndefMessage | [NdefMessage](js-apis-nfctech.md#ndefmessage9) | Yes | NDEF message to convert.| 888 889**Return value** 890 891| **Type**| **Description** | 892| -------- | ------------------------------------------------------------------------------------- | 893| number[] | NDEF message in bytes, which consists of hexadecimal numbers ranging from **0x00** to **0xFF**.| 894 895**Example** 896 897```js 898import tag from '@ohos.nfc.tag'; 899 900let rawData = [0xD1, 0x01, 0x03, 0x54, 0x4E, 0x46, 0x43]; // MUST can be parsed as NDEF Record. 901try { 902 let ndefMessage = tag.ndef.createNdefMessage(rawData); 903 console.log("ndef createNdefMessage, ndefMessage: " + ndefMessage); 904 let rawData2 = tag.ndef.messageToBytes(ndefMessage); 905 console.log("ndefMessage messageToBytes rawData2: " + rawData2); 906} catch (busiError) { 907 console.error("ndef createNdefMessage busiError: " + busiError); 908} 909``` 910## tag.ndef.createNdefMessage<sup>9+</sup> 911 912createNdefMessage(data: number[]): [NdefMessage](js-apis-nfctech.md#ndefmessage9) 913 914Creates 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. 915 916**System capability**: SystemCapability.Communication.NFC.Tag 917 918**Parameters** 919 920| **Name**| **Type**| **Mandatory**| **Description** | 921| ---------- | -------- | -------- | ---------------------------------------------------------------------------------- | 922| data | number[] | Yes | Raw byte data, which consists of hexadecimal numbers ranging from **0x00** to **0xFF**. The data must comply with the NDEF record format.| 923 924**Return value** 925 926| **Type** | **Description** | 927| ---------------------------------------------- | ------------------------------------------------------------- | 928| [NdefMessage](js-apis-nfctech.md#ndefmessage9) | NDEF message created. For details, see *NFCForum-TS-NDEF_1.0*.| 929 930**Example** 931```js 932import tag from '@ohos.nfc.tag'; 933 934let rawData = [0xD1, 0x01, 0x03, 0x54, 0x4E, 0x46, 0x43]; // MUST can be parsed as NDEF Record. 935try { 936 let ndefMessage = tag.ndef.createNdefMessage(rawData); 937 console.log("ndef createNdefMessage, ndefMessage: " + ndefMessage); 938} catch (busiError) { 939 console.error("ndef createNdefMessage busiError: " + busiError); 940} 941``` 942 943## tag.ndef.createNdefMessage<sup>9+</sup> 944 945createNdefMessage(ndefRecords: NdefRecord[]): [NdefMessage](js-apis-nfctech.md#ndefmessage9) 946 947Creates an NDEF message from the NDEF records list. 948 949**System capability**: SystemCapability.Communication.NFC.Tag 950 951**Parameters** 952 953| **Name** | **Type** | **Mandatory**| **Description** | 954| ----------- | --------------------------------------------- | -------- | ---------------------------------------------------------------- | 955| ndefRecords | [NdefRecord](js-apis-nfcTag.md#ndefrecord9)[] | Yes | NDEF record list used to create the NDEF message. For details, see *NFCForum-TS-NDEF_1.0*.| 956 957**Return value** 958 959| **Type** | **Description** | 960| ---------------------------------------------- | ------------------------------------------------------------- | 961| [NdefMessage](js-apis-nfctech.md#ndefmessage9) | NDEF message created. For details, see *NFCForum-TS-NDEF_1.0*.| 962 963**Example** 964 965```js 966import tag from '@ohos.nfc.tag'; 967 968let uriRecord = tag.ndef.makeUriRecord("https://gitee.com/openharmony"); 969let textRecord = tag.ndef.makeTextRecord("Hello World", "en"); 970let ndefRecords = [uriRecord, textRecord]; 971try { 972 let ndefMessage = tag.ndef.createNdefMessage(ndefRecords); 973 console.log("ndef createNdefMessage ndefMessage: " + ndefMessage); 974} catch (busiError) { 975 console.error("ndef createNdefMessage busiError: " + busiError); 976} 977``` 978 979## TagInfo 980 981Defines the **TagInfo** object, which provides information about the tag technologies supported by a card. 982 983**System capability**: SystemCapability.Communication.NFC.Tag 984 985**Required permissions**: ohos.permission.NFC_TAG 986 987| **Name** | **Type** | **Readable**| **Writable**| **Description** | 988| ----------------------------- | ------------------------------------------------------------- | -------- | -------- | -------------------------------------------------------------------------------------------- | 989| uid<sup>9+</sup> | number[] | Yes | No | Tag unique identifier (UID), which consists of hexadecimal numbers ranging from **0x00** to **0xFF**. | 990| technology<sup>9+</sup> | number[] | Yes | No | Supported tag technologies. Each number is a constant indicating the supported technology. | 991| supportedProfiles | number[] | Yes | No | Supported profiles. This parameter is not supported since API version 9. Use [tag.TagInfo#technology](#taginfo) instead. | 992| extrasData<sup>9+</sup> | [PacMap](js-apis-inner-ability-dataAbilityHelper.md#pacmap)[] | Yes | No | Extended attribute value of the tag technology.<br>**System API**: This is a system API. | 993| tagRfDiscId<sup>9+</sup> | number | Yes | No | ID allocated when the tag is discovered.<br>**System API**: This is a system API. | 994| remoteTagService<sup>9+</sup> | [rpc.RemoteObject](js-apis-rpc.md#remoteobject) | Yes | No | Remote object of the NFC service process used for interface communication between the client and the service.<br>**System API**: This is a system API.| 995## NdefRecord<sup>9+</sup> 996Defines an NDEF record. For details, see *NFCForum-TS-NDEF_1.0*. 997 998**System capability**: SystemCapability.Communication.NFC.Tag 999 1000| **Name**| **Type**| **Readable**| **Writable**| **Description** | 1001| -------- | -------- | -------- | -------- | ----------------------------------------------------------------------------------------- | 1002| tnf | number | Yes | No | Type name field (TNF) of the NDEF record. | 1003| rtdType | number[] | Yes | No | Record type definition (RTD) of the NDEF record. It consists of hexadecimal numbers ranging from **0x00** to **0xFF**.| 1004| id | number[] | Yes | No | NDEF record ID, which consists of hexadecimal numbers ranging from **0x00** to **0xFF**. | 1005| payload | number[] | Yes | No | NDEF payload, which consists of hexadecimal numbers ranging from **0x00** to **0xFF**. | 1006 1007## Technology Type Definition 1008Enumerates the tag technology types. 1009 1010**System capability**: SystemCapability.Communication.NFC.Tag 1011 1012| **Name** | **Value**| **Description** | 1013| ---------------------------- | ------ | --------------------------- | 1014| NFC_A | 1 | NFC-A (ISO 14443-3A). | 1015| NFC_B | 2 | NFC-B (ISO 14443-3B). | 1016| ISO_DEP | 3 | ISO-DEP (ISO 14443-4).| 1017| NFC_F | 4 | NFC-F (JIS 6319-4). | 1018| NFC_V | 5 | NFC-V (ISO 15693). | 1019| NDEF | 6 | NDEF. | 1020| NDEF_FORMATABLE<sup>9+</sup> | 7 | NDEF formattable. | 1021| MIFARE_CLASSIC | 8 | MIFARE Classic. | 1022| MIFARE_ULTRALIGHT | 9 | MIFARE Ultralight. | 1023 1024## TnfType<sup>9+</sup> 1025Enumerates the TNF types. For details, see *NFCForum-TS-NDEF_1.0*. 1026 1027**System capability**: SystemCapability.Communication.NFC.Tag 1028 1029| **Name** | **Value**| **Description** | 1030| ---------------- | ------ | ------------------------------------------------ | 1031| TNF_EMPTY | 0x0 | Empty. | 1032| TNF_WELL_KNOWN | 0x1 | NFC Forum Well Known Type [NFC RTD]. | 1033| TNF_MEDIA | 0x2 | Media-type as defined in RFC 2046 [RFC 2046]. | 1034| TNF_ABSOLUTE_URI | 0x3 | Absolute URI as defined in RFC 3986 [RFC 3986].| 1035| TNF_EXT_APP | 0x4 | NFC Forum external type [NFC RTD]. | 1036| TNF_UNKNOWN | 0x5 | Unknown. | 1037| TNF_UNCHANGED | 0x6 | Unchanged (see section 2.3.3 in *NFCForum-TS-NDEF_1.0*). | 1038 1039## NDEF Record RTD 1040Enumerates the NDEF record types. For details about the RTD, see *NFCForum-TS-NDEF_1.0*. 1041 1042**System capability**: SystemCapability.Communication.NFC.Tag 1043 1044| **Name** | **Value**| **Description** | 1045| --------------------- | ------ | ----------------------- | 1046| RTD_TEXT<sup>9+</sup> | [0x54] | NDEF record of the text type.| 1047| RTD_URI<sup>9+</sup> | [0x55] | NDEF record of the URI type. | 1048 1049## NfcForumType<sup>9+</sup> 1050Enumerates the NFC Forum tag types. 1051 1052**System capability**: SystemCapability.Communication.NFC.Tag 1053 1054| **Name** | **Value**| **Description** | 1055| ---------------- | ------ | -------------------- | 1056| NFC_FORUM_TYPE_1 | 1 | NFC Forum tag type 1. | 1057| NFC_FORUM_TYPE_2 | 2 | NFC Forum tag type 2. | 1058| NFC_FORUM_TYPE_3 | 3 | NFC Forum tag type 3. | 1059| NFC_FORUM_TYPE_4 | 4 | NFC Forum tag type 4. | 1060| MIFARE_CLASSIC | 101 | MIFARE Classic.| 1061 1062## MifareClassicType<sup>9+</sup> 1063Enumerates the MIFARE Classic tag types. 1064 1065**System capability**: SystemCapability.Communication.NFC.Tag 1066 1067| **Name** | **Value**| **Description** | 1068| ------------ | ------ | -------------------- | 1069| TYPE_UNKNOWN | 0 | Unknown type. | 1070| TYPE_CLASSIC | 1 | MIFARE Classic.| 1071| TYPE_PLUS | 2 | MIFARE Plus. | 1072| TYPE_PRO | 3 | MIFARE Pro. | 1073 1074## MifareClassicSize<sup>9+</sup> 1075Enumerates the sizes of a MIFARE Classic tag. 1076 1077**System capability**: SystemCapability.Communication.NFC.Tag 1078 1079| **Name** | **Value**| **Description** | 1080| ------------ | ------ | --------------------------------- | 1081| MC_SIZE_MINI | 320 | Each tag has 5 sectors, and each sector has 4 blocks. | 1082| MC_SIZE_1K | 1024 | Each tag has 16 sectors, and each sector has 4 blocks.| 1083| MC_SIZE_2K | 2048 | Each tag has 32 sectors, and each sector has 4 blocks.| 1084| MC_SIZE_4K | 4096 | Each tag has 40 sectors, and each sector has 4 blocks.| 1085 1086## MifareUltralightType<sup>9+</sup> 1087Enumerates the MIFARE Ultralight tag types. 1088 1089**System capability**: SystemCapability.Communication.NFC.Tag 1090 1091| **Name** | **Value**| **Description** | 1092| ----------------- | ------ | ------------------------- | 1093| TYPE_UNKNOWN | 0 | Unknown type. | 1094| TYPE_ULTRALIGHT | 1 | MIFARE Ultralight. | 1095| TYPE_ULTRALIGHT_C | 2 | MIFARE Ultralight C.| 1096 1097 <!--no_check-->