npm - @metagl/sdk-plotting - Versions diffs - 0.0.1 → 0.0.3 - Mend

@metagl/sdk-plotting 0.0.1 → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (486) hide show

package/README.md CHANGED Viewed

@@ -1,86 +1,267 @@
-# geovisearthsdk_web - plotting 模块 README
-## 简介
-plotting 模块为 GeovisEarth Web SDK 提供矢量绘制、标注与图形交互的封装组件，便于在地图上创建、编辑与管理点、线、面、标注等图形要素。
-## 主要功能
-- 创建点、线、面、文本标注、图标等要素
-- 支持要素样式配置（颜色、宽度、图标、透明度等）
-- 要素编辑（拖拽、顶点编辑、删除）
-- 支持要素分组与图层管理
-- 事件绑定（点击、悬停、编辑开始/结束等）
-- 批量导入/导出 GeoJSON
-## 快速开始
-安装（npm）
-```bash
-npm install @metagl/sdk-plotting
-```
-浏览器引入（UMD）
-```html
-<script src="path/to/sdk-plotting.js"></script>
-```
-初始化并创建一个点
-```js
-import { Plotting } from '@metagl/sdk-plotting';
-const map = new GeoMap({ container: 'map' });
-const plotting = new Plotting({ map });
-const marker = plotting.createPoint({
-    position: [116.397389, 39.908860],
-    style: { color: '#ff0000', size: 12 }
-});
-plotting.add(marker);
-```
-## 基本 API（概览）
-- Plotting(options)
-    - map: 地图实例
-    - zIndex, defaultStyle 等
-- createPoint({ position, style })
-- createLine({ positions, style })
-- createPolygon({ positions, style })
-- createLabel({ position, text, style })
-- add(feature) / remove(feature) / clear()
-- edit(feature) / stopEdit()
-- toGeoJSON() / fromGeoJSON(geojson)
-- on(event, handler) / off(event, handler)
-常见事件：'click'、'dblclick'、'pointermove'、'editstart'、'editend'、'create'
-## 配置示例
-```js
-const plotting = new Plotting({
-    map,
-    defaultStyle: {
-        point: { color: '#3388ff', size: 8 },
-        line: { color: '#33aa33', width: 3 },
-        polygon: { fillColor: 'rgba(51,136,255,0.2)', strokeColor: '#3388ff' }
-    }
-});
-```
-## 编辑与交互
-- 通过 plotting.edit(feature) 启动编辑模式
-- 支持拖动顶点、添加/删除顶点
-- 编辑完成触发 'editend' 事件，可获取最新 GeoJSON
-## 导入/导出
-```js
-const geojson = plotting.toGeoJSON();
-plotting.fromGeoJSON(geojson);
-```
-## 常见问题
-- 要素不可见：检查图层可见性及样式透明度、地图投影设置
-- 编辑失败：确保 feature 已添加到 plotting 管理器并传入正确坐标格式
-## 贡献
-欢迎提交 issue 与 PR。请遵守项目代码风格并补充单元测试。
-## 许可证
-ISC
+# @metagl/sdk-plotting
+GeovisEarth SDK Plotting 模块，为 GeovisEarth Web SDK 提供矢量绘制、标注与图形交互的封装组件，支持在 Cesium 地图上创建、编辑与管理点、线、面、标注等图形要素。
+## 两种使用方式
+### 方式一：HTML script 标签引入（UMD 方式）
+适用于传统 HTML 页面，通过 `<script>` 标签直接引入，通过全局变量 `LACDT` 访问 API。
+**前置依赖：** 需先引入 Cesium。
+```html
+<!DOCTYPE html>
+<html lang="zh">
+<head>
+  <meta charset="utf-8" />
+  <!-- 1. 引入 Cesium -->
+  <link href="https://io-qos.geovisearth.com/getfile/46/brainsim-cdn/open/cesiumjs/1.136/Widgets/widgets.css" rel="stylesheet">
+  <script src="https://io-qos.geovisearth.com/getfile/46/brainsim-cdn/open/cesiumjs/1.136/Cesium.js"></script>
+  <!-- 2. 引入 sdk-plotting（线上 CDN 或本地文件） -->
+  <script src="https://io-qos.geovisearth.com/getfile/46/brainsim-cdn/open/sdk/lacdt.plotting.js"></script>
+  <!-- 本地引入：<script src="./lib/lacdt.plotting.js"></script> -->
+</head>
+<body>
+  <div id="cesiumContainer" style="width:100%;height:100%"></div>
+  <script>
+    // 初始化 Cesium
+    const viewer = new Cesium.Viewer('cesiumContainer');
+    // 3. 通过全局对象 LACDT 使用 plotting
+    const plotting = new LACDT.Plotting({ viewer });
+    // 使用 API 创建要素
+    const point = plotting.createPoint({
+      position: [116.397389, 39.908860]
+    });
+    plotting.add(point);
+  </script>
+</body>
+</html>
+```
+**资源文件说明：** 打包产物中 `resources/` 目录包含图片、纹理等静态资源，需与 JS 文件保持相对路径关系。如果自定义了部署路径，需确保 `resources/` 目录可被访问。
+---
+### 方式二：npm import 引入（ESM 方式）
+适用于 Vue/Vite/Webpack 等现代前端工程化项目，通过 ES Module 动态导入。
+#### 1. 安装
+```bash
+# npm 官方源
+npm install @metagl/sdk-plotting
+# 或本地 file 引用（开发调试阶段）
+npm install @metagl/sdk-plotting@file:../../sdk-plotting/publish
+```
+#### 2. Vite 项目配置要点
+##### 2.1 Cesium 别名映射
+sdk-plotting 打包时将 Cesium 标记为 external（全局变量 `Cesium`），但 Vite 按模块名解析时需要映射：
+```js
+// vite.config.js
+import { defineConfig } from 'vite'
+import path from 'path'
+export default defineConfig({
+  resolve: {
+    alias: {
+      // 关键：将 UMD external 的 'Cesium' 映射到 npm 包名 'cesium'
+      'Cesium': 'cesium',
+    }
+  },
+  define: {
+    // Cesium 静态资源路径
+    CESIUM_BASE_URL: JSON.stringify('/cesium')
+  },
+  optimizeDeps: {
+    include: ['cesium']
+  }
+})
+```
+##### 2.2 静态资源拷贝
+sdk-plotting 的 `resources/` 目录（图片、纹理等）需要通过 `vite-plugin-static-copy` 或其他方式复制到构建输出：
+```js
+// vite.config.js
+import { viteStaticCopy } from 'vite-plugin-static-copy'
+export default defineConfig({
+  plugins: [
+    viteStaticCopy({
+      targets: [
+        // Cesium 静态资源
+        {
+          src: 'node_modules/cesium/Build/Cesium/*',
+          dest: 'cesium'
+        },
+        // sdk-plotting 资源
+        {
+          src: 'node_modules/@metagl/sdk-plotting/resources',
+          dest: 'resources'
+        }
+      ]
+    })
+  ],
+  // 如果代码中通过 /lib/resources 路径请求资源，配置代理
+  server: {
+    proxy: {
+      '/lib/resources': {
+        target: 'http://localhost:9521',
+        changeOrigin: true,
+        rewrite: (path) => path.replace('/lib/resources', '/resources')
+      }
+    }
+  }
+})
+```
+##### 2.3 入口文件加载
+UMD 格式需要通过动态 import 加载，并在加载后将全局变量 `LACDT` 和 `window.Cesium` 暴露出来：
+```js
+// main.js
+import { createApp } from 'vue'
+import App from './App.vue'
+// 解冻 Cesium（使 sdk-plotting 能扩展 Cesium 对象）
+function makeExtensible(obj) {
+  const newObj = Object.create(Object.getPrototypeOf(obj))
+  Object.getOwnPropertyNames(obj).forEach(key => {
+    const descriptor = Object.getOwnPropertyDescriptor(obj, key)
+    if (descriptor) {
+      Object.defineProperty(newObj, key, {
+        ...descriptor,
+        configurable: true,
+        writable: true
+      })
+    }
+  })
+  return newObj
+}
+async function bootstrap() {
+  // 1. 加载 Cesium
+  const CesiumModule = await import('cesium')
+  let cesium = CesiumModule.default || CesiumModule
+  cesium = makeExtensible(cesium)
+  window.Cesium = cesium
+  // 2. 加载 sdk-plotting（动态 import）
+  await import('@metagl/sdk-plotting')
+  // 3. 此时 LACDT 全局对象已就绪
+  const app = createApp(App)
+  app.config.globalProperties.$metaGL = window.LACDT
+  app.config.globalProperties.$cesium = window.Cesium
+  app.mount('#app')
+}
+bootstrap()
+```
+#### 3. Webpack 项目配置要点
+Webpack 项目需配置 Cesium 为 external：
+```js
+// webpack.config.js
+module.exports = {
+  externals: {
+    cesium: 'Cesium'
+  }
+}
+```
+---
+## 主要功能
+- 创建点、线、面、文本标注、图标等要素
+- 支持要素样式配置（颜色、宽度、图标、透明度等）
+- 要素编辑（拖拽、顶点编辑、删除）
+- 支持要素分组与图层管理
+- 事件绑定（点击、悬停、编辑开始/结束等）
+- 批量导入/导出 GeoJSON
+- 军事标会、箭头、扇形、椭圆等多种军事图形
+- 热力图、OD 线、三维体（立方体、圆柱体）等分析效果
+## 快速开始
+初始化并创建一个点：
+```js
+// UMD 方式
+const plotting = new LACDT.Plotting({ viewer });
+// npm import 方式
+import { Plotting } from '@metagl/sdk-plotting';
+const plotting = new Plotting({ viewer });
+// 创建点
+const marker = plotting.createPoint({
+  position: [116.397389, 39.908860],
+  style: { color: '#ff0000', size: 12 }
+});
+plotting.add(marker);
+```
+## 基本 API（概览）
+- **Plotting(options)**
+  - `viewer`: Cesium Viewer 实例
+  - `zIndex`, `defaultStyle` 等
+- **createPoint**({ position, style })
+- **createLine**({ positions, style })
+- **createPolygon**({ positions, style })
+- **createLabel**({ position, text, style })
+- **add**(feature) / **remove**(feature) / **clear**()
+- **edit**(feature) / **stopEdit**()
+- **toGeoJSON**() / **fromGeoJSON**(geojson)
+- **on**(event, handler) / **off**(event, handler)
+常见事件：`click`、`dblclick`、`pointermove`、`editstart`、`editend`、`create`
+## 构建
+```bash
+npm run build         # webpack 生产构建
+npm run build:rollup  # rollup 构建
+npm run build:dts     # 生成类型声明文件
+```
+构建产物输出到 `lib/` 目录，`npm run build` 会自动将产物复制到 `publish/` 目录。
+## 发布
+```bash
+npm run login        # 登录 npm
+cd publish && npm publish --access public  # 发布
+```
+## 常见问题
+### UMD 方式
+- **资源 404**：确保 `resources/` 目录与 `lacdt.plotting.js` 保持正确的相对路径
+- **LACDT 未定义**：确保 `lacdt.plotting.js` 在 Cesium 之后加载
+### npm import 方式
+- **Cannot assign to "e" because it is a constant**：构建产物问题，需重新 `npm run build`
+- **Cesium could not be resolved**：在 `vite.config.js` 中添加 `'Cesium': 'cesium'` 别名
+- **SDK 无法扩展 Cesium**：UMD 格式的 SDK 会扩展 `window.Cesium`，需在 import 之前确保 Cesium 已挂载到 `window`，且对象未被 `Object.freeze()`
+## 许可证
+ISC