在线咨询
QQ交流群
微信公众号

Class: App

THING~ App

App ThingJS 库入口,提供加载场景、搜索、事件绑定、摄像机控制等功能


new App(options) → {App}

构建方法

Parameters:
Name Type Description
options Object

参数列表

Properties
Name Type Description
url String

初始场景资源路径

background Number

背景颜色或图片

skyBox String

天空盒资源名称

complete function

初始化完成的函数回调

Returns:

程序集对象

Type
App
Example
// 仅初始化 3D 应用
var app=new THING.App();
// 初始化 3D 应用,并加载场景
var app = new THING.App({
  url: 'https://www.thingjs.com/static/models/storehouse'// 场景地址
});
// 设置天空盒
var app = new THING.App({
  url: 'https://www.thingjs.com/static/models/storehouse',// 场景地址
  skyBox:'BlueSky'
});
// 设置背景图片
var app = new THING.App({
  url: 'https://www.thingjs.com/static/models/storehouse',// 场景地址
  background: 'http://www.thingjs.com/static/images/background_img_03.png'
});

Members


background :String|Number

背景颜色或者图片, 参数为RGB颜色值 或 十六进制颜色值 或 图片资源路径

Type:
  • String | Number
Example
app.background = 0xFF00FF;
app.background = '#FF00FF';
app.background = 'rgb(255,0,255)';
app.background = 'http://www.thingjs.com/static/images/background_img_03.png'

camera :THING.CameraController

获取摄像机

Type:

currentFrameCount :Number

获取从 3D 启动以来一共渲染了多少帧

Type:
  • Number

deltaTime :Number

获取距上一帧流逝的时间(毫秒)

Type:
  • Number

elapsedTime :Number

获取从 3D 启动到现在流逝的时间(毫秒)

Type:
  • Number

fog :Object

设置雾参数

Type:
  • Object
Properties:
Name Type Description
options.color Number

雾颜色数值

options.far Number

设置远距离的雾效浓度

options.near Number

设置近距离的雾效浓度

Example
// 具体参数调节以及效果调整可使用「工具」——>「场景效果」——>「雾」生成代码块
// 线性雾
app.fog = {color: 0x888888, near: 1, far: 100};
// 清除雾
app.fog = null;

isMobileDevice :boolean

判断是否为移动端设备

Type:
  • boolean

keepBackgroundAspect :Boolean

是否保持背景图片的长宽比

Type:
  • Boolean
Default Value:
  • true
Example
app.keepBackgroundAspect = true;

level :THING.SceneLevel

获取场景层次管理器

Type:

lighting :Object

设置灯光参数

Type:
  • Object
Properties:
Name Type Description
options.showHelper Boolean

是否显示辅助线

options.ambientLight Object

环境光

Properties
Name Type Description
intensity Number

环境光强度

color Number

环境光颜色

options.mainLight Object

主灯光

Properties
Name Type Description
intensity Number

主灯光强度

color Number

主灯光颜色

alpha Number

主灯光角度

beta Number

主灯光角度

options.secondaryLight Object

第二光源

Properties
Name Type Description
intensity Number

第二光源强度

color Number

第二光源颜色

alpha Number

第二光源角度

beta Number

第二光源角度

options.tertiaryLight Object

第三光源

Properties
Name Type Description
intensity Number

第三光源强度

color Number

第三光源颜色

alpha Number

第三光源角度

beta Number

第三光源角度

