npm - @yangyongtao/gaea - Versions diffs - 1.1.11 → 1.1.13 - Mend

@yangyongtao/gaea 1.1.11 → 1.1.13

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 (11) hide show

package/CHANGELOG.md +5 -0
package/README.md +178 -52
package/package.json +5 -3
package/scripts/postinstall.mjs +18 -107
package/src/GaeaMethods.js +127 -38
package/src/components/VectorPolygonControl.vue +396 -0
package/src/components/index.cjs +6 -0
package/src/components/index.js +1 -0
package/src/index.cjs +11 -0
package/src/plugin.cjs +6 -0
package/USAGE.md +0 -200

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,10 @@
 # Changelog
+## [1.1.13] - 2026-07-10
+### Added
+- 支持 CommonJS 引入（`require`），同时兼容 ESM 和 CJS 项目
 ## [1.1.6] - 2026-07-01
 ### Changed

package/README.md CHANGED Viewed

@@ -1,18 +1,29 @@
 # @yangyongtao/gaea
-Gaea 3D 可视化组件库 — 基于 Godot WASM 引擎的 Vue 3 组件包。
+基于 Godot WASM 引擎的 Vue 3 三维可视化组件库。提供影像/地形/贴地线加载、相机视角控制、图层树、天气控制、沿线飞行、断面游览、室内游览等能力，并内置 Vite 插件自动注入引擎资源。
-## 安装
+> 完整可运行示例参考消费者项目的 `src/App.vue`，本文所有片段均以其为参考。
+---
+## 1. 安装
 ```bash
 npm install @yangyongtao/gaea
 ```
-## 快速开始
+peerDependencies（按需安装）：`vue ^3.4`、`element-plus ^2.6`（可选）、`pinia ^2.1`（可选）。
+> ⚠️ 引擎大资源文件（`Gaea.pck` / `Gaea.wasm` / `1111.res` / `gltf` 等）**不随 npm 包分发**，需手动放置，详见第 8 节。
-### 1. `vite.config.js`
+---
+## 2. Vite 配置
+引入并注册 `gaeaVitePlugin`，它会自动注入 `Gaea.js`、提供引擎静态资源、设置 SharedArrayBuffer 所需的跨域隔离响应头。
 ```js
+// vite.config.js
 import { defineConfig } from 'vite';
 import vue from '@vitejs/plugin-vue';
 import { gaeaVitePlugin } from '@yangyongtao/gaea/plugin';
@@ -24,95 +35,210 @@ export default defineConfig({
 });
 ```
-### 2. `src/App.vue`
+---
+## 3. 快速开始
+页面里需要一个 `id="canvas"` 的画布。调用 `setConfig(...)` 后 `new GaeaApp()` 即可自动完成「引擎启动 → 环境初始化 → 图层加载 → 模型加载」。
 ```vue
 <template>
   <div id="gaea-app">
+    <div class="toolbar">
+      <button @click="showWeather = !showWeather">天气控制</button>
+      <button @click="showFly = !showFly">沿线飞行</button>
+      <button @click="showLayerTree = !showLayerTree">图层控制</button>
+      <WaterGateTour />
+    </div>
-    <div class="canvas-area">
+    <div class="canvas-area" id="canvas-container">
       <canvas id="canvas"></canvas>
     </div>
+    <WeatherControl v-if="showWeather" :appInstance="app" @close="showWeather = false" />
+    <FlyAlongRoute v-if="showFly" :appInstance="app" @close="showFly = false" />
+    <LayerTree v-if="showLayerTree" :appInstance="app" @close="showLayerTree = false" @node-click="onLayerNodeClick" />
+    <HydrologicStationDialog />
+    <SecTourView />
   </div>
 </template>
 <script setup>
 import { ref } from 'vue';
 import { GaeaApp, setConfig } from '@yangyongtao/gaea';
+import { WeatherControl, FlyAlongRoute, HydrologicStationDialog, SecTourView, WaterGateTour } from '@yangyongtao/gaea/components';
+import LayerTree from '@yangyongtao/gaea/components/LayerTree.vue';
-// 配置
 setConfig({
-  serveLocal: `${window.location.origin}/static/`,
+  serveLocal: `${window.location.origin}/static`,
   serveUrl: 'http://192.168.3.151:8088/gaeaExplorerServer/',
-  defaultLayers: [
-    { layerName: 'earthland', forMat: 'image/png', min: 0, max: 18, transparency: 0.3 },
-    { layerName: '苍南L19', forMat: 'image/png', min: 5, max: 17 },
-  ],
-  useTianditu: true,
-  tiandituToken: '4ebb3872e465273416314341a99caea6',
+  serviceMode: 'platform',
   defaultCameraPosition: '27.3680928977018,120.414139621887,0,109379.690132486,0,0',
 });
-// 初始化（自动完成：引擎启动 → 环境初始化 → 图层加载）
 const app = new GaeaApp();
-window.APP = app;
+window.APP = app;               // 组件内部通过 window.APP 兜底获取实例
 const showWeather = ref(false);
 const showFly = ref(false);
+const showLayerTree = ref(false);
+function onLayerNodeClick({ node }) {
+  app.flyToNode(node);
+}
 </script>
 ```
-## API
+---
+## 4. setConfig 配置项
-### 配置项
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `serveLocal` | string | `''` | 引擎本地静态资源地址（AssetHost），一般为 `${origin}/static` |
+| `serveUrl` | string | `''` | 服务平台地址（WMTS 影像 / 地形 / 贴地线均基于此） |
+| `serviceMode` | `'platform' \| 'online'` | `'platform'` | **服务模式**：见下方说明 |
+| `tiandituToken` | string | — | 在线模式的天地图 token |
+| `tiandituLevelRange` | [number,number] | `[0,18]` | 天地图层级范围 |
+| `defaultLayers` | Array | 见下 | 服务平台模式下加载的影像图层 |
+| `defaultTerrains` | Array | 见下 | 服务平台模式下加载的地形服务 |
+| `defaultGroundLines` | Array | 见下 | 服务平台模式下加载的贴地线 |
+| `defaultCameraPosition` | string | — | 初始相机视角：`纬度,经度,高程,相机高,俯仰,朝向` |
+| `layerCategories` | Array | 内置 | 图层树分类数据（接口数据会合并进来） |
+| `dataHubApiUrl` | string | `''` | 图层树数据接口地址，为空则只用默认数据 |
+| `onProgress` | function | — | 引擎加载进度回调 `(cur, total) => {}` |
+### 4.1 serviceMode —— 服务模式（区分「服务平台」与「在线」）
+- `'platform'`（服务平台）：影像走 `serveUrl` 的 WMTS，并加载 `defaultTerrains` 地形、`defaultGroundLines` 贴地线。
+- `'online'`（在线）：**仅加载天地图影像**，不加载地形和贴地线（在线模式目前只有天地图一种影像来源）。
 ```js
-import { setConfig } from '@yangyongtao/gaea';
+setConfig({ serviceMode: 'platform' });  // 内网/服务平台
+// 或
+setConfig({ serviceMode: 'online', tiandituToken: '你的token' }); // 在线（天地图）
+```
-setConfig({
-  serveUrl: '',           // WMTS 服务地址
-  serveLocal: '',          // 静态资源地址
-  defaultLayers: [],       // 默认影像图层
-  defaultCameraPosition: 'lat,lng,alt,dist,pitch,heading',
-  onProgress: (cur, total) => {},  // 引擎加载进度回调
-});
+### 4.2 defaultLayers —— 影像图层（服务平台模式）
+```js
+defaultLayers: [
+  { layerName: 'earthland', forMat: 'image/png', min: 0, max: 18, transparency: 0.3 },
+  { layerName: '苍南L19',   forMat: 'image/png', min: 5, max: 17 },
+]
+```
+- `layerName`：WMTS 服务里的图层名（Title）
+- `forMat`：影像格式，如 `image/png`、`image/jpeg`
+- `min` / `max`：显示层级范围
+- `transparency`：透明度（可选）
+### 4.3 defaultTerrains —— 地形服务（服务平台模式）
+```js
+defaultTerrains: [
+  { name: '苍南县地形', url: 'htc/service/tms/1.0.0/苍南县地形@EPSG%3A4326@terrain/' },
+]
 ```
