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