Cordova NFC插件中文说明V1.0

喜欢ヅ旅行 2024-05-25 17:37 156阅读 0赞

## PhoneGap NFC插件 ##

本插件地址：[https://github.com/chariotsolutions/phonegap-nfc][https_github.com_chariotsolutions_phonegap-nfc]

翻译：hunkxia

本插件可允许您读取和写入NFC标签。你也可以向其他支持NFC的设备发送信息，并从它们接收信息。

可以用来

*  从NFC标签读取数据
 *  写入数据到NFC标签
 *  发送数据到其他NFC启用设备
 *  从NFC设备接收数据
 *  发送原始命令(ISO 14443-3A, ISO 14443-3A, ISO 14443-4, JIS 6319-4, ISO 15693)到NFC标签

这个插件使用NDEF (NFC数据交换格式)来适配NFC设备、标签类型和操作系统之间的最大兼容性。

### 可支持平台 ###

*  Android
 *  iOS 11
 *  Windows (includes Windows Phone 8.1, Windows 8.1, Windows 10)
 *  BlackBerry 10
 *  Windows Phone 8
 *  BlackBerry 7

### 内容 ###

*  安装
 *  NFC部分
 *  NDEF部分
    
     *  Ndef消息
     *  Ndef记录
 *  事件
 *  平台差异
 *  BlackBerry 10调用
 *  扫描标签启动应用
 *  测试
 *  示例项目
 *  HCE(基于主机的卡模拟)
 *  相关书籍
 *  许可证

## 安装 ##

#### Cordova ####

$ cordova plugin add phonegap-nfc

#### PhoneGap ####

$ phonegap plugin add phonegap-nfc

#### PhoneGap Build ####

编辑config.xml安装\[PhoneGap Build\]插件(http://build.phonegap.com)。

Windows Phone 8.1应该使用 **Windows** 平台。基于Silverlight的Windows Phone 8代码已不再维护。

BlackBerry7只支持Cordova 2.x。针对BlackBerry7的应用程序，你可能需要使用旧版本的phonegap-nfc。

具体可通过查看：[开始使用插件][Link 1] 和 [BlackBerry 10入门][BlackBerry 10] 来了解更多相关知识。

### iOS注意事项 ###

从iOS 11开始，iPhone 7(及之后版本)支持读取NFC NDEF标签。iOS 13增加了将NDEF消息写入NFC标签的功能。iOS 13还增加了从一些NFC标签获取UID的功能。在iOS上，用户必须手动启动NFC会话来扫描标签。这与Android不同，Android可以不断扫描NFC标签。可通过函数 nfc.scanndef 和 nfc.scantag 来启动NFC扫描会话。而NFC标签通过Promise方式返回结果。如果你现有代码含有已弃用函数 nfc.beginSession，请使用新的函数 `nfc.scanNdef` 。

`scandef` 函数使用iOS原生类 [NFCNDEFReaderSession][] 来获取NFC数据交换格式(NDEF)标签数据。而 `scanTag` 使用iOS 13中更新的 [NFCTagReaderSession][] 来检测ISO15693、FeliCa和MIFARE标签。`scanTag` 函数将包括一些NFC标签的标签UID、标签类型、以及NDEF消息数据。`scanTag` 也可以读取一些没有NDEF信息的RFID标签。`scanTag` 不会扫描一些NDEF标签，包括Topaz和Mifare Classic。

你必须在每次扫描之前需调用 nfc.scanNdef 和 nfc.scanTag 函数。

在iOS上编辑NFC标签同样使用 nfc.write 函数。虽然方法是一样的，但在iOS上的流程不完全一致。调用此方法后，iOS设备将启动一个新的扫描会话，并将数据写入被扫描的标签之中。

## NFC部分 ##

> nfc对象提供对设备nfc传感器的访问。

### 方法列表 ###

*  nfc.addNdefListener
 *  nfc.addTagDiscoveredListener
 *  nfc.addMimeTypeListener
 *  nfc.addNdefFormatableListener
 *  nfc.write
 *  nfc.makeReadOnly
 *  nfc.share
 *  nfc.unshare
 *  nfc.erase
 *  nfc.handover
 *  nfc.stopHandover
 *  nfc.enabled
 *  nfc.showSettings
 *  nfc.beginSession
 *  nfc.invalidateSession
 *  nfc.scanNdef
 *  nfc.scanTag
 *  nfc.cancelScan

平台支持函数列表

<table> 
 <thead> 
  <tr> 
   <th>方法</th> 
   <th>Adnroid</th> 
   <th>iOS</th> 
   <th>Windows</th> 
   <th>BlackBerry 7</th> 
   <th>BlackBerry 10</th> 
   <th>Windows Phone 8</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>addNdefListener</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>支持</td> 
  </tr> 
  <tr> 
   <td>addTagDiscoveredListener</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>addMimeTypeListener</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>addNdefFormatableListener</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>write</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>支持</td> 
  </tr> 
  <tr> 
   <td>makeReadOnly</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>share</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>支持</td> 
  </tr> 
  <tr> 
   <td>unshare</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>erase</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>handover</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>stopHandover</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>enabled</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>showSettings</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>支持</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>beginSession</td> 
   <td>-</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>invalidateSession</td> 
   <td>-</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>scanNdef</td> 
   <td>-</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>scanTag</td> 
   <td>-</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
  <tr> 
   <td>cancelScan</td> 
   <td>-</td> 
   <td>支持</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
   <td>-</td> 
  </tr> 
 </tbody> 
</table>

### 只读模式 ###

*  nfc.readerMode
 *  nfc.disableReaderMode

### 标签技术功能 ###

*  nfc.connect
 *  nfc.transceive
 *  nfc.close
 *  ISO-DEP example

### nfc.addNdefListener ###

注册事件监听NDEF标签。

nfc.addNdefListener(callback, [onSuccess], [onFailure]);

#### 参数说明 ####

*  **callback**: 当读取NDEF标签时调用的回调函数。
 *  **onSuccess**: (可选)添加监听器时调用的回调函数。
 *  **onFailure**: (可选)当发生错误时调用的回调函数。

#### 描述 ####

使用函数 `nfc.addNdefListener` 注册ndef事件回调。

当NDEF标签被读取时，会触发一个ndef事件。

针对BlackBerry 10，你必须配置你的应用程序将读取标签的类型 config.xml调用目标。

在Android上注册的mimetypelistener优先级高于这个更通用的NDEF侦听器。

在iOS上，你必须在扫描标签之前调用beingSession。

#### 支持的平台 ####

*  Android
 *  iOS
 *  Windows
 *  BlackBerry 7
 *  BlackBerry 10
 *  Windows Phone 8

### nfc.removeNdefListener ###

删除之前通过 `nfc.addNdefListener` 添加的事件监听器。

nfc.removeNdefListener(callback, [onSuccess], [onFailure]);

通常，您不需要调用此函数，相反的，你可以考虑在监听事件中忽略这些你不需要的消息。

#### 参数 ####

*  **callback**: 之前回调函数
 *  **onSuccess**: (可选) 当监听器被成功移除时调用的回调函数。
 *  **onFailure**: (可选) 如果在移除过程中出现错误，则调用该回调函数。

#### 支持平台 ####

*  Android
 *  iOS
 *  Windows
 *  BlackBerry 7

### nfc.addTagDiscoveredListener ###

为匹配任何标记类型的标记注册事件侦听器。

nfc.addTagDiscoveredListener(callback, [onSuccess], [onFailure]);

#### 参数 ####

*  **callback**: 当检测到标签时调用的回调函数。
 *  **onSuccess**: (可选) 添加监听器时调用的回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 描述 ####

使用 `nfc.addTagDiscoveredListener` 函数，为标签事件注册回调函数。

当手机检测到任何标签时，就会发生此事件。

#### 支持平台 ####

*  Android
 *  Windows
 *  BlackBerry 7

请注意，Windows phone需要新的NXP PN427芯片组来读取非ndef标签。该标记将被读取，但没有标记元数据也是允许的。

### nfc.removeTagDiscoveredListener ###

删除之前通过 `nfc.addTagDiscoveredListener` 添加的监听事件。

nfc.removeTagDiscoveredListener(callback, [onSuccess], [onFailure]);

通常，您不需要调用此函数，相反的，你可以考虑在监听事件中忽略这些你不需要的消息。

#### 参数 ####

*  **callback**: 之前注册事件
 *  **onSuccess**: (可选) 当监听器被成功移除时调用的回调函数。
 *  **onFailure**: (可选) 如果在移除过程中出现错误，则调用该回调函数。

#### 支持平台 ####

*  Android
 *  Windows
 *  BlackBerry 7

### nfc.addMimeTypeListener ###

为指定了特定MIME类型匹配的NDEF标记注册事件侦听器。

nfc.addMimeTypeListener(mimeType, callback, [onSuccess], [onFailure]);

#### 参数 ####

*  **mimeType**: 消息需要过滤的MIME类型。
 *  **callback**: 当读取匹配MIME类型的NDEF标签时调用的回调函数。
 *  **onSuccess**: (可选) 添加监听器时调用的回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 描述 ####

为ndef-mime事件注册回调监听的 `nfc.addMimeTypeListener` 函数。

A ndef-mime event occurs when a `Ndef.TNF_MIME_MEDIA` tag is read and matches the specified MIME type.

ndef-mime事件通常发生在 `Ndef.TNF_MIME_MEDIA` 标记被读取并匹配指定的MIME类型时。

此函数可以被多次调用，并指定不同的MIME类型。针对所有MIME消息，你应该使用 *同样* 的处理方式。

nfc.addMimeTypeListener("text/json", *onNfc*, success, failure);
        nfc.addMimeTypeListener("text/demo", *onNfc*, success, failure);

在Android平台，MIME类型通常都是小写字母。(查看 [IntentFilter.addDataType()][IntentFilter.addDataType])

#### 支持平台 ####

*  Android
 *  BlackBerry 7

### nfc.removeMimeTypeListener ###

删除通过 `nfc.addMimeTypeListener` 注册的监听事件。

nfc.removeMimeTypeListener(mimeType, callback, [onSuccess], [onFailure]);

通常，您不需要调用此函数，相反的，你可以考虑在监听事件中忽略这些你不需要的消息。

#### 参数 ####

*  **mimeType**: 消息需要过滤的MIME类型。
 *  **callback**: 之前注册事件
 *  **onSuccess**: (可选) 当监听器被成功移除时调用的回调函数。
 *  **onFailure**: (可选) 如果在移除过程中出现错误，则调用该回调函数。

#### 支持平台 ####

*  Android
 *  BlackBerry 7

### nfc.addNdefFormatableListener ###

针对可格式化的NDEF标签，注册监听事件。

nfc.addNdefFormatableListener(callback, [onSuccess], [onFailure]);

#### 参数 ####

*  **callback**: 当可格式化标签被读取时的回调函数。
 *  **onSuccess**: (可选) 添加监听器时调用的回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 描述 ####

通过 `nfc.addNdefFormatableListener` 函数，可以为可格式化的ndef标签注册监听事件。

当读取可以进行NDEF格式化的标记时，就会发生NDEF格式化事件。对于已经被格式化为NDEF的标记，不会触发此操作。ndef-formatable事件将不包含NdefMessage。

#### 支持平台 ####

*  Android

### nfc.write ###

将NDEF消息写入NFC标签中。

一个NDEF消息由一个或多个NDEF记录组成的数组。

var message = [
        ndef.textRecord("hello, world"),
        ndef.uriRecord("http://github.com/chariotsolutions/phonegap-nfc")
    ];
    
    nfc.write(message, [onSuccess], [onFailure]);

#### 参数 ####

*  **ndefMessage**: NDEF记录数组。
 *  **onSuccess**: (可选) 当写标签时调用的回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 描述 ####

通过 `nfc.write` 函数，可以将NDEF函数写入标签。

在 **Android** 上，这个方法必须在NDEF事件处理程序中调用。

在 **iOS** 上，这个方法可以在NDEF事件处理程序之外调用，它将启动一个新的扫描会话。也可以重用读会话来写入数据。参见下面的示例。

在 **Windows** 上，这个方法 *可能* 从NDEF事件处理程序中调用。

在 **Windows Phone 8.1** 上，这个方法应该在NDEF事件处理程序之外调用，否则Windows会在你写标签时尝试读取标签内容。

#### 示例 ####

##### Android #####

在Android平台，写入操作必须在事件处理内调用：

function onNfc(nfcEvent) {
        
    
        console.log(nfcEvent.tag);
        
        var message = [
            ndef.textRecord(new String(new Date()))
        ];
        
        nfc.write(
            message,
            success => console.log('wrote data to tag'),
            error => console.log(error)
        );
    
    nfc.addNdefListener(onNfc);

##### iOS - 简单使用 #####

在iOS平台，需要先创建一个新扫描对话，然后用户靠近一个NFC标签，进行写入数据操作：

var message = [
        ndef.textRecord("Hello, world")
    ];
    
    nfc.write(
        message,
        success => console.log('wrote data to tag'),
        error => console.log(error)
    );

##### iOS - 读和写操作 #####

在iOS平台，你可以选择在读操作会话的时候向NFC标签写入数据。

try {
        
        let tag = await nfc.scanNdef({
         keepSessionOpen: true});
    
        // 你可以在此读取数据
        console.log(tag);
        
        // 这个例子展示写入一个时间戳数据
        var message = [
            ndef.textRecord(new String(new Date()))
        ];
    
        nfc.write(
            message,
            success => console.log('wrote data to tag'),
            error => console.log(error)
        );
    
    } catch (err) {
        
        console.log(err);
    }

#### 支持平台 ####

*  Android
 *  iOS
 *  Windows
 *  BlackBerry 7
 *  Windows Phone 8

### nfc.makeReadOnly ###

设置某个NFC标签为只读。 **特别注意，这个是永久的**

nfc.makeReadOnly([onSuccess], [onFailure]);

#### 参数 ####

*  **onSuccess**: (可选) 当标签被锁定时候的回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 描述 ####

使用函数 `nfc.makeReadOnly` 可以让NFC标签变为只读。 **特别注意这样的操作是永久的**，并且不能再撤回操作。

在 **Android** 系统上，这个方法 *必须* 在NDEF事件操作中执行。

示例用法：

onNfc: function(nfcEvent) {
        
    
        var record = [
            ndef.textRecord("hello, world")
        ];
    
        var failure = function(reason) {
        
            alert("ERROR: " + reason);
        };
    
        var lockSuccess = function() {
        
            alert("Tag is now read only.");
        };
    
        var lock = function() {
        
            nfc.makeReadOnly(lockSuccess, failure);
        };
    
        nfc.write(record, lock, failure);
    
    },

#### 支持平台 ####

*  Android

### nfc.share ###

通过点对点共享NDEF消息。

一个NDEF由一个或多个NDEF记录数组组成。

var message = [
        ndef.textRecord("hello, world")
    ];
    
    nfc.share(message, [onSuccess], [onFailure]);

#### 参数 ####

*  **ndefMessage**: NDEF记录数组。
 *  **onSuccess**: (可选) 当消息推送成功后回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 描述 ####

`nfc.share` 函数通过使用点对点方式，写入一个Ndef消息。这应该以NFC标签的形式出现在另一个设备上。

#### 支持平台 ####

*  Android
 *  Windows
 *  BlackBerry 7
 *  BlackBerry 10
 *  Windows Phone 8

#### 平台差异 ####

Android - 会一直共享消息，直到调用 nfc.unshare 函数被调用。
    Blackberry 10 - 共享一次消息或直到 nfc.unshare 函数被调用。
    Windows Phone 8 - 和 nfc.write 函数一样，必须在NFC事件处理中调用。

### nfc.unshare ###

停止通过点对点共享NDEF数据。

nfc.unshare([onSuccess], [onFailure]);

#### 参数 ####

*  **onSuccess**: (可选) 当停止共享回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 描述 ####

`nfc.unshare` 函数停止点对点共享数据。

#### 支持平台 ####

*  Android
 *  Windows
 *  BlackBerry 7
 *  BlackBerry 10

### nfc.erase ###

清除一个NDEF标签。

nfc.erase([onSuccess], [onFailure]);

#### 参数 ####

*  **onSuccess**: (可选) 清除成功后的回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 描述 ####

`nfc.erase` 函数将写入空消息来擦除标签。同时，在标签写入之前将会格式化未格式化的标签。

此方法 *必须* 在NDEF事件处理中调用。

#### 支持平台 ####

*  Android
 *  BlackBerry 7

### nfc.handover ###

通过NFC数据切换将文件传输到另外一个设备。

var uri = "content://media/external/audio/media/175";
    nfc.handover(uri, [onSuccess], [onFailure]);
    
    
    var uris = [
        "content://media/external/audio/media/175",
        "content://media/external/audio/media/176",
        "content://media/external/audio/media/348"
    ];
    nfc.handover(uris, [onSuccess], [onFailure]);

#### 参数 ####

*  **uri**: URI字符串，或一组URI地址。
 *  **onSuccess**: (可选) 当消息推送成功后回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 描述 ####

`nfc.handover` 函数使用切换将文件分享给一个NFC点。通过特定 file:// 或 context:// UIR或一组UI发送文件。NFC完成文件传输初始化，同时通过蓝牙或者WIFI来完成数据传输，而这一切都是由NFC数据切换请求实现。Android代码负责构建切换NFC消息。

这只适用于Android，但其他平台后面也可能会实现此功能。

#### 支持平台 ####

*  Android

### nfc.stopHandover ###

停止通过NFC切换共享NDEF数据。

nfc.stopHandover([onSuccess], [onFailure]);

#### 参数 ####

*  **onSuccess**: (可选) 当停止共享成功时回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 描述 ####

`nfc.stopHandover` 函数停止通过NFC切换共享NDEF数据。

#### 支持平台 ####

*  Android

### nfc.showSettings ###

显示设置上的NFC设置信息。

nfc.showSettings(onSuccess, onFailure);

#### 描述 ####

`showSettings` 函数可以打开操作系统的NFC设置。

#### 参数 ####

*  **onSuccess**: (可选) 当调取成功时回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 示例 ####

nfc.showSettings();

#### 支持平台 ####

*  Android
 *  Windows
 *  BlackBerry 10

### nfc.enabled ###

检查设备上的NFC是否可用，并启动NFC功能。

nfc.enabled(onSuccess, onFailure);

#### 参数 ####

*  **onSuccess**: 当NFC启用时的回调函数。
 *  **onFailure**: 当NFC功能被禁用，或者丢失的时候回调函数。

#### 描述 ####

`nfc.enabled` 函数可显示的查看手机是否具有NFC功能，并且确认此功能是否已启用。如果一切都正常，那么成功回调被调用。假设有问题，则失败回调将调用，并附带原因代码。

**NO\_NFC** ：表示设备不支持NFC。  
**NFC\_DISABLED** ：表示用户禁用了NFC功能。

注意：在Android上，NFC状态在每个API调用之前都会被检查， **NO\_NFC** 或 **NFC\_DISABLED** 就可能出现在 **任何** 失败函数的返回参数中。

NFC不存在或禁用时，Windows将返回 **NO\_NFC\_OR\_NFC\_DISABLED** 。如果用户在应用程序启动后禁用了NFC, Windows可能返回 **NFC\_DISABLED** 。Windows在大多数API调用之前检查NFC状态，但在某些情况下，NFC状态还是无法确定。

#### 支持平台 ####

*  Android
 *  iOS
 *  Windows

### nfc.beginSession ###

**`beginSession` 已经过时了. 请使用 `scanNdef` 或 `scanTag`** 。

iOS需要你在开始扫描NFC标签前，开始一个对话。

nfc.beginSession(onSuccess, onFailure);

#### 描述 ####

**`beginSession` 已经过时了. 请使用 `scanNdef` 或 `scanTag`** 。

`beginSession` 方法启动 [NFCNDEFReaderSession][] 让iOS开始扫描NFC标签，同时使用 nfc.addNdefListener 来接收扫描结果。

#### 参数 ####

*  **onSuccess**: (可选) 当调取成功时回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 示例 ####

nfc.beginSession();

#### 支持平台 ####

*  iOS

### nfc.invalidateSession ###

**`invalidateSession` 函数已过期。请使用 `cancelScan` 函数替代。**

设置NFC会话无效。

nfc.invalidateSession(onSuccess, onFailure);

#### 描述 ####

`invalidateSession` 函数停止 [NFCNDEFReaderSession][] ，并将控制权返回给应用。

#### 参数 ####

*  **onSuccess**: (可选) 当停止会话成功时回调函数。
 *  **onFailure**: (可选) 如果有错误调用的回调函数。

#### 案列 ####

nfc.invalidateSession();

#### 支持平台 ####

*  iOS

### nfc.scanNdef ###

调用 `scanNdef` 函数将会开启NFC扫描会话。扫描结果将会通过Promise返回。

nfc.scanNdef();

#### 描述 ####

`scanNdef` 方法启动[NFCNDEFReaderSession][]，允许iOS扫描NFC标签。

#### 返回 ####

*  Promise

#### 示例 ####

// Promise
        nfc.scanNdef().then(
            tag => console.log(JSON.stringify(tag)),
            err => console.log(err)
        );
    
        // Async Await
        try {
        
            let tag = await nfc.scanNdef();
            console.log(JSON.stringify(tag));
        } catch (err) {
        
            console.log(err);
        }

#### 支持平台 ####

*  iOS

### nfc.scanTag ###

调用 `scanTag` 函数将会开启NFC扫描会话。扫描结果将会通过Promise返回。

nfc.scanTag();

#### 描述 ####

`scanTag` 方法启动 [NFCTagReaderSession][]，允许iOS扫描NFC标签。

标签阅读器将尝试从NFC标签获取UID。它还可以从一些非ndef标签中读取UID。

使用 `scanNdef` 方法就可以读取NFC标签信息，除非你需要获取标签的UID。

#### 返回 ####

*  Promise

#### 示例 ####

// Promise
        nfc.scanTag().then(
            tag => {
        
                console.log(JSON.stringify(tag))
                if (tag.id) {
        
                    console.log(nfc.bytesToHexString(tag.id));
                }            
            },
            err => console.log(err)
        );
    
        // Async Await
        try {
        
            let tag = await nfc.scanTag();
            console.log(JSON.stringify(tag));
            if (tag.id) {
        
                console.log(nfc.bytesToHexString(tag.id));
            }
        } catch (err) {
        
            console.log(err);
        }

#### 支持平台 ####

*  iOS

### nfc.cancelScan ###

停止通过 `scanNdef` 或 `scanTag` 创建的NFC扫描会话。

nfc.cancelScan();

#### 描述 ####

`cancelScan` 函数会停止 [NFCReaderSession][] ，并将控制权交给应用。

#### 返回 ####

*  Promise

#### 示例 ####

nfc.cancelScan().then(
            success => {
         console.log('Cancelled NFC session')}, 
            err => {
         console.log(`Error cancelling session ${
          err}`)}
        );

#### 支持平台 ####

*  iOS

## 读取模式功能 ##

### nfc.readerMode ###

读取NFC标签，将标签数据发送给成功回调。

nfc.readerMode(flags, onSuccess, onFailure);

#### 描述 ####

在读取模式下，当读取NFC标签时，结果会作为标签对象返回给回调函数。请注意，普通事件侦听器 *不* 在读取器模式下使用。回调函数接收到的是没有事件包装器的标记对象。

{
        
            "isWritable": true,
            "id": [4, 96, 117, 74, -17, 34, -128],
            "techTypes": ["android.nfc.tech.IsoDep", "android.nfc.tech.NfcA", "android.nfc.tech.Ndef"],
            "type": "NFC Forum Type 4",
            "canMakeReadOnly": false,
            "maxSize": 2046,
            "ndefMessage": [{
        
                "id": [],
                "type": [116, 101, 120, 116, 47, 112, 103],
                "payload": [72, 101, 108, 108, 111, 32, 80, 104, 111, 110, 101, 71, 97, 112],
                "tnf": 2
            }]
        }

启用读取模式后，前台调度和点对点功能将被禁用。

标志控制可指定哪些标签被扫描。同时读取模式的一个好处是，通过添加 nfc.FLAG\_READER\_NO\_PLATFORM\_SOUNDS 标志位，系统声音是可以被禁用的。具体可以查看Android文档 [NfcAdapter.enableReaderMode()][NfcAdapter.enableReaderMode] 来了解更多标志位。

#### 参数 ####

*  **flags**: 表示轮询技术和其他可选参数的标志。
 *  **onSuccess**: 标签被扫描时调用的回调函数。
 *  **onFailure**: 如果有错误调用的回调函数。

#### 示例 ####

nfc.readerMode(
            nfc.FLAG_READER_NFC_A | nfc.FLAG_READER_NO_PLATFORM_SOUNDS, 
            nfcTag => console.log(JSON.stringify(nfcTag)),
            error => console.log('NFC reader mode failed', error)
        );

#### 支持平台 ####

*  Android

### nfc.disableReaderMode ###

禁止NFC读取模式。

nfc.disableNfcReaderMode(onSuccess, onFailure);

#### 描述 ####

禁止NFC读取模式。

#### 参数 ####

*  **onSuccess**: 当禁止成功时的回调函数。
 *  **onFailure**: 当禁止失败时的回调函数。

#### 示例 ####

nfc.disableReaderMode(
            () => console.log('NFC reader mode disabled'),
            error => console.log('Error disabling NFC reader mode', error)
        )

#### 支持平台 ####

*  Android

## 标签技术功能 ##

标签技术功能能直接对标签进行I/O操作。连接标签之后，可用收发器发送命令，关闭标签等。详见[Android TagTechnology][] 、[IsoDep][] 、[NfcV][] 等实现。这些新的api是基于promise方式，而非回调函数。

##### ISO-DEP (ISO 14443-4) 示例 #####

### nfc.connect ###

连接到标签，并从这个TagTechnology对象启用对标签的I/O操作。

nfc.connect(tech);
        nfc.connect(tech, timeout);

#### 描述 ####

`connect` 函数可以通过TagTechnology对象对标签进行I/O操作。`nfc.connect` 函数需要在 `addTagDiscoveredListener` 或 `readerMode` 的回调函数接收到NFC事件之后，才能使用。并且每次只允许一个TagTechnology对象连接到标签。

查看android文档 [TagTechnology.connect()][TagTechnology.connect] 获取更多相关知识。

#### 参数 ####

*  **tech**: 标签技术，如android.nfc.tech.IsoDep。
 *  **timeout**: (可选) 超时时间，单位为毫秒。

#### 返回 ####

*  Promise

当连接成功后，如果标签技术支持maxTransceiveLength属性，则可以选择使用maxTransceiveLength属性。

#### 示例 ####

nfc.addTagDiscoveredListener(function(nfcEvent) {
        
            nfc.connect('android.nfc.tech.IsoDep', 500).then(
                () => console.log('connected to', nfc.bytesToHexString(nfcEvent.tag.id)),
                (error) => console.log('connection failed', error)
            );
        })

#### 支持平台 ####

*  Android

### nfc.transceive ###

向标签发送原始命令并接收响应。

nfc.transceive(data);

#### 描述 ####

`transceive`方法实现向标签发送原始命令并接收响应。此方法调用前需要调用 `nfc.connect`。传输的数据可以是十六进制字符串表示的字节或ArrayBuffer。promise中返回的响应结果为ArrayBuffer格式。

查看Android文档 [IsoDep.transceive()][IsoDep.transceive]、[NfcV.transceive()][NfcV.transceive]、[MifareUltralight.transceive()][MifareUltralight.transceive] 获取更多相关知识。

#### 参数 ####

*  **data**: 十六进制数据字符串或ArrayBuffer。

#### 返回 ####

*  Promise

ArrayBuffer格式的响应数据。

#### 示例 ####

// Promise 风格
        nfc.transceive('90 5A 00 00 03 AA AA AA 00').then(
            response => console.log(util.arrayBufferToHexString(response)),
            error => console.log('Error selecting DESFire application')
        )
    
        // async await
        const response = await nfc.transceive('90 5A 00 00 03 AA AA AA 00');
        console.log('response =',util.arrayBufferToHexString(response));

#### 支持平台 ####

*  Android

### nfc.close ###

关闭TagTechnology连接。

nfc.close();

#### 描述 ####

`close` 方法禁止从TagTechnology对象对标记进行I/O操作，并释放资源。

查看Android文档 [TagTechnology.close()][TagTechnology.close] 获取更多相关知识。

#### 参数 ####

*  none

#### 返回 ####

*  Promise - 当链接被成功关闭

#### 示例 ####

nfc.transceive().then(
            () => console.log('connection closed'),
            (error) => console.log('error closing connection', error);
        )

#### 支持平台 ####

*  Android

## NDEF ##

> `ndef`对象提供NDEF常量，以及创建Ndef记录和转换数据的功能。  
> 查看文档 [android.nfc.NdefRecord][] 获取更多关于常量的信息。

### NdefMessage ###

表示包含一个或多个NdefRecords的NDEF (NFC数据交换格式)数据消息。  
这个插件使用一个NdefRecords数组来表示一个NdefMessage。

### NdefRecord ###

表示一个逻辑的(未分块的)NDEF(NFC Data Exchange Format)记录。

#### Properties ####

*  **tnf**: 3-bit TNF (Type Name Format) - 使用 TNF\_\* 常量之一。
 *  **type**: 字节数组，长度为0 ~ 255字节，不能为空。
 *  **id**: 字节数组，长度为0 ~ 255字节，不能为空。
 *  **payload**: 字节数组，包含0到(2 \*\* 32 - 1)字节，不能为空。

`ndef` 对象具有创建Ndef记录的功能。

var type = "text/pg",
            id = [],
            payload = nfc.stringToBytes("Hello World"),
            record = ndef.record(ndef.TNF_MIME_MEDIA, type, id, payload);

这些辅助函数也可以帮忙创建其它类型记录：

创建一个URI记录：

var record = ndef.uriRecord("http://chariotsolutions.com");

创建一个纯文本记录：

var record = ndef.textRecord("Plain text message");

创建一个 MIME 类型记录：

var mimeType = "text/pg",
            payload = "Hello Phongap",
            record = ndef.mimeMediaRecord(mimeType, nfc.stringToBytes(payload));

创建一个空记录：

var record = ndef.emptyRecord();

创建一个Android应用记录：

var record = ndef.androidApplicationRecord('com.example');

查看 `ndef.record`、`ndef.textRecord`、`ndef.mimeMediaRecord`、 以及 `ndef.uriRecord`。

Ndef对象具有将某些数据类型与字节数组之间进行转换的函数。

查看 [phonegap-nfc.js][] 源代码获取更多信息。

## 事件列表 ##

通过向 `nfc` 对象注册监听器。当NFC标签被读取时，这些事件将被触发。例如：`nfc.addNdefListener(myNfcListener, win, fail)`。

### NFC事件 ###

#### 属性 ####

*  **type**: 事件类型
 *  **tag**: Ndef标签

#### 事件类型列表 ####

*  tag
 *  ndef-mime
 *  ndef
 *  ndef-formatable

标签内容是有平台依懒性的。

在Android上扫描标签时，`id` 和 `techTypes` 可能包含在内。`serialNumber` 可能包含在BlackBerry7上。

`id` and `serialNumber` 是相同值的不同名称。`id` 通常显示为十六进制字符串（通过 `nfc.bytesToHexString(tag.id)` 可以展示出来）。

Windows、Windows Phone 8 和 BlackBerry 10 从标签读取NDEF信息，但无法访问标签id或其他元数据，如容量、只读状态或标签技术。

假设将以下NDEF消息写入标记，则读取时将产生以下事件。

var ndefMessage = [
            ndef.createMimeRecord('text/pg', 'Hello PhoneGap')
        ];

##### Android上事件示例 #####

{
        
            type: 'ndef',
            tag: {
        
                "isWritable": true,
                "id": [4, 96, 117, 74, -17, 34, -128],
                "techTypes": ["android.nfc.tech.IsoDep", "android.nfc.tech.NfcA", "android.nfc.tech.Ndef"],
                "type": "NFC Forum Type 4",
                "canMakeReadOnly": false,
                "maxSize": 2046,
                "ndefMessage": [{
        
                    "id": [],
                    "type": [116, 101, 120, 116, 47, 112, 103],
                    "payload": [72, 101, 108, 108, 111, 32, 80, 104, 111, 110, 101, 71, 97, 112],
                    "tnf": 2
                }]
            }
        }

##### BlackBerry 7上事件示例 #####

{
        
            type: 'ndef',
            tag: {
        
                "tagType": "4",
                "isLocked": false,
                "isLockable": false,
                "freeSpaceSize": "2022",
                "serialNumberLength": "7",
                "serialNumber": [4, 96, 117, 74, -17, 34, -128],
                "name": "Desfire EV1 2K",
                "ndefMessage": [{
        
                    "tnf": 2,
                    "type": [116, 101, 120, 116, 47, 112, 103],
                    "id": [],
                    "payload": [72, 101, 108, 108, 111, 32, 80, 104, 111, 110, 101, 71, 97, 112]
                }]
            }
        }

##### Windows, BlackBerry 10, or Windows Phone 8等上事件示例 #####

{
        
            type: 'ndef',
            tag: {
        
                "ndefMessage": [{
        
                    "tnf": 2,
                    "type": [116, 101, 120, 116, 47, 112, 103],
                    "id": [],
                    "payload": [72, 101, 108, 108, 111, 32, 80, 104, 111, 110, 101, 71, 97, 112]
                }]
            }
        }

### 获取更多关于事件的详细信息 ###

已扫描标签的原始信息在触发事件之前已写入日志。在Android上可使用 `adb logcat`，在BlackBerry上可使用 `Event Log` (按住alt + lglg)。

您还可以在事件处理程序中记录标记内容 `console.log(JSON.stringify(nfcEvent.tag))`。请注意，您想要字符串化标签而不是事件，以避免循环引用。

## 平台差异性 ##

### Non-NDEF Tags ###

只有安卓和BlackBerry7可以读取非ndef NFC标签的数据。使用NXP PN427芯片组的新Windows phone可以读取非ndef标签，但无法获得任何标签元数据。

### Mifare Classic Tags ###

BlackBerry 7, BlackBerry 10 和更新的Android 手机将无法读取Mifare Classic标签。Mifare Ultralight 标签因为是NFC Forum Type 2类型标签可以正常使用。新的Windows 8.1 手机(Lumia 640) 可以读取Mifare Classic标签。

### Tag Id and Meta Data ###

Windows Phone 8、BlackBerry 10和Windows从标签读取NDEF信息，但无法访问标签id或其他元数据，如容量、只读状态或标签技术。

### 多重监听 ###

可以在JavaScript中注册多个侦听器。例如addNdefListener, addTagDiscoveredListener, addmimetypellistener。

在Android上，只有最特定的事件才会触发。如果扫描Mime Media Tag，则只调用addMimeTypeListener回调，而不调用addNdefListener中定义的回调。您可以对多个侦听器使用相同的事件处理程序。

对于Windows，这个插件模仿Android的行为。如果触发了ndef事件，则不会触发标签事件。每个标记应该接收一个事件。

在BlackBerry7上，如果Mime媒体标签被扫描，所有事件都会启动。

### addTagDiscoveredListener ###

在Android上，addTagDiscoveredListener可以扫描non-NDEF标签和NDEF标签。即使标签上有NDEF消息，标签事件也不包含ndefMessage。只有使用addNdefListener或addMimeTypeListener获取NDEF信息。

Windows可以使用addTagDiscoveredListener扫描non-NDEF(未格式化)标签。标记事件将不包含任何数据。

在BlackBerry 7上，addTagDiscoveredListener不扫描non-NDEF标签。事件中返回ndefMessage。

#### 在 *Android* 上使用 addTagDiscoveredListener 扫描Non-NDEF标签 ####

{
        
            type: 'tag',
            tag: {
        
                "id": [-81, 105, -4, 64],
                "techTypes": ["android.nfc.tech.MifareClassic", "android.nfc.tech.NfcA", "android.nfc.tech.NdefFormatable"]
            }
        }

#### 在 *Android* 上使用 addTagDiscoveredListener 扫描NDEF标签 ####

{
        
            type: 'tag',
            tag: {
        
                "id": [4, 96, 117, 74, -17, 34, -128],
                "techTypes": ["android.nfc.tech.IsoDep", "android.nfc.tech.NfcA", "android.nfc.tech.Ndef"]
            }
        }

#### 在 *Windows* 上使用 addTagDiscoveredListener 扫描Non-NDEF标签 ####

{
        
            type: 'tag',
            tag: {
        
            }
        }

## BlackBerry 10 调用目标 ##

这个插件使用[BlackBerry调用框架][BlackBerry]来读取BlackBerry 10上的NFC标签。这意味着您需要在config.xml中注册一个调用目标。

如果你的项目支持多个平台，将www/config.xml复制到merges/config.xml并添加 `rim:invoke-target` 标签。invoke-target决定应用程序在运行时将扫描哪些标签。如果你的应用程序没有运行，黑莓会在扫描到匹配的标签时启动它。

这个样例配置尝试打开任何NDEF标签。

<rim:invoke-target id="your.unique.id.here">
            <type>APPLICATION</type>
            <filter>
                <action>bb.action.OPEN</action>
                <mime-type>application/vnd.rim.nfc.ndef</mime-type>
                
                <property var="uris" value="ndef://0,ndef://1,ndef://2,ndef://3,ndef://4" />
            </filter>
        </rim:invoke-target>

您可以将应用程序配置为仅处理某些标记。

例如，只扫描类型为“text/pg”的MIME媒体标签：

<rim:invoke-target id="your.unique.id.here">
            <type>APPLICATION</type>
            <filter>
                <action>bb.action.OPEN</action>
                <mime-type>application/vnd.rim.nfc.ndef</mime-type>
                
                <property var="uris" value="ndef://2/text/pg" />
            </filter>
        </rim:invoke-target>

或者只扫描纯文本标签使用:

<rim:invoke-target id="your.unique.id.here">
            <type>APPLICATION</type>
            <filter>
                <action>bb.action.OPEN</action>
                <mime-type>application/vnd.rim.nfc.ndef</mime-type>
                
                <property var="uris" value="ndef://1/T" />
            </filter>
        </rim:invoke-target>

查看[BlackBerry文档][BlackBerry 1] 获取更多信息。

## 扫描标签启动应用 ##

在Android上，intent可以用来在NFC标签被读取时启动应用程序。这是可选的，并且需要在AndroidManifest.xml中配置。

<intent-filter>
          <action android:name="android.nfc.action.NDEF_DISCOVERED" />
          <data android:mimeType="text/pg" />
          <category android:name="android.intent.category.DEFAULT" />
        </intent-filter>

注意: `data android:mimeType="text/pg"` 应该匹配你在JavaScript中指定的数据类型。

我们发现有必要添加 `android:noHistory="true"` 到activity元素，以便在用户按下home键后扫描标签启动应用程序。

查看 [NFC intents过滤器][NFC intents] 获取更多信息.

## 相关测试 ##

测试需要使用 [Cordova Plugin 测试框架][Cordova Plugin]

创建一个新的工程

git clone https://github.com/chariotsolutions/phonegap-nfc
        cordova create nfc-test com.example.nfc.test NfcTest
        cd nfc-test
        cordova platform add android
        cordova plugin add ../phonegap-nfc
        cordova plugin add ../phonegap-nfc/tests
        cordova plugin add https://github.com/apache/cordova-plugin-test-framework.git

在 `config.xml` 修改启动页面

在你的手机中启动应用

cordova run

## 示例工程 ##

*  [Ionic NFC Reader][]
 *  [NFC Reader][]
 *  [NFC Writer][]
 *  [NFC Peer to Peer][]
 *  [ApacheCon 2014 Demos][]
 *  [Rock Paper Scissors][] *Android 2.x only*

## HCE ##

主机卡模拟器（Host Card Emulation） (HCE), 可以尝试此插件 [Cordova HCE Plugin][].

## 相关书籍 ##

需要更多信息? 可以查看我写的书

[Beginning NFC: Near Field Communication with Arduino, Android, and PhoneGap][Beginning NFC_ Near Field Communication with Arduino_ Android_ and PhoneGap]

[https_github.com_chariotsolutions_phonegap-nfc]: https://github.com/chariotsolutions/phonegap-nfc
[Link 1]: https://github.com/chariotsolutions/phonegap-nfc/blob/master/doc/GettingStartedCLI.md
[BlackBerry 10]: https://github.com/chariotsolutions/phonegap-nfc/blob/master/doc/GettingStartedBlackberry10.md
[NFCNDEFReaderSession]: https://developer.apple.com/documentation/corenfc/nfcndefreadersession
[NFCTagReaderSession]: https://developer.apple.com/documentation/corenfc/nfctagreadersession
[IntentFilter.addDataType]: http://developer.android.com/reference/android/content/IntentFilter.html#addDataType%28java.lang.String%29
[NFCReaderSession]: https://developer.apple.com/documentation/corenfc/nfcreadersession
[NfcAdapter.enableReaderMode]: https://developer.android.com/reference/android/nfc/NfcAdapter#enableReaderMode%28android.app.Activity,%20android.nfc.NfcAdapter.ReaderCallback,%20int,%20android.os.Bundle%29
[Android TagTechnology]: https://developer.android.com/reference/android/nfc/tech/TagTechnology
[IsoDep]: https://developer.android.com/reference/android/nfc/tech/IsoDep
[NfcV]: https://developer.android.com/reference/android/nfc/tech/NfcV
[TagTechnology.connect]: https://developer.android.com/reference/android/nfc/tech/TagTechnology.html#connect%28%29
[IsoDep.transceive]: https://developer.android.com/reference/android/nfc/tech/IsoDep.html#transceive%28byte%5B%5D%29
[NfcV.transceive]: https://developer.android.com/reference/android/nfc/tech/NfcV.html#transceive%28byte%5B%5D%29
[MifareUltralight.transceive]: https://developer.android.com/reference/android/nfc/tech/MifareUltralight.html#transceive%28byte%5B%5D%29
[TagTechnology.close]: https://developer.android.com/reference/android/nfc/tech/TagTechnology.html#close%28%29
[android.nfc.NdefRecord]: http://developer.android.com/reference/android/nfc/NdefRecord.html
[phonegap-nfc.js]: https://github.com/chariotsolutions/phonegap-nfc/blob/master/www/phonegap-nfc.js
[BlackBerry]: http://developer.blackberry.com/native/documentation/cascades/device_platform/invocation/receiving_invocation.html
[BlackBerry 1]: http://developer.blackberry.com/native/documentation/cascades/device_comm/nfc/receiving_content.html
[NFC intents]: http://developer.android.com/guide/topics/connectivity/nfc/nfc.html#ndef-disc
[Cordova Plugin]: https://github.com/apache/cordova-plugin-test-framework
[Ionic NFC Reader]: https://github.com/don/ionic-nfc-reader
[NFC Reader]: https://github.com/don/phonegap-nfc-reader
[NFC Writer]: https://github.com/don/phonegap-nfc-writer
[NFC Peer to Peer]: https://github.com/don/phonegap-p2p
[ApacheCon 2014 Demos]: https://github.com/don/apachecon-nfc-demos
[Rock Paper Scissors]: https://github.com/don/rockpaperscissors
[Cordova HCE Plugin]: https://github.com/don/cordova-plugin-hce
[Beginning NFC_ Near Field Communication with Arduino_ Android_ and PhoneGap]: http://www.tkqlhce.com/click-7835726-11260198-1430755877000?url=http%3A%2F%2Fshop.oreilly.com%2Fproduct%2F0636920021193.do%3Fcmp%3Daf-prog-books-videos-product_cj_9781449372064_%2525zp&cjsku=0636920021193