+- `name`：地形名称
+- `url`：相对 `serveUrl` 的路径（也支持传完整 `http(s)://` 地址）
+- 空数组 `[]` 则不加载地形
+### 4.4 defaultGroundLines —— 贴地线（服务平台模式）
-### GaeaApp 方法
+依赖 `serveUrl` 的 WMTS 矢量线服务（自动通过 `getAllServe` 获取服务列表后按名匹配）。
+```js
+defaultGroundLines: [
+  { name: '苍南县边界',        range: [0, 9],   color: [255, 255, 0],   index: 100 },
+  { name: '苍南县镇边界',      range: [9, 15],  color: [0, 255, 0],     index: 80 },
+  { name: '苍南县村边界',      range: [15, 19], color: [255, 255, 255], index: 60 },
+  { name: '沿浦海塘工程范围线', range: [0, 21],  color: [0, 255, 255],   index: 120 },
+]
+```
+- `name`：矢量线服务名（Title）
+- `range`：显示层级范围 `[min, max]`
+- `color`：线颜色 `[r, g, b]`（0-255）
+- `index`：渲染优先级
+- 每项可加 `isInitLoad: false` 跳过该条
+---
+## 5. 组件说明
+组件从 `@yangyongtao/gaea/components` 导入；`LayerTree` 需按路径单独导入。多数交互组件接收 `:appInstance="app"`，未传时内部回退到 `window.APP`。
+| 组件 | 说明 | 主要事件 |
+|------|------|----------|
+| `WeatherControl` | 天气/台风控制面板（含台风路线拾取与播放） | `@close` |
+| `FlyAlongRoute` | 沿线飞行：地图拾取点位，可设飞行高度/时长 | `@close` |
+| `LayerTree` | 图层树，点击节点飞行定位 | `@close`、`@node-click` |
+| `HydrologicStationDialog` | 水文测站弹窗，自监听 `gaea-icon-click` 事件 | — |
+| `SecTourView` | 断面游览滚动条，模型锁定后显示 | — |
+| `WaterGateTour` | 室内游览按钮（下拉选择水闸模型） | — |
+---
+## 6. 常用实例方法（window.APP / app）
 | 方法 | 说明 |
 |------|------|
