更新记录
1.0.0(2021-07-25) 下载此版本
首次发布
平台兼容性
Android | Android CPU类型 | iOS |
---|---|---|
适用版本区间:4.4 - 11.0 | armeabi-v7a:支持,arm64-v8a:支持,x86:未测试 | × |
原生插件通用使用流程:
- 购买插件,选择该插件绑定的项目。
- 在HBuilderX里找到项目,在manifest的app原生插件配置中勾选模块,如需要填写参数则参考插件作者的文档添加。
- 根据插件作者的提供的文档开发代码,在代码中引用插件,调用插件功能。
- 打包自定义基座,选择插件,得到自定义基座,然后运行时选择自定义基座,进行log输出测试。
- 开发完毕后正式云打包
付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios
注意事项:使用HBuilderX2.7.14以下版本,如果同一插件且同一appid下购买并绑定了多个包名,提交云打包界面提示包名绑定不一致时,需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择
安卓NTP客户端原生插件
介绍
向NTP时间服务器发起请求得到服务器返回的时间,支持请求超时及时区设定,估算服务器的响应时间及返回服务器的IP地址。
限制
- 只支持安卓
使用场景
- 实时获取NTP时间服务器的时间。
- 测试NTP时间服务器是否可访问。
- 比较及分析NTP时间服务器的响应时间。
使用方法
请按以下步骤次序使用插件。
- 加载插件
// 加载NTP客户端插件
// 插件名称为'zodiac-ntp'
const ntp = uni.requireNativePlugin('zodiac-ntp');
// 加载事件监听插件
const globalEvent = uni.requireNativePlugin('globalEvent');
- 注册事件监听回调
// 可在页面onLoad()中调用
// 'ntpStatusChange'为默认的事件名称
globalEvent.addEventListener('ntpStatusChange', (e) => {
// 在此处理事件的相应逻辑
// 参数e为事件的详细内容,格式请参考“事件格式”章节
});
- 向NTP服务器发起请求
// res如果大于0表示调用成功
// host为NTP服务器的主机名称或IP地址
// NTP服务器返回结果会调用步骤2的事件监听回调
const res = ntp.getDate({
host: 'time.windows.com'
});
方法说明
setHost
用途 设定全局的NTP服务器主机名称或IP地址。后续调用getDate方法时如果输入参数没有给'host'属性则用此全局主机名称。
限制 不接受null或空字符串。
输入值 字符串类型的NTP服务器主机名称或IP地址。
返回值 数字类型,大于0表示调用成功,小于或等于0表示调用失败。0表示主机名称为null或空字符串。
getHost
用途 获取全局的NTP服务器主机名称或IP地址。
限制 无
输入值 无
返回值 字符串类型,全局的NTP服务器主机名称或IP地址。如果没有调用setHost设定主机名称,返回默认值null。
setTimeZone
用途 设定全局的时区。后续调用getDate方法时如果输入参数没有给'timezone'属性则用此全局的时区。设定时区会影响返回的NTP时间的时区值。如未设定时区,默认值为插件所运行的操作系统时区。
限制 无
输入值 字符串类型的时区ID(如'Asia/Shanghai')。插件内部调用java.util.TimeZone.getTimeZone()来获取时区对象,java.util.TimeZone.getTimeZone()可接受的时区ID格式都可输入。时区ID可参考这个网页。 输入值为null或空字符串时表示重设时区为默认值(操作系统时区)。 输入值为错误的时区ID时则会将时区设为’UTC/GMT'时区。
返回值 无
getTimeZone
用途 获取设定的全局时区ID。
限制 无
输入值 无
返回值 字符串类型,全局的时区ID。如果没有调用setTimeZone()设定时区,返回默认值为操作系统时区。
setTimeout
用途 设定全局的NTP服务器响应超时时间。后续调用getDate方法时如果输入参数没有给'timeout'属性则用此全局的超时时间。如未设定超时时间,默认值为5000(毫秒)。
限制 不接受0或小于0的输入值。不接受0表示不能设定无超时。
输入值 数字类型的超时时间,以毫秒为单位。
返回值 数字类型,大于0表示调用成功,小于或等于0表示调用失败。-1表示输入值为0或小于0。
getTimeout
用途 获取设定的全局NTP服务器响应超时时间。
限制 无
输入值 无
返回值 数字类型,全局的NTP服务器响应超时时间。如果没有调用setTimeout设定响应超时时间,返回默认值为5000(毫秒)。
setEventName
用途 设定插件发布事件时的事件名称。默认值为'ntpStatusChange'。调用此方法后插件发布事件的事件名称将会更改。
一般情况不需要变更事件名称,除非默认的事件名称与其他插件所用的事件名称冲突。
限制 不接受null或空字符串。 setEventName()需在调用globalEvent.addEventListener()方法之前调用,且两者使用的事件名称必须相同。
输入值 字符串类型的事件名称。
返回值 数字类型,大于0表示调用成功,小于或等于0表示调用失败。-2表示事件名称为null或空字符串。
getEventName
用途 获取插件发布事件时使用的事件名称。
限制 无
输入值 无
返回值 字符串类型的事件名称。如果没有调用setEventName()设定事件名称,返回默认值'ntpStatusChange'。
getDate
用途 向NTP服务器发起请求获取NTP服务器时间。服务器返回后会调用globalEvent.addEventListener()方法注册的事件监听回调。
限制 无
输入值 Object类型,格式如下:
{
host: 'pool.ntp.org',
timeout: 5000,
timezone: 'Asia/Shanghai'
}
属性 | 必需 | 类型 | 说明 |
---|---|---|---|
host | 否 | String | NTP服务器主机名称或IP地址。如果没有调用过setHost()设定全局的主机名称,则此属性必需给值且不能给空字符串。如果不给此属性,则会使用setHost()所设定的全局主机名称。 |
timeout | 否 | Number | NTP服务器响应超时时间。如果没有此属性,则会使用setTimeout()所设定的全局服务器响应超时时间。如果没有调用过setTimeout()设定全局的服务器响应超时时间,则会使用默认值5000(毫秒)。 |
timezone | 否 | String | 时区,设定事件ntpDate属性的时区(详见事件格式章节)。如果没有此属性,则会使用setTimeZone()所设定的全局时区。如果没有调用过setTimeZone()设定全局的时区,则会使用默认值(操作系统时区)。 |
如果所有属性都不赋值需要传入空Object {}。如下示例:
// 使用设定的全局参数发起请求
ntp.getDate({});
返回值 数字类型,大于0表示调用成功,小于或等于0表示调用失败,0表示主机名称为null或空字符串,-1表示无效的timeout值(等于0或小于0)。
事件格式
在注册事件监听回调时,如下例:
globalEvent.addEventListener('ntpStatusChange', (e) => {
// 在此处理事件的相应逻辑
// 参数e为事件的详细内容
});
第一个参数'ntpStatusChange'为事件名称,第二个参数为回调函数,回调函数入参e格式为:
{
status: 'success',
ntpDate: '2021-07-22T10:21:35+0800',
ntpIp: '192.168.0.100',
ntpRoundTrip: 35,
errorCode: 0
}
属性名 | 类型 | 必须 | 说明 |
---|---|---|---|
status | String | 是 | 请求NTP服务器的结果状态。可为'success'(请求成功)或'failure'(请求失败)。当值为'success',有效属性为'ntpDate', 'ntpIp', 'ntpRoundTrip'。当值为'failure'时,有效属性为'errorCode'。 |
ntpDate | String | 否 | NTP服务器返回的服务器时间。格式为'yyyy-MM-dd'T'HH:mm:ssZ',如'2021-07-22T10:21:35+0800'。时间格式中的'Z'表示时区。时区为调用getDate()方法时timezone属性所设定的时区,如果调用getDate()方法时没有给时区,则使用setTimeZone()所设定的全局时区,如果没有调用setTimeZone(),则使用默认值(操作系统时区)。 |
ntpIp | String | 否 | NTP服务器的IP地址。 |
ntpRoundTrip | Number | 否 | 向NTP服务器发起请求到收到响应的时间差,以毫秒为单位。 |
errorCode | Number | 否 | 错误代码。当'status'属性值为'failure'时有效。'errorCode'有效值为1,2,3,4,5,6,7,8。1为网络底层问题无法发送或接收封包。2为违反系统的安全策略。3为网络封包无法送达。4为处理任务阻塞。5为参数不匹配。6为请求超时。7为通信管道已关闭。8为请求的服务器名称或IP地址错误。 |
其他注意事项
- 事件的属性不是每个都会有值,需先判断status属性值再取其他属性值。
- NTP服务器响应时间一般都在100毫秒以内才算正常,因此timeout值不用设的太长,默认为5000毫秒已经很长了。
- 调用getDate()方法内部分为两个步骤:(1)向DNS发起请求解析域名获得NTP服务器IP地址。(2)用IP地址向NTP服务器发起请求。setTimeout()方法设定的NTP服务器响应超时时间并不包括DNS解析域名的时间。
- 事件属性ntpRoundTrip是向NTP服务器发起请求到收到响应的时间差,不包括DNS解析域名的时间。如果第一次向NTP服务器发起请求可能实际响应时间会比ntpRoundTrip的值长很多(例如实际响应时间好几秒,但ntpRoundTrip值是几十毫秒),这是因为第一次请求时要向DNS请求解析域名,DNS响应时间可能几秒,后续请求IP地址被缓存了,因此可能会快很多。