cesium-xs-sdk 1.0.2 → 1.0.4

package/README.md

@@ -36,17 +36,49 @@ npm install cesium-xs-sdk cesium
 </script>
 ```
 
-### Vue 3
+### Vue 3 / Vite（推荐 SDK 内置插件）
+
+Vite 打包环境下，Cesium 运行时需要额外静态资源（如 `ApproximateTerrainHeights.json`、纹理、Worker 等）。使用 SDK 内置的 Vite 插件，无需手动把 Cesium 复制到 `public/`，开发时自动从 `node_modules/cesium` serve 资源，构建时自动复制到产物目录，离线可用。
+
+```bash
+npm install cesium-xs-sdk cesium
+```
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import { cesiumXsSdkPlugin } from 'cesium-xs-sdk/vite';
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    cesiumXsSdkPlugin({ cesiumBaseUrl: '/Cesium/' })
+  ]
+});
+```
 
 ```js
+// 组件中
 import { useXs3d } from 'cesium-xs-sdk/vue';
 
-const { sdk, sceneModule, graphicModule, isReady } = useXs3d('cesiumContainer', {
-  cesiumToken: 'your-token'
+const { sdk, sceneModule, graphicModule, controlModule, isReady } = useXs3d('cesiumContainer', {
+  cesiumToken: 'your-token',
+  cesiumBaseUrl: '/Cesium/',
+  controls: {
+    locationBar: true,
+    zoom: true,
+    compass: true,
+    distanceLegend: true
+  }
 });
 ```
 
-### Vue 2
+> 插件默认从项目 `node_modules/cesium` 读取资源；若 Cesium 安装位置不同，可传 `cesiumPackageRoot: '/path/to/cesium'`。
+
+如果不使用内置插件，也可以手动复制 `node_modules/cesium/Build/Cesium/` 到 `public/Cesium/`，但内置插件能避免维护这些静态文件。
+
+### Vue 2 / Vue CLI
 
 ```js
 import { useXs3d } from 'cesium-xs-sdk/vue2';
@@ -54,13 +86,16 @@ import { useXs3d } from 'cesium-xs-sdk/vue2';
 export default {
   setup() {
     const { sdk, sceneModule, graphicModule } = useXs3d('cesiumContainer', {
-      cesiumToken: 'your-token'
+      cesiumToken: 'your-token',
+      cesiumBaseUrl: '/Cesium/'
     });
     return { sdk, sceneModule, graphicModule };
   }
 };
 ```
 
+> Vue CLI 项目请将 `node_modules/cesium/Build/Cesium/` 复制到 `public/Cesium/`。
+
 ### React
 
 ```jsx
@@ -68,12 +103,15 @@ import { useXs3d } from 'cesium-xs-sdk/react';
 
 function Map() {
   const { sdk, isReady } = useXs3d('cesiumContainer', {
-    cesiumToken: 'your-token'
+    cesiumToken: 'your-token',
+    cesiumBaseUrl: '/Cesium/'
   });
   return <div id="cesiumContainer" style={{ width: '100%', height: '100%' }} />;
 }
 ```
 
+> React + Vite/CRA 项目同样需要将 `node_modules/cesium/Build/Cesium/` 复制到 `public/Cesium/`。
+
 ## 构建产物
 
 ```text

package/dist/cesium-xs-sdk.cjs.js

@@ -8589,6 +8589,10 @@ class GeoCalcUtil {
 const xs3d = {
     // 初始化 SDK
     init: (container, config = {}) => {
+        // 设置 Cesium 资源基础路径（在创建 Viewer 之前生效）
+        if (config.cesiumBaseUrl && window.Cesium?.buildModuleUrl) {
+            window.Cesium.buildModuleUrl.setBaseUrl(config.cesiumBaseUrl);
+        }
         // 设置 Cesium Token（提前处理，避免内部模块重复设置）
         if (config.cesiumToken) {
             window.Cesium.Ion.defaultAccessToken = config.cesiumToken;