Device插件参考手册¶
Title: | Device插件参考手册 |
---|---|
Author: | cuipeng@boyaa.com |
Version: | 3.0.1 |
Update: | 2017-11-15 |
简介¶
Device是客户端引擎V3.x/4.0的Plugin,封装了设备原生的一些功能给lua开发者使用
主要功能包含相机、相册、通讯录、嵌入浏览器、原生对话框、设备信息、网络信息、电源信息等
使用Device插件的同学,请关注我的文章: http://stackoverflow.oa.com/people/崔鹏
使用支持多选功能的相册,请参考:
http://gogit.oa.com/cuipeng/AndroidMediaPicker
http://gogit.oa.com/cuipeng/iOSMediaPicker
使用音频管理模块,请参考:
版本策略¶
向下兼容
Device插件采用向下兼容的方式开发和升级,也就是说,高版本(后续版本)将继续支持低版本的API
新的功能将在最新的Device插件版本上增加,旧版本的Device插件仅进行bugfix
运行时查看版本方法是:插件启动后会打印版本号,例如:
device version 3.0.0.20161027161568 (编译日期为2016-10-27 16:15:68)
device插件4.0和3.x版本分别对应引擎3.x和4.0版本,不能混用.
支持的引擎版本
CHANGES¶
Build 4.0.1.20170523¶
NativeDevice 增加
NativeDevice.isReady
Build 4.0.1.20170508¶
AudioRecorder 增加
AudioRecorder.rawPause
AudioRecorder.rawResume
AudioRecorder.rawIsPause
Device 4.0 支持引擎4.0
iOS 最低支持 iOS8
Build 3.0.1.20170420¶
NetworkInfo 增加:
NetworkInfo.getMNO
NetworkInfo.getSSID
PowerInfo 增加:
PowerInfo.setBatteryChangedEvent
增加 DisplayInfo :
DisplayInfo.getInches
增加 isVirtual.lua
bugfix
Build 3.0.1.20170214¶
WebView 增加:
WebView.enableLoadingDialog2
增加 javascript 函数: native_close_loading 增加 javascript 函数: native_close_keyboard
Build 3.0.1.20170120¶
WebView 增加:
WebView.TOP_LEFT_INNER
WebView.TOP_RIGHT_INNER
PhotoLibrary 增加:
PhotoLibrary.insertImageFile
增加了 AudioRecorder 类
NetworkInfo 增加:
NetworkInfo.getNetworkSubType
Permissions 增加
Permissions.EXTERNAL_STORAGE
Build 3.0.1.20161214¶
WebView 增加:
WebView.setBackgroundColor
WebView.loadString
WebView.enableLoadImage
NetworkInfo 增加:
NetworkInfo.isInternetConnected
增加了 GeoLocation 类
Build 3.0.1.20161223¶
WebView 增加:
增加 javascript 函数: native_log
DeviceInfo 增加:
DeviceInfo.getStorageSize
DeviceInfo.getStorageAvailable
增加了 MemoryInfo 类
Build 3.0.1.20161229¶
WebView 增加:
WebView.EVENT_REFRESH
WebView.enablePullRefresh
安装¶
发布地址和文件列表¶
win32文件列表
device.dll
(插件主库)
libconfig++.dll
(读写配置文件用的库)
ByCamera.exe
(windows相机程序)
PhotoAlbum.exe
(windows相册程序)
location.html
(定位功能模拟用的地图页面)
Settings.exe
(windows权限管理工具,用户可手动运行)
device.lua
(配置文件,配置启动画面/权限模拟平台/通讯录等,源码中包含详细说明)
chrome21.zip
(chrome浏览器库,解压至device.dll
相同目录下,要覆盖2个OpenGL库)android文件列表
libdevice.so
device.jar
iOS文件列表
libdevice.a
—lua 文件列表
android 接入¶
编译环境配置
<uses-sdk android:minSdkVersion="14" android:targetSdkVersion="23"/>若直接支持 android 6.0 (Device插件支持),可将
targetSdkVersion
的值配置为>=23<uses-sdk android:minSdkVersion="14" android:targetSdkVersion="23"/>需要最新版的
android-support-v4.jar
在Activity中初始化:
import com.boyaa.engine.device.Device; //Activity的派生类需要实现一个interface并加入onRequestPermissionsResult的方法实现 public class Game extends AppActivity implements ActivityCompat.OnRequestPermissionsResultCallback @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); //初始化device //device内部调用了android的Activity.startActivityForResult方法 //这里的requestCodeStart是设置device使用>=1000的值. //device内部会使用不超过10个requestCode int requestCodeStart = 1000; int permissionsRequestCodeStart=1000; Device.getInstance().init(this,requestCodeStart,permissionsRequestCodeStart); } @Override protected void onResume() { //Device resume Device.getInstance().onResume(); super.onResume(); } @Override protected void onPause() { //Device pause Device.getInstance().onPause(); super.onPause(); } @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { //Device onActivityResult if ( Device.getInstance().onActivityResult(requestCode, resultCode, data)) { return; } super.onActivityResult(requestCode, resultCode, data); } @Override public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) { //Device onRequestPermissionsResult if ( Device.getInstance().onRequestPermissionsResult(requestCode, permissions, grantResults)) { return; } }配置权限
如果没有用到Device插件对应的功能,就无需配置对应的权限.
读写 external storage
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />相机
<uses-permission android:name="android.permission.CAMERA" />通讯录
<uses-permission android:name="android.permission.READ_CONTACTS" />访问设备(震动、屏幕亮度控制等)
<uses-permission android:name="android.permission.VIBRATE" /> <uses-permission android:name="android.permission.WAKE_LOCK" />网络信息
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.READ_PHONE_STATE" />录音
<uses-permission android:name="android.permission.RECORD_AUDIO" />电源信息
<uses-permission android:name="android.permission.BATTERY_STATS"/>获取设备名称:DeviceInfo.getName()
<uses-permission android:name="android.permission.BLUETOOTH" />定位(GPS)
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />![]()
iOS 接入¶
Xcode环境相关
device工程在Xcode中的Deployment Target设置为7.0 ( Device插件最低支持 iOS 7.0 )
Objective-C Automatic Reference Counting 设置为 YES
Other Linker Flags增加一条: -ObjC (可以去掉了)
需要链接下面所有的库(请注意
optional
):libdevice.a
required
AddressBook.framework
required
Contacts.framework
optional
Photos.framework
optional
UIKit.framework
optional
WebKit.framework
optional
SystemConfiguration.framework
required
CoreMotion.framework
required
AVFoundation.framework
optional
CoreLocation.framework
optional
CoreTelephony.framework
optional
Hide status bar
如果需要支持iOS平台NetworkInfo.getNetworkTypeName/getNetworkSubType接口的话,XCode设置中不要选中这项;
在 Build 3.0.1.20170420之后的版本,不再需要 Hide status bar
配置权限
如果没有用到Device插件对应的功能,就无需配置对应的权限.
在Info.plist中增加如下内容:
相机:NSCameraUsageDescription
相册:NSPhotoLibraryUsageDescription
通讯录:NSContactsUsageDescription
录音:NSMicrophoneUsageDescription
定位(GPS):NSLocationWhenInUseUsageDescription
打开电话和短信:
<key>LSApplicationQueriesSchemes</key> <array> <string>tel</string> <string>sms</string> </array>打开IOS[定位服务]的系统设置界面:
xcode设置:[info]->[URL Types] 中添加一项,并将[URL Schemes]中填入”prefs”(不包含引号).
源码相关
示例代码¶
相机¶
--此为拍摄完成后回调的lua函数
onCameraEvent = function(flag,imageFile)
if NativeDevice.Camera.OPEN_SUCCESS == flag then
--拍摄成功, imageFile是图片文件名
end
if NativeDevice.Camera.OPEN_CANCEL == flag then
--用户Cancel了拍摄
end
if NativeDevice.Camera.OPEN_ERROR == flag then
--错误
end
if NativeDevice.Camera.OPEN_NO_PERMISSION == flag then
--没有权限或用户禁止了权限
end
end
function openCamera()
local outputPath = ...
--设置拍摄图片的存放路径
NativeDevice.Camera.setImagePath(outputPath);
--设置拍摄图片为PNG格式
NativeDevice.Camera.setImageFormat(NativeDevice.Camera.IMAGE_PNG);
--设置拍摄图片的长度、宽度,单位为像素
NativeDevice.Camera.setImageSize(400,300);
--选择缺省的相机
NativeDevice.Camera.select(NativeDevice.Camera.DEFAULT_CAMERA);
--拍摄完成后允许编辑
NativeDevice.Camera.enableEdit(true);
--打开相机,设置拍摄完成后回调的lua函数
NativeDevice.Camera.open(onCameraEvent);
end

