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(<BaseModel>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(<Object3D>obj, <String>name, <Function>handler) | | 给 three 3D 对象绑定事件，支持mousemove和click事件 | | tick(<Number>time, <Number>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 | Object | 配置项 |

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(<Object3D>resource) | | 添加 | | remove(<Object3D>resource) | | 移除 | | dispose(<Object3D>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');