Vue3 + Cesium 三维实体材质开发入门教程

一、前言

1.1 本教程目标

本教程旨在帮助掌握 Vue3 + Cesium 实体材质系统核心用法，涵盖五种核心材质类型：颜色、图像、棋盘格、条纹、网格材质。每种材质都配有详细参数解析和完整代码示例，快速上手为三维实体添加丰富的视觉效果。

1.2 基础知识要求

• Vue3基础：了解组合式API、组件生命周期

• Cesium基础：熟悉实体创建、坐标系统

• JavaScript基础：ES6+语法、异步编程

二、项目基础准备

2.1 基础项目结构

vue

<!– App.vue –>
<template>
<div id="cesiumContainer" style="width: 100vw; height: 100vh;"></div>
</template>

<script setup>
import * as Cesium from 'cesium'
import "cesium/Build/Cesium/Widgets/widgets.css"
import { onMounted, onUnmounted } from 'vue'

let viewer = null;

onMounted(() => {
// 1. 配置 Ion Token
Cesium.Ion.defaultAccessToken = '你的Cesium Ion Token';

// 2. 初始化 Viewer
viewer = new Cesium.Viewer('cesiumContainer', {
animation: false, baseLayerPicker: false, fullscreenButton: false,
geocoder: false, homeButton: false, infoBox: false,
sceneModePicker: false, selectionIndicator: false, timeline: false,
navigationHelpButton: false
});

// 隐藏默认水印
viewer.cesiumWidget.creditContainer.style.display = 'none';

// ========== 以下开始材质代码示例 ==========
});

onUnmounted(() => {
if (viewer) {
viewer.destroy();
viewer = null;
}
});
</script>

三、颜色材质（Color）

3.1 功能说明

颜色材质是 最简单直接 的材质类型，用于实体纯色填充，支持透明度、RGB/HSL多种颜色格式，适用于快速原型开发和基础可视化需求。

3.2 完整代码示例

javascript

// 1. 定义立方体位置（美国堪萨斯州）
const colorCubePos = Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333, 500);

// 2. 添加带颜色材质的立方体实体
viewer.entities.add({
id: 'color-cube-demo',
position: colorCubePos,
name: '颜色材质立方体',

box: {
dimensions: new Cesium.Cartesian3(300000, 200000, 150000), // 长宽高(米)
material: Cesium.Color.RED.withAlpha(0.7), // 核心：红色70%透明
outline: true, // 显示边框
outlineColor: Cesium.Color.WHITE,
outlineWidth: 2
}
});

// 3. 相机定位到实体
viewer.camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(-98.5855, 39.8333, 1500000),
duration: 2
});

3.3 参数解析

四、图像材质（Image）

4.1 功能说明

图像材质允许将 外部图片 作为纹理贴在实体表面，支持平铺重复、旋转、透明度等高级控制，适用于创建逼真的建筑表面、地形纹理等效果。

4.2 完整代码示例

javascript

// 在 viewer 初始化后添加
// 1. 定义立方体位置（美国德克萨斯州）
const imageCubePos = Cesium.Cartesian3.fromDegrees(-97.7431, 30.2672, 500);

// 2. 创建图像材质
const imageMaterial = new Cesium.ImageMaterialProperty({
image: 'Assets/Textures/logo.png', // 图片URL
repeat: new Cesium.Cartesian2(4, 2), // 水平和垂直重复次数
color: Cesium.Color.WHITE.withAlpha(0.9), // 颜色叠加
transparent: true, // 启用透明度
colorToAlpha: 0.1, // 颜色转透明度阈值
colorToAlphaEdge: 0.5, // 边缘平滑度
rotation: 0, // 旋转角度(弧度)
offset: new Cesium.Cartesian2(0, 0) // UV偏移
});

// 3. 添加带图像材质的立方体实体
viewer.entities.add({
id: 'image-cube-demo',
position: imageCubePos,
name: '图像材质立方体',

box: {
dimensions: new Cesium.Cartesian3(400000, 300000, 200000),
material: imageMaterial, // 核心：图像材质
outline: true,
outlineColor: Cesium.Color.BLACK,
outlineWidth: 1
}
});

// 4. 相机定位
viewer.camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(-97.7431, 30.2672, 1800000),
duration: 2.5
});

4.3 参数解析

五、棋盘格材质（Checkerboard）

5.1 功能说明

棋盘格材质创建 交替颜色 的棋盘图案，常用于调试、测试网格对齐，或创建特殊的视觉效果，如棋盘地面、网格化表面等。

5.2 实例代码

// 1. 定义立方体位置（美国科罗拉多州）
const checkerboardPos = Cesium.Cartesian3.fromDegrees(-105.7821, 39.5501, 500);

// 2. 创建棋盘格材质
const checkerboardMaterial = new Cesium.CheckerboardMaterialProperty({
evenColor: Cesium.Color.WHITE, // 偶数格颜色
oddColor: Cesium.Color.BLACK, // 奇数格颜色
repeat: new Cesium.Cartesian2(10, 10), // 棋盘格密度
colorToAlpha: 0.0, // 颜色转透明度
colorToAlphaEdge: 0.0, // 边缘平滑
transparent: false, // 是否透明
offset: new Cesium.Cartesian2(0, 0), // UV偏移
rotation: 0, // 旋转角度
scale: 1.0 // 整体缩放
});