相机权限¶
local Permissions = NativeDevice.Permissions;
--查询相机权限,以便于分别处理
local status = Permissions.getStatus(Permissions.CAMERA);
--如果是受限状态(比如儿童模式),则返回
if status == Permissions.STATUS_RESTRICTED then
return;
end
--如果是允许状态,则打开相机
if status == Permissions.STATUS_GRANTED then
openCamera();
return;
end
--用户授权的回调函数
function onUserGranted(granted)
if granted then
openCamera();
end
end
--如果是未确定状态,则请求相机权限(会打开系统对话框)
if status == Permissions.STATUS_NOT_DETERMINED then
Permissions.request(Permissions.CAMERA,onUserGranted);
end
--如果是拒绝状态,则向用户解释原因,请求用户再次授权
if status == Permissions.STATUS_DENIED then
local param = {
reason="斗地主拍照功能需要使用您的相机,在使用相机之前需要您授权同意,请点击[下一步]进入授权界面",
ok_title="下一步",
cancel_title="取消"};
Permissions.requestReason(Permissions.CAMERA,param,onUserGranted);
end

相册¶
--此为浏览并选择图片完成后回调的lua函数
onPhotoLibEvent = function(flag,imageFile)
if NativeDevice.PhotoLibrary.PICK_SUCCESS == flag then
--成功, imageFile是图片文件名
end
if NativeDevice.PhotoLibrary.PICK_CANCEL == flag then
--用户Cancel了
end
if NativeDevice.PhotoLibrary.PICK_ERROR == flag then
--错误
end
if NativeDevice.PhotoLibrary.PICK_NO_PERMISSION == flag then
--没有权限或用户禁止了权限
end
end
local path = ...
--设置图片的存放路径
NativeDevice.PhotoLibrary.setImagePath(path);
--设置图片保存为PNG格式
NativeDevice.PhotoLibrary.setImageFormat(NativeDevice.PhotoLibrary.IMAGE_PNG);
--设置图片的长度、宽度,单位为像素
NativeDevice.PhotoLibrary.setImageSize(400,300);
--设置用户选择完成后允许编辑
NativeDevice.PhotoLibrary.enableEdit(true);
--浏览图片,设置浏览完成后回调的lua函数
NativeDevice.PhotoLibrary.pick(onPhotoLibEvent);

通讯录¶
--读取通讯录数目
local count = NativeDevice.Contacts.getCount();
--从第0条开始读取,读20条
local defaultSort = 0;
local contacts = NativeDevice.Contacts.read(0,20,defaultSort);
--返回contacts是一个lua table,格式如下:
--contacts[1] = {id="7033",name="赵丽颖",phone_numbers = {home="0755-88886666",mobile="13988886666"}}
--contacts[2] = {id="7034",name="李易峰",phone_numbers = {"46446","+86 18633443344"}}
--...
--contacts[5] = {id="7028",name="杨紫",phone_numbers = {workNumber="010-88310571"}}

WebView¶
--java script调用lua的回调函数
onWeb1JsEvent = function(stringData)
--
end
--webview事件
onWeb1Event = function(cmd)
if cmd == NativeDevice.WebView.EVENT_LOAD_SUCCESS then
--加载网页成功
end
if cmd == NativeDevice.WebView.EVENT_LOAD_FAILED then
--加载网页失败
end
if cmd == NativeDevice.WebView.EVENT_QUIT then
--用户点击了网页上的close按钮(如果有的话)
end
end
--创建一个WebView对象,设置屏幕坐标,单位为像素
web1 = NativeDevice.WebView(0,0,400,300);
--设置webview事件回调的lua函数
web1:setEvent(onWeb1Event);
--设置java script调用lua的回调函数
web1:setJsCallback(onWeb1JsEvent);
local imgPath = sys_get_string("storage_app_images");
--在webview窗口右上角添加一个close按钮,设置按钮图片,按钮大小,单位为像素
web1:enableCloseButton(NativeDevice.WebView.TOP_RIGHT,imgPath.."close.png",32,32);
--设置webview在加载网页时显示一个loading动画,设置动画图片,动画窗口大小,单位为像素,动画窗口显示的文字
web1:enableLoadingDialog(imgPath.."load1.png",loadingSize,loadingSize,"加载&Loading...");
--设置webview显示水平和垂直滚动条
web1:enableScrollBar(true,true);
--设置webview禁止缓存
web1:enableCache(false);
--设置webview浏览时禁止回退和前进
web1:enableBackOrForward(false);
--打开webview窗口,并且加载指定网址
web1:loadUrl("www.boyaa.com");