Example
// 具体参数调节以及效果调整可使用「工具」——>「场景效果」——> 「灯光配置」生成代码块
app.lighting = {
  showHelper: false, // 灯光标示
  ambientLight: {
    intensity: 0.5,
    color: 0xffffff
  },
  hemisphereLight: {
    intensity: 0.0,
    color: 0xffffff,
    groundColor: 0x222222
  },
  mainLight: {
    // If enable shadow of main light.
    shadow: false,
    // Quality of main light shadow. 'low'|'medium'|'high'|'ultra'
    shadowQuality: 'high',
    // Intensity of main light
    intensity: 0.5,
    // Color of main light
    color: 0xffffff,
    // Alpha is rotation from bottom to up.
    alpha: 30,
    // Beta is rotation from left to right.
    beta: 30
  },
  secondaryLight: {
    shadow: false,
    shadowQuality: 'high',
    intensity: 0,
    color: 0xffffff,
    alpha: 138,
    beta: 0
  },
  tertiaryLight: {
    shadow: false,
    shadowQuality: 'high',
    intensity: 0,
    color: 0xffffff,
    alpha: 0,
    beta: 0
  }
};

pixelRatio :Number

设置/获取像素比 默认为1,可设置为0-1之间的数值 数值越大,渲染效果越清晰(帧率降低), 数值越小,渲染效果越模糊(帧率提高) 在移动设备上,为了渲染帧率,可将 app.pixelRatio 设置成小于1的值

Type:
  • Number
Example
app.pixelRatio = 0.8

postEffect :Object

设置后期处理参数

Type:
  • Object
Properties:
Name Type Description
options.temporalSuperSampling Object

超采样(场景静止时起作用)

Properties
Name Type Description
enable boolean
size Number

采样的帧数,帧数越多,收敛速度越慢

options.postEffect Object

后期处理

Properties
Name Type Description
enable boolean
options.bloom Object

泛光(会影响天空盒)

Properties
Name Type Description
enable boolean
strength Number

泛光强度

radius Number

泛光半径

threshold Number

泛光阈值

options.screenSpaceAmbientOcclusion Object

屏幕空间环境光遮蔽(相对昂贵的性能开销)

Properties
Name Type Description
enable boolean
radius Number

采样半径

quality Number

采样等级

intensity Number

环境光遮蔽强度

temporalFilter Number

使用temporal超采样时起作用,柔化采样效果

ignoreTransparent boolean

忽略透明物体

options.colorCorrection Object

颜色调整

Properties
Name Type Description
enable boolean
exposure Number

曝光

brightness Number

亮度

contrast Number

对比度

saturation Number

饱和度

options.vignette Object

光晕效果

Properties
Name Type Description
enable boolean
type String

光晕类型:目前支持 'color', 'blur' 两种模式,默认为 'blur'

color Number

光晕颜色:只在 color 模式下生效,默认 0x000000

offset Number

光晕从边缘到中心的渐变偏移值,范围推荐 0-8,默认为 1.5

options.FXAA Object

快速近似抗锯齿,性能优于MASS

Properties
Name Type Description
enable boolean
options.MSAA Object

多重采样抗锯齿(只在支持WebGL2.0的浏览器中可用)

Properties
Name Type Description
enable boolean
resetOther? boolean

是否重置其它未设置的后期处理配置,默认为false,会保持当前的设置状态

Example
// 具体参数调节以及效果调整可使用「工具」——>「场景效果」——>「后期设置」生成代码块
// 后期处理
app.postEffect = {
  // If enable post effects.
  enable: false,
  // Configuration about bloom post effect
  // 泛光(会影响天空盒)
  bloom: {
    // If enable bloom
    enable: false,
    // Intensity of bloom
    // 泛光强度
    strength: 0.14,
    // radius of bloom
    // 泛光半径
    radius: 0.4,
    // threshold of bloom
    // 泛光阈值
    threshold: 0.7
  },
  // Configuration about screen space ambient occulusion
  // 屏幕空间环境光遮蔽(相对昂贵的性能开销)
  screenSpaceAmbientOcclusion: {
    // If enable SSAO
    enable: false,
    // Sampling radius in work space.
    // Larger will produce more soft concat shadow.
    // But also needs higher quality or it will have more obvious artifacts
    // 采样半径
    radius: 0.2,
    // Quality of SSAO. 'low'|'medium'|'high'|'ultra'
    // 采样等级
    quality: 'medium',
    // Intensity of SSAO
    // 环境光遮蔽强度
    intensity: 0.8,

    // temporal filter in temporal super sampling mode
    // 使用temporal超采样时起作用,柔化采样效果
    temporalFilter: true,

    // if ignore transparent objects
    // 忽略透明物体
    ignoreTransparent: false
  },
  // Configuration about color correction
  // 颜色调整
  colorCorrection: {
    // If enable color correction
    enable: false,
    // 曝光
    exposure: 0,
    // 亮度
    brightness: 0,
    // 对比度
    contrast: 1,
    // 饱和度
    saturation: 1,
    // 伽马矫正
    gamma: 1
  },
  // Configuration about FXAA
  // fxaa 抗锯齿
  FXAA: {
    // If enable FXAA
    enable: false
  },
  // Configuration about MSAA
	 // msaa 抗锯齿
	 MSAA: {
	   // If enable MSAA
	   // only support by WebGL2.0
	   enable: true
	 }
};

