1# @ohos.connectedTag (有源标签) 2 3本模块提供有源标签的使用，包括初始化有源标签芯片、读取有源标签内容、写入内容到有源标签等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```js 12import { connectedTag } from '@kit.ConnectivityKit'; 13``` 14 15## connectedTag.init<sup>(deprecated)</sup> 16 17init(): boolean 18 19初始化有源标签芯片。 20 21> **说明：** 22> 23> 从API version 8开始支持，从API version 9开始废弃，建议使用[initialize](#connectedtaginitialize9)替代。 24 25**需要权限**：ohos.permission.NFC_TAG 26 27**系统能力**：SystemCapability.Communication.ConnectedTag 28 29**返回值：** 30 31| **类型** | **说明** | 32| -------- | -------- | 33| boolean | true：初始化成功。 <br>false：初始化失败。 | 34 35## connectedTag.initialize<sup>9+</sup> 36 37initialize(): void 38 39初始化有源标签芯片。 40 41**需要权限：** ohos.permission.NFC_TAG 42 43**系统能力：** SystemCapability.Communication.ConnectedTag 44 45**错误码：** 46 47以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[NFC错误码](errorcode-nfc.md)。 48 49| 错误码ID | 错误信息| 50| -------- | -------- | 51|201 | Permission denied. | 52|801 | Capability not supported. | 53|3200101 | Connected NFC tag running state is abnormal in service. | 54 55## connectedTag.uninit<sup>(deprecated)</sup> 56 57uninit(): boolean 58 59卸载有源标签芯片资源。 60 61> **说明：** 62> 63> 从API version 8开始支持，从API version 9开始废弃，建议使用[uninitialize](#connectedtaguninitialize9)替代。 64 65**需要权限**：ohos.permission.NFC_TAG 66 67**系统能力**：SystemCapability.Communication.ConnectedTag 68 69**返回值：** 70 71| **类型** | **说明** | 72| -------- | -------- | 73| boolean | true：卸载操作成功。 <br>false：卸载操作失败。 | 74 75## connectedTag.uninitialize<sup>9+</sup> 76 77uninitialize(): void 78 79卸载有源标签芯片资源。 80 81**需要权限:** ohos.permission.NFC_TAG 82 83**系统能力:** SystemCapability.Communication.ConnectedTag 84 85**错误码：** 86 87以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[NFC错误码](errorcode-nfc.md)。 88 89| 错误码ID | 错误信息| 90| -------- | -------- | 91|201 | Permission denied. | 92|801 | Capability not supported. | 93|3200101 | Connected NFC tag running state is abnormal in service. | 94 95## connectedTag.readNdefTag<sup>(deprecated)</sup> 96 97readNdefTag(): Promise<string> 98 99读取有源标签内容，使用promise方式作为异步方法。 100 101> **说明：** 102> 103> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[connectedTag.read](#connectedtagread9)替代。 104 105**需要权限**：ohos.permission.NFC_TAG 106 107**系统能力**：SystemCapability.Communication.ConnectedTag 108 109**返回值：** 110 111| **类型** | **说明** | 112| -------- | -------- | 113| Promise<string> | 返回读取有源标签内容。 | 114 115**示例：** 116 117```js 118import { connectedTag } from '@kit.ConnectivityKit'; 119import { BusinessError } from '@kit.BasicServicesKit'; 120 121connectedTag.readNdefTag().then((data) => { 122 console.log("connectedTag readNdefTag Promise data = " + data); 123}).catch((err: BusinessError)=> { 124 console.error("connectedTag readNdefTag Promise err: " + err); 125}); 126``` 127 128## connectedTag.read<sup>9+</sup> 129 130read(): Promise<number[]> 131 132读取有源标签内容，使用promise方式作为异步方法。 133 134**需要权限：** ohos.permission.NFC_TAG 135 136**系统能力：** SystemCapability.Communication.ConnectedTag 137 138**返回值：** 139 140| **类型** | **说明** | 141| -------- | -------- | 142| Promise<number[]> | 返回读取有源标签内容。 | 143 144**错误码：** 145 146以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[NFC错误码](errorcode-nfc.md)。 147 148| 错误码ID | 错误信息| 149| -------- | -------- | 150|201 | Permission denied. | 151|801 | Capability not supported. | 152|3200101 | Connected NFC tag running state is abnormal in service. | 153 154**示例：** 155 156```js 157import { connectedTag } from '@kit.ConnectivityKit'; 158import { BusinessError } from '@kit.BasicServicesKit'; 159 160connectedTag.read().then((data) => { 161 console.log("connectedTag read Promise data = " + data); 162}).catch((err: BusinessError)=> { 163 console.error("connectedTag read Promise err: " + err); 164}); 165``` 166 167## connectedTag.readNdefTag<sup>(deprecated)</sup> 168 169readNdefTag(callback: AsyncCallback<string>): void 170 171读取有源标签内容，使用AsyncCallback方式作为异步方法。 172 173> **说明：** 174> 175> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[connectedTag.read](#connectedtagread9)替代。 176 177**需要权限**：ohos.permission.NFC_TAG 178 179**系统能力**：SystemCapability.Communication.ConnectedTag 180 181**参数：** 182 183| **参数名** | **类型** | **必填** | **说明** | 184| -------- | -------- | -------- | -------- | 185| callback | AsyncCallback<string> | 是 | 读取有源标签内容回调函数。 | 186 187**示例：** 188 189```js 190import { connectedTag } from '@kit.ConnectivityKit'; 191 192connectedTag.readNdefTag((err, data)=> { 193 if (err) { 194 console.error("connectedTag readNdefTag AsyncCallback err: " + err); 195 } else { 196 console.log("connectedTag readNdefTag AsyncCallback data: " + data); 197 } 198}); 199``` 200 201## connectedTag.read<sup>9+</sup> 202 203read(callback: AsyncCallback<number[]>): void 204 205读取有源标签内容，使用AsyncCallback方式作为异步方法。 206 207**需要权限：** ohos.permission.NFC_TAG 208 209**系统能力：** SystemCapability.Communication.ConnectedTag 210 211**参数：** 212 213| **参数名** | **类型** | **必填** | **说明** | 214| -------- | -------- | -------- | -------- | 215| callback | AsyncCallback<number[]> | 是 | 读取有源标签内容回调函数。 | 216 217**错误码：** 218 219以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[NFC错误码](errorcode-nfc.md)。 220 221| 错误码ID | 错误信息| 222| -------- | -------- | 223|201 | Permission denied. | 224|801 | Capability not supported. | 225|3200101 | Connected NFC tag running state is abnormal in service. | 226 227**示例：** 228 229```js 230import { connectedTag } from '@kit.ConnectivityKit'; 231 232connectedTag.read((err, data)=> { 233 if (err) { 234 console.error("connectedTag read AsyncCallback err: " + err); 235 } else { 236 console.log("connectedTag read AsyncCallback data: " + data); 237 } 238}); 239``` 240 241## connectedTag.writeNdefTag<sup>(deprecated)</sup> 242 243writeNdefTag(data: string): Promise<void> 244 245写入内容到有源标签，使用promise方式作为异步方法。 246 247> **说明：** 248> 249> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[connectedTag.write](#connectedtagwrite9)替代。 250 251**需要权限**：ohos.permission.NFC_TAG 252 253**系统能力**：SystemCapability.Communication.ConnectedTag 254 255**参数：** 256 257| **参数名** | **类型** | **必填** | **说明** | 258| -------- | -------- | -------- | -------- | 259| data | string | 是 | 有源标签内容, 最大长度为1024个字节。 | 260 261**返回值：** 262 263| **类型** | **说明** | 264| -------- | -------- | 265| Promise<void> | 无返回值。 | 266 267**示例：** 268 269```js 270import { connectedTag } from '@kit.ConnectivityKit'; 271import { BusinessError } from '@kit.BasicServicesKit'; 272 273let rawData = "010203"; // change it to be correct. 274connectedTag.writeNdefTag(rawData).then(() => { 275 console.log("connectedTag.writeNdefTag Promise success."); 276}).catch((err: BusinessError)=> { 277 console.error("connectedTag.writeNdefTag Promise err: " + err); 278}); 279``` 280 281## connectedTag.write<sup>9+</sup> 282 283write(data: number[]): Promise<void> 284 285写入内容到有源标签，使用promise方式作为异步方法。 286 287**需要权限：** ohos.permission.NFC_TAG 288 289**系统能力：** SystemCapability.Communication.ConnectedTag 290 291**参数：** 292 293| **参数名** | **类型** | **必填** | **说明** | 294| -------- | -------- | -------- | -------- | 295| data | number[] | 是 | 有源标签内容, 由十六进制数字组成。范围：0x00至0xFF。 | 296 297**返回值：** 298 299| **类型** | **说明** | 300| -------- | -------- | 301| Promise<void> | 无返回值。 | 302 303**错误码：** 304 305以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[NFC错误码](errorcode-nfc.md)。 306 307| 错误码ID | 错误信息| 308| -------- | -------- | 309|201 | Permission denied. | 310|401 | The parameter check failed. Possible causes: <br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameters types.<br>3. Parameter verification failed. | 311|801 | Capability not supported. | 312|3200101 | Connected NFC tag running state is abnormal in service. | 313 314**示例：** 315 316```js 317import { connectedTag } from '@kit.ConnectivityKit'; 318import { BusinessError } from '@kit.BasicServicesKit'; 319 320let rawData = [0x01, 0x02, 0x03]; // change it to be correct. 321connectedTag.write(rawData).then(() => { 322 console.log("connectedTag.writeNdefTag Promise success."); 323}).catch((err: BusinessError)=> { 324 console.error("connectedTag.writeNdefTag Promise err: " + err); 325}); 326``` 327 328## connectedTag.writeNdefTag<sup>(deprecated)</sup> 329 330writeNdefTag(data: string, callback: AsyncCallback<void>): void 331 332写入内容到有源标签，使用AsyncCallback方式作为异步方法。 333 334> **说明：** 335> 336> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[connectedTag.write](#connectedtagwrite9)替代。 337 338**需要权限**：ohos.permission.NFC_TAG 339 340**系统能力**：SystemCapability.Communication.ConnectedTag 341 342**参数：** 343 344| **参数名** | **类型** | **必填** | **说明** | 345| -------- | -------- | -------- | -------- | 346| data | string | 是 | 有源标签内容, 最大长度为1024个字节。 | 347| callback | AsyncCallback<void> | 是 | 读取有源标签内容回调函数。 | 348 349**示例：** 350 351```js 352import { connectedTag } from '@kit.ConnectivityKit'; 353 354let rawData = "010203"; // change it to be correct. 355connectedTag.writeNdefTag(rawData, (err)=> { 356 if (err) { 357 console.error("connectedTag.writeNdefTag AsyncCallback err: " + err); 358 } else { 359 console.log("connectedTag.writeNdefTag AsyncCallback success."); 360 } 361}); 362``` 363 364## connectedTag.write<sup>9+</sup> 365 366write(data: number[], callback: AsyncCallback<void>): void 367 368写入内容到有源标签，使用AsyncCallback方式作为异步方法。 369 370**需要权限：** ohos.permission.NFC_TAG 371 372**系统能力：** SystemCapability.Communication.ConnectedTag 373 374**参数：** 375 376| **参数名** | **类型** | **必填** | **说明** | 377| -------- | -------- | -------- | -------- | 378| data | number[] | 是 | 有源标签内容, 由十六进制数字组成。范围：0x00至0xFF。 | 379| callback | AsyncCallback<void> | 是 | 读取有源标签内容回调函数。 | 380 381**错误码：** 382 383以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[NFC错误码](errorcode-nfc.md)。 384 385| 错误码ID | 错误信息| 386| -------- | -------- | 387|201 | Permission denied. | 388|401 | The parameter check failed. Possible causes: <br>1. Mandatory parameters are left unspecified.<br>2. Incorrect parameters types.<br>3. Parameter verification failed. | 389|801 | Capability not supported. | 390|3200101 | Connected NFC tag running state is abnormal in service. | 391 392**示例：** 393 394```js 395import { connectedTag } from '@kit.ConnectivityKit'; 396 397let rawData = [0x01, 0x02, 0x03]; // change it to be correct. 398connectedTag.write(rawData, (err)=> { 399 if (err) { 400 console.error("connectedTag.writeNdefTag AsyncCallback err: " + err); 401 } else { 402 console.log("connectedTag.writeNdefTag AsyncCallback success."); 403 } 404}); 405``` 406 407## connectedTag.on('notify') 408 409on(type: "notify", callback: Callback<number>): void 410 411注册NFC场强状态事件。 412 413**需要权限**：ohos.permission.NFC_TAG 414 415**系统能力**：SystemCapability.Communication.ConnectedTag 416 417**参数：** 418 419| **参数名** | **类型** | **必填** | **说明** | 420| -------- | -------- | -------- | -------- | 421| type | string | 是 | 固定填"notify"字符串。 | 422| callback | Callback<number> | 是 | 状态改变回调函数，返回值参见[NfcRfType](#nfcrftype)。 | 423 424## connectedTag.off('notify') 425 426off(type: "notify", callback?: Callback<number>): void 427 428取消NFC场强状态事件的注册。 429 430**需要权限**：ohos.permission.NFC_TAG 431 432**系统能力**：SystemCapability.Communication.ConnectedTag 433 434**参数：** 435 436| **参数名** | **类型** | **必填** | **说明** | 437| -------- | -------- | -------- | -------- | 438| type | string | 是 | 固定填"notify"字符串。 | 439| callback | Callback<number> | 否 | 状态改变回调函数。如果callback不填，将“去注册”该事件关联的所有回调函数。| 440 441**示例：** 442 443```js 444import { connectedTag } from '@kit.ConnectivityKit'; 445 446async function nfcTagTest(): Promise<void> { 447 // Register event 448 connectedTag.on("notify", (rfState : number)=> { 449 console.log("connectedTag on Callback rfState: " + rfState); 450 }); 451 try { 452 connectedTag.initialize(); 453 let tag = [3, 1, 0]; 454 console.log("connectedTag write: tag=" + tag); 455 await connectedTag.write(tag); 456 let data = await connectedTag.read(); 457 console.log("connectedTag read: data=" + data); 458 connectedTag.uninitialize(); 459 } catch (error) { 460 console.error("connectedTag error: " + error); 461 } 462 463 // Unregister event 464 connectedTag.off("notify", (rfState : number)=> { 465 console.log("connectedTag off Callback rfState: " + rfState); 466 }); 467} 468 469export { nfcTagTest } 470``` 471 472## NfcRfType 473 474表示NFC场强状态的枚举。 475 476**系统能力**：SystemCapability.Communication.ConnectedTag 477 478| 名称 | 值 | 说明 | 479| -------- | -------- | -------- | 480| NFC_RF_LEAVE | 0 | NFC离场事件。 | 481| NFC_RF_ENTER | 1 | NFC进场事件。 | 482