API

init

快速初始化，并返回相机、场景、渲染器等对象和添加鼠标控制、获取鼠标点击对象等方法

示例

import lec3d from "@trickle/lec3d";
const { scene, renderer, camera, mountTo, refresh, addControls } = lec3d.init({
  axesHelperConfigs: {
    length: 10000,
  },
});

mountTo(yourElement);

参数

• params: 配置项，所有内容都是可选的，具体定义如下:

type InitParams = {
  /** 光照配置 */
  lightConfigs?: {
    // 统一控制所有光照颜色，优先级较低
    color?: number | string;
    // 统一控制所有光照透明度，优先级较低
    colorOpacity?: number;
    // 环境光
    ambientLightColor?: number | string;
    ambientLightColorOpacity?: number;
    // 直射光
    directLightColor?: number | string;
    directLightColorOpacity?: number;
  };
  /** 相机配置 */
  cameraConfigs?: {
    width?: number;
    height?: number;
    position?: {
      x: number;
      y: number;
      z: number;
    };
    lookAt?: {
      x: number;
      y: number;
      z: number;
    };
  };
  /** 辅助坐标系配置 */
  axesHelperConfigs?: {
    // 坐标轴长度
    length?: number;
  };
  /** 渲染器配置 */
  rendererConfigs?: {
    width?: number;
    height?: number;
    backgroundColor?: number | string;
    backgroundColorOpacity?: number;
  };
} | null;

返回值

type InitReturns = {
  // 渲染器
  renderer: Renderer;
  // 相机
  camera: Camera;
  // 场景
  scene: Scene;
  // 挂载函数，用于创建 canvas 绘制 3d 场景
  mountTo: (el: HTMLElement) => void;
  // 刷新函数，用于特殊场景下的手动刷新，一般情况不会用到
  refresh: () => void;
  // 添加鼠标控制，可以通过返回的控制对象进一步配置
  addControls: (params: AddControlsParams) => AddControlsParams;
  // 鼠标点击，返回值的第0个元素即鼠标选中的模型对象
  getClickEventTargets: (
    e: MouseEvent
  ) => Intersection<Object3D<Object3DEventMap>>[];
};

initCss3d

创建 css 3d 内容，主要分为 对象 和 精灵 两种：

对象: 能够被鼠标操作缩放，不被模型遮挡，能够通过DOM操作获取

精灵: 不能被鼠标操作缩放，可以被模型遮挡，能够通过射线拾取(可以粗略理解为鼠标点击操作获取)

示例

参数

• initCss3dParams: 配置项，定义如下:

type InitCss3dParams = {
  scene: Scene;
  camera: Camera;
};

返回值

type InitCss3dReturns = {
  // 手动刷新
  refresh: () => void;
  // 挂载 canvas 元素
  mountTo: (element: HTMLElement) => void;
  // 创建 css 3d 对象
  createCss3dObject: ({ element }: CreateCss3dObjectParams) => CSS3DObject;
  // 创建 css 3d 精灵
  createCss3dSprite: ({ element }: CreateCss3dObjectParams) => CSS3DSprite;
  // 创建 3d 文字
  createText: ({
    text,
    color,
    fontSize,
    thickness,
    position,
  }: CreateTextParams) => THREE.Mesh<
    TextGeometry,
    THREE.MeshBasicMaterial,
    THREE.Object3DEventMap
  >;
};

interface CreateTextParams {
  text: string;
  color?: number | string;
  fontSize?: number;
  thickness?: number;
  position?: {
    x: number;
    y: number;
    z: number;
  };
}

initCss2d

创建 css 2d 内容，其特点是：

不能被鼠标操作缩放，默认情况下不被模型遮挡，能够通过DOM操作获取

但是 lec3d 提供了配置项，能够控制其是否被模型遮挡

示例

参数

• intCss2dParams: 配置项，定义如下:

type InitCss2dParams = {
  scene: Scene;
  camera: Camera;
};

返回值

type InitCss2dReturns = {
  refresh: () => void;
  mountTo: (element: HTMLElement) => void;
  // 创建 css 2d 对象
  createCss2dObject: (params: CreateCss2dObjectParams) => CSS2DObject;
};

interface CreateCss2dObjectParams {
  // 内容
  content: string | HTMLElement;
  // css 样式属性
  style: Record<string, any>;
  // 是否可被模型遮挡
  occludable: boolean;
}

loadGLTF

导入 GLTF 模型文件, 并做相关配置

示例

import lec3d from "@trickle/lec3d";
const { scene } = lec3d.init();

lec3d.loadGLTF({
  modelPath: "3d_model/scene.gltf",
  options: {
    scale: 30,
    position: {
      x: 100,
      y: 100,
    },
    rotation: {
      x: "30", // 字符串数字代表角度，即 30 度
      z: -0.5,
    },
  },
  callback: (gltf, model) => {
    scene.add(model);
  },
});

参数

• loadGLTFparams: 配置项，定义如下：

type LoadGLTFParams = {
  // 模型文件路径
  modelPath: string;
  // 模型文件配置
  options?: CommonModelOptions;
  callback?: (gltf: GLTF, model: THREE.Group<THREE.Object3DEventMap>) => void;
};

interface CommonModelOptions {
  // 模型缩放
  scale?: number;
  // 模型的名字
  name?: string;
  // 模型位置

  position?: {
    x?: number;
    y?: number;
    z?: number;
  };
  // 模型旋转角度，使用字符串则为角度值，使用数字则为弧度值
  // 如 '30' 代表 30 度， 30 代表 180*30/PI 度
  rotation?: {
    x?: number | string;
    y?: number | string;
    z?: number | string;
  };
}

返回值

type LoadGLTFReturns = void;