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