412 lines
10 KiB
Markdown
412 lines
10 KiB
Markdown
---
|
||
outline: [2, 3]
|
||
---
|
||
|
||
# CubePanel
|
||
|
||
- 源文件：`packages/sdk/src/mesh/CubePanel.ts`
|
||
- 文档位置：`packages/docs/api/mesh/CubePanel.md`
|
||
|
||
## 枚举：`LabelPosition`
|
||
|
||
- 作用：标签位置枚举
|
||
|
||
| 枚举项 | 值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `TOP` | `'top'` | 枚举值 `TOP`。 |
|
||
| `BOTTOM` | `'bottom'` | 枚举值 `BOTTOM`。 |
|
||
| `LEFT` | `'left'` | 枚举值 `LEFT`。 |
|
||
| `RIGHT` | `'right'` | 枚举值 `RIGHT`。 |
|
||
|
||
## 接口：`ISmallTextConfig`
|
||
|
||
- 作用：小字配置接口
|
||
|
||
### 字段
|
||
|
||
| 字段名 | 类型 | 必填 | 作用 |
|
||
| --- | --- | --- | --- |
|
||
| `text` | `string` | 是 | 文字内容 |
|
||
| `cubeIndex` | `number` | 是 | 目标正方体索引（0-4），-1 表示全部 |
|
||
| `rotation` | `number` | 否 | 旋转角度（度） |
|
||
| `fontSize` | `number` | 否 | 字体大小（像素） |
|
||
| `color` | `string` | 否 | 字体颜色 |
|
||
| `fontWeight` | `string` | 否 | 字体权重 |
|
||
| `offset` | `number` | 否 | 与面板边缘的距离（3D单位） |
|
||
|
||
## 接口：`ICubeData`
|
||
|
||
- 作用：小正方体数据接口
|
||
|
||
### 字段
|
||
|
||
| 字段名 | 类型 | 必填 | 作用 |
|
||
| --- | --- | --- | --- |
|
||
| `color` | `THREE.Color` | 是 | 颜色 |
|
||
| `text` | `string` | 是 | 文字 |
|
||
|
||
## 接口：`ISinglePanelOptions`
|
||
|
||
- 作用：单个面板配置选项
|
||
|
||
### 字段
|
||
|
||
| 字段名 | 类型 | 必填 | 作用 |
|
||
| --- | --- | --- | --- |
|
||
| `name` | `string` | 是 | 面板名称 |
|
||
| `size` | `number` | 否 | 面板大小,three 的单位 |
|
||
| `cubeSize` | `number` | 否 | 小正方体大小 |
|
||
| `cubeGap` | `number` | 否 | 小正方体间距 |
|
||
| `position` | `THREE.Vector3` | 否 | 面板位置 |
|
||
| `rotation` | `THREE.Euler` | 否 | 面板旋转 |
|
||
| `initialData` | `ICubeData[][]` | 否 | 初始数据 |
|
||
| `titleConfig` | `{ text: string; position: LabelPosition; rotation?: number; fontSize?: number; color?: string; offset?: number; }` | 否 | 标题配置 |
|
||
| `smallTextConfig` | `{ position: LabelPosition; smallText1?: ISmallTextConfig[]; smallText2?: ISmallTextConfig[]; rotation?: number; }` | 否 | 小字乐配置 |
|
||
| `visibleColumns` | `number[]` | 否 | 可见列索引数组，只有这些列会显示，其他列显示为白色 |
|
||
|
||
## 类：`CubePanel`
|
||
|
||
- 作用：单个面板类 表示一个由5*5个小正方体构成的面板
|
||
|
||
### 构造函数
|
||
|
||
#### `new CubePanel(options: ISinglePanelOptions)`
|
||
|
||
- 作用：创建单个面板
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `options` | `ISinglePanelOptions` | 是 | - 配置选项 |
|
||
|
||
- 出参：`CubePanel`
|
||
- 返回说明：返回当前类实例。
|
||
|
||
### 属性
|
||
|
||
| 属性名 | 可见性 | 类型 | 作用 |
|
||
| --- | --- | --- | --- |
|
||
| `name` | `public` | `string` | 面板名称 |
|
||
| `group` | `public` | `THREE.Group` | 面板组对象 |
|
||
| `cubeData` | `public` | `Map<string, ICubeData>` | 小正方体数据映射 |
|
||
| `panelMesh` | `public` | `THREE.Mesh \| null` | 面板网格 |
|
||
| `options` | `public` | `Required<ISinglePanelOptions>` | 配置选项 |
|
||
| `titleObject` | `public` | `THREE.Mesh \| null` | 标题对象 |
|
||
| `titleConfig` | `public` | `{ text: string; position: LabelPosition; rotation: number; fontSize: number; color: string; offset?: number } \| null` | 标题配置 |
|
||
| `fontLoader` | `public` | `FontLoader` | 字体加载器 |
|
||
| `font` | `public` | `any` | 加载的字体 |
|
||
| `smallTextObjects` | `public` | `THREE.Mesh[]` | 小字对象数组 |
|
||
| `smallTextPlanes` | `public` | `THREE.Mesh[]` | 小字平面几何体数组 |
|
||
| `smallTextCanvas` | `public` | `HTMLCanvasElement \| null` | 小字生成的 canvas |
|
||
| `visibleColumns` | `public` | `Set<number>` | 可见列索引集合 |
|
||
|
||
### 方法
|
||
|
||
#### `getModelSize(targetModel: THREE.Object3D): THREE.Vector3 | null`
|
||
|
||
- 作用：静态方法：获取场景中指定名称的模型并计算其包围盒大小
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `targetModel` | `THREE.Object3D` | 是 | 参数 `targetModel`，类型为 `THREE.Object3D`。 |
|
||
|
||
- 出参：`THREE.Vector3 \| null`
|
||
- 返回说明：模型的包围盒大小，如果未找到模型则返回 null
|
||
|
||
#### `getModelFaceCenters(targetModel: THREE.Object3D): { [key: string]: THREE.Vector3; } | null`
|
||
|
||
- 作用：静态方法：获取场景中指定名称的模型并计算其包围盒六个面的中心点位置
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `targetModel` | `THREE.Object3D` | 是 | 参数 `targetModel`，类型为 `THREE.Object3D`。 |
|
||
|
||
- 出参：`{ [key: string]: THREE.Vector3; } \| null`
|
||
- 返回说明：模型的包围盒六个面的中心点位置，如果未找到模型则返回 null
|
||
|
||
#### `createPanel(): void`
|
||
|
||
- 作用：创建面板
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `initDefaultData(): void`
|
||
|
||
- 作用：初始化默认数据
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `generatePanelHTML(): string`
|
||
|
||
- 作用：生成面板的 HTML
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`string`
|
||
- 返回说明：HTML 字符串
|
||
|
||
#### `updatePanelTexture(): Promise<void>`
|
||
|
||
- 作用：将 HTML 转换为纹理并更新面板
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`Promise<void>`
|
||
- 返回说明：返回 Promise，解析结果类型为 `void`。
|
||
|
||
#### `setCubeData(row: number, col: number, data: ICubeData): void`
|
||
|
||
- 作用：设置小正方体数据
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `row` | `number` | 是 | - 行索引 |
|
||
| `col` | `number` | 是 | - 列索引 |
|
||
| `data` | `ICubeData` | 是 | - 小正方体数据 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `getCubeData(row: number, col: number): ICubeData | undefined`
|
||
|
||
- 作用：获取小正方体数据
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `row` | `number` | 是 | - 行索引 |
|
||
| `col` | `number` | 是 | - 列索引 |
|
||
|
||
- 出参：`ICubeData \| undefined`
|
||
- 返回说明：小正方体数据
|
||
|
||
#### `setPanelData(data: ICubeData[][]): void`
|
||
|
||
- 作用：批量设置面板数据
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `data` | `ICubeData[][]` | 是 | - 面板数据 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `setTitle(titleConfig: ISinglePanelOptions['titleConfig']): void`
|
||
|
||
- 作用：设置面板标题
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `titleConfig` | `ISinglePanelOptions['titleConfig']` | 是 | - 标题配置 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `loadFontAndCreateTitle(): void`
|
||
|
||
- 作用：加载字体并创建标题
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `createTitleObject(): void`
|
||
|
||
- 作用：创建标题对象
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `setSmallText(smallTextConfig: ISinglePanelOptions['smallTextConfig']): Promise<void>`
|
||
|
||
- 作用：设置小字
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `smallTextConfig` | `ISinglePanelOptions['smallTextConfig']` | 是 | - 小字配置 |
|
||
|
||
- 出参：`Promise<void>`
|
||
- 返回说明：返回 Promise，解析结果类型为 `void`。
|
||
|
||
#### `createSmallTextHTML(smallTextConfig: ISinglePanelOptions['smallTextConfig']): Promise<void>`
|
||
|
||
- 作用：使用 HTML 实现小字，在一个大的 div 中创建所有小字，然后转为 canvas 到一个新的平面几何体
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `smallTextConfig` | `ISinglePanelOptions['smallTextConfig']` | 是 | - 小字配置 |
|
||
|
||
- 出参：`Promise<void>`
|
||
- 返回说明：返回 Promise，解析结果类型为 `void`。
|
||
|
||
#### `clearSmallText(): void`
|
||
|
||
- 作用：清理小字
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `clearTitle(): void`
|
||
|
||
- 作用：清理标题对象
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `addDebugSpheres(): void`
|
||
|
||
- 作用：添加调试小球，在小字和mountGroup的原点添加不同颜色的小球
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `clearDebugSpheres(): void`
|
||
|
||
- 作用：清理调试小球
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `dispose(): void`
|
||
|
||
- 作用：销毁面板
|
||
|
||
- 入参：无
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `setVisibleColumns(columns: number[]): void`
|
||
|
||
- 作用：设置可见列
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `columns` | `number[]` | 是 | - 可见列索引数组 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
#### `toggleColumnVisibility(column: number): void`
|
||
|
||
- 作用：切换列的可见性
|
||
|
||
- 入参：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `column` | `number` | 是 | - 列索引 |
|
||
|
||
- 出参：`void`
|
||
- 返回说明：无返回值。
|
||
|
||
## 构造示例
|
||
|
||
- 来源：`packages/demo/src/panels/TunnelScene/LoadSurface.vue`
|
||
|
||
```ts
|
||
text: config.title,
|
||
position: LabelPosition.TOP,
|
||
rotation: 0,
|
||
fontSize: 1,
|
||
color: '#000000',
|
||
offset: 1
|
||
},
|
||
smallTextConfig: config.smallTextConfig,
|
||
// ZD 面只显示第2列（索引为2）
|
||
visibleColumns: key === 'ZD' ? [2] : undefined
|
||
};
|
||
|
||
const panel = new CubePanel(panelOptions);
|
||
panel.group.visible = false; // 初始隐藏
|
||
viewer.scene.add(panel.group);
|
||
panels.set(key, panel);
|
||
});
|
||
```
|
||
|
||
## 函数示例
|
||
|
||
### `CubePanel.getModelFaceCenters`
|
||
|
||
- 来源：`packages/demo/src/panels/TunnelScene/LoadSurface.vue`
|
||
|
||
```ts
|
||
if (!viewer) return;
|
||
// 使用 CubePanel 的静态方法获取模型包围盒六个面的中心点位置
|
||
// const faceCenters = CubePanel.getModelFaceCenters(bus.getRockSample());
|
||
const faceCenters = {
|
||
"YF": {
|
||
"x": 0,
|
||
"y": 0,
|
||
"z": 2.5
|
||
},
|
||
"BEI": {
|
||
"x": 0,
|
||
"y": 0,
|
||
"z": -2.5
|
||
},
|
||
"ZUO": {
|
||
"x": -2.5,
|
||
"y": 0,
|
||
"z": 0
|
||
},
|
||
"YOU": {
|
||
"x": 2.5,
|
||
```
|
||
|
||
## Demo 参考
|
||
|
||
### `LabelPosition`
|
||
|
||
以下示例文件中可以看到该 API 的实际调用方式：
|
||
|
||
- `packages/demo/src/panels/TunnelScene/LoadSurface.vue`
|
||
|
||
### `ISinglePanelOptions`
|
||
|
||
以下示例文件中可以看到该 API 的实际调用方式：
|
||
|
||
- `packages/demo/src/panels/TunnelScene/LoadSurface.vue`
|
||
|
||
### `CubePanel`
|
||
|
||
以下示例文件中可以看到该 API 的实际调用方式：
|
||
|
||
- `packages/demo/src/panels/TunnelScene/LoadSurface.vue`
|
||
|