-| `new GaeaApp(options)` | 创建实例，自动初始化引擎/环境/图层 |
-| `app.getAllServe()` | 获取 WMTS 服务图层列表 |
-| `app.addLayer({ layerName, forMat, min, max, transparency })` | 添加影像图层 |
-| `app.SetPosition('lat,lng,alt,dist,pitch,heading')` | 定位到指定视角 |
-| `app.favorite()` | 记录当前视角，返回 URI 字符串 |
-| `app.favoritePosition(uri)` | 恢复已保存的视角 |
-| `app.ready` | Promise，等待初始化完成 |
+| `SetPosition('纬度,经度,高程,相机高,俯仰,朝向')` | 定位到指定视角 |
+| `flyToNode({ position:{x,y,z} })` | 飞到指定位置 |
+| `flyAlongPath(lineData, options)` | 沿线飞行，`lineData=[{x:纬度,y:经度,z:高度}]`，`options={duration,xrotation,lockEye,...}` |
+| `stopFlyAlongPath()` | 停止沿线飞行 |
+| `cameraReset()` | 相机复位到 `defaultCameraPosition` |
+| `addInitTerrainServer(terrains?)` | 手动加载地形（不传则用 `defaultTerrains`） |
+| `addGroundLines(lines?)` | 手动加载贴地线（不传则用 `defaultGroundLines`） |
+| `addTyphoonRoute(pointList, options)` | 加载台风路线并播放动画 |
+| `clearTyphoonRoute()` | 清除台风路线 |
+| `getAllServe()` | 获取 WMTS 服务图层列表 |
+| `addLayer({ layerName, forMat, min, max, transparency })` | 添加影像图层 |
+| `favorite()` / `favoritePosition(uri)` | 记录 / 恢复视角 |
-### Vue 组件
+---
-```vue
-<script setup>
-import { WeatherControl, FlyAlongRoute } from '@yangyongtao/gaea/components';
+## 7. 注意事项
-const app = window.APP;
-const show = ref(false);
-</script>
+- 页面必须存在 `id="canvas"` 的 `<canvas>`，引擎会挂载到它上面。
+- 需要跨域隔离（COOP/COEP）才能启用 SharedArrayBuffer，`gaeaVitePlugin` 已自动处理；首次进入若未隔离会自动刷新一次。
+- 服务平台模式下地形/贴地线依赖 `serveUrl` 对应服务，若服务器无对应服务名，控制台会打印「未找到/加载失败」警告，不影响其它功能。
+- 大体积引擎资源不随 npm 包分发，需手动放置，详见第 8 节。
-<template>
-  <WeatherControl :appInstance="app" @close="show = false" />
-  <FlyAlongRoute :appInstance="app" @close="show = false" />
-</template>
+---
+## 8. 大资源文件的放置
+引擎运行需要的大文件体积过大，**不包含在 npm 包内，也不会自动下载**（`postinstall` 仅做检测与提示）。请通过内网传输或手动拷贝的方式，将它们放到消费者项目里 gaea 包的 `public` 目录下。
+### 8.1 需要放置的文件
+放置目标目录：`node_modules/@yangyongtao/gaea/public/`
+| 文件 / 目录 | 目标位置 | 参考大小 | 说明 |
+|------|------|------|------|
+| `Gaea.pck` | `public/Gaea.pck` | ~450 MB | 引擎主资源包 |
+| `Gaea.wasm` | `public/Gaea.wasm` | ~16 MB | 引擎 WASM |
+| `1111.res` | `public/static/1111.res` | **~34.6 MB** | 点图标/纹理资源包（务必用完整版，见下方警告） |
+| `gltf/` | `public/static/gltf/` | 若干 | 断面/水闸等 GLTF 模型 |
+> ⚠️ **重要**：`1111.res` 必须使用 **完整版（约 34.6 MB）**。早期存在一个残缺的 6.5MB 版本，会导致点图标纹理为空、加载台风路线时引擎崩溃（`SimpleFeatureRenderer.CombineSymbolMeshs` 空引用）。放置后可用文件大小快速校验。
+### 8.2 校验是否就位
+```powershell
+# Windows PowerShell
+Get-Item node_modules/@yangyongtao/gaea/public/Gaea.pck | Select-Object Length
+Get-Item node_modules/@yangyongtao/gaea/public/static/1111.res | Select-Object Length
 ```
+`Gaea.pck` 约 450MB、`1111.res` 约 34.6MB 即为正确。
+### 8.3 注意事项
-### 其他导出
+- 更换 `1111.res` 后，若浏览器曾加载过旧的残缺资源，引擎会把资源按名缓存进持久化虚拟文件系统，需**强制刷新（Ctrl+Shift+R）**一次；本库已用版本化资源名规避该缓存问题。
+- 若不放置这些文件，`npm install` 后控制台会打印提示，且页面无法正常渲染三维场景。
+- CI 等无需下载/提示的环境，可设置环境变量 `GAEA_SKIP_DOWNLOAD=1` 跳过 postinstall 提示。
-| 导出 | 路径 | 说明 |
-|------|------|------|
-| `GaeaApp`, `setConfig`, `getConfig` | `@yangyongtao/gaea` | 核心功能 |
-| `loadResource`, `screenToLatLng` | `@yangyongtao/gaea` | 工具函数 |
-| `WeatherControl`, `FlyAlongRoute` | `@yangyongtao/gaea/components` | Vue 组件 |
-| `gaeaVitePlugin`, `GaeaPlugin` | `@yangyongtao/gaea/plugin` | Vite 插件 / v-drag 指令 |
+---
 ## License

package/package.json CHANGED Viewed

@@ -1,22 +1,25 @@
 {
   "name": "@yangyongtao/gaea",
-  "version": "1.1.11",
+  "version": "1.1.13",
   "description": "Gaea 3D visualization component library - Vue 3 components based on Godot WASM engine. Includes WMTS layer loading, camera view control, Vite plugin auto-injection, etc.",
   "type": "module",
-  "main": "src/index.js",
+  "main": "src/index.cjs",
   "module": "src/index.js",
   "exports": {
     ".": {
       "import": "./src/index.js",
+      "require": "./src/index.cjs",
       "default": "./src/index.js"
     },
     "./components": {
       "import": "./src/components/index.js",
+      "require": "./src/components/index.cjs",
       "default": "./src/components/index.js"
     },
     "./components/*": "./src/components/*",
     "./plugin": {
       "import": "./src/plugin.js",
+      "require": "./src/plugin.cjs",
       "default": "./src/plugin.js"
     }
   },
@@ -24,7 +27,6 @@
     "src/",
     "scripts/",
     "README.md",
-    "USAGE.md",
     "CHANGELOG.md",
     "public/*.js",
     "public/*.html",

package/scripts/postinstall.mjs CHANGED Viewed

@@ -1,128 +1,39 @@
 /**
- * Post-install script: auto-download engine + asset files from GitHub Releases.
+ * Post-install script.
  *
- * To skip (e.g. in CI): set env GAEA_SKIP_DOWNLOAD=1
+ * 说明：引擎与大资源文件（Gaea.pck / Gaea.wasm / static/1111.res / static/gltf/ 等）
+ * 体积较大，不随 npm 包分发，也不再自动从 GitHub 下载。
+ * 请通过其它方式（内网传输 / 手动拷贝）将这些文件放置到消费者项目的 public/static 目录，
+ * 详见 README.md 第 8 节「大资源文件的放置」。
  *
- * GitHub Releases 需要上传的文件:
- *   gaea-assets-v{version}.zip  (包含 Gaea.pck, Gaea.wasm, static/gltf/, static/1111.res)
- *
- * Zip 内部结构:
- *   Gaea.pck
- *   Gaea.wasm
- *   static/
- *     gltf/  (所有 .gltf 文件)
- *     1111.res
+ * 如需强制跳过本脚本的任何提示：设置环境变量 GAEA_SKIP_DOWNLOAD=1
  */
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import https from 'https';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const PUBLIC_DIR = path.join(PACKAGE_ROOT, 'public');
-const PKG = JSON.parse(fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf-8'));
-const VERSION = PKG.version;
-const ASSETS_VERSION = '1.1.1';  // 大文件资源版本，不随 npm 版本变动
-const ZIP_NAME = `gaea-assets-v${ASSETS_VERSION}.zip`;
-const GITHUB_RELEASES = `https://github.com/smallflypig/Gaea/releases/download/v${ASSETS_VERSION}`;
-const ZIP_URL = `${GITHUB_RELEASES}/${ZIP_NAME}`;
-// ── helpers ──────────────────────────────────────────────────────────
-function download(url, dest) {
-  return new Promise((resolve, reject) => {
-    const file = fs.createWriteStream(dest);
-    https.get(url, (res) => {
-      if (res.statusCode === 302 || res.statusCode === 301) {
-        file.close();
-        try { fs.unlinkSync(dest); } catch {}
-        return download(res.headers.location, dest).then(resolve, reject);
-      }
-      if (res.statusCode !== 200) {
-        file.close();
-        try { fs.unlinkSync(dest); } catch {}
-        reject(new Error(`HTTP ${res.statusCode}`));
-        return;
-      }
-      const total = parseInt(res.headers['content-length'], 10) || 0;
-      let downloaded = 0;
-      res.on('data', (chunk) => {
-        downloaded += chunk.length;
-        if (total > 0 && downloaded % (50 * 1024) < chunk.length) {
-          const pct = Math.round((downloaded / total) * 100);
-          process.stdout.write(`  ${pct}%\r`);
-        }
-      });
-      res.pipe(file);
-      file.on('finish', () => {
-        file.close();
-        process.stdout.write('\r');
-        resolve();
-      });
-    }).on('error', (err) => {
-      file.close();
-      try { fs.unlinkSync(dest); } catch {}
-      reject(err);
-    });
-  });
-}
-// ── main ─────────────────────────────────────────────────────────────
 if (process.env.GAEA_SKIP_DOWNLOAD === '1') {
-  console.log('[gaea] GAEA_SKIP_DOWNLOAD=1, skipping.');
   process.exit(0);
 }
-// Quick check: do essential files already exist?
+// 检测关键资源是否已就位（Gaea.pck 通常 >100MB）
 const MARKER = path.join(PUBLIC_DIR, 'Gaea.pck');