API参考¶
Permissions(权限)¶
简介
API列表
Permissions.getStatus(type)
功能说明
查询某类权限的状态,权限的状态有4种: 未确定,授权,拒绝,限制授权
type
查询的类型,取值为:
Permissions.CAMERA
Permissions.PHOTO_LIBRARY
Permissions.CONTACTS
Permissions.PHONE_STATE
Permissions.RECORD_AUDIO
Permissions.GEO_LOCATION
Permissions.EXTERNAL_STORAGE
返回值
返回权限的状态, 取值为:
Permissions.STATUS_NOT_DETERMINED
Permissions.STATUS_GRANTED
Permissions.STATUS_DENIED
Permissions.STATUS_RESTRICTED
Permissions.request(type,function)
功能说明
请求某类权限. 如果某类权限为Permissions.STATUS_NOT_DETERMINED
状态,调用此接口可以打开系统对话框,让用户进行授权.
type
请求的类型,取值为:
Permissions.CAMERA
Permissions.PHOTO_LIBRARY
Permissions.CONTACTS
Permissions.PHONE_STATE
Permissions.RECORD_AUDIO
Permissions.GEO_LOCATION
Permissions.EXTERNAL_STORAGE
function
函数声明为:onUserGrant=function(granted) --granted 取值为 true/false, true以为用户同意授权 end
function
不允许为nil
返回值
无
Permissions.requestReason(type,param,function)
功能说明
当用户拒绝(Permissions.STATUS_DENIED
)了某类权限后,调用此接口创建对话框向用户解释申请某类权限的原因,如果用户同意则可再次进行授权.
type
请求的类型,取值为:
Permissions.CAMERA
Permissions.PHOTO_LIBRARY
Permissions.CONTACTS
Permissions.PHONE_STATE
Permissions.RECORD_AUDIO
Permissions.GEO_LOCATION
Permissions.EXTERNAL_STORAGE
function
函数声明为:onUserGrant=function(granted) --granted 取值为 true/false, true以为用户同意授权 end
function
不允许为nil
param
对话框的参数, 类型为 lua table, 如下:param = { reason="拍照功能需要使用您的相机,在使用相机之前需要您授权同意,请点击[下一步]进入授权界面", --向用户解释原因 ok_title="下一步", --用户同意按钮的标题 cancel_title="取消" --用户不同意按钮的标题 };
返回值
无win32提供了对以上权限接口的完整模拟,介绍如下: 在 Settings.exe 中可以修改权限; 在 device.lua 中可以选择win32模拟哪类设备的权限,支持:
iOS
android 4.x原生
android 4.x 定制或root版
android 6.0
device.lua中配置示例如下:
permissions = { options = {"ios","android_4","android_root","android_6"}, camera = "ios", --win32模拟iOS相机权限 photo_library="android_6", --win32模拟 android 6.0 相册权限 contacts="android_root", --win32模拟 android 4.x 华为 通讯录权限 phone_state="android_4", --win32模拟 android 4.x 原生版权限 record_audio="android_4", geo_location="android_6", }
Camera(相机)¶
简介
API列表
Camera.setImagePath(path)
功能说明
设置拍摄图片的存放路径,缺省值为空
path
类型为string
,拍照图片文件保存路径
返回值
无
Camera.setImageFormat(format)
功能说明
设置拍摄图片的格式,缺省值为png格式
format
图片格式,取值为:
Camera.IMAGE_PNG
Camera.IMAGE_JPG
返回值
无
Camera.setQuality(quality)
功能说明
设置拍摄图片后保存图片质量,仅对jpg格式有效
quality
图片质量,取值为0-100,缺省值为80
返回值
无
Camera.setImageSize(width,height)
功能说明
设置拍摄图片的长度、宽度,单位为像素,缺省值为0,0
width
类型为number
,宽度,>=0
height
类型为number
,宽度,>=0,如果width
height
其中一个为0,则为0的值会自动按原图的长宽比计算
返回值
无
Camera.enableEdit(enable)
功能说明
设置拍摄完成后允许编辑,缺省为true
enable
类型为boolean
返回值
无
Camera.select(type)
功能说明
选择摄像机
type
相机类型,取值为:
Camera.DEFAULT_CAMERA
Camera.FRONT_CAMERA
缺省为
Camera.DEFAULT_CAMERA
返回值
无
支持平台
Camera.FRONT_CAMERA
仅支持iOS平台
Camera.open(function)
功能说明
启动相机进行拍照
function
函数声明为:onCameraEvent=function(flag,fileName) --flag取值为: --Camera.OPEN_SUCCESS 拍摄成功 --Camera.OPEN_CANCEL 拍摄时用户取消 --Camera.OPEN_ERROR 拍摄时未知错误 --Camera.OPEN_NO_PERMISSION 没有权限 --fileName取值:当flag为Camera.OPEN_SUCCESS时,fileName为图片名,例如:13198118.png end
function
不允许为nil
返回值
无
此为异步接口
平台差异
android平台不同厂家(三星、华为、小米、360等)调用此接口会有差异, 未授权时华为mate7(android 4.x) 上onCameraEvent
不会被调用. 未授权时360(android 6.0)上事件结果是Camera.OPEN_CANCEL
.
权限
Permissions.CAMERA
PhotoLibrary(相册)¶
简介
API列表
PhotoLibrary.setImagePath(path)
功能说明
设置选中图片的存放路径,缺省值为空
path
类型为string
,选中图片文件保存路径
返回值
无
PhotoLibrary.setImageFormat(format)
功能说明
设置选中图片的保存格式,缺省值为png格式
format
图片格式,取值为:
PhotoLibrary.IMAGE_PNG
PhotoLibrary.IMAGE_JPG
返回值
无
PhotoLibrary.setQuality(quality)
功能说明
设置选中图片后保存图片的质量,仅对jpg格式有效
quality
图片质量,取值为0-100,缺省值为80
返回值
无
PhotoLibrary.setImageSize(width,height)
功能说明
设置选中图片保存的长度、宽度,单位为像素,缺省值为0,0
width
类型为number
,宽度,>=0
height
类型为number
,宽度,>=0,如果width
height
其中一个为0,则为0的值会自动按原始图片的长宽比计算
返回值
无
PhotoLibrary.enableEdit(enable)
功能说明
设置选中后允许编辑,缺省为true
enable
类型为boolean
返回值
无
PhotoLibrary.pick(function)
功能说明
打开系统缺省图片浏览器进行选择
function
函数声明为:onPhotoLibraryEvent=function(flag,fileName) --flag取值为: --PhotoLibrary.PICK_SUCCESS 选择成功 --PhotoLibrary.PICK_CANCEL 选择时用户取消 --PhotoLibrary.PICK_ERROR 选择时未知错误 --PhotoLibrary.PICK_NO_PERMISSION 没有权限 --fileName取值:当flag为PhotoLibrary.PICK_SUCCESS,fileName为图片名,例如:13198118.png end
function
不允许为nil
返回值
无
此为异步接口
平台差异
android平台不支持PhotoLibrary.PICK_NO_PERMISSION
参数,但用户拒绝权限时,onPhotoLibraryEvent
不会被调用
权限
Permissions.PHOTO_LIBRARY
PhotoLibrary.insertImageFile(path)
功能说明
将指定图片文件放入相册
path
类型为string
,图片文件的完整路径
返回值
返回boolean
如果文件不存在则返回false
此为异步接口
调用此接口返回true
后不能立即删除文件,因为执行图片文件拷贝的线程还未执行完成.
权限
Permissions.EXTERNAL_STORAGE
Contacts(通讯录)¶
简介
API列表
contacts.getCount()
功能说明
读取通讯录中记录的数目
返回值
类型为number
,返回数目
线程支持
支持在任意线程中调用
性能说明
Android平台调用此接口耗时在几十毫秒,iOS平台调用此接口耗时在几十毫秒
权限
Permissions.CONTACTS
contacts.read(start,num,sortType)
功能说明
读取通讯录中的记录
start
类型为number
,从第start条开始读取, -1意为倒数第1条
num
类型为number
,最多读取num条
sortType
固定取值为contacts.SORT_DEFAULT
,保留值
返回值
类型为table
或nil
,例如:--contacts[1] = {id="7033",name="赵丽颖",timestamp=1474193836631.000,phone_numbers = {home="0755-88886666",mobile="13988886666"}} --contacts[2] = {id="7034",name="李易峰",timestamp=1474193836631.000,phone_numbers = {"46446","+86 18633443344"}} --... --contacts[5] = {id="7028",name="杨紫",timestamp=1474193836631.000,phone_numbers = {workNumber="010-88310571"}} --说明1:phone_numbers是一个lua table; 其中的电话号码是从手机中读出并且未做任何处理的. --说明2:timestamp是此条记录的最后修改时间
线程支持
支持在任意线程中调用
性能说明
Android平台调用此接口耗时在几十至几百毫秒,iOS平台调用此接口耗时在几十至几百毫秒
权限
Permissions.CONTACTS
contacts.search(key)
功能说明
按关键字搜索通讯录中的记录
key
类型为string
,搜索关键字,例如 “张” “139”
返回值
同contacts.read
线程支持
支持在任意线程中调用
性能说明
Android平台调用此接口耗时在几十至几百毫秒,iOS平台调用此接口耗时在几十至几百毫秒
权限
Permissions.CONTACTS
Uri¶
简介
API列表
Uri.stringEscape(str,spaceToPlus,normalizeBreaks);
功能说明
url编码
str
类型为string
输入的字符串
spaceToPlus
类型为boolean
是否将空格转为+
normalizeBreaks
类型为boolean
是否将CR和LF转为CR-LF
返回值
类型为string
,编码后的字符串
Uri.stringUnescape(str,plusToSpace);
功能说明
url解码
str
类型为string
输入的字符串
plusToSpace
类型为boolean
是否将+转为空格
返回值
类型为string
,解码后的字符串![]()
GeoLocation(定位)¶
简介
API列表
GeoLocation.isEnable(type)
功能说明
检查type
功能是否可用
type
取值GeoLocation.GPS
或GeoLocation.NETWORK
, 一般手机均支持2种定位, 一种是卫星定位, 一种是网络(cell或wifi等)定位. 该接口的一种用途是:如果需要GPS定位,可以预先检查一下是否可用. 如果要定位到城市,那么用网络定位可能更快.
返回值
类型为boolean
权限
Permissions.GEO_LOCATION
GeoLocation.showSettings()
功能说明
打开定位服务的系统设置对话框,可以让用户更快捷的启动系统的定位服务.
返回值
无
GeoLocation.setEvent(accuracy, minTime, minDistance,function);
功能说明
启动定位, 位置信息会源源不断的发往function
,每次调用此接口,都会先清除上一次的调用和参数设置.
accuracy
定位精度, 取值如下. 定位精度要求越高,越耗电,精度要求越高,首次定位速度越慢.建议选择业务所需的合理精度. 定位精度仅是一个参考值,定位结果的精度可能与其有出入.GeoLocation.ACCURACY_FOR_NAVIGATION 用于导航的精度 GeoLocation.ACCURACY_BEST 最好的精度 GeoLocation.ACCURACY_TEN_METERS 10米左右的精度 GeoLocation.ACCURACY_HUNDRED_METERS 100米左右的精度 GeoLocation.ACCURACY_KM 公里级的精度 GeoLocation.ACCURACY_THREE_KMS 三公里的精度
minTime
定位的最小时间间隔.单位为毫秒
, 系统将会按照这个最小间隔来定位. 时间间隔越小,越耗电.
minDistance
距离变化的最小值, 当位置发生变化之后,与上一次位置的距离大于该值时,才回调function
,仅作为一个参考值.
function
系统调用此函数来传递定位结果, 函数声明为:function onLocation (location) --[[ location是一个table,定义如下 location = { status = GeoLocation.STATUS_XXX, --返回定位结果的当前状态和信息,下文有定义 gps = true, --定位的结果是否来源于gps,取值 true or false longitude = 经度, latitude = 纬度, altitude = 海拔,米 accuracy = 精度,米 timestamp = 时间戳,毫秒 } ]] endstatus 取值如下:
GeoLocation.STATUS_AVAILABLE_WITH_DATA 定位设备可用,当前location结果中包含经纬度等定位数据 GeoLocation.STATUS_AVAILABLE 定位设备可用, GeoLocation.STATUS_TEMPORARILY_UNAVAILABLE 定位设备临时不可用,可以继续使用. GeoLocation.STATUS_OUT_OF_SERVICE 无GPS信号(不在服务区) ,可以继续使用. GeoLocation.STATUS_ENABLE 定位被启用(比如:手机中的位置服务被用户启用) GeoLocation.STATUS_DISABLE 定位被禁用或或其他原因无法使用.无法继续使用. 对于可以继续使用的状态, location 数据还会继续收到.
function
取值为nil
则会终止定位.
返回值
无
支持平台
win32平台通过地图来模拟定位,需要开发人员手动在地图上多次选择位置.
权限
Permissions.GEO_LOCATION
GeoLocation.setSingleEvent(accuracy, function);
功能说明
定位1次, 位置信息(或错误信息)会发往function
,连续调用多次本接口, 每次调用都会回调function
,除了导航等功能以外,大多业务需求仅需1次定位, 更省电,速度可能更快.
accuracy
定位精度, 同setEvent
的参数``accuracy``
function
为nil
则调用无效, 其余使用同setEvent``的参数 ``function
返回值
无
支持平台
win32平台通过地图来模拟定位,需要开发人员手动在地图上选择1次位置.
权限
Permissions.GEO_LOCATION
WebView(嵌入浏览器)¶
简介
嵌入浏览器:
支持设置浏览器窗口大小;支持lua和javascript互相调用;支持在浏览器窗口的顶部添加一个原生的关闭按钮
tips
引擎画面、原生WebView、html5界面:引擎画面本身是一个原生窗口,WebView也是一个原生窗口,WebView叠加到引擎窗口之上,所以WebView会遮挡住引擎绘制的所有内容.
对于html5内容,就完全在WebView窗口之内.
此外,WebView支持在自己的顶部添加一个原生的按钮,这个按钮的位置可以超出WebView一半,如果是透明的图片,引擎画面会透过来,也可以是不超出WebView的区域,如下图:
![]()
基于这些特性,使用WebView有一些技巧: 对于非全屏的WebView,可以使用WebView提供的顶部关闭按钮.对于全屏WebView,既可以用上面这种关闭按钮,也可以用html5来实现顶部的返回或关闭按钮.不过如果用html5来实现关闭按钮的话,有可能html加载失败,此时按钮就无法显示了.
tips
引擎WebView和Html5/JS交互的分享: http://stackoverflow.oa.com/article/13
tips
视频格式支持:iOS支持H264, android 2.3+ 支持H264/WebM. 可用如下网站测试: http://www.quirksmode.org/html5/tests/video.html
tips
请注意WebView接口调用的限制:比如WebView对象的
enableCloseButton
和enableLoadingDialog
一旦被调用,该对象就不能取消关闭按钮或Loading对话框了。
tips
IOS8以上(WKWebView)的差异:IOS8以上,WebView的背景色会变为透明,请H5开发同学强制设置背景色.
IOS8以上,网页会显示的比较小,请在H5页面中控制页面显示大小,例如添加如下代码:
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" >
tips
win32平台支持IE9/IE10/IE11/chrome21,您可以在device.lua
中配置当前要使用哪一种浏览器
tips
存在这样的问题:用户点击网页中的编辑框时,如果编辑框太靠近下方,弹出的软键盘可能会遮挡编辑框.这将导致用户无法看到输入的内容.这个问题是系统原因造成,建议H5开发同学在布局的时候考虑这种情况.
https://code.google.com/p/android/issues/detail?id=5497
有一种解决方法是:当用户点击网页中的编辑框时,创建一个原生的编辑框,让用户在这个编辑框中输入.但这种方法需要先关闭再弹出软键盘,很卡,体验不好,所以没有采用此种方法.
![]()
API列表
WebView(x,y,width,height)
功能说明
创建WebView对象
x,y,width,height
类型为number
,屏幕坐标
返回值
WebView对象,是一个lua引用,在该引用被释放时,WebView对象也被销毁.
WebView.setRect(x,y,width,height)
功能说明
设置屏幕坐标,可以在WebView创建前后来设置WebView的位置和大小
x,y,width,height
类型为number
,屏幕坐标
返回值
无
WebView.setBackgroundColor(r,g,b)
功能说明
设置背景色. 缺省为透明. 此处设置网页加载完成之前的背景色,加载完成之后的背景色由网页自行设定. 在loadUrl
或loadFile
调用之前,调用本接口有效
r,g,b
类型为number
, 分别是红色、绿色、蓝色分量,取值 [ 0.0, 1.0 ]
返回值
无
支持平台
不支持win32平台.
WebView.loadUrl(stringUrl)
功能说明
加载一个网址,调用此接口后,WebView才在引擎画面上显示.可以对同一个WebView对象多次调用此接口加载不同url
stringUrl
类型为string
,网址,例如www.boyaa.com
返回值
无
此为异步接口
tips
iOS9+版本限制打开http网址,可参考NSAppTransportSecurity
相关说明
WebView.loadFile(basePath,fileName)
功能说明
加载一个本地网页文件,调用此接口后,WebView才在引擎画面上显示.可以对同一个WebView对象多次调用此接口加载不同内容
basePath
类型为string
,一般取值为sys_get_string("storage_inner_root")
代表与引擎的scripts image目录是同级目录
fileName
类型为string
,网页文件名
返回值
无
此为异步接口
备注
如果网页中包含图片或js脚本,图片和js请用相对路径;iOS平台要求图片和js必须位于当前网页的相同或子目录下.android平台可以加载apk中的网页文件,WebView内部首先会检查basePath+fileName组成的绝对路径的网页文件是否存在,如果不存在,就会忽略basePath并尝试加载apk中assets下的fileName文件. 比如要加载assets/html/help.html文件,需要将fileName写为html/help.html.
WebView.loadString(htmlString,baseUrl,encoding)
功能说明
加载一个字符串,调用此接口后,WebView才在引擎画面上显示.可以对同一个WebView对象多次调用此接口加载不同内容
htmlString
类型为string
baseUrl
类型为string
,网页中相对路径的baseUrl,可以为”“
encoding
类型为number
,固定为WebView.ENCODING_UTF8
返回值
无
此为异步接口
支持平台
baseUrl
参数在win32平台无效
WebView.enableLoadImage(type)
功能说明
设置仅在WIFI网络时下载图片,缺省不是.
type
类型为number
,取值为WebView.WIFI
或者WebView.ALL
返回值
无
支持平台
不支持win32平台,不支持iOS平台
WebView:close()
功能说明
关闭WebView窗口.在WebView显示之后,调用本接口有效
返回值
无
此为异步接口
WebView:setEvent(function)
功能说明
设置WebView的事件响应接口.在loadUrl
或loadFile
调用之前,调用本接口有效
function
函数声明为:onLoadEvent=function(cmd) --cmd取值为: --WebView.EVENT_LOAD_SUCCESS 网页加载成功 --WebView.EVENT_LOAD_FAILED 网页加载失败 --WebView.EVENT_CLOSE 用户点击WebView自带的关闭按钮或javascript调用native_close --WebView.EVENT_REFRESH 下拉更新事件,可在这个事件里重新加载网页 end
function
取值为nil
则会设置事件响应函数为空
返回值
无
支持平台
WebView.EVENT_REFRESH 不支持win32平台
WebView:setJsCallback(function)
功能说明
设置WebView的响应javascript调用的回调函数.在loadUrl
或loadFile
调用之前,调用本接口有效
function
函数声明为:onJsCall=function(stringData) --stringData是javascript传递的字符串 end
function
取值为nil
则会设置事件响应函数为空
返回值
无
WebView:callJs(funcName,stringData)
功能说明
调用javascript函数
funcName
类型为string
,javascript的函数名,是一个网页最顶层的全局javascript函数
stringData
类型为string
,传递给javascript函数的字符串参数
javascript的例子
<script type="text/javascript"> function webview_data_init(stringDataFromLua) { window.alert(stringDataFromLua); } </script> //WebView内置了4个javascript接口,javascript开发者可以使用这4个接口,声明如下: function native_call(stringData); function native_close(); function native_log(stringData); function native_close_loading(); //调用native_call(stringData)后,lua中onJsCall函数会响应 //调用native_close(),lua中会响应onLoadEvent(WebView.EVENT_CLOSE) //调用native_log(stringData),可以将stringData输出到lua日志相同的地方 //调用native_close_loading(),会关闭loading动画界面
lua的例子
myWeb:callJs("webview_data_init","json_data_from_http");
返回值
无
lua和javascript互相调用均为异步接口
WebView:enableCloseButton(pos,imagePath,width,height)
功能说明
在WebView顶部添加一个原生关闭按钮,在第一次loadUrl
或loadFile
调用之前,调用本接口有效.一旦调用过此接口,可以再次调用来修改参数,但无法禁用原生按钮.
pos
添加按钮的位置,取值为预定的值:WebView.TOP_LEFT
WebView.TOP_LEFT_INNER
是在左上角添加,WebView.TOP_RIGHT
WebView.TOP_RIGHT_INNER
是在右上角添加
imagePath
类型为string
,是图片(支持png和jpg)的完整路径,该图片将被加载并显示为关闭按钮
width
类型为number
,图片显示的宽度,单位为像素
height
类型为number
,图片显示的高度,单位为像素
返回值
无
WebView:enableLoadingDialog(imagePath,width,height,loadingText)
功能说明
允许WebView在网页加载期间显示一个loading动画界面.在第一次loadUrl
或loadFile
调用之前,调用本接口有效.一旦调用过此接口,可以再次调用来修改参数,但无法不显示loading动画.
imagePath
类型为string
,是图片(支持png和jpg)的完整路径,该图片将被加载并显示为动画
width
类型为number
,图片显示的宽度,单位为像素
height
类型为number
,图片显示的高度,单位为像素
loadingText
类型为string
,loading动画的文字提示,允许为”“
返回值
无
WebView:enableLoadingDialog2(imagePath,width,height,loadingText,closeTimeout)
功能说明
在enableLoadingDialog
基础上增加了 closeTimeout 参数, 允许延时关闭loading动画界面
closeTimeout
类型为number
,延时时长, 单位为毫秒
返回值
无
WebView:enableScrollBar(hScroll,vScroll)
功能说明
设置WebView是否显示水平滚动条和垂直滚动条,缺省仅显示垂直滚动条.在loadUrl
或loadFile
调用之前,调用本接口有效
hScroll
类型为boolean
,是否显示水平滚动条
vScroll
类型为boolean
,是否显示垂直滚动条
返回值
无
支持平台
win32(IE)平台上水平和垂直滚动条无法单独控制可见性,只能全部显示或全部隐藏.win32(chrome21)不支持滚动条的可见性控制(H5可以). IOS设置任一滚动条不显示,则水平和垂直滚动条都不显示.
WebView:enablePullRefresh(titleUp,titleDown,imagePathUp,imagePathDown,imageWidth,imageHeight,subTitle)
功能说明
允许用户下拉网页后刷新网页,例如:local imgPath = sys_get_string("storage_app_images"); local imageUp = imgPath.."common/arrow_up.png"; local imageDown = imgPath.."common/arrow_down.png"; web1:enablePullRefresh("下拉中...","松开刷新",imageUp,imageDown,64,64,"最后更新时间12:00:00"); --响应 WebView.EVENT_REFRESH 事件
返回值
无
支持平台
不支持win32平台
WebView:enableCache(enable)
功能说明
设置WebView是否优先使用缓存的网页(未过期的情况下),缺省是不缓存,在loadUrl
或loadFile
调用之前,调用本接口有效
enable
类型为boolean
,是否使用缓存
返回值
无
支持平台
IOS不支持Cache
WebView:enableBackKey(enable)
功能说明
设置android返回键是否令到WebView回退,缺省是false
.在loadUrl
或loadFile
调用之前,调用本接口有效
enable
类型为boolean
返回值
无
WebView:enableBackOrForward(enable)
功能说明
设置WebView是否允许回退、前进;只有允许之后,android的Back才可能回退,网页中(javascript)调用回退、前进功能才有效,缺省是false
.在loadUrl
或loadFile
调用之前,调用本接口有效
enable
类型为boolean
,是否支持回退、前进
返回值
无
WebView:setVisible(visible)
功能说明
设置WebView可见性,缺省是可见,注意:设置引擎节点与设置WebView的可见性,是不同步的.在loadUrl
或loadFile
调用之后,调用本接口有效
visible
类型为boolean
,是否可见
返回值
无
此为异步接口
AlertDialog(原生对话框)¶
简介
API列表
AlertDialog()
功能说明
创建AlertDialog对象
返回值
返回AlertDialog对象,是一个lua引用,在该引用被释放时,AlertDialog对象也被销毁.
AlertDialog:setTitle(title)
功能说明
设置标题,缺省为”“
title
类型为string
,标题
返回值
无
AlertDialog:setMessage(msg)
功能说明
设置显示内容,缺省为”“
msg
类型为string
,内容
返回值
无
AlertDialog:enableButton(idx,buttonText)
功能说明
启用内置的按钮,缺省包含一个按钮,按钮文字是”close”,最多支持2个按钮.
idx
预定义的按钮id,取值为:
AlertDialog.BUTTON_IDX_0
AlertDialog.BUTTON_IDX_1
buttonText
类型为string
,按钮上的文字
返回值
无
AlertDialog:show(function)
功能说明
显示对话框,非阻塞调用,创建并同时弹出多个AlertDialog是允许的
function
函数声明为:onAlertDialogClose=function(idx) --idx为用户点击的按钮id,取值为: --AlertDialog.BUTTON_IDX_0 --AlertDialog.BUTTON_IDX_1 end
function
可以为nil
返回值
无
此为异步接口
Toast(小提示)¶
简介
API列表
DeviceInfo(设备信息)¶
简介
API列表
DeviceInfo.getPlatform()
功能说明
获取平台类型
返回值
类型为string
,目前返回值包括android
ios
win32
线程支持
支持在任意线程中调用
DeviceInfo.getVersion()
功能说明
返回OS版本号
返回值
类型为string
, android平台返回的是android.os.Build.$VERSION.RELEASE,例如返回”4.2.2”; iOS平台返回的是[[UIDevice currentDevice] systemVersion],例如返回”9.3.2”; win32平台返回的是Win8.1 Win10等
线程支持
支持在任意线程中调用
DeviceInfo.getAppInfo(type);
功能说明
获取本应用的信息
type
支持的信息类型,取值为:
DeviceInfo.PACKAGE_NAME_OR_BUNDLE_ID
返回android的package name
或iOS平台的CFBundleIdentifier
DeviceInfo.VERSION_CODE_OR_BUNDLE_VERSION
返回android的versionCode
或iOS平台的CFBundleVersion
DeviceInfo.VERSION_NAME_OR_BUNDLE_SHORT_VERSION_STRING
返回android的versionName
或iOS平台的CFBundleShortVersionString
返回值
类型为string
, win32平台可以在device.lua
中配置
线程支持
支持在任意线程中调用
DeviceInfo.getUserAgent()
功能说明
获取浏览器user-agent
返回值
类型为string
, win32平台可以在device.lua
中配置
线程支持
支持在任意线程中调用
性能说明
首次调用此接口耗时往往在几十到几百毫秒
DeviceInfo.getUUID()
功能说明
返回一个通用唯一识别码 (Universally Unique Identifier)
返回值
类型为string
, android平台返回的是UUID.randomUUID(),每次调用此接口,都会重新生成一个值; iOS平台返回的是一个CFUUIDCreate生成的UUID,每次调用此接口,都会重新生成一个值; win32平台返回的是CoCreateGuid生成的GUID,每次调用此接口,都会重新生成一个值
线程支持
支持在任意线程中调用
性能说明
Android平台调用此接口耗时在几毫秒以上
DeviceInfo.getSerial()
功能说明
获取设备序列号(唯一标识)
返回值
类型为string
, android平台返回的是android.os.Build$SERIAL,例如:某手机返回的是”M9N7N15929003218”; win32平台返回主板的序列号
支持平台
不支持iOS平台
线程支持
支持在任意线程中调用
性能说明
Android平台调用此接口耗时在几毫秒
DeviceInfo.isVirtual()
功能说明
是否在模拟器上运行
返回值
类型为boolean
线程支持
支持在任意线程中调用
支持平台
不支持 android TV, win32平台可以在device.lua
中配置
DeviceInfo.isTablet()
功能说明
是否是平板
返回值
类型为boolean
线程支持
支持在任意线程中调用
支持平台
不支持 android TV, win32平台可以在device.lua
中配置
DeviceInfo.getName()
功能说明
获取设备用户名称(iOS->设置->通用->关于本机->名称, android是获取蓝牙的名称)
返回值
类型为string
, win32平台可以在device.lua
中配置
线程支持
支持在任意线程中调用
DeviceInfo.getModel()
功能说明
获取设备型号
返回值
类型为string
, android平台返回的是android.os.Build$MODEL,例如:华为Mate7手机返回的是”HUAWEI MT7-TL10”; iOS平台返回的是iPhone 6 Plus
iPad Air 2
iPad Pro 12.9-inch
等等, win32平台返回的是电脑型号
线程支持
支持在任意线程中调用
DeviceInfo.getBrand()
功能说明
获取品牌名
返回值
类型为string
, win32平台可以在device.lua
中配置
线程支持
支持在任意线程中调用
DeviceInfo.getManufacturer()
功能说明
返回制造商名称
返回值
类型为string
, android平台返回的是android.os.Build$MANUFACTURER,例如:华为手机返回的是”HUAWEI”; iOS平台返回的是”Apple”
线程支持
支持在任意线程中调用
DeviceInfo.getLocale()
功能说明
获取当前设置区域的语言
返回值
类型为string
, win32平台可以在device.lua
中配置
线程支持
支持在任意线程中调用
DeviceInfo.getCountry()
功能说明
获取当前设置的国家或地区
返回值
类型为string
, win32平台可以在device.lua
中配置
线程支持
支持在任意线程中调用
DeviceInfo.getTimeZone()
功能说明
获取当前时区
返回值
类型为string
, win32平台可以在device.lua
中配置
线程支持
支持在任意线程中调用
DeviceInfo.getStorageSize(type)
功能说明
获取总的存储空间大小,对于win32来说,是获取磁盘分区的大小,对于iOS来说,是获取机身存储的大小.
type
类型为number
,取值为DeviceInfo.INTERNAL
或者DeviceInfo.EXTERNAL
,对于win32和iOS来说,传这两个参数获取的结果是一样的,对于Android来说,DeviceInfo.INTERNAL
是获取机身存储的大小. 对于DeviceInfo.EXTERNAL
如果使用sd卡作为主外部存储,则获取的是sd卡的大小,否则是获取机身存储大小.如果使用引擎3.x向storage_outer_root
写文件前要判断存储空间是否够用,就要用DeviceInfo.EXTERNAL
.
返回值
类型为number
,单位为字节
线程支持
支持在任意线程中调用
DeviceInfo.getStorageAvailable(type)
功能说明
获取可用存储空间大小
type
类型为number
,取值为DeviceInfo.INTERNAL
或者DeviceInfo.EXTERNAL
返回值
类型为number
,单位为字节
线程支持
支持在任意线程中调用
MemoryInfo(内存信息)¶
简介
API列表
MemoryInfo.getMemoryInfo()
功能说明
实时获取内存信息
返回值
类型为table
, android 返回值为mem_info = { totalMem = 0, availMem = 0, threshold = 0, runtime={ maxMemory = 0, totalMemory = 0, freeMemory = 0} debug = { totalPss = 0, totalPrivateDirty = 0, totalSharedDirty = 0, dalvikPss = 0, dalvikPrivateDirty = 0, dalvikSharedDirty = 0, nativePss = 0, nativePrivateDirty = 0, nativeSharedDirty = 0, otherPss = 0, otherPrivateDirty = 0, otherSharedDirty = 0}}详情请参考:http://stackoverflow.oa.com/question/69
iOS 返回值为
mem_info = { physicalMemory = 0, wire_count = 0, active_count = 0, inactive_count = 0, free_count = 0, resident_size = 0}详情请参考:http://stackoverflow.oa.com/article/20
win32 返回值为
mem_info = { totalPhys = 7984279552, --RAM大小,8G availPhys = 2914562048, --操作系统中剩余的RAM 接近3G workingSetSize = 44417024 --当前进程已经使用的RAM 44M左右, 因为windows平台大量存在独立显存的显卡,此值不包含贴图. }
线程支持
支持在任意线程中调用
NativeDevice(设备相关功能)¶
简介
API列表
NativeDevice.Vibrate(ms)
功能说明
设备震动
ms
类型为number
,震动的时长,单位为毫秒,取值为0意为停止震动
返回值
无
支持平台
iPhone/iPod不支持ms
参数;iPad不支持此接口;部分android pad不支持此接口
NativeDevice.Beep()
功能说明
铃声
返回值
无
支持平台
iOS不支持此接口;部分android pad不支持此接口
NativeDevice.setScreenBrightness(level)
功能说明
设置屏幕亮度
level
类型为number
,level取值0.0~1.0,1.0屏幕最亮
返回值
无
平台差异
android平台上,设置亮度之后,不影响其他程序的屏幕亮度,重启游戏失效; iOS平台上,设置亮度后,不影响其他程序的屏幕亮度,重启游戏失效; windows平台上,设置亮度后,会改变整个屏幕亮度,影响到所有程序,重启电脑失效
已知问题
iOS平台在游戏切换到后台之后,如果玩家在系统设置或其他App中设置了亮度,下次游戏切换到后台之后,并不能恢复原样;
NativeDevice.keepScreenOn(enable)
功能说明
设置屏幕常亮并且不锁屏,缺省为NO
enable
类型为bool
返回值
无
NativeDevice.openUrl(url)
功能说明
用操作系统缺省浏览器打开一个网址
url
类型为string
url地址
返回值
无
NativeDevice.openDialer(phoneNumber)
功能说明
打开系统的电话拨号界面
phoneNumber
类型为string
电话号码
返回值
无
平台差异
win32平台为模拟界面
NativeDevice.openSms(phoneNumber,content)
功能说明
打开系统的短信发送界面
phoneNumber
类型为string
电话号码
content
类型为string
短信内容
返回值
无
平台差异
iOS平台不支持content
参数; win32平台为模拟界面
NetworkInfo(网络)¶
简介
API列表
NetworkInfo.getNetworkType()
功能说明
获取联网类型
返回值
返回值为预定义的值,取值为:
NetworkInfo.TYPE_MOBILE
移动网络;
NetworkInfo.TYPE_WIFI
WIFI;
NetworkInfo.TYPE_ETHERNET
以太网;
NetworkInfo.TYPE_UNKNOWN
未知
线程支持
支持在任意线程中调用
性能说明
Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时小于几毫秒
权限
Permissions.PHONE_STATE
NetworkInfo.getNetworkSubType()
功能说明
获取联网类型和子类型
返回值
返回值为预定义的值,取值为:
NetworkInfo.TYPE_2G
NetworkInfo.TYPE_3G
NetworkInfo.TYPE_4G
移动网络;
NetworkInfo.TYPE_WIFI
WIFI;
NetworkInfo.TYPE_ETHERNET
以太网;
NetworkInfo.TYPE_UNKNOWN
未知
线程支持
支持在任意线程中调用
性能说明
Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时小于几毫秒
权限
Permissions.PHONE_STATE
NetworkInfo.getNetworkTypeName()
功能说明
获取联网类型的名称
返回值
类型为string
支持平台
如果需要支持iOS平台的话,XCode设置中不要选中 “Hide status bar”
线程支持
支持在任意线程中调用
性能说明
Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时小于几毫秒
权限
Permissions.PHONE_STATE
NetworkInfo.getSSID()
功能说明
获取WIFI的名称,如果没有WIFI权限或未连接,则返回字符串长度为0
返回值
类型为string
支持平台
不支持win32
线程支持
支持在任意线程中调用
权限
Permissions.PHONE_STATE
NetworkInfo.getMNO()
功能说明
获取mobile network operator
的名称,也就是运营商的名称. 可能返回字符串长度为0
返回值
类型为string
支持平台
不支持win32
线程支持
支持在任意线程中调用
权限
Permissions.PHONE_STATE
NetworkInfo.isNetworkConnected()
功能说明
检查是否联网
返回值
类型为boolean
线程支持
支持在任意线程中调用
性能说明
Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时小于几毫秒
权限
Permissions.PHONE_STATE
NetworkInfo.isInternetConnected(ipOrHost,port,timeout)
功能说明
检查是否能连接到指定服务器
ipOrHost
类型为string
服务器ip地址或域名,例如"www.boyaa.com"
或"183.61.180.186"
.支持 IPV6
port
类型为number
端口号
timeout
类型为number
连接的超时时间,单位为毫秒. 如果ipOrHost
为域名的话, 此参数仅包含连接的超时时间, 不包括域名解析的超时时间. 所以推荐用 IP 地址.
返回值
类型为boolean
,连接成功返回true
线程支持
支持在任意线程中调用
性能说明
此接口为同步接口,耗时从几毫秒到几十秒,建议在ThreadPool线程中使用.
NetworkInfo.setNetworkConnectivityEvent(function)
功能说明
启用网络断开、连接的监控功能
function
函数声明为:onNetworkConnected=function(conn,subType) --conn取值为true/false --type取值为 network sub type --备注1: --conn和subType的值,是操作系统层在网络连通/断开时的值 --isNetworkConnected()/getNetworkSubType()获取的是当前的值. --应用层收到事件是有延迟的,所以,以上两者有可能不同. --备注2: --android手机wifi断开,然后4G连接,事件序列如下: -- onNetworkConnected ( false, TYPE_WIFI ) -- onNetworkConnected ( true, TYPE_4G ) --iPhone wifi断开,然后4G连接,事件序列如下: -- onNetworkConnected ( true, TYPE_4G ) --iPod wifi断开,事件序列如下: -- onNetworkConnected ( false, TYPE_UNKNOWN ) --备注3: --事件可能会重复发送,所以,可以通过与上一次的值的比较,来决定后续的动作. --监控网络发生变化的一般流程: --第一步:调用isNetworkConnected()/getNetworkSubType()获取当前的值conn1,subType1; --第二步:调用 setNetworkConnectivityEvent 启用网络监控 --第三步:在 onNetworkConnected 事件中,将conn1,subType1与conn,subType对比. end
function
为nil
意为停止(关闭)网络断开、连接的监控功能
返回值
无
平台差异
不支持win32
权限
Permissions.PHONE_STATE
PowerInfo(电力)¶
简介
API列表
PowerInfo.getBatteryValue()
功能说明
获取电池电量
返回值
类型为number
,调用成功的取值范围为[0.0~1.0],接近1.0为满电,失败为其他值.
线程支持
支持在任意线程中调用
性能说明
Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时在几毫秒
PowerInfo.isCharging()
功能说明
检查是否正在充电
返回值
类型为boolean
线程支持
支持在任意线程中调用
性能说明
Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时在几毫秒
PowerInfo.isPlug()
功能说明
检查是否连接插电设备
返回值
类型为boolean
线程支持
支持在任意线程中调用
性能说明
Android平台调用此接口耗时在几毫秒,iOS平台调用此接口耗时在几毫秒
PowerInfo.setChargingEvent(function)
功能说明
启用充电通知
function
函数声明为:onCharging=function(charging) --charging取值为true/false end
function
为nil
意为停止(关闭)充电通知
返回值
无
PowerInfo.setLowPowerEvent(function)
功能说明
启用连接插电设备通知
function
函数声明为:onLowPower=function(lowpower) --lowpower取值为true/false end
function
为nil
意为停止(关闭)插电设备通知
返回值
无
PowerInfo.setBatteryChangedEvent(function)
功能说明
启用电池电量信息监控
function
函数声明为:onBatteryChanged=function(level) --level取值同 getBatteryValue 的返回值 end
function
为nil
意为停止(关闭)通知
返回值
无
Sensor(传感器)¶
简介
API列表
Sensor.catchAccelerometer(function, hz)
功能说明
获取加速计数据,调用此接口后,加速计数据会源源不断通过function函数输出给lua,供lua代码处理,当程序切换到后台时加速计会暂停
function
函数声明为:onAccelerometerDataEvent=function(x,y,z,timestamp) --x,y,z是double类型,3个方向的加速度 --目前存在一个问题是:android和iOS设备的向上的方向是相反的 --timestamp是double类型,时间戳,单位是秒,但精度达到了微秒,取毫秒值则是timestamp*1000,微秒值是timestamp*1000*1000 end
function
取值为nil
则会设置失败
hz
类型为number
正整数,每秒种抓取加速计值的次数(大约的值,经过测试,不太精确),参数名hz是赫兹的缩写.还可以使用下面一些预置的常量:
Sensor.UPDATE_UI
值为15
Sensor.UPDATE_GAME
值为50
Sensor.UPDATE_FASTEST
值为100当然也允许设置为1000000以上的值,用于采集数据,不过这样比较耗电.
返回值
无
线程支持
阻塞函数,仅支持lua子线程中调用
支持平台
不支持win32,调用接口无效
Sensor.releaseAccelerometer()
功能说明
释放加速计
返回值
无
线程支持
阻塞函数,仅支持lua子线程中调用,包括调用Sensor.catchAccelerometer
的线程
支持平台
不支持win32,调用接口无效
Sensor.setShakeEvent(function, param)
功能说明
启用手机摇晃检测.每次当手机达到摇晃标准时,都回调function
一次
function
函数声明为:onShakeEvent=function() end
function
取值为nil
则会取消摇晃检测
param
摇晃检测的参数, 类型为 lua table, 如果设为nil
则取如下缺省值param = { samplePerSecond = 50, --每秒钟从加速计(指硬件)取值的次数 acceleration = 1.4, --重力加速度G的倍数,只有大于此值的加速计值,才会参与摇晃判定的运算 minInterval = 0.25, --执行摇晃判定的最小时间间隔,单位是秒 maxInterval = 0.5, --执行摇晃判定的最大时间间隔,单位是秒 samplePercent = 0.75 --采样的百分比,建议维持使用缺省值 }
返回值
无
支持平台
不支持win32,调用接口无效
Sensor.hasStepCounter()
功能说明
检测系统是否支持计步器
返回值
boolean
,有计步器则为true
支持平台
不支持win32,调用接口返回false
另外,pad设备一般没有计步器
Sensor.setStepCounterEvent(function)
功能说明
启用系统计步器
function
函数声明为:onStepCounterEvent=function(num) --num是自启用计步器起的步数, num的值具有不确定性 end
function
取值为nil
则会取消系统计步器
返回值
无
支持平台
不支持win32,调用接口无效
PopupLogger(弹出式日志窗口)¶
简介
API列表
PopupLogger.show(enable)
功能说明
显示或隐藏日志窗口
enable
类型为boolean
返回值
无
线程支持
支持在任意线程中调用
PopupLogger.clear()
功能说明
清空日志窗口中的日志内容
返回值
无
线程支持
支持在任意线程中调用
PopupLogger.logi( msg ); PopupLogger.logw( msg ); PopupLogger.logd( msg ); PopupLogger.loge( msg );
功能说明
用不同的颜色写日志
msg
类型为string
日志内容
返回值
无
线程支持
支持在任意线程中调用
支持平台
win32平台不支持多种颜色
AudioRecorder(录音)¶
简介
API列表
AudioRecorder.getSupportFormat()
功能说明
获取当前设备支持的录音格式
返回值
类型为array
,数组中包含多个table
,每个的格式如下:params[1] = { sampleRate=44100, channels=1,bitsPerSample=16,minBufferSize=1024 }; sampleRate是采样频率,单位是赫兹;channels是声道数;bitsPerSample是位数;minBufferSize是最小缓冲区大小,单位为字节; 支持8位/16位采样,采样值是8位/16位带符号整数.
线程支持
支持在任意线程中调用
权限
Permissions.RECORD_AUDIO
AudioRecorder.rawStart(param)
功能说明
用指定数据格式,开始录音
param
类型为table
是用getSupportFormat函数取得,其中只有minBufferSize允许修改,且只能乘以2的N次方
返回值
类型为boolean
,成功为true
线程支持
支持在任意线程中调用
权限
Permissions.RECORD_AUDIO
AudioRecorder.rawPause()
功能说明
暂停
返回值
无
线程支持
支持在任意线程中调用
支持版本
4.0以上
权限
Permissions.RECORD_AUDIO
AudioRecorder.rawIsPause();
功能说明
返回是否处于暂停状态
返回值
类型为boolean
线程支持
支持在任意线程中调用
支持版本
4.0以上
权限
Permissions.RECORD_AUDIO
AudioRecorder.rawResume()
功能说明
恢复
返回值
无
线程支持
支持在任意线程中调用
支持版本
4.0以上
权限
Permissions.RECORD_AUDIO
AudioRecorder.rawRead()
功能说明
同步读取录音数据,会读取minBufferSize大小的数据流并返回,也可能返回nil
或长度小于minBufferSize. rawRead返回的是录音设备提供的未经处理的数据流,应用层需要考虑消除噪音、回响等.如果在rawStart时设置的minBufferSize过大,那么系统录音设备会录制很久才能填满minBufferSize,会导致rawRead阻塞很久,流式语音就会产生较大延迟.如果CPU处理不及时,也会导致延迟.
返回值
类型为binary
线程支持
支持在任意线程中调用
权限
Permissions.RECORD_AUDIO
AudioRecorder.rawStop()
功能说明
停止录音
返回值
无
线程支持
支持在任意线程中调用
权限
Permissions.RECORD_AUDIO
AudioRecorder.rawIsStop()
功能说明
返回是否处于停止状态
返回值
类型为boolean
线程支持
支持在任意线程中调用
权限
Permissions.RECORD_AUDIO