arc3dlab-sdk

v1.0.0

Published

2 months ago

基于开源项目 Cesium 封装的模块化 WebGIS 应用框架

0High
0Medium
0Low

wangjianlei

3D webGL WebGIS Cesium Arc3DLab Arc3DLab SDK 地图三维地球

Arc3DLab SDK

基于 Cesium 构建的模块化 WebGIS 应用框架

文档: SDK 设计文档 | API 文档 (构建后生成) | 更新日志

✨ 特性

🎯 模块化设计: 按需实例化,灵活组合
🔤 TypeScript: 完整的类型定义
📦 多格式输出: UMD / ESM / CJS
🌐 浏览器直用: 支持 <script> 标签引入
📚 API 文档: 自动生成完整文档
🚀 零侵入: 不修改 Cesium 原生对象

📦 安装

NPM 安装

npm install arc3dlab cesium

CDN 引入

<!-- Cesium -->
<script src="https://cesium.com/downloads/cesiumjs/releases/1.136/Build/Cesium/Cesium.js"></script>
<link href="https://cesium.com/downloads/cesiumjs/releases/1.136/Build/Cesium/Widgets/widgets.css" rel="stylesheet">

<!-- Arc3DLab SDK -->
<script src="https://unpkg.com/arc3dlab/dist/arc3dlab.umd.min.js"></script>

🚀 快速开始

NPM 使用方式

import { Arc3DViewer, Arc3DReminderTip, Arc3DEventEmitter } from 'arc3dlab';
import 'cesium/Build/Cesium/Widgets/widgets.css';

// 创建查看器
const viewer = new Arc3DViewer('container');

// 创建鼠标提示
const tip = new Arc3DReminderTip(viewer);
tip.show = true;
tip.message = 'Hello Arc3DLab!';

// 创建事件管理器
const events = new Arc3DEventEmitter(viewer);
events.on('leftClick', (e) => {
  console.log('Click:', e.position);
});

HTML Script 标签使用方式

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Arc3DLab Demo</title>
  <script src="https://cesium.com/downloads/cesiumjs/releases/1.136/Build/Cesium/Cesium.js"></script>
  <link href="https://cesium.com/downloads/cesiumjs/releases/1.136/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
  <script src="https://unpkg.com/arc3dlab/dist/arc3dlab.umd.min.js"></script>
  <style>
    #map { width: 100%; height: 100vh; margin: 0; }
  </style>
</head>
<body>
  <div id="map"></div>
  <script>
    const viewer = new Arc3DLab.Arc3DViewer('map');
    const tip = new Arc3DLab.Arc3DReminderTip(viewer);
    tip.show = true;
    tip.message = 'Hello Arc3DLab!';
    
    const events = new Arc3DLab.Arc3DEventEmitter(viewer);
    events.on('leftClick', (e) => console.log('Click:', e.position));
  </script>
</body>
</html>

📖 核心 API

Arc3DViewer

三维地球查看器,提供优化的 Cesium Viewer 默认配置。

const viewer = new Arc3DViewer(container, options?);

参数:

container: DOM 元素或 ID
options: 可选配置
- fpsShow: 是否显示帧率
- mapboxController: 是否使用 Mapbox 风格控件
- defaultKey: Cesium Ion 访问令牌

Arc3DEventEmitter

屏幕空间事件管理器。

import { Arc3DViewer, Arc3DEventEmitter } from 'arc3dlab';

const viewer = new Arc3DViewer('container');
const events = new Arc3DEventEmitter(viewer);

events.on('leftClick', (e) => {
  console.log('Click:', e.position);
});

Arc3DReminderTip

鼠标跟随提示框组件。

const tip = new Arc3DReminderTip(viewer);
tip.show = true;
tip.message = 'Click to select';

🎯 常见场景

场景 1: 创建基础地球

import { Arc3DViewer } from 'arc3dlab';

const viewer = new Arc3DViewer('map');

场景 2: 添加鼠标交互

import { Arc3DViewer, Arc3DEventEmitter } from 'arc3dlab';

const viewer = new Arc3DViewer('map');
const events = new Arc3DEventEmitter(viewer);

events.on('leftClick', (e) => {
  console.log('点击位置:', e.position);
});

场景 3: 显示鼠标提示

import { Arc3DViewer, Arc3DReminderTip, Arc3DEventEmitter } from 'arc3dlab';

const viewer = new Arc3DViewer('map');
const tip = new Arc3DReminderTip(viewer);

tip.show = true;
tip.message = '移动鼠标查看坐标';

// 结合事件使用
const events = new Arc3DEventEmitter(viewer);
events.on('mouseMove', (e) => {
  tip.message = `坐标: ${e.endPosition.x}, ${e.endPosition.y}`;
});

场景 4: 获取场景截图

const viewer = new Arc3DViewer('map');

// 获取 base64 图片
const screenshot = viewer.image;

// 下载截图
const link = document.createElement('a');
link.download = 'screenshot.png';
link.href = screenshot;
link.click();

🛠️ 开发

# 安装依赖
npm install

# 构建项目
npm run build

# 监听模式构建
npm run build:watch

# 生成 API 文档
npm run docs

# 监听模式生成文档
npm run docs:watch

# 代码格式化
npm run format

📂 项目结构

Arc3DLab_SDK/
├── src/              # 源代码
│   ├── core/         # 核心模块
│   │   ├── Viewer.ts
│   │   ├── EventEmitter.ts
│   │   └── ui/
│   ├── types/        # 类型定义
│   ├── utils/        # 工具函数
│   └── index.ts      # 入口
├── dist/             # 构建输出
├── docs/             # 文档
├── SDK_DESIGN.md     # 设计文档
└── README.md         # 使用说明

详细结构说明请查看 SDK_DESIGN.md

📝 版本日志

v1.0.0 (2026-05-26)

重大更新: 重构为模块化架构

✨ 新增 Arc3DViewer 替代原 Viewer
✨ 新增 Arc3DEventEmitter 事件管理
✨ 新增 Arc3DReminderTip 鼠标提示
🎯 所有核心类统一使用 Arc3D 前缀
📦 支持 UMD/ESM/CJS 多格式输出
🌐 支持浏览器 <script> 标签直接引入
📚 完善 TypeDoc API 文档生成

详细更新记录请查看 CHANGES.md

🤝 贡献

欢迎提交 Issue 和 Pull Request!

📄 许可证

ISC License - 详见 LICENSE

Made with ❤️ by Arc3DLab Team