cesium-xs-sdk 1.0.11 → 1.0.13

package/README.md

@@ -1,170 +1,258 @@
-# cesium-xs-sdk
-
-基于 [Cesium 1.137](https://cesium.com/) 封装的轻量级三维 GIS SDK。
-
-> 目标：让 Cesium 常用能力（图层、标绘、事件、编辑）更易用、更统一。
-
-## 安装
-
-### 外网项目（npm）
-
-```bash
-npm install cesium-xs-sdk cesium
-```
-
-### 内网项目（离线包）
-
-从 [Gitee Release](https://gitee.com/d1564427109/cesium-xs-sdk/releases) 下载 `cesium-xs-sdk-v{x.x.x}-offline.zip`，解压后复制到项目。
-
-## 快速开始
-
-### HTML / script 标签
-
-```html
-<link rel="stylesheet" href="Cesium-1.137/Build/Cesium/Widgets/widgets.css" />
-<script src="Cesium-1.137/Build/Cesium/Cesium.js"></script>
-<script src="xs3d/cesium-xs-sdk.umd.js"></script>
-
-<script>
-  const sdk = xs3d.init('cesiumContainer', {
-    cesium: window.Cesium,
-    cesiumToken: 'your-ion-token'
-  });
-
-  sdk.graphicModule.createPoint('p1')
-    .setPosition([116.4, 39.9, 0])
-    .setColor(Cesium.Color.RED);
-</script>
-```
-
-### 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 * as Cesium from 'cesium';
-import { useXs3d } from 'cesium-xs-sdk/vue';
-
-const { sdk, sceneModule, graphicModule, controlModule, isReady } = useXs3d('cesiumContainer', {
-  cesium: Cesium,
-  cesiumToken: 'your-token',
-  cesiumBaseUrl: '/Cesium/',
-  controls: {
-    locationBar: true,
-    zoom: true,
-    compass: true,
-    distanceLegend: true
-  }
-});
-```
-
-> 插件默认从项目 `node_modules/cesium` 读取资源；若 Cesium 安装位置不同，可传 `cesiumPackageRoot: '/path/to/cesium'`。
-
-如果不使用内置插件，也可以手动复制 `node_modules/cesium/Build/Cesium/` 到 `public/Cesium/`，但内置插件能避免维护这些静态文件。
-
-### Vue 2 / Vue CLI
-
-```js
-import * as Cesium from 'cesium';
-import { useXs3d } from 'cesium-xs-sdk/vue2';
-
-export default {
-  setup() {
-    const { sdk, sceneModule, graphicModule } = useXs3d('cesiumContainer', {
-      cesium: Cesium,
-      cesiumToken: 'your-token',
-      cesiumBaseUrl: '/Cesium/'
-    });
-    return { sdk, sceneModule, graphicModule };
-  }
-};
-```
-
-> Vue CLI 项目请将 `node_modules/cesium/Build/Cesium/` 复制到 `public/Cesium/`。
-
-### React
-
-```jsx
-import * as Cesium from 'cesium';
-import { useXs3d } from 'cesium-xs-sdk/react';
-
-function Map() {
-  const { sdk, isReady } = useXs3d('cesiumContainer', {
-    cesium: Cesium,
-    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
-dist/
-├── cesium-xs-sdk.esm.js    # ES Module（Vite / Vue3 / 现代构建工具）
-├── cesium-xs-sdk.cjs.js    # CommonJS（Node / SSR）
-├── cesium-xs-sdk.umd.js    # UMD / 全局变量 xs3d（HTML / script 标签）
-└── cesium-xs-sdk.d.ts      # TypeScript 类型声明
-```
-
-## 核心模块
-
-| 模块 | 说明 |
-|------|------|
-| `SceneModule` | 影像/地形/3D Tiles 图层、坐标转换、相机定位 |
-| `GraphicModule` | 点、线、面、模型、文字、标绘图元创建与管理 |
-| `EventModule` | 鼠标、键盘、场景事件订阅与发布 |
-| `EditorModule` | 绘制、编辑、选择、删除等交互工具 |
-| `ControlModule` | 地图控件管理（状态栏、缩放、指南针、比例尺等） |
-
-## 控件系统
-
-SDK 内置参考 Mars3D 的地图控件，可在 `xs3d.init` 时通过 `controls` 配置自动挂载：
-
-```js
-const sdk = xs3d.init('cesiumContainer', {
-  cesium: Cesium,
-  cesiumToken: 'your-ion-token',
-  controls: {
-    locationBar: { showFPS: true },
-    zoom: true,
-    compass: true,
-    distanceLegend: true
-  }
-});
-```
-
-支持的控件：`LocationBar`、`Zoom`、`Compass`、`DistanceLegend`。详见 [控件系统使用文档](docs/controls.md)。
-
-## 文档
-
-- [SDK 开发指南](CLAUDE.md)
-- [控件系统使用文档](docs/controls.md)
-- [军事标绘集成计划](docs/military-plot-sdk-integration-plan.md)
-- [变更记录](docs/change-log/)
-
-## 许可证
-
-MIT © 成都玄宿科技有限公司
+# cesium-xs-sdk
+
+基于 [Cesium 1.137](https://cesium.com/) 封装的轻量级三维 GIS SDK。
+
+> 目标：让 Cesium 常用能力（图层、标绘、事件、编辑、测量、军标）更易用、更统一。
+
+## 安装
+
+### 外网项目（npm）
+
+```bash
+npm install cesium-xs-sdk cesium
+```
+
+> `cesium` 是 peer dependency，需要业务项目自行安装。
+
+### 内网项目（离线包）
+
+从 [Gitee Release](https://gitee.com/d1564427109/cesium-xs-sdk/releases) 下载 `cesium-xs-sdk-v{x.x.x}-offline.zip`，解压后复制到项目。
+
+## 快速开始
+
+### HTML / script 标签
+
+```html
+<link rel="stylesheet" href="Cesium-1.137/Build/Cesium/Widgets/widgets.css" />
+<script src="Cesium-1.137/Build/Cesium/Cesium.js"></script>
+<script src="xs3d/cesium-xs-sdk.umd.js"></script>
+
+<script>
+  const sdk = xs3d.init('cesiumContainer', {
+    cesium: window.Cesium,
+    cesiumToken: 'your-ion-token'
+  });
+
+  sdk.graphicModule.createPoint('p1')
+    .setPosition([116.4, 39.9, 0])
+    .setColor(Cesium.Color.RED);
+</script>
+```
+
+### 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 * as Cesium from 'cesium';
+import { useXs3d } from 'cesium-xs-sdk/vue';
+
+const {
+  sdk,
+  sceneModule,
+  graphicModule,
+  controlModule,
+  militarySymbolModule,
+  editorModule,
+  isReady
+} = useXs3d('cesiumContainer', {
+  cesium: Cesium,
+  cesiumToken: 'your-token',
+  cesiumBaseUrl: '/Cesium/',
+  controls: {
+    locationBar: true,
+    zoom: true,
+    compass: true,
+    distanceLegend: true
+  }
+});
+```
+
+> 插件默认从项目 `node_modules/cesium` 读取资源；若 Cesium 安装位置不同，可传 `cesiumPackageRoot: '/path/to/cesium'`。
+
+如果不使用内置插件，也可以手动复制 `node_modules/cesium/Build/Cesium/` 到 `public/Cesium/`，但内置插件能避免维护这些静态文件。
+
+### Vue 2 / Vue CLI
+
+```js
+import * as Cesium from 'cesium';
+import { useXs3d } from 'cesium-xs-sdk/vue2';
+
+export default {
+  setup() {
+    const { sdk, sceneModule, graphicModule, militarySymbolModule } = useXs3d('cesiumContainer', {
+      cesium: Cesium,
+      cesiumToken: 'your-token',
+      cesiumBaseUrl: '/Cesium/'
+    });
+    return { sdk, sceneModule, graphicModule, militarySymbolModule };
+  }
+};
+```
+
+> Vue CLI 项目请将 `node_modules/cesium/Build/Cesium/` 复制到 `public/Cesium/`。
+
+### React
+
+```jsx
+import * as Cesium from 'cesium';
+import { useXs3d } from 'cesium-xs-sdk/react';
+
+function Map() {
+  const { sdk, isReady } = useXs3d('cesiumContainer', {
+    cesium: Cesium,
+    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
+dist/
+├── cesium-xs-sdk.esm.js    # ES Module（Vite / Vue3 / 现代构建工具）
+├── cesium-xs-sdk.cjs.js    # CommonJS（Node / SSR）
+├── cesium-xs-sdk.umd.js    # UMD / 全局变量 xs3d（HTML / script 标签）
+└── cesium-xs-sdk.d.ts      # TypeScript 类型声明
+```
+
+## 核心模块
+
+| 模块 | 说明 |
+|------|------|
+| `SceneModule` | 影像/地形/3D Tiles 图层、坐标转换、相机定位 |
+| `GraphicModule` | 点、线、面、模型、文字、标绘图元创建与管理 |
+| `EventModule` | 鼠标、键盘、场景事件订阅与发布 |
+| `EditorModule` | 绘制、编辑、选择、删除、测量等交互工具 |
+| `MilitarySymbolModule` | 军标图标创建、更新、定位、拖拽编辑 |
+| `ControlModule` | 地图控件管理（状态栏、缩放、指南针、比例尺等） |
+
+## 控件系统
+
+SDK 内置参考 Mars3D 的地图控件，可在 `xs3d.init` 时通过 `controls` 配置自动挂载：
+
+```js
+const sdk = xs3d.init('cesiumContainer', {
+  cesium: Cesium,
+  cesiumToken: 'your-ion-token',
+  controls: {
+    locationBar: { showFPS: true },
+    zoom: true,
+    compass: true,
+    distanceLegend: { left: 20, bottom: 20 }
+  }
+});
+```
+
+支持的控件：`LocationBar`、`Zoom`、`Compass`、`DistanceLegend`。其中 `Zoom` 默认挂载在 SDK 统一工具栏，如需自定义位置可传入 `container`。详见 [控件系统使用文档](docs/controls.md)。
+
+## 测量工具
+
+`EditorModule` 内置测距和测面积工具：
+
+```js
+// 测距
+sdk.editorModule.activateMeasureTool(xs3d.MeasureType.DISTANCE);
+
+// 测面积
+sdk.editorModule.activateMeasureTool(xs3d.MeasureType.AREA);
+
+// 监听结果
+sdk.editorModule.onMeasureComplete((result) => {
+  console.log(result.type, result.formatted); // { type: 'distance', formatted: '105.47 km' }
+});
+
+// 清除所有测量结果
+sdk.editorModule.getMeasureTool().clearMeasurements();
+```
+
+交互：左键加点、右键/Enter 完成、Esc 取消、Backspace 撤销上一点。一次测量完成后结果保留在场景中，可连续绘制多个长度/面积。
+
+## 军标模块
+
+`MilitarySymbolModule` 提供军标图元的创建、更新、删除、定位及拖拽编辑：
+
+```js
+// 创建内置军标
+sdk.militarySymbolModule.create('radio-1', {
+  position: [116.4, 39.9, 0],
+  type: 'small-radio',
+  name: '小电台'
+});
+
+// 使用自定义图片
+sdk.militarySymbolModule.create('custom-1', {
+  position: [116.5, 39.9, 0],
+  type: 'my-symbol',
+  iconMode: 'custom',
+  imgUrl: '/icons/my-symbol.png'
+});
+
+// 注册全局默认图标
+sdk.militarySymbolModule.registerDefaultImage('my-symbol', '/icons/my-symbol.png');
+
+// 开启拖拽编辑
+sdk.militarySymbolModule.enableEditMode();
+
+// 定位
+sdk.militarySymbolModule.flyTo('radio-1');
+```
+
+支持的 `iconMode`：`default`（SDK 内置）、`custom`（自定义图片）、`overlay`（在内置图标上叠加自定义图片）。
+
+## 图元定位与外边框
+
+`GraphicModule` 提供针对图元的定位和外边框能力：
+
+```js
+// 飞行定位到图元
+await sdk.graphicModule.flyTo('p1', { duration: 1.5 });
+
+// 瞬间定位
+sdk.graphicModule.zoomTo('p1');
+
+// 为贴地面图元添加外边框（polyline 模拟）
+sdk.graphicModule.setOutline('polygon-1', {
+  enabled: true,
+  color: Cesium.Color.RED,
+  width: 2
+});
+
+// 移除外边框
+sdk.graphicModule.removeOutline('polygon-1');
+```
+
+## 文档
+
+- [SDK 开发指南](CLAUDE.md)
+- [控件系统使用文档](docs/controls.md)
+- [军事标绘集成计划](docs/military-plot-sdk-integration-plan.md)
+- [后续发版操作手册](docs/release/README.md)
+- [变更记录](docs/change-log/)
+
+## 许可证
+
+MIT © 成都玄宿科技有限公司