mobileNFC

available addEventListener begin invalidate read write readTag setTips stopReadTag

概述

2017年苹果在 WWDC 大会上 开放了 iOS11 读取 NDEF 标准格式的 NFC 功能，但只限于 iPhone 7 及以上的机型。iOS13 开始支持 ISO14443、ISO15693 的读取。

支持NFC的设备： 1、iOS11上的手机只支持读的功能，可以通过手机的NFC功能读标签. 2、iOS13以上的系统支持写的功能。 3、支持NFC的最低设备为iPhone 7和iPhone 7Plus

注意：readTag、setTips、stopReadTag三个接口需要在iOS13以上设备

插件使用攻略

1、登录苹果开发者中心，配置包名（Bundle Identifier）申请 NFC 权限，如下图所示：

图片说明

2、创建 entitlements 文件，告诉 YonBuilder移动开发 应用打包服务器 APP 申请访问 NFC 权限。配置详情参考论坛文档，示例如下：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.nfc.readersession.formats</key>
    <array>
        <string>NDEF</string>
    </array>
</dict>
</plist>

3、应用打包时勾选、填写访问 NFC 提示语，如下图所示：

图片说明

available

当前设备是否支持 NFC 功能

available()

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status:  //布尔类型；是否支持，true|false
}

示例代码

var mobileNFC = api.require('mobileNFC');
mobileNFC.available(function(ret) {
    if (ret.status) {
        api.alert({ msg: "支持 NFC 功能！" });
    } else {
        api.alert({ msg: "不支持 NFC 功能！" });
    }
});

可用性

iOS11 及以上系统

可提供的 1.0.0 及更高版本

addEventListener

添加识别 NDEF 结果的监听

addEventListener(callback(ret))

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    
   status: ,               //布尔类型；是否获取成功 deprecated
   eventType:'',           //字符串类型；交互事件类型；取之范围：
                           //didDetectNDEFs：在iOS11-iOS12上读取成功的回调
                           //didDetectTags：在iOS13上读取带tag成功的回调
                           //connectToTagFail：链接 tag 失败
                           //connectToTagSuccess：链接成功，可以开始读写了
                           //queryNDEFStatusFail：查询tag 状态失败
                           //queryNDEFNotSupported：不是NDEF标签
   messages:[              //数组类型；仅当 eventType 为didDetectNDEFs 时有效
      records:[{
            type:,           //字符串类型；载体的类型
            identifier:,     //字符串类型；载体的标识
            payload: ,       //字符串类型；载体中的未解析数据
            typeNameFormat:  //数字类型；载体的类型名称格式
                             // 0：Empty
                             // 1：NFCWellKnown 
                             // 2：Media  
                             // 3：AbsoluteURI 
                             // 4：NFCExternal   
                             // 5：Unknown 
                             // 6：Unchanged  
      }]
   ]
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    
   code: ,         //布尔类型；是否获取成功
    msg:,           //字符串类型；
}

示例代码

var mobileNFC = api.require('mobileNFC');
mobileNFC.addEventListener(function(ret, err) {
    if (ret.status) {
        api.alert({ msg: JSON.stringify(ret) });
    } else {
        api.alert({ msg: JSON.stringify(err)});
    }
});

可用性

iOS11 及以上系统

可提供的 1.0.0 及更高版本

begin

开始识别 NDEF

begin({params})

params

title：

  • 类型：字符串
  • 描述：（可选项）验证弹框的提示语

multiple：

  • 类型：布尔
  • 描述：（可选项）是否支持多次自动识别
  • 默认：false（识别到 tag 即停止本次识别）

示例代码

var mobileNFC = api.require('mobileNFC');
mobileNFC.begin({
   title: '您正在使用 NFC 功能',
   multiple: false
});

可用性

iOS11 及以上系统

可提供的 1.0.0 及更高版本

invalidate

停止识别 NDEF

invalidate()

示例代码

var mobileNFC = api.require('mobileNFC');
mobileNFC.invalidate();

可用性

iOS11 及以上系统

可提供的 1.0.0 及更高版本

read

