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