411 lines
10 KiB
Markdown
411 lines
10 KiB
Markdown
---
|
||
outline: [2, 3]
|
||
---
|
||
|
||
# FractureEffect
|
||
|
||
- 源文件：`packages/sdk/src/effect/FractureEffect.ts`
|
||
- 文档位置：`packages/docs/api/effect/FractureEffect.md`
|
||
|
||
## 接口：`FractureEffectOptions`
|
||
|
||
- 作用：FractureEffectOptions 的结构定义。
|
||
|
||
### 字段
|
||
|
||
| 字段名 | 类型 | 必填 | 作用 |
|
||
| --- | --- | --- | --- |
|
||
| `points` | `THREE.Vector3[]` | 是 | 用于保存 `points` 的集合数据。 |
|
||
| `curveType` | `'catmullrom' \| 'linear'` | 否 | 用于保存 `curveType` 对应的数据。 |
|
||
| `tension` | `number` | 否 | 用于保存 `tension` 对应的数据。 |
|
||
| `closed` | `boolean` | 否 | 用于标记 `closed` 的启用状态。 |
|
||
| `spacing` | `number` | 否 | 用于保存 `spacing` 对应的数据。 |
|
||
| `bufferRatio` | `number` | 否 | 用于保存 `bufferRatio` 对应的数据。 |
|
||
| `minRadius` | `number` | 否 | 用于保存 `minRadius` 对应的数据。 |
|
||
| `maxRadius` | `number` | 否 | 用于保存 `maxRadius` 对应的数据。 |
|
||
| `animationDuration` | `number` | 否 | 用于保存 `animationDuration` 对应的数据。 |
|
||
| `sphereAnimDuration` | `number` | 否 | 用于保存 `sphereAnimDuration` 对应的数据。 |
|
||
| `sphereOpacity` | `number` | 否 | 用于保存 `sphereOpacity` 对应的数据。 |
|
||
| `spheresVisible` | `boolean` | 否 | 用于标记 `spheresVisible` 的启用状态。 |
|
||
| `cracksVisible` | `boolean` | 否 | 用于标记 `cracksVisible` 的启用状态。 |
|
||
| `colorMode` | `'random' \| 'gradient' \| 'fixed'` | 否 | 用于保存 `colorMode` 对应的数据。 |
|
||
| `fixedColor` | `number` | 否 | 用于保存 `fixedColor` 对应的数据。 |
|
||
| `gradientStart` | `number` | 否 | 用于保存 `gradientStart` 对应的数据。 |
|
||
| `gradientEnd` | `number` | 否 | 用于保存 `gradientEnd` 对应的数据。 |
|
||
| `autoStart` | `boolean` | 否 | 用于标记 `autoStart` 的启用状态。 |
|
||
| `crackModelUrls` | `string[]` | 否 | 用于保存 `crackModelUrls` 的集合数据。 |
|
||
|
||
## 类：`FractureEffect`
|
||
|
||
- 作用：压裂效果 沿着一组点生成的曲线生成一系列带弹性动画的球体，模拟压裂过程
|
||
|
||
### 构造函数
|
||
|
||
#### `new FractureEffect(options: FractureEffectOptions)`
|
||
|
||
- 作用：创建 FractureEffect 实例。
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `options` | `FractureEffectOptions` | 是 | 当前功能对应的配置项。 |
|
||
|
||
- 出参：`FractureEffect`
|
||
- 返回说明：返回当前类实例。
|
||
|
||
### 属性
|
||
|
||
| 属性名 | 可见性 | 类型 | 作用 |
|
||
| --- | --- | --- | --- |
|
||
| `options` | `public` | `Required<FractureEffectOptions>` | 用于保存 `options` 对应的数据。 |
|
||
| `active` | `public` | `boolean` | 用于标记 `active` 的启用状态。 |
|
||
| `running` | `public` | `boolean` | 用于标记 `running` 的启用状态。 |
|
||
| `spheres` | `public` | `FractureSphere[]` | 用于保存 `spheres` 的集合数据。 |
|
||
| `group` | `public` | `THREE.Group` | 用于保存 `group` 对应的数据。 |
|
||
| `crackModels` | `public` | `THREE.Object3D[]` | 用于保存 `crackModels` 的集合数据。 |
|
||
| `crackModelTemplates` | `public` | `THREE.Object3D[]` | 用于保存 `crackModelTemplates` 的集合数据。 |
|
||
| `progressCallback` | `public` | `((progress: number) => void) \| null` | 用于保存 `progressCallback` 对应的数据。 |
|
||
| `curve` | `public` | `THREE.Curve<THREE.Vector3> \| null` | 用于保存 `curve` 对应的数据。 |
|
||
|
||
### 方法
|
||
|
||
#### `createCurve(): void`
|
||
|
||
- 作用：根据点数组创建曲线
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `onProgress(callback: (progress: number) => void): void`
|
||
|
||
- 作用：设置进度回调
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `callback` | `(progress: number) => void` | 是 | 回调函数。 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `start(): Promise<void>`
|
||
|
||
- 作用：开始压裂动画
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`Promise<void>`
|
||
- 返回说明：返回 Promise，解析结果类型为 `void`。
|
||
|
||
#### `stop(): void`
|
||
|
||
- 作用：停止动画
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `clear(): void`
|
||
|
||
- 作用：清除所有球体和裂缝模型
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `showCracks(): void`
|
||
|
||
- 作用：显示裂缝模型
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `hideCracks(): void`
|
||
|
||
- 作用：隐藏裂缝模型
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `toggleCracks(): void`
|
||
|
||
- 作用：切换裂缝模型显示
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `showSpheres(): void`
|
||
|
||
- 作用：显示球体
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `hideSpheres(): void`
|
||
|
||
- 作用：隐藏球体
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `toggleSpheres(): void`
|
||
|
||
- 作用：切换球体显示
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `setOpacity(opacity: number): void`
|
||
|
||
- 作用：设置球体透明度
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `opacity` | `number` | 是 | 参数 `opacity`，类型为 `number`。 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `updatePoints(points: THREE.Vector3[]): void`
|
||
|
||
- 作用：更新点数组
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `points` | `THREE.Vector3[]` | 是 | 参数 `points`，类型为 `THREE.Vector3[]`。 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `restart(): Promise<void>`
|
||
|
||
- 作用：重新开始
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`Promise<void>`
|
||
- 返回说明：返回 Promise，解析结果类型为 `void`。
|
||
|
||
#### `getSphereCount(): number`
|
||
|
||
- 作用：获取球体数量
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`number`
|
||
- 返回说明：返回数值结果。
|
||
|
||
#### `getSpheres(): FractureSphere[]`
|
||
|
||
- 作用：获取球体列表
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`FractureSphere[]`
|
||
- 返回说明：返回数组结果，元素类型为 `FractureSphere`。
|
||
|
||
#### `dispose(): void`
|
||
|
||
- 作用：销毁
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `loadCrackModels(): Promise<void>`
|
||
|
||
- 作用：加载裂缝模型模板
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`Promise<void>`
|
||
- 返回说明：返回 Promise，解析结果类型为 `void`。
|
||
|
||
#### `getRandomHighContrastColor(): THREE.Color`
|
||
|
||
- 作用：生成高对比度随机颜色
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`THREE.Color`
|
||
- 返回说明：返回 `THREE.Color`。
|
||
|
||
#### `getGradientColor(t: number): THREE.Color`
|
||
|
||
- 作用：根据位置获取渐变颜色
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `t` | `number` | 是 | 参数 `t`，类型为 `number`。 |
|
||
|
||
- 出参：`THREE.Color`
|
||
- 返回说明：返回 `THREE.Color`。
|
||
|
||
#### `getSphereColor(t: number): THREE.Color`
|
||
|
||
- 作用：获取球体颜色
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `t` | `number` | 是 | 参数 `t`，类型为 `number`。 |
|
||
|
||
- 出参：`THREE.Color`
|
||
- 返回说明：返回 `THREE.Color`。
|
||
|
||
#### `easeOutElastic(x: number): number`
|
||
|
||
- 作用：缓动函数 - easeOutElastic
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `x` | `number` | 是 | 参数 `x`，类型为 `number`。 |
|
||
|
||
- 出参：`number`
|
||
- 返回说明：返回数值结果。
|
||
|
||
#### `animateSphereIn(sphere: THREE.Mesh): Promise<void>`
|
||
|
||
- 作用：球体弹入动画
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `sphere` | `THREE.Mesh` | 是 | 参数 `sphere`，类型为 `THREE.Mesh`。 |
|
||
|
||
- 出参：`Promise<void>`
|
||
- 返回说明：返回 Promise，解析结果类型为 `void`。
|
||
|
||
#### `calculatePositions(): { position: THREE.Vector3; t: number; index: number; }[]`
|
||
|
||
- 作用：计算球体位置
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`{ position: THREE.Vector3; t: number; index: number; }[]`
|
||
- 返回说明：返回数组结果，元素类型为 `{ position: THREE.Vector3; t: number; index: number; }`。
|
||
|
||
## 构造示例
|
||
|
||
- 来源：`packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue`
|
||
|
||
```ts
|
||
const points = [
|
||
new THREE.Vector3(1.5, -0.3, 1.5),
|
||
new THREE.Vector3(0, -0.3, 0)
|
||
]
|
||
|
||
effect = new FractureEffect({
|
||
points: points,
|
||
curveType: 'catmullrom',
|
||
tension: 0.5,
|
||
spacing: 0.1, // 增大间距
|
||
bufferRatio: 0.02,
|
||
closed: false, // 不闭合，形成螺旋
|
||
spheresVisible: showRuptureSpheres.value,
|
||
cracksVisible: showFractures.value
|
||
});
|
||
```
|
||
|
||
- 来源：`packages/demo/src/panels/OilGasScene/FracturingPanel.vue`
|
||
|
||
```ts
|
||
const points = generateSpiralPoints();
|
||
|
||
effect = new FractureEffect({
|
||
points: points,
|
||
curveType: 'catmullrom',
|
||
tension: 0.5,
|
||
spacing: 0.2, // 增大间距
|
||
bufferRatio: 0.02,
|
||
closed: false, // 不闭合，形成螺旋
|
||
spheresVisible: showRuptureSpheres.value,
|
||
cracksVisible: showFractures.value
|
||
});
|
||
```
|
||
|
||
## 函数示例
|
||
|
||
### `FractureEffect.onProgress`
|
||
|
||
- 来源：`packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue`
|
||
|
||
```ts
|
||
effect = new FractureEffect({
|
||
points: points,
|
||
curveType: 'catmullrom',
|
||
tension: 0.5,
|
||
spacing: 0.1, // 增大间距
|
||
bufferRatio: 0.02,
|
||
closed: false, // 不闭合，形成螺旋
|
||
spheresVisible: showRuptureSpheres.value,
|
||
cracksVisible: showFractures.value
|
||
});
|
||
|
||
isRunning.value = true;
|
||
effect.onProgress((progress) => {
|
||
if (progress >= 1) isRunning.value = false;
|
||
});
|
||
```
|
||
|
||
### `FractureEffect.showCracks`
|
||
|
||
- 来源：`packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue`
|
||
|
||
```ts
|
||
if (effect) {
|
||
if (showFractures.value) effect.showCracks(); else effect.hideCracks();
|
||
}
|
||
isRunning.value = false;
|
||
};
|
||
```
|
||
|
||
### `FractureEffect.showSpheres`
|
||
|
||
- 来源：`packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue`
|
||
|
||
```ts
|
||
if (!effect) return;
|
||
if (val) effect.showSpheres(); else effect.hideSpheres();
|
||
});
|
||
```
|
||
|
||
## Demo 参考
|
||
|
||
### `FractureEffect`
|
||
|
||
以下示例文件中可以看到该 API 的实际调用方式：
|
||
|
||
- `packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue`
|
||
- `packages/demo/src/panels/OilGasScene/FracturingPanel.vue`
|
||
|