jn-cesium 使用指南（Vue 3｜Vite / Webpack）

一个基于 Vue3 的 Cesium 封装组件与工具库。本文提供在 Vite 或 Webpack 中集成的最简说明。

安装

npm i jn-cesium cesium
# 或
yarn add jn-cesium cesium

说明：项目侧显式安装 cesium；库不会强绑定其版本。

在 Vite 中使用

1. 安装静态资源拷贝插件

npm i -D vite-plugin-static-copy

2. 配置 vite.config.ts（或 vite.config.js）

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { viteStaticCopy } from 'vite-plugin-static-copy'

export default defineConfig(() => ({
  plugins: [
    vue(),
    viteStaticCopy({
      targets: [
        { src: 'node_modules/cesium/Build/Cesium/Workers',    dest: 'cesium' },
        { src: 'node_modules/cesium/Build/Cesium/ThirdParty', dest: 'cesium' },
        { src: 'node_modules/cesium/Build/Cesium/Assets',     dest: 'cesium' },
        { src: 'node_modules/cesium/Build/Cesium/Widgets',    dest: 'cesium' }
      ]
    })
  ]
}))

3. 在入口文件设置 CESIUM_BASE_URL 并引入组件

// main.ts / main.js
import { createApp } from 'vue'
import App from './App.vue'

if (typeof window !== 'undefined' && !window.CESIUM_BASE_URL) {
  window.CESIUM_BASE_URL = '/cesium/'
}

import 'cesium/Build/Cesium/Widgets/widgets.css'
import JnCesium, { CesiumViewerComponent } from 'jn-cesium'

const app = createApp(App)
app.use(JnCesium) // 或按需：app.component('CesiumViewerComponent', CesiumViewerComponent)
app.mount('#app')

4. 页面中使用

<template>
  <div style="width:100%;height:100vh;">
    <CesiumViewerComponent />
  </div>
</template>

在 Webpack 中使用（Vue CLI 或自定义）

1. 安装依赖

npm i -D copy-webpack-plugin

2. 在 webpack.config.js 复制 Cesium 资源

const CopyWebpackPlugin = require('copy-webpack-plugin')

module.exports = {
  // ...
  plugins: [
    new CopyWebpackPlugin({
      patterns: [
        { from: 'node_modules/cesium/Build/Cesium/Workers',    to: 'cesium/Workers' },
        { from: 'node_modules/cesium/Build/Cesium/ThirdParty', to: 'cesium/ThirdParty' },
        { from: 'node_modules/cesium/Build/Cesium/Assets',     to: 'cesium/Assets' },
        { from: 'node_modules/cesium/Build/Cesium/Widgets',    to: 'cesium/Widgets' }
      ]
    })
  ]
}

3. 在入口设置 CESIUM_BASE_URL 并引入组件

// main.js
import { createApp } from 'vue'
import App from './App.vue'

if (typeof window !== 'undefined' && !window.CESIUM_BASE_URL) {
  window.CESIUM_BASE_URL = '/cesium/'
}

import 'cesium/Build/Cesium/Widgets/widgets.css'
import JnCesium from 'jn-cesium'

const app = createApp(App)
app.use(JnCesium)
app.mount('#app')

组件与 API（简要）

• CesiumViewerComponent：Vue 组件，模板内直接使用。
• CesiumViewerClass：类封装，需代码控制时可直接实例化。

按需导入：

import { CesiumViewerComponent, CesiumViewerClass, Cesium } from 'jn-cesium'

使用 Image Primitive 指定中心位置与尺寸

import { onMounted, ref } from 'vue'
import { CesiumViewerClass } from 'jn-cesium'

export default {
  setup() {
    const containerRef = ref(null)

    onMounted(() => {
      const viewer = new CesiumViewerClass(containerRef.value)
      viewer.graphic.addImage({
        image: '/textures/logo.png',
        position: { longitude: 116.39, latitude: 39.9, height: 50 },
        dimensions: { width: 500, height: 300 },
        rotation: 15,
        color: '#ffffff'
      })
    })

    return { containerRef }
  }
}

模板中准备 <div ref="containerRef"></div>；position 以度为单位指定中心点，dimensions 为宽高（米）。

使用左上角锚点添加图片

import { onMounted, ref } from 'vue'
import { CesiumViewerClass } from 'jn-cesium'

export default {
  setup() {
    const containerRef = ref(null)

    onMounted(async () => {
      const viewer = new CesiumViewerClass(containerRef.value)
      await viewer.graphic.addImageByCorner({
        image: '/textures/banner.png',
        topLeft: { longitude: 116.38, latitude: 39.92, height: 80 },
        width: 600,
        color: '#ffffff',
        displayMode: 'plane'
      })
    })

    return { containerRef }
  }
}

topLeft 为图片左上角（西北角）位置，经纬度单位为度；width/height 表示沿东西、南北方向的距离（米），图片保持正北朝上。若只提供其中一个尺寸，将按照图片原始宽高比计算另一个尺寸；可通过 displayMode（取值 'plane' 或 'ground'）或布尔参数 clampToGround 控制是否贴地渲染（默认悬浮于 topLeft.height 指定的高度）。

常见问题

• 黑屏或 WebGL 警告：确保 CESIUM_BASE_URL 指向包含 Workers/ThirdParty/Assets/Widgets 的目录。
• 无样式：确认已引入 cesium/Build/Cesium/Widgets/widgets.css。
• 生产环境路径：将 window.CESIUM_BASE_URL 设置为你的部署前缀（如 '/static/cesium/'）。