root :THING.SceneRoot

获取场景根节点

Type:

skyBox :String

设置天空盒 目前提供了几个内置的天空盒, 分别是'BlueSky'、'MilkyWay'、'Night'和'SunCloud' 还可以使用自定义的天空盒贴图来,详见下面的例子 注意: 图片的宽高比必须1:1, 并且每张图片大小必须一致

Type:
  • String
Example
// 使用内置天空盒
app.skyBox = 'SunCloud';
// 设置自定义天空盒
app.skyBox = {
  up: './images/Night/posy.jpg',
  rt: './images/Night/negx.jpg',
  lf: './images/Night/posx.jpg',
  fr: './images/Night/negz.jpg',
  dn: './images/Night/negy.jpg',
  bk: './images/Night/posz.jpg'
};
// 设置自定义天空盒
app.skyBox = {
  negx: './images/Night/negx.jpg',
  negy: './images/Night/negy.jpg',
  negz: './images/Night/negz.jpg',
  posx: './images/Night/posx.jpg',
  posy: './images/Night/posy.jpg',
  posz: './images/Night/posz.jpg'
};
// 设置自定义天空盒(顺序要求[posx, negx, posy, negy, posz, negz])
app.skyBox = [
  './images/Night/posx.jpg',
  './images/Night/negx.jpg',
  './images/Night/posy.jpg',
  './images/Night/negy.jpg',
  './images/Night/posz.jpg',
  './images/Night/negz.jpg'
];

skyEffect :Object

设置动态天空效果,自带两个光源:一个用于模拟太阳的直射光源与模拟散射的半球光源。

Type:
  • Object
Properties:
Name Type Description
options.time Number

时间

options.beta Number

角度

options.turbidity Number

混浊度

options.rayleigh Number

瑞利散射

options.mieCoefficient Number

散射系数

options.mieDirectionalG Number
Example
// 具体参数调节以及效果调整可使用「工具」——>「场景效果」——>「动态天空」生成代码块
app.skyEffect = {
  time: 9,
  beta: 45,
  turbidity: 10,
  rayleigh: 1.5,
  luminance: 1,
  mieCoefficient: 0.005,
  mieDirectionalG: 0.98
};

Methods


addControl(ctrl, name?)

添加控件

Parameters:
Name Type Description
ctrl Object

控件对象

name? String

控件自定义名称(用于查找、获取)

Example
var ctrl = app.addControl(new THING.WalkControl(),'第一人称行走控件');

captureScreenshot(fileName)

将当前 3D 渲染内容截屏保存到指定文件中, 保存目录为浏览器下载目录(请保证具有写入权限)。

Parameters:
Name Type Description
fileName String

文件名称

Example
// 将3D渲染的画面保存成 myScreenshot.jpg 下载至浏览器默认文件下载目录
app.captureScreenshot('myScreenshot');

captureScreenshotToImage(width?, height?, extension?, quality?) → {Object}

将当前 3D 渲染内容截屏保存到缓冲区中

