# vue3-use-cesium

> 在 Vue3 中简洁、快速的使用 Cesium

Latest version **0.0.40** (published 2026-03-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install vue3-use-cesium
pnpm add vue3-use-cesium
yarn add vue3-use-cesium
bun add vue3-use-cesium
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.0.40 |
| Published | 2026-03-31 |
| First published | 2023-07-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 4.9 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Hxy1992 |
| Maintainers | hxy1992 |
| Keywords | vue3, cesium, use |

## Links

- npm: https://www.npmjs.com/package/vue3-use-cesium
- Homepage: https://github.com/Hxy1992/vue3-use-cesium
- npm.io page: https://npm.io/package/vue3-use-cesium

## Dependencies (1)

- [supercluster](https://npm.io/package/supercluster.md) ^8.0.1

## Alternatives

- [adhdev](https://npm.io/package/adhdev.md) — 11.1K weekly downloads
- [react-slide-button](https://npm.io/package/react-slide-button.md) — 310 weekly downloads
- [better](https://npm.io/package/better.md) — 42 weekly downloads
- [react-native-swipe-image](https://npm.io/package/react-native-swipe-image.md) — 22 weekly downloads
- [nl.fokkezb.pulltorefresh](https://npm.io/package/nl.fokkezb.pulltorefresh.md) — 11 weekly downloads

## Recent versions

- 0.0.40 (latest) — 2026-03-31
- 0.0.38 — 2026-01-21
- 0.0.37 — 2026-01-21
- 0.0.36 — 2026-01-20
- 0.0.35 — 2026-01-20
- 0.0.34 — 2026-01-20
- 0.0.33 — 2026-01-19
- 0.0.31 — 2025-08-29
- 0.0.30 — 2025-06-16
- 0.0.29 — 2025-05-27
- 0.0.28 — 2025-05-20
- 0.0.27 — 2025-05-14
- 0.0.26 — 2025-05-09
- 0.0.24 — 2025-05-06
- 0.0.23 — 2025-05-06
- … 20 more at https://npm.io/package/vue3-use-cesium/versions

## README

# vue3-use-cesium

基于 Vue3、Typescrip、Cesium 的组件库。

### 功能 📖

基于 pnpm workspace、vite、glup、rollup 脚手架，依赖 Vue3、Cesium 开发的 CBB 公共库——vue3-use-cesium
有以下特点/功能：

- 可支持 Cesium 库的按需加载
- 基于 vue3 传送组件，实现多页面复用单个 Cesium 实例，防止频繁切换地图导致的卡顿，非首次地图无感加载
- 支持封装 hook，使用简单
- 支持地形、事件管理、图层管理、图层弹窗等
- 支持地图工具（主页、底图图层、放大缩小、二三维切换等）、地图状态信息（鼠标位置、相机信息）
- 支持标绘功能，绘制点线面、贴地/贴模型绘制等等，结果可输出 geojson
- 支持测量功能，坐标测量(椭球/地形/模型)、距离测量(椭球/地形/模型/贴地/贴模型) 、面积测量(椭球/地形/模型/贴地/贴模型) 、高度差测量(地形/模型) 、三角测量(地形/模型)
- 支持点聚合
- 支持场景书签
- 支持常用 Entity、Primitive 材质，如光电扫描球、颜色扫描球、雷达扫描、扩散圆、渐变墙、闪烁线等等
- 支持热力图

关于 Cesium 版本兼容性，已在 1.105、1.119 版本进行验证。

### 快速开始 📔

- **安装**

```bash
yarn add vue3-use-cesium # npm i vue3-use-cesium --save
```

- **使用**

1. 引入组件和样式

在 App.vue 中使用组件，示例如下：

```vue
<template>
	<router-view></router-view>
	<z-map-base />
</template>
<script setup lang="ts">
import { ZMapBase } from "vue3-use-cesium";
</script>
```

在 main.js 引入样式：

```typescript
import "vue3-use-cesium/style";
```

2. 在路由拦截中加载初始化并加载 Cesium.js

```typescript
import { initMap } from "vue3-use-cesium";
// 路由拦截
router.beforeEach(async (to, from, next) => {
	// ...

	// 如果页面包含地图则加载Cesium.js
	if (to.meta.hasMap) {
		await initMap([`/CesiumV1.105/Cesium.js`, `/CesiumV1.105/Widgets/widgets.css`], {
			imagery: "gd-img"
		});
	}

	// ...
	next();
});
```

3. 定义 hooks（可选）

```typescript
import { onBeforeUnmount, onMounted } from "vue";
import { setToTarget, setVisible, clearMapElements, clearMapEvents, getViewer } from "vue3-use-cesium";

/**
 * 基础地图使用
 * @param selector div的id / body
 * @param mapCreated 成功回调(返回Viewer)
 */
export const useBaseMap = (selector: string, mapCreated?: (viewer: any) => void) => {
	onMounted(() => {
		setToTarget(selector);
		setVisible(true);
		if (mapCreated) {
			mapCreated(getViewer());
		}
	});
	onBeforeUnmount(() => {
		clearMapElements();
		clearMapEvents();
		setVisible(false);
		setToTarget("body");
	});
};
```

4. 页面使用

```vue
<template>
	<!-- 注意：HTML注释得去掉，可能是Vue传送组件的bug？？ -->
	<!-- 只有一个顶层div -->
	<div class="bbox">
		<!-- 地图容器不能是顶层div -->
		<div id="my-map">
			<!-- 地图弹窗... -->
		</div>
		<!-- 地图面板等... -->
	</div>
</template>

<script setup lang="ts">
import { useBaseMap } from "@/hooks/useCesium";

// 地图初始化
useBaseMap("#my-map", viewer => {
	console.log(viewer);
});
</script>
```

---
_Source: https://npm.io/package/vue3-use-cesium · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._