qqsl-ngx-cesium 使用文档

qqsl-ngx-cesium 是一套基于 Angular + Cesium 的地图/河流渲染组件库，当前主组件为 NgxCesiumMapComponent。

1. 依赖说明

• Angular 15.x
• [email protected]
• @angular/common、@angular/core

库内部默认会读取 Cesium 资源目录：

export const CESIUM_ASSET_BASE_URL = '/assets/cesium';

所以宿主项目需要提前准备 Cesium 静态资源。

2. 最小接入

2.1 引入模块

import { NgxCesiumMapModule } from 'qqsl-ngx-cesium/map';

如果你的项目是 standalone 组件：

imports: [NgxCesiumMapModule]

2.2 模板使用

<ngx-cesium-map
  style="width: 100%; height: 100%;"
  [center]="center"
  [riverPath]="riverPath"
  [meshList]="meshList"
  [flowSpeedPoints]="flowSpeedPoints"
  [riverDepthPoints]="riverDepthPoints"
  [tilesetUrl]="tilesetUrl"
></ngx-cesium-map>

2.3 常用输入

• center：初始相机中心点
• riverPath：河道轮廓点
• meshList：模型列表
• flowSpeedPoints：分段流速边界点
• riverDepthPoints：水深散点数组，每项为 { lng: number | string, lat: number | string, depth: number | string }
• tilesetUrl：倾斜摄影地址
• showRiverDepthGradient：水深渐变层开关
• showFlowSpeedPoints：流速调试点开关
• riverDepthStyle：水深图层样式。默认 depthRangeMode: 'auto'，按当前有效水深动态拉伸色带；如需固定 0-15m，传 { depthRangeMode: 'fixed', fixedDepthRange: { min: 0, max: 15 } }

3. 开发联调方案

如果目标是“组件库代码改动后，外部项目立刻看到变化，而且不需要先打包”，推荐直接走源码联调，不走 ng build / yalc。

方案 A：同一工作区联调

这个仓库里已经配置好了路径别名：

• qqsl-ngx-cesium -> ./dist/qqsl-ngx-cesium
• qqsl-ngx-cesium/* -> ./projects/qqsl-ngx-cesium/*

所以在同仓库里的 demo 或其他应用中，可以直接从源码路径导入：

import { NgxCesiumMapModule } from 'qqsl-ngx-cesium/map';

联调时只需要运行宿主应用的开发服务，例如：

npm run start

这样你修改 projects/qqsl-ngx-cesium/** 下的代码后，宿主应用会在重新编译时直接吃到最新源码，不需要先构建库包。

方案 B：其他项目联调，但不打包

如果是另一个独立项目，推荐把这个库源码以本地目录或符号链接的方式接进来，再在消费项目的 tsconfig 里把包名指向源码目录。

示例思路：

{
  "compilerOptions": {
    "paths": {
      "qqsl-ngx-cesium": ["<本地源码路径>/projects/qqsl-ngx-cesium"],
      "qqsl-ngx-cesium/*": ["<本地源码路径>/projects/qqsl-ngx-cesium/*"]
    }
  }
}

然后在消费项目里直接引入：

import { NgxCesiumMapModule } from 'qqsl-ngx-cesium/map';

这类方式的核心是“源码直连”，不是 npm 包安装，所以组件库文件一改，消费项目重新编译后就能看到更新。

联调建议

• 宿主项目保持 ng serve 常驻
• 组件库不要先 ng build qqsl-ngx-cesium
• 需要稳定观察变化时，优先改源码路径联调，而不是推 dist

4. 生产使用方案

生产环境建议走标准库发布流程：

1. 构建库：

npm run build:qqsl-ngx-cesium

2. 发布到 npm：

npm run publish:qqsl-ngx-cesium

3. 在业务项目中安装并使用：

import { NgxCesiumMapModule } from 'qqsl-ngx-cesium';

如果你的消费项目需要保持和当前仓库一致的源码引用习惯，也可以继续用 qqsl-ngx-cesium/map，但前提是你的构建/发布方式已经把该路径纳入可解析范围；生产环境更推荐以包根入口为准。

5. 运行时注意点

• 需要提前准备 Cesium 静态资源，并保证 CESIUM_ASSET_BASE_URL 可访问
• 如果使用倾斜摄影，tilesetUrl 要保证跨域和鉴权可用
• flowSpeedPoints 的语义是“从当前边界开始，到下一个边界之前”这一段使用当前点的速度
• showFlowSpeedPoints、showRiverSamplePoints、showRiverDepthGradient 这些开关适合联调阶段打开
• riverDepthPoints 现在按散点渲染水深，组件会用 KNN + IDW 对水面网格做平滑插值；落在河道外的散点会被忽略。可以参考 projects/qqsl-ngx-cesium/map/test-depth-data.ts

水深散点示例：

const riverDepthPoints = [
  { lng: 120, lat: '12', depth: 20 },
  { lng: 120.001, lat: 12.001, depth: 12.5 },
];

6. 示例入口

仓库里的示例页面可以参考：

• projects/demo/src/app/pages/cesium/cesium-test.component.ts

它演示了 NgxCesiumMapModule 的基本接入方式，也包含了水深、流速、倾斜摄影等常用输入。