更新记录

1.0.0（2021-07-25）

首次发布

平台兼容性

原生插件通用使用流程：

1. 购买插件，选择该插件绑定的项目。
2. 在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
3. 根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
4. 打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
5. 开发完毕后正式云打包

付费原生插件目前不支持离线打包。
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地址。

限制

1. 只支持安卓

使用场景

1. 实时获取NTP时间服务器的时间。
2. 测试NTP时间服务器是否可访问。
3. 比较及分析NTP时间服务器的响应时间。

使用方法

请按以下步骤次序使用插件。

1. 加载插件

// 加载NTP客户端插件
// 插件名称为'zodiac-ntp'
const ntp = uni.requireNativePlugin('zodiac-ntp');
// 加载事件监听插件
const globalEvent = uni.requireNativePlugin('globalEvent');

2. 注册事件监听回调

// 可在页面onLoad()中调用
// 'ntpStatusChange'为默认的事件名称
globalEvent.addEventListener('ntpStatusChange', (e) => {
    // 在此处理事件的相应逻辑
    // 参数e为事件的详细内容，格式请参考“事件格式”章节
});

3. 向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'
}

如果所有属性都不赋值需要传入空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
}

其他注意事项

1. 事件的属性不是每个都会有值，需先判断status属性值再取其他属性值。
2. NTP服务器响应时间一般都在100毫秒以内才算正常，因此timeout值不用设的太长，默认为5000毫秒已经很长了。
3. 调用getDate()方法内部分为两个步骤：(1)向DNS发起请求解析域名获得NTP服务器IP地址。(2)用IP地址向NTP服务器发起请求。setTimeout()方法设定的NTP服务器响应超时时间并不包括DNS解析域名的时间。
4. 事件属性ntpRoundTrip是向NTP服务器发起请求到收到响应的时间差，不包括DNS解析域名的时间。如果第一次向NTP服务器发起请求可能实际响应时间会比ntpRoundTrip的值长很多(例如实际响应时间好几秒，但ntpRoundTrip值是几十毫秒)，这是因为第一次请求时要向DNS请求解析域名，DNS响应时间可能几秒，后续请求IP地址被缓存了，因此可能会快很多。