---
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`