Parameters:
Name Type Description
width? Number

图片宽度

height? Number

图片高度

extension? String

文件类型, 默认 jpeg 类型

quality? Number

质量(0~1]之间

Returns:

base64 编码图片数据

Type
Object
Example
var base64 = app.captureScreenshotToImage(1024, 768, 'png', 0.5);
var img = new Image()
img.src = base64;

create(type, id, name, url, position, complete) → {THING.BaseObject}

创建物体

Parameters:
Name Type Description
type String

物体类型

id Number | String

物体 ID,可通过 THING.Utils.generateUUID() 生成唯一标识

name String

物体名称

url String

模型资源地址(Thing)/图片资源地址(Marker)/页面资源地址(WebView)

position Array.<Number>

物体在世界坐标系下的位置

complete function

物体加载完成后的回调函数

Returns:
Type
THING.BaseObject
Example
// type:'Thing'
var truck = app.create({
  type: 'Thing',
  id: 'myCar01',
  name: 'truck',
  url: 'https://speech.uinnova.com/static/models/truck/',
  position: [-5, 0, 0],
  complete: function() {
    console.log('truck created!');
  }
});
// type:'UIAnchor';
var ui = app.create({
  type: 'UIAnchor',
  element: domElement, // 界面的dom元素
  parent: parent, // 界面的父物体(位置跟随父物体更新)
  localPosition: [0,0,0], // 相对父物体的偏移
  pivot: [0,0.5], // 界面轴心
});
// type:'Marker';
var marker = app.create({
  type: "Marker",
  id: "myMarker01",
  url: "https://speech.uinnova.com/static/images/warning1.png",
  position: [0, 5, 0],
  size: 4
});
// type:'WebView';
var webView = app.create({
  type: 'WebView',
  id: 'myWebView01',
  url: 'https://www.thingjs.com',
  position: [0, 0, 0],
  width: 1920 * 0.01, // 3D 中实际宽度 单位 米
  height: 1080 * 0.01, // 3D 中实际高度 单位 米
  domWidth: 1920, // 页面宽度 单位 px
  domHeight: 1080 // 页面高度 单位 px
});
// type:'Box';
var box = app.create({
  type: 'Box',
  width: 1.0, // 宽度
  height: 1.0, // 高度
  depth: 1.0, // 深度
  widthSegments: 1.0, //宽度上的节数
  heightSegments: 1.0, // 高度上的节数
  depthSegments: 1.0, // 深度上的节数
  center: 'Bottom', // 中心点
  style: {
    color: '#ffffff',
    opacity: 0.8,
    image: 'images/uv.jpg'
  }
});
// type:'Sphere';
var sphere = app.create({
  type: 'Sphere',
  radius: 1,
  widthSegments: 12,
  heightSegments: 12,
  position: [2, 0, 0],
  style: {
    image: 'images/uv.jpg'
  }
});
// type:'Plane';
var plane = app.create({
  type: 'Plane',
  width: 2,
  height: 1,
  position: [0, 1, 0],
  style: {
    doubleSide: true,
    image: 'images/uv.jpg'
  }
});
// type:'Cylinder';
var plane = app.create({
  type: 'Cylinder',
  radius: 0.4,
  height: 1.6,
  position: [0, 0, 2]
});
// type:'Tetrahedron';
var t = app.create({
  type: 'Tetrahedron',
  radius: 1,
  position: [2, 0, 2]
});
// 另外,可通过 THING.factory.registerClass(类型名称, 类) 来扩展物体类型
// 注册自定义类
THING.factory.registerClass('Car', Car);

focus()

使 3D 窗口获得焦点

Example
app.focus();

getCampusJSON(url, params) → {Object}

请求场景数据,请求成功后以 JSON 结构返回 主要用途是查询未加载或者准备加载的场景数据。

Parameters:
Name Type Description
url String

场景路径

params Object

参数列表

Properties
Name Type Description
disableCache? Boolean