-if (fs.existsSync(MARKER) && fs.statSync(MARKER).size > 100 * 1024 * 1024) {
-  console.log('[gaea] Assets already exist, skip download.');
-  process.exit(0);
+const ready = fs.existsSync(MARKER) && fs.statSync(MARKER).size > 100 * 1024 * 1024;
+if (ready) {
+  console.log('[gaea] 引擎资源已就位。');
+} else {
+  console.log(
+    '\n[gaea] 未检测到引擎大资源文件（Gaea.pck / Gaea.wasm / static/1111.res / static/gltf 等）。\n' +
+    '[gaea] 这些文件不随 npm 包分发，请通过内网/手动方式放置到项目静态资源目录后再运行。\n' +
+    '[gaea] 放置方法详见 README.md 第 8 节。\n'
+  );
 }
-console.log(`[gaea] Downloading assets from GitHub Releases v${VERSION}...`);
-console.log(`[gaea] ${ZIP_URL}`);
-const tmpZip = path.join(PUBLIC_DIR, ZIP_NAME);
-(async () => {
-  try {
-    // 1. Download zip
-    await download(ZIP_URL, tmpZip);
-    // 2. Extract
-    console.log('[gaea] Extracting...');
-    const { execSync } = await import('child_process');
-    try {
-      execSync(`powershell -Command "Expand-Archive -Path '${tmpZip}' -DestinationPath '${PUBLIC_DIR}' -Force"`, {
-        stdio: 'pipe',
-      });
-    } catch {
-      // Fallback: try unzip
-      execSync(`unzip -o "${tmpZip}" -d "${PUBLIC_DIR}"`, { stdio: 'pipe' });
-    }
-    // 3. Cleanup
-    fs.unlinkSync(tmpZip);
+process.exit(0);
-    console.log('[gaea] Assets installed successfully.');
-  } catch (e) {
-    console.error(`\n[gaea] Download failed: ${e.message}`);
-    console.error(
-      `[gaea] Please download manually: ${ZIP_URL}\n` +
-      `       Extract to: ${PUBLIC_DIR}\n` +
-      `       Or set GAEA_SKIP_DOWNLOAD=1 to skip.`
-    );
-    try { fs.unlinkSync(tmpZip); } catch {}
-    process.exit(0);
-  }
-})();

package/src/GaeaMethods.js CHANGED Viewed

@@ -274,6 +274,7 @@ export class GaeaApp {
     this._screenIconList = [];
     this._secIsClickArr = [];
     this._secScreenIconKeyValue = {};
+    this._groundPolygonElements = [];
     this.tweenGroup = new TWEEN.Group();
     this._tourConfig = {
       '沿浦水闸': { direction: [-0.5, 0.3, 0.3], positionList: [
@@ -335,47 +336,59 @@ export class GaeaApp {
     await this._initLayers();
     console.log('[GaeaApp] 图层加载完成');
-    // 5. 调整模型位置
-    console.log('[GaeaApp] 开始调整模型位置...');
-    const models = [
-      { nodeName: '沿浦水闸', position: '-2876603.788, 4892658.352, 2900208.622', rotation: '-37.24, 162.42, -17.17' },
-      { nodeName: '下在水闸', position: '-2875959.024, 4893109.058, 2900101.919', rotation: '-23.42, -165.20, -34.52' },
-      { nodeName: '联盟水闸', position: '-2878251.995, 4893011.199, 2897998.160', rotation: '-23.43, -165.98, -33.40' },
-      { nodeName: '岭尾新闸', position: '-2877382.212, 4892920.226, 2898965.484', rotation: '7.79, 36.98, 40.83' },
-      { nodeName: '岭尾水闸', position: '-2877582.576, 4892520.352, 2899499.184', rotation: '-41.04, 126.37, 6.29' },
-    ];
-    for (const model of models) {
-      try {
-        const node = Gaea.World.Instance.GetNode(model.nodeName);
-        if (!node) { console.warn(`[GaeaApp] 未找到节点: ${model.nodeName}`); continue; }
-        const inst = Gaea.MeshInstance.ConvertBy(node);
-        const pos = model.position.split(',').map(v => parseFloat(v.trim()));
-        const rot = model.rotation.split(',').map(v => parseFloat(v.trim()));
-        if (inst.Translation) inst.Translation = new Gaea.Vector3(pos[0], pos[1], pos[2]);
-        if (inst.RotationDegrees) inst.RotationDegrees = new Gaea.Vector3(rot[0], rot[1], rot[2]);
-        console.log(`[GaeaApp] 模型 ${model.nodeName} 位置调整完成`);
-      } catch (e) {
-        console.warn(`[GaeaApp] 调整模型 ${model.nodeName} 失败:`, e.message);
+    // 影像/地形就绪即可显示地图，隐藏 loading，避免用户等待模型/接口
+    hideLoading();
+    this._addResetButton();
+    console.log('[GaeaApp] 地图已就绪，模型与图层树数据后台加载中...');
+    // 剩余重资源（模型位置、GLTF、图层树接口、屏幕图标）后台异步加载，不阻塞地图显示
+    this._loadRestAsync();
+  }
+  /** 后台异步加载：模型位置调整 → GLTF → 图层树数据 → 屏幕图标 */
+  async _loadRestAsync() {
+    try {
+      // 5. 调整模型位置
+      console.log('[GaeaApp] 开始调整模型位置...');
+      const models = [
+        { nodeName: '沿浦水闸', position: '-2876603.788, 4892658.352, 2900208.622', rotation: '-37.24, 162.42, -17.17' },
+        { nodeName: '下在水闸', position: '-2875959.024, 4893109.058, 2900101.919', rotation: '-23.42, -165.20, -34.52' },
+        { nodeName: '联盟水闸', position: '-2878251.995, 4893011.199, 2897998.160', rotation: '-23.43, -165.98, -33.40' },
+        { nodeName: '岭尾新闸', position: '-2877382.212, 4892920.226, 2898965.484', rotation: '7.79, 36.98, 40.83' },
+        { nodeName: '岭尾水闸', position: '-2877582.576, 4892520.352, 2899499.184', rotation: '-41.04, 126.37, 6.29' },
+      ];
+      for (const model of models) {
+        try {
+          const node = Gaea.World.Instance.GetNode(model.nodeName);
+          if (!node) { console.warn(`[GaeaApp] 未找到节点: ${model.nodeName}`); continue; }
+          const inst = Gaea.MeshInstance.ConvertBy(node);
+          const pos = model.position.split(',').map(v => parseFloat(v.trim()));
+          const rot = model.rotation.split(',').map(v => parseFloat(v.trim()));
+          if (inst.Translation) inst.Translation = new Gaea.Vector3(pos[0], pos[1], pos[2]);
+          if (inst.RotationDegrees) inst.RotationDegrees = new Gaea.Vector3(rot[0], rot[1], rot[2]);
+        } catch (e) {
+          console.warn(`[GaeaApp] 调整模型 ${model.nodeName} 失败:`, e.message);
+        }
       }
-    }
-    console.log('[GaeaApp] 所有模型位置调整完成');
+      console.log('[GaeaApp] 所有模型位置调整完成');
-    // 6. 加载 GLTF 模型
-    await this._loadGltfModels();
+      // 6. 加载 GLTF 模型
+      await this._loadGltfModels();
-    // 7. 获取图层树数据（有接口走接口，没接口用默认）
-    await this._fetchLayerTreeData();
+      // 7. 获取图层树数据（有接口走接口，没接口用默认）
+      await this._fetchLayerTreeData();
-    // 同步 layerCategories（修复数据更新未同步的问题）
-    this.layerCategories = this.config.layerCategories || [];
-    console.log('[GaeaApp] layerCategories 更新后:', this.layerCategories.length);
+      // 同步 layerCategories（修复数据更新未同步的问题）
+      this.layerCategories = this.config.layerCategories || [];
+      console.log('[GaeaApp] layerCategories 更新后:', this.layerCategories.length);
-    // 8. 初始化屏幕图标
-    this._initScreenIcons();
+      // 8. 初始化屏幕图标
+      this._initScreenIcons();
-    hideLoading();
-    this._addResetButton();
-    console.log('[GaeaApp] 初始化完成');
+      console.log('[GaeaApp] 后台资源加载完成');
+    } catch (e) {
+      console.error('[GaeaApp] 后台资源加载出错:', e);
+    }
   }
   _waitForCanvas() {
@@ -570,13 +583,14 @@ export class GaeaApp {
     }
     console.log('[GaeaApp] 开始加载 GLTF 模型...');
-    for (const item of gltfList) {
+    // 并行加载所有模型（原串行逐个 await 会累加耗时）
+    await Promise.all(gltfList.map(async (item) => {
       item.url = encodeURI(item.url);
       try {
         const el = await this.AddGltf(item);
         if (el) this._gltfElements[item.name] = el;
       } catch (e) { console.warn(`[GaeaApp] 模型 ${item.name} 加载失败:`, e.message); }
-    }
+    }));
     console.log('[GaeaApp] GLTF 模型加载完成');
   }
@@ -619,7 +633,7 @@ export class GaeaApp {
       });
       Gaea.World.Instance.RenderableObjectList.AddLast(element);
-      setTimeout(() => res(element), 20000);
+      setTimeout(() => res(element), 8000);
     });
   };
@@ -948,6 +962,81 @@ export class GaeaApp {
     }
   }
+  // ---- 贴地面（矢量面绘制） ----
+  /**
+   * 根据坐标数组添加贴地面
+   * @param {Array} coords - 坐标数组，格式 [[lng, lat], [lng, lat], ...]
+   * @param {string} name - 面名称
+   * @param {string} colorHex - 颜色 hex 值，如 '#3498db'
+   * @returns {object|null} 创建的 PolygonGeometryElement，失败返回 null
+   */
+  addGroundPolygonByCoords(coords, name, colorHex) {
+    if (!coords || coords.length < 3) {
+      console.warn(`坐标点不足，跳过: ${name}`);
+      return null;
+    }
+    // 检查是否已存在同名面
+    if (this._groundPolygonElements.find(p => p.name === name)) {
+      console.warn(`贴地面 "${name}" 已存在，跳过`);
+      return null;
+    }
+    const positions = coords.map(c => new Gaea.Vector3(c[1], c[0], 50));
+    const geometry = Gaea.Geometry.Create1(Gaea.GeometryType.Polygon, positions);
+    const res = Gaea.GaeaResourceLoader.Instance.LoadLoaclResource('res://assets/shaders/polygonClampGround.shader');
+    const shader = Gaea.Shader.ConvertBy(res);
+    const material = new Gaea.ShaderMaterial();
+    material.Shader = shader;
+    const hex = colorHex.replace('#', '');
+    const r = parseInt(hex.substring(0, 2), 16) / 255;
+    const g = parseInt(hex.substring(2, 4), 16) / 255;
+    const b = parseInt(hex.substring(4, 6), 16) / 255;
+    Gaea.World.Instance.SetMtlColor(material, 'albedo', new Gaea.Color(r, g, b, 0.5));
+    const symbol = new Gaea.GroundPolygonSymbol();
+    symbol.PrismHeight = 9999;
+    symbol.GroundPolygonMtl = material;
+    const polygonElement = new Gaea.PolygonGeometryElement();
+    polygonElement.Symbol = symbol;
+    polygonElement.Shape = geometry;
+    polygonElement.EnablePick = true;
+    polygonElement.EnableEdit = true;
+    polygonElement.NeedIntersectWithMesh = false;
+    polygonElement.EnableVirtualPoint = true;
+    polygonElement.Name = name;
+    Gaea.World.Instance.RenderableObjectList.AddLast(polygonElement);
+    this._groundPolygonElements.push({ name, color: colorHex, element: polygonElement });
+    return polygonElement;
+  }
+  /** 移除指定贴地面 */
+  removeGroundPolygon(element) {
+    try {
+      Gaea.World.Instance.RenderableObjectList.Remove(element);
+    } catch (err) {
+      console.error('移除贴地面失败:', err);
+    }
+    const idx = this._groundPolygonElements.findIndex(p => p.element === element);
+    if (idx >= 0) this._groundPolygonElements.splice(idx, 1);
+  }
+  /** 清除所有贴地面 */
+  clearAllGroundPolygons() {
+    this._groundPolygonElements.forEach(item => {
+      try {
+        Gaea.World.Instance.RenderableObjectList.Remove(item.element);
+      } catch (err) {
+        console.error('移除贴地面失败:', err);
+      }
+    });
+    this._groundPolygonElements = [];
+  }
   /** 定位到指定视角（经纬度高程 + 相机参数） */
   SetPosition(numStr) {
     const arr = numStr.split(',').map(s => Number(s.trim()));

package/src/components/VectorPolygonControl.vue ADDED Viewed

@@ -0,0 +1,396 @@
+<template>
+  <div class="vector-polygon-panel" v-drag>
+    <div class="panel-header title">
+      <span class="panel-title">画矢量面</span>
+      <button class="close-btn" @click="handleClose">&times;</button>
+    </div>
+    <div class="panel-body">
+      <!-- 颜色选择 -->
+      <div class="section">
+        <div class="section-header">
+          <span class="section-label"><i class="fas fa-palette"></i> 面颜色</span>
+        </div>
+        <div class="color-row">
+          <div
+            v-for="c in presetColors"
+            :key="c"
+            class="color-block"
+            :class="{ active: polygonColor === c }"
+            :style="{ backgroundColor: c }"
+            @click="polygonColor = c"
+          ></div>
+          <div class="color-custom">
+            <input type="color" v-model="polygonColor" class="color-picker" />
+            <span class="color-hex">{{ polygonColor }}</span>
+          </div>
+        </div>
+      </div>
+      <!-- 上传GeoJSON -->
+      <div class="section">
+        <div class="section-header">
+          <span class="section-label"><i class="fas fa-file-upload"></i> 上传GeoJSON</span>
+        </div>
+        <div
+          class="upload-area"
+          :class="{ 'drag-over': isDragOver }"
+          @click="triggerFileInput"
+          @dragover.prevent="isDragOver = true"
+          @dragleave.prevent="isDragOver = false"
+          @drop.prevent="handleFileDrop"
+        >
+          <i class="fas fa-cloud-upload-alt upload-icon"></i>
+          <span class="upload-text">点击或拖拽.geojson文件到此处</span>
+          <input
+            ref="fileInput"
+            type="file"
+            accept=".geojson,.json"
+            multiple
+            style="display: none"
+            @change="handleFileSelect"
+          />
+        </div>
+        <div v-if="uploadingFile" class="upload-status">
+          <i class="fas fa-spinner fa-spin"></i> 正在处理: {{ uploadingFile }}
+        </div>
+      </div>
+      <!-- 已加载的面列表 -->
+      <div class="section" v-if="polygonList.length > 0">
+        <div class="section-header">
+          <span class="section-label"><i class="fas fa-list"></i> 已加载矢量面 ({{ polygonList.length }})</span>
+          <button class="btn-clear-small" @click="clearAll">清空全部</button>
+        </div>
+        <div class="polygon-items">
+          <div v-for="(item, i) in polygonList" :key="i" class="polygon-item">
+            <span
+              class="polygon-color-dot"
+              :style="{ backgroundColor: item.color }"
+            ></span>
+            <span class="polygon-name" :title="item.name">{{ item.name }}</span>
+            <button class="polygon-delete" @click="removePolygon(i)" title="删除">
+              <i class="fas fa-trash-alt"></i>
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+<script setup>
+import { ref } from 'vue';
+import { GaeaApp } from '../GaeaMethods.js';
+import vDrag from '../directives/vDrag.js';
+const props = defineProps({
+  appInstance: { type: Object, default: null }
+});
+const emit = defineEmits(['close']);
+const APP = props.appInstance || (window.APP || new GaeaApp());
+const presetColors = [
+  '#e74c3c', '#e67e22', '#f1c40f', '#2ecc71',
+  '#1abc9c', '#3498db', '#9b59b6', '#34495e',
+];
+const polygonColor = ref('#3498db');
+const fileInput = ref(null);
+const isDragOver = ref(false);
+const uploadingFile = ref('');
+const polygonList = ref([]);
+const triggerFileInput = () => {
+  fileInput.value?.click();
+};
+const handleFileDrop = (e) => {
+  isDragOver.value = false;
+  const files = e.dataTransfer.files;
+  if (files.length > 0) processFiles(files);
+};
+const handleFileSelect = (e) => {
+  const files = e.target.files;
+  if (files.length > 0) processFiles(files);
+  e.target.value = '';
+};
+const processFiles = async (files) => {
+  for (const file of files) {
+    if (!file.name.endsWith('.geojson') && !file.name.endsWith('.json')) continue;
+    uploadingFile.value = file.name;
+    try {
+      const text = await file.text();
+      const geojson = JSON.parse(text);
+      const polygons = extractPolygons(geojson, file.name.replace(/\.(geojson|json)$/i, ''));
+      for (const poly of polygons) {
+        const el = APP.addGroundPolygonByCoords(poly.coords, poly.name, polygonColor.value);
+        if (el) {
+          polygonList.value.push({ name: poly.name, color: polygonColor.value, element: el });
+        }
+      }
+    } catch (err) {
+      console.error(`解析GeoJSON文件失败: ${file.name}`, err);
+      alert(`解析文件 "${file.name}" 失败: ${err.message}`);
+    }
+  }
+  uploadingFile.value = '';
+};
+const extractPolygons = (geojson, defaultName) => {
+  const results = [];
+  const processGeometry = (geom, name) => {
+    if (!geom) return;
+    if (geom.type === 'Polygon') {
+      results.push({ name, coords: geom.coordinates[0] });
+    } else if (geom.type === 'MultiPolygon') {
+      geom.coordinates.forEach((poly, idx) => {
+        results.push({ name: `${name}_${idx + 1}`, coords: poly[0] });
+      });
+    }
+  };
+  if (geojson.type === 'FeatureCollection') {
+    geojson.features.forEach((feature, idx) => {
+      const featureName = feature.properties?.name || feature.properties?.Name || `${defaultName}_${idx + 1}`;
+      processGeometry(feature.geometry, featureName);
+    });
+  } else if (geojson.type === 'Feature') {
+    const featureName = geojson.properties?.name || geojson.properties?.Name || defaultName;
+    processGeometry(geojson.geometry, featureName);
+  } else if (geojson.type === 'Polygon') {
+    results.push({ name: defaultName, coords: geojson.coordinates[0] });
+  } else if (geojson.type === 'MultiPolygon') {
+    geojson.coordinates.forEach((poly, idx) => {
+      results.push({ name: `${defaultName}_${idx + 1}`, coords: poly[0] });
+    });
+  }
+  return results;
+};
+const removePolygon = (index) => {
+  const item = polygonList.value[index];
+  if (!item) return;
+  APP.removeGroundPolygon(item.element);
+  polygonList.value.splice(index, 1);
+};
+const clearAll = () => {
+  APP.clearAllGroundPolygons();
+  polygonList.value = [];
+};
+const handleClose = () => {
+  emit('close');
+};
+</script>
+<style lang="less" scoped>
+.vector-polygon-panel {
+  position: absolute;
+  top: 100px;
+  left: 600px;
+  width: 360px;
+  background: rgba(30, 41, 59, 0.95);
+  border: 1px solid rgba(255, 255, 255, 0.15);
+  border-radius: 10px;
+  color: #e2e8f0;
+  font-size: 13px;
+  z-index: 10000;
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4);
+  backdrop-filter: blur(8px);
+}
+.panel-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 10px 14px;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+}
+.panel-title {
+  font-weight: 600;
+  font-size: 15px;
+}
+.close-btn {
+  background: none;
+  border: none;
+  color: #94a3b8;
+  font-size: 18px;
+  cursor: pointer;
+  padding: 0 4px;
+  &:hover { color: #fff; }
+}
+.panel-body {
+  padding: 12px 14px;
+}
+.section {
+  margin-bottom: 16px;
+  &:last-child { margin-bottom: 0; }
+}
+.section-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 8px;
+}
+.section-label {
+  font-weight: 500;
+  font-size: 13px;
+  color: #cbd5e1;
+  i { margin-right: 6px; color: #3b82f6; }
+}
+.btn-clear-small {
+  background: rgba(239, 68, 68, 0.15);
+  border: 1px solid rgba(239, 68, 68, 0.3);
+  color: #ef4444;
+  font-size: 11px;
+  padding: 3px 8px;
+  border-radius: 4px;
+  cursor: pointer;
+  &:hover { background: rgba(239, 68, 68, 0.3); }
+}
+.color-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+.color-block {
+  width: 26px;
+  height: 26px;
+  border-radius: 4px;
+  cursor: pointer;
+  border: 2px solid transparent;
+  transition: all 0.15s;
+  &:hover { transform: scale(1.1); }
+  &.active {
+    border-color: #fff;
+    box-shadow: 0 0 8px rgba(59, 130, 246, 0.5);
+  }
+}
+.color-custom {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+.color-picker {
+  width: 28px;
+  height: 28px;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  padding: 0;
+  background: transparent;
+  &::-webkit-color-swatch-wrapper { padding: 0; }
+  &::-webkit-color-swatch {
+    border-radius: 4px;
+    border: 1px solid rgba(255, 255, 255, 0.2);
+  }
+}
+.color-hex {
+  font-size: 11px;
+  color: #94a3b8;
+  font-family: monospace;
+}
+.upload-area {
+  border: 2px dashed rgba(148, 163, 184, 0.3);
+  border-radius: 8px;
+  padding: 20px;
+  text-align: center;
+  cursor: pointer;
+  transition: all 0.2s;
+  &:hover {
+    border-color: rgba(59, 130, 246, 0.5);
+    background: rgba(59, 130, 246, 0.05);
+  }
+  &.drag-over {
+    border-color: #3b82f6;
+    background: rgba(59, 130, 246, 0.1);
+  }
+}
+.upload-icon {
+  font-size: 28px;
+  color: #64748b;
+  display: block;
+  margin-bottom: 8px;
+}
+.upload-text {
+  font-size: 12px;
+  color: #94a3b8;
+}
+.upload-status {
+  margin-top: 8px;
+  font-size: 12px;
+  color: #3b82f6;
+  i { margin-right: 4px; }
+}
+.polygon-items {
+  max-height: 200px;
+  overflow-y: auto;
+}
+.polygon-item {
+  display: flex;
+  align-items: center;
+  padding: 6px 8px;
+  margin-bottom: 4px;
+  background: rgba(255, 255, 255, 0.04);
+  border-radius: 6px;
+  &:hover { background: rgba(255, 255, 255, 0.08); }
+}
+.polygon-color-dot {
+  width: 12px;
+  height: 12px;
+  border-radius: 3px;
+  flex-shrink: 0;
+  margin-right: 8px;
+}
+.polygon-name {
+  flex: 1;
+  font-size: 12px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.polygon-delete {
+  background: none;
+  border: none;
+  color: #64748b;
+  cursor: pointer;
+  padding: 2px 6px;
+  font-size: 12px;
+  border-radius: 4px;
+  &:hover {
+    color: #ef4444;
+    background: rgba(239, 68, 68, 0.1);
+  }
+}
+</style>

package/src/components/index.cjs ADDED Viewed

@@ -0,0 +1,6 @@
+/**
+ * @yangyongtao/gaea/components - CJS 入口
+ */
+'use strict';
+module.exports = import('./index.js').then(m => m);

package/src/components/index.js CHANGED Viewed

@@ -5,3 +5,4 @@ export { default as CommonDialog } from './CommonDialog.vue';
 export { default as HydrologicStationDialog } from './HydrologicStationDialog.vue';
 export { default as SecTourView } from './SecTourView.vue';
 export { default as WaterGateTour } from './WaterGateTour.vue';
+export { default as VectorPolygonControl } from './VectorPolygonControl.vue';

package/src/index.cjs ADDED Viewed

@@ -0,0 +1,11 @@
+/**
+ * @yangyongtao/gaea - CJS 入口
+ *
+ * CommonJS 用法:
+ *   const gaea = await import('@yangyongtao/gaea');
+ *   或
+ *   require('@yangyongtao/gaea').then(({ GaeaApp, setConfig }) => { ... })
+ */
+'use strict';
+module.exports = import('./index.js').then(m => m);

package/src/plugin.cjs ADDED Viewed

@@ -0,0 +1,6 @@
+/**
+ * @yangyongtao/gaea/plugin - CJS 入口
+ */
+'use strict';
+module.exports = import('./plugin.js').then(m => m);

package/USAGE.md DELETED Viewed

@@ -1,200 +0,0 @@
-# @yangyongtao/gaea 使用文档
-基于 Godot WASM 引擎的 Vue 3 三维可视化组件库。提供影像/地形/贴地线加载、相机视角控制、图层树、天气控制、沿线飞行、断面游览、室内游览等能力，并内置 Vite 插件自动注入引擎资源。
-> 完整可运行示例见 `gaea-ground-test/src/App.vue`，本文所有片段均以其为参考。
----
-## 1. 安装
-```bash
-npm install @yangyongtao/gaea
-```
-peerDependencies（按需安装）：`vue ^3.4`、`element-plus ^2.6`（可选）、`pinia ^2.1`（可选）。
----
-## 2. Vite 配置
-引入并注册 `gaeaVitePlugin`，它会自动注入 `Gaea.js`、提供引擎静态资源、设置 SharedArrayBuffer 所需的跨域隔离响应头。
-```js
-// vite.config.js
-import { defineConfig } from 'vite';
-import vue from '@vitejs/plugin-vue';
-import { gaeaVitePlugin } from '@yangyongtao/gaea/plugin';
-export default defineConfig({
-  plugins: [vue(), gaeaVitePlugin()],
-  resolve: { preserveSymlinks: true },
-  optimizeDeps: { exclude: ['@yangyongtao/gaea'] },
-});
-```
----
-## 3. 快速开始
-页面里需要一个 `id="canvas"` 的画布。调用 `setConfig(...)` 后 `new GaeaApp()` 即可自动完成「引擎启动 → 环境初始化 → 图层加载 → 模型加载」。
-```vue
-<template>
-  <div id="gaea-app">
-    <div class="toolbar">
-      <button @click="showWeather = !showWeather">天气控制</button>
-      <button @click="showFly = !showFly">沿线飞行</button>
-      <button @click="showLayerTree = !showLayerTree">图层控制</button>
-      <WaterGateTour />
-    </div>
-    <div class="canvas-area" id="canvas-container">
-      <canvas id="canvas"></canvas>
-    </div>
-    <WeatherControl v-if="showWeather" :appInstance="app" @close="showWeather = false" />
-    <FlyAlongRoute v-if="showFly" :appInstance="app" @close="showFly = false" />
-    <LayerTree v-if="showLayerTree" :appInstance="app" @close="showLayerTree = false" @node-click="onLayerNodeClick" />
-    <HydrologicStationDialog />
-    <SecTourView />
-  </div>
-</template>
-<script setup>
-import { ref } from 'vue';
-import { GaeaApp, setConfig } from '@yangyongtao/gaea';
-import { WeatherControl, FlyAlongRoute, HydrologicStationDialog, SecTourView, WaterGateTour } from '@yangyongtao/gaea/components';
-import LayerTree from '@yangyongtao/gaea/components/LayerTree.vue';
-setConfig({
-  serveLocal: `${window.location.origin}/static`,
-  serveUrl: 'http://192.168.3.151:8088/gaeaExplorerServer/',
-  serviceMode: 'platform',
-  defaultCameraPosition: '27.3680928977018,120.414139621887,0,109379.690132486,0,0',
-});
-const app = new GaeaApp();
-window.APP = app;               // 组件内部通过 window.APP 兜底获取实例
-const showWeather = ref(false);
-const showFly = ref(false);
-const showLayerTree = ref(false);
-function onLayerNodeClick({ node }) {
-  app.flyToNode(node);
-}
-</script>
-```
----
-## 4. setConfig 配置项
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `serveLocal` | string | `''` | 引擎本地静态资源地址（AssetHost），一般为 `${origin}/static` |
-| `serveUrl` | string | `''` | 服务平台地址（WMTS 影像 / 地形 / 贴地线均基于此） |
-| `serviceMode` | `'platform' \| 'online'` | `'platform'` | **服务模式**：见下方说明 |
-| `tiandituToken` | string | — | 在线模式的天地图 token |
-| `tiandituLevelRange` | [number,number] | `[0,18]` | 天地图层级范围 |
-| `defaultLayers` | Array | 见下 | 服务平台模式下加载的影像图层 |
-| `defaultTerrains` | Array | 见下 | 服务平台模式下加载的地形服务 |
-| `defaultGroundLines` | Array | 见下 | 服务平台模式下加载的贴地线 |
-| `defaultCameraPosition` | string | — | 初始相机视角：`纬度,经度,高程,相机高,俯仰,朝向` |
-| `layerCategories` | Array | 内置 | 图层树分类数据（接口数据会合并进来） |
-| `dataHubApiUrl` | string | `''` | 图层树数据接口地址，为空则只用默认数据 |
-| `onProgress` | function | — | 引擎加载进度回调 `(cur, total) => {}` |
-### 4.1 serviceMode —— 服务模式（区分「服务平台」与「在线」）
-- `'platform'`（服务平台）：影像走 `serveUrl` 的 WMTS，并加载 `defaultTerrains` 地形、`defaultGroundLines` 贴地线。
-- `'online'`（在线）：**仅加载天地图影像**，不加载地形和贴地线（在线模式目前只有天地图一种影像来源）。
-```js
-setConfig({ serviceMode: 'platform' });  // 内网/服务平台
-// 或
-setConfig({ serviceMode: 'online', tiandituToken: '你的token' }); // 在线（天地图）
-```
-### 4.2 defaultLayers —— 影像图层（服务平台模式）
-```js
-defaultLayers: [
-  { layerName: 'earthland', forMat: 'image/png', min: 0, max: 18, transparency: 0.3 },
-  { layerName: '苍南L19',   forMat: 'image/png', min: 5, max: 17 },
-]
-```
-- `layerName`：WMTS 服务里的图层名（Title）
-- `forMat`：影像格式，如 `image/png`、`image/jpeg`
-- `min` / `max`：显示层级范围
-- `transparency`：透明度（可选）
-### 4.3 defaultTerrains —— 地形服务（服务平台模式）
-```js
-defaultTerrains: [
-  { name: '苍南县地形', url: 'htc/service/tms/1.0.0/苍南县地形@EPSG%3A4326@terrain/' },
-]
-```
-- `name`：地形名称
-- `url`：相对 `serveUrl` 的路径（也支持传完整 `http(s)://` 地址）
-- 空数组 `[]` 则不加载地形
-### 4.4 defaultGroundLines —— 贴地线（服务平台模式）
-依赖 `serveUrl` 的 WMTS 矢量线服务（自动通过 `getAllServe` 获取服务列表后按名匹配）。
-```js
-defaultGroundLines: [
-  { name: '苍南县边界',        range: [0, 9],   color: [255, 255, 0],   index: 100 },
-  { name: '苍南县镇边界',      range: [9, 15],  color: [0, 255, 0],     index: 80 },
-  { name: '苍南县村边界',      range: [15, 19], color: [255, 255, 255], index: 60 },
-  { name: '沿浦海塘工程范围线', range: [0, 21],  color: [0, 255, 255],   index: 120 },
-]
-```
-- `name`：矢量线服务名（Title）
-- `range`：显示层级范围 `[min, max]`
-- `color`：线颜色 `[r, g, b]`（0-255）
-- `index`：渲染优先级
-- 每项可加 `isInitLoad: false` 跳过该条
----
-## 5. 组件说明
-组件从 `@yangyongtao/gaea/components` 导入；`LayerTree` 需按路径单独导入。多数交互组件接收 `:appInstance="app"`，未传时内部回退到 `window.APP`。
-| 组件 | 说明 | 主要事件 |
-|------|------|----------|
-| `WeatherControl` | 天气/台风控制面板（含台风路线拾取与播放） | `@close` |
-| `FlyAlongRoute` | 沿线飞行：地图拾取点位，可设飞行高度/时长 | `@close` |
-| `LayerTree` | 图层树，点击节点飞行定位 | `@close`、`@node-click` |
-| `HydrologicStationDialog` | 水文测站弹窗，自监听 `gaea-icon-click` 事件 | — |
-| `SecTourView` | 断面游览滚动条，模型锁定后显示 | — |
-| `WaterGateTour` | 室内游览按钮（下拉选择水闸模型） | — |
----
-## 6. 常用实例方法（window.APP / app）
-| 方法 | 说明 |
-|------|------|
-| `SetPosition('纬度,经度,高程,相机高,俯仰,朝向')` | 定位到指定视角 |
-| `flyToNode({ position:{x,y,z} })` | 飞到指定位置 |
-| `flyAlongPath(lineData, options)` | 沿线飞行，`lineData=[{x:纬度,y:经度,z:高度}]`，`options={duration,xrotation,lockEye,...}` |
-| `stopFlyAlongPath()` | 停止沿线飞行 |
-| `cameraReset()` | 相机复位到 `defaultCameraPosition` |
-| `addInitTerrainServer(terrains?)` | 手动加载地形（不传则用 `defaultTerrains`） |
-| `addGroundLines(lines?)` | 手动加载贴地线（不传则用 `defaultGroundLines`） |
-| `addTyphoonRoute(pointList, options)` | 加载台风路线并播放动画 |
-| `clearTyphoonRoute()` | 清除台风路线 |
----
-## 7. 注意事项
-- 页面必须存在 `id="canvas"` 的 `<canvas>`，引擎会挂载到它上面。
-- 需要跨域隔离（COOP/COEP）才能启用 SharedArrayBuffer，`gaeaVitePlugin` 已自动处理；首次进入若未隔离会自动刷新一次。
-- 服务平台模式下地形/贴地线依赖 `serveUrl` 对应服务，若服务器无对应服务名，控制台会打印「未找到/加载失败」警告，不影响其它功能。
-- 大体积引擎资源（`Gaea.pck` / `Gaea.wasm` / `1111.res` 等）通过 postinstall 脚本下载到本地静态目录，请确保下载源可访问。