npm package: @mofair/mf-cesium-jssdk
Description: MFair-JSSDK-Cesium-Launcher
Latest version: 0.3.10

# CesiumFair

CesiumFair 是一个基于 Cesium 的封装库，提供了更简洁的 API 和常用功能封装，帮助开发者快速构建三维地理信息应用。

## 一、快速上手

### 安装

```bash
npm install @mofair/mf-cesium-jssdk
```

### 引入

```js
import { CesiumFair } from '@mofair/mf-cesium-jssdk'
```
### 初始化实例

创建一个 CesiumFair 实例，初始化三维地球场景。

```js
const fair = new CesiumFair(container, options);
```

#### 参数说明

- `container` (HTMLElement): 地图容器 DOM 元素
- `options` (Object): 初始化配置选项，详细如下

#### Options配置项

| 配置项                            | 类型                                                         | 说明                                                         | 默认值    |
| --------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | --------- |
| `sceneModePicker`                 | boolean                                                      | 是否显示「投影模式切换按钮」（支持 3D/2D / 哥伦布视图切换）  | false     |
| `fullscreenButton`                | boolean                                                      | 是否显示「全屏按钮」（位于场景右下角）                       | false     |
| `imageryLayers`                   | Array<ImageryTile \| ImageryWms>                             | 栅格瓦片图层配置（支持多图层叠加，类型见 2.4 节）            | []        |
| `terrain`                         | {  url: Resource \| string \| Promise<Resource> \| Promise<string>,  option?: CesiumTerrainProvider.ConstructorOptions } | 地形数据配置，参考 Cesium 原生 [CesiumTerrainProvider](https://cesium.com/learn/cesiumjs/ref-doc/CesiumTerrainProvider.html#.fromUrl) | undefined |
| `location`                        | CesiumLocation                                               | 初始化视角位置（含经纬度、高度、俯仰角等，格式见 2.4 节）    | undefined |
| `depthTestTerrain`                | boolean                                                      | 是否开启「地形深度缓冲」（优化地形与模型的遮挡显示）         | false     |
| `globeTransparent`                | boolean                                                      | 是否设置地球透明（常用于叠加自定义底图或特殊视觉效果）       | false     |
| `cameraCollision`                 | boolean                                                      | 是否开启「相机与地形碰撞检测」（避免相机穿透地形）           | false     |
| `tiles3d`                         | Array<Tile3DOption>                                          | 3D Tiles 模型配置（支持批量加载，格式见 2.4 节）             | []        |
| `useBrowserRecommendedResolution` | boolean                                                      | 是否使用浏览器推荐的分辨率（平衡性能与视觉效果）             | true      |
| `shouldAnimate`                   | boolean                                                      | 是否开启动画（如地球自转）                                   | true      |

#### 关联类型定义

为帮助理解配置格式，以下是核心关联类型的 TypeScript 定义：

1. **CesiumLocation（视角位置）**
   控制初始化时相机的位置与姿态：

   ```typescript
   interface CesiumLocation {
     center: [number, number, number]; // [经度, 纬度, 高度]，例：[113.1433, 23.103, 2500]
     pitch?: number;                  // 俯仰角（单位：度），默认 -30（俯视），-90 为正俯视
     heading?: number;                // 航向角（单位：度），默认 0（正北方向）
     roll?: number;                   // 翻滚角（单位：度），默认 0（无倾斜）
   }
   ```

2. **ImageryTile（瓦片图层）**
   配置栅格瓦片底图（如高德、百度瓦片或自定义瓦片服务）：

   ```typescript
   interface ImageryTile {
     type: 'tile'; // 固定值，标识瓦片类型
     option: {
       url: string;                  // 瓦片服务地址，支持 {z}/{x}/{y} 模板，例：http://xxx.com/{z}/{x}/{y}.webp
       enablePickFeatures?: boolean; // 是否允许拾取瓦片要素（如矢量瓦片的属性信息），默认 false
       // 其他 Cesium 原生 ImageryProvider 支持的配置（如 minimumLevel、maximumLevel 等）
     };
   }
   ```

3. **Tile3DOption（3D Tiles 模型）**
   配置倾斜摄影、BIM 等 3D 模型数据：

   ```typescript
   interface Tile3DOption {
     option: {
       url: string; // 3D Tiles 服务地址（.json 入口文件），例：http://xxx.com/model/tileset.json
       // 其他 Cesium 原生 Cesium3DTileset 支持的配置（如 maximumScreenSpaceError、cullWithChildrenBounds 等）
     };
     location?: boolean; // 加载完成后是否自动聚焦到该模型，默认 false
   }
   ```

### 完整使用示例

以下是包含「底图、地形、3D 模型、初始视角」的完整初始化示例：

```js
const config = {
    imageryLayers: [
        {
            type: 'tile',
            option: {
                url: 'http://www.example.com/{z}/{x}/{y}.webp',
                // 这里需要替换成你自己的瓦片地址
                enablePickFeatures: false,
            },
        },
    ],
    terrain: {
        url: 'TERRAIN_URL',
        // 这里需要替换成你自己的地形地址
    },
    depthTestTerrain: true,
    location: {
        center: [113.1433, 23.103, 2500],
        pitch: -90,
    },
    controlAsMapbox: true,
    tiles3d: [
        {
            option: {
                // 这里替换成你的3dtile 地址
                // 3dtile 可一次性加载多个
                url: 'OBLIQUE_URL',
            },
            location: false,
            // 是否聚焦到该图层
        }
    ],
}
const cesiumFair = new CesiumFair(document.getElementById('globe'), config);
```

### 销毁实例

```js
cesiumFair.destroy()
```

### 监听和卸载点击事件

```js
// 添加点击事件
cesiumFair.on('click', ({ feature, location }) => {
  // feature: 拾取到的对象（如 Cesium3DTileFeature、ImageryLayerFeatureInfo 等）
  // location: 点击位置的经纬度与高度，格式 [经度, 纬度, 高度]
  console.log('点击要素信息：', feature);
  console.log('点击位置：', location);
});

// 移除监听
cesiumFair.off('click', handleClick);
```

## 二、 获取原生 Cesium Viewer

若需使用 Cesium 原生 API（如自定义 Entity、Primitive 等），可通过实例获取原生 `Viewer` 对象：

```typescript
// 获取原生 Viewer 实例
const viewer = cesiumFair.viewer;

// 示例：使用原生 API 添加点实体
const entity = viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(113.1433, 23.103, 1000),
  point: {
    pixelSize: 10,
    color: Cesium.Color.RED,
  },
});
```