Cordova NFC插件中文说明V1.0

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)。

<preference name="phonegap-version" value="cli-9.0.0" />
<plugin name="phonegap-nfc" source="npm" />

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

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

具体可通过查看：开始使用插件 和 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

平台支持函数列表

方法	Adnroid	iOS	Windows	BlackBerry 7	BlackBerry 10	Windows Phone 8
addNdefListener	支持	支持	支持	支持	支持	支持
addTagDiscoveredListener	支持	-	支持	支持	-	-
addMimeTypeListener	支持	-	-	支持	-	-
addNdefFormatableListener	支持	-	-	-	-	-
write	支持	支持	支持	支持	-	支持
makeReadOnly	支持	-	-	-	-	-
share	支持	-	支持	支持	支持	支持
unshare	支持	-	支持	支持	支持	-
erase	支持	-	-	支持	-	-
handover	支持	-	-	-	-	-
stopHandover	支持	-	-	-	-	-
enabled	支持	支持	支持	-	-	-
showSettings	支持	-	支持	-	支持	-
beginSession	-	支持	-	-	-	-
invalidateSession	-	支持	-	-	-	-
scanNdef	-	支持	-	-	-	-
scanTag	-	支持	-	-	-	-
cancelScan	-	支持	-	-	-	-

只读模式

• 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())

支持平台

• 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() 来了解更多标志位。

参数

• 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) 示例

    const DESFIRE_SELECT_PICC = '00 A4 04 00 07 D2 76 00 00 85 01 00';
    const DESFIRE_SELECT_AID = '90 5A 00 00 03 AA AA AA 00'

    async function handleDesfire(nfcEvent) {
        
        const tagId = nfc.bytesToHexString(nfcEvent.tag.id);
        console.log('Processing', tagId);

        try {
            await nfc.connect('android.nfc.tech.IsoDep', 500);
            console.log('connected to', tagId);
            
            let response = await nfc.transceive(DESFIRE_SELECT_PICC);
            ensureResponseIs('9000', response);
            
            response = await nfc.transceive(DESFIRE_SELECT_AID);
            ensureResponseIs('9100', response);
            // 91a0 means the requested application not found

            alert('Selected application AA AA AA');

            // more transcieve commands go here
            
        } catch (error) {
            alert(error);
        } finally {
            await nfc.close();
            console.log('closed');
        }

    }

    function ensureResponseIs(expectedResponse, buffer) {
        const responseString = util.arrayBufferToHexString(buffer);
        if (expectedResponse !== responseString) {
            const error = 'Expecting ' + expectedResponse + ' but received ' + responseString;
            throw error;
        }
    }

    function onDeviceReady() {
        nfc.addTagDiscoveredListener(handleDesfire);
    }

    document.addEventListener('deviceready', onDeviceReady, false);

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() 获取更多相关知识。

参数

• 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()、NfcV.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() 获取更多相关知识。

参数

• 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 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>
            <!-- any TNF Empty(0), Well Known(1), MIME Media(2), Absolute URI(3), External(4) -->
            <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>
            <!-- TNF MIME Media(2) with type "text/pg" -->
            <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>
            <!-- TNF Well Known(1), RTD T -->
            <property var="uris" value="ndef://1/T" />
        </filter>
    </rim:invoke-target>

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

扫描标签启动应用

在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过滤器 获取更多信息.

相关测试

测试需要使用 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 修改启动页面

    <content src="cdvtests/index.html" />

在你的手机中启动应用

    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