Appearance
场景操作
setBackgroundColor
设置背景色
样例：
定义：
ts
function setBackgroundColor(color: IColor): void;用法：
js
ssp.setBackgroundColor(0xff0000);参数：
color
- 类型: IColor
- 描述: 颜色值
- 必填:
setBackgroundColorAlpha
设置背景色（不透明度）
定义：
ts
function setBackgroundColorAlpha(color: IColor, alpha?: number): void;用法：
js
ssp.setBackgroundColorAlpha(0xff0000, 0.5);参数：
color
- 类型: IColor
- 描述: 颜色值
- 必填:
alpha
- 类型: number
- 描述: 不透明度
- 必填: ，默认值为 1
setBackgroundImage
设置背景图
样例：
定义：
ts
function setBackgroundImage(imgUrl: string): Promise<void>;用法：
js
await ssp.setBackgroundImage('http://xx.com/xx.png');
console.log('背景图替换成功');参数：
imgUrl
- 类型: string
- 描述: 图片路径
- 必填:
setSphereSkyBackground
设置球体天空盒，球体天空盒的图片资源是一张全景图。( HDR 天空盒模版资源下载 ) )
样例：
定义：
ts
function setSphereSkyBackground(imgUrl: string): Promise<void>;用法：
js
await ssp.setSphereSkyBackground('http://xx.com/xx.png');
console.log('球体天空盒替换成功');参数：
imgUrl
- 类型: string
- 描述: 图片路径。
- 必填:
setSkyBackground
设置天空盒 ( 天空盒模版资源下载 )
样例：
定义：
ts
function setSkyBackground(dirPath: string, fileNames: string[]): Promise<void>;用法：
js
await ssp.setSkyBackground(
// 文件夹路径
'./xxx/sunny/',
// 有序的图片名集合
['px.jpg', 'nx.jpg', 'py.jpg', 'ny.jpg', 'pz.jpg', 'nz.jpg']
);
console.log('天空盒替换成功');参数：
dirPath
- 类型: string
- 描述: 图片文件夹路径。
- 必填:
fileNames
- 类型: string[]
- 描述: 六张图片的名称集合。
- 必填:
提示
参数 fileNames 内的图片是有严格顺序的。依次为：
- 以空间坐标系为参考
x 轴正向（px）、x 轴负向（nx）、y 轴正向（py）、y 轴负向（ny）、z 轴正向（pz）、z 轴负向（nz）。
p -> positive、 n -> negative - 以立方体盒子的六个面为参考
右（right）、左（left）、上（top）、下（bottom）、前（front）、后（back）。
setColorSpace
设置场景的色彩空间
版本：
v2.3.14
样例：
定义：
ts
type ColorSpace = 'Linear' | 'sRGB'
setColorSpace(colorSpace: ColorSpace): void用法：
js
ssp.setColorSpace('Linear');colorSpace
- 类型:
ColorSpace - 描述: 色彩值
- 必填: ，默认值为
sRGB
setToneMapping
设置场景色调
样例：
定义：
ts
interface ToneMappingOptions {
type?: 'None' | 'Reinhard' | 'Cineon' | 'ACESFilmic' | 'AGX';
exposure?: number;
}
setToneMapping(options?: ToneMappingOptions): void用法：
js
ssp.setToneMapping({ type: 'ACESFilmic', exposure: 0.8 });options
- 类型:
ToneMappingOptions - 描述: 配置选项
- 必填:
ToneMappingOptions
| 属性 | 描述 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| type | 色调类型 | ToneMappingOptions[type] | ACESFilmic | |
| exposure | 曝光度 | number | 0.8 |
setSky
设置天空
版本：
v2.3.14
样例：
定义：
ts
interface SkyOptions {
enabled?: boolean;
position?: Position;
scalar?: number;
turbidity?: number;
rayleigh?: number;
elevation?: number;
azimuth?: number;
}
function setSky(options?: SkyOptions): Sky | undefined;用法：
js
ssp.setSky({
enabled: true,
position: { x: 0, y: 0, z: 0 },
scalar: 450000,
turbidity: 10,
rayleigh: 3,
elevation: 2,
azimuth: 180,
});options
- 类型:
SkyOptions - 描述: 配置选项
- 必填:
SkyOptions
| 属性 | 描述 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| enabled | 是否开启天空 | boolean | true | |
| position | 天空位置 | Position | { "x": 0, "y": 0, "z": 0 } | |
| scalar | 天空范围 | number | 450000 | |
| turbidity | 太阳浑浊度 | number | 10 | |
| rayleigh | 太阳雷利值 | number | 3 | |
| elevation | 太阳海拔 | number | 2 | |
| azimuth | 太阳方位 | number | 180 |
setBloom
设置泛光
样例：
定义：
ts
interface BloomOptions {
enabled?: boolean;
mipmapBlur?: boolean;
radius?: number;
intensity?: number;
threshold?: number;
smoothing?: number;
scalar?: number;
opacity?: number;
selection?: Object3D[];
}
function setBloom(options?: BloomOptions): void;用法：
js
ssp.setBloom({
enabled: true,
threshold: 0.1,
intensity: 2,
radius: 0.1,
opacity: 1,
});参数:
options
- 类型:
BloomOptions - 描述: 配置选项
- 必填:
BloomOptions
| 属性 | 描述 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| enabled | 是否开启 | boolean | true | |
| mipmapBlur | 是否开启 mipmap 模糊 | boolean | true | |
| radius | mipmap 模糊半径 | number | 0.85 | |
| intensity | 泛光强度 | number | 3 | |
| threshold | 泛光阈值（颜色） | number | 1 | |
| smoothing | 泛光的平滑度 | number | 0.01 | |
| scalar | 配合 `selection` 使用，选中的材质颜色会乘以 `scalar` 使色值超出 `threshold` | number | 2 | |
| opacity | 泛光的不透明度 | number | 1 | |
| selection | 选中的泛光对象 | Object3D[] | [] |
setSSAO
设置环境光遮蔽
样例：
定义：
ts
interface SSAOOptions {
enabled?: boolean;
aoRadius?: number;
distanceFalloff?: number;
intensity?: number;
aoSamples?: number;
denoiseSamples?: number;
denoiseRadius?: number;
color?: IColor;
}
setSSAO(options?: SSAOOptions): void用法：
js
ssp.setSSAO({
enabled: true,
aoSamples: 8,
intensity: 3,
});参数:
options
- 类型:
SSAOOptions - 描述: 配置选项
- 必填:
SSAOOptions
| 属性 | 描述 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| enabled | 是否开启 | boolean | true | |
| aoRadius | AO 半径 | number | 3 | |
| aoSamples | AO 采样数量 | number | 16 | |
| denoiseSamples | 降噪采样数量 | number | 4 | |
| denoiseRadius | 降噪采样半径 | number | 12 | |
| distanceFalloff | 遮挡阴影的消失距离，通常是半径的1/5 | number | 1 | |
| intensity | AO 强度 | number | 3 | |
| color | AO 颜色 | IColor | #333 |
推荐配置表
| 质量 | aoSamples | denoiseSamples | denoiseRadius | 适用终端 |
|---|---|---|---|---|
| 高性能模式 (不稳定，有部分噪点) | 8 | 4 | 12 | 移动端，集成显卡，笔记本 |
| 低 (暂时稳定，有低频噪点) | 16 | 4 | 12 | 高端移动机型，集成显卡，笔记本 |
| 中等 (暂时稳定，几乎没有噪点) | 16 | 8 | 12 | 高端移动机型，笔记本，桌面设备 |
| 高 (更清晰的 AO，几乎没有噪点) | 64 | 8 | 6 | 桌面端，独立显卡 |
| 极高 (没有噪点) | 64 | 16 | 6 | 桌面端，独立显卡 |
setEnvironment
设置场景环境反射
版本：
v2.3.12
样例：
定义：
ts
interface GetTextureOptions {
path?: string;
file: string | string[];
}
interface EnvironmentOptions extends GetTextureOptions {
background?: boolean;
}
setEnvironment(options?: EnvironmentOptions): Promise<THREE.Texture>用法：
js
/**
* 设置默认环境
*/
ssp.setEnvironment();
// or
ssp.setEnvironment({ file: './xxx.hdr', background: true });
// or
ssp.setEnvironment({
path: './imgs/',
file: ['px.jpg', 'nx.jpg', 'py.jpg', 'ny.jpg', 'pz.jpg', 'nz.jpg'],
background: true,
});参数:
options
- 类型:
EnvironmentOptions - 描述: 配置选项
- 必填:
EnvironmentOptions
| 属性 | 描述 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| path | 基础路径 | string | ||
| file | 文件路径 | string | string[] | ||
| background | 是否同步至背景 | boolean | false |
openSceneFog
开启场景雾化
样例：
定义:
ts
interface FogOptions {
color?: IColor;
near?: number;
far?: number;
}
function openSceneFog(options?: FogOptions): void;用法:
js
ssp.openSceneFog({ color: '0xcce0ff', near: 1, far: 1000 });参数:
options
- 类型: FogOptions
- 描述: 配置选项
- 必填:
FogOptions
| 属性 | 描述 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| color | 颜色 | IColor | 0xcce0ff | |
| near | 起始位置(距离相机) | number | 500 | |
| far | 结束位置(距离相机) | number | 50000 |
closeSceneFog
关闭场景雾化
定义:
ts
function closeSceneFog(): void;用法:
js
ssp.closeSceneFog();screenshot
截取场景快照
定义:
ts
function screenshot(): Promise<Blob | null>;用法:
js
ssp.screenshot().then((blob) => {
const newImg = document.createElement('img');
const url = URL.createObjectURL(blob);
newImg.onload = () => {
URL.revokeObjectURL(url);
};
newImg.src = url;
});getObjectLabelPos
获取对象的标签位置坐标
定义:
ts
interface LabelOptions {
mode?: 'scene' | 'screen';
extendScale?: number;
}
function getObjectLabelPos(
object: BaseObject3D,
viewpoint?: FlyToViewpoint;
options?: LabelOptions
): Position;用法:
js
ssp.getObjectLabelPos(object, 'front', { mode: 'scene', extendScale: 1.6 });参数:
object
- 类型: BaseObject3D
- 描述: 模型对象
- 必填:
viewpoint
- 类型: FlyToViewpoint
- 描述: 相对模型视角枚举
- 必填:
options
- 类型: LabelOptions
- 描述: 配置选项
- 必填:
LabelOptions
| 属性 | 描述 | 类型 | 必填 | 默认值 |
|---|---|---|---|---|
| mode | 相对于谁 | scene | screen | scene | |
| extendScale | 延伸比例 | number | 1.6 |
getOffsetByPosition
通过空间坐标点获取屏幕坐标点
定义:
ts
function getOffsetByPosition(position: Position): { left: number; top: number };用法:
js
ssp.getOffsetByPosition({ x: 100, y: 200, z: 300 });参数:
position
- 类型: Position
- 描述: 空间坐标
- 必填:
getPositionByOffset
通过屏幕坐标点获取空间坐标点
定义:
ts
function getPositionByOffset(offset: OffsetPoint, z?: number, scalar?: number): Vector3;用法:
js
ssp.getPositionByOffset({ offsetX: 10, offsetY: 10 }, 0.1, 10);参数:
offset
- 类型: OffsetPoint
- 描述: 偏移量
- 必填:
z
- 类型: number
- 描述: z 轴, 默认值 0.1
- 必填:
scalar
- 类型: number
- 描述: 延长标量, 默认值是 camera 到原点的距离
- 必填:
setHoverEnabled
设置开启鼠标悬浮
定义:
ts
function setHoverEnabled(enabled: boolean): void;用法:
js
ssp.setHoverEnabled(true);参数:
object
- 类型: boolean
- 描述: 是否开启
- 必填:
setLevelEnabled
设置开启 level 功能
定义:
ts
function setLevelEnabled(enabled: boolean): void;用法:
js
ssp.setLevelEnabled(true);setScaleFixedEnabled
设置开启 scaleFixed 功能
定义:
ts
function setScaleFixedEnabled(enabled: boolean): void;用法:
js
ssp.setScaleFixedEnabled(true);setFileCacheEnabled
v2.6.34
设置开启文件请求缓存
定义:
ts
function setFileCacheEnabled(enabled: boolean): void;用法:
js
ssp.setFileCacheEnabled(false);参数:
object
- 类型: boolean
- 描述: 是否开启
- 必填:
render
手动渲染一次场景
定义:
ts
function render(fn?: () => void): Promise<void>;用法:
js
// 用法一
model.position.x = 1000;
ssp.render().then(() => {
console.log('场景渲染完成');
});
// 用法二
ssp
.render(() => {
model.position.x = 1000;
})
.then(() => {
console.log('场景渲染完成');
});
// 用法三
ssp
.render(() => {
return new Promise((resolve) => {
setTimeout(() => {
model.position.x = 1000;
resolve();
}, 3000);
});
})
.then(() => {
console.log('场景渲染完成');
});参数:
fn
- 类型: () => void
- 描述: 在渲染之前执行
- 必填:
提示
fn 函数可以返回一个 Promise, 场景会在 fn 返回结果之后渲染
clearObject
清除除灯光外所有对象
定义:
ts
function clearObject(): void;用法:
js
ssp.clearObject();clearSignals
清除事件信号监听
定义:
ts
function clearSignals(): void;用法:
js
ssp.clearSignals();clear
清除所有对象
定义:
ts
function clear(): void;用法:
js
ssp.clear();dispose
销毁场景
定义:
ts
function dispose(): void;用法:
js
ssp.dispose();提示
dispose 常用于 react、vue 等组件的生命周期卸载阶段
例如在 react 中
js
useEffect(() => {
const ssp = new SoonSpace({
...
})
return () => {
ssp.dispose()
};
}, []);