// 3. 添加带棋盘格材质的立方体实体
viewer.entities.add({
id: 'checkerboard-cube-demo',
position: checkerboardPos,
name: '棋盘格材质立方体',

box: {
dimensions: new Cesium.Cartesian3(350000, 350000, 350000),
material: checkerboardMaterial, // 核心：棋盘格材质
outline: true,
outlineColor: Cesium.Color.YELLOW,
outlineWidth: 2
}
});

// 4. 相机定位
viewer.camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(-105.7821, 39.5501, 2000000),
duration: 3
});

javascript

5.3 参数解析

六、条纹材质（Stripe）

6.1 功能说明

条纹材质创建 交替颜色条纹 图案，支持水平和垂直方向，常用于创建警示标识、方向指引、特殊标记等效果。

6.2 代码示例

javascript

// 1. 定义立方体位置（美国内华达州）
const stripePos = Cesium.Cartesian3.fromDegrees(-119.7661, 36.7378, 500);

// 2. 创建条纹材质
const stripeMaterial = new Cesium.StripeMaterialProperty({
evenColor: Cesium.Color.RED, // 偶数条纹颜色
oddColor: Cesium.Color.YELLOW, // 奇数条纹颜色
repeat: 16, // 条纹数量
orientation: Cesium.StripeOrientation.HORIZONTAL, // 条纹方向
offset: 0, // 条纹偏移(0-1)
colorToAlpha: 0.0, // 颜色转透明度
colorToAlphaEdge: 0.0, // 边缘平滑
transparent: false, // 是否透明
rotation: 0, // 旋转角度
scale: 1.0 // 整体缩放
});

// 3. 添加带条纹材质的立方体实体
viewer.entities.add({
id: 'stripe-cube-demo',
position: stripePos,
name: '条纹材质立方体' ,
box: {
dimensions: new Cesium.Cartesian3(320000, 320000, 320000),
material: stripeMaterial, // 核心：条纹材质
outline: true,
outlineColor: Cesium.Color.WHITE,
outlineWidth: 1
}
});

// 4. 相机定位
viewer.camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(-119.7661, 36.7378, 1800000),
duration: 2.5
});

6.3 参数解析

七、网格材质（Grid）

7.1 功能说明

网格材质创建 坐标网格 图案，支持自定义网格数量、线粗细、透明度，常用于创建测量网格、坐标参考、科学可视化等场景。

7.2 完整代码示例

javascript

// 1. 定义立方体位置（美国犹他州）
const gridPos = Cesium.Cartesian3.fromDegrees(-111.6585, 39.3210, 500);

// 2. 创建网格材质
const gridMaterial = new Cesium.GridMaterialProperty({
color: Cesium.Color.CYAN, // 网格线颜色
cellAlpha: 0.2, // 单元格透明度
lineCount: new Cesium.Cartesian2(8, 8), // 网格数量
lineThickness: new Cesium.Cartesian2(1.0, 1.0),// 线粗细
lineOffset: new Cesium.Cartesian2(0.0, 0.0), // 线偏移
repeat: new Cesium.Cartesian2(1, 1), // 重复次数
transparent: true, // 是否透明
colorToAlpha: 0.0, // 颜色转透明度
colorToAlphaEdge: 0.0 // 边缘平滑
});

// 3. 添加带网格材质的立方体实体
viewer.entities.add({
id: 'grid-cube-demo',
position: gridPos,
name: '网格材质立方体',

box: {
dimensions: new Cesium.Cartesian3(380000, 380000, 380000),
material: gridMaterial, // 核心：网格材质
outline: true,
outlineColor: Cesium.Color.WHITE,
outlineWidth: 2
}
});

// 4. 相机定位
viewer.camera.flyTo({
destination: Cesium.Cartesian3.fromDegrees(-111.6585, 39.3210, 2200000),
duration: 3
});

7.3 参数解析

7.4 网格材质变体

javascript

// 创建不同风格的网格材质
const gridVariants = [
{
name: '细网格',
material: new Cesium.GridMaterialProperty({
color: Cesium.Color.WHITE,
cellAlpha: 0.1,
lineCount: new Cesium.Cartesian2(20, 20),
lineThickness: new Cesium.Cartesian2(0.5, 0.5)
})
},
{
name: '粗网格',
material: new Cesium.GridMaterialProperty({
color: Cesium.Color.YELLOW,
cellAlpha: 0.3,
lineCount: new Cesium.Cartesian2(5, 5),
lineThickness: new Cesium.Cartesian2(2.0, 2.0)
})
},
{
name: '非对称网格',
material: new Cesium.GridMaterialProperty({
color: Cesium.Color.MAGENTA,
cellAlpha: 0.15,
lineCount: new Cesium.Cartesian2(12, 6), // 水平12格，垂直6格
lineThickness: new Cesium.Cartesian2(1.0, 3.0) // 垂直线粗
})
},
{
name: '虚线网格',
material: new Cesium.GridMaterialProperty({
color: Cesium.Color.GREEN,
cellAlpha: 0.25,
lineCount: new Cesium.Cartesian2(8, 8),
lineThickness: new Cesium.Cartesian2(1.0, 1.0),
lineOffset: new Cesium.Cartesian2(0.0, 0.5) // 垂直线偏移50%
})
}
];

// 展示网格变体
gridVariants.forEach((variant, index) => {
const longitude = -111.6585 + (index – 1.5) * 0.7;

viewer.entities.add({
position: Cesium.Cartesian3.fromDegrees(longitude, 39.3210, 500),
name: `网格变体-${variant.name}`,
box: {
dimensions: new Cesium.Cartesian3(150000, 150000, 150000),
material: variant.material,
outline: true,
outlineColor: Cesium.Color.BLACK
}
});
});

八、学习建议