PolylineGeometry用于Primitive PolylineMaterialAppearance做三维空间折线支持 Z 高程MultiLineString‑Z不是贴地线。 贴地线请用GroundPolylineGeometry / GroundPolylinePrimitive。一、核心概念PolylineGeometry几何体只存顶点坐标、线宽不能直接渲染必须包装进GeometryInstance交给Primitive渲染。PolylineMaterialAppearance配套外观材质支持纯色、虚线、纹理独有depthFailAppearance被地形遮挡时切换材质。不支持每个线段不同颜色同一份 Primitive 内所有线段共用一套 Appearance。如果要多条线不同颜色按颜色分组每个颜色新建一套 Primitive就是现在业务的做法。关键参数 PolylineGeometryconst lineGeo new Cesium.PolylineGeometry({ positions: Cartesian3[], // 笛卡尔3坐标数组必须≥2个点支持独立高程Z width: number, // 线宽【⚠️WebGL限制大部分浏览器最大有效2px】 vertexFormat: Cesium.VertexFormat.POSITION_ONLY });⚠️坑width 2在很多浏览器会强制变成 1 像素。粗线不要用这个改用GroundPolylinePrimitive。Primitive 重要属性表格属性说明geometryInstancesGeometryInstance 数组一条线对应一个实例appearance正常显示的材质PolylineMaterialAppearancedepthFailAppearance✅线被地形遮挡时使用这套材质地下变色 / 虚线仅线支持面不支持asynchronoustrue异步解析几何体页面不卡顿大数据建议 trueallowPickingtrue开启拾取pick()拿到 GeometryInstance 的 id二、基础完整示例1、单条三维空间线// 经纬度高程转Cartesian3 function lngLatHeightToCart3(lng:number,lat:number,h0){ return Cesium.Cartesian3.fromDegrees(lng,lat,h); } //1.顶点数组 const positions [ lngLatHeightToCart3(102.49,24.70,1800), lngLatHeightToCart3(102.50,24.71,1900), lngLatHeightToCart3(102.51,24.72,1750), ]; //2.构建几何体 const lineGeometry new Cesium.PolylineGeometry({ positions: positions, width:2 }); //3.包装实例 const instance new Cesium.GeometryInstance({ geometry: lineGeometry, id:line_001 //拾取id }); //4.创建Primitive带地下遮挡材质 const prim new Cesium.Primitive({ geometryInstances: instance, appearance: new Cesium.PolylineMaterialAppearance({ material: Cesium.Material.fromType(Color,{ color:Cesium.Color.ORANGE }) }), // 被地形埋住地下显示半透明 depthFailAppearance: new Cesium.PolylineMaterialAppearance({ material: Cesium.Material.fromType(Color,{ color:Cesium.Color.ORANGE.withAlpha(0.3) }) }), asynchronous:true }); //添加到场景 this.viewer.scene.primitives.add(prim);2、多条线批量按颜色分组项目现有模式// 按颜色分组每个颜色一组instances const tempLineGroup new Mapstring, {positions:Cesium.Cartesian3[],_featureId:string}[](); // 模拟多条线数据 tempLineGroup.forEach((lineList,cssColor){ const instances:Cesium.GeometryInstance[] []; lineList.forEach(opt{ if(opt.positions.length 2) return; const geo new Cesium.PolylineGeometry({ positions:opt.positions, width:3 }); instances.push(new Cesium.GeometryInstance({ geometry:geo, id:opt._featureId })) }) if(!instances.length) return; const mainColor Cesium.Color.fromCssColorString(cssColor); const prim new Cesium.Primitive({ geometryInstances:instances, appearance: new Cesium.PolylineMaterialAppearance({ material:Cesium.Material.fromType(Color,{color:mainColor}) }), depthFailAppearance: new Cesium.PolylineMaterialAppearance({ material:Cesium.Material.fromType(Color,{color:mainColor.withAlpha(0.35)}) }), asynchronous:true }) this.viewer.scene.primitives.add(prim); //保存引用用于后续删除 this.lineCollectionMap.set(cssColor, prim); })三、depthFailAppearance 两种常用材质①地下半透明实线上面示例②地下虚线管线 / 高压线业务最常用depthFailAppearance: new Cesium.PolylineMaterialAppearance({ material: new Cesium.Material({ fabric:{ type:Dash, uniforms:{ dashPattern:255, color: mainColor.withAlpha(0.35) } } }) })四、拾取点击Primitive 开启拾取点击拿到GeometryInstance的 idconst handler new Cesium.ScreenSpaceEventHandler(this.viewer.canvas); handler.setInputAction((click){ const pick this.viewer.scene.pick(click.position); if(Cesium.defined(pick)){ console.log(线要素id, pick.id); } },Cesium.ScreenSpaceEventType.LEFT_CLICK)五、销毁、清除内存泄漏重点// Map保存所有线Primitive引用 private lineCollectionMap new Mapstring,Cesium.Primitive(); //清除所有线 public clearLinePrimitive(){ this.lineCollectionMap.forEach(prim{ this.viewer.scene.primitives.remove(prim); }) this.lineCollectionMap.clear(); }六、PolylineGeometry 重要坑清单width 受 WebGL 限制有效宽度一般最大 2px设置 width5浏览器渲染依旧很细。✅粗线解决方案改用GroundPolylinePrimitive贴地或者 Entity polyline。三维空间线带 Z 高程不能用 GroundPolylineGeometryGround 系列强制贴地形会丢弃顶点 Z。depthFailAppearance只有 PolylineMaterialAppearance 支持PerInstanceColorAppearance面不支持。Primitive 一旦创建不能修改单条线的顶点、颜色。更新数据销毁旧 Primitive全部重新构建。输入坐标必须是Cartesian3不能直接传经纬度Cartesian3.fromDegrees(lng,lat,height)。线段至少 2 个点少于 2 个点会直接报错渲染崩溃。解析 WKT 时要做过滤、去重重合点。同一份 Primitive 内所有线段共用一套材质想要不同颜色必须拆分成多个 Primitive你的 Map 分组就是标准做法。七、对比表PolylineGeometry(Primitive)GroundPolylineGeometryEntity.polyline三维 Z 高程✅支持❌强制贴地丢弃 Z✅支持depthFailAppearance 地下变色✅支持❌不支持❌不支持线宽最大≈2px✅支持粗线✅支持粗线性能很高几千条较高差几百条卡顿拾取scene.pickscene.pick直接拿到 entity动态修改单条❌整体重绘❌整体重绘✅直接赋值业务选型建议三维管线、高压线、MultiLineString‑Z选PolylineGeometry Primitive depthFailAppearance。不需要高程、只贴地表、需要粗线GroundPolylinePrimitive。数量少频繁修改Entity。