CesiumFair

CesiumFair 是一个基于 Cesium 的封装库，提供了更简洁的 API 和常用功能封装，帮助开发者快速构建三维地理信息应用。

一、快速上手

安装

npm install @mofair/mf-cesium-jssdk

引入

import { CesiumFair } from '@mofair/mf-cesium-jssdk'

初始化实例

创建一个 CesiumFair 实例，初始化三维地球场景。

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 | Promise, option?: CesiumTerrainProvider.ConstructorOptions } | 地形数据配置，参考 Cesium 原生 CesiumTerrainProvider | undefined | | location | CesiumLocation | 初始化视角位置（含经纬度、高度、俯仰角等，格式见 2.4 节） | undefined | | depthTestTerrain | boolean | 是否开启「地形深度缓冲」（优化地形与模型的遮挡显示） | false | | globeTransparent | boolean | 是否设置地球透明（常用于叠加自定义底图或特殊视觉效果） | false | | cameraCollision | boolean | 是否开启「相机与地形碰撞检测」（避免相机穿透地形） | false | | tiles3d | Array | 3D Tiles 模型配置（支持批量加载，格式见 2.4 节） | [] | | useBrowserRecommendedResolution | boolean | 是否使用浏览器推荐的分辨率（平衡性能与视觉效果） | true | | shouldAnimate | boolean | 是否开启动画（如地球自转） | true |

关联类型定义

为帮助理解配置格式，以下是核心关联类型的 TypeScript 定义：

1. CesiumLocation（视角位置） 控制初始化时相机的位置与姿态：

   interface CesiumLocation {
     center: [number, number, number]; // [经度, 纬度, 高度]，例：[113.1433, 23.103, 2500]
     pitch?: number;                  // 俯仰角（单位：度），默认 -30（俯视），-90 为正俯视
     heading?: number;                // 航向角（单位：度），默认 0（正北方向）
     roll?: number;                   // 翻滚角（单位：度），默认 0（无倾斜）
   }

2. ImageryTile（瓦片图层） 配置栅格瓦片底图（如高德、百度瓦片或自定义瓦片服务）：

   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 模型数据：

   interface Tile3DOption {
     option: {
       url: string; // 3D Tiles 服务地址（.json 入口文件），例：http://xxx.com/model/tileset.json
       // 其他 Cesium 原生 Cesium3DTileset 支持的配置（如 maximumScreenSpaceError、cullWithChildrenBounds 等）
     };
     location?: boolean; // 加载完成后是否自动聚焦到该模型，默认 false
   }

完整使用示例

以下是包含「底图、地形、3D 模型、初始视角」的完整初始化示例：

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);

销毁实例

cesiumFair.destroy()

监听和卸载点击事件

// 添加点击事件
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 对象：

// 获取原生 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,
  },
});