Room3D
介绍
Room3D是一款JS插件,它能帮你用纯html/css快速构建3D房间和盒子。
这是一个轻量且不依赖任何第三方库的插件,设计它的初衷仅用于帮助开发者快速构建简单布局的3D场景,或者用于简易3D特效。如果你需要构建复杂场景,且对渲染效果要求较高,建议使用基于WebGL的3D库,如threeJs/babylonJs等。
———— 作者:DAN
中文文档 | English Document | DEMO on gitee | DEMO on git | Github仓库 | Npm Package
使用方法
安装插件,你将获得一个名为Scene3D
的构造函数
通过<script src="room3d.js"></script>
标签引入html文件,或者在模块化开发中,通过npm install room3d
安装插件,然后 使用const Scene3D = require("room3d")
或者import Scene3D from "room3d"
都能获得Scene3D
构造函数
引入样式文件room3d.css
准备Html元素<div id="wraper"><div>
,选择器可使用id或class。你可以手动为元素设置csswidth
和height
,如果未设置,插件将会为其设置widt:100%; height:100%;
编写脚本使用配置项创建场景和元素吧
let myScene = new Scene3D("#wraper",{width:"400px",depth:"400px",rooms:[{height:"400px",boxes:[{width:"100px",depth:"100px",height:"100px",left:"150px",top:"160px",color:"green"}]}]})
关系图
API
Scene 场景对象
配置项
方法
创建一个Scene对象let Scene = new Scene3D("#Scene1",{options...})
,该对象将可以使用以下方法:
Scene.showGrid( boolean )
参数
boolean {boolean} |必须
| 传true表示显示,false表示隐藏
返回值
返回当前Scene对象,可用于链式调用
说明
用于显示或隐藏场景的网格
Scene.resetScene()
参数
-
返回值
返回当前Scene对象,可用于链式调用
说明
重置场景旋转和缩放状态至初始值
Scene.buildRoom( options )
参数
options {object} |可选
| 配置对象,参照Room配置项
返回值
返回被创建的Room对象
说明
用传入的配置参数,手动创建Room,如果不传options参数,则使用默认配置创建Room
Room 房间对象
配置项
其中top
right
bottom
left
用于定位房间在场景中的水平位置,一般left
和right
只需要设置其中一项即可。top
和bottom
同理
关于宽度、进深、高度如何定义,可查看文档顶部的图示。
方法
创建一个Room对象let Room = Scene.buildRoom()
。如果是通过配置对象生成的Room,则可以通过let Room = Scene.rooms[index]
获得Room对象,该对象可以使用以下方法:
Room.showFloor( boolean )
Room.showWall( boolean )
Room.showLine( boolean )
参数
boolean {boolean} |必须
| 传true表示显示,false表示隐藏
返回值
返回当前Room对象,可用于链式调用
说明
用于显示或隐藏Room的Floor地板、Wall墙壁、Line墙角线。
Room.backface( value )
参数
value {string} |必须
| value可以为 “hidden” 或 “visible”
返回值
返回当前Room对象,可用于链式调用
说明
用于设置墙壁元素的backface-visibility
样式,具体表现是:设置为"hidden",朝向屏幕方向的墙壁将变成透明的,从而可以看见房间内的元素,且不会遮挡鼠标与房间内元素的交互。
Room.buildDoor( wall , doorOptions )
参数
wall {string} |必须
| wall参数可选值为"left"
,"right"
,"fore"
,"back"
doorOptions {object} |可选
| 门的配置项对象,详细配置参数见下方的Door配置项。
返回值
返回被创建的Door对象
说明
用传入的配置参数,手动创建Door。
Door 配置项
Door 方法
使用let Door = Room.buildDoor( wall , doorArray )[index]
或者let Door = Room.walls[wall].doors[index]
获取Door对象,该对象可以使用以下方法:
Door.openDoor()
将门打开Door.closeDoor()
将门关闭
Room.buildBox( options )
参数
options {object} |可选
| 配置对象,参数见Box配置项
返回值
返回被创建的Box对象
说明
用传入的配置参数,手动创建Box,如果不传options参数,则使用默认配置创建Box
Room.destroy()
参数
-
返回值
-
说明
销毁Room实例对象
Box 盒子对象
配置项
其中top
right
bottom
left
用于定位盒子在房间中的水平位置,一般left
和right
只需要设置其中一项即可。top
和bottom
同理
方法
创建一个Box对象let Box = Room.buildBox()
。如果是通过配置对象生成的Box,则可以通过let Box = Room.boxes[index]
获得Box对象,该对象可以使用以下方法:
Box.showLine( boolean )
Box.showMarker( boolean )
参数
boolean {boolean} |必须
| 传true表示显示,false表示隐藏
返回值
返回当前Box对象,可用于链式调用
说明
用于显示或隐藏Box的Line边角线、Marker标注。
Box.buildMarker( options )
参数
options {object} |可选
| 配置对象,参数见Marker配置项
返回值
返回被创建的Marker对象
说明
每一个Box对象被创建的时候会顺便自动创建相应的Marker对象,所以该方法实际上是先销毁原有的标注,再用新的配置项重新创建一个标注。如果你只是希望改变标注的一些数据,可以使用Marker对象的updateMarker()
方法。
Box.destroy()
参数
-
返回值
-
说明
销毁Box实例对象
Marker 标注对象
配置项
由于在dom结构中标注是直接创建在场景中,所以其top
right
bottom
left
是相对于场景的定位,同样left
和right
以及top
和bottom
只需要设置其中一项即可。并且由于left
和top
的默认值是一个表达式,用于将标注创建在盒子的正上方,所以如果需要用right
和bottom
进行定位,则必须将对应的left
和top
值设置为auto
。
方法
创建一个Marker对象并获取它let Marker = Box.buildMarker()
。如果要获取已经生成的Marker,则可以通过let Marker = Box.marker
获得,该对象可以使用以下方法:
Marker.updateMarker( params )
参数
params {object} |必须
| params对象必须包含与标注content模板相匹配的属性,以及需要更新的值。
返回值
返回当前Marker对象
说明
用于更新Marker内容模板。
Marker.destroy()
参数
-
返回值
-
说明
销毁Marker实例对象
注意事项
所有的长度及距离数值必须使用统一的单位,推荐使用px,否则会出现一些因为单位换算而导致的bug
两个紧贴相邻的Room如果需要在紧贴着的墙上创建门,需要在两个Room上对应的墙上都使用buildDoor()
方法,在对称的位置创建门,同时将其中一个门设置为不可见,即可实现。
你还可以使用css为场景内的各种元素设置background-image
样式,模仿贴图效果,从而实现更丰富的场景。
NPM包版本与更新
1.0.0
发布时间:/6/81.0.1
&1.0.2
发布时间:/6/8 修改说明文档1.1.0
发布时间:/6/15 Marker 对象添加scene
属性,它的值指向当前场景对象;Box 对象增加.destroy()
方法;Room 对象增加.destroy()
方法。