@yangyongtao/gaea 1.1.14 → 1.1.15

package/README.md

@@ -18,7 +18,34 @@ peerDependencies（按需安装）：`vue ^3.4`、`element-plus ^2.6`（可选
 
 ---
 
-## 2. Vite 配置
+## 2. 引入方式
+
+本库同时支持 ESM 和 CommonJS。
+
+### ESM（推荐，vue-cli / vite / webpack 默认）
+
+```js
+import { GaeaApp, setConfig } from '@yangyongtao/gaea';
+import { WeatherControl, FlyAlongRoute } from '@yangyongtao/gaea/components';
+import { gaeaVitePlugin } from '@yangyongtao/gaea/plugin';
+```
+
+### CommonJS
+
+```js
+// 需要使用 await import() 或 .then()
+const gaea = await import('@yangyongtao/gaea');
+gaea.setConfig({ ... });
+
+// vite 配置中使用 CJS 引用插件
+const { gaeaVitePlugin } = await import('@yangyongtao/gaea/plugin');
+```
+
+> CJS 环境下 **不能** 直接用 `require()`，因为内部实现是 ESM 模块。Node.js 对 CJS `require` ESM 有限制，因此 CJS 包装入口返回的是 Promise。
+
+---
+
+## 3. Vite 配置
 
 引入并注册 `gaeaVitePlugin`，它会自动注入 `Gaea.js`、提供引擎静态资源、设置 SharedArrayBuffer 所需的跨域隔离响应头。
 
@@ -37,7 +64,7 @@ export default defineConfig({
 
 ---
 
-## 3. 快速开始
+## 4. 快速开始
 
 页面里需要一个 `id="canvas"` 的画布。调用 `setConfig(...)` 后 `new GaeaApp()` 即可自动完成「引擎启动 → 环境初始化 → 图层加载 → 模型加载」。
 
@@ -91,7 +118,7 @@ function onLayerNodeClick({ node }) {
 
 ---
 
-## 4. setConfig 配置项
+## 5. setConfig 配置项
 
 | 参数 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
@@ -108,7 +135,7 @@ function onLayerNodeClick({ node }) {
 | `dataHubApiUrl` | string | `''` | 图层树数据接口地址，为空则只用默认数据 |
 | `onProgress` | function | — | 引擎加载进度回调 `(cur, total) => {}` |
 
-### 4.1 serviceMode —— 服务模式（区分「服务平台」与「在线」）
+### 5.1 serviceMode —— 服务模式（区分「服务平台」与「在线」）
 
 - `'platform'`（服务平台）：影像走 `serveUrl` 的 WMTS，并加载 `defaultTerrains` 地形、`defaultGroundLines` 贴地线。
 - `'online'`（在线）：**仅加载天地图影像**，不加载地形和贴地线（在线模式目前只有天地图一种影像来源）。
@@ -119,7 +146,7 @@ setConfig({ serviceMode: 'platform' });  // 内网/服务平台
 setConfig({ serviceMode: 'online', tiandituToken: '你的token' }); // 在线（天地图）
 ```
 
-### 4.2 defaultLayers —— 影像图层（服务平台模式）
+### 5.2 defaultLayers —— 影像图层（服务平台模式）
 
 ```js
 defaultLayers: [
@@ -132,7 +159,7 @@ defaultLayers: [
 - `min` / `max`：显示层级范围
 - `transparency`：透明度（可选）
 
-### 4.3 defaultTerrains —— 地形服务（服务平台模式）
+### 5.3 defaultTerrains —— 地形服务（服务平台模式）
 
 ```js
 defaultTerrains: [
@@ -143,7 +170,7 @@ defaultTerrains: [
 - `url`：相对 `serveUrl` 的路径（也支持传完整 `http(s)://` 地址）
 - 空数组 `[]` 则不加载地形
 
-### 4.4 defaultGroundLines —— 贴地线（服务平台模式）
+### 5.4 defaultGroundLines —— 贴地线（服务平台模式）
 
 依赖 `serveUrl` 的 WMTS 矢量线服务（自动通过 `getAllServe` 获取服务列表后按名匹配）。
 
@@ -163,7 +190,7 @@ defaultGroundLines: [
 
 ---
 
-## 5. 组件说明
+## 6. 组件说明
 
 组件从 `@yangyongtao/gaea/components` 导入；`LayerTree` 需按路径单独导入。多数交互组件接收 `:appInstance="app"`，未传时内部回退到 `window.APP`。
 
@@ -206,11 +233,11 @@ defaultGroundLines: [
 
 ---
 
-## 8. 大资源文件的放置
+## 9. 大资源文件的放置
 
 引擎运行需要的大文件体积过大，**不包含在 npm 包内，也不会自动下载**（`postinstall` 仅做检测与提示）。请通过内网传输或手动拷贝的方式，将它们放到消费者项目里 gaea 包的 `public` 目录下。
 
-### 8.1 需要放置的文件
+### 9.1 需要放置的文件
 
 放置目标目录：`node_modules/@yangyongtao/gaea/public/`
 
@@ -223,7 +250,7 @@ defaultGroundLines: [
 
 > ⚠️ **重要**：`1111.res` 必须使用 **完整版（约 34.6 MB）**。早期存在一个残缺的 6.5MB 版本，会导致点图标纹理为空、加载台风路线时引擎崩溃（`SimpleFeatureRenderer.CombineSymbolMeshs` 空引用）。放置后可用文件大小快速校验。
 
-### 8.2 校验是否就位
+### 9.2 校验是否就位
 
 ```powershell
 # Windows PowerShell
@@ -232,7 +259,7 @@ Get-Item node_modules/@yangyongtao/gaea/public/static/1111.res | Select-Object L
 ```
 `Gaea.pck` 约 450MB、`1111.res` 约 34.6MB 即为正确。
 
-### 8.3 注意事项
+### 9.3 注意事项
 
 - 更换 `1111.res` 后，若浏览器曾加载过旧的残缺资源，引擎会把资源按名缓存进持久化虚拟文件系统，需**强制刷新（Ctrl+Shift+R）**一次；本库已用版本化资源名规避该缓存问题。
 - 若不放置这些文件，`npm install` 后控制台会打印提示，且页面无法正常渲染三维场景。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yangyongtao/gaea",
-  "version": "1.1.14",
+  "version": "1.1.15",
   "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.cjs",
@@ -13,13 +13,11 @@
     },
     "./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"
     }
   },

package/src/components/index.cjs

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

package/src/plugin.cjs

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