是否禁用缓冲数据,默认 false 。如果禁用,每次都请求最新的场景数据

complete? function

请求数据成功时的回调函数

error? function

请求数据失败时的回调函数

Returns:
Type
Object
Example
app.getCampusJSON('https://www.thingjs.com/static/models/storehouse', {
  complete: function (ev) {
    var result = ev;
    var children = result.children;
    for (var i = 0; i < children.length; i++) {
      var child = children[i];
      console.log(child.name)
    }
  }
});

getControl(name) → {Object}

根据名字获取控件

Parameters:
Name Type Description
name String

控件自定义名称

Returns:

控件对象

Type
Object
Example
var ctrl = app.getControl('第一人称行走控件');

hasControl(ctrl) → {Boolean}

判断是否已添加了某控件

Parameters:
Name Type Description
ctrl Object | String

控件对象 或 控件自定义名称

Returns:
Type
Boolean
Example
app.hasControl('第一人称行走');

isKeyPressed(key) → {Boolean}

判断某按键是否按下

Parameters:
Name Type Description
key number

键值

Returns:
Type
Boolean

off(eventType, condition, callback)

移除事件绑定

Parameters:
Name Type Description
eventType String

事件类型名称

condition String

物体类型选择条件

callback function | String

事件触发的回调函数 或 事件标签(tag)

Example
// 移除所有 Click 事件的绑定
app.off('click');
// 移除对场景中 Thing 类型物体的 Click 事件绑定
app.off('click','.Thing');
// 移除标记为某个事件标签的事件绑定,如果绑定(on)时没写条件,则第二个参数需填写 null
app.off('click','.Thing','我的点击事件01')
app.off('click',null,'我的点击事件02')

on(eventType, condition?, userData?, callback, tag?, priority?)

全局绑定事件

Parameters:
Name Type Description
eventType String

事件类型名称

condition? String

物体类型选择条件

userData? Object

事件传递自定义数据

callback function

事件触发的回调函数

tag? String

事件标签

priority? Number

优先级(默认值 50 ),数值越大优先级越高,越先响应

Example
// 绑定 Click 事件
app.on('click',function(ev){
  console.log(ev.object.name);
})
// 给场景中所有 Thing 类型对象,绑定 Click 事件
app.on('click','.Thing',function(ev){
  console.log(ev.object.name);
})
// 设置事件标签 tag
app.on('click','.Thing',function(ev){
  console.log(ev.object.name);
},'我的点击事件01');
// 设置事件优先级
app.on('click',function(ev){
  console.log(ev.object.name);
},'我的点击事件02',51)
// 填写 userData 传递参数
app.on('click', { color: '#ff0000' }, function (ev) {
  var color = ev.data.color;
  console.log(color)
});

one(eventType, condition, userData, callback, tag?, priority?)

绑定事件(只触发一次)

Parameters:
Name Type Description
eventType String

事件名称

condition String

物体类型选择条件

userData Object

事件绑定自定义数据

callback function

事件触发的回调函数

tag? String

事件标签

priority? Number

优先级(默认值 50 ),数值越大优先级越高,越先响应

Example
app.one('click', '.Building', function(ev) {...});
app.one('click', '.Thing', {color:'#ff0000'}, function(ev) {...});
app.one('update', function(ev) {...});

pauseEvent(eventType, condition, tag?)

暂停事件响应

Parameters:
Name Type Description
eventType String

事件名称

condition String

物体类型选择条件

tag? String

事件标签

Example
// 暂停系统内置的左键双击进入下一层级操作
app.pauseEvent(THING.EventType.DBLClick, '*', THING.EventTag.LevelEnterOperation);
// 暂停系统内置的右键单击返回上一层级操作
app.pauseEvent(THING.EventType.Click, null, THING.EventTag.LevelBackOperation);
// 暂停进入物体层级默认操作行为
app.pauseEvent(THING.EventType.EnterLevel, '.Thing', THING.EventTag.LevelSceneOperations);
// 暂停退出物体层级默认操作行为
app.pauseEvent(THING.EventType.LeaveLevel, '.Thing', THING.EventTag.LevelSceneOperations);
// 暂停进入物体层级的默认飞行行为
app.pauseEvent(THING.EventType.EnterLevel, '.Thing', THING.EventTag.LevelFly);
// 暂停进入物体层级的默认背景设置操作
app.pauseEvent(THING.EventType.EnterLevel, '.Thing', THING.EventTag.LevelSetBackground);
// 暂停给物体绑定的 Click 事件操作
app.pauseEvent('click','.Thing','我的点击事件01')

query(param) → {THING.Selector}

物体查询

Parameters:
Name Type Description
param String

查询条件

Returns:

查询结果

Type
THING.Selector
Example
// 查询 id 为 001 的对象集合
app.query('#001');
// 查询名称为 car01 的对象集合
app.query('car01');
// 查询类型为 Thing 的对象集合
app.query('.Thing');
// 查询自定义属性 [prop=value] 的对象集合
app.query('["userData/power"=60]');
// 根据正则表达式匹配 name 中包含 'car' 的子物体
app.query(/car/);
// 上行代码等同于
// var reg = new RegExp('car');
// var cars=app.query(reg);

// 注意:
// 通过 query 查询的结果都是满足条件的对象集合(Selector)
// 如需访问单个对象,可通过下标获取,如
var obj=app.query('#001')[0];
// 也可通过循环遍历对象集合
var objs=app.query('.Thing');
objs.forEach(function(obj){
  console.log(obj.name)
})

removeControl(ctrl)

删除控件

Parameters:
Name Type Description
ctrl Object | String

控件对象 或 控件自定义名称

Example
// 删除控件
app.removeControl(ctrl);
// 根据控件自定义名称删除控件
app.removeControl('第一人称行走控件');

resumeEvent(eventType, condition, tag?)

恢复事件响应

Parameters:
Name Type Description
eventType String

事件名称

condition String

物体类型选择条件

tag? String

事件标签

Example
// 恢复系统内置的左键双击进入下一层级操作
app.resumeEvent(THING.EventType.DBLClick, '*', THING.EventTag.LevelEnterOperation);
// 恢复系统内置的右键单击返回上一层级操作
app.resumeEvent(THING.EventType.Click, null, THING.EventTag.LevelBackOperation);
// 恢复进入物体层级默认操作行为
app.resumeEvent(THING.EventType.EnterLevel, '.Thing', THING.EventTag.LevelSceneOperations);
// 恢复退出物体层级默认操作行为
app.resumeEvent(THING.EventType.LeaveLevel, '.Thing', THING.EventTag.LevelSceneOperations);
// 恢复进入物体层级的默认飞行行为
app.resumeEvent(THING.EventType.EnterLevel, '.Thing', THING.EventTag.LevelFly);
// 恢复进入物体层级的默认背景设置操作
app.resumeEvent(THING.EventType.EnterLevel, '.Thing', THING.EventTag.LevelSetBackground);
// 恢复给物体绑定的 Click 事件操作
app.resumeEvent('click','.Thing','我的点击事件01')

saveFile(fileName, data)

保存文件到浏览器下载目录(请确保具有写权限)

Parameters:
Name Type Description
fileName String

文件名称

data String

文件数据

Example
var json = { 'name': 'ThingJs', 'time': '2019' };
app.saveFile('test.json',JSON.stringify(json))

trigger(eventType, condition?, ev?)

触发事件

Parameters:
Name Type Description
eventType String

事件名称

condition? String

物体类型选择条件

ev? Object

事件信息,传递回调参数

Example
// 触发自定义的告警事件
app.trigger('Alarm');
app.on('Alarm',function(){  })
// 传递参数
app.trigger('Alarm','.Thing',{level:2});
app.on('Alarm','.Thing',function(ev){
  console.log(ev.level)
})