base-three
threejs基本封装
使用说明
安装
npm install base-three
# OR
yarn add base-three
BaseThree
BaseThree对threejs做了初始化封装，并添加了动画、事件等其他逻辑封装，并在window上挂载了THREE和TWEEN属性。
示例
import BaseThree from 'base-three';
// OR
import { BaseThree } from 'base-three';
// 挂载
const threeIns = new BaseThree('#app', {
// options
});
// 卸载
threeIns.dispose();
参数
| 参数 | 类型 | 描述 |
|---|
| element | String|HTMLElement | 挂载元素，选择器或者 dom 元素 |
| options | Object | 配置项 |
options
| 属性 | 类型 | 默认值 | 描述 |
|---|
| debug | Boolean | false | 开启调试 |
| backgroundColor | String | 0x000000 | 背景色 |
| interactive | Boolean | false | 开启交互 |
| css2DRenderer | Boolean | false | 开启 CSS2DRenderer |
| css3DRenderer | Boolean | false | 开启 CSS3DRenderer |
| camera | Object | 见下方 | 相机配置 |
| controls | Object | 见下方 | 控制器 |
| stats | Object | 见下方 | 监控器 |
| axes | Object | 见下方 | 坐标轴 |
camera
| 属性 | 类型 | 默认值 | 描述 |
|---|
| fov | Number | 45 | 相机视角 |
| near | Number | 0.1 | 相机近距 |
| far | Number | 1000 | 相机远距 |
| position | Number | 0, 10, 15 | 相机位置 |
controls
| 属性 | 类型 | 默认值 | 描述 |
|---|
| visible | Boolean | true | 开启控制器 |
| enableDamping | Boolean | true | 启用惯性 |
以及OrbitControls的其他参数。
stats
| 属性 | 类型 | 默认值 | 描述 |
|---|
| visible | Boolean | true | 开启监控器 |
注意：监控器只在调试模式下显示。
axes
| 属性 | 类型 | 默认值 | 描述 |
|---|
| visible | Boolean | true | 开启坐标轴 |
| size | Number | 1 | 坐标轴尺寸 |
注意：坐标轴只在调试模式下显示。
实例方法
| 名称 | 返回值 | 备注 |
|---|
| addModel(\model) | | 添加模型，挂载模型的动画和事件 |
| dispose | | 销毁实例 |
注意：模型为BaseModel实例，BaseModel见下方。
BaseModel
BaseModel为模型基类，通过继承使用。该类继承了tiny-emitter事件库。
示例
import { BaseModel } from 'base-three';
class Model extends BaseModel {
constructor(options) {
super();
this.options = {
size: 1,
...options,
};
this.#init();
}
#init() {
// ...
// 添加3D对象
const mesh = new THREE.Mesh(geometry, material);
this.object.add(mesh);
// 3D对象绑定事件
this.listen(mesh, 'mousemove', (intersects) => {
const obj = intersects[0]?.object;
// ...
// 自定义事件，tiny-emitter提供支持
this.emit('model:active', '123');
});
// 添加动画
const tween = new TWEEN.Tween(texture.offset, this.tweenGroup).to({ x: -1 }, 3 * 1000).repeat(Infinity);
this.tweenList.push(tween);
}
}
const model = new Model({});
threeIns.scene.add(model.object);
threeIns.addModel(model);
model.start();
实例属性
| 属性 | 类型 | 描述 |
|---|
| tweenGroup | TWEEN.Group | 动画分组 |
| tweenList | Array | 动画列表 |
| listener | Object | 监听事件 |
| object | THREE.Group | three 分组 |
| disposed | Boolean | 是否销毁 |
实例方法
| 名称 | 返回值 | 备注 |
|---|
| listen(\obj, \name, \handler) | | 给 three 3D 对象绑定事件，支持mousemove和click事件 |
| tick(\time, \delta) | | 动画钩子，每帧触发，可更新动画 |
| start() | | 开启动画 |
| stop() | | 停止动画 |
| dispose() | | 销毁实例 |
Label
Label为html标签类，使用该功能需在BaseThree中开启CSS2DRenderer或CSS3DRenderer渲染器。
示例
import { Label } from 'base-three';
// ...
const label = new Label({
html: labelEl,
position: position,
});
scene.add(label);
参数
options
| 属性 | 类型 | 默认值 | 描述 |
|---|
| renderer | String | 3d | 渲染器类型，2d、3d |
| faceToCamera | Boolean | true | 是否始终朝向相机，只在 3d 模式生效 |
| scale | Number | 0.05 | 3d 渲染器下的缩放 |
| position | Array | 0, 0, 0 | 标签位置 |
| html | HTMLElement | null | 标签 dom 元素 |
WallGeometry
WallGeometry可根据path路径生成墙面几何体。
示例
import { WallGeometry } from 'base-three';
const geometry = new WallGeometry({
path: [
[0, 0],
[1, 0],
[2, 0],
],
height: 1,
});
// ...
const mesh = new THREE.Mesh(geometry, material);
scene.add(mesh);
参数
| 参数 | 类型 | 描述 |
|---|
| path | Array | 墙面路径，[0, 0, 1, 0, ...]、[0, 0, 1, 1, 0, 2, ...] |
| height | Number | 墙面高度，二维 path 必须设置高度；三维 path 可选，如果设置了将作为基础高度 |
ResourceTracker
ResourceTracker用于资源跟踪与销毁。
示例
import { ResourceTracker } from 'base-three';
const tracker = new ResourceTracker();
// 添加
tracker.add(mesh);
// 移除
tracker.remove(mesh);
// 销毁
tracker.dispose(mesh);
// 销毁所有
tracker.disposeAll();
实例方法
| 名称 | 返回值 | 备注 |
|---|
| add(\resource) | | 添加 |
| remove(\resource) | | 移除 |
| dispose(\resource) | | 销毁 |
| disposeAll() | | 销毁所有 |
utils
utils里提供了一些使用方法。
示例
import { loadTexture, assignUVs, getProjection, log } from 'base-three';
// 加载纹理资源，同时设置colorSpace
const texture = loadTexture(url);
// 矫正几何体UV属性值，一般用于shape贴图
assignUVs(geometry);
// 将经纬度转为threejs坐标，参数为分区geojson数据和相对大小（用于控制缩放，默认40）
const projection = getProjection(boundData, baseSize);
const [x, y] = projection([lng, lat]);
// 封装的带标签的console.log
log('test');