开始读取 NDEF 数据。注意本接口仅支持iOS13以上设备。

read(callback(ret))

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{ 
   eventType:'',           //字符串类型；交互事件类型；取之范围：
                           //readNDEFFail：读取错误
                           //messageNull：信息为空
                           //readSuccess：读取成功              
      records:[{           //数组类型；仅当 readSuccess 为didDetectNDEFs 时有效
            type:,           //字符串类型；载体的类型
            identifier:,     //字符串类型；载体的标识
            payload: ,       //字符串类型；载体中的未解析数据
            typeNameFormat:  //数字类型；载体的类型名称格式
                             // 0：Empty
                             // 1：NFCWellKnown 
                             // 2：Media  
                             // 3：AbsoluteURI 
                             // 4：NFCExternal   
                             // 5：Unknown 
                             // 6：Unchanged  
      }] 
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    
   code: ,         //布尔类型；是否获取成功
    msg:,           //字符串类型；
}

示例代码

var mobileNFC = api.require('mobileNFC');
mobileNFC.read(function(ret, err) {
    if (ret.eventType == 'readSuccess') {
        api.alert({ msg: JSON.stringify(ret) });
    } else {
        api.alert({ msg: JSON.stringify(err)});
    }
});

可用性

iOS13 及以上系统

可提供的 1.0.1 及更高版本

write

写 NDEF 数据。注意本接口仅支持iOS13以上设备。

write({params},callback(ret))

params

type：

  • 类型：字符串
  • 描述：载体的类型

identifier：

  • 类型：字符串
  • 描述：载体的标识

payload：

  • 类型：字符串
  • 描述：载体中的未解析数据

typeNameFormat：

  • 类型：数字
  • 描述：（可选项）载体的类型名称格式
  • 默认：1
  • 取值范围：
    • 0：Empty
    • 1：NFCWellKnown
    • 2：Media
    • 3：AbsoluteURI
    • 4：NFCExternal
    • 5：Unknown
    • 6：Unchanged

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{ 
   status:''           //布尔类型；
}

err：

  • 类型：JSON 对象
  • 内部字段：
{
    
   code: ,         //布尔类型；是否获取成功
    msg:,           //字符串类型；
}

示例代码

var mobileNFC = api.require('mobileNFC');
mobileNFC.write({
   type:'U',
   identifier:'123456',
   payload:'www.apicloud.com',
   typeNameFormat:1
},function(ret, err) {
    if (ret.eventType == 'readSuccess') {
        api.alert({ msg: JSON.stringify(ret) });
    } else {
        api.alert({ msg: JSON.stringify(err)});
    }
});

可用性

iOS13 及以上系统

可提供的 1.0.1 及更高版本

readTag

打开NFC，读取ISO14443、ISO15693卡片信息。

readTag(callback(ret，err))

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
  status:      //是否成功
  id:          //status为true时返回卡片物理id
  msg:         //status为false时返回错误信息 
}

err：

  • 类型：JSON 对象
  • 描述：只支持iOS端
  • 内部字段：
{
    
   code: ,         //布尔类型；是否获取成功
    msg:,           //字符串类型；
}

示例代码

var mobileNFC = api.require('mobileNFC');
mobileNFC.readTag(function(ret,err) {
    if (ret.status) {
        api.alert({msg: JSON.stringify(ret)});
    }
}

可用性

iOS 系统

可提供的1.0.2及更高版本

stopReadTag

关闭读取

stopReadTag()

示例代码

var mobileNFC = api.require('mobileNFC');
mobileNFC.stopReadTag();

可用性

iOS 系统

可提供的1.0.2及更高版本

setTips

设置提示文案

setTips({params})

parames

tips:

  • 类型：字符串
  • 描述：（可选项）提示文案
  • 默认："靠近手机背部开始识别"

示例代码

var mobileNFC = api.require('mobileNFC');
mobileNFC.setTips({
    tips:"识别成功！"
});

可用性

iOS 系统

可提供的1.0.2及更高版本

是否仍需要帮助？ 请保持联络！
最后更新于 2024/04/24