Cesium + Vue3 三维几何实体开发入门教程
一、前言
1.1 适用人群
本教程面向有 Vue 基础（Vue2/Vue3 均可）、刚接触 Cesium 的开发者，聚焦「Cesium 实体（Entity）」核心用法，常见实体（点、线、面、立方体）的创建、样式配置、交互控制，全程手把手教学，解决新手入门的核心痛点。
1.2 核心目标
掌握 Cesium 实体的基础概念，能独立在 Vue 项目中创建点、线、面、立方体等常用地理实体，理解实体的坐标系统、样式配置、视角适配逻辑。
app.vue
以下实例可以放到onUnmounted函数中执行。
二、点实体（Point）
功能说明
标记三维空间中的兴趣点（POI），如城市地标、设备位置等，支持自定义大小、颜色、描边，且可配置距离缩放效果（近大远小）。
// 在 onMounted 初始化后添加
// 1. 定义点位置（经纬度+高度）
const pointPos = Cesium.Cartesian3.fromDegrees(116.4074, 39.9042, 500);
// 2. 添加点实体,viewer已经创建
const pointEntity = viewer.entities.add({
id: 'point-beijing', // 实体唯一标识（可选，用于后续操作）
position: pointPos,
point: {
pixelSize: 15, // 点像素大小（不随距离缩放）
color: Cesium.Color.RED, // 填充色
outlineColor: Cesium.Color.WHITE, // 描边色
outlineWidth: 3, // 描边宽度
// 距离缩放：1000米内1:1显示，50万米外缩至0.1倍
scaleByDistance: new Cesium.NearFarScalar(1000, 1, 500000, 0.1)
}
});
// 3. 相机定位到点实体（可选，方便查看）
viewer.camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(116.4074, 39.9042, 2000),
// 相机在点上方2000米
orientation: {
heading: Cesium.Math.toRadians(0), // 朝向正北
pitch: Cesium.Math.toRadians(-90), // 向下90度视角（看向点）
roll: 0
},
duration: 2, // 飞行时长2秒
complete: function() {
// 飞行完成后强制刷新渲染（确保点实体立即显示）
viewer.scene.requestRender();
}
});
参数解析
表格
| 参数 | 类型 | 说明 |
|---|---|---|
pixelSize | Number | 点的屏幕像素大小，不随相机距离变化 |
color | Cesium.Color | 点的填充颜色，支持 RGB、透明度配置 |
scaleByDistance | NearFarScalar | 距离缩放规则，优化远距离视觉效果 |
三、线实体（Polyline）
功能说明
绘制线性要素，如道路、航线、边界等，支持贴地 / 空间两种绘制模式，可自定义线宽、颜色、透明度。
// 1. 定义美国横向线路坐标（西海岸洛杉矶 → 东海岸纽约）
const linePos = Cesium.Cartesian3.fromDegreesArray([
-118.2437, 34.0522, // 起点：加利福尼亚州洛杉矶（Los Angeles）
-74.0060, 40.7128 // 终点：纽约州纽约市（New York）
]);
// 2. 添加横向线实体（保留你原有的贴地/样式配置，适配横向线路）
viewer.entities.add({
id: 'line-la-nyc',
polyline: {
positions: linePos,
width: 8, // 横向线路跨度大，适度加宽确保可见
arcType: Cesium.ArcType.RHUMB, // 等角航线贴地，适配美国本土地形
material: Cesium.Color.BLUE.withAlpha(0.8), // 保留蓝色半透明
clampToGround: true, // 强制贴地
widthScaleByDistance: new Cesium.NearFarScalar(500000, 1, 2000000, 0.5), // 适配横向大跨度的缩放规则
disableDepthTestDistance: Number.POSITIVE_INFINITY, // 始终最上层显示
zIndex: 1000
}
});参数解析
表格
| 参数 | 类型 | 说明 |
|---|---|---|
positions | Cartesian3[] | 线顶点坐标数组，通过 fromDegreesArray 转换 |
arcType | ArcType | 绘制模式：RHUMB（贴地）、NONE（空间） |
clampToGround | Boolean | 是否强制贴地，仅 RHUMB 模 |
四、广告牌实体（Billboard）
功能说明
添加图片标记，如图标、Logo、设备标识等，始终面向相机显示，支持本地 / 网络 / Base64 图片。
// 1. 定义广告牌位置
const billboardPos = Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333, 300);
// 2. 添加广告牌实体
viewer.entities.add({
id: 'billboard',
position: billboardPos,
billboard: {
image:"Assets/Textures/logo.png",
width: 60, // 图片宽度（像素）
height: 60, // 图片高度（像素）
horizontalOrigin: Cesium.HorizontalOrigin.CENTER, // 水平居中
verticalOrigin: Cesium.VerticalOrigin.BOTTOM // 垂直底部对齐
}
});
// 3. 相机定位到广告牌（可选）
viewer.camera.flyTo({
// 高度120万米
destination: Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333, 1200000),
orientation: {
heading: Cesium.Math.toRadians(0), // 朝向正北，横向线路居中显示
pitch: Cesium.Math.toRadians(-50), // 向下50度，兼顾整条横向线路的可见性
roll: 0
},
duration: 4, // 横向跨度大，飞行时长稍延长（4秒）
complete: function() {
viewer.scene.requestRender();
// 聚焦到横向线路实体，确保初始化显示
viewer.trackedEntity = viewer.entities.getById('billboard');
setTimeout(() => {
viewer.trackedEntity = undefined;
}, 500);
}
});参数解析
表格
| 参数 | 类型 | 说明 |
|---|---|---|
image | String | 图片路径（本地路径需放在 public 目录） |
width/height | Number | 图片显示尺寸，单位为像素 |
horizontalOrigin | HorizontalOrigin | 水平对齐方式：LEFT/CENTER/RIGHT |
五、标签实体（Label）
功能说明
添加文字标注，如地名、数值说明等，始终面向相机，支持自定义字体、颜色、描边、偏移量，避免与其他实体重叠。
// 1. 定义广告牌位置
const billboardPos = Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333, 300);
// 2. 添加广告牌实体
viewer.entities.add({
id: 'id',
position: billboardPos,
billboard: {
image:"Assets/Textures/logo.png",
width: 60, // 图片宽度（像素）
height: 60, // 图片高度（像素）
horizontalOrigin: Cesium.HorizontalOrigin.CENTER, // 水平居中
verticalOrigin: Cesium.VerticalOrigin.BOTTOM // 垂直底部对齐
}
});核心参数解析
表格
| 参数 | 类型 | 说明 |
|---|---|---|
text | String | 标注文字内容，支持多行（ 换行） |
font | String | 字体配置（字号 + 字体族），支持 CSS 格式 |
pixelOffset | Cartesian2 | 像素偏移，调整标签位置避免重叠 |
六、椭圆实体（Ellipse）
功能说明
绘制圆形 / 椭圆形区域，如影响范围、搜索半径等，支持贴地显示、自定义旋转角度、填充色和描边。
//1. 定义位置
const ellipsePos = Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333);
// 2. 添加椭圆实体
viewer.entities.add({
id: 'ellipse-guangzhou',
position: ellipsePos,
ellipse: {
semiMinorAxis: 20000, // 短半轴（20公里）
semiMajorAxis: 30000, // 长半轴（30公里）
material: Cesium.Color.GREEN.withAlpha(0.5), // 填充材质
outline: true, // 显示描边
outlineColor: Cesium.Color.BLACK, // 描边色
rotation: Cesium.Math.toRadians(30), // 旋转30°（弧度）
clampToGround: true // 强制贴地
}
});
// 3. 相机定位到广告牌（可选）
viewer.camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333, 50000),
duration: 2
});
参数解析
表格
| 参数 | 类型 | 说明 |
|---|---|---|
semiMinorAxis | Number | 短半轴长度，单位为米 |
semiMajorAxis | Number | 长半轴长度，单位为米（与短半轴相等为圆形） |
rotation | Number | 旋转角度（需转弧度） |
七、锥体实体（Cone）
功能说明
绘制圆锥 / 圆台实体，如雷达覆盖范围、塔状建筑简化模型等，通过调整上下底半径实现不同形状。
//1. 定义位置
const pos = Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333);
// 2. 添加锥体实体
viewer.entities.add({
id: 'cone-guangzhou',
position: pos,
cylinder: {
length: 600, // 锥体高度（600米）
topRadius: 0, // 上底半径（0=圆锥，非0=圆台）
bottomRadius: 300, // 下底半径（300米）
material: Cesium.Color.ORANGE.withAlpha(0.6), // 填充材质
outline: true, // 显示描边
outlineColor: Cesium.Color.WHITE // 描边色
}
});
// 3. 相机定位到广告牌（可选）
viewer.camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333, 5000),
duration: 2
});参数解析
表格
| 参数 | 类型 | 说明 |
|---|---|---|
length | Number | 锥体高度，单位为米 |
topRadius | Number | 上底半径，0 时为圆锥 |
bottomRadius | Number | 下底半径，与上底相等时为圆柱 |
八、球体实体（Sphere）
功能说明
绘制球体 / 椭球体实体，如地球卫星、圆形覆盖区域等，支持自定义半径、材质、描边，可调整分段数提升渲染精度。
//在 onMounted 初始化后添加
//1. 定义位置
const pos = Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333);
// 2. 添加球体实体（Cesium 用 ellipsoid 实现球体）
viewer.entities.add({
id: 'id',
position: pos,
ellipsoid: {
radii: new Cesium.Cartesian3(500, 500, 500), // x/y/z 半径（均为500米=正球体）
material: Cesium.Color.PURPLE.withAlpha(0.6), // 填充材质
outline: true, // 显示描边
outlineColor: Cesium.Color.WHITE, // 描边色
stackPartitions: 32, // 垂直分段数（精度）
slicePartitions: 32 // 水平分段数（精度）
}
});
// 3. 相机定位到广告牌（可选）
viewer.camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333, 5000),
duration: 2
});参数解析
表格
| 参数 | 类型 | 说明 |
|---|---|---|
radii | Cartesian3 | x/y/z 轴半径，三值相等为正球体 |
stackPartitions | Number | 垂直分段数，值越大精度越高 |
slicePartitions | Number | 水平分段数，值越大精度越高 |
九、正方体实体（Box）
功能说明
绘制立方体 / 长方体实体，如建筑、设备模型等，支持自定义长宽高、朝向、材质，可用于三维场景中的实体建模。
//在 onMounted 初始化后添加
//1. 定义位置
const pos = Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333);
viewer.entities.add({
position: pos,
// 正方体朝向（无旋转）
orientation: Cesium.Transforms.headingPitchRollQuaternion(
pos,
new Cesium.HeadingPitchRoll(0, 0, 0)
),
box: {
dimensions: new Cesium.Cartesian3(400, 400, 400), // 长宽高（400米=正方体）
material: Cesium.Color.YELLOW.withAlpha(0.7), // 填充材质
outline: true, // 显示描边
outlineColor: Cesium.Color.BLACK // 描边色
}
});
// 3. 相机定位到广告牌（可选）
viewer.camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333, 5000),
duration: 2
});
参数解析
| 参数层级 | 参数名 | 类型 / 取值示例 | 功能说明 | 默认值 / 注意事项 |
|---|---|---|---|---|
| 根层级 | position | Cesium.Cartesian3 | 正方体的中心点坐标（经纬度转笛卡尔坐标） | 无（必填）；需通过 Cesium.Cartesian3.fromDegrees(经度, 纬度, 高度) 生成 |
| 根层级 | orientation | Cesium.Quaternion | 正方体的朝向（航向 / 俯仰 / 翻滚） | 无（可选）；通常通过 Transforms.headingPitchRollQuaternion 生成朝向四元数 |
orientation 生成参数 | HeadingPitchRoll | new Cesium.HeadingPitchRoll(h, p, r) | 定义朝向的三个角度（弧度）：h：航向（绕 Z 轴旋转）p：俯仰（绕 X 轴旋转）r：翻滚（绕 Y 轴旋转） | 示例 (0,0,0) 表示无旋转；角度需用 Cesium.Math.toRadians(角度值) 转弧度 |
box 核心配置 | dimensions | Cesium.Cartesian3(x, y, z) | 正方体的长宽高（单位：米） | 无（必填）；示例 (400,400,400) 表示长宽高均为 400 米的正立方体 |
box 样式 | material | Cesium.Color/ 材质对象 | 正方体填充材质 / 颜色 | 默认为白色；支持半透明（.withAlpha(0-1)）、渐变 / 图片材质（如 PolylineGlowMaterial） |
box 样式 | outline | Boolean（true/false） | 是否显示正方体的描边（边框） | false（不显示）；开启后需配合 outlineColor 使用 |
box 样式 | outlineColor | Cesium.Color | 描边的颜色 | 默认为黑色；支持 Cesium.Color.RED/fromCssColorString('#ff0000') 等写法 |
box 样式（扩展） | outlineWidth | Number | 描边的宽度（像素） | 1.0；注意：WebGL 限制，部分浏览器下宽度只能为 1 |
box 显示控制（扩展） | show | Boolean（true/false） | 是否显示整个正方体实体 | true（显示）；可动态修改隐藏 / 显示实体 |
box 高度参考（扩展） | heightReference | Cesium.HeightReference | 高度参考模式：NONE（绝对高度）RELATIVE_TO_GROUND（相对地面）CLAMP_TO_GROUND（贴地） | NONE；贴地时正方体底部贴合地形 / 地表 |
box 深度检测（扩展） | disableDepthTestDistance | Number（如 Number.POSITIVE_INFINITY） | 禁用深度检测的距离（超过该距离后正方体始终显示在最上层） | 0.0；设置为 Number.POSITIVE_INFINITY 可强制正方体不被遮挡 |
box 距离缩放（扩展） | scaleByDistance | Cesium.NearFarScalar(近距, 近距缩放, 远距, 远距缩放) | 正 |
十、三维模型实体（GLB/GLTF）
功能说明
加载外部三维模型（支持 GLB/GLTF 格式，推荐 GLB 格式，体积更小、加载更快），适用于建筑建模、设备可视化、车辆 / 人物模型展示等场景，支持自定义缩放、朝向、材质等配置。
// 在 onMounted 初始化后添加
// 1. 定义模型位置（经纬度+高度，北京天安门附近）
const pos = Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333, 10);
// 2. 添加三维模型实体
viewer.entities.add({
id: 'model-truck-beijing', // 实体唯一标识（可选）
position: pos,
// 模型朝向配置（默认朝向正北，可通过 HeadingPitchRoll 调整旋转）
orientation: Cesium.Transforms.headingPitchRollQuaternion(
pos,
new Cesium.HeadingPitchRoll(
Cesium.Math.toRadians(0), // 航向角（0=正北，90=正东，单位：弧度）
0, // 俯仰角（0=水平，单位：弧度）
0 // 翻滚角（0=无倾斜，单位：弧度）
)
),
model: {
uri: 'Assets/SampleData/models/CesiumMilkTruck/CesiumMilkTruck.glb',
scale: 5.0, // 模型缩放倍数（根据模型实际大小调整，默认1.0）
minimumPixelSize: 32, // 最小像素尺寸（保证相机远距离时模型仍可见）
maximumScale: 1000, // 最大缩放倍数（防止模型过度放大）
show: true, // 是否显示模型
// 可选：替换模型材质颜色（覆盖原有材质）
color: Cesium.Color.WHITE.withAlpha(0.9),
// 可选：开启模型阴影（提升真实感）
shadows: Cesium.ShadowMode.ENABLED
}
});
// 3. 相机定位到模型位置（俯角45°，方便查看模型细节）
viewer.camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333, 200),
orientation: {
heading: Cesium.Math.toRadians(0),
pitch: Cesium.Math.toRadians(-45),
roll: 0
},
duration: 2
});核心参数解析
表格
| 参数 | 类型 | 说明 |
|---|---|---|
uri | String | 模型文件路径（本地文件需放在 public 目录，路径无需加 public 前缀） |
scale | Number | 模型缩放倍数，根据模型原始大小调整（如小型设备模型用 0.1~1，大型建筑用 10~100） |
minimumPixelSize | Number | 最小像素尺寸，防止模型因相机距离过远而消失 |
orientation | Quaternion | 模型朝向，通过 HeadingPitchRoll 转换为四元数，控制模型旋转 |
color | Cesium.Color | 模型整体颜色（可选），支持透明度配置，会覆盖原有材质颜色 |
shadows | ShadowMode | 阴影模式（ENABLED = 开启阴影，DISABLED = 关闭），提升场景真实感 |
关键使用注意事项
- 模型路径配置：
- 本地模型需放在项目
public目录下，代码中路径写为Assets/SampleData/models/CesiumMilkTruck/CesiumMilkTruck.glb（无需加public）； - 支持网络模型路径（如
https://xxx.com/models/car.glb），需确保跨域可访问； - 推荐使用 GLB 格式（单个文件包含模型、材质、纹理），GLTF 格式需确保材质、纹理文件路径正确。
- 本地模型需放在项目
- 缩放倍数调整：
- 不同模型的原始大小差异较大，需通过
scale参数适配场景（如示例中卡车模型缩放 5 倍后适配地球尺度）； - 若模型显示过大 / 过小，可逐步调整
scale值（如 0.5、1、3、10），直到视觉协调。
- 不同模型的原始大小差异较大，需通过
- 模型加载失败排查：
- 检查
uri路径是否正确（控制台无 404 错误）； - 确认模型格式是否为 GLB/GLTF（其他格式如 FBX 需先转换）；
- 若模型体积过大（超过 10MB），建议压缩（使用 glTF Transform 等工具），避免加载卡顿。
- 检查
- 材质与阴影：
- 若需保留模型原有材质，删除
color参数； - 开启阴影（
shadows: Cesium.ShadowMode.ENABLED）需确保场景光照开启（Cesium 默认开启），提升模型立体感。
- 若需保留模型原有材质，删除
