cesium-easy

Cesium 封装库，提供开箱即用的初始化、工具模块和 Cesium API 简化。

Quick start

npm install cesium-easy cesium

import { initViewer } from 'cesium-easy'
import * as Cesium from 'cesium'

const { viewer } = initViewer('cesium_container', { shouldAnimate: true })
viewer.entities.add({ ... })

cesium 是 peerDependency，需自行安装。推荐通过 <script> 标签加载 Cesium（UMD 方式），或配置 bundler 处理 Cesium 的静态资源（Worker、图片等）。

Dev

npm install
npm run dev        # 启动 Vite dev server，HMR 预览示例
npm run build      # 构建 ESM + CJS + UMD + .d.ts
npm run preview    # 构建 + 启动静态 server，验证 dist 产物
npm test           # 运行测试

示例

打开 http://localhost:5173/examples/ 可浏览所有示例。每个示例是一个独立 HTML，通过 ESM import 从源码引入 cesium-easy，修改源码后浏览器自动热更新。

构建产物

npm run build 产出：

| 文件 | 用途 | |---|---| | dist/index.js | ESM 入口（import { initViewer } from 'cesium-easy'） | | dist/index.cjs | CJS 入口（require('cesium-easy')） | | dist/index.umd.js | UMD 入口（<script src="...umd.js">） | | dist/index.d.ts | TypeScript 类型声明 | | dist/image/, dist/data/, dist/video/ | 静态资源 |

ESM / CJS 产物中 cesium 保持 external，使用方需自行提供 Cesium 模块。

Exports

// 核心
export { initViewer, ViewerWrapper } from 'cesium-easy'

// 实体与坐标
export { EntityManager, toCartesian3, toDegrees }

// 模块（200+ 功能）
export { Earth, Scene, Camera, Radar, Plot, Measure, Visibility, … }

// 类型
export type { LngLatAlt, PointOptions }

完整导出列表见 src/index.ts。

发布

使用 Changesets 管理版本：

npx changeset           # 选择版本类型（major / minor / patch）
npx changeset version   # 更新版本号 + CHANGELOG
npm run build
npx changeset publish   # 发布到 npm

项目结构

cesium-easy/
├── src/              # 源码
│   ├── index.ts      # 统一导出
│   ├── core/         # Viewer 初始化
│   ├── modules/      # 功能模块
│   ├── utils/        # 工具函数
│   └── types/        # 类型定义
├── examples/         # 示例 HTML
│   ├── satellite.html
│   ├── radar.html
│   ├── effects/
│   └── preview.html  # 验证 dist 产物
├── public/           # 静态资源（构建时复制到 dist）
├── scripts/
│   └── preview.mjs   # preview 脚本
├── tests/
├── vite.config.ts
├── tsconfig.json
└── package.json