cesium-xs-sdk 1.0.1 → 1.0.3

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
@@ -92,10 +130,30 @@ dist/
 | `GraphicModule` | 点、线、面、模型、文字、标绘图元创建与管理 |
 | `EventModule` | 鼠标、键盘、场景事件订阅与发布 |
 | `EditorModule` | 绘制、编辑、选择、删除等交互工具 |
+| `ControlModule` | 地图控件管理（状态栏、缩放、指南针、比例尺等） |
+
+## 控件系统
+
+SDK 内置参考 Mars3D 的地图控件，可在 `xs3d.init` 时通过 `controls` 配置自动挂载：
+
+```js
+const sdk = xs3d.init('cesiumContainer', {
+  cesiumToken: 'your-ion-token',
+  controls: {
+    locationBar: { showFPS: true },
+    zoom: true,
+    compass: true,
+    distanceLegend: true
+  }
+});
+```
+
+支持的控件：`LocationBar`、`Zoom`、`Compass`、`DistanceLegend`。详见 [控件系统使用文档](docs/controls.md)。
 
 ## 文档
 
-- [SDK 开发指南](../CLAUDE.md)
+- [SDK 开发指南](CLAUDE.md)
+- [控件系统使用文档](docs/controls.md)
 - [军事标绘集成计划](docs/military-plot-sdk-integration-plan.md)
 - [变更记录](docs/change-log